laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6855ac7078fe6dd5f075273f933ae76f53570d71
.pouch/skills/orc/SKILL.md
T

12 KiB
Raw Blame History

name, description
name description
orc 作为薄路由器显式识别开发、源码版本发布、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 的模型列表或其它可信配置，不能从任务文本猜测。修改后运行：

/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、deb-publisher、 publish-docker-image。只检查实际会用到的项。
  5. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标是 当前 Git 仓库已注册的 worktree 且身份稳定后才可创建终端。不得只做文本比较或跳过 机器校验。
  6. 任何 profile、CLI、Skill、运行时或 worktree 不可用时 fail closed；不得切换其它 CLI、 相邻档位、复用身份不明的终端或手写替代流程。

编排

  1. 读取 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：

    /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，把阶段组织为 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 构建或上传交给 $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 的独立阶段负责。
  • 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 的反向引用。

Reference in New Issue View Git Blame Copy Permalink