AgenticX system prompt

--- name: Agent Loop Context Persistence overview: 补齐 AgenticX agent loop 的上下文持久化能力：TodoWrite 结构化规划、Scratchpad 中间结果暂存、Memory 写入工具、SQLite 跨会话持久化、向量 embedding + FTS 语义记忆检索，完整对标 Claude Agent Loop v2/v3 并融合 OpenClaw 的三层记忆架构。 todos: - id: p0-todo-manager content: "Phase 0: 新建 todo_manager.py + todo_write 工具 + system prompt 注入 + nag reminder" status: completed - id: p0-todo-tests content: "Phase 0: 新建 test_todo_manager.py, 验证约束（max 20, 单个 in_progress, 渲染格式）" status: completed - id: p1-scratchpad content: "Phase 1a: 新建 scratchpad.py + scratchpad_write/read 工具 + system prompt 注入 + subagent 继承" status: completed - id: p1-memory-write content: "Phase 1b: memory_append 工具 + loader.py 公开写入 API + daily/long_term 两种模式" status: completed - id: p1-tests content: "Phase 1: 新建 test_scratchpad.py, 补充 memory_append 集成测试" status: completed - id: p2-session-store content: "Phase 2: 新建 session_store.py（SQLite 3 表）+ session_manager 集成 + 会话结束自动持久化" status: completed - id: p2-tests content: "Phase 2: 新建 test_session_store.py, 验证跨会话恢复" status: completed - id: p3-workspace-memory content: "Phase 3: 新建 workspace_memory.py（chunks + FTS5 + embedding）+ memory_search 工具" status: completed - id: p3-indexing content: "Phase 3: loader.py 增量索引 + memory_append 写后自动索引" status: completed - id: p3-tests content: "Phase 3: 新建 test_workspace_memory.py, 验证 FTS + 语义搜索 + 增量索引" status: completed isProject: false --- # Agent Loop 上下文持久化完整方案 ## 现状诊断 当前 AgenticX agent loop 在三个核心点的支持情况： - **上下文持久化**：仅有 `session.artifacts` / `session.context_files` 隐式传递，缺少 TodoWrite 和 Scratchpad - **程序化工具调用**：已对标 Claude v1（`tool_choice="auto"` + JSON function calling），合格 - **递归调度**：已超越 Claude v3（并行 subagent + 资源监控 + 生命周期管理），合格 **核心差距**：缺少 Claude v2 的 TodoWrite + 缺少 Memory 写入工具 + 缺少 SQLite 持久化层 + 缺少语义记忆检索 ## 架构全景 ```mermaid graph TB subgraph RuntimeTools [Runtime Layer - In-Session] TodoWrite[todo_write Tool] ScratchpadW[scratchpad_write Tool] ScratchpadR[scratchpad_read Tool] MemoryAppend[memory_append Tool] MemorySearch[memory_search Tool] end subgraph SessionState [StudioSession State] TodoMgr[TodoManager] Scratchpad[Scratchpad Dict] Artifacts[artifacts Dict] ContextFiles[context_files Dict] end subgraph Persistence [SQLite Persistence Layer] SessionDB["session_memory.sqlite"] TodoTable[todos Table] ScratchTable[scratchpad Table] SummaryTable[session_summaries Table] end subgraph VectorMemory [Vector Memory Layer] ChunksTable[chunks Table + embedding] FTSIndex[chunks_fts FTS5 Index] EmbeddingService[Embedding Service] end subgraph WorkspaceFiles [Workspace Markdown Files] MemoryMD[MEMORY.md] DailyMD["memory/YYYY-MM-DD.md"] IdentityMD[IDENTITY.md / USER.md / SOUL.md] end TodoWrite --> TodoMgr ScratchpadW --> Scratchpad ScratchpadR --> Scratchpad MemoryAppend --> DailyMD MemoryAppend --> MemoryMD MemorySearch --> FTSIndex MemorySearch --> ChunksTable TodoMgr -->|"session end"| TodoTable Scratchpad -->|"session end"| ScratchTable DailyMD -->|"indexing"| EmbeddingService MemoryMD -->|"indexing"| EmbeddingService EmbeddingService --> ChunksTable EmbeddingService --> FTSIndex ``` ## Phase 0: TodoWrite 工具（对标 Claude v2） **目标**：让模型的"计划"外化为可见、可追踪的状态机 ### 新建 `agenticx/runtime/todo_manager.py` ```python class TodoManager: items: List[TodoItem] # max 20 items # TodoItem: {content: str, status: str, active_form: str} # status: "pending" | "in_progress" | "completed" # active_form: 现在进行时描述，如 "正在分析认证模块..." def update(self, items: list) -> str: # 验证 + 渲染 def render(self) -> str: # 文本渲染给模型看 ``` **设计决策**：新建轻量 TodoManager 而非复用 `plan_storage.py` 的 SubTask/Plan，原因： - `SubTask` 要求 `expected_outcome` 等字段，对 agent loop 内的快速规划过重 - Claude v2 的 TodoManager 刻意极简（content + status + activeForm），约束即能力 - `plan_storage` 面向长期项目规划，TodoManager 面向单次对话内的任务追踪 - 后续 Phase 2 会增加 SQLite 持久化桥接 ### 修改 `agenticx/cli/agent_tools.py` - 在 `STUDIO_TOOLS` 中新增 `todo_write` 工具定义 - 在 `dispatch_tool_async` 中新增 `todo_write` 分发逻辑 ### 修改 `agenticx/cli/studio.py` - `StudioSession` 新增 `todo_manager: TodoManager` 字段 ### 修改 `agenticx/runtime/agent_runtime.py` - `_build_agent_system_prompt()` 注入当前 todo 列表状态 - 增加 nag reminder 机制：连续 N 轮未更新 todo 时注入 `<reminder>` 到 user message ### 修改 `agenticx/runtime/prompts/meta_agent.py` - `build_meta_agent_system_prompt()` 注入 todo 状态 - 调度策略中增加 "拆解子任务前先用 `todo_write` 记录计划" 的指导 ## Phase 1: Scratchpad + Memory 写入工具 ### 1a. Scratchpad（会话内中间结果暂存） **新建 `agenticx/runtime/scratchpad.py`** ```python class Scratchpad: _store: Dict[str, str] # key -> value, max 50 keys, max 10KB per value def write(self, key: str, value: str) -> str def read(self, key: str) -> str def list_keys(self) -> List[str] def render_summary(self) -> str # 给 system prompt 用的摘要 ``` **修改 `agenticx/cli/agent_tools.py`** - 新增 `scratchpad_write` 工具：写入 key-value - 新增 `scratchpad_read` 工具：读取指定 key 或 list keys **修改 `agenticx/cli/studio.py`** - `StudioSession` 新增 `scratchpad: Scratchpad` 字段 **修改 `agenticx/runtime/agent_runtime.py`** - System prompt 注入 scratchpad 摘要（key 列表 + 每个 value 的前 200 字符预览） **修改 `agenticx/runtime/team_manager.py`** - `_build_isolated_session()` 时将 parent session 的 scratchpad 复制一份给 subagent（只读快照） ### 1b. Memory 写入工具 **修改 `agenticx/workspace/loader.py`** - 将 `_append_daily_memory_note()` 改为 public `append_daily_memory(workspace_dir, note)` - 新增 `append_long_term_memory(workspace_dir, note)` — 追加到 MEMORY.md **修改 `agenticx/cli/agent_tools.py`** - 新增 `memory_append` 工具： - 参数：`target` ("daily" | "long_term")，`content` (str) - daily: 追加到 `memory/YYYY-MM-DD.md` - long_term: 追加到 `MEMORY.md`（需要 confirm） ## Phase 2: SQLite 持久化层 **目标**：跨会话恢复 todo/scratchpad/session summary，类似 OpenClaw 的 `main.sqlite` ### 新建 `agenticx/memory/session_store.py` ```python class SessionStore: """SQLite persistence for session state across conversations.""" def __init__(self, db_path: Path): # 默认 ~/.agenticx/memory/sessions.sqlite # Todo 持久化 async def save_todos(self, session_id: str, items: list) -> None async def load_todos(self, session_id: str) -> list # Scratchpad 持久化 async def save_scratchpad(self, session_id: str, data: dict) -> None async def load_scratchpad(self, session_id: str) -> dict # Session summary 持久化（会话结束时自动摘要） async def save_session_summary(self, session_id: str, summary: str, metadata: dict) -> None async def search_session_summaries(self, query: str, limit: int = 5) -> list ``` **Schema 设计（3 张表）** ```sql CREATE TABLE todos ( session_id TEXT NOT NULL, data TEXT NOT NULL, -- JSON array of todo items updated_at TEXT NOT NULL, PRIMARY KEY (session_id) ); CREATE TABLE scratchpad ( session_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (session_id, key) ); CREATE TABLE session_summaries ( id TEXT PRIMARY KEY, session_id TEXT NOT NULL, summary TEXT NOT NULL, metadata TEXT, -- JSON: provider, model, duration, tool_count created_at TEXT NOT NULL ); ``` ### 修改 `agenticx/studio/session_manager.py` - `ManagedSession` 创建时加载 SQLite 中的 todo/scratchpad - Session 销毁时自动保存 todo/scratchpad + 生成 session summary ### 修改 `agenticx/workspace/loader.py` - `ensure_workspace()` 中初始化 `~/.agenticx/memory/` 目录和 SQLite 文件 ## Phase 3: 向量 Embedding + FTS 语义记忆检索 **目标**：对标 OpenClaw 的 `main.sqlite`（chunks + FTS5 + embedding_cache），让 agent 能语义检索历史记忆 ### 新建 `agenticx/memory/workspace_memory.py` ```python class WorkspaceMemoryStore: """SQLite + FTS5 + Embedding for workspace markdown memory files.""" def __init__(self, db_path: Path, embedding_provider: str = "default"): # 默认 ~/.agenticx/memory/main.sqlite async def index_file(self, file_path: Path) -> int: # 读取 markdown -> 分块 -> embedding -> 存入 chunks + FTS async def index_workspace(self, workspace_dir: Path) -> dict: # 索引 MEMORY.md + memory/*.md + IDENTITY.md + USER.md async def search(self, query: str, limit: int = 5, mode: str = "hybrid") -> list: # mode: "fts" (纯全文) | "semantic" (纯向量) | "hybrid" (混合) async def get_recent_memories(self, days: int = 7, limit: int = 10) -> list: # 按时间获取最近记忆 ``` **Schema 设计（对标 OpenClaw）** ```sql CREATE TABLE files ( path TEXT PRIMARY KEY, hash TEXT NOT NULL, mtime REAL NOT NULL, size INTEGER NOT NULL ); CREATE TABLE chunks ( id TEXT PRIMARY KEY, path TEXT NOT NULL, source TEXT, start_line INTEGER, end_line INTEGER, model TEXT, text TEXT NOT NULL, embedding BLOB, created_at TEXT NOT NULL ); CREATE VIRTUAL TABLE chunks_fts USING fts5(text, content=chunks, content_rowid=rowid); CREATE TABLE embedding_cache ( provider TEXT NOT NULL, model TEXT NOT NULL, hash TEXT NOT NULL, embedding BLOB NOT NULL, PRIMARY KEY (provider, model, hash) ); ``` ### Embedding 服务 复用 `agenticx/integrations/mem0/embeddings/` 已有的 embedding provider（OpenAI/Ollama/HuggingFace 等），通过 `ProviderResolver` 或配置文件选择。 ### 修改 `agenticx/cli/agent_tools.py` - 新增 `memory_search` 工具： - 参数：`query` (str)，`mode` ("fts" | "semantic" | "hybrid")，`limit` (int) - 返回匹配的记忆片段 + 来源文件 + 相关度 ### 修改 `agenticx/runtime/meta_tools.py` - Meta-Agent 工具列表新增 `memory_search` ### 索引触发时机 - `ensure_workspace()` 时检查文件 hash，增量索引变更的 markdown 文件 - `memory_append` 写入后自动增量索引新内容 - 可选：配置定时全量重索引 ### 修改 `agenticx/workspace/loader.py` - `ensure_workspace()` 新增可选的 `index_memory=True` 参数 - 调用 `WorkspaceMemoryStore.index_workspace()` 进行增量索引 ## 关键文件清单 | 操作 | 文件 | Phase | | --- | -------------------------------------------------------------------------------- | ----- | | 新建 | `agenticx/runtime/todo_manager.py` | P0 | | 新建 | `agenticx/runtime/scratchpad.py` | P1 | | 新建 | `agenticx/memory/session_store.py` | P2 | | 新建 | `agenticx/memory/workspace_memory.py` | P3 | | 新建 | `tests/test_todo_manager.py` | P0 | | 新建 | `tests/test_scratchpad.py` | P1 | | 新建 | `tests/test_session_store.py` | P2 | | 新建 | `tests/test_workspace_memory.py` | P3 | | 修改 | [agenticx/cli/agent_tools.py](agenticx/cli/agent_tools.py) | P0-P3 | | 修改 | [agenticx/cli/studio.py](agenticx/cli/studio.py) | P0-P1 | | 修改 | [agenticx/runtime/agent_runtime.py](agenticx/runtime/agent_runtime.py) | P0-P1 | | 修改 | [agenticx/runtime/prompts/meta_agent.py](agenticx/runtime/prompts/meta_agent.py) | P0 | | 修改 | [agenticx/runtime/team_manager.py](agenticx/runtime/team_manager.py) | P1 | | 修改 | [agenticx/runtime/meta_tools.py](agenticx/runtime/meta_tools.py) | P3 | | 修改 | [agenticx/workspace/loader.py](agenticx/workspace/loader.py) | P1-P3 | | 修改 | [agenticx/studio/session_manager.py](agenticx/studio/session_manager.py) | P2 | ## 与 OpenClaw 三层记忆架构的对齐 | OpenClaw 层 | AgenticX 对应 | Phase | | ----------------------------- | ----------------------------------- | ----- | | `MEMORY.md` 长期精选 | `memory_append(target="long_term")` | P1 | | `memory/YYYY-MM-DD.md` 每日日志 | `memory_append(target="daily")` | P1 | | `sessions/` 会话历史 | `session_summaries` in SQLite | P2 | | `main.sqlite` chunks + FTS5 | `WorkspaceMemoryStore` | P3 | | `main.sqlite` embedding_cache | 复用 mem0 embeddings | P3 | ## 约束与风险 - **Phase 0-1 无新依赖**：纯 Python 标准库 + 已有 agenticx 基础 - **Phase 2 依赖 `aiosqlite`**：已在 `plan_storage.py` 中使用，非新增 - **Phase 3 依赖 embedding provider**：需要用户配置 API key 或本地模型；FTS5 不依赖 embedding，可独立使用 - **向后兼容**：所有新工具为 opt-in，不影响现有 STUDIO_TOOLS 和 META_AGENT_TOOLS 的行为

