> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supervisor Change：让大型任务安全并行

> 将大型目标拆成可独立完成的子任务，在隔离工作区中并行推进，最后统一验证和交付。

export const SupervisorVideo = ({src, width, height, label, fallback}) => <div className="comet-home__supervisor-media">
    <video autoPlay muted loop playsInline controls preload="metadata" width={width} height={height} aria-label={label}>
      <source src={src} type="video/mp4" />
      {fallback}
    </video>
  </div>;

Supervisor Change 是 Native 为大型任务提供的并行交付模式。它按照验收要求，将整体目标拆成可以独立实现和验证的子任务。Runtime 负责管理依赖、隔离工作区、记录执行状态、集成结果并完成最终验收。

无论拆成多少个子任务，最终交付仍然只有一个。所有结果集成后，主任务必须对完整目标重新 Verify。单个 Agent 报告完成、某个子任务通过验证，或者代码已经进入集成分支，都不能代表整个任务已经完成。

## 子任务统一管理与交付

| 产品能力    | 实际作用                                      |
| ------- | ----------------------------------------- |
| 按验收项拆分  | 每个子任务都负责明确的验收项，不采用“前端、后端各做一点”这类模糊分工       |
| 按依赖自动推进 | Runtime 只安排依赖已经满足的子任务，避免尚未具备条件的任务提前开始     |
| 独立工作区   | 每个子任务只在自己的 worktree 中修改代码，避免多个 Agent 相互覆盖 |
| 结果不会串线  | 任务包、基线提交和 `runId` 共同标识当前执行，迟到或重复的结果会被拒绝   |
| 整体统一验收  | 所有子任务集成后，再对完整目标执行一次最终验收                   |

例如，一个权限管理目标可以拆成权限 API、权限配置页面和审计日志。三个结果可以独立实现和验证，但仍属于同一个产品目标，需要统一集成和最终验收。这类任务适合使用 Supervisor Change。

## 按照可交付结果拆分任务

Comet 会在最终 Shape 确认前检查是否值得拆分。只有同时满足以下条件，才会建议使用 Supervisor Change：

* 至少有两个结果可以独立实现和验证；
* 整体目标中的每个验收项都能明确分配给某个子任务；
* 子任务之间的依赖可以明确表达；
* 并行执行或分阶段交付确实能降低整体等待时间。

需求文字很长、任务条目很多，并不代表适合拆分。如果多个部分需要反复修改同一核心区域，或者拆分后增加的沟通与集成成本高于并行收益，继续使用单个 Native Change 更合适。没有共同最终验收的目标，则应创建多个独立 Change。

拆分草案记录在 `children.yaml`。RC1 使用 `comet.native.children.v2`：`acceptance_index` 保存从 `brief.md` 派生的整体目标验收 ID、来源和完整文字，每个子任务只声明唯一名称、依赖项和自己覆盖的验收 ID。Runtime 会检查名称重复、未知依赖、依赖环和验收遗漏。

## 用户选择拆分方案与推进方式

确认前，Comet 会展示整体目标、子任务列表、依赖关系和验收映射。用户可以调整拆分、继续使用单个 Native Change，或者选择一种推进方式：

| 选项 | 推进方式      | 实际影响                                                                     |
| -- | --------- | ------------------------------------------------------------------------ |
| A  | 多会话协作（推荐） | 当前会话只负责统筹；优先由 Codex 独立会话或 Claude Code Agent Teams 执行，宿主不支持时自动改用 subagent |
| B  | 单会话推进     | 不创建独立会话或 Agent Team；当前会话按照同一范围、依赖和验收要求依次完成子任务                            |

推进方式只决定子任务在哪里执行，不会改变拆分结果、依赖、验收标准或集成规则。确认 Supervisor 拆分时，Runtime 会把选择作为 `coordination_mode` 写入 `comet-state.yaml`。恢复流程或因需求变化重新进入 Shape 时会沿用这个选择，不重复询问。只有出现新的用户可见决定时，流程才会返回 Shape，请用户重新确认。

确认之前，Runtime 不会创建子任务、worktree 或外部会话。包含两个或更多子任务时，普通的“确认”也不能代替推进方式选择。

## 每个子任务都有独立工作区

Shape 确认后，Runtime 会先为主任务创建专用的集成分支和集成 worktree，再以集成分支的当前提交为起点，为各个子任务准备独立 worktree 和任务包。

每份任务包包含：

* 子任务的角色和验收范围；
* 唯一的工作目录；
* 当前集成基线提交；
* 用于绑定任务回报的 `runId`；
* 依赖条件和停止条件。

Runtime 通过 `readyChildren` 告诉主会话哪些子任务现在可以开始。多会话模式默认最多同时启动两个互不依赖的子任务；单会话模式按顺序执行。需要临时改为串行推进时，可以使用：

