PRD: Multi-Agent Collaborative CLI System

多 Agent 协同 CLI 系统

版本: v0.1 Draft 作者: 老黄日期: 2026-04-29 状态: Draft

背景与目标

现有单 Agent 模式的局限：

记忆污染：同一个 Agent 积累的 coding skill 和日常任务混在一起，行为越来越难预测
能力边界模糊：让一个 Agent 同时写代码、做日报、管 cron，职责不清
无法横向扩展：任务并发时只能串行等待

本 PRD 设计一套多 Agent 协同 CLI 系统，解决两个核心场景：

AI 软件工厂：Commander 拆解任务 → 分发给专用 Agent → 代码任务调用 Claude/Codex → 多 worktree 并行开发 → 全程可观测
多 Agent 自由协同：多个 Agent 通过 CLI 和 A2A 协议自由通信，按工作流协作

方向一：AI 软件工厂

1.1 架构总览

用户 / Web 界面
       │
       ▼
┌─────────────────┐
│   Commander     │  Hermes Profile: commander
│  (任务分解中枢)  │  - 理解需求
└────────┬────────┘  - 拆解子任务
         │           - 调度 coder/其他 agent
         │ dispatch
    ┌────┼────┬──────────┐
    ▼    ▼    ▼          ▼
┌──────┐  ┌──────┐   ┌──────────┐
│Coder │  │Coder │   │ Reviewer │
│Agent │  │Agent │   │  Agent   │
│ (A)  │  │ (B)  │   │          │
└──┬───┘  └──┬───┘   └────┬─────┘
   │         │            │
   ▼         ▼            ▼
Claude/   Claude/     Hermes 本地
Codex A   Codex B     skill 审查
          │
          ▼
   ┌──────────────┐
   │  Git Worktree│  每个 coder 一个独立 worktree
   │  Branch 隔离 │
   └──────────────┘

1.2 Agent 角色定义

Commander（指挥官）

Profile 名: commander 核心职责: 需求理解 → 任务分解 → 调度追踪 → 结果汇总

SOUL.md 核心:

# 身份
你是软件工厂的指挥官。接收产品需求，拆解为可执行的子任务，
分发给专属 Agent 执行，追踪进度，汇总结果。

# 核心原则
- 不自己写代码，只做调度
- 每个任务必须明确边界和验收标准
- 追踪所有子任务的完成状态
- 主动汇报进度，不等待用户询问

# 调度策略
- IO密集型任务（查文档、拉数据）：并行分发
- 有依赖的任务（先 API 再前端）：按拓扑顺序
- 长时间任务：定期心跳检查

# 输出格式
每个任务完成后汇报：
[任务ID] [Agent] [状态: 完成/失败/需人工介入] [耗时] [摘要]

可用工具:

delegate_task → 调度 coder/reviewer
a2a_call → 向其他 Hermes Agent 发消息
terminal → 执行 git / tmux 命令
session_search → 查历史项目上下文

Coder Agent（编码员）

Profile 名: coder-{feature-name} 或 coder-{序号} 核心职责: 执行具体代码任务，调用 Claude/Codex，不自己生成代码

SOUL.md 核心:

# 身份
你是专业编码员。你自己不生成代码，
通过调用 Claude Code 或 Codex CLI 完成所有编码工作。

# 工作流
1. 接收任务（包含：目标、验收标准、约束）
2. 确认 worktree 分支（与 commander 确认分配给自己的分支）
3. 构建 prompt → 调用 claude 或 codex
4. 审查结果（检查是否符合验收标准）
5. 不符合 → 要求重写（最多 2 轮）
6. 提交 PR / 汇报完成

# 代码审查清单
- 是否完成目标功能
- 是否有明显的逻辑错误
- 命名是否清晰
- 是否有未处理的边界情况

# 禁止
- 不自己写大段代码
- 不在未经审查的情况下直接提交

可用工具:

terminal → 调用 claude / codex / git
tmux 相关工具 → 管理多 panel
file → 读写代码文件
delegate_task → 不能再委托（leaf role）

Reviewer Agent（审查员）

Profile 名: reviewer 核心职责: 代码审查、架构评审、安全扫描

SOUL.md 核心:

# 身份
你是资深架构师和代码审查员。对提交上来的代码进行严格审查。

# 审查维度
- 正确性：功能是否完整实现
- 健壮性：边界条件、异常处理
- 安全性：SQL注入、XSS、敏感信息泄露
- 架构：模块耦合度、可测试性
- 性能：N+1查询、不必要的循环

