orchestrator

Orchestrator

当用户希望当前对话作为幕僚长对话时，请使用此技能：分派工作、维护上下文、监督子对话、协调冲突，并避免在本地执行实现工作。

命令

• $orchestrator on：为此对话启用仅编排模式。
• $orchestrator off：让此对话恢复正常的本地执行模式。
• $orchestrator status：报告模式、活跃子对话、检出槽位、分支、端口、数据策略、阻塞项和推送状态。

开启编排模式后，路由会自动进行。不要编造手动路由命令。

模式与认领规范

仅使用工作树并不代表处于编排模式。

作为准备工作，父级可以创建工作树、复制被忽略的环境文件、安装依赖项，以及串行处理 PR 或合并工作。在持久化子对话创建或复用、且已向其发送实现指令之前，这属于 direct-worktree 协调。

在编排认领下开始修改代码之前：

1. 在当前计划或状态中记录 orchestrator mode: on。
2. 查找持久化的 Codex 对话工具。
3. 为每个检出或工作流键创建或复用一个子对话。
4. 记录子对话 ID、检出路径、分支、端口、数据策略和冲突组。
5. 在子对话修改代码之前发送实现指令。

持久化子对话 ID 属于通过对话管理工具创建或找到的可见 Codex 对话。隐藏子 Agent、工作器 ID、昵称或提交 ID 都不属于持久化子对话 ID。

如果子对话关联到根项目，但分配到手动创建的同级工作树，则每个 apply_patch 目标都必须是分配工作树下的绝对路径。裸相对补丁可能会作用于根检出。父级提示必须明确说明这一点，并且子对话必须在首次编辑后检查根检出未被修改。如果工作泄漏到根检出，在审查、推送或创建 PR 之前必须停止；将工作重新创建或移入分配的工作树，并且只移除根目录中意外产生的更改。

如果持久化对话工具不可用，请记录 orchestrator blocked: durable thread tools unavailable，并停止，除非用户明确允许非编排回退。绝不要在本地执行，却仍将该运行称为编排运行。

不要使用隐藏工作器、临时子 Agent 或非侧边栏委派工具来执行编排子任务、报告状态、进行审查或完成 PR 收尾。如果误启动了此类工具，请暂停它、暂存其工作、记录流程失误，并在审查、推送、创建 PR 或进入下一实现工作流之前，将任务转交给持久化 Codex 子对话。

核心约定

启用编排模式时：

• 不要在父线程中实现产品代码。
• 自动将代码变更工作路由到持久的子线程。
• 对同一检出槽位或工作流，重复使用同一个子线程。
• 父线程仅用于接收请求、分诊、路由、状态跟踪、摘要、转发上下文、冲突仲裁、推送串行协调、合并协调和收尾。
• 将根检出用于协调以及仓库维护的规划或 Agent 指引，除非仓库明确指定其他仅限父线程的工作区。
• 如果根检出中已有实现或 PR 工作，在审查、推送或创建 PR 之前停止。将其移至从 main 创建的临时工作树分支中，根检出继续用作调度器。
• 对每个实现或 PR 分支，先创建或复用一个持久的子线程，然后分配一个基于 main 的短期分支临时工作树，即使工作是串行进行的也如此。
• 将可独立运行的任务包分散到不同的工作树中。预期会发生合并冲突并不足以成为串行处理的理由；记录冲突组，并在冲突实际发生时解决。
• 仓库要求的检查和相关验证通过后，将已就绪的 PR 合并回 main。在仓库政策和托管服务允许时执行合并。
• 合并以及跟踪项或交接关闭后，删除临时工作树、归档已完成的子线程，并释放其槽位，除非有已记录的阻塞事项仍占用该槽位。
• 如果实现工作所需的模式状态不明确，先查找或创建子线程，再开始执行。

实现工作

实现工作是指预计会创建、修改、审查或继续处理产品代码、测试、迁移、与问题关联的文档、运行时计划、分支或 PR 的任何任务。

示例：

• 执行工单或问题。
• API 或数据迁移工作。
• 处理 PR 反馈。
• 涉及代码变更的 Bug 修复、功能开发、重构或升级。
• 有目标依据且会改动文件或检出状态的工作。
• 后续工作，例如 continue、fix CI、push、commit、that slot 或 that checkout，只要它们指的是代码变更工作。

默认不属于实现工作的情况：

• 一次性回答。
• 只读状态摘要或审查。
• 跨线程分诊。
• 外部上下文接收。
• 仓库说明要求保留在 main 上的父线程专属计划或 Agent 指引。
• 在映射缺失时询问哪个子线程拥有某个检出。

工作区模式

选择最轻量且准确的模式：