```bash theme={null}
comet native next <supervisor-change> --max-parallel 1
```

这个参数只限制同时执行的任务数量，不会改变任务依赖或验收范围。

## 在Codex中采用多会话并行推进

在 Codex 中选择多会话协作后，当前会话成为主会话。它负责分配任务、持续检查进度、处理阻塞、让 Runtime 集成已经验证的结果，并完成主任务的最终 Verify。主会话不直接进入子任务 worktree 修改代码。

`readyChildren` 中的每个子任务都会交给一个用户可见的独立任务。独立任务沿用当前项目，并直接进入 Runtime 已经准备好的子任务目录，无需另外创建 worktree。任务完成后，主会话仍要等待子任务 Verify 和 Runtime 集成，不能把独立任务的完成消息当作交付结果。

<SupervisorVideo src="/vedio/codex.mp4" width={1230} height={858} label="Comet Supervisor Change 在 Codex 中通过多个独立会话执行子任务" fallback="你的浏览器不支持 HTML5 视频" />

## 在Claude Code中采用Agent Teams 并行推进

在 Claude Code 的交互式会话中，可以使用 Agent Teams 运行不同子任务。PowerShell 中可通过以下环境变量启用：

```powershell theme={null}
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1"
```

当前会话作为 team lead，为 `readyChildren` 中的每个子任务分配一个有明确名称的 teammate。teammate 只在 Runtime 指定的子任务 worktree 中工作，不能自行创建新的工作区、领取依赖尚未满足的子任务、集成主任务分支或创建嵌套团队。

Agent Teams 负责运行多个会话，Native Runtime 仍然负责工作区、任务状态、验证和集成。团队成员的消息不能覆盖 Runtime 状态，也不能代替主任务的最终验收。

<SupervisorVideo src="/vedio/claude%20code.mp4" width={1548} height={1080} label="Comet Supervisor Change 在 Claude Code 中通过 Agent Teams 执行子任务" fallback="你的浏览器不支持 HTML5 视频" />

## 先验证，再集成

每个子任务都必须经过 `active → verified → integrated`：

1. Builder 在子任务 worktree 中完成候选实现，并提交绑定当前 `runId` 的结果；
2. 独立 Verifier 检查候选提交和子任务验收范围；
3. Runtime 只接受角色、`runId` 和当前任务状态都匹配的回报；
4. 验证通过后，Runtime 把已验证提交集成到 Supervisor 的集成 worktree，并运行必要的集成检查。

子任务不单独执行 Archive，也不能自行合并主任务分支。Agent 声称“已经完成”不能作为集成依据；worktree 中存在未提交修改时，也说明结果尚未准备好。只有 Runtime 将状态记录为 `integrated`，依赖它的后续子任务才会进入 `readyChildren`。

## 集成完成后统一验收

所有子任务进入 `integrated` 后，Runtime 会立即推进主任务的最终 Verify，不需要用户再次发送“继续”。最终 Verify 在集成 worktree 中运行至少一项集成检查，并覆盖整体目标的完整验收范围。

最终 Verify 通过后，Supervisor Change 才能进入 Archive。用户仍按 Native 的正常交付选项决定保留工作区、本地合并、推送或创建 PR，目标分支在最终交付前不会被提前修改。

如果最终 Verify 失败，Runtime 会保留集成现场，不会重新打开已经完成集成的子任务。流程会根据实际失败的验收项追加一个名称唯一的修复子任务，补充整体目标的验收映射，并返回 Shape 让用户确认新增修复范围。

## 可恢复的任务进度

主会话可以通过以下命令查看子任务汇总、`readyChildren`、集成状态和下一步：

```bash theme={null}
comet native status <supervisor-change> --details --json
```

恢复任务时，Comet 以 Runtime 持久化的 `coordination_mode` 为准，不重复创建已有子任务或 worktree。`multi-session` 继续使用多会话协作，`single-session` 继续由当前会话按顺序推进。

如果原来的 Codex 独立会话或 Claude Code Agent Team 已经不存在，Comet 会重新读取 Runtime，并在 `multi-session` 下自动改用 subagent。已经派发但丢失的任务会先通过 `supervisor-cancel` 使旧 `runId` 失效，再使用新的任务包和 `runId` 重新派发；旧执行的迟到结果会被拒绝。subagent 也不可用时，Comet 会报告真实阻塞，不会自动切换为单会话推进。

继续阅读 [Native Loop](/zh/native/native-loop)，了解主任务和子任务共用的验收机制。阅读 [多 Change 与规格冲突](/zh/native/multi-change-and-conflicts) 和 [恢复手册](/zh/native/recovery-playbook)，了解并发冲突与中断恢复。