clawgo/docs/master-subagent-development.md

主 Agent + 子 Agent 架构开发文档

1. 目标与范围

本文档定义在 ClawGo 中实现“单一主 Agent 对话入口 + 可动态创建子 Agent 执行任务”的开发方案。

目标：

• 由主 Agent 统一接收用户对话并调度子 Agent。
• 子 Agent 可按职责分工（如 coding、docs、testing）。
• 子 Agent 具备各自独立记忆与会话上下文。
• 所有 Agent 共享同一工作空间（文件系统）。
• 支持主 Agent 在一次对话中创建、调用、监控子 Agent 并汇总结果。

非目标：

• 不在本阶段引入独立进程/独立容器隔离。
• 不在本阶段实现跨机器分布式调度。

---

2. 现状（基于当前代码）

已具备能力：

• spawn 工具可创建后台子任务。
• subagents 工具可 list/info/kill/steer/resume。
• Orchestrator + pipeline_* 具备任务依赖编排模型。

关键差距：

• 目前子任务偏“临时任务实例”，缺少“长期角色子 Agent”概念。
• spawn.role 参数未完整进入任务状态与调度决策。
• 子任务会话键未与 agent/task 强绑定，存在上下文串线风险。
• pipeline_* 工具已实现但尚未在主循环注册使用。
• 记忆目前以工作区全局为主，缺少“子 Agent 命名空间隔离”。

---

3. 总体架构

3.1 角色分层

• 主 Agent（Orchestrator Agent）
  • 职责：需求理解、任务拆分、分派、进度追踪、结果汇总、用户回复。
  • 不直接承载全部执行细节。
• 子 Agent（Worker Agent）
  • 职责：按角色执行具体任务（代码实现、文档编写、测试验证等）。
  • 具备独立的会话与记忆上下文。

3.2 共享与隔离策略

• 共享：workspace 文件系统、工具注册中心、pipeline shared_state。
• 隔离：子 Agent 的 session history、长期记忆、每日记忆。

3.3 运行模型

• 主 Agent 发起任务后，创建/复用子 Agent profile。
• 通过 pipeline_create 建立任务 DAG。
• 通过 pipeline_dispatch 调度 dependency-ready 任务到子 Agent。
• 子 Agent 完成后回填结果，主 Agent 汇总并回复用户。

---

4. 数据模型设计

4.1 SubagentProfile（新增，持久化）

建议存储位置：workspace/agents/profiles/<agent_id>.json

字段：

• agent_id: 全局唯一 ID（如 coder, writer, tester）。
• name: 展示名。
• role: 角色（coding/docs/testing/research...）。
• system_prompt: 角色系统提示词模板。
• tool_allowlist: 可调用工具白名单。
• memory_namespace: 记忆命名空间，默认同 agent_id。
• status: active|disabled。
• created_at / updated_at。

4.2 SubagentTask（扩展现有）

文件：pkg/tools/subagent.go

已有字段基础上强化：

• Role：落库并展示。
• AgentID：绑定具体子 Agent profile。
• SessionKey：固定记录实际执行 session key。
• MemoryNamespace：记录使用的记忆命名空间。

4.3 记忆目录结构（新增约定）

• 主 Agent（保持现状）：
  • workspace/MEMORY.md
  • workspace/memory/YYYY-MM-DD.md
• 子 Agent <agent_id>：
  • workspace/agents/<agent_id>/MEMORY.md
  • workspace/agents/<agent_id>/memory/YYYY-MM-DD.md

---

5. 工具与接口设计

5.1 现有工具接入调整

• spawn
  • 新增/强化参数：agent_id、role。
  • 优先级：agent_id > role（role 可映射默认 profile）。
• subagents
  • list/info 输出包含：agent_id、role、session_key、memory_namespace。

5.2 新增工具建议

• subagent_profile
  • action: create|get|list|update|disable|enable|delete
  • 用途：由主 Agent 在对话中动态创建/管理子 Agent。
• subagent_dispatch（可选）
  • 对单个 profile 下发任务，内部调用 spawn 并处理 profile 绑定。

5.3 Pipeline 工具注册

需在 pkg/agent/loop.go 中注册：

• pipeline_create
• pipeline_status
• pipeline_state_set
• pipeline_dispatch

使主 Agent 能直接调用现有编排能力。

---

6. 执行流程（主对话驱动）

1. 用户下达复合目标（如“先实现功能，再生成文档”）。
2. 主 Agent 判断是否已有对应 profile：
   • 无则 subagent_profile.create。
   • 有则复用。
3. 主 Agent 生成 pipeline 任务图（含依赖）。
4. 主 Agent 调用 pipeline_dispatch 派发可运行任务。
5. 子 Agent 执行并回填结果到任务状态/共享状态。
6. 主 Agent 轮询 pipeline_status，直到完成或失败。
7. 主 Agent 汇总结果，面向用户输出最终响应。

---

7. 会话与记忆隔离实现要点