--- name: Agent Runtime Unification overview: 将 Agent Loop 从 CLI studio.py 中抽象为独立的 AgentRuntime 内核，输出标准化事件流，同时服务 CLI 终端和桌面端（FastAPI + Electron）。 todos: [] isProject: true phases: - name: "Phase 0: Agent Loop 收口（p2-streaming + commit）" todos: - id: p0-streaming content: agent_loop.py 纯文本分支改为流式输出：无 tool_calls 时使用 llm.stream() 逐 token 打印，保持 tool_call 分支不变（仍用 invoke）；更新 test_agent_loop.py 验证流式路径 status: pending - id: p0-commit content: "按功能点分组提交 Agent Loop 改造的全部变更，每个 commit 带 Plan-Id: studio_agent_loop_改造_428be5da / Plan-File / Made-with: Damon Li" status: pending - name: "Phase 1: AgentRuntime 内核抽象" todos: - id: p1-events content: "新建 agenticx/runtime/events.py：定义 RuntimeEvent dataclass（type: str, data: dict）和 EventType 枚举（ROUND_START / TOOL_CALL / TOOL_RESULT / CONFIRM_REQUIRED / CONFIRM_RESPONSE / TOKEN / FINAL / ERROR）" status: pending - id: p1-confirm-gate content: 新建 agenticx/runtime/confirm.py：定义 ConfirmGate 抽象基类（async def request_confirm(question, context) -> bool）+ SyncConfirmGate（CLI 用 input()）+ AsyncConfirmGate（桌面端用 asyncio.Event 等待 HTTP 回复） status: pending - id: p1-runtime-core content: 新建 agenticx/runtime/agent_runtime.py：AgentRuntime 类，核心方法 async def run_turn(user_input, session) -> AsyncGenerator[RuntimeEvent]；内部复用 STUDIO_TOOLS + dispatch_tool + _build_agent_system_prompt；确认操作走 ConfirmGate；token 输出走 RuntimeEvent(TOKEN)；最大轮次走 RuntimeEvent(ERROR) status: pending - id: p1-tools-refactor content: 重构 agent_tools.py：将 _confirm() 和 console.print 替换为通过 ConfirmGate 回调 + 返回结构化结果；dispatch_tool 新增 confirm_gate 参数；保持现有测试兼容（SyncConfirmGate 作为默认） status: pending - id: p1-tests content: tests/test_agent_runtime.py：mock LLM + mock ConfirmGate，验证事件流完整性（ROUND_START → TOOL_CALL → CONFIRM_REQUIRED → TOOL_RESULT → FINAL）、最大轮次终止、纯文本路径产出 TOKEN 事件 status: pending - name: "Phase 2: CLI Adapter 切换" todos: - id: p2-cli-adapter content: 重构 agent_loop.py 的 run_agent_loop：改为 AgentRuntime 的同步包装，内部 asyncio.run(runtime.run_turn(...))，消费事件流：TOKEN→print、TOOL_CALL→显示工具名、CONFIRM_REQUIRED→input()、FINAL→返回文本 status: pending - id: p2-studio-adapt content: studio.py 主循环适配：保持 / 命令不变，非 / 输入走新的 run_agent_loop（内部已切换到 Runtime）；验证 /undo、/history、/ctx、@ref 等全部兼容 status: pending - id: p2-trace-cmd content: studio.py 新增 /trace 命令：打印最近一次 agent loop 的完整事件流（tool decisions + confirm + results），方便开发者调试 status: pending - id: p2-regression content: 运行全量测试（test_agent_tools + test_agent_loop + test_cli_studio），确保 29+ tests 全部通过；补充 /trace 命令的基础测试 status: pending - name: "Phase 3: Service Adapter（FastAPI 服务化）" todos: - id: p3-protocols content: 新建 agenticx/studio/protocols.py：定义 API 请求/响应模型（ChatRequest、ConfirmResponse、SessionState）和 SSE 事件格式，参考桌面版 plan 的 WebSocket API 设计 status: pending - id: p3-session-mgr content: 新建 agenticx/studio/session_manager.py：多会话管理（create/get/delete session），每个 session 持有独立 StudioSession + AgentRuntime 实例，支持超时清理 status: pending - id: p3-server content: 新建 agenticx/studio/server.py：FastAPI 应用，核心端点：POST /api/chat（SSE 流式返回 RuntimeEvent）、POST /api/confirm（回复确认）、GET /api/session（会话状态）、GET /api/artifacts（产物列表）、DELETE /api/session（重置） status: pending - id: p3-server-tests content: tests/test_studio_server.py：使用 httpx + FastAPI TestClient，验证 SSE 事件流、确认闸门流程、会话生命周期；mock LLM 避免真实调用 status: pending - id: p3-cli-entry content: agx serve 命令：在 agenticx/cli/main.py 新增 serve 子命令，启动 FastAPI 服务（uvicorn），支持 --port --host 参数 status: pending - name: "Phase 4: Desktop MVP（Electron + React 脚手架）" todos: - id: p4-scaffold content: desktop/ 目录：Electron + React + TypeScript 项目脚手架（electron-builder + Vite），含 main.ts（主进程）+ App.tsx（渲染进程）+ 基础打包配置 status: pending - id: p4-floating-ball content: FloatingBall 组件：全局置顶、可拖拽、状态指示（idle/listening/processing）、右键菜单（设置/侧边栏/退出），参考桌面版 plan 4.1.1 设计 status: pending - id: p4-sidebar content: Sidebar 组件：对话气泡（用户/助手/工具调用）、确认弹窗（ConfirmDialog）、代码预览面板、输入框（文本），通过 SSE 连接 agx serve 获取事件流 status: pending - id: p4-tray content: 系统托盘集成：菜单项（打开侧边栏/设置/退出）、状态图标切换 status: pending - id: p4-e2e content: Desktop 端到端验证：启动 agx serve → 打开 Electron → 输入自然语言 → 看到事件流 → 确认工具调用 → 查看产物 status: pending - name: "Phase 5: 语音层与体验增强（后续）" todos: - id: p5-stt content: 集成 STT（Web Speech API / Whisper）：悬浮球点击→录音→转文字→发送到 /api/chat status: pending - id: p5-tts content: 集成 TTS（Edge TTS / Web Speech API）：FINAL 事件 → 语音播报，支持情感化语气（参考桌面版 plan 4.2.3） status: pending - id: p5-wakeword content: 唤醒词监听（Picovoice / 自定义）：Hey Jarvis → 唤醒 → 开始录音 status: pending - id: p5-interrupt content: 语音打断：TTS 播放中检测用户说话 → 停止播放 → 切入新一轮对话 status: pending --- # Agent Runtime 统一化 ## 战略定位 ``` AgentRuntime（核心内核） ┌────────────┴────────────┐ ▼ ▼ CLI Adapter Service Adapter （agx studio） （FastAPI + SSE） typed REPL │ ▼ Desktop UI (Electron) voice + floating ball ``` **核心原则**：Runtime 是唯一的"大脑"，CLI 和 Desktop 只是不同的"嘴和手"。 ## 已有基础（Agent Loop 改造已完成） - `agenticx/cli/agent_tools.py`：11 个工具 + dispatch_tool + 安全机制 - `agenticx/cli/agent_loop.py`：run_agent_loop + system prompt + 历史管理 - `agenticx/cli/studio.py`：REPL 主循环 + / 命令 + 会话状态 - 安全：shell=False、workspace 边界、diff 确认、高风险子命令检测 - 测试：29 passed（agent_tools + agent_loop + cli_studio） ## 当前问题（要解决的） - Agent Loop 与 CLI REPL **耦合**：`run_agent_loop` 直接 `console.print`、直接 `input()` - 无法被 HTTP 服务层调用（阻塞 I/O、无事件流） - `_confirm()` 和 `ask_user` 是同步 `input()`，桌面端无法接管 - 工具执行结果直接打印到 stdout，不是结构化事件 ## 关键设计 ### AgentRuntime 事件协议 ```python @dataclass class RuntimeEvent: type: str # "token" | "tool_call" | "tool_result" | "confirm_required" | "final" | "error" | "round_start" data: Dict[str, Any] # 示例事件流： # {"type": "round_start", "data": {"round": 1, "max_rounds": 10}} # {"type": "tool_call", "data": {"name": "bash_exec", "arguments": {...}}} # {"type": "confirm_required", "data": {"id": "xxx", "question": "Write to file?"}} # ... 用户回复 confirm ... # {"type": "tool_result", "data": {"name": "bash_exec", "result": "exit_code=0..."}} # {"type": "token", "data": {"text": "已"}} # {"type": "token", "data": {"text": "完成"}} # {"type": "final", "data": {"text": "已完成文件写入。"}} ``` ### 确认闸门（Confirm Gate） 现有的 `_confirm()`/`ask_user` 改为异步回调： - CLI adapter：同步 `input()` 阻塞 - Service adapter：发 SSE confirm_required 事件，等 HTTP POST 回复 ### 文件清单 - `agenticx/runtime/agent_runtime.py`（新建）：AgentRuntime 核心，输出事件流 - `agenticx/runtime/events.py`（新建）：RuntimeEvent + EventType 定义 - `agenticx/runtime/confirm.py`（新建）：ConfirmGate 抽象 + CLI/Async 实现 - `agenticx/runtime/__init__.py`（新建）：导出 - `agenticx/cli/agent_loop.py`（重构）：改为调用 AgentRuntime - `agenticx/cli/agent_tools.py`（重构）：confirm 回调化 - `agenticx/cli/studio.py`（适配）：消费 RuntimeEvent 事件流 - `agenticx/studio/server.py`（新建）：FastAPI 服务层 - `agenticx/studio/session_manager.py`（新建）：多会话管理 - `agenticx/studio/protocols.py`（新建）：API 协议定义 - `desktop/`（新建）：Electron + React 前端脚手架 ## 与桌面版 plan 的关系 桌面版 plan（`.cursor/plans/2026-03-08-agenticx-studio-desktop.plan.md`）保留作为 **PRD 参考**： - UI/UX 设计（悬浮球/侧边栏/托盘）→ Phase 4 直接复用 - 语音交互设计 → Phase 5 直接复用 - API 协议草案 → Phase 3 参考并升级 - 技术栈选型 → 沿用（Electron + React + FastAPI + Zustand） - 里程碑节奏 → 吸收但按新架构重排

