team-solve

团队协作解决问题

通过并行研究调查并解决一个或多个问题，然后按顺序实施。

适用场景

• 需要处理多个不同问题或主题的任务
• 适合同时研究多个方面的代码库变更
• 可分解为相互独立的调查方向的工作
• 希望在进行更改前系统地收集证据的情况

---

说明

你是协调“先调查、后解决”工作流的团队负责人。

协调协议

队友之间的消息是异步的——现在发送的消息，可能要等收件人完成当前工作后才能读到。你不能依赖消息的送达时间来协调。相反，任务状态是共享状态，能让每个 Agent 了解当前进度。

任务状态作为位置标记

队友收到消息时，应通过查看任务状态来确定消息在对话中的位置，而不是假设消息是“刚刚”发出的。

状态	设置者	含义
pending	负责人	尚未开始，等待分配
in_progress	队友	正在处理，或已完成并暂停等待负责人确认
completed	仅限负责人	负责人已阅读队友的报告——这就代表已确认

由负责人将任务标记为 completed，而不是队友。 队友看到任务标记为 completed 时，就知道负责人已处理其报告，此后收到的任何新消息都是最新指令。

队友协议

在每位队友的启动提示词中都包含以下规则：

1. 开始工作时，将任务标记为 in_progress
2. 使用 TaskGet 读取任务——任务描述包含所需的一切内容（实施细节、此前各方向的摘要等）。不要搜索文件系统或其他 Agent 的文件来查找这些内容。
3. 如果任务描述缺少必要内容（例如，实施任务没有详细说明），立即告知负责人并暂停。不要自行猜测。
4. 完成后，通过 SendMessage 发送报告，然后暂停——停止所有工作，不要查看 TaskList 或领取新任务，只需等待。
5. 对收到的任何消息采取行动前，通过 TaskGet 检查任务状态：
   • 仍为 in_progress → 负责人尚未确认你的报告。此消息可能早于你的报告。请回复当前状态，不要重新执行任务。
   • 为 completed → 负责人已处理你的报告。如果消息分配了新任务，则该消息包含最新指令；按指示继续。
6. 发送报告前，等待所有已启动的子 Agent 完成。不要留下仍在后台运行的工作。

负责人协议

1. 阅读队友的报告后，将其任务标记为 completed（表示已确认）
2. 发送新指令前，确保前一个任务已标记为 completed，并已创建和分配新任务
3. 通过 TaskList 确认阶段是否完成——检查所有相关任务是否处于预期状态，不要只凭记忆跟踪消息
4. 在不同实施方向之间切换时，运行 git status，确认工作树干净后再继续

阶段 1：问题拆解

1. 解析用户输入，识别不同的问题或主题
2. 如果问题含糊或信息不足，先提出澄清问题再继续
3. 将相关问题分组为 2–5 个调查方向（每个方向由一位队友负责）
4. 向用户说明拆解结果：
   • 列出每个方向及其负责的问题
   • 为每位队友取一个能体现职责的名称（例如，filter-investigator、output-researcher）
   • 询问：“我将并行启动 N 位调查员。是否继续？”

阶段 2：并行调查

调查工作并行进行。

1. 使用 TeamCreate 创建一个团队
2. 使用 TaskCreate 为每条调查线创建任务
3. 使用带有 team_name 的 Task，为每条调查线启动一名 general-purpose 队友
   • 每位队友的提示词必须包含：
     • 要调查的具体问题
     • 仅进行研究，不要做任何更改的指示
     • 上文协调协议中的队友协议（逐字复制到提示词中）
     • 下方的子代理指导（复制到提示词中）
     • 使用下方报告格式通过 SendMessage 汇报调查结果的指示
   • 并行启动所有调查人员——不要等一位调查人员完成后再启动下一位
4. 调查人员汇报后，不要将其关闭——他们会在阶段 4 继续保留上下文

调查人员的子代理指导

在每位调查人员的提示词中加入以下内容：

使用子代理（Task 工具）来保持上下文聚焦。 针对以下事项启动子代理：

• 探索特定文件、模块或子系统
• 搜索 Git 历史、日志或大型代码库
• 任何可能没有结果的研究分支

每个子代理都应汇报：

1. 相关发现——对调查有帮助的发现
2. 误导线索（1-2 句）——看似相关但实际上无关的内容，以及原因。尽早指出这些内容可以避免重复探索死胡同。

即使主要发现已经明确，也要汇报误导线索——这可以避免其他 Agent 重复探索相同的死胡同。

收到子代理的报告后，决定是否：

• 直接使用其发现——摘要已提供足够信息以继续推进
• 亲自深入调查——如果子代理发现了有潜力的内容，而你希望在得出结论前亲自全面了解该领域。示例：证据相互矛盾，需要直接检查；对子代理的评估信心不足；或涉及复杂状态/流程，需要亲自了解。

选择子代理类型时，对于开放式代码库搜索，优先选择只读或专注探索的类型；对于需要更深入工具访问权限的定向分析，则选择功能完备的类型。

调查人员报告格式

每位调查人员应按以下格式组织报告：

## Track: {description}

### Findings
- {what was discovered, root causes, relevant code paths}

### Proposed Approach
- {what to change, which files, how}

### Risks & Edge Cases
- {what could go wrong with this approach}
- {what adjacent code/features could be affected}
- {what happens if data is unexpected or flow is interrupted}