7.1 Session Key 规范

禁止使用进程级固定 key。

建议格式：

• subagent:<agent_id>:<task_id>

效果：

• 同一子 Agent 不同任务可隔离上下文。
• 可追溯某次任务完整对话与工具链。

7.2 ContextBuilder 多命名空间支持

为 MemoryStore 增加 namespace 参数，按 namespace 读取不同路径：

• namespace=main -> 当前全局路径（兼容）。
• namespace=<agent_id> -> workspace/agents/<agent_id>/...

在子 Agent 执行入口按任务绑定 namespace 构建上下文。

7.3 Memory Tool 命名空间透传

memory_search / memory_get / memory_write 增加可选参数：

• namespace（默认 main）

子 Agent 默认注入自身 namespace，避免写入全局记忆。

---

8. 调度与并发控制

• 同会话调度仍受 SessionScheduler 约束。
• pipeline 维度使用依赖图保证顺序正确。
• 对写冲突资源建议引入 resource_keys（文件路径、模块名）串行化。
• 子 Agent 失败后可支持：
  • resume
  • 自动重试（指数退避）
  • 主 Agent 降级接管

---

9. 安全与治理

• 子 Agent 继承 AGENTS.md 安全策略。
• 外部/破坏性动作必须经主 Agent 显式确认。
• 子 Agent 工具权限建议最小化（allowlist）。
• 审计日志需记录：
  • 谁创建了哪个子 Agent
  • 子 Agent 执行了什么任务
  • 任务结果和错误

---

10. 实施顺序（不含工期）

阶段 A：打通主调度闭环

• 修正子任务 session key 规范化。
• 将 Role、AgentID 写入任务结构与 subagents 输出。
• 在主循环注册 pipeline_* 工具并验证端到端可调度。

阶段 B：子 Agent 记忆隔离

• 实现 SubagentProfile 持久化与管理工具。
• MemoryStore 增加 namespace。
• memory 系列工具支持 namespace。

阶段 C：稳定性与治理增强

• 增加资源冲突控制（resource keys）。
• 增加失败重试、超时、配额与审计维度。
• 增加 WebUI 可视化（profile/task/pipeline/memory namespace）。

---

13. 当前实现状态（代码已落地）

13.1 已完成

• 主循环已注册：
  • subagent_profile
  • pipeline_create
  • pipeline_status
  • pipeline_state_set
  • pipeline_dispatch
• spawn 已支持：
  • agent_id
  • role
  • agent_id > role 解析优先级
  • 当仅提供 role 时，按 role 自动映射已存在 profile（最近更新优先）
• 子任务会话隔离：
  • session_key 使用 subagent:<agent_id>:<task_id>
• 子任务记忆隔离：
  • memory namespace 已接入 ContextBuilder 与 memory_search/get/write
  • 子 Agent 运行时会自动注入其 namespace
• 子任务治理信息增强：
  • subagents list/info/log 可显示 agent_id/role/session_key/memory namespace/tool allowlist
• 安全治理：
  • tool_allowlist 已在执行期强制拦截
  • parallel 工具的内部子调用也会被白名单校验
  • tool_allowlist 已支持分组策略（group:<name> / @<name> / 组名直写）
  • disabled profile 会阻止 spawn
• 稳定性治理：
  • 子 Agent 已支持 profile 级重试/退避/超时/配额控制（max_retries / retry_backoff_ms / timeout_sec / max_task_chars / max_result_chars）
  • 子任务元数据与 system 回填中包含重试/超时信息，便于审计追踪
• WebUI 可视化：
  • 已提供 subagent profile 管理页
  • 已提供 subagent runtime 列表/详情/控制页（spawn/kill/resume/steer）
  • 已提供 pipeline 列表/详情/dispatch/创建入口

13.2 待继续增强

• （当前版本）无阻塞项；可继续按需增强：
  • allowlist 分组支持自定义组配置（当前为内置组）。
  • pipeline / subagent 运行态持久化与历史回放（当前为进程内实时视图）。

---

11. 验收标准

• 用户可通过自然语言要求主 Agent 创建指定角色子 Agent。
• 主 Agent 可在一次对话内完成“创建 -> 派发 -> 监控 -> 汇总”。
• 子 Agent 记忆互不污染，主 Agent 与子 Agent 记忆边界清晰。
• 同一 workspace 下可稳定并发执行多子任务，无明显上下文串线。
• 任务失败可追踪、可恢复，且审计信息完整。

---

12. 与现有代码的对应关系

• 子任务管理：pkg/tools/subagent.go
• 子任务工具：pkg/tools/subagents_tool.go
• 子任务创建：pkg/tools/spawn.go
• 流水线编排：pkg/tools/orchestrator.go
• 流水线工具：pkg/tools/pipeline_tools.go
• 主循环工具注册：pkg/agent/loop.go
• 上下文与记忆：pkg/agent/context.go, pkg/agent/memory.go
• memory 工具：pkg/tools/memory*.go