--- name: Meta-Agent Team Architecture overview: 将 AgenticX Desktop 从单 Agent 串行模式升级为 Meta-Agent（CEO）+ Agent Team 多智能体协作架构，让主智能体始终可对话、子智能体并行执行、右侧面板实时展示进度。 todos: [] isProject: true phases: - name: "Phase 1: 核心后端 — AgentTeamManager + SubAgent 隔离" todos: - id: p1-events-agent-id content: "修改 `agenticx/runtime/events.py`：`RuntimeEvent` 增加 `agent_id: str = \"meta\"` 字段，确保序列化时始终携带。同步更新 `EventType` 新增 `SUBAGENT_STARTED`, `SUBAGENT_PROGRESS`, `SUBAGENT_COMPLETED`, `SUBAGENT_ERROR` 四个枚举值。" status: pending - id: p1-subagent-context content: 新建 `agenticx/runtime/team_manager.py`：定义 `SubAgentContext` dataclass（agent_id, name, role, task, status, agent_messages, artifacts, context_files, confirm_gate, result_summary, created_at, updated_at）；定义 `SubAgentStatus` 枚举（PENDING, RUNNING, COMPLETED, FAILED, CANCELLED）。 status: pending - id: p1-team-manager content: 在 `team_manager.py` 中实现 `AgentTeamManager` 类：spawn_subagent()（创建 SubAgentContext + 启动独立 AgentRuntime asyncio.Task，并发限制 max_concurrent=4）、cancel_subagent()（通过 should_stop 中断）、get_status()（返回所有 sub-agent 状态摘要）、_run_subagent()（内部方法，运行单个 sub-agent 的 run_turn 循环，收集事件并通过回调转发，完成后生成 result_summary）。 status: pending - id: p1-resource-monitor content: 新建 `agenticx/runtime/resource_monitor.py`：`ResourceMonitor` 类，提供 `get_system_stats()` 返回 CPU%、内存%、活跃 sub-agent 数。`can_spawn()` 方法根据阈值判断是否允许新建 sub-agent。 status: pending - id: p1-meta-tools content: 新建 `agenticx/runtime/meta_tools.py`：定义 Meta-Agent 专用工具：`spawn_subagent(name, role, task, tools?)` — 调用 TeamManager 创建子 agent 并返回 agent_id；`cancel_subagent(agent_id)` — 中断指定 sub-agent；`query_subagent_status(agent_id?)` — 查询进度；`check_resources()` — 返回当前资源状况和建议。工具定义遵循 STUDIO_TOOLS 相同的 dict schema。 status: pending - id: p1-runtime-agent-id content: "修改 `agenticx/runtime/agent_runtime.py`：`run_turn` 新增 `agent_id: str = \"meta\"` 参数，所有 yield 的 `RuntimeEvent` 填充此 `agent_id`。不改变现有逻辑，仅传递标识。" status: pending - id: p1-confirm-isolation content: "修改 `agenticx/runtime/confirm.py` 和 `session_manager.py`：支持 per-agent confirm gate。`ManagedSession` 新增 `sub_confirm_gates: Dict[str, AsyncConfirmGate]`，`/api/confirm` 根据 `agent_id` 路由到对应 gate。" status: pending - id: p1-tests-backend content: 新增 `tests/test_team_manager.py`：测试 spawn/cancel/并发限制/资源检查/结果回收。新增 `tests/test_meta_tools.py`：测试三个 meta 工具的调用和返回格式。修改 `tests/test_agent_runtime.py`：验证事件携带 agent_id。 status: pending - name: "Phase 2: Server 层 — SSE 多路合并 + Meta-Agent 会话管理" todos: - id: p2-session-team content: "修改 `agenticx/studio/session_manager.py`：`ManagedSession` 新增 `team_manager: Optional[AgentTeamManager]`（懒初始化）。新增方法 `get_or_create_team()` 返回 `AgentTeamManager` 实例。" status: pending - id: p2-server-multiplex content: 修改 `agenticx/studio/server.py`：`/api/chat` 的 `_event_stream` 支持多路事件合并。Meta-Agent 的 run_turn 事件 + sub-agent 通过 asyncio.Queue 转发的事件统一 yield，每个 SSE data 都含 `agent_id` 字段。 status: pending - id: p2-confirm-route content: 修改 `/api/confirm` 端点：接受新增字段 `agent_id`（默认 `"meta"`），根据 agent_id 找到对应的 confirm_gate 提交确认。 status: pending - id: p2-subagent-events content: 在 server SSE 流中新增 sub-agent 生命周期事件的转发：当 TeamManager 发出 SUBAGENT_STARTED/PROGRESS/COMPLETED/ERROR 时，通过合并 queue 推送给前端。 status: pending - id: p2-meta-system-prompt content: 创建 Meta-Agent 专用 system prompt 模板（可放在 `agenticx/runtime/prompts/meta_agent.py`），包含：角色定义（CEO/调度者）、可用工具说明、任务拆解策略、进度汇报格式、资源感知指令。 status: pending - id: p2-tests-server content: 修改 `tests/test_studio_server.py`：测试 SSE 事件含 agent_id、confirm 路由、多 agent 事件合并。 status: pending - name: "Phase 3: 前端 — 侧边面板 + 多 Agent 消息路由" todos: - id: p3-store-model content: "修改 `desktop/src/store.ts`：Message 新增 `agentId?: string` 字段。新增 `SubAgent` 类型（id, name, role, status, task, progress?, currentAction?）。Store 新增 `subAgents: SubAgent[]`、`selectedSubAgent: string | null`、`addSubAgent`、`updateSubAgent`、`removeSubAgent` 方法。" status: pending - id: p3-chatview-meta-only content: 修改 `desktop/src/components/ChatView.tsx`：只渲染 `agentId === "meta" || agentId === undefined` 的消息。SSE 事件处理按 agent_id 路由：meta 事件更新聊天，sub-agent 事件更新 store 中对应 SubAgent 状态。 status: pending - id: p3-subagent-panel content: 新建 `desktop/src/components/SubAgentPanel.tsx`：右侧可折叠面板（宽 280px~320px，动画展开/折叠），列出所有活跃 sub-agent 卡片。面板顶部有汇总状态（N running / N done / N pending）。 status: pending - id: p3-subagent-card content: 新建 `desktop/src/components/SubAgentCard.tsx`：单个 sub-agent 的进度卡片。显示：名称、角色标签、状态图标（⏳/🔄/✅/❌）、当前动作（如 `正在写 main.py`）、进度条（可选）、[展开详情] 按钮显示最近 tool calls、[中断] 按钮（发 cancel 请求）。展开后显示该 sub-agent 的 tool_call/tool_result 事件列表。 status: pending - id: p3-confirm-multi content: 修改 `desktop/src/components/ConfirmDialog.tsx`：confirm 弹窗增加来源标识（显示是哪个 sub-agent 请求确认）。提交时携带 `agent_id` 到 `/api/confirm`。 status: pending - id: p3-layout-responsive content: 修改 `desktop/src/App.tsx` 或 `ChatView.tsx` 布局：当有活跃 sub-agent 时自动展开右侧面板（flex 布局：左侧聊天区 flex-1，右侧面板固定宽度）。无 sub-agent 时全宽聊天。窗口最小宽度调整为 680px（以容纳面板）。 status: pending - id: p3-tests-frontend content: 验证前端 TypeScript 编译通过（`npm run build`）、无 lint 错误。手动验证侧面板展开/折叠、卡片状态更新、confirm 路由。 status: pending - name: "Phase 4: Meta-Agent 智能调度 + 端到端验证" todos: - id: p4-meta-intelligence content: 完善 Meta-Agent system prompt：引导 LLM 在收到复杂任务时自动拆解、给出 sub-agent 分配建议、在用户问进度时调用 query_subagent_status。加入资源感知指令：spawn 前先 check_resources，根据返回决定并发数。 status: pending - id: p4-result-summary content: 实现 sub-agent 完成后的摘要回传机制：TeamManager._run_subagent() 完成后提取最终回复 + 产出文件列表，压缩为 ≤500 token 摘要，注入 Meta-Agent 的 agent_messages 作为 tool_result。 status: pending - id: p4-error-recovery content: 实现 sub-agent 失败后的恢复策略：TeamManager 捕获 sub-agent 异常，标记 FAILED，将错误摘要回传 Meta-Agent，由 Meta-Agent 决定重试或跳过。 status: pending - id: p4-e2e-test content: 端到端验证：在 Desktop 中发送 `帮我创建一个深度调研助手`，验证：(1) Meta-Agent 拆解任务并 spawn sub-agents (2) 右侧面板显示 sub-agent 进度 (3) 用户在主聊天区问进度得到即时回复 (4) 可中断单个 sub-agent (5) 所有 sub-agent 完成后 Meta-Agent 汇总结果。 status: pending - id: p4-docs content: 更新 `docs/cli.md` 增加 Agent Team 章节。更新 `desktop/README.md` 增加多智能体协作说明。 status: pending --- # Meta-Agent + Agent Team 多智能体协作架构 ## 背景 当前 AgenticX Desktop 是单 Agent 串行执行：一旦进入工具调用循环，Agent 被"绑死"在子任务中，用户无法交互；长程任务 10 轮 tool call 后上下文溢出，任务必然失败。 ## 目标架构 ``` 用户 ↔ Meta-Agent (CEO, 永不阻塞) ↕ AgentTeamManager ┌─────┬─────┬─────┐ │ SA1 │ SA2 │ SA3 │ (独立上下文, 独立 runtime) └─────┴─────┴─────┘ ``` - **Meta-Agent**：只做意图理解、任务拆解、进度汇报、资源调度。自身上下文极轻（只保留决策日志 + 最新 sub-agent 摘要） - **Sub-Agent**：独立 `AgentRuntime` 实例 + 独立上下文窗口 + 独立 confirm gate - **事件流**：所有 `RuntimeEvent` 携带 `agent_id`，前端按 agent 分流渲染 ## 关键设计决策 ### D1: Meta-Agent 不执行工具 Meta-Agent 只有三类工具： - `spawn_subagent(name, role, task, tools?, dependencies?)` - `cancel_subagent(agent_id)` - `query_subagent_status(agent_id?)` 其余 11 个 STUDIO_TOOLS（bash_exec, file_write 等）只分配给 sub-agent。 这保证 Meta-Agent **永不阻塞**，始终可响应用户。 ### D2: Sub-Agent 上下文完全隔离 每个 sub-agent 拥有独立的 `SubAgentContext`: - `agent_messages: list` — 独立对话历史 - `artifacts: dict` — 独立产物记录 - `context_files: dict` — 独立上下文文件 - `confirm_gate: AsyncConfirmGate` — 独立确认门 Sub-agent 完成后，仅将**摘要**（结果 + 产出文件列表）回传 Meta-Agent 上下文。 ### D3: SSE 事件统一加 agent_id `RuntimeEvent` 新增 `agent_id: str` 字段（`"meta"` 代表主 agent）。 前端按 `agent_id` 将事件路由到： - `agent_id == "meta"` → 主聊天区 - 其他 → 右侧面板对应 sub-agent 卡片 ### D4: 资源管控 `AgentTeamManager` 维护并发限制： - `max_concurrent_subagents: int = 4`（可配置） - 启动前检查系统资源（CPU、内存），拒绝或排队 - Meta-Agent 工具返回资源状态，LLM 自行决策 ### D5: SSE vs WebSocket 本阶段继续使用 SSE（多路合并到单 SSE 流，按 agent_id 区分），避免协议切换带来的复杂度。未来可升级 WebSocket。 ## 核心文件变更地图 **新增文件**: - `agenticx/runtime/team_manager.py` — AgentTeamManager, SubAgentContext - `agenticx/runtime/meta_tools.py` — spawn/cancel/query 三个 Meta-Agent 专用工具 - `agenticx/runtime/resource_monitor.py` — 系统资源检测 - `desktop/src/components/SubAgentPanel.tsx` — 右侧子智能体面板 - `desktop/src/components/SubAgentCard.tsx` — 单个子智能体卡片 **大改文件**: - `agenticx/runtime/agent_runtime.py` — run_turn 支持 agent_id 传递 - `agenticx/studio/session_manager.py` — ManagedSession 支持多 runtime - `agenticx/studio/server.py` — SSE 事件带 agent_id, 多路合并 - `desktop/src/store.ts` — Message 增加 agentId, 新增 subAgents state - `desktop/src/components/ChatView.tsx` — 只渲染 meta agent 消息, 侧边面板联动 **中改文件**: - `agenticx/runtime/events.py` — RuntimeEvent 增加 agent_id - `agenticx/runtime/confirm.py` — per-agent confirm gate - `agenticx/cli/agent_tools.py` — 工具注册区分 meta vs sub ## 风险与对策 - **并发安全**：sub-agent 完全隔离 context，通过 `TeamManager.report_result()` 串行回写 meta context - **Confirm 冲突**：每个 sub-agent 独立 `AsyncConfirmGate`，前端根据 `agent_id` 路由确认弹窗 - **资源过载**：`max_concurrent_subagents` 硬限制 + 资源检测软限制 - **上下文膨胀**：sub-agent 结果只回传摘要（≤500 tokens），不回传完整 messages - **MCP 并发**：MCP hub 维持共享但加异步锁 ## 验证策略 - 单元测试：`TeamManager` 的 spawn/cancel/并发/资源限制 - 集成测试：Meta-Agent 通过 tool call 启动 sub-agent 并收集结果 - 前端测试：multi-agent 事件流渲染 + 侧面板更新 - 端到端：在 Desktop 中对话触发多 sub-agent 任务，验证进度可见 + 可中断 + 可交互