# 输出格式
[问题级别: CRITICAL/HIGH/MEDIUM/LOW]
[文件: 行号] [问题描述]
[建议修复方案]

1.3 多 Worktree + 多 Panel 管理

Git Worktree 隔离

每个 Coder Agent 分配独立的 worktree：

# Commander 执行
git worktree add ../wt-{feature-name} -b feature/{name}
git worktree add ../wt-{bugfix-name} -b fix/{name}
 
# coder agent 在自己的 worktree 里工作
cd /path/to/repo/wt-{feature-name}

worktree 生命周期:

创建 → 分配给 Coder Agent → 开发 → PR 合入 → 等待清理 → 删除 worktree

状态追踪（Commander 维护）:

worktrees:
  wt-auth:
    branch: feature/auth-module
    owner: coder-1
    status: developing
    created_at: "2026-04-29T10:00:00Z"
    pr_url: null
  wt-api:
    branch: feature/api-v2
    owner: coder-2
    status: pr_open
    created_at: "2026-04-29T10:05:00Z"
    pr_url: "https://github.com/.../pull/42"

tmux Multi-Panel

Commander 可以打开多 panel 实时监控各 Coder 进展：

┌─────────────────────────────────────────────────┐
│ Commander: task-dashboard                       │
├─────────────┬─────────────┬────────────────────┤
│ coder-1     │ coder-2     │ reviewer-1         │
│ (wt-auth)   │ (wt-api)    │ (wt-auth PR)       │
│             │             │                    │
│ $ claude -p │ $ codex ".." │ $ hermes review... │
│ [running]   │ [complete]  │ [waiting]         │
│             │             │                    │
├─────────────┴─────────────┴────────────────────┤
│ Task Queue                                      │
│ [✓] auth-module skeleton     coder-1 2min      │
│ [✓] API client             coder-2  5min      │
│ [→] review auth PR          reviewer  pending  │
│ [ ] auth integration test   coder-1  queued   │
└────────────────────────────────────────────────┘

tmux 管理命令:

# 创建一个监控 session
tmux new-session -d -s factory -x 200 -y 50
 
# 为每个 Coder 创建 window
tmux new-window -t factory -n coder-1
tmux split-window -t factory:coder-1 -h  # 左右分屏
tmux send-keys -t factory:coder-1 'cd /repo/wt-auth' Enter
 
# 同步输入（commander 可以广播到所有 panel）
tmux set-window-option -t factory synchronize-panes on
 
# 监控面板（commander 专用）
tmux split-window -t factory -l 20 -d 'watch -n 5 factory status'

1.4 Web 端人类可观测性

实时状态面板

URL: http://localhost:7890/factory/dashboard

功能:

任务看板：Kanban 视图（TODO / IN PROGRESS / REVIEW / DONE）
Agent 状态：哪些在线、当前任务、耗时
Worktree 状态：分支、PR 地址、最后活动时间
Terminal 回放：每个 Coder 的命令历史（tmux capture）
代码变更：各 worktree 的 diff 预览

技术方案:

Commander 启动一个 FastAPI/Flask 本地服务
SSE（Server-Sent Events）推送实时更新
前端：简单的 HTML + JavaScript（不需要 SPA 框架）
数据来源：Commander 的内存状态 + tmux capture

API 设计:

GET  /api/tasks              # 任务列表
GET  /api/tasks/{id}         # 任务详情
GET  /api/agents             # Agent 状态
GET  /api/worktrees           # Worktree 列表
GET  /api/worktrees/{name}/diff  # Worktree diff
GET  /api/terminal/{agent}   # Agent 的终端回放（SSE）
POST /api/tasks              # 创建任务（人工干预入口）

人工介入机制

当 Coder Agent 遇到无法解决的困难时：

Coder → "需要人工介入" → Dashboard 告警 → 人类处理 → 继续

告警条件:

Coder 连续 3 轮未能完成任务
代码审查发现 CRITICAL 问题
Agent 失联超过 5 分钟

方向二：多 Agent 自由协同

2.1 架构总览

与"软件工厂"的"指挥官-执行者"模式不同，自由协同是对等网络：

┌──────────────────────────────────────────────┐
│            Hermes Agent Network              │
│                                              │
│  ┌────────┐    A2A     ┌────────┐          │
│  │ Agent  │◄──────────►│ Agent  │          │
│  │  Alice │    CLI     │  Bob   │          │
│  └────────┘            └────────┘          │
│       │                     │               │
│  delegate_task         delegate_task        │
│       │                     │               │
│       ▼                     ▼               │
│  ┌────────┐            ┌────────┐          │
│  │Subagent│            │Subagent│          │
│  │  (A1)  │            │  (B1)  │          │
│  └────────┘            └────────┘          │
└──────────────────────────────────────────────┘

