96 lines
4.4 KiB
Markdown
96 lines
4.4 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`，以及本阶段精确的 `--model-auth`、`--remote-auth`。JSON 结果包含选择来源、
|
||
结构化 profile、认证选择、配置与 worktree identity、可信 Python/Codex/Orca executable、
|
||
`launchFingerprint`、固定 worker/launcher argv，以及完整的 `terminalCreateArgv` 和
|
||
`terminalCreateShellCommand`。
|
||
|
||
- 优先把返回的 `terminalCreateArgv` 原样交给 argv-capable 进程工具；若工具只接受 shell
|
||
字符串，则执行完整的 `terminalCreateShellCommand`。不得再插值、包引号或追加参数。
|
||
- `terminalCreateArgv` 的首项是 resolver 选定的绝对 Orca executable，不替换成裸
|
||
`orca` 或重新通过项目 `PATH` 查找。
|
||
- 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
|
||
- `remote-auth` 必须与本阶段唯一目标 provider/transport 一致；默认 `none`，不为方便
|
||
同时暴露多个 token 或 SSH agent。需要代理、额外凭据或 Docker registry env secret 时
|
||
fail closed，由用户确认新的最小权限适配，不继承 ambient proxy/credential 变量。
|
||
- resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
|
||
- 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册、
|
||
跨仓库或不在 allowlist 的目标，并把身份写入 fingerprint。
|
||
- ORC v1 profile 必须使用 `workspace-write`。`read-only` sandbox 可能阻止 Orca CLI
|
||
写入自身运行时或挂载目录，导致 worker 无法发送 `worker_done`；只读工作通过 task
|
||
spec 限制，而不是换成无法完成 lifecycle 的 sandbox。
|
||
|
||
## 创建与派发
|
||
|
||
每个需要 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 的安全规则处理。
|