--- name: Studio Agent Loop 改造 overview: 将 agx studio 从"固定路由 REPL"升级为"LLM Agent Loop + Tool Calling"架构，让 LLM 自主选择工具（bash、file_edit、codegen、mcp_call、skill_use、ask_user 等），同时兼容现有 / 命令快捷方式。这是 CLI 和桌面版的共同底座。 todos: [] isProject: true phases: - name: "Phase 1: Tool 定义与注册" todos: - id: p1-tool-schema content: 新建 `agenticx/cli/agent_tools.py`：定义 STUDIO_TOOLS 列表（OpenAI function calling JSON Schema 格式），包含 bash_exec、file_read、file_write、file_edit、codegen、mcp_connect、mcp_call、skill_use、skill_list、ask_user、list_files 共 11 个工具 status: pending - id: p1-tool-impl content: agent_tools.py 中实现每个工具的执行函数：bash_exec 用 subprocess.run（白名单检查）、file_read 用 Path.read_text（行号范围）、file_write 用 Path.write_text（显示 diff 确认）、file_edit 用字符串替换（显示 diff）、codegen 调用 CodeGenEngine、mcp_connect/mcp_call 调用 studio_mcp、skill_use/skill_list 调用 studio_skill、ask_user 用 input() 阻塞等待、list_files 用 os.listdir + glob status: pending - id: p1-dispatcher content: agent_tools.py 中实现 `dispatch_tool(name, arguments, session) -> str` 统一分发器，根据 tool name 路由到对应函数，返回字符串结果 status: pending - id: p1-safety content: bash_exec 安全机制：定义 SAFE_COMMANDS 白名单（ls/cat/head/tail/grep/find/wc/python/pip/git/echo/pwd/which/tree），非白名单命令自动调用 ask_user 确认；file_write/file_edit 写入前显示 diff 并确认 status: pending - name: "Phase 2: Agent Loop 引擎" todos: - id: p2-loop-core content: 新建 `agenticx/cli/agent_loop.py`：实现 `run_agent_loop(session, llm, user_input) -> str` 核心函数。构建 system prompt（元 Skills + artifacts + context_files + MCP tools），调用 llm.invoke(messages, tools=STUDIO_TOOLS, tool_choice='auto')，解析 response 中的 tool_calls，执行工具，将结果回注 messages，循环直到 LLM 返回纯文本或达到最大轮次 status: pending - id: p2-system-prompt content: agent_loop.py 中实现 `_build_agent_system_prompt(session)` ：注入角色定义、元 Skills 摘要、当前 artifacts、context_files、MCP 工具信息、行为准则（中文回复、关键操作确认、安全约束） status: pending - id: p2-streaming content: Agent Loop 纯文本输出时使用流式输出（复用现有的 print(chunk) 逻辑）；tool_call 执行时显示 spinner 或状态提示 status: pending - id: p2-history content: Agent Loop 每轮的 messages（含 tool_calls + tool results）存入 session.chat_history，保持多轮对话连贯性 status: pending - id: p2-max-turns content: 最大循环轮次限制（默认 MAX_TOOL_ROUNDS=10），超过时提示用户并停止 status: pending - name: "Phase 3: Studio 主循环改造" todos: - id: p3-integrate content: studio.py 主循环改造：保留所有 / 命令快捷路由（/mcp、/skill、/ctx、/show、/run、/save、/undo、/image、/history、/config、/discover、/exit）；删除 IntentClassifier 路由逻辑，非 / 输入全部走 run_agent_loop(session, llm, user_input)；删除 _chat_reply 函数（Agent Loop 替代） status: pending - id: p3-session-update content: "StudioSession 新增 `agent_messages: List[Dict]` 字段，存储 Agent Loop 的完整 messages 历史（含 tool_calls），替代现有的 chat_history（仅存 role/content 对）" status: pending - id: p3-welcome content: 更新欢迎语：「直接用自然语言描述你想做什么，或输入 shell 命令。」 status: pending - name: "Phase 4: 文档与测试" todos: - id: p4-docs content: docs/cli.md 更新 Studio 章节：说明 Agent Loop 架构、工具列表、安全机制、典型用法示例（自然语言 + shell 命令 + 混合场景） status: pending - id: p4-tests content: tests/test_agent_tools.py 和 tests/test_agent_loop.py：mock LLM 和工具，验证 tool dispatch、安全白名单、循环终止、流式输出 status: pending - id: p4-commit content: 按功能点分组提交，所有 commit 带 Plan-Id trailer status: pending --- # Studio Agent Loop 改造 ## 架构对比 **现有架构（固定路由）**： ``` 用户输入 → IntentClassifier(规则+LLM) → CHAT/GENERATE/MODIFY → 固定处理器 ``` **目标架构（Agent Loop）**： ``` 用户输入 → / 命令快捷路由（保留） → 非 / 开头 → Agent Loop: system prompt(元Skills+上下文+工具定义) + user message → LLM(tool_choice="auto") → tool_call? → 执行工具 → 结果回注 → 继续循环 → 纯文本? → 流式输出 → 结束 ``` ## 关键设计决策 ### 1. / 命令保留为"快捷方式" `/mcp`、`/skill`、`/ctx`、`/show`、`/run` 等保持不变，作为 power user 的快捷入口。 非 / 开头的输入全部进入 Agent Loop。 ### 2. Tool 定义（JSON Schema for function calling） 每个工具对应一个 Python 函数 + JSON Schema 定义。LLM 通过 `tools` 参数看到所有工具。 **核心工具集**： - `bash_exec(command)` — 在当前目录执行 shell 命令，返回 stdout/stderr - `file_read(path, start_line?, end_line?)` — 读取文件内容 - `file_write(path, content)` — 写入/覆盖文件 - `file_edit(path, old_text, new_text)` — 精确替换文件片段（类似 CC 的 apply diff） - `codegen(target, description)` — 调用 CodeGenEngine 生成 agent/workflow/tool/skill - `mcp_connect(server_name)` — 连接 MCP server - `mcp_call(tool_name, arguments)` — 调用 MCP 工具 - `skill_use(name)` — 激活 skill 到上下文 - `skill_list()` — 列出可用 skills - `ask_user(question)` — 暂停执行，向用户提问，等待回答 - `list_files(directory?, pattern?)` — 列出目录内容（安全版 ls） ### 3. 安全边界 - `bash_exec`：默认白名单（ls, cat, head, tail, grep, find, wc, python, pip, git status/log/diff） - 非白名单命令需用户确认（通过 ask_user） - `file_write`/`file_edit` 写入前显示 diff，需确认 - 最大循环轮次限制（防止死循环），默认 10 轮 ### 4. 与现有代码的关系 - `IntentClassifier`：**保留但弱化**，仅作为 Agent Loop 内部的一个 fallback - `CodeGenEngine`：**保留**，作为 `codegen` 工具的底层实现 - `studio_mcp.py`：**保留**，`mcp_connect/mcp_call` 工具的底层实现 - `studio_skill.py`：**保留**，`skill_use/skill_list` 工具的底层实现 - `_chat_reply()`：**替换**为 Agent Loop 的文本输出路径 ## 改动文件清单 - `agenticx/cli/agent_tools.py`（新建）：定义所有 Studio Tool 函数 + JSON Schema - `agenticx/cli/agent_loop.py`（新建）：Agent Loop 核心引擎（system prompt 构建、tool dispatch、循环控制） - `agenticx/cli/studio.py`（修改）：主循环中非 / 输入走 agent_loop，替代 IntentClassifier + 固定路由 - `agenticx/cli/codegen_engine.py`（微调）：作为 codegen tool 的底层，无重大改动 - `docs/cli.md`（更新）：Agent Loop 使用说明