laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ack): add structured worker model routing

Browse Source
This commit is contained in:
laily
2026-07-31 23:34:13 +08:00
parent ee66dbe9ce
commit ae3bce7b5d
23 changed files with 6491 additions and 327 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/ack/references/orca-adapter.md
+57 -53
View File
@@ -23,79 +23,83 @@ orca orchestration task-list --json
orca orchestration inbox --limit 20 --json
```
确认：Orca runtime 可达；Coordinator、Developer、Test 三个终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。
确认：Orca runtime 可达并取得本次 `runtimeId`；Coordinator 终端存在；当前没有冲突
的活跃编排任务。Developer/Test worker 必须通过本次 launcher 新建，不要求预先存在。
---
## 解析并复用 worker
## 既有 worker 的处理
**默认复用，创建是兜底。** 每次向 Developer 或 Test 派发前都先解析 worker，不能直接照后文示例执行 `terminal create`：
1. 运行 `orca terminal list --json`，筛选 `connected=true`、`writable=true`、目标 `worktreePath` 一致、标题角色和配置一致的终端。稳定标题使用 `ACK-<ROLE>-<CLI>-<TIER>-<N>`，例如 `ACK-DEV-CODEX-TERRA-1`、`ACK-TEST-CODEX-LUNA-1`、`ACK-DEV-CURSOR-AUTO-1`；强档示例为 `ACK-DEV-CODEX-SOL-1`。
2. 运行 `orca orchestration task-list --status dispatched --json`。若候选 handle 出现在活跃任务的 `assignee_handle`，视为 busy，不复用；不要仅凭终端预览文本或最近输出时间猜忙闲。
3. 对空闲候选运行 `orca terminal show --terminal <handle> --json`，确认仍存活且 worktree、角色和 Agent CLI / 模型档位符合本次要求。符合就直接把该 handle 作为 `dispatch --to` 的目标。
4. 只有不存在兼容的空闲候选时才创建。若同角色同配置已有 busy worker，使用下一个未占用序号，例如 `ACK-DEV-CODEX-TERRA-2`；不要创建另一个同名终端。
5. dispatch 成功后，把实际 handle 写入对应 `tasks.yaml` 条目的 `dispatch.worker`。下一轮先尝试该 handle；若它已消失、断开、不可写、worktree/角色/档位不兼容或正忙，再回到第 1 步选择其它 worker。
`tasks.yaml.dispatch.worker` 记录“这个任务实际用了谁”，便于续跑和审计；`orca terminal list` 记录“谁现在还活着”，是运行时存活状态的事实源。不要另建一份永久 worker 池，因为终端关闭后其中的 handle 会过期。
复用决策：
v0.10 **不自动复用任何既有终端**。`receiptHash` 是无密钥 checksum，Orca 当前的
terminal metadata 也不包含原始 Agent argv、模型或权限 attestation；两者即使完全
匹配，仍不足以证明旧终端由可信 launcher 以目标 profile 创建。标题、preview、分支
名或 worker 自报更不能作为证明。
| 情况 | 动作 |
|------|------|
| 任务已记录 worker，且该 handle 存活、兼容、空闲 | 优先复用原 handle |
| 有其它同 worktree、同角色、兼容的空闲 worker | 复用该 handle |
| 同角色 worker 存在但都 busy | 创建下一编号的临时并发 worker |
| worker 已关闭、断开或不存在 | 创建新 worker |
| 模型升级或 worktree 不同 | 不复用不兼容 worker，创建对应档位/路径的新 worker |
| 历史 receipt 与 live metadata 看似完全匹配 | 只作审计，不自动复用；重新 launch |
| 没有 receipt，或只有同名终端 | 不复用；重新 launch |
| 需要并发 worker | 使用下一 `slot` 重新 launch |
| Developer 升级模型档位 | 选择强档安全 profile，重新 plan/launch |
只有刚刚成功返回的 `launch` 标准输出中的 fresh handle，才可用于紧随其后的本次
dispatch。未来若 Orca/ACP 增加启动参数 attestation，或 ACK 接入项目外可信签发
通道，再单独设计自动复用；不能用项目文档声明跳过这条限制。
---
## 给 worker 终端固定模型
## 通过 launcher 创建 worker
**编排层不设模型。** `task-create` / `dispatch` 都没有 `--model`；`dispatch --to <handle>` 只是把任务投给一个已存在的终端，用的是那个终端里 agent 会话启动时的模型。要固定模型，就在 **创建 worker 终端** 时用 agent CLI 的模型参数：
**模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、
模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile
决定，并且只能由 ACK launcher 构造。
默认沿用 Coordinator 当前所在的 Agent CLI：Cursor Coordinator 创建 Cursor worker，Codex Coordinator 创建 Codex worker。不要通过询问模型来猜运行环境；以当前 CLI / 终端环境为准。除非项目 overlay 或用户明确指定，否则不跨 Agent CLI 创建 worker。
先只读生成计划：
```bash
# Cursor：Test / Developer worker 用 auto 模型，并按项目要求启用 YOLO
orca terminal create --worktree path:<dev_worktree> \
--command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
# 需要更强模型时改成具体模型
orca terminal create --worktree path:<dev_worktree> \
--command "cursor-agent --yolo --model claude-opus-4-8-thinking-high" --title "ACK-DEV-CURSOR-STRONG-1" --json
# Codex：Developer worker
orca terminal create --worktree path:<dev_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium" \
--title "ACK-DEV-CODEX-TERRA-1" --json
# Codex：Test worker
orca terminal create --worktree path:<test_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low" \
--title "ACK-TEST-CODEX-LUNA-1" --json
# Codex：复杂 Developer 任务升级
orca terminal create --worktree path:<dev_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-sol -c model_reasoning_effort=high" \
--title "ACK-DEV-CODEX-SOL-1" --json
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
--project-root <project-root> --task-id <task-id> \
--attempt-id <task-id>-A<round> --role <developer-or-test> \
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
```
这些创建命令只在复用流程找不到空闲兼容 worker 时执行。拿到返回的 handle 后再 `task-create` + `dispatch --to <handle>`，并把 handle 写入 `tasks.yaml` 的 `dispatch.worker`。模型档位与选型策略见 `model-routing.md`。
需要隔离/并行时，先建新 worktree 再在其中起 worker（是否新建见 `closed-loop.md` §「子任务放哪」）：
确认计划中的任务、attempt、角色、profile hash、绝对 worktree 和安全权限模式后，再
执行唯一启动入口：
```bash
orca worktree create --name <feature> --base-branch <base> --json
orca terminal create --worktree path:<new_worktree> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
--project-root <project-root> --task-id <task-id> \
--attempt-id <task-id>-A<round> --role <developer-or-test> \
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
--expected-launch-fingerprint <plan 中的 sha256:...>
```
- `cursor-agent --list-models` 可列出合法模型；`auto` 表示由 Cursor 自动选型。
- Codex 用 `-m / --model` 指定模型，用 `-c model_reasoning_effort=<effort>` 固定推理档位；不要把省略 `-m` 当作 Cursor `auto` 的等价物。
- 本项目要求 Cursor worker 带 `--yolo`，Codex worker 带 `--dangerously-bypass-approvals-and-sandbox`；创建前先运行项目覆盖层指定的校验器。
- 其它 CLI（opencode 等）用各自的模型参数或配置，`--command` 相应替换。
- 若 worker 是已在跑的会话（用 `--inject` 投递），模型已由该会话启动时决定，无法在 dispatch 时改；要换模型需新建终端。
`launch` 必须携带刚才审阅的 `plan.launchFingerprint`；若 profile、任务/attempt、
worktree、CLI identity/version 或精确 argv 漂移，创建前就失败。它内部调用当前
Orca 后端并完成终端绑定；Coordinator 不自行执行或拼装 Orca 的底层终端创建文本，
也不直接调用 launcher 的私有 bootstrap。
若 launcher 报告 `indeterminate` 或 `reconcile required`，说明终端可能已经创建且
持久关闭尚未得到可信确认；此时先按返回的 launch ID/record 和 Orca live state
人工核对，禁止直接重复执行 `launch`。
标准输出是单一 JSON。成功后：
1. 校验返回 receipt 的 `receiptHash`；
2. 把 receipt 原样追加到 `tasks.yaml.workerReceipts`；
3. 把 `receipt.id` 写入当前任务 `dispatch.<role>.receiptId`，把 `profileId` 写入
`dispatch.<role>.profileId`，把本轮 `<task-id>-A<round>` 写入
`dispatch.<role>.attemptId`；校验器会要求 receipt 的 task/role/profile/attempt
与当前 ACK 任务完全一致；
4. 再用 receipt binding 中的 handle 创建/派发 Orca 子任务。
profile 只允许 `read-only` 或 `workspace-write`。v0.10 不提供可信的 full-access 授权
通道；bypass、YOLO/force、关闭 sandbox 及其它 full-access 请求必须由 schema 和
launcher fail closed，不能改用手写命令兜底。模型档位与升级规则见
`model-routing.md`。
需要隔离/并行时，可以先用 Orca 创建 worktree。Coordinator 必须先把返回的绝对
路径加入 `project.orchestration.allowedWorktrees` 并重新校验 `tasks.yaml`，然后才在
该路径上走 `plan` -> 带 expected fingerprint 的 `launch`，并把 receipt 留作审计。
既有会话可以由用户直接操作，但不能进入 ACK v0.10 的自动派发信任路径。
---