feat(ack): support project agent routing overrides

2026-09-19 17:52:14 +08:00
parent 44cee4be91
commit f469c8f5f5
25 changed files with 746 additions and 83 deletions
@@ -10,6 +10,8 @@
      `project.knowledgeFile` 指针，没有重跑初始化或覆盖其它项目状态。
 - [ ] 项目中没有 ACK Skill 的复制目录或 `kit`、`framework` 软链接。
 - [ ] `tasks.yaml` 使用 `ackVersion` 记录 ACK Skill 版本。
+- [ ] 若存在 `.pouch/ack/agents.yaml`，已运行 `validate_agents.py`；它优先于任务板
+      `project.orchestration`，且只包含结构化 profile，不包含自由 command/argv/env。

 ## 项目覆盖层

@@ -24,7 +26,9 @@
 - [ ] 技术栈、运行、构建、单测和集成测试命令均来自项目证据。
 - [ ] Coordinator、Developer、Test 的模型档位和升级规则已明确。
 - [ ] `project.orchestration` 使用受支持的 profileVersion，模型都命中项目
-      allowlist，默认 profile 与角色/档位一致。
+  allowlist，默认 profile 与角色/档位一致。
+- [ ] `agents.yaml`（若存在）使用受支持的 profileVersion，Pi 默认模型使用
+  `cli: pi` + `model: null`，配置 hash 会绑定启动 plan/fingerprint/receipt。
 - [ ] `allowedWorktrees` 已废弃（v0.19 起），新任务板不配置；worker 默认在
      `--project-root` 工作，其它 worktree 由 launcher 按同 git 仓库且已注册约束放行。
 - [ ] `tasks.yaml` 不需要保存 `repoPath` 或 `devWorktree`；项目状态从当前
@@ -34,7 +34,7 @@ Coordinator 发现或读取 open 任务
  -> 从 knowledge.yaml 按 scope 推荐 active 知识，Coordinator 确认固定 revision 的 knowledgeRefs
  -> 为新轮次生成稳定 attemptId（<task-id>-A<round>），Developer 与 Test 共用
  -> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
-  -> 解析安全 profile：机器配置只读 tasks.yaml.project.orchestration
+  -> 解析安全 profile：机器配置只读 agents.yaml（存在时），否则读取 tasks.yaml.project.orchestration
  -> 运行 launcher plan 并审阅 launchFingerprint
  -> 检查同轮空闲 worker；可信清理历史消息成功才复用，否则带 expected fingerprint 启动 fresh worker
  -> 把本次 task/attempt receipt 写回 tasks.yaml（见 orca-adapter.md）
@@ -103,6 +103,9 @@ pouch init ack --project <project-root>
 - `allowedWorktrees` 已废弃（v0.19 起），新任务板不生成该字段；worker 默认在
  `--project-root` 工作。模型 allowlist、profiles 和 defaults 使用项目实际允许值。
  不要把完整启动命令、`extraArgs`、`env` 或任意 executable 写进任务板。
+- `.pouch/ack/agents.yaml` 是可选的临时 worker 路由覆盖；存在时优先于任务板中的
+  `project.orchestration`。它必须使用结构化 profile；Pi 默认模型写成 `cli: pi`、
+  `model: null`，不能写自由命令。
 - 非服务项目的 `baseUrl` 写为 `n/a`。
 - 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。

@@ -152,6 +155,8 @@ python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
  --tasks .pouch/ack/tasks.yaml --project-root <project-root>
 python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yaml \
  --tasks .pouch/ack/tasks.yaml