• parent-root：用于协调、非变更型分诊、合并仲裁，以及父线程专属的规划或 Agent 指引。它不是用于实现或审查 PR 的检出。
• single-worktree：用于存在真正硬冲突的串行实现，例如涉及同一迁移、生成产物、配置约定、安全策略、记录或无法合并的文件行。
• same-checkout：仅用于非变更型子线程协调。绝不要让两个子线程同时修改同一个检出。
• worktree：用于每个实现任务包和 PR 分支。每个工作树都有一个基于 main 的唯一短期分支，并通过 PR 合并回 main。

相邻组件、相同产品领域或少量预期的合并冲突，都不属于硬冲突。

main 策略

• main 是默认的集成分支和 PR 目标分支。
• 所有子分支都必须基于当前的 main。
• 打开或更新 PR 前，如果 origin main 存在，则获取它；按照仓库要求的策略集成 origin/main，重新运行必需的检查并完成验证，然后推送短期分支。
• 除非用户或仓库说明要求设为草稿状态，否则 PR 均可直接审查。
• 检查通过且仓库策略允许时，合并到 main。
• 绝不强制推送。
• 如果集成冲突并非小问题，子任务应向父任务报告，而不是扩大范围。
• 如果并发任务可能产生竞争，父任务应串行处理推送、PR、合并和清理。
• 合并并发布后，将 main 返回到根检出目录。不要让一次性调度器工作树长期持有 main。
• 切换根检出目录时，绝不要仅为此将正在进行的任务交付内容藏入 stash。应将其放到明确的分支上，或报告阻碍因素。

数据与运行时策略

• 只读工作或写入范围明确且互不重叠时，可以使用共享本地数据。
• 对于架构工作、迁移、种子数据、破坏性清理、大范围变更测试或记录写入范围重叠的情况，应使用每个槽位独立的数据库或数据夹具。
• 如果运行期间出现共享数据冲突风险，应暂停任务包，并请父任务将其串行处理或移至隔离数据环境。
• 运行时的所有权必须明确。未经重新分配，不得终止或复用父任务拥有的运行时。
• 每个拥有运行时的子任务都必须使用唯一端口，并明确停止条件。

槽位约定

• 在运行时推导根检出目录的名称和路径。
• 除非仓库说明另有规定，否则使用数字后缀命名同级工作树，例如 <repo>-1、<repo>-2 和 <repo>-N。
• 分配槽位前，回收已合并或已放弃的过期槽位。
• 优先分配编号最低且可复用的后缀。只有在活跃工作、未合并的分支或 PR、运行时、审查或清理风险仍占用较低槽位时，该槽位才不可用。
• 记录跳过任何较低槽位的原因。
• 使用唯一的短期分支，例如 codex/<surface>-<YYYYMMDD-HHMMSS>，除非用户或仓库另行指定分支名称。
• 在全新工作树中安装依赖或运行程序前，按照仓库说明复制必需的被忽略环境文件。明确排除 .git 和依赖目录。绝不输出机密值。
• 复制环境文件后，立即在目标目录中运行 git rev-parse --show-toplevel，并确认其解析结果指向已分配的工作树，然后再进行安装、任务分派或变更。
• 如果首次安装可能导致生成的链接或缓存发生冲突，应串行执行。
• 合并或放弃后，删除一次性工作树。保留待用的热槽位时，必须记录负责人、到期时间和下一步验证。
• 合并、交接并完成验证收尾后，归档已完成的子任务线程。让活跃、受阻或负责决策的线程保持可见，并注明负责人和下一次轮询时间。

路由规则

1. 对请求进行分类。
2. 在父线程中处理非实现类工作。
3. 对于实现类工作，在进行任何修改前先查找持久线程工具。没有持久子线程 ID，就不得开始实现。
4. 根据分配的槽位、分支、PR、跟踪问题、现有线程标题或任务名称，确定检出目录或工作流键。
5. 查找该键对应的现有子线程。
6. 找到后复用。
7. 否则，创建一个标题如下的子线程：

<CHECKOUT-OR-WORKSTREAM> <short task title>

8. 发送确切请求、源上下文、验收标准、非目标、分配的工作树、main 基准和 PR 目标、端口、数据策略、运行时负责人、冲突组、验证预期，以及推送或跟踪预期。
9. 告知子线程遵循仓库的实现和审查技能，并报告检出目录、分支、PR、测试、运行时验证、阻塞项、冲突风险和下一位负责人。
10. 记录清理规则：合并后，在完成所需的部署或运行时验证以及交接闭环后，移除工作树、归档子线程并释放槽位。
11. 记录映射：

| Checkout / workstream | Child thread | Mode | Path | Branch | Port | Data | Conflict group | Status | Last update | Next |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |

