opencode-ensemble

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCode Ensemble

Use OpenCode Ensemble as a coordination system, not a shortcut for avoiding judgment. Parallel agents work best when the lead owns decomposition, sequencing, review, merge, and verification.

将OpenCode Ensemble用作协调系统，而非规避判断的捷径。当负责人掌控任务分解、排序、审核、合并和验证时，并行Agent的工作效果最佳。

Core Principle

核心原则

Spawn teammates only for independent, verifiable work. A good Ensemble team has narrow task ownership, clear dependencies, and a lead that integrates results deliberately.

仅为独立、可验证的工作创建团队成员。一个优秀的Ensemble团队应具备明确的任务归属、清晰的依赖关系，且由负责人统筹整合结果。

Use Ensemble When

适用场景

Work can be split into independent research, implementation, test, or review slices.
A read-only scout can map unfamiliar code before edits begin.
Multiple files or subsystems can be changed without overlapping ownership.
A risky change benefits from
```
plan_approval: true
```
before edits.
A final reviewer can inspect merged changes without creating another branch.

工作可拆分为独立的调研、实现、测试或审核模块。
在开始编辑前，可通过只读的侦察Agent（Scout）梳理不熟悉的代码。
可在不重叠归属的情况下修改多个文件或子系统。
高风险变更可在编辑前启用
```
plan_approval: true
```
进行方案审批。
最终审核人员可检查合并后的变更，无需创建新分支。

Do Not Use Ensemble When

不适用场景

The task is small enough for one agent to finish quickly.
The work is tightly coupled and every teammate would need the same files.
The lead cannot describe each teammate's output and success criteria.
The user needs one coherent design decision rather than parallel exploration.
You are tempted to spawn agents because the task feels hard but not divisible.

任务规模小到单个Agent可快速完成。
工作耦合度高，所有团队成员都需要操作相同文件。
负责人无法明确描述每个团队成员的输出和成功标准。
用户需要统一的设计决策，而非并行探索多种方案。
因任务难度大但无法拆分而想要创建多个Agent。

Lead Workflow

负责人工作流程

Decide whether parallelism is justified.
Create a team with
```
team_create
```
.
Add tasks with
```
team_tasks_add
```
; use
```
depends_on
```
for sequencing.
Spawn teammates one at a time with
```
team_spawn
```
.
Use
```
worktree: false
```
for read-only
```
explore
```
teammates.
Use
```
plan_approval: true
```
for risky implementation work.
Wait for teammate messages instead of polling status repeatedly.
Read full results with
```
team_results
```
when messages are truncated or consequential.
Shut down completed teammates with
```
team_shutdown
```
.
Merge branches with
```
team_merge
```
; inspect the diff before trusting it.
Run project verification before
```
team_cleanup
```
and before claiming done.

判断是否有必要采用并行模式。
使用
```
team_create
```
创建团队。
使用
```
team_tasks_add
```
添加任务；通过
```
depends_on
```
设置任务顺序。
使用
```
team_spawn
```
逐个创建团队成员。
为只读的
```
explore
```
类型团队成员设置
```
worktree: false
```
。
针对高风险实现工作启用
```
plan_approval: true
```
。
等待团队成员的消息，而非反复轮询状态。
当消息被截断或内容至关重要时，使用
```
team_results
```
查看完整结果。
使用
```
team_shutdown
```
关闭已完成任务的团队成员。
使用
```
team_merge
```
合并分支；在信任合并结果前先检查差异。
在执行
```
team_cleanup
```
和宣告任务完成前，运行项目验证。

Role Defaults

角色默认配置

Role	Agent	Worktree	Model guidance	Use for
Scout	`explore`	`false`	`openai/gpt-5.3-codex-spark`	Codebase mapping, risk discovery, file ownership plan
Builder	`build`	`true`	`anthropic/claude-opus-4-7`	Narrow implementation slice
QA	`build`	`true`	strong balanced model	Tests, fixtures, regression coverage
Reviewer	`explore`	`false`	`openai/gpt-5.3-codex-spark`	Diff review, risk review, missed-test review

Start with two or three teammates. Add more only when the work has more independent slices than active teammates.

角色	Agent	工作树	模型指引	适用场景
Scout	`explore`	`false`	`openai/gpt-5.3-codex-spark`	代码库映射、风险排查、文件归属规划
Builder	`build`	`true`	`anthropic/claude-opus-4-7`	细分模块实现
QA	`build`	`true`	均衡型强模型	测试用例、测试夹具、回归覆盖
Reviewer	`explore`	`false`	`openai/gpt-5.3-codex-spark`	差异审核、风险审核、遗漏测试审核

初始团队配置2-3名成员即可。仅当工作的独立模块数量多于当前活跃成员时，再添加更多成员。

Load References As Needed

按需加载参考文档

Need a team shape? Read
```
references/coordination-patterns.md
```
.
Need prompts? Read
```
references/prompt-recipes.md
```
.
Need a pre-spawn, merge, cleanup, or verification gate? Read
```
references/lead-checklists.md
```
.
Something feels off or too chatty? Read
```
references/anti-patterns.md
```
.
Creating or improving this skill? Read
```
references/eval-scenarios.md
```
.

需要团队架构方案？阅读
```
references/coordination-patterns.md
```
。
需要提示词模板？阅读
```
references/prompt-recipes.md
```
。
需要预创建、合并、清理或验证的检查清单？阅读
```
references/lead-checklists.md
```
。
感觉流程有问题或沟通过于繁琐？阅读
```
references/anti-patterns.md
```
。
要创建或优化该技能？阅读
```
references/eval-scenarios.md
```
。

Hard Rules

硬性规则

Do not invent task IDs.
```
team_tasks_add
```
generates IDs; use the IDs returned by earlier calls when setting
```
depends_on
```
or
```
claim_task
```
.
Keep teammate prompts short. The plugin already injects team role, allowed tools, worktree context, and the required task-result format.
Do not give teammates vague prompts like "fix the bug" or "work on tests".
Do not ask teammates to use lead-only tools such as
```
team_spawn
```
,
```
team_shutdown
```
,
```
team_merge
```
,
```
team_cleanup
```
, or
```
team_view
```
.
Do not tell teammates to report only in plain text. They must use
```
team_message
```
.
Do not merge a teammate branch without reading its result and inspecting the diff.
Do not call the work complete until the repository's verification commands pass or you have clearly reported the blocker.

不要自行创建任务ID。
```
team_tasks_add
```
会生成ID；设置
```
depends_on
```
或
```
claim_task
```
时，请使用之前调用返回的ID。
团队成员的提示词要简洁。插件已自动注入团队角色、允许使用的工具、工作树上下文以及要求的任务结果格式。
不要给团队成员模糊的提示，比如“修复bug”或“处理测试”。
不要要求团队成员使用仅负责人可用的工具，如
```
team_spawn
```
、
```
team_shutdown
```
、
```
team_merge
```
、
```
team_cleanup
```
或
```
team_view
```
。
不要要求团队成员仅用纯文本汇报。他们必须使用
```
team_message
```
。
在未查看结果和检查差异的情况下，不要合并团队成员的分支。
在仓库的验证命令通过或已明确报告阻塞问题前，不要宣告工作完成。

Minimal Example

最简示例

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.3-codex-spark",
  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.",
})

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.3-codex-spark",
  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.",
})