+# 存在临时角色配置时
+python3 <ack-skill-dir>/scripts/validate_agents.py .pouch/ack/agents.yaml
 ```

 同时确认：
@@ -164,6 +169,8 @@ python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yam
 - Developer 与 Test 的验证命令可执行。
 - `project.orchestration` 的 profile/allowlist/defaults 通过校验，自动模式只允许
  `read-only` 或 `workspace-write`；旧任务板未迁移时保持手动模式。
+- 若存在 `agents.yaml`，其 profile/allowlist/defaults 也通过校验，且启动配置 hash
+  会绑定 plan、fingerprint 和 receipt。
 - 顶层 `workerReceipts` 和 `dispatch.developer/test` 的 task/role/profile/attempt
  引用一致；`receiptId` 与 `attemptId` 同时为空或同时填写。持久 receipt 只作审计，
  不能单独授权复用旧终端；复用还需要空闲状态、身份匹配和可信历史清理证明。
@@ -10,8 +10,9 @@

 **你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、
 编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；
-具体 CLI、模型、reasoning effort 和执行模式的机器事实源是
-`.pouch/ack/tasks.yaml` 的 `project.orchestration`。`.pouch/ack/project.md` 只解释项目
+具体 CLI、模型、reasoning effort 和执行模式的机器事实源优先是
+`.pouch/ack/agents.yaml`，不存在时回退到 `.pouch/ack/tasks.yaml` 的
+`project.orchestration`。`.pouch/ack/project.md` 只解释项目
 差异，不能提供另一套启动命令。

 ---
@@ -65,8 +66,8 @@ python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
 python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml --tasks .pouch/ack/tasks.yaml
 ```

-   `project.orchestration` 是 worker profile 的机器 SSOT；未知字段、非 allowlist 模型、
-   不匹配的角色/档位和非安全权限必须在派发前 fail closed。
+   有效 worker routing（`agents.yaml` 优先，否则 `project.orchestration`）是 profile 的机器
+   SSOT；未知字段、非 allowlist 模型、不匹配的角色/档位和非安全权限必须在派发前 fail closed。

   读取任务上下文使用：

@@ -96,7 +97,7 @@ python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \

 ## 第 3 步：审阅并启动 worker

-先读 `tasks.yaml.project.orchestration` 的结构化 profiles。历史 receipt 或既有 Orca
+先读有效 routing（`agents.yaml` 优先，否则 `tasks.yaml.project.orchestration`）的结构化 profiles。历史 receipt 或既有 Orca
 terminal 不能单独授权复用。复用候选必须属于同一轮 ACK、处于空闲状态，且角色、
 profile、worktree 与启动身份仍完全匹配；还必须通过受信后端清理历史消息并取得可核对
 的新会话身份。当前 Orca 接口缺少该清理证明，所以 Orca 派发仍创建 fresh worker。
@@ -196,7 +197,7 @@ Coordinator 最后标记整轮任务完成后，用 `scripts/reclaim_workers.py`
 ## 一句话

 产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 从
-`tasks.yaml.project.orchestration` 解析安全 profile → 审阅 plan 并用 expected
+有效 routing（`agents.yaml` 优先，否则 `tasks.yaml.project.orchestration`）解析安全 profile → 审阅 plan 并用 expected
 fingerprint 启动 fresh DEV/TEST → dispatch / 复测 / 终检循环 → 任务结论落
 `tasks.yaml` → 可选收获回归用例到 `regression.yaml` → 可选 delivery profile
 到审核点，验证后的跨任务知识由 Coordinator 落 `knowledge.yaml` → 整轮完成后回收
@@ -1,6 +1,6 @@
 # 模型路由（稳定核心）

-本文件是**三角色默认模型档位、升级规则和 worker profile 选择规则**的单一规范源。
+本文件是**三角色默认模型档位、升级规则和 worker profile 选择规则**的规范源。
 目标是在不牺牲质量的前提下降低 token 和模型成本：把昂贵的强模型留给需要判断的
 工作，把机械执行交给较弱模型。

@@ -64,23 +64,32 @@ profile 升级时不得复用旧 worker，Test 也不得使用 Developer 的强

 ## 结构化 worker profile

-### 机器事实源
+### 机器事实源与项目临时覆盖