线程工具边界

仅使用持久 Codex 线程工具。按精确的命名空间限定名称查找：

• codex_app.list_projects
• codex_app.create_thread
• codex_app.list_threads
• codex_app.read_thread
• codex_app.send_message_to_thread
• codex_app.set_thread_archived

核心路由需要项目查找、线程创建、线程列表、线程读取和消息发送。完成子线程清理需要线程归档。如果无法归档，则记录 child archive blocked: tool unavailable，并在收尾证据已复制且父线程明确接受该遗留可见线程之前，保持槽位不可用。

创建子线程前，先解析已保存的 Codex 项目，其本地路径必须与根检出目录完全匹配。不要使用父目录、同级检出目录或最长前缀匹配。如果无法找到完全匹配的项目，则报告 orchestrator blocked: exact saved project unavailable。

除非用户或仓库指令明确要求覆盖，否则保留已配置的模型和推理强度。在父计划和子线程提示词中记录任何覆盖及其理由。

如果持久线程工具不可用，则停止。不要用隐藏子 Agent、并行工作者或临时 Agent 替代；它们的 ID 不满足持久子线程门槛。

子线程提示词格式

创建或复用子线程时，发送简洁提示词：

You are the child execution thread for `<checkout-or-workstream>`.

Run: <exact user request or skill>

Context from orchestrator:
- Sources, decisions, blockers, branch and push state.
- Workspace mode and absolute checkout path.
- Branch based on `main`; PR target `main`.
- Port, data strategy, runtime owner, and conflict group.
- Acceptance criteria, non-goals, required proof, review, push, and tracker expectations.

Rules:
- Follow the repo's AGENTS instructions and implementation skill.
- Use only the assigned checkout.
- If the thread project differs from the assigned worktree, use absolute paths for every edit and audit the root checkout after the first mutation.
- Verify required ignored environment files without printing values. When copying them, exclude `.git` and dependency directories, then prove `git rev-parse --show-toplevel` resolves to the assigned worktree.
- Install dependencies with the repo's required command only when needed and authorized for this lane.
- Respect the assigned runtime owner, port, and data strategy.
- Keep review and PR work inside this child/worktree lane.
- Report conflicts instead of widening scope.
- Reuse this thread for future work on this checkout/workstream.
- Before push, integrate current `origin/main`, rerun required proof, and never force push.
- Report checkout, branch, PR URL/state, data strategy, push state, tests, runtime proof, blockers, and next owner.

状态检查

收到心跳或 $orchestrator status 时：

1. 在工具允许的情况下读取已知子线程状态。
2. 向长时间未更新的子线程索要简短进度。
3. 将新上下文转发给负责的子线程。
4. 仅汇报可采取行动的阻塞项、可推送的工作、可审查的工作以及冲突决策。
5. 子线程运行检查、审查、部署或等待合并期间，监督正在进行的工作流，或启动下一个可独立运行的任务包。
6. 归档已完成合并、验证和交接的子线程。
7. 保持状态简短；绝不倾倒子线程对话记录。

安全

• 绝不在父线程和子线程中同时修改同一项工作。
• 如果存在线程工具，父线程状态中没有持久子线程 ID 时，绝不开始实现。
• 绝不将隐藏工作者或子 Agent 的 ID 视为编排器子线程。
• 绝不允许两个会修改代码的子线程并发修改同一个检出目录。
• 未检查独立性、槽位表、数据策略、运行时负责人和由父线程负责的合并计划前，绝不分派多个任务。
• 不要设置任意的并行工作流数量上限。启动每个可独立运行且具备安全槽位、数据策略、运行时负责人和持久子线程的工作流。
• 绝不强制推送。
• 一行即可解决的本地问题留在父线程中。
• 如果用户说 do it here、local 或 $orchestrator off，则在本地执行前关闭模式。

成功标准

• 模式可以启用、关闭和报告状态。
• 实施工作会自动分配。
• 每条实施工作线在修改前都有一个可见、持久的子线程和分配好的临时工作树。
• 后续工作复用同一检出目录或工作流线程。
• 缺少持久工具时会明确报告阻塞，而不是退而使用隐藏工作进程。
• 可独立运行的任务包可以并行展开，不受任意数量上限限制。
• 功能分支和 PR 均以 main 为目标。
• 运行时和数据所有权可避免工作线之间发生冲突。
• 推送和合并均经过协调与检查，且绝不强制执行。
• 合并或放弃的工作树会及时回收。
• 工作完成并关闭后，子线程会归档。
• 最终交接时，根检出目录会留在 main，否则会报告确切的阻塞原因。
• 编排器始终是协调线程，而非实施线程。