/multi-agent

name: multi-agent
description: Multi-Agent Orchestration - 蚁群仿生设计，定义Agent角色、生命周期、信息素通信、任务分解、冲突解决。当需要多Agent并行协作时路由到此。
license: MIT
user-invocable: false
disable-model-invocation: false

🕸 天罗秘典 · 多 Agent 协同（蚁群仿生版）

> 参考蚁群仿生架构：侦察→工作→审查→修复→完成，信息素间接通信，自适应并发。

---

蚁群生命周期

所有多 Agent 协同任务遵循统一生命周期：

目标 → 侦察(Scout) → 任务池 → 工蚁(Worker)并行执行 → 兵蚁(Soldier)审查 → 修复(如需) → 完成
         │                           │
         │  信息素衰减（过时信息自动失效）  │  子任务自动产生
         └───────────────────────────┘

阶段定义

| 阶段 | 角色 | 动作 | 产出 | |------|------|------|------| | 🔍 侦察 | Scout | 探索代码库，标记关键文件和依赖 | 任务池 + 依赖图 | | ⚒️ 工作 | Worker | 并行执行任务，可产生子任务 | 代码变更 + 进度信息素 | | 🛡️ 审查 | Soldier | 审查所有变更，发现问题 | 修复任务 / 通过 | | 🔧 修复 | Worker | 执行审查产生的修复任务 | 修复后的代码 | | ✅ 完成 | Lead | 汇总报告，统一 commit | 最终交付 |

---

Codex 原生协同协议（强化）

在 Codex CLI 中，TeamCreate/Task 抽象统一映射到以下原生动作：

| 协同意图 | Codex 动作 | 约束 | |---------|------------|------| | 创建团队/子任务 | `spawn_agent` | 明确角色、文件所有权、完成定义 | | 下发任务/追问 | `send_input` | 单条消息只包含一个目标动作 | | 等待完成 | `wait` | 优先长等待，避免忙轮询 | | 长耗时命令 | `awaiter` agent | 测试/构建/监控必须用 awaiter | | 代码探索 | `explorer` agent | 探索结果视为权威，不重复检索 | | 执行改动 | `worker` agent | 明确“只改分配文件” | | 收尾回收 | `close_agent` | 任务结束必须关闭子 Agent |

执行顺序（不可跳步）

1. 拆解任务 + 文件锁定矩阵
2. spawn explorer/worker/awaiter
3. 并行执行 + wait 收敛
4. reviewer 审查 + 必要修复
5. 汇总结果 + close_agent 全量回收

---

何时启用多 Agent

TeamCreate vs Task(subagent) 决策树

收到任务 → 评估规模
  │
  ├─ 涉及 ≥3 个独立文件/模块？ → TeamCreate
  ├─ 需要 ≥2 个并行工作流？   → TeamCreate
  ├─ 总步骤 >10 步？          → TeamCreate
  ├─ 用户明确要求并行/团队？   → TeamCreate
  │
  ├─ 单一探索/搜索任务？       → explorer agent
  ├─ 单文件独立操作？          → worker agent
  └─ 简单查询/单步操作？       → 直接执行

**铁律**：当犹豫时，优先 TeamCreate。多 Agent 并行效率远高于串行 subagent。

满足**任意 1 条**即启用 TeamCreate：

| 条件 | 说明 | 示例 | |------|------|------| | 多文件独立变更 | ≥3 个无交叉依赖的文件 | 6 个新秘典各自独立 | | 可并行子任务 | ≥2 个无数据依赖的工作流 | 前端+后端+文档 | | 复杂度高 | 单 Agent 需 >10 步 | 全栈重构 | | 时间紧迫 | 劫钟催命，需加速 | 紧急修复多服务 |

---

角色体系（蚁群映射）

| 角色 | 蚁群映射 | 道语 | 职责 | 工具权限 | 模型建议 | |------|----------|------|------|----------|----------| | 主修 (Lead) | 蚁后 Queen | 天罗主修 | 任务分解、调度、汇总 | `spawn_agent/send_input/wait/close_agent` | 当前模型 | | 斥候 (Scout) | 侦察蚁 Scout | 天罗斥候 | 只读探索，标记关键文件 | `explorer` + Read/Grep/Glob（只读） | haiku（快速低成本） | | 道侣 (Worker) | 工蚁 Worker | 天罗道侣 | 执行任务，可产生子任务 | `worker` + Read/Write/Edit/Bash | sonnet/当前模型 | | 护法 (Soldier) | 兵蚁 Soldier | 天罗护法 | 审查质量，发现问题 | `worker`(审查模式) + Read/Grep/Glob（只读） | sonnet | | 走卒 (Drone) | 无人蚁 Drone | 天罗走卒 | 简单 bash 命令，零 LLM 成本 | Bash（仅此一个） | 无（execSync） |

角色使用时机

需要了解代码库结构？ → 派 Scout（agent_type=explorer）
需要修改代码？       → 派 Worker（agent_type=worker）
需要审查变更？       → 派 Soldier（agent_type=worker，审查提示词）
需要长耗时命令？      → 派 awaiter（agent_type=awaiter）
需要短命令？         → 直接 Bash（Drone 等价）

---

企业级角色扩展（`/ccg:team` 专用）