两种通信模式:

模式	适用场景	机制
A2A（对等）	两个 Agent 需要协商/讨论/共享上下文	HTTP P2P，消息注入当前 session
delegate_task（主从）	主 Agent 发任务给子 Agent 执行	树形 spawn，结果汇总

2.2 协作工作流引擎

工作流定义（YAML）

name: api-migration
description: 将 Django REST API 迁移到 FastAPI
 
variables:
  repo: /home/user/project
  api_version: v2
 
steps:
  - id: analyze
    agent: analyzer
    prompt: "分析 {{repo}} 中 auth/orders/inventory 三个模块的接口依赖"
    parallel: false
 
  - id: migrate-auth
    agent: coder
    prompt: "迁移 {{repo}}/auth 模块到 FastAPI，保持接口兼容"
    depends_on: [analyze]
    worktree: wt-auth
 
  - id: migrate-orders
    agent: coder
    prompt: "迁移 {{repo}}/orders 模块到 FastAPI，参考 auth 模块的 pattern"
    depends_on: [analyze]
    worktree: wt-orders
 
  - id: migrate-inventory
    agent: coder
    prompt: "迁移 {{repo}}/inventory 模块"
    depends_on: [analyze]
    worktree: wt-inventory
 
  - id: integration-test
    agent: tester
    prompt: "对 {{repo}} 运行集成测试，验证三个模块的兼容性"
    depends_on: [migrate-auth, migrate-orders, migrate-inventory]
 
  - id: review
    agent: reviewer
    prompt: "代码审查，重点关注三个模块间的接口变化"
    depends_on: [integration-test]

工作流执行器

# 运行工作流
hermes workflow run api-migration.yaml
 
# 查看进度
hermes workflow status api-migration
 
# 暂停 / 恢复
hermes workflow pause api-migration
hermes workflow resume api-migration
 
# 人工介入
hermes workflow intervene api-migration --step migrate-auth

执行逻辑:

1. 解析 YAML，构建拓扑图
2. 找出入度为 0 的步骤，并行启动
3. 每个步骤完成后通知执行器
4. 执行器检查依赖，更新可执行步骤
5. 重复直到所有步骤完成
6. 生成汇总报告

2.3 Agent 间 CLI 通信

直接 CLI 消息

# 发送消息给指定 Agent（通过 A2A）
hermes send --to bob --message "帮我review这个PR: https://..."
 
# 广播消息给所有已知 Agent
hermes broadcast --message "新代码已合入，主分支已更新"
 
# 查看与其他 Agent 的对话历史
hermes conversation --with bob

对话式协作

# 启动一个多方会话
hermes group add alice
hermes group add bob
hermes group start --topic "讨论新的认证方案"
 
# 或者让 Agent 自动发起协作讨论
# Commander 发现架构问题 → A2A 咨询架构师 Agent → 讨论 → 结论注入任务

2.4 共享上下文与记忆

各 Agent 有独立的 Profile（记忆/技能/配置隔离），但可以共享上下文：

# 在工作流中共享文件上下文
hermes context share --file /repo/docs/api-spec.yaml --to coder,reviewer
 
# 共享的 project brief（所有 Agent 都能读到）
# 放在共享空间（而非单个 Profile 的 memory）
/shared/projects/{project-id}/
  brief.md          # 项目概述
  decisions/        # 架构决策记录（ADR）
  context/          # 共享技术上下文

共享记忆的更新权限:

# 只有 reviewer 可以更新 decisions/
decisions/:
  write: [reviewer, architect]
  read: [all]

核心子系统设计

3.1 Profile 管理系统

基于 Hermes 原生 Profiles，每个角色一个 Profile：

~/.hermes/profiles/
├── commander/      # 指挥官
├── coder-base/     # Coder 模板（克隆使用）
├── reviewer/       # 审查员
├── analyzer/       # 分析员
└── tester/         # 测试员

Profile 模板机制:

# 从模板创建新的 Coder
hermes profile clone coder-base coder-feature-auth
hermes profile clone coder-base coder-feature-api
 
# Profile 继承链
coder-base (模板)
  ├── coder-feature-auth (继承 + 追加 SOUL.md)
  └── coder-feature-api (继承 + 追加 SOUL.md)