-worker 路由的机器可读事实只保存在 `.pouch/ack/tasks.yaml` 的
-`project.orchestration`。`project.md` 可以解释项目为何选某个档位，但不能另写一份
-完整启动命令或覆盖机器配置。字段结构以 `templates/tasks.schema.json` 为准。
+worker 路由的机器可读事实默认保存在 `.pouch/ack/tasks.yaml` 的
+`project.orchestration`。项目需要临时调整角色 CLI 或模型时，可以在同一目录增加
+`.pouch/ack/agents.yaml`；它使用与 `project.orchestration` 相同的结构，且优先级更高。
+删除该文件即回退到任务板配置。`project.md` 只能解释项目为何选某个档位，不能另写一份
+完整启动命令或覆盖机器配置。字段结构以 `templates/tasks.schema.json` 和
+`templates/agents.schema.json` 为准。
+
+`agents.yaml` 的配置 hash 会进入 profile-hash、launch plan、fingerprint 和 receipt。
+因此修改临时配置后必须重新审阅 plan；旧 fingerprint 不会被接受。

 每个 profile 明确声明：

 - `role`：`developer` 或 `test`；
- `cli`：受支持的 Agent CLI（`codex`、`cursor-agent`、`grok`、`omp`）；
+- `cli`：受支持的 Agent CLI（`codex`、`cursor-agent`、`grok`、`omp`、`pi`）；
 - `tier`：角色模型档位；
- `model`：项目 allowlist 中的精确模型 ID；
+- `model`：项目 allowlist 中的精确模型 ID；Pi 可用 `null` 表示其默认模型；
 - `reasoningEffort`：CLI 支持时显式声明；
 - `permissionMode`：只允许 `read-only` 或 `workspace-write`。

-`project.orchestration` 必须声明按 CLI/角色/档位分组的 `modelAllowlist`、命名
-`profiles` 和角色 `defaults`（`allowedWorktrees` 自 v0.19 起废弃，不再配置）。
+有效路由配置必须声明按 CLI/角色/档位分组的 `modelAllowlist`、命名 `profiles` 和角色
+`defaults`（`allowedWorktrees` 自 v0.19 起废弃，不再配置）。`cli: pi` 使用真实的
+Pi CLI；`model: null` 表示使用 Pi 自己保存的默认模型。当前 launcher 对 Pi 只构造
+固定的 `--thinking`，工作目录由受信 bootstrap 设置；Pi 的 `read-only` profile 只允许
+`read,grep,find,ls` 工具。
 launcher 请求的 worktree 必须是同 Git 仓库的已注册 worktree，profile 的模型也必须
 命中对应 CLI/角色/档位的精确列表。

@@ -142,10 +151,10 @@ worker 实际工作的绝对路径，两者可以不同。后者仍必须与项

 项目状态文件固定从 `--project-root/.pouch/ack/` 解析；任务板不需要保存 `repoPath` 或
 `devWorktree`。旧任务板中的这两个字段仅作兼容信息，launcher 不使用它们授权或定位。
-`projectRoot`、任务板内容摘要和 worker worktree identity 都会进入 launch fingerprint，
+`projectRoot`、任务板内容摘要、有效 agents 配置 hash 和 worker worktree identity 都会进入 launch fingerprint，
 因此切换权威项目根、任务板内容或 worker 路径后必须重新生成并审阅 plan。

- `profile-hash` 读取 `tasks.yaml` 中的 profile，输出确定性 hash。
+- `profile-hash` 读取有效路由配置中的 profile，并输出配置来源与确定性 hash。
 - `plan` 只校验并展示将使用的结构化计划，不创建终端。
 - `launch` 是唯一允许创建 worker 的入口；它要求传入刚审阅的
  `plan.launchFingerprint`，当前 profile、任务/attempt、worktree、CLI 或 argv
@@ -63,8 +63,8 @@ reset/attestation 后才能启用上述复用路径，不能用项目文档声
 ## 通过 launcher 创建 worker

 **模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、
-模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile
-决定，并且只能由 ACK launcher 构造。
+模型、reasoning effort 和权限由 `.pouch/ack/agents.yaml`（存在时）或
+`tasks.yaml.project.orchestration` 的结构化 profile 决定，并且只能由 ACK launcher 构造。

 先只读生成计划：