`/ccg:team` 命令在蚁群基础角色之上，增加 3 个大厂级专业角色，对应 Agent Teams 真实 teammates：

| 角色 | Agent 名 | 道语 | 职责 | 工具权限 | 模型 | |------|----------|------|------|----------|------| | 🏗 架构师 (Architect) | `team-architect` | 天罗军师 | 代码库扫描、架构蓝图、文件分配矩阵 | Read/Glob/Grep（只读） | Sonnet | | 🧪 QA 工程师 (QA) | `team-qa` | 天罗验毒 | 写测试、跑测试、lint、typecheck | Read/Write/Edit/Bash/Glob/Grep | Sonnet | | 🔬 审查员 (Reviewer) | `team-reviewer` | 天罗护法 | 综合 Codex/Gemini 审查、分级判决 | Read/Glob/Grep（只读） | Sonnet |

8 阶段流水线

Phase 0: PRE-FLIGHT    → 环境检测 + 参数解析
Phase 1: REQUIREMENT   → Lead 需求增强 → mini-PRD
Phase 2: ARCHITECTURE  → Codex∥Gemini 外援 + Architect teammate 出蓝图
Phase 3: PLANNING      → Lead 拆任务 → 零决策并行计划
Phase 4: DEVELOPMENT   → Dev×N teammates 并行编码（文件隔离）
Phase 5: TESTING       → QA teammate 写测试 + 跑全量验证
Phase 6: REVIEW        → Codex∥Gemini 外援 + Reviewer teammate 综合审查
Phase 7: FIX           → Dev teammate(s) 修复 Critical（最多 2 轮）
Phase 8: INTEGRATION   → Lead 全量验证 + 报告 + 清理

角色生命周期

TeamCreate ─── Phase 2: spawn Architect → shutdown
            ├─ Phase 4: spawn Dev×N → shutdown
            ├─ Phase 5: spawn QA → shutdown
            ├─ Phase 6: spawn Reviewer → shutdown
            ├─ Phase 7: spawn Fix-Dev(s) → shutdown
            └─ Phase 8: TeamDelete

**推荐入口**：`/ccg:team <需求描述>` — 一键跑完 8 阶段。 **分步入口**（兼容）：`/ccg:team-research` → `/ccg:team-plan` → `/ccg:team-exec` → `/ccg:team-review`

---

信息素系统（Stigmergy）

蚁群通过信息素间接通信，而非直接对话。在 Claude Code 中，用 **TaskCreate metadata** 模拟信息素：

信息素类型

| 类型 | 释放者 | 含义 | 用途 | |------|--------|------|------| | `discovery` | Scout | 发现的代码结构、关键文件 | 帮助 Worker 快速定位 | | `progress` | Worker | 完成的变更、修改的文件 | 帮助后续 Worker 避免冲突 | | `warning` | Soldier | 质量问题、冲突风险 | 降低相关任务优先级 | | `completion` | Worker | 任务完成标记 | 强化成功路径 | | `repellent` | 任意 | 失败路径标记（负信息素） | 阻止后续 Agent 走同一条死路 |

实现方式

# Scout 完成后，在 TaskUpdate 的 metadata 中记录发现
TaskUpdate(taskId, metadata: {
  pheromone: "discovery",
  files: ["src/auth.ts", "src/middleware.ts"],
  content: "认证模块依赖 middleware，需先改 middleware"
})

# Worker 失败后，释放负信息素
TaskUpdate(taskId, metadata: {
  pheromone: "repellent",
  files: ["src/legacy.ts"],
  content: "此文件有循环依赖，直接修改会崩溃"
})

信息素决策规则

| 规则 | 说明 | |------|------| | **正强化** | discovery/completion 信息素的文件 → 优先分配 | | **负惩罚** | warning 信息素的文件 → 降低优先级 | | **强负惩罚** | repellent 信息素的文件 → 避免分配，需主修评估 | | **ε-greedy** | 90% 按信息素强度选任务，10% 随机选 → 避免全挤同一条路 |

---

自适应并发

根据任务数量和复杂度动态调整 Agent 数量：

任务数 1-2   → 1-2 个 Worker（直接 Task subagent）
任务数 3-5   → TeamCreate, 2-3 个 Worker
任务数 6-10  → TeamCreate, 3-5 个 Worker
任务数 >10   → TeamCreate, 5-7 个 Worker（上限）

过载保护

| 信号 | 动作 | |------|------| | Agent 连续失败 ≥2 次 | 减少并发，释放 repellent 信息素 | | 429 限流 | 暂停派发，等待恢复后继续 | | 所有任务完成 | 立即进入审查阶段 | | 子任务膨胀 >30 | 停止产生新子任务，先完成现有 |

---

TeamCreate 最佳实践

命名规范

team_name: "{项目}-{任务类型}"  # 如 "abyss-skill-expansion"
agent_type: "{角色}"            # 如 "lead", "developer", "reviewer"
description: "一句话说明团队目标"

---

任务分解策略

按文件拆分（首选）

每个 Agent 负责独立的文件集合，零交叉：

Agent-A: [file1.md, file2.md]  — 互不干涉
Agent-B: [file3.md, file4.md]  — 互不干涉
Agent-C: [file5.md]            — 互不干涉

按模块拆分

每个 Agent 负责一个功能模块：

Agent-前端: src