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

fix: 复用 agent

Browse Source
This commit is contained in:
laily
2026-07-15 01:29:56 +08:00
parent b3765ecad6
commit 8b82539f6f
5 changed files with 52 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
kits/ack/README.md
+7 -5
View File
@@ -107,26 +107,28 @@ ln -s <此框架绝对路径> <project>/docs/ack/kit
```text
我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范：
先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml；
先给我确认产品文档+任务拆分，再按 project.md 校验并启动 DEV/TEST worker，核对实际模型后循环派发/复测/终检；
先给我确认产品文档+任务拆分，再按 project.md 优先复用空闲 DEV/TEST worker，没有时才校验并创建，核对实际模型后循环派发/复测/终检；
每个任务最多三轮，三轮不过记 leftover。
```
### 校验并启动 worker
### 复用或启动 worker
先按 `core/orca-adapter.md` §「解析并复用 worker」运行 `terminal list` 和活跃任务查询。只有没有同 worktree、同角色、配置兼容的空闲 worker 时，才执行下面的创建命令：
```bash
DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium'
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
python3 docs/ack/validate_worker_command.py --role developer --command "$DEV_CMD"
python3 docs/ack/validate_worker_command.py --role test --command "$TEST_CMD"
orca terminal create --worktree active --command "$DEV_CMD" --title "DEV" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "TEST" --json
orca terminal create --worktree active --command "$DEV_CMD" --title "ACK-DEV-CODEX-TERRA-1" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json
# Cursor worker 使用同一项目校验器
CURSOR_CMD='cursor-agent --yolo --model auto'
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"
```
需要隔离/并行时先建 worktree：`orca worktree create --name <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
派发成功后把实际 handle 写入任务的 `dispatch.worker`，下次优先复用。需要隔离/并行时先建 worktree：`orca worktree create --name <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
### 派发与等待（Orca）
kits/ack/adoption-checklist.md
+1
View File
@@ -41,6 +41,7 @@
- [ ] 决定用 Orca（`kit/core/orca-adapter.md`）还是手动模式（`kit/core/closed-loop.md`）。
- [ ] Orca：`orca status`、`terminal list` 可用，Coordinator / Developer / Test 三个终端都在，回报能发回 Coordinator。
- [ ] 派发前会先查空闲 worker：按 `ACK-<ROLE>-<CLI>-<TIER>-<N>` 复用同 worktree、同角色、同配置终端；仅在不存在或都 busy 时新建，并把实际 handle 写入 `dispatch.worker`。
- [ ] 决定子任务放当前 worktree 起子 agent，还是新建隔离 worktree（决策速查见 `kit/core/closed-loop.md` §「子任务放哪」）。
- [ ] 多 worktree 时确认 `tasks.yaml`（SSOT）只保留一个权威副本，由 Coordinator 单写。
kits/ack/core/closed-loop.md
+7 -5
View File
@@ -29,7 +29,7 @@
Coordinator 发现或读取 open 任务
-> prepare：写/补全 tasks.yaml 验收信号
-> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
-> 起 worker：先按项目覆盖层校验命令，再按档位和执行模式建 worker 终端（见 model-routing.md）
-> 解析 worker：先复用同 worktree、同角色的空闲 worker；没有可复用项时才校验命令并新建（见 orca-adapter.md）
-> dispatch 给 Developer（--to <worker handle>）
-> wait：Developer 的 worker_done / escalation
-> writeback fixed_by_dev
@@ -43,7 +43,7 @@ Coordinator 发现或读取 open 任务
```
一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
「决定 worktree」「起 worker」两步的决策见下节与 `model-routing.md` / `orca-adapter.md`。
「决定 worktree」「解析 worker」两步的决策见下节与 `model-routing.md` / `orca-adapter.md`。
---
@@ -51,10 +51,11 @@ Coordinator 发现或读取 open 任务
Coordinator 派发前先决定 Developer/Test 在哪工作。两种方式：
**方式 1：当前 worktree 起子 agent（终端）**
**方式 1：当前 worktree 复用或起子 agent（终端）**
```bash
orca terminal create --worktree active --command "cursor-agent --yolo --model auto" --json
# 先按 orca-adapter.md 的 worker 复用流程查找空闲终端；没有时才创建
orca terminal create --worktree active --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
```
- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
@@ -65,7 +66,8 @@ orca terminal create --worktree active --command "cursor-agent --yolo --model au
```bash
orca worktree create --name <feature> --base-branch <base> --json
# 然后在新 worktree 内 orca terminal create --worktree path:<new> --command "cursor-agent --yolo --model auto"
# 然后先查该 worktree 的同角色空闲终端；没有时才创建
orca terminal create --worktree path:<new> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1"
```
- 适合：并行多个互不依赖的子任务、大/高风险/实验性改动、要保持基线分支干净（如 prod 不动、feature 走独立分支）、要独立 build 或跑独立服务实例、best-of-N 尝试。
kits/ack/core/kickoff.md
+6 -6
View File
@@ -50,9 +50,9 @@ python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
---
## 第 3 步：校验并启动 worker
## 第 3 步：复用或启动 worker
先读 `docs/ack/project.md` 的项目覆盖规则。如果项目提供 `validate_worker_command.py`，校验未通过时不得创建终端。
先读 `docs/ack/project.md` 的项目覆盖规则，再按 `orca-adapter.md` §「解析并复用 worker」执行：先列出现有终端和活跃任务，优先复用同 worktree、同角色、配置兼容且空闲的 worker。只有没有可复用项时才创建新终端；如果项目提供 `validate_worker_command.py`，校验未通过时不得创建。
```bash
# Codex 示例（模型与执行模式以项目覆盖层为准）
@@ -60,16 +60,16 @@ DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c mo
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
python3 docs/ack/validate_worker_command.py --role developer --command "$DEV_CMD"
python3 docs/ack/validate_worker_command.py --role test --command "$TEST_CMD"
orca terminal create --worktree active --command "$DEV_CMD" --title "DEV" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "TEST" --json
orca terminal create --worktree active --command "$DEV_CMD" --title "ACK-DEV-CODEX-TERRA-1" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json
# Cursor 示例
CURSOR_CMD='cursor-agent --yolo --model auto'
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"
orca terminal create --worktree active --command "$CURSOR_CMD" --title "DEV" --json
orca terminal create --worktree active --command "$CURSOR_CMD" --title "ACK-DEV-CURSOR-AUTO-1" --json
```
新 worktree 时先 `orca worktree create --name <feature> --base-branch <base>`，再在其中起终端。选型与升级见 `model-routing.md`。终端启动后、dispatch 前必须读取启动信息，确认实际 CLI、模型和 reasoning effort。
上面的 `terminal create` 都是“没有空闲兼容 worker”时的兜底，不是每次 kickoff 的固定动作。新 worktree 时先 `orca worktree create --name <feature> --base-branch <base>`，再解析该 worktree 的 worker。选型与升级见 `model-routing.md`。新建终端后、dispatch 前必须读取启动信息，确认实际 CLI、模型和 reasoning effort；派发后把实际 handle 写入对应任务的 `dispatch.worker`。
---
kits/ack/core/orca-adapter.md
+31 -7
View File
@@ -27,6 +27,30 @@ orca orchestration inbox --limit 20 --json
---
## 解析并复用 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 会过期。
复用决策：
| 情况 | 动作 |
|------|------|
| 任务已记录 worker，且该 handle 存活、兼容、空闲 | 优先复用原 handle |
| 有其它同 worktree、同角色、兼容的空闲 worker | 复用该 handle |
| 同角色 worker 存在但都 busy | 创建下一编号的临时并发 worker |
| worker 已关闭、断开或不存在 | 创建新 worker |
| 模型升级或 worktree 不同 | 不复用不兼容 worker，创建对应档位/路径的新 worker |
---
## 给 worker 终端固定模型
**编排层不设模型。** `task-create` / `dispatch` 都没有 `--model`；`dispatch --to <handle>` 只是把任务投给一个已存在的终端，用的是那个终端里 agent 会话启动时的模型。要固定模型，就在 **创建 worker 终端** 时用 agent CLI 的模型参数：
@@ -36,35 +60,35 @@ orca orchestration inbox --limit 20 --json
```bash
# Cursor：Test / Developer worker 用 auto 模型，并按项目要求启用 YOLO
orca terminal create --worktree path:<dev_worktree> \
--command "cursor-agent --yolo --model auto" --title "DEV" --json
--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 "DEV" --json
--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 "DEV" --json
--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 "TEST" --json
--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 "DEV-STRONG" --json
--title "ACK-DEV-CODEX-SOL-1" --json
```
拿到返回的 handle 后再 `task-create` + `dispatch --to <handle>`。模型档位与选型策略见 `model-routing.md`。
这些创建命令只在复用流程找不到空闲兼容 worker 时执行。拿到返回的 handle 后再 `task-create` + `dispatch --to <handle>`，并把 handle 写入 `tasks.yaml` 的 `dispatch.worker`。模型档位与选型策略见 `model-routing.md`。
需要隔离/并行时，先建新 worktree 再在其中起 worker（是否新建见 `closed-loop.md` §「子任务放哪」）：
```bash
orca worktree create --name <feature> --base-branch <base> --json
orca terminal create --worktree path:<new_worktree> --command "cursor-agent --yolo --model auto" --json
orca terminal create --worktree path:<new_worktree> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
```
- `cursor-agent --list-models` 可列出合法模型；`auto` 表示由 Cursor 自动选型。