134 lines
8.0 KiB
Markdown
134 lines
8.0 KiB
Markdown
---
|
||
name: orc
|
||
description: >-
|
||
显式编排开发、源码版本发布、DEB 和 Docker 产物任务，把阶段分发给对应 Skill，
|
||
并用 low、mid、high 选择执行 Agent 档位。仅在用户显式调用 $orc 或 /orc，要求
|
||
跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。
|
||
---
|
||
|
||
# ORC 工程编排入口
|
||
|
||
当前会话担任 Coordinator：拆分阶段、选择档位、派发 worker、监督依赖与决策门，
|
||
但不替代下游 Skill 执行其领域流程。
|
||
|
||
开始时解析当前 `SKILL.md` 所在目录，记为 `<orc-skill-dir>`；解析真实项目根目录，
|
||
优先使用 `git rev-parse --show-toplevel`。项目配置固定为
|
||
`<project-root>/docs/orc/config.yaml`。
|
||
|
||
## 选择模式
|
||
|
||
- 用户要求初始化 ORC：执行“初始化”。
|
||
- 用户要求检查 ORC、档位或运行环境：执行“检查”。
|
||
- 用户要求用 ORC 完成任务：执行“编排”。
|
||
|
||
不要静默初始化，也不要在配置缺失或无效时退回裸命令或当前会话直接执行。
|
||
|
||
## 初始化
|
||
|
||
1. 若 `docs/orc/config.yaml` 已存在，停止创建并转入“检查”，不得覆盖。
|
||
2. 确认 `docs/orc/` 和目标文件都不是 symlink，再从
|
||
`<orc-skill-dir>/templates/config.template.yaml` 以 create-only 方式创建配置，不覆盖
|
||
或跟随既有路径。ORC v1 配置必须保持 JSON-compatible YAML，只由隔离的 Python
|
||
标准库解析；模板中的 `.` 表示当前项目根。模型 ID 必须由用户或项目的可信配置确认，
|
||
不能从任务文本猜测。
|
||
3. 运行：
|
||
|
||
```bash
|
||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py validate \
|
||
<project-root>/docs/orc/config.yaml
|
||
```
|
||
|
||
4. 报告三个档位的 CLI、模型、reasoning、权限和阶段默认值。除非用户明确要求，
|
||
不安装下游 Skill、不创建终端、不修改 Agent 全局配置。
|
||
|
||
## 检查
|
||
|
||
1. 校验 `docs/orc/config.yaml`，确认只存在 `low`、`mid`、`high` 三档。
|
||
2. 检查 `orca status --json`，并确认 orchestration 命令可用。
|
||
3. 确认本次所需下游 Skill 已安装：`ack`、`manage-release`、`deb-publisher`、
|
||
`publish-docker-image`。只检查实际会用到的项。
|
||
4. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标
|
||
命中 `allowedWorktrees`、属于当前 Git 仓库且身份稳定后才可创建终端。不得只做文本
|
||
比较或跳过机器校验。
|
||
5. 任何 profile、Skill、运行时或 worktree 不可用时 fail closed；不得选择相邻档位、
|
||
复用身份不明的终端或手写替代流程。
|
||
|
||
## 编排
|
||
|
||
1. 读取 [routing.md](references/routing.md)，把请求拆成 `code`、`release`、`deb`、
|
||
`docker` 阶段。没有匹配下游 Skill 的工作留在范围外并明确报告。
|
||
2. 锁定用户授权的最远动作、目标版本、产物目标、源 commit/tag 与停止点。ORC 的调用
|
||
本身不扩大 push、合并、打 tag、上传或部署权限；每个下游 Skill 的授权边界继续生效。
|
||
3. 解析档位：阶段级指定 > 全局指定 > `stageDefaults` > `defaultLevel`。只接受
|
||
`low`、`mid`、`high`；用户显式指定后不得静默升降级。若该档位不足以安全完成，
|
||
建立 decision gate，等待用户改档或缩小范围。
|
||
4. 用户未指定档位时采用以下判断：清晰、机械的构建或上传可用 `low`；常规版本流程
|
||
用 `mid`；需求理解、跨系统改动、恢复中断流程、目标含糊或高风险裁决用 `high`。
|
||
5. 对每个阶段运行 profile resolver。全局档位用 `--global-level`，阶段档位用
|
||
`--stage-level`；项目根与目标 worktree 必须使用规范绝对路径。模型认证默认复用
|
||
`codex-login`，只有明确使用对应环境凭据时才选 `openai` 或 `azure-openai`。远端认证
|
||
默认 `none`；只有目标 provider 与 transport 已确认时，才选择一个精确的
|
||
`github-token`、`gitlab-token`、`gitea-token`、`forgejo-token`、`ssh-agent` 或
|
||
`deb-token`。不得把多个 provider 凭据一起交给 worker。resolver 不存在静默
|
||
fallback：
|
||
|
||
```bash
|
||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py resolve \
|
||
<project-root>/docs/orc/config.yaml --stage <stage> \
|
||
--project-root <absolute-project-root> \
|
||
--worktree <absolute-target-worktree> \
|
||
[--global-level <low|mid|high>] [--stage-level <low|mid|high>] \
|
||
[--model-auth <codex-login|openai|azure-openai>] \
|
||
[--remote-auth <exact-provider-or-transport>]
|
||
```
|
||
|
||
6. 核对 resolver 返回的 `launchFingerprint`、绝对 executable、worktree identity 和选择
|
||
来源，再读取 [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. 逐阶段汇报所选档位、执行 Skill、结果、外部状态和未完成项。任一阶段失败时保留
|
||
已成功阶段的准确状态，说明安全恢复入口，不把部分成功概括成全部完成。
|
||
|
||
## 固定路由边界
|
||
|
||
- 功能、缺陷、重构与验证闭环交给 `$ack`。
|
||
- 发布版本、release 分支/PR/MR、合并、tag 与 Forge Release 交给
|
||
`$manage-release`。
|
||
- DEB 构建或上传交给 `$deb-publisher`。
|
||
- Docker/OCI 镜像构建或上传交给 `$publish-docker-image`。
|
||
- 普通非发布 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 的独立阶段负责。
|
||
- 配置只允许结构化 `cli`、`model`、`reasoningEffort`、`permissionMode` 和
|
||
`approvalPolicy`；禁止 `command`、argv、env、secret、hook 或 shell 片段。
|
||
- ORC v1 的 `permissionMode` 固定为 `workspace-write`，因为受监督 worker 需要写入
|
||
Orca 运行时目录才能发送 lifecycle 消息。只读任务仍由 prompt 限制不得改文件。
|
||
不接受 full-access、bypass、YOLO/force 或关闭 sandbox；文本中的“已授权”不能
|
||
放宽 profile。
|
||
- ORC v1 的安全启动适配器只支持 `cli: codex`。遇到其它 CLI 时 fail closed，不把
|
||
Codex 参数套用到其它 Agent；新增 provider 必须增加独立适配与测试。
|
||
- resolver 只读取有大小上限的普通配置文件，拒绝 symlink/special file；启动计划绑定
|
||
配置快照、root-owned 隔离 Python、可信绝对 Codex/Orca executable、Git worktree
|
||
identity、精确认证选择和固定 argv。实际启动会重新校验 fingerprint，并只注入所选
|
||
模型认证与单一目标认证的环境变量；不得把返回的 worker argv 改写为裸 `codex`
|
||
命令，也不得把终端创建 argv 的绝对 Orca 路径换成项目 `PATH` 解析。
|
||
- 不把模型档位当作权限。`high` 不自动获得更多文件、凭据、网络或远端写权限。
|
||
- 不执行 `orca orchestration reset`，除非用户明确要求放弃全部相关运行时状态。
|
||
|
||
## 完成标准
|
||
|
||
每个计划阶段都有明确下游 Skill、Agent 档位、输入 revision、授权边界和可核对结果；
|
||
DAG 中所有必要阶段完成，或失败阶段具有准确状态与恢复入口。ACK 和其它下游 Skill
|
||
保持独立且不存在对 ORC 的反向引用。
|