opencode-ensemble

OpenCode Ensemble

将 OpenCode Ensemble 用作协调系统，而不是逃避判断的捷径。并行 Agent 最适合由负责人掌控任务拆分、排序、审查、合并和验证。

此仓库引入了上游 hueyexe/opencode-ensemble 技能，版本标签为 v0.14.2（b6bc7f706c13aa42d32e836ea647677d0b14c2f7），并针对此 OpenCode 设置调整了模型指南。默认情况下，队友应继承仓库管理的 OpenCode Agent 变体；只有当任务确实需要有意覆盖模型时，才传入显式的 team_spawn.model。

核心原则

仅为独立且可验证的工作启动队友。优秀的 Ensemble 团队具备明确的任务职责、清晰的依赖关系，以及有意识地整合结果的负责人。

调度表

根据用户请求路由 $ARGUMENTS：

$ARGUMENTS 模式	模式	操作
parallel, team, ensemble, delegate, teammate	团队规划	判断是否适合使用 Ensemble；如果有用，则创建一个由负责人统筹的团队。
waves, parallel teams, subagents, fan out	波次规划	将工作规划为一个团队，包含角色组、任务依赖关系和由负责人掌控的关卡。
review teammate output, merge team, finish team	整合	阅读结果、关闭队友、使用 team_merge 合并、检查差异并验证。
models, model pool, which model	模型指南	继承仓库默认设置，除非有充分理由有意覆盖 team_spawn.model。
空或含义不明确	适用性检查	说明 Ensemble 在何时有帮助；范围较小时优先选择一名侦察者或直接处理。

规范术语

术语	含义
负责人	调用 team_create 并负责任务拆分、启动、合并和验证的会话。
队友	由负责人通过 team_spawn 启动的 OpenCode 会话。
波次	一组分阶段的任务；其依赖项完成后即可开始执行。
角色组	单个团队内一组相关队友，例如 api-*、ui-*、qa-* 或 review-*。
关卡	由负责人掌控的检查点；通过后才能开始下一波任务。
队友子 Agent	由队友创建的子会话；无法使用 team_* 工具。

并行波次

将并行团队建模为一个由负责人拥有、包含角色组和分阶段波次的 Ensemble 团队。使用 team_tasks_add.depends_on 编码波次 DAG，使用 team_spawn.claim_task 将队友绑定到实际任务 ID，并在各波次之间设置由负责人把关的关卡，用于综合汇总、合并和验证。

支持的模式：

1. 波次 0 的侦察人员使用 agent: "explore" 和 worktree: false，梳理边界和风险。
2. 负责人总结侦察结果，之后才生成独立的构建人员。
3. 构建人员在隔离的工作树中并行处理互不重叠的部分。
4. 负责人查看结果，关闭队友，合并并检查差异，然后再解除 QA 或审查人员的阻塞。
5. QA 和审查人员在实现分支集成后开展工作。

一个负责人会话只能拥有一个活跃的 Ensemble 团队。如果确实需要独立的团队，请使用不同的负责人会话；否则，应将角色组保留在同一个团队中，并在任务内容中清晰命名各个波次。

不要要求队友创建的子 Agent 使用 team_* 工具进行协调。Ensemble 会有意阻止队友的后代使用团队工具，因此负责人必须生成所有需要参与团队协调的队友。

适合使用 Ensemble 的情况

• 工作可以拆分为相互独立的研究、实现、测试或审查部分。
• 只读侦察人员可以在开始编辑前梳理陌生代码。
• 可以在不发生所有权重叠的情况下修改多个文件或子系统。
• 有风险的变更适合在编辑前设置 plan_approval: true。
• 最终审查人员可以检查已合并的变更，而无需创建另一个分支。
• 工作可以表示为分阶段波次，后续每个波次都依赖前序波次已完成的任务 ID。

不适合使用 Ensemble 的情况

• 任务足够小，一个 Agent 可以快速完成。
• 工作紧密耦合，每个队友都需要修改相同的文件。
• 负责人无法说明每个队友的产出和成功标准。
• 用户需要一个连贯的设计决策，而不是并行探索。
• 你因为任务感觉困难就想生成 Agent，但任务实际上无法拆分。
• 你需要一个负责人会话同时运行多个活跃团队。
• 你需要队友的子 Agent 使用 team_* 工具进行协调。

