🕸 天罗秘典 · 多 Agent 协同

何时启用多 Agent

TeamCreate vs Task(subagent) 决策树

code

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

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

满足任意 1 条即启用 TeamCreate：

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

TeamCreate 最佳实践

命名规范

yaml

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

角色定义

角色	道语	职责	工具权限
主修 (Lead)	天罗主修	任务分解、进度追踪、结果汇总	TaskCreate/TaskUpdate/SendMessage
道侣 (Worker)	天罗道侣	执行具体子任务、报告进度	Read/Write/Edit/Bash/SendMessage
护法 (Reviewer)	天罗护法	代码审查、质量校验、冲突检测	Read/Grep/Glob/SendMessage

任务分解策略

按文件拆分（首选）

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

code

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

按模块拆分

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

code

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

按流水线拆分

串行依赖时，前一个 Agent 的输出是后一个的输入：

code

Agent-生成 → Agent-校验 → Agent-集成

并行 vs 串行决策

code

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

依赖矩阵示例

	Task-A	Task-B	Task-C
Task-A	-	无依赖	无依赖
Task-B	无依赖	-	B→C
Task-C	无依赖	B→C	-

结论：A 与 B 并行，C 等 B 完成后执行。

Agent 角色模板

主修（Lead）启动模板

code

你是天罗主修，负责协调多 Agent 协同任务。

职责：
1. 将大任务分解为独立子任务
2. 为每个道侣分配文件集合（不可重叠）
3. 追踪进度，处理阻塞
4. 汇总结果，统一验证

铁律：
- 每个文件只能分配给一个 Agent
- 独立任务必须并行启动
- 收到所有道侣完成消息后才能进入汇总

道侣（Worker）启动模板

code

你是天罗道侣，负责执行分配的子任务。

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

报告格式：
- 完成：列出创建/修改的文件 + 行数
- 阻塞：说明原因 + 建议方案

通信协议

SendMessage 规范

类型	用途	格式
message	点对点通信	`{type: "message", recipient: "agent-name", content: "...", summary: "5字摘要"}`
broadcast	全体通知	`{type: "broadcast", content: "...", summary: "5字摘要"}`
shutdown_request	请求关闭	`{type: "shutdown_request", recipient: "agent-name", content: "原因"}`

通信时机

事件	发送者	接收者	内容
任务分配	主修	道侣	文件列表 + 要求
进度更新	道侣	主修	完成百分比 + 当前状态
任务完成	道侣	主修	文件清单 + 验证结果
遇阻报告	道侣	主修	阻塞原因 + 建议
汇总指令	主修	全体	broadcast 进入汇总阶段

文件锁定与冲突避免

黄金规则

code

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

锁定策略

•分配时锁定 — 主修分配任务时明确文件归属
•声明式锁定 — 道侣开始前声明要操作的文件
•冲突检测 — 主修检查文件分配无重叠后才启动

冲突解决

冲突类型	解决方案
两个 Agent 需写同一文件	串行执行，先完成的先写
写入内容矛盾	主修裁决，以业务逻辑为准
依赖文件未就绪	阻塞等待，主修协调优先级

状态共享

TaskCreate/TaskUpdate 规范

code

TaskCreate: 主修创建总任务 + 子任务
TaskUpdate: 道侣更新子任务状态
TaskList:   主修查看全局进度

状态流转

code

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

错误处理与容错

单 Agent 失败

code

道侣失败 → 报告主修 → 主修评估影响
  ├─ 可重试 → 同一道侣重试（≤2次）
  ├─ 需换策略 → 主修调整方案后重新分配
  └─ 不可恢复 → 主修接管该子任务

通信超时

code

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

降级策略

code

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

结果汇总模式

汇总流程

code

1. 收集所有道侣完成报告
2. 验证文件完整性（所有预期文件存在）
3. 验证内容一致性（交叉引用正确）
4. 统一 git add + commit
5. 输出汇总报告

统一 Commit 规范

bash

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

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

汇总报告模板

code

🕸 天罗收阵！

【阵法】{团队名称}
【阵员】{Agent数量} 道侣
【战果】
  - Agent-A: {文件数} 文件，{行数} 行
  - Agent-B: {文件数} 文件，{行数} 行
【验证】全部文件存在 ✓ | 交叉引用正确 ✓
【耗时】{总时间}