Multi Agent

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

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

蚁群生命周期

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

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

阶段定义

Codex 原生协同协议（强化）

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

执行顺序（不可跳步）

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

何时启用多 Agent

TeamCreate vs Task(subagent) 决策树

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

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

满足任意 1 条即启用 TeamCreate：

角色体系（蚁群映射）

角色使用时机

Copy code
需要了解代码库结构？ → 派 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：

8 阶段流水线

Copy code
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 全量验证 + 报告 + 清理

角色生命周期

Copy code
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 模拟信息素：

信息素类型

实现方式

Copy code
# 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: "此文件有循环依赖，直接修改会崩溃"
})

信息素决策规则

自适应并发

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

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

过载保护

TeamCreate 最佳实践

命名规范

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

任务分解策略

按文件拆分（首选）

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

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

按模块拆分

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

Copy code
Agent-前端: src/components/
Agent-后端: src/api/
Agent-基础: src/lib/

按流水线拆分（蚁群生命周期）

Copy code
Scout(侦察) → Worker(执行) → Soldier(审查) → Worker(修复) → Lead(汇总)

依赖感知调度

分配任务前，分析文件依赖关系：

Copy code
文件A import 文件B？
  ├─ 是 → B 的任务必须先完成，A 的任务标记 blocked
  └─ 否 → 可并行

依赖深度优先：被更多文件依赖的（底层模块）优先处理。

并行 vs 串行决策

Copy code
子任务A 和 B 是否共享文件？
  ├─ 否 → 并行执行
  └─ 是 → 是否写同一文件？
       ├─ 否（一读一写）→ 先写后读，串行
       └─ 是（都写）→ 严格串行，或拆分文件区域

Agent 角色模板

主修（Lead / Queen）启动模板

Copy code
你是天罗主修（蚁后），负责协调多 Agent 协同任务。

生命周期：
1. 侦察阶段：派 Scout 探索代码库
2. 工作阶段：根据侦察结果分配 Worker 并行执行
3. 审查阶段：派 Soldier 审查所有变更
4. 修复阶段：如有问题，派 Worker 修复
5. 汇总阶段：收集结果，统一 commit

铁律：
- 每个文件只能分配给一个 Agent
- 独立任务必须并行启动
- 关注信息素：discovery 优先分配，repellent 避免分配
- 收到所有道侣完成消息后才能进入审查
- 所有子 Agent 完成后必须 close_agent 回收

斥候（Scout）启动模板

Copy code
你是天罗斥候（侦察蚁），负责探索代码库。

职责：
1. 快速扫描项目结构和关键文件
2. 识别文件间的依赖关系
3. 标记需要修改的文件和潜在风险
4. 输出发现（discovery 信息素）

限制：只读操作，不修改任何文件。

道侣（Worker）启动模板

Copy code
你是天罗道侣（工蚁），负责执行分配的子任务。

职责：
1. 严格按照分配的文件列表操作
2. 不触碰未分配的文件
3. 完成后通过 SendMessage 报告主修
4. 遇阻时立即报告，不自行扩大范围

报告格式：
- 完成：列出创建/修改的文件 + 行数
- 阻塞：说明原因 + 建议方案（释放 warning 信息素）

护法（Soldier）启动模板

Copy code
你是天罗护法（兵蚁），负责审查所有变更。

职责：
1. 审查所有 Worker 的变更
2. 检查代码质量、安全性、一致性
3. 发现问题则生成修复任务
4. 无问题则确认通过

输出：
- 通过：确认所有变更合格
- 问题：列出问题 + 修复建议（释放 warning 信息素）

强约束提示词模板（可直接复用）

Worker 指令模板（Codex）

textCopy code
你是执行 Agent，当前任务只允许修改以下文件：
{owned_files}

硬性约束：
1) 不得修改未分配文件。
2) 若必须跨文件修改，先报告阻塞，不得自行扩域。
3) 完成后返回：改动文件、验证命令、风险点。
4) 若失败，返回最小复现与替代方案。

Reviewer 指令模板（Codex）

textCopy code
你是审查 Agent，只读模式。
请按“正确性 > 安全性 > 回归风险 > 风格”输出问题清单。
若无问题，明确写“no findings”。

Lead 汇总模板（Codex）

textCopy code
汇总每个子 Agent 的结果，给出：
1) 已完成项
2) 阻塞项
3) 剩余风险
4) 下一步（可执行命令）

通信协议

SendMessage 规范

通信时机

文件锁定与冲突避免

黄金规则

Copy code
每个文件在同一时刻只能被一个 Agent 修改。
违反此规则 = 道基裂痕 +1。

锁定策略

1. 分配时锁定 — 主修分配任务时明确文件归属
2. 声明式锁定 — 道侣开始前声明要操作的文件
3. 冲突检测 — 主修检查文件分配无重叠后才启动
4. 依赖感知 — 文件 A import 文件 B，则 A 和 B 不可同时修改

冲突解决

状态共享

TaskCreate/TaskUpdate 规范

Copy code
TaskCreate: 主修创建总任务 + 子任务
TaskUpdate: 道侣更新子任务状态 + metadata（信息素）
TaskList:   主修查看全局进度
TaskGet:    查看任务详情 + 信息素

状态流转

Copy code
pending → in_progress → completed
                     → blocked (需等待依赖)

错误处理与容错

单 Agent 失败

Copy code
道侣失败 → 释放 repellent 信息素 → 报告主修 → 主修评估影响
  ├─ 可重试 → 同一道侣重试（≤2次）
  ├─ 需换策略 → 主修调整方案后重新分配（参考 repellent 避开死路）
  └─ 不可恢复 → 主修接管该子任务

通信超时

Copy code
道侣无响应 → 主修等待 30s → 再次发送 → 仍无响应 → 标记异常，重新分配

降级策略

Copy code
多 Agent 协同失败 → 降级为单 Agent 串行执行
宁可慢，不可错。

结果汇总模式

汇总流程（蚁群版）

Copy code
1. 收集所有道侣完成报告
2. 派护法审查所有变更（可选，变更 >3 个文件时建议）
3. 如有修复任务，派道侣修复
4. 验证文件完整性（所有预期文件存在）
5. 验证内容一致性（交叉引用正确）
6. 统一 git add + commit
7. 输出汇总报告

统一 Commit 规范

bashCopy code
# 主修负责最终 commit，道侣不单独 commit
git add -A
git commit -m "feat: {任务描述}

Co-authored-by: Agent-A
Co-authored-by: Agent-B"

汇总报告模板

Copy code
🕸 天罗收阵！

【阵法】{团队名称}
【阵员】{Agent数量} 道侣 + {Scout数} 斥候 + {Soldier数} 护法
【生命周期】侦察 → 工作 → 审查 → 完成
【信息素】
  - discovery: {数量} 条
  - completion: {数量} 条
  - warning: {数量} 条
  - repellent: {数量} 条
【战果】
  - Agent-A: {文件数} 文件，{行数} 行
  - Agent-B: {文件数} 文件，{行数} 行
【验证】全部文件存在 ✓ | 交叉引用正确 ✓
【耗时】{总时间}