111 lines
5.6 KiB
Markdown
111 lines
5.6 KiB
Markdown
# ORC 的 Orca 适配
|
||
|
||
Orca 保存运行时任务、依赖、dispatch 和消息；ORC 保存稳定路由规则。不要在项目中
|
||
复制一份 Orca 运行时任务板。
|
||
|
||
## 运行前
|
||
|
||
```bash
|
||
orca status --json
|
||
orca orchestration task-list --json
|
||
orca orchestration inbox --limit 20 --json
|
||
```
|
||
|
||
确认 runtime 可达、orchestration 可用，并识别是否存在与当前请求相同的活跃任务。
|
||
恢复流程时复用身份匹配的 task；身份不明时不要猜测或清空全局状态。
|
||
|
||
## 解析安全启动计划
|
||
|
||
对每个阶段调用 `resolve_profile.py resolve`，同时传入规范绝对 `--project-root`、
|
||
`--worktree` 和从当前 Agent 系统身份确定的必填 `--host-cli`，以及本阶段精确的
|
||
`--model-auth`、`--remote-auth`。
|
||
resolver 始终读取 skill 内共享的 `config.yaml`，不接受项目配置路径。JSON 结果包含
|
||
选择来源、结构化 profile、认证选择、配置与 worktree identity、可信 Python/Agent
|
||
CLI/Orca executable、
|
||
`launchFingerprint`、固定 worker/launcher argv，以及完整的 `terminalCreateArgv` 和
|
||
`terminalCreateShellCommand`。
|
||
|
||
- 优先把返回的 `terminalCreateArgv` 原样交给 argv-capable 进程工具；若工具只接受 shell
|
||
字符串，则执行完整的 `terminalCreateShellCommand`。不得再插值、包引号或追加参数。
|
||
- `terminalCreateArgv` 的首项是 resolver 选定的绝对 Orca executable，不替换成裸
|
||
`orca` 或重新通过项目 `PATH` 查找。
|
||
- 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
|
||
- `remote-auth` 只表示显式注入的单一环境 token 或 SSH agent；默认 `none`，不为方便同时
|
||
暴露多组环境凭据。release worker 直接使用当前 shell 已有的 Git/Forge CLI 登录，
|
||
resolver 不读取 tea/gh/glab 配置，也不注入 credential helper。
|
||
- release 计划要求 `origin` 恰好一个 fetch URL 和一个 push URL，二者规范化后完全一致；
|
||
remote identity 会进入 fingerprint，并在实际 launch 时重新解析。独立 `pushurl`、多个
|
||
push URL、local/file remote 或带内嵌 HTTPS 凭据的 URL 都 fail closed。
|
||
- Codex release 计划固定使用 `on-request` + `auto_review`，开启 workspace-write 网络并启用
|
||
network proxy，只允许绑定的 remote 与确定性 Forge API host。GitHub 固定追加
|
||
`api.github.com` 和 `uploads.github.com`；其它本地阶段保持默认禁网。不得替换成
|
||
`danger-full-access`。Cursor 继续使用自身的 auto-review sandbox。
|
||
- resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
|
||
- 不从任务文本、可执行文件存在性或共享配置猜宿主；Codex 传 `--host-cli codex`，Cursor
|
||
传 `--host-cli cursor-agent`。宿主身份不明确时停止。
|
||
- 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册
|
||
或跨仓库的目标，并把身份写入 fingerprint。
|
||
- ORC v2 profile 必须使用 `workspace-write`。`read-only` sandbox 可能阻止 Orca CLI
|
||
写入自身运行时或挂载目录，导致 worker 无法发送 `worker_done`；只读工作通过 task
|
||
spec 限制，而不是换成无法完成 lifecycle 的 sandbox。
|
||
- Codex 与 Cursor 使用不同的固定 argv 适配器。Cursor 只允许 `--auto-review`、启用的
|
||
sandbox 和精确 workspace；不得把 Codex 参数套给 Cursor，也不得给 Cursor 追加
|
||
`--force` 或 `--yolo`。
|
||
|
||
## 创建与派发
|
||
|
||
每个需要 fresh worker 的阶段依次执行：
|
||
|
||
1. 使用解析结果创建目标 worktree 内的终端。下面整行代表 resolver 返回的一个完整值，
|
||
不是待替换的参数模板：
|
||
|
||
```bash
|
||
<resolver-terminalCreateShellCommand>
|
||
```
|
||
|
||
2. 使用返回的具体 handle 等待 Agent TUI 可接收输入：
|
||
|
||
```bash
|
||
orca terminal wait --terminal <handle> --for tui-idle \
|
||
--timeout-ms 60000 --json
|
||
```
|
||
|
||
3. 先为前置阶段创建 task，再用其 ID 构造依赖数组创建后置 task。task spec 使用
|
||
`routing.md` 的 worker prompt 契约。
|
||
4. 对已就绪 task 执行：
|
||
|
||
```bash
|
||
orca orchestration dispatch --task <task-id> --to <handle> --inject --json
|
||
```
|
||
|
||
不要把同一 task 同时派给多个写 worker。并行阶段必须使用不会竞争同一工作树写入的
|
||
独立 worker；否则串行执行。`terminal create` 超时或连接中断时状态不确定：先用
|
||
`terminalTitle`、worktree 和 fingerprint 核对 `orca terminal list --json`，没有完成
|
||
reconciliation 前不得重试创建。
|
||
|
||
## 监督循环
|
||
|
||
```bash
|
||
orca orchestration check --wait \
|
||
--types worker_done,escalation,decision_gate \
|
||
--timeout-ms 900000 --json
|
||
```
|
||
|
||
- timeout 或空结果是检查点，不等于失败；任务仍活跃时继续滚动等待。
|
||
- 收到 `decision_gate` 时只回答当前问题，不扩大用户授权。
|
||
- 收到 `escalation` 时保留已完成状态，判断是改档、补输入还是停止。
|
||
- 收到 `worker_done` 后核对 task/dispatch ID、下游完成证据和外部状态，再把依赖 task
|
||
标记完成并派发新就绪阶段。
|
||
- 三次连续同因失败后停止重派，报告恢复入口；不要用新终端掩盖同一阻塞。
|
||
|
||
## ACK 特例
|
||
|
||
`code` worker 是运行 `$ack` 的阶段 Coordinator。ORC 的 `low/mid/high` 只决定这个
|
||
worker 的启动 profile；ACK 启动 Developer/Test 时继续读取自己的项目配置与
|
||
`standard/strong` 规则。ORC 不读取、改写或覆盖 ACK 的内部 worker profiles。
|
||
|
||
## 收尾
|
||
|
||
不要自动关闭仍承担恢复入口的终端，不自动删除 worktree 或清空 runtime-global task。
|
||
只有用户明确要求清理时，才按 Orca 和下游 Skill 的安全规则处理。
|