--- name: orc description: >- 作为薄路由器显式识别开发、源码版本发布、DEB 和 Docker 意图，把阶段分发给对应 Skill，并按静态规则选择 low、mid、high 执行档位。仅在用户显式调用 $orc 或 /orc， 要求跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。 --- # ORC 工程编排入口 当前会话担任薄路由器（Thin Coordinator）：只识别阶段、宿主 CLI、静态档位、依赖和 授权边界，然后派发 worker、转发决策门并汇总结构化状态。ORC 不做领域判断，不替代 下游 Skill 执行、分析或复核其领域流程。 开始时解析当前 `SKILL.md` 所在目录，记为 ``；解析真实项目根目录， 优先使用 `git rev-parse --show-toplevel`。所有项目共享唯一配置 `/config.yaml`，不得在项目中创建 `docs/orc/config.yaml` 或其它配置副本。 ## 选择模式 - 用户要求初始化 ORC：说明 ORC 已改为共享配置、不需要项目初始化，然后执行“检查”。 - 用户要求检查 ORC、CLI、档位或运行环境：执行“检查”。 - 用户明确要求修改 ORC 的共享模型或档位默认值：执行“修改共享配置”。 - 用户要求用 ORC 完成任务：执行“编排”。 配置或运行时无效时 fail closed，不退回裸命令或当前会话直接执行。 ## 薄路由器边界 ORC 只执行以下机械步骤： 1. 把用户明确表达的意图映射到 `code`、`release`、`deb`、`docker`。 2. 从系统身份映射宿主 CLI，并按显式覆盖或共享配置解析档位。 3. 根据固定路由表建立任务依赖，生成满足契约的 worker prompt 并派发。 4. 转发 `decision_gate` / `escalation`，按下游 Skill 的完成证据汇总状态。 不得阅读项目实现来形成技术判断，不得决定版本号、实现方案、测试策略、发布风险、 合并方式或产物策略，不得代替 worker 执行命令。意图无法映射时报告范围外；缺少派发所需 的关键输入时建立 decision gate。领域问题原样交给对应下游 Skill，不由 ORC 推理补全。 ## 共享配置 `/config.yaml` 是 ORC profile 的 SSOT，对所有项目生效。配置使用 JSON-compatible YAML，并由隔离的 Python 标准库解析。它固定包含： - `cliPolicy: current-host`：Codex 宿主只启动 Codex worker，Cursor 宿主只启动 Cursor worker。 - `defaultLevel` 与 `stageDefaults`：只用于下游 worker 的 `low`、`mid`、`high` 默认选择， 不表示 ORC Coordinator 自身的模型档位。 - `worktreePolicy: registered-same-repository`：允许当前仓库中已注册且身份一致的 worktree。 - `profiles.codex` 与 `profiles.cursor-agent`：两个 CLI 各自完整的三档 profile。 不要把项目路径、命令、argv、环境变量、secret、hook 或 shell 片段写入共享配置。 旧项目若残留 `docs/orc/config.yaml`，resolver 会忽略它；没有用户明确清理授权时不要删除。 ## 修改共享配置 只有用户明确要求修改 ORC 的全局档位或模型时才编辑 `/config.yaml`。修改前说明它会影响所有项目；模型 ID 必须来自用户输入、 目标 CLI 的模型列表或其它可信配置，不能从任务文本猜测。修改后运行： ```bash /usr/bin/python3 -I -S /scripts/resolve_profile.py validate ``` 报告两个 CLI 的三个档位、reasoning、权限策略、阶段默认值和宿主 CLI 策略。不要创建 项目配置。 ## 检查 1. 运行共享配置校验，确认 `codex` 和 `cursor-agent` 都完整配置 `low`、`mid`、`high`。 2. 检查 `orca status --json`，并确认 orchestration 命令可用。 3. 从当前 Agent 的系统身份确定宿主 CLI：Codex 映射为 `codex`，Cursor 映射为 `cursor-agent`。身份不明确时停止，不从用户任务文本、默认值或已安装 executable 猜测。 确认宿主 CLI 可用；在 Cursor 中还要用 `cursor-agent --list-models` 核对精确模型 ID 对当前账号可见。 4. 确认本次所需下游 Skill 已安装：`ack`、`manage-release`、`builder`。只检查实际 会用到的项；`deb` 与 `docker` 阶段都由 `$builder` 承载。 5. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标是 当前 Git 仓库已注册的 worktree 且身份稳定后才可创建终端。不得只做文本比较或跳过 机器校验。 6. 任何 profile、CLI、Skill、运行时或 worktree 不可用时 fail closed；不得切换其它 CLI、 相邻档位、复用身份不明的终端或手写替代流程。 ## 编排 1. 读取 [routing.md](references/routing.md)，把请求拆成 `code`、`release`、`deb`、 `docker` 阶段。没有匹配下游 Skill 的工作留在范围外并明确报告。 2. 原样提取用户明确给出的授权最远动作、目标版本、产物目标、源 commit/tag 与停止点； 未给出的领域参数保持未指定并交给下游 Skill。ORC 的调用本身不扩大 push、合并、 打 tag、上传或部署权限。 3. 从系统身份锁定当前宿主 CLI。运行在 Codex 时传 `--host-cli codex`；运行在 Cursor 时传 `--host-cli cursor-agent`。宿主 CLI 不是任务选项，即使用户文本点名另一个 CLI 也不得 跨宿主启动；身份不明确时 fail closed。 4. 解析档位：阶段级指定 > 全局指定 > `stageDefaults` > `defaultLevel`。只接受 `low`、`mid`、`high`；用户显式指定后不得静默升降级。ORC 不根据任务复杂度动态判断 档位；worker 报告能力不足时，只转发 escalation 或 decision gate。 5. 对每个阶段运行 profile resolver。宿主用必填的 `--host-cli`，全局档位用 `--global-level`，阶段 档位用 `--stage-level`；项目根与目标 worktree 必须使用规范绝对路径。Codex 默认复用 `codex-login`，Cursor 默认复用 `cursor-login`；只有明确使用环境凭据时才分别选择 `openai`、`azure-openai` 或 `cursor-api-key`。远端认证默认 `none`。release worker 作为 受信任发布角色，直接调用当前 shell 中已认证的 `git` 与 Forge CLI；Gitea/Forgejo 由 `$manage-release` 在目标 worktree 中运行 `tea`，resolver 不读取 tea 配置、不注入 credential helper，也不把 tea token 转成环境变量。只有明确改用环境 token 或 SSH agent 时，才选择一个精确的 `github-token`、`gitlab-token`、`gitea-token`、 `forgejo-token`、`ssh-agent` 或 `deb-token`，不得同时交给 worker 多组环境凭据。resolver 不存在静默 fallback： ```bash /usr/bin/python3 -I -S /scripts/resolve_profile.py resolve \ --stage \ --project-root \ --worktree \ --host-cli \ [--global-level ] [--stage-level ] \ [--model-auth ] \ [--remote-auth ] ``` 6. 核对 resolver 返回的 `launchFingerprint`、绝对 executable、worktree identity、CLI 与 档位选择来源，再读取 [orca-adapter.md](references/orca-adapter.md)，把阶段组织为 Orca task DAG。worker prompt 必须显式写出对应 `$skill`、阶段范围、输入 revision、用户授权 边界、验收证据和依赖结果；下游 Skill 无需知道 ORC。 7. 监督 `worker_done`、`escalation` 与 `decision_gate`。`worker_done` 只代表该 worker 回报完成；Coordinator 只核对下游 Skill 声明的证据字段和 DAG 后置条件，不重新进行 领域审查。 8. 逐阶段汇报所选 CLI、档位、执行 Skill、结果、外部状态和未完成项。任一阶段失败时 保留已成功阶段的准确状态，说明安全恢复入口，不把部分成功概括成全部完成。 ## 固定路由边界 - 功能、缺陷、重构与验证闭环交给 `$ack`。 - 发布版本、release 分支/PR/MR、合并、tag 与 Forge Release 交给 `$manage-release`。 - DEB 构建或上传交给 `$builder`（deb 阶段）；Docker/OCI 镜像构建或上传也交给 `$builder`（docker 阶段）。 - 普通非发布 PR/MR 不伪装成版本发布；只有 ACK 已验证交付或明确的 release 流程才 进入对应下游能力。 ## 依赖与安全边界 - 依赖始终单向：`orc -> 下游 Skill`。不得要求 ACK 或其它下游 Skill 引用 ORC、读取 ORC 配置或改变自身触发规则。 - ORC 档位只选择阶段 worker。进入 `$ack` 后，ACK 自己的 Coordinator、Developer、 Test 角色和 `standard/strong` 模型路由仍完全由 ACK 管理。 - ORC 的 `code` 阶段必须锁定停止点：纯开发停在 ACK `verified`；用户明确要求普通 PR/MR 时最多到 ACK `review_ready`。不得让 ACK 在同一阶段继续执行版本发布、DEB、 Docker 或部署；这些动作由 ORC 的独立阶段负责。 - ORC v2 的 `permissionMode` 固定为 `workspace-write`，因为受监督 worker 需要写入 Orca 运行时目录才能发送 lifecycle 消息。只读任务仍由 prompt 限制不得改文件。 - release 阶段必须绑定 `origin` 唯一且规范化后完全一致的 fetch/push URL，并把 remote identity 写入 fingerprint；多个 URL、独立 `pushurl` 或不支持的 remote 直接停止。 - Codex release worker 固定使用 `on-request` 与 `auto_review`，开启 `sandbox_workspace_write.network_access=true`，并用 network proxy 只允许绑定的 remote 与确定性的 Forge API host。GitHub 固定追加 `api.github.com` 和 `uploads.github.com`； Gitea、Forgejo 与 GitLab 默认只使用 remote host。其它本地阶段默认禁网；不得改用 `danger-full-access`。Cursor 继续使用自身的 `--auto-review --sandbox enabled`。 - 安全启动适配器只支持 `codex` 和 `cursor-agent`。Codex 使用结构化 sandbox 与 approval 参数；Cursor 使用 `--auto-review --sandbox enabled --workspace `。不接受 full-access、bypass、`--force`、`--yolo` 或关闭 sandbox。 - `cliPolicy` 固定为 `current-host`，resolver 不提供默认 CLI；漏传宿主身份会直接失败， 不得从共享配置回退到 Codex 或 Cursor。 - Cursor 的 reasoning 档位编码在精确模型 ID 中，因此其 `reasoningEffort` 必须为 null； Codex 则显式传递 `model_reasoning_effort`。 - resolver 只读取 skill 内有大小上限的普通共享配置文件，拒绝 symlink/special file； 启动计划绑定配置快照、root-owned 隔离 Python、可信绝对 Agent/Orca executable、Git worktree identity、release remote identity、精确环境认证选择和固定 argv。实际启动会 重新校验 fingerprint；release 阶段允许受信任的 `$manage-release` 直接使用当前 shell 已有的 Git/Forge 登录，resolver 不检查或复制认证文件。显式 token/SSH 认证仍只注入所选 环境变量。不得改写 resolver 返回的 worker argv，也不得把终端创建 argv 的绝对 Orca 路径换成项目 `PATH` 解析。 - 不把模型档位当作权限。`high` 不自动获得更多文件、凭据、网络或远端写权限。 - 不执行 `orca orchestration reset`，除非用户明确要求放弃全部相关运行时状态。 ## 完成标准 每个计划阶段都有明确下游 Skill、Agent CLI、档位、输入 revision、授权边界和可核对结果； DAG 中所有必要阶段完成，或失败阶段具有准确状态与恢复入口。ACK 和其它下游 Skill 保持独立且不存在对 ORC 的反向引用。