From 63760ff1869cfea77659277069cb40285c322865 Mon Sep 17 00:00:00 2001 From: yumoqing Date: Sat, 15 Aug 2026 09:04:49 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=80=9A=E7=94=A8=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E9=9B=86=E5=AE=9A=E4=B9=89(read/write/list/search=5Ffiles/sess?= =?UTF-8?q?ion=5Fsearch/todo)+=E6=95=B4=E4=BD=93=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agent-architecture.md | 84 +++++++++++++++++++++++++++++++++++ pipeline_core/agent_config.py | 37 +++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 docs/agent-architecture.md diff --git a/docs/agent-architecture.md b/docs/agent-architecture.md new file mode 100644 index 0000000..2426aaa --- /dev/null +++ b/docs/agent-architecture.md @@ -0,0 +1,84 @@ +# pipeline-core Agent 架构设计：对齐 Hermes CLI 能力 + +> 目标：让 pipeline-core 的 agent 达到 Hermes CLI 的能力水平，通过 gateway 服务层 + bricks 适配， +> 在 Web 界面用 AgentIO 提供与 Hermes CLI 相同的交互体验。 + +## 1. 现状盘点 + +pipeline-core 已有"对照 Hermes 重构"的骨架： + +| 层 | 现状 | 位置 | +|----|------|------| +| 能力定义 | AgentConfig / ToolDefinition / CompressionConfig / MemoryConfig / SkillConfig | pipeline_core/agent_config.py | +| 工具注册 | ToolRegistry / register_tool / to_openai_schema | pipeline_core/tool_registry.py | +| 技能系统 | SkillLoader 三级隔离（global/orgs/users） | pipeline_core/skill_loader.py | +| 记忆系统 | MemoryStore（MySQL pipeline_user_memory + 缓存） | pipeline_core/memory_store.py | +| 执行引擎 | AgentExecutor（多轮 tool-loop + native function calling） | pipeline_service/agent_loop_v2.py | +| 通用工具底层 | _run_shell / _write_code_file / _git_* （仅角色 agent 用） | pipeline_service/agent_loop.py | + +## 2. 目标架构（四层） + +``` +┌────────────────────────────────────────────────────────────┐ +│ L4 交互层 pipeline-sdlc / bricks │ +│ AgentIO + slash 命令菜单 + 流式工具预览 + 会话列表 │ +├────────────────────────────────────────────────────────────┤ +│ L3 Gateway 层 pipeline-core / pipeline-service │ +│ 常驻服务 + 会话生命周期 + 通道抽象（Web AgentIO 为第一通道）│ +├────────────────────────────────────────────────────────────┤ +│ L2 执行引擎 pipeline-service AgentExecutor │ +│ 多轮工具循环 + native function calling + 上下文压缩 │ +├────────────────────────────────────────────────────────────┤ +│ L1 能力定义 pipeline-core │ +│ AgentConfig + ToolRegistry + SkillLoader + MemoryStore │ +│ + 通用工具集（terminal/file/session_search/delegation/ │ +│ clarify/todo） │ +└────────────────────────────────────────────────────────────┘ +``` + +## 3. 差距分析 + +| 能力 | Hermes CLI | pipeline 现状 | 缺口 | +|------|-----------|--------------|------| +| 多轮工具循环 | ✅ | ✅ AgentExecutor | 无 | +| 记忆 / 技能 | ✅ | ✅ 雏形 | 无 | +| 诚实降级 / 澄清 | ✅ | ✅（已修） | 无 | +| 文件工具 read/write/list/search | ✅ | 仅角色 agent 有 | cockpit 缺 | +| shell 执行 | ✅ terminal | ✅ _run_shell（run_command 已接） | 需增强 | +| 会话搜索 | ✅ session_search | ❌ | 缺 | +| 子代理委派 | ✅ delegate_task | delegate_subtask 只有壳 | 缺实现 | +| 任务规划 | ✅ todo | ❌ | 缺 | +| slash 命令 | ✅ 40+ 个 | ❌ | 缺 | +| gateway 层 | ✅ 多平台 | ❌ 只有 Web | 缺 | +| 流式 + 工具预览 + 文件上传 + 模型选择 | ✅ | ✅ 部分 | 需打磨 | + +## 4. 分阶段计划 + +### 阶段1：通用工具集（让 agent 能"干活"） +新增工具（cockpit AgentExecutor 暴露）： +- `read_file` / `write_file` / `list_files` / `search_files` —— 复用 agent_loop.py 底层，加 workspace 沙箱限制 +- `run_command` —— 已有，增强（超时/输出截断已具备） +- `session_search` —— 搜 pipeline_conversations 表 +- `delegate_subtask` —— 真正实现：spawn 子 AgentExecutor 独立执行 +- `ask_user` —— 已修好（合法终止动作） +- `todo` —— 会话内任务列表（内存态） + +交付物：pipeline-core 新增 GENERAL_TOOLS 定义 + pipeline-service 实现 handler。 + +### 阶段2：slash 命令 + AgentIO 交互对齐 +- 后端：解析 /new /model /tools /skills /status /reset 等 slash 命令 +- 前端：AgentIO 支持 slash 命令 + 工具调用过程完整展示 + 会话列表 + +### 阶段3：gateway 服务层 +- 常驻服务抽象 + 会话生命周期管理 + 通道抽象 +- 第一通道 = Web AgentIO（bricks），预留多通道接口 + +## 5. 安全约束（贯穿所有阶段） + +- terminal/file 工具必须在 workspace 目录内操作（`_is_safe_workdir` 白名单） +- 陌生用户入口（Wterm 等）必须沙箱化 + 最小权限 +- 危险命令（rm -rf 等）需确认（requires_confirmation） + +## 6. 验证标准 + +每个阶段完成后：浏览器端到端实测 agent 完整交互流程，不靠声称通过。 diff --git a/pipeline_core/agent_config.py b/pipeline_core/agent_config.py index 5a78298..92d517a 100644 --- a/pipeline_core/agent_config.py +++ b/pipeline_core/agent_config.py @@ -299,6 +299,43 @@ SDLC_DEFAULT_TOOLS = [ parameters={"goal": "子任务目标", "context": "背景信息"}, category="agent", ), + # ── 通用工具集（Hermes CLI 能力子集：文件/搜索/会话/规划）── + ToolDefinition( + name="read_file", + description="读取工作空间中的文件", + parameters={"path": "相对路径"}, + category="file", + ), + ToolDefinition( + name="write_file", + description="写入文件到工作空间（自动创建父目录）", + parameters={"path": "相对路径", "content": "文件内容"}, + category="file", + ), + ToolDefinition( + name="list_files", + description="列出工作空间目录内容", + parameters={"path": "相对路径(可选,默认工作空间根)"}, + category="file", + ), + ToolDefinition( + name="search_files", + description="在工作空间中搜索文件内容（grep）", + parameters={"pattern": "搜索关键词或正则", "path": "相对路径(可选,默认整个工作空间)"}, + category="file", + ), + ToolDefinition( + name="session_search", + description="搜索本项目的会话历史记录，找回之前讨论过的内容", + parameters={"query": "搜索关键词"}, + category="memory", + ), + ToolDefinition( + name="todo", + description="管理当前会话的任务清单（list/add/done）", + parameters={"action": "list|add|done", "content": "任务内容(add时必填)"}, + category="agent", + ), ]