Agentic

一个实验性的 AI Agent IDE — 探索 LLM 自主编程的上下文管理与工具设计。

An experimental AI Agent IDE — exploring context management and tool design for autonomous LLM-driven programming.

---

概述 | Overview

Agentic 是一个类 VS Code 的轻量级 IDE，内置了完整的 AI Agent 系统。它不仅仅是一个"聊天+编辑器"的拼接，而是对 Agent 上下文管理、记忆压缩、工具调用设计进行了深度实验的平台。

Agentic is a lightweight VS Code-like IDE with a fully integrated AI Agent system. Rather than a simple "chat + editor" mashup, it serves as a platform for deep experimentation with agent context management, memory compression, and tool call design.

核心设计理念 | Core Design Principles

• 三段式上下文架构 | 3-Part Context Architecture — 静态前缀缓存区 → 消息历史区 → 临时尾部区，最大化 LLM API 的前缀缓存命中率
• Agent 驱动的意图压缩 | Intent-Driven Compression — Agent 自主决定何时、如何压缩历史，生成面向下一任务的定向摘要，而非盲目压缩
• 自由形式笔记本 | Free-Form Notebook — 替代僵化的任务列表/记忆系统，Agent 用 Markdown 笔记自行组织工作
• 文件内容在历史中 | File Content in History — 文件内容通过 file_read 结果进入对话历史，而非固定在 system prompt 中

技术栈 | Tech Stack

层级 Layer	技术 Technology
框架 Framework	SvelteKit (SPA Mode) + Svelte 5 ($state runes)
样式 Styling	Tailwind CSS v4
桌面运行时 Desktop	NW.js (可选 optional)
语言 Language	TypeScript

项目结构 | Project Structure

src/lib/
├── agent/                  # Agent 核心引擎 | Agent core engine
│   ├── context.ts          #   三段式 prompt 构建 | 3-part prompt builder
│   ├── session.ts          #   会话管理与主循环 | Session manager & main loop
│   ├── parser.ts           #   XML 工具调用解析 | XML tool call parser
│   ├── tools.ts            #   工具执行器 | Tool executor
│   ├── types.ts            #   类型定义 | Type definitions
│   ├── archive.ts          #   压缩存档工具 | Compression archive utilities
│   └── llm.ts              #   OpenAI 兼容 LLM 提供者 | OpenAI-compatible LLM provider
│
├── services/               # 业务服务层 | Business service layer
│   ├── agent.ts            #   Agent 服务（桥接引擎↔UI）| Agent service (engine↔UI bridge)
│   ├── editor.ts           #   编辑器服务 | Editor service
│   ├── fs.ts               #   文件系统抽象（Node / Web）| FS abstraction (Node / Web)
│   └── project.ts          #   项目管理 | Project management
│
├── stores/                 # 响应式状态（Svelte 5 Runes）| Reactive state (Svelte 5 Runes)
│   ├── agent.svelte.ts     #   Agent UI 状态 | Agent UI state
│   ├── editor.svelte.ts    #   编辑器状态 | Editor state
│   ├── diff.svelte.ts      #   文件变更记录 | File change records
│   ├── layout.svelte.ts    #   布局状态 | Layout state
│   ├── project.svelte.ts   #   项目状态 | Project state
│   └── theme.svelte.ts     #   主题状态 | Theme state
│
├── components/
│   ├── base/               # 基础 UI 组件 | Base UI components
│   ├── layout/             # 布局组件 | Layout components
│   ├── complex/            # 复合组件（TreeView, Monaco）| Complex components
│   ├── modules/            # 业务模块 | Business modules
│   │   ├── AgentBar.svelte #   Agent 时间线面板 | Agent timeline panel
│   │   ├── SideBar.svelte  #   侧边栏（Explorer, Agent Context, Settings）
│   │   ├── EditorArea.svelte
│   │   ├── ActivityBar.svelte
│   │   └── MenuBar.svelte
│   └── settings/           # 配置 UI | Settings UI
│
├── config/                 # 多层配置系统 | Multi-layer config system
└── fs-viewer.svelte.ts     # 目录树视图状态 | Directory tree view state

Agent 系统 | Agent System