### Red Herrings
- {things explored that weren't relevant, and why}

### Confidence: {high/medium/low}
{brief justification}

### Dependencies
- {does this approach depend on or conflict with other tracks?}

阶段 3：讨论检查点

1. 调查人员陆续汇报时，将每项调查任务标记为 completed（确认收到报告），并向用户简要更新进度
2. TaskList 中的所有调查任务均显示为 completed 后，综合调查结果：
   • 每条调查线的关键发现
   • 建议的方案及其信心水平
   • 各调查线之间的任何冲突或依赖关系
   • 连带影响——评估所有调查线的影响：
     • “对……会有什么影响？”——文档、相邻功能、API 使用方、共享状态、缓存
     • “如果……会发生什么？”——意外数据、流程中断、并发访问、回滚
   • 建议的实施顺序（先处理依赖项，再处理风险最高的事项，最后处理其余事项）
3. 如果调查发现问题与预期不同，请明确说明——建议调整调查线，而不是强行沿用原计划
4. 询问用户：“准备好开始实施，还是想调整方案？”

阶段 4：串行实施

实施一次只处理一个轨道。这样可以避免：

• 在同一个提交中混入无关工作
• 因并发变更尚在进行而导致构建／测试失败，令人困惑
• 队友修改共享代码时发生文件冲突

1. 对于每个轨道（按与用户商定的顺序），遵循负责人协议： a. 为此轨道创建一个实施任务。**在任务说明中包含：**要完成的工作、以下子 Agent 指引，以及（对于后续轨道）上一个轨道的「变更内容」摘要 b. 将任务分配给最初的调查员，并给他们发送消息，说明实施任务已就绪——任务说明中包含他们所需的一切 c. 等待——调查员会开展工作、发送报告，然后暂停 d. 阅读报告。将实施任务标记为 completed（表示你已确认）。 e. 运行 git status，确认工作树干净——没有未提交的变更，也没有遗留文件 f. 运行相关测试／检查，快速验证是否正常 g. 只有完成以上步骤后，才继续下一个轨道
2. 并行例外：只有当轨道之间完全没有文件重叠，且代码库没有可能导致并发失败交错、令人困惑的共享构建／测试流水线时，才考虑并行实施。如果你认为并行是安全的，请说明原因并询问用户。
3. 部分失败：
   • 如果调查员报告信心不足或未发现可采取的措施，请在实施前与用户讨论——可选择放弃该轨道、将其合并到另一轨道，或进一步调查
   • 如果实施在轨道进行中失败，请停止并与用户讨论是回滚还是调整方案，然后再继续下一个轨道

实施子 Agent 指引

发送实施指令时，请包含以下内容：

使用子 Agent，让你的主要上下文专注于实施逻辑。 针对以下工作启动子 Agent：

• 重复性编辑——在多个文件中进行类似修改（更新导入、在测试文件中重命名、将某种模式应用到多个模块）
• 影响分析——在更改函数签名之前查找所有调用方，检查 API 的所有使用方
• 探索性阅读——检查模块的假设是否会因你的更改而失效，验证相邻代码中的边缘情况
• 后台测试运行——在你继续处理下一项更改时运行测试

**重要：**在报告轨道已完成之前，等待所有子 Agent 完成。报告完成时，不要遗留仍在运行的后台任务。

阶段 5：验证

1. 启动验证员之前，通过 TaskList 确认所有实施任务均为 completed，并运行 git status 确认工作树干净
2. 启动一位全新的 general-purpose 队友，命名为 validator。验证员的启动提示必须包含：协调协议中的队友协议（逐字照录）、阶段 1 中的原始问题、阶段 3 中商定的实施方案、调查员指出的风险区域，以及所有变更文件的列表（或 git diff 范围）。优先将 diff 直接嵌入启动提示；如果内容过长，则使用 mktemp 写入临时文件（例如 mktemp /tmp/team-solve-diff.XXXXXX），并让验证员从该路径读取。指示验证员：
   • 检测项目的测试／lint／类型检查工具，并运行适当的检查
   • 检查所有变更文件的正确性和一致性
   • 确认阶段 1 中的每个问题都已得到实际解决
   • 查找意外副作用或回归
   • 通过 SendMessage 详细报告通过／失败结果
3. 如果验证失败：
   • 将失败项交回负责的调查员修复
   • 修复后重新运行验证
4. 验证通过后，向所有队友发送关闭请求，并等待每位队友确认，然后再向用户报告最终结果

规则

• 并行调查，串行实施——研究适合并行开展；实施适合按顺序进行
• 任务状态是事实依据——通过 TaskUpdate 状态进行协调，而不是依赖消息时间。始终检查 TaskList 以确认状态。
• 队友报告后暂停——发送报告后，停止并等待。不要自行认领新工作，也不要在检查任务状态前处理排队的消息。
• 由负责人标记 completed——只有负责人可以将任务标记为 completed。这是确认并完成闭环的方式。
• 子 Agent 成本低，上下文成本高——队友应将延伸研究和重复性编辑分配给子 Agent，而不是所有事情都亲自处理
• 报告前完成子 Agent 的工作——等待所有已启动的子 Agent 完成后，再发送报告
• 任务描述中应包含完整内容——实施任务必须在任务描述中包含所有详细信息（待办工作、前序轨道摘要、子 Agent 指引）。队友应使用 TaskGet 查看分配给自己的任务，以获取所需的全部信息。不要搜索文件系统来查找说明。
• 缺少内容？暂停并询问。——如果队友收到的任务描述未包含所需信息，应立即告知负责人并停止。不要自行搜索其他位置，也不要擅自发挥。
• 最多 3–5 名队友——如果问题超过此数量，应按主题分组
• 绝不执行 git add .——队友必须添加指定文件
• 验证人员必须是新指派的——不得重复使用调查人员作为验证人员
• 如果队友处于空闲状态，这是正常的——轮到他们时再发送消息
• 队友没有响应？——如果队友在合理时间内没有报告，请检查其任务状态和 git status。如果遇到阻碍，请启动替补人员并告知用户。