3.2 任务分发系统

基于 delegate_task，但扩展为：

# 扩展的 delegate_task 参数
{
    "goal": "迁移 auth 模块到 FastAPI",
    "context": {
        "repo": "/repo",
        "branch": "feature/auth-fastapi",
        "acceptance": ["接口兼容", "测试通过", "无 regression"],
    },
    "role": "leaf",  # coder 不能进一步委托
    "toolsets": ["terminal", "file"],
    "worktree": "wt-auth",  # 分配 worktree
    "checkpoint_interval": 60,  # 每60秒报告进度
    "escalate_on": ["CRITICAL安全问题", "无法解决的依赖"],
}

任务状态机:

PENDING → ASSIGNED → RUNNING → CHECKPOINT → COMPLETED/FAILED/ESCALATED
                              ↓
                        HUMAN_INTERVENTION

3.3 A2A 通信协议

利用已有的 hermes-a2a 插件：

# Agent 注册到 A2A 网络
hermes a2a register --name commander --url http://localhost:8080
 
# Agent 发现其他 Agent
hermes a2a discover
 
# Agent 间发送任务（同步等待）
hermes a2a send --to reviewer --task "review PR #42" --timeout 300

A2A 消息类型:

intent	说明	期望行为
`action_request`	请对方执行动作	执行后回复结果
`review`	请对方审查	审查意见回复
`consultation`	请对方提供意见	建议回复
`notification`	通知事件	无需回复
`instruction`	下达指令	执行（用于 commander→coder）

3.4 观测与日志

集中日志

~/.hermes/factory/logs/
├── commander.log
├── coder-auth.log
├── coder-api.log
├── reviewer.log
└── audit.log          # 所有 agent 间通信记录

审计日志格式:

{
  "timestamp": "2026-04-29T10:30:00Z",
  "type": "a2a_message",
  "from": "commander",
  "to": "reviewer",
  "intent": "review",
  "content": "review PR #42",
  "response_time_ms": 45230,
  "status": "completed"
}

回调通知

# Commander 配置通知渠道
notifications:
  on_task_complete: ["feishu:ou_xxx", "local"]
  on_task_fail: ["feishu:ou_xxx", "telegram:@user"]
  on_human_needed: ["feishu:ou_xxx", "telegram:@user", "local"]

技术实现路线

Phase 1: 基础框架（1-2 周）

Commander Profile + SOUL.md
Coder Profile 模板 + Claude/Codex 集成
基础的 delegate_task 分发（单层，无 worktree）
基础任务状态追踪（SQLite）

Phase 2: 多任务并行（1 周）

Git worktree 生命周期管理
多 Coder 并行调度
tmux panel 管理命令
基础 Web dashboard（Flask + SSE）

Phase 3: 完整工作流（1-2 周）

YAML 工作流解析器
工作流执行引擎（含拓扑排序）
A2A 协议集成（自由协同场景）
人工介入告警机制

Phase 4: 生产可用（1 周）

Web dashboard 完善（Terminal 回放、Diff 预览）
审计日志 + 通知渠道
Profile 模板系统完善
文档 + 演示

与现有系统的关系

组件	关系
Hermes Agent	核心引擎，所有 Agent 都基于 Hermes
Agent Company OS	本 PRD 是 ACS 的多 Agent 能力扩展
MCO	MCO 的并行执行模式被本系统吸收；Session Daemon 概念借鉴
OpenClaw ClawSweeper	启发自：AI 解决 AI 产生的问题
蝈蝈的 Profiles 实践	直接采用：Profile 隔离 + 专业化分工

附录

A. 关键文件清单

agent-os-laohuang-self/
├── docs/
│   └── prd-multi-agent-cli.md    ← 本文档
├── src/
│   └── multi-agent-cli/          ← 核心实现
│       ├── commander/            # Commander Profile
│       ├── profiles/             # Profile 模板
│       ├── workflow/             # 工作流引擎
│       ├── web/                  # Dashboard
│       └── cli/                  # 新增 CLI 命令
└── tests/
    └── test_multi_agent.py

B. 参考资料

Hermes Agent Profiles 系统：/root/.hermes/hermes-agent/hermes_cli/profiles.py
delegate_task 机制：/root/.hermes/hermes-agent/tools/delegate_tool.py
A2A 协议：/root/hermes-a2a/plugin/
MCO 多 Agent 编排：/tmp/mco/runtime/orchestrator.py
蝈蝈 Profiles 实践：CSDN 文章（2026-04-19）