负责人工作流

1. 判断是否有理由采用并行处理。
2. 使用 team_create 创建团队。
3. 使用 team_tasks_add 添加任务；使用 depends_on 设置执行顺序。
4. 使用 team_spawn 逐个生成队友；生成后，他们会异步并行运行。
5. 对只读的 explore 队友使用 worktree: false。
6. 对有风险的实现工作使用 plan_approval: true。
7. 在启动依赖波次前，先由负责人进行综合汇总并把关。
8. 等待队友发消息，而不是反复轮询状态。
9. 如果消息被截断或结果影响重大，请使用 team_results 查看完整结果。
10. 使用 team_shutdown 关闭已完成的队友。
11. 使用 team_merge 合并分支；在信任合并结果前检查差异。
12. 在运行项目验证后、执行 team_cleanup 前，确认可以宣布完成。

角色默认设置

角色	Agent	工作树	模型指导	用途
Scout	explore	false	继承仓库的 high 默认值	代码库梳理、风险发现、文件所有权规划
Builder	build	true	继承仓库的 high 默认值	范围明确的实现切片
QA	build	true	继承仓库的 high 默认值	测试、夹具、回归覆盖
Reviewer	explore	false	继承仓库的 high 默认值	差异审查、风险审查、遗漏测试审查

从两到三名队友开始。在这台机器上，当系统资源和 API 配额允许时，5-8 名队友是开展大量独立工作的合理上限。只有当工作的独立切片多于活跃队友时，才增加队友人数；相比一开始就投入过多队友，更推荐分批增加。

参考文件索引

文件	何时加载
references/coordination-patterns.md	选择团队结构、工作波次拓扑、角色组或单独的负责人会话时。
references/prompt-recipes.md	编写 Scout、Builder、QA、Reviewer 或特定波次的队友提示词时。
references/lead-checklists.md	执行启动前、波次、合并、清理或验证关卡时。
references/anti-patterns.md	检查计划是否过度并行、缺乏支持或沟通冗长时。
references/eval-scenarios.md	创建或改进此技能的行为检查时。

关键规则

1. 记录生成的任务 ID。team_tasks_add 会生成 ID；设置 depends_on 或 claim_task 时，使用先前调用返回的 ID。
2. 队友提示词要简短。插件已注入团队角色、允许使用的工具、工作树上下文以及必需的任务结果格式。
3. 避免含糊的委派。诸如“修复这个 bug”或“处理测试”之类的提示会造成工作重叠，且难以验证。
4. 仅由负责人使用负责人的工具。不要要求队友使用 team_spawn、team_shutdown、team_merge、team_cleanup 或 team_view。
5. 不要让队友子 Agent 参与团队协调。它们无法访问 team_*，这是有意为之。
6. 对有依赖关系的波次设置关卡。所需任务 ID 完成并由负责人整合之前，不要启动依赖波次。
7. 要求使用 team_message 汇报结果。不要要求队友只用纯文本汇报。
8. 合并前先审查。未阅读队友的结果并检查差异前，不要合并队友分支。
9. 声称工作完成前先验证。运行仓库验证命令，或明确报告阻碍因素。

验证约定

声称 Ensemble 工作流成功之前：

• 负责人能够说明这项工作为何可以拆分。
• 每位生成的队友都有明确的负责范围，并在适用时分配了一个任务 ID。
• 依赖波次使用真实的 depends_on ID。
• 只读角色使用 agent: "explore" 和 worktree: false。
• 如果队友结果被截断或影响重大，已使用 team_results 阅读结果。
• 已通过项目差异检查合并的分支。
• 仓库特定的验证命令已通过，或已报告阻碍因素。

修改此技能时，在声明编辑完成前，运行 python scripts/check.py 和 uv run pytest tests/test_distribution_metadata.py tests/test_sync_agent_stack.py -q。

最简示例

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,
  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",
  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.",
});