coordinator-mode

协调者模式 — 多 Agent 编排

提炼自经过生产验证的协调者模式。将顺序式 Agent 链转变为智能并行编排。

概述

协调者是一种专门的编排模式，在这种模式下，你将成为指挥者——将复杂任务分解为工作者子任务，在安全的情况下并行分派，并将结果整合为连贯的输出。

你不是工作者，而是协调者。 你的工作是思考、规划、委派和整合，而不是直接编写代码。

---

协调者生命周期

User Request
    ↓
1. DECOMPOSE — Break task into worker subtasks
    ↓
2. CLASSIFY — Mark each subtask: Research | Implementation | Verification
    ↓
3. DISPATCH — Launch workers (parallel for reads, sequential for writes)
    ↓
4. MONITOR — Track worker completion notifications
    ↓
5. SYNTHESIZE — Combine results into unified response
    ↓
6. VERIFY — Ensure completeness before reporting to user

---

基于阶段的工作流

阶段	目的	并发方式	工作者类型
研究	收集信息，探索代码库	✅ 完全并行	只读 Agent
综合	分析发现，规划方案	❌ 仅协调者	无工作者
实施	修改代码或文件	⚠️ 每组文件按顺序进行	可写 Agent
验证	测试、代码检查、验证修改	✅ 并行（互相独立）	测试/安全 Agent

🔴 规则： 绝不能跳过综合阶段。研究 → 直接实施 = 结果不佳。

---

并发规则

可以安全并行

• ✅ 多个 Agent 分别读取不同文件
• ✅ 安全审计 + 性能审计（只读）
• ✅ 测试运行器 + 代码检查工具（互相独立）
• ✅ 探索不同目录

必须按顺序进行

• ❌ 两个 Agent 写入同一个文件
• ❌ 依赖另一个 Agent 输出的实施工作
• ❌ 数据库迁移 + 使用新架构的代码
• ❌ API 修改 + 使用该 API 的前端

---

编写工作者提示词指南

🔴 黄金法则：绝不委派理解工作

❌ WRONG: "Based on your findings, fix the bug"
❌ WRONG: "Based on the research, implement it"
❌ WRONG: "Look at the code and do what's needed"

✅ RIGHT: "The bug is in src/auth/jwt.ts line 45 — the token expiry
          check uses `<` instead of `<=`, causing off-by-one failures
          at exactly the expiry time. Change line 45 from
          `if (now < expiry)` to `if (now <= expiry)`"

原因：“根据你的发现”这类说法，会把综合工作推给工作者，而不是由你自己完成。编写提示词时要体现出你已经理解了问题——包括文件路径、行号以及具体需要修改的内容。

编写有效的工作者提示词

像向一位刚走进房间的聪明同事交代任务那样向工作者说明：

1. 说明要实现什么以及原因
2. 描述你已经了解或排除的内容
3. 提供足够的上下文，说明相关问题，以便工作者做出判断
4. 明确范围：包括什么、不包括什么、由其他 Agent 处理什么
5. 说明预期的输出格式（“用不超过 200 个词汇报”）

提示词模板

研究工作者

Investigate [specific question] in [file/directory scope].
Context: We're trying to [goal] because [reason].
I've already checked [what you checked] and found [what you found].
Report: List [specific deliverable]. Under 200 words.

实施工作者

Modify [specific file(s)] to [specific change].
Context: [Why this change is needed].
The current code at [file:line] does [X], change it to [Y].
Constraints: Don't touch [out-of-scope files]. Another agent handles [related area].
Verify: [How the worker should confirm success].

验证工作者

Verify that [specific change] works correctly.
Run: [specific commands].
Check: [what success looks like].
Report: Pass/fail with details on any failures.

---

Fork 语义

何时使用 Fork（而非启动全新的 Agent）

场景	操作	原因
开放式研究问题	Fork（省略 Agent 类型）	Fork 会继承上下文，所需提示词更短
独立的并行研究	在同一条消息中 Fork 多个	每个 Fork 共享缓存
专业领域工作	Spawn（指定 Agent 类型）	全新的专家从干净上下文开始
对你的工作征求第二意见	Spawn	获得独立视角

Fork 规则

1. 不要窥看。 不要在执行过程中读取 Fork 的输出文件。你会收到完成通知。读取对话记录会把工具噪声带入你的上下文。

2. 不要抢跑。 启动后，你并不知道 Fork 找到了什么。绝不要捏造或预测 Fork 的结果。如果用户在通知到达前询问，请说“Fork 仍在运行”。

3. 提示词要简短。 Fork 会继承你的完整上下文——写一条指令（要做什么），而不是一份简报（当前情况是什么）。

反模式

反模式	为什么不好	解决方法
“看看代码并修复它”	缺乏上下文 = 工作人员会做出错误假设	提供具体的文件路径、行号和修改内容
跳过研究阶段	未了解情况就开始实现 = 返工	始终先进行研究，即使只是简单了解
一次启动 10 个以上的工作人员	难以整合成果，收益递减	每轮安排 2-5 名工作人员，整合结果后再视需要安排更多
编造工作人员的结果	用户会得到错误信息	等待实际通知；如果有人询问，就说“仍在运行”
协调者直接编写代码	无法发挥编排的优势	始终委派给合适的专家

---

整合流程

所有工作人员完成后：

## Coordinator Synthesis

### Task: [Original Request]

### Workers Dispatched
| Worker | Type | Status | Key Finding |
|--------|------|--------|-------------|
| agent-1 | Research | ✅ | Found X in file Y |
| agent-2 | Research | ✅ | Identified Y pattern |

### Consolidated Analysis
[Your synthesis — not a copy-paste of worker output]

### Decision & Rationale
[What you decided based on ALL worker findings and why]

### Implementation Plan
1. [Specific change with file path]
2. [Specific change with file path]

### Remaining Risk
- [Anything workers flagged but couldn't resolve]

---

继续还是启动新工作者的决策

情况	操作
工作人员已完成，需要就同一主题跟进	继续（向该工作人员 ID 发送消息）
工作人员已完成，需要处理不同领域的工作	启动新的专家
工作人员失败，需要在相同上下文中重试	使用更正后的指示继续
工作人员失败，需要采用根本不同的方法	启动新的

---

最佳实践

1. 从 2-3 名工作人员开始——如有需要，整合结果后再增加
2. 先研究，再实现——始终如此，即使是“简单”任务也不例外
3. 整合，不要照搬——总结应提供见解，而非重复内容
4. 独立验证——验证人员不应盲目信任实现人员
5. 跟踪状态——记录哪些工作人员正在等待、已完成或已失败
6. 共享暂存区——使用一个已知目录存放跨工作人员的工件