上下文架构 | Context Architecture

┌──────────────────────────────────────────────────────────┐
│ PART 1: 静态前缀缓存区 PREFIX CACHE ZONE                 │
│ ─ 角色、响应格式、工具参考、规则                            │
├──────────────────────────────────────────────────────────┤
│ PART 2: 消息历史区 MESSAGE HISTORY ZONE                   │
│ ─ [可选] 压缩存档（详细摘要 + 文件快照）                    │
│ ─ 未压缩的对话历史（assistant 工具调用 ↔ user 工具结果）     │
├──────────────────────────────────────────────────────────┤
│ PART 3: 临时尾部区 EPHEMERAL TRAILING ZONE               │
│ ─ 项目上下文                                              │
│ ─ 目录树视图                                              │
│ ─ Agent 笔记本（Markdown 自由记录）                        │
│ ─ 动态提示（任务完成建议、压缩机会等）                       │
└──────────────────────────────────────────────────────────┘

工具集 | Tool Set (9 tools)

工具 Tool	用途 Purpose
update_notebook	自由形式 Markdown 笔记 — 替代任务列表和记忆系统
dir_open	展开目录到持久目录视图
dir_list	一次性列出目录内容
file_read	读取文件（结果含行号）
file_write	完整写入文件
file_patch	搜索/替换编辑（支持 start_line 偏移、完成后输出完整内容）
mark_task_end	在历史中放置任务里程碑标记
compress_history	压缩旧历史为摘要（双摘要：LLM 详细 + 用户简要）
report_to_user	停止执行，向用户报告/征询（支持超时自动继续）

压缩策略 | Compression Strategy

Agent 完成任务
    ↓
mark_task_end（放置里程碑标记）
    ↓
Agent 更新笔记本（开始规划新工作）
    ↓
下一回合提示：已检测到新任务开始，建议压缩旧历史
    ↓
Agent 自主决定是否压缩
    ├── 压缩 → 生成双摘要，清除旧历史，保留文件快照
    └── 跳过 → 下次更新笔记本时再提醒，直到压缩

压缩由 Agent 主动驱动，摘要面向下一任务的需求定向生成，而非在任务完成时盲目压缩。这确保了摘要的相关性和信息密度。

Compression is agent-driven. The summary is generated with awareness of the upcoming task's needs, rather than blindly at task completion. This ensures relevance and information density.

开发 | Development

前置要求 | Prerequisites

• Node.js 18+ 或 Bun
• NW.js (可选，用于桌面模式 | optional, for desktop mode)

安装 | Install

# 安装依赖 | Install dependencies
npm install
# 或 | or
bun install

开发服务器 | Dev Server

# 启动开发服务器 | Start dev server
npm run dev

# 桌面模式（NW.js）| Desktop mode (NW.js)
npm run dev:nw

构建 | Build

# 构建静态产物 | Build static assets
npm run build

# 预览构建 | Preview build
npm run preview

类型检查 | Type Checking

# TypeScript + Svelte 检查 | TypeScript + Svelte check
npm run check

配置 | Configuration

通过内置的 Settings 面板进行配置（侧边栏 → ⚙️ Settings），支持多层配置（默认/项目级/用户级）。

Configuration is done via the built-in Settings panel (Sidebar → ⚙️ Settings), with multi-layer support (default / project / user).

配置项 Config	说明 Description
llm.apiKey	LLM API Key（兼容 OpenRouter / OpenAI）
llm.baseUrl	API Base URL（默认 OpenRouter）
llm.model	模型名称
llm.temperature	温度参数
llm.maxTokens	最大生成 token 数
agent.autoContinueLimit	自动继续的最大轮数
agent.maxEntriesPerDir	目录视图每个目录最大条目数
agent.userPromptTimeoutMs	report_to_user 后自动继续的超时（0 = 永久等待）

设计文档 | Design Documents

文档 Document	内容 Content
docs/Context Design.md	上下文架构设计详解
docs/DESIGN.md	系统整体设计说明
docs/Architecture.md	架构分层与重构方案
docs/Config System Design.md	多层配置系统设计

许可 | License

Private — 仅供学习与实验用途。

Private — For learning and experimentation purposes only.