ace
47bd454fa3
- skills/builder: SKILL.md, README.md, references/contract.md (make/publish contract v1), references/registry.md - scripts/check.py: executable contract checker (make dry-run probes, secret scan, push thin-wrapper and script path checks; --build verifies real .deb) - scripts/upload_deb.sh: migrated from deb-publisher, adds project .env auto-load and dirty-worktree publish gate - scripts/publish_docker.sh: migrated from publish-docker-image publish.sh, now env-first (DOCKER_REGISTRY/REPOSITORY/IMAGE_TAG/PLATFORMS), refuses floating latest and multi-platform --load - scripts/verify_deb.sh: metadata/content/sha256 verification with v-prefix normalization - orc: deb+docker stages both route to $builder; routing table, DAGs, README, config untouched stage names; tests updated - ack delivery.md + skiff source-model.md: reference builder - remove skills/deb-publisher and skills/publish-docker-image
180 lines
12 KiB
Markdown
180 lines
12 KiB
Markdown
---
|
||
name: orc
|
||
description: >-
|
||
作为薄路由器显式识别开发、源码版本发布、DEB 和 Docker 意图，把阶段分发给对应
|
||
Skill，并按静态规则选择 low、mid、high 执行档位。仅在用户显式调用 $orc 或 /orc，
|
||
要求跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。
|
||
---
|
||
|
||
# ORC 工程编排入口
|
||
|
||
当前会话担任薄路由器（Thin Coordinator）：只识别阶段、宿主 CLI、静态档位、依赖和
|
||
授权边界，然后派发 worker、转发决策门并汇总结构化状态。ORC 不做领域判断，不替代
|
||
下游 Skill 执行、分析或复核其领域流程。
|
||
|
||
开始时解析当前 `SKILL.md` 所在目录，记为 `<orc-skill-dir>`；解析真实项目根目录，
|
||
优先使用 `git rev-parse --show-toplevel`。所有项目共享唯一配置
|
||
`<orc-skill-dir>/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 推理补全。
|
||
|
||
## 共享配置
|
||
|
||
`<orc-skill-dir>/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 的全局档位或模型时才编辑
|
||
`<orc-skill-dir>/config.yaml`。修改前说明它会影响所有项目；模型 ID 必须来自用户输入、
|
||
目标 CLI 的模型列表或其它可信配置，不能从任务文本猜测。修改后运行：
|
||
|
||
```bash
|
||
/usr/bin/python3 -I -S <orc-skill-dir>/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 <orc-skill-dir>/scripts/resolve_profile.py resolve \
|
||
--stage <stage> \
|
||
--project-root <absolute-project-root> \
|
||
--worktree <absolute-target-worktree> \
|
||
--host-cli <codex|cursor-agent> \
|
||
[--global-level <low|mid|high>] [--stage-level <low|mid|high>] \
|
||
[--model-auth <codex-login|openai|azure-openai|cursor-login|cursor-api-key>] \
|
||
[--remote-auth <exact-provider-or-transport>]
|
||
```
|
||
|
||
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 <path>`。不接受
|
||
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 的反向引用。
|