opencode-ensemble

OpenCode Ensemble

将 OpenCode Ensemble 用作协调系统，而不是逃避判断的捷径。并行 Agent 的效果最好时，主 Agent 会负责任务拆解、排序、审查、合并和验证。

核心原则

仅在工作彼此独立且可验证时才启动队友。好的 Ensemble 团队应有明确的任务归属、清晰的依赖关系，并由主 Agent 有条不紊地整合结果。

适合使用 Ensemble 的情况

• 工作可以拆分为独立的调研、实现、测试或审查任务。
• 只读侦察 Agent 可以在开始编辑前梳理不熟悉的代码。
• 可以修改多个文件或子系统，且任务归属互不重叠。
• 高风险改动需要在编辑前启用 plan_approval: true。
• 最终审查者可以检查合并后的改动，而无需创建另一个分支。

不适合使用 Ensemble 的情况

• 任务足够小，一个 Agent 可以快速完成。
• 工作紧密耦合，且每个队友都需要处理相同的文件。
• 主 Agent 无法描述每个队友的产出和成功标准。
• 用户需要的是一个连贯的设计决策，而不是并行探索。
• 你想启动 Agent，只是因为任务感觉很难，但实际上无法拆分。

主 Agent 工作流

1. 判断并行处理是否合理。
2. 使用 team_create 创建团队。
3. 使用 team_tasks_add 添加任务；用 depends_on 设置执行顺序。
4. 使用 team_spawn 逐个启动队友。
5. 对只读的 explore 队友使用 worktree: false。
6. 对高风险实现工作使用 plan_approval: true。
7. 等待队友发送消息，不要反复轮询状态。
8. 当消息被截断或结果影响重大时，使用 team_results 阅读完整结果。
9. 使用 team_shutdown 关闭已完成的队友。
10. 使用 team_merge 合并分支；在信任改动前先检查差异。
11. 在执行 team_cleanup 前、以及宣告完成前，运行项目验证。

角色默认设置

角色	Agent	Worktree	模型建议	适用场景
侦察员	explore	false	例如 openai/gpt-5-mini	梳理代码库、发现风险、规划文件归属
构建者	build	true	例如 anthropic/claude-opus-4-7	范围明确的实现任务
QA	build	true	强大的模型，例如 anthropic/claude-opus-4-7	测试、固件、回归覆盖
审查者	explore	false	例如 openai/gpt-5-mini	差异审查、风险审查、检查遗漏的测试

模型 ID 仅为示例，请向你的提供商确认当前 ID。根据任务匹配成本：批量使用便宜模型执行侦察和审查；让擅长处理复杂工作的构建者使用能力强但价格较高的模型；如果合适，也可以为不同角色选择不同的提供商。在 team_spawn 中始终显式传入 model：省略模型时会回退到服务默认值，而默认值可能需要付费或配置错误。

从两到三名队友开始。只有当独立任务片段多于活跃队友时，才增加队友。

按需加载参考资料

• 需要团队结构？阅读 references/coordination-patterns.md。
• 需要提示词？阅读 references/prompt-recipes.md。
• 需要启动前、合并、清理或验证关卡？阅读 references/lead-checklists.md。
• 感觉哪里不对劲或沟通太频繁？阅读 references/anti-patterns.md。
• 正在创建或改进此技能？阅读 references/eval-scenarios.md。

硬性规则

• 不要编造任务 ID。team_tasks_add 会生成 ID；设置 depends_on 或 claim_task 时，请使用先前调用返回的 ID。
• 保持给队友的提示词简短。插件已注入团队角色、允许使用的工具、工作树上下文以及所需的任务结果格式。
• 不要给队友发送“修复这个 bug”或“处理一下测试”这类含糊的提示词。
• 不要要求队友使用仅限负责人使用的工具，例如 team_spawn、team_shutdown、team_merge 或 team_cleanup。
• 不要要求队友只用纯文本汇报。他们必须使用 team_message。
• 未阅读队友的结果并检查差异前，不要合并队友分支。
• 除非仓库的验证命令通过，或你已明确报告阻碍，否则不要宣告工作完成。
• 在 OpenCode v2 上，队友的报告和通知会以持久的合成系统行形式出现在对话记录中；只有在传入 navigate: true 时，team_view 才会切换 TUI（切勿未经提示就这样做，以免劫持用户的客户端）；team_cleanup 的清理操作需要先由人工审核预览，再予以确认。

最简示例

team_create({ name: "checkout-idempotency" })

team_tasks_add({
  tasks: [
    { content: "Map checkout webhook flow and risky files", priority: "high" },
    { content: "Implement duplicate-webhook idempotency guard", priority: "high" },
  ],
})
// Record returned IDs, for example: task_abc123 for scout and task_def456 for builder.

team_tasks_add({
  tasks: [
    { content: "Add duplicate-webhook regression tests", priority: "high", depends_on: ["task_def456"] },
  ],
})
// Record returned QA task ID, for example: task_ghi789.

team_tasks_add({
  tasks: [
    { content: "Review merged diff for correctness and missed tests", priority: "medium", depends_on: ["task_def456", "task_ghi789"] },
  ],
})

team_spawn({
  name: "scout",
  agent: "explore",
  worktree: false,
  model: "openai/gpt-5-mini",
  claim_task: "task_abc123",
  prompt: "Trace the checkout webhook flow. Report files, data model, existing tests, risks, and a smallest-safe-change plan. Do not edit files.",
})

team_spawn({
  name: "api-dev",
  agent: "build",
  model: "anthropic/claude-opus-4-7",
  plan_approval: true,
  claim_task: "task_def456",
  prompt: "Use scout's findings to implement only the idempotency guard. Commit your work and send a task-result message with files changed and tests run.",
})