weichen/Agent-System-Dev
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions 4 Packages Projects Releases Wiki Activity

Design project-level execution agent routing

Browse Source 
Why: Let each project route expensive implementation work across available Agent CLIs while the host model retains planning and delivery control.

Evidence: The specification passed placeholder, consistency, scope, path, and whitespace self-checks; implementation and runtime validation remain NOT_RUN.

Impact: Defines a review-only R1-R10 design for Markdown configuration, adapters, run-everything execution, receipts, recovery, and host fallback without enabling the new route.

Refs: .task/feature-goal-first-delivery.md
This commit is contained in:
weichen
2026-10-15 01:45:15 +00:00
parent cc03710240
commit 5ff0a4d510
2 changed files with 353 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.task/feature-goal-first-delivery.md
+22 -19
View File
@@ -7,16 +7,16 @@
- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 33261925a10c4eee40d1b6175b3895e78a47ef02
- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-goal-first-delivery（worktree）；分支：feature/goal-first-delivery
- 授权与交付终点：完善本仓交付规范及必要的任务卡接线，确立目标优先、不私自扩围、先可用再迭代，移除可移除的人工环节，并规定每个实施单元由一个新 Cursor CLI 运行执行、主模型只规划和管理；本轮交付阶段 6 候选供用户评审，不修改 Guidelines 子模块、业务代码或平台保护。
- 授权与交付终点：完善本仓交付规范，确立目标优先、不私自扩围、先可用再迭代并移除机械人工环节；进一步设计每项目一份 Markdown 执行 Agent 配置、多 CLI adapter、`run-everything` 优先与全候选不可用后主模型回退。当前终点是书面设计评审；未授权实施执行器、修改 Guidelines 子模块、业务代码或平台保护。
- 交付模式：transition-manual（本任务在旧规范下启动；2026-10-15 用户已批准阶段 1–5）
- 合入执行：agent（已授权交付范围内，Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入）
- 人工决策点：本轮阶段 6 产物评审；其余按旧规范与后续授权执行
- 当前阶段：正式测试与验收；当前增量：I1（goal-first）+ I2（cursor-per-unit）
- 人工决策点：用户审阅项目级执行 Agent 书面设计；审阅通过后才编写实施计划
- 当前阶段：方案设计；当前增量：U0（项目级执行 Agent 设计）
- 流程依据：仓库根目录 policy/delivery.md（归档后仍按仓库根目录定位）
## 目标与非目标
目标：使本仓执行者优先完成已授权任务目标并保持系统可用，只处理直接阻塞项，非阻塞问题按价值记录或忽略；在一次确认目标、范围和终点后连续交付；产生仓库变更的每个实施单元由独立 Cursor CLI 运行完成，主模型不直接代写。
目标：使本仓执行者优先完成已授权任务目标并保持系统可用，只处理直接阻塞项，非阻塞问题按价值记录或忽略；每个项目通过一份 Markdown 配置外部 Agent CLI，主模型优先做规划和交付把控，高消耗实施优先下放给 CLI，全部候选不可用后才回退主模型。
非目标：不放宽授权、独立 Review、证据、CI/平台准入、高后果双钥匙或安全回收条件；不修改通用 Guidelines 子模块和业务功能。
@@ -42,12 +42,15 @@
| R2 | 禁止私自扩围，仅解决直接阻塞项；非阻塞项按价值记录或忽略 | 收紧基线硬边界 1，不放宽授权 | P0 | 规范具有阻塞/有价值非阻塞/低影响噪音分流，任务外修复必须获得授权 | R1 | 纳入 I1 |
| R3 | 移除可移除的逐阶段人工停顿，保留真实决策、安全和质量门禁 | 项目层在通用基线内明确执行方式 | P0 | 任务卡默认 goal-first，阶段为追溯记录而非人工签字表；治理测试覆盖模板 | R1、R2 | 纳入 I1 |
| R4 | 每个产生仓库变更的实施单元启动一个新 Cursor CLI，主模型只规划和管理 | 保留 host 的范围、验证、集成和交付权威；worker 无提交/扩围权 | P0 | AGENTS.md/policy 明确一单元一新进程、禁止主模型代写和失败 blocker；任务卡模板生成实施模式与收据表 | R1–R3 | 纳入 I2 |
| R5 | 用项目级 Markdown 配置驱动多 Agent CLI，取代固定 Cursor 候选 | R4 保留为历史候选；新契约只在项目显式采纳后生效 | P0 | 书面设计定义 `AGENT-EXECUTION.md`、adapter seam、角色顺序、模型 auto 和受控 custom adapter | R1–R4 | 纳入 U0 |
| R6 | 优先 `run-everything`，配置候选全部不可用后才回退当前主模型 | 不放宽任务授权、共享环境、秘密、平台准入或高后果边界 | P0 | 书面设计定义终态机、精确恢复和 `host-fallback-authorized` 收据 | R5 | 纳入 U0 |
| R7 | 将高消耗实施下放给 CLI，限制主模型上下文消耗 | 主模型仍负责范围、Review、权威验证、集成和交付决定 | P0 | 任务包传路径/固定版本，正常收据有上限，原始日志不自动进入主模型上下文 | R5、R6 | 纳入 U0 |
## 方案与计划
- 方案引用：2026-10-15 对话内有界方案（用户已批准）
- 实施计划引用：I1 修订 goal-first 规范与必要接线；I2 通过单独 Cursor P2 单元加入 cursor-per-unit 规则、收据模板和回归
- 测试计划引用：R1–R4 用治理模板 red→green、文档一致性、`git diff --check` 和 `make test-governance` 验证
- 方案引用：[2026-10-15 项目级执行 Agent 路由设计](../docs/superpowers/specs/2026-10-15-project-agent-execution-design.md)（待书面评审）
- 实施计划引用：NOT_RUN；书面设计批准后才编写 U1–U5 计划
- 测试计划引用：设计规定配置/解析、adapter 契约、路由/回退、主模型消耗和真实 CLI 探针；具体命令待实施计划确定
## 阶段评审
@@ -55,11 +58,11 @@
|---|---|---|---|---|---|
| 需求拆解 | 2026-10-15 对话内方案 | 通过 | weichen | 2026-10-15 | 用户“批准，并且移除可以被移除的人工环节” |
| 需求评估 | 2026-10-15 对话内方案 | 通过 | weichen | 2026-10-15 | 同上 |
| 需求表确认 | R1–R4 | 通过 | weichen | 2026-10-15 | 用户追加“每个单独步骤或任务拉起 Cursor CLI，主模型只规划和管理” |
| 方案设计 | 2026-10-15 对话内方案+用户追加要求 | 通过 | weichen | 2026-10-15 | 同上 |
| 实施计划 | I1+I2 | 通过 | weichen | 2026-10-15 | 用户追加要求及 sandbox 实测 |
| 需求表确认 | R1–R7 | 通过 | weichen | 2026-10-15 | 用户确认多 CLI 受控 adapter、`run-everything` 优先、主模型低消耗与全候选不可用后回退 |
| 方案设计 | `docs/superpowers/specs/2026-10-15-project-agent-execution-design.md` | 待评审 | weichen | 2026-10-15 | 用户已批准对话设计；待审阅书面规格 |
| 实施计划 | U1–U5 | 未评审 | — | — | 书面设计未批准前 NOT_RUN |
| 实施与自检 | `8b7e8ca` 审阅候选 | 通过 | weichen | 2026-10-15 | 用户明确“批准”；P2 收据及控制器聚焦验证/`make test-governance` run receipt |
| 正式测试与验收 | 同步后候选（待固定） | 进行中 | Codex host | 2026-10-15 | `make task-sync` SELF 收据；sync_base=`cc40e10`，正式测试待执行 |
| 正式测试与验收 | 旧 `cursor-per-unit` 候选 `cc03710` | 不适用（范围已变更） | Codex host | 2026-10-15 | 本地 `make test`/`make build` SELF 只保留旧对象历史；未进入 PR/GATE |
| 代码 Review | 待定 | 未评审 | — | — | — |
| 合入 | 待定 | 未评审 | — | — | — |
| 合入核验与收口 | 待定 | 未评审 | — | — | — |
@@ -84,25 +87,25 @@
## 交付调度
- 调度状态：已领取 Dev main 最终窗口；调度记录：[#518 评论 6478](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/issues/518#issuecomment-6478)
- 调度状态：已因实质范围变更释放最终窗口；调度记录：[#518 领取评论 6478](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/issues/518#issuecomment-6478)，[释放评论 6479](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/issues/518#issuecomment-6479)
- entry_id：`feature/goal-first-delivery`；attempt_id：`mq-dev-20261015-goal-first-delivery-01`；窗口执行者：当前 Codex host
- 固定候选：待本任务卡与同步收据提交后记录；base=`cc40e10f3b4b6e41cb3a7aa0826e08dd3b8b7270`
- 固定候选：无；旧 `cc03710` 因新架构要求不再作为最终交付对象
- 调度依据：policy/merge-queue.md；新模式启用前按既有交付门禁
- 固定后证据：源码外 RECEIPT；实际结果后按授权原样导入和闭合
## 结果与验证（完成后填写）
- 结果：阶段 6 候选已就位；goal-first、严格范围/问题分流、去机械人工节点和 cursor-per-unit 均已接入根入口、交付规范、任务卡生成器与回归。
- 结果：旧 cursor-per-unit 候选已停止交付；新项目级多 Agent CLI 路由设计已写入书面规格，待用户评审。
- 验证：SELF PASS — Cursor focused red→green；host 集成验证 PASS；控制器 `make test-governance` 退出 0，对象 `d79d6c17`，evidence digest `d16726eb13aba7f5`；状态收据由 `make evidence` 写入。
- 影响与剩余项：当前只完成本地阶段 6 候选；阶段 7 正式同步/验证、独立 Review、PR、CI、合入和收口均 NOT_RUN。
- 影响与剩余项：新设计的实施计划、业务实施、测试、Review、PR、CI、合入与采纳均 NOT_RUN。
## 规划进展与下一步
- 本次推进/剩余：规范候选已实施与自检；剩余为本任务阶段 7–10，不是新任务。
- 首选下一任务：无；先完成当前任务评审与交付，不为低影响建议创建新任务。
- 本次推进/剩余：U0 书面设计已起草；待审阅后编写 U1–U5 实施计划。
- 首选下一任务：审阅书面设计；未批准前不启动实施。
- 推荐依据：遵循本次 goal-first 与不扩围原则。
- 前置条件/待确认：用户完成阶段 6 候选评审。
- 预期产物/验收条件：当前任务按阶段 7–10 完成正式证据、Review、PR/CI、合入和安全收口。
- 前置条件/待确认：用户审阅 `docs/superpowers/specs/2026-10-15-project-agent-execution-design.md`。
- 预期产物/验收条件：批准的 R1–R10 设计及可执行 U1–U5 计划；实施和采纳后续分别交付。
- 重复任务核对：未发现需另建任务的重复范围。
- 启动授权：未授权（建议不自动启动新任务，仍须明确授权）
docs/superpowers/specs/2026-10-15-project-agent-execution-design.md
+331
View File
@@ -0,0 +1,331 @@
# 项目级执行 Agent 路由设计
状态：待书面评审
日期：2026-10-15（Asia/Shanghai）
适用范围：Agent-System-Dev 的项目级开发与交付治理
## 背景
当前候选将 Cursor CLI 固定为仓库写入的唯一实施通道。这能分离规划与实施，但不能表达不同项目的 CLI 可用性、额度、模型或角色分工，也无法在 Cursor 不可用时安全选择其他执行者。
目标架构将主模型限定为规划者和交付管理者。实施、修复和可下放的局部验证优先由项目配置的 Agent CLI 执行。只有配置的候选全部对当前单元不可用，且所有已启动尝试都能证明没有未知副作用时，才回退当前主模型。
## 目标
1. 每个项目用一份 Markdown 配置文档声明可用 Agent、角色顺序、模型和执行档位。
2. 主模型负责需求、方案、单元拆分、调度、范围审查、权威验证、集成和交付。
3. 仓库写入默认交给外部 Agent CLI，每个实施单元使用新进程和隔离工作区。
4. 默认使用 `run-everything` 权限语义，减少 CLI 向主模型或用户反复请求批准。
5. 内置适配 Cursor、Antigravity `agy`、Claude、PI、OpenCode、Codex 和 Kimi，并允许受控扩展其他 CLI。
6. 通过有界任务包、有上限的结果收据和按需读日志，降低主模型上下文消耗。
## 非目标
- 不让 Agent CLI 取得任务授权、扩围、提交、推送、PR、合入、部署或安全清理的终局权威。
- 不把 `run-everything` 解释为可以越过秘密、数据、共享环境、平台准入或高后果双钥匙。
- 不在 Markdown 中保存凭据值，也不允许未经结构化验证的 shell 命令模板。
- 不在首个增量建设跨主机调度、中央队列、额度交易或自动模型评测系统。
- 不要求所有 CLI 在首个增量具备相同的流式输出、沙箱或模型回执能力。
## 需求
| ID | 需求 | 验收条件 |
|---|---|---|
| R1 | 项目级单一配置 | 根目录只有一份 `AGENT-EXECUTION.md`；`AGENTS.md` 在需要实施、修复、测试或审阅调度时指向它 |
| R2 | 声明式角色路由 | 每个角色用有序 profile 列表声明候选；选择不依赖文档顺序以外的隐式偏好 |
| R3 | 模型可选 | `model: auto` 不传模型参数；固定模型必须通过 adapter 的路由兼容校验 |
| R4 | `run-everything` 优先 | 实施候选默认要求非交互自动执行；adapter 不支持时该 profile 对当前角色不可用 |
| R5 | 多 CLI adapter | 七个内置 adapter 共用同一执行收据契约；未安装 CLI 明确返回 `unavailable` |
| R6 | 安全回退 | 只有全部候选已耗尽且无未知副作用时才返回 `host-fallback-authorized` |
| R7 | 主模型低消耗 | 正常路径只向主模型返回有上限的摘要、改动路径、验证结果、身份与收据索引；原始日志留在仓外 |
| R8 | 严格范围 | worker 只能修改任务包的允许路径；实际路径超出范围时保留现场并返回 `scope-expansion` |
| R9 | 受控自定义 | `custom` adapter 只接受结构化 argv 字段和受限占位符；禁止 shell 解析、凭据值和未知环境继承 |
| R10 | 可恢复证据 | 每个候选尝试记录配置摘要、单元、CLI/模型身份、终态、改动和清理/恢复收据 |
## 配置文档
### 路径与载入
`AGENT-EXECUTION.md` 是项目执行路由的单一权威。文档可包含人读说明，但只能有一个标记为 `agent-execution` 的 YAML 代码块。解析器拒绝缺失、重复或未知 schema，不从其他 Markdown 代码块猜测配置。
`AGENTS.md` 只保留一个上下文指针：在需要选择执行 Agent 时必读 `AGENT-EXECUTION.md`。CLI 标志、模型和回退细则不在 `AGENTS.md` 重复。
### 配置示例
```agent-execution
schema: agent-execution/v1
execution:
fresh_process_per_unit: true
permission: run-everything
fallback_to_host: all-unavailable
max_parallel: 3
timeout_seconds: 7200
summary_bytes: 16384
raw_output_bytes: 10485760
roles:
implementation: [cursor, antigravity, claude, codex, pi, kimi, opencode]
repair: [cursor, antigravity, codex, claude]
test: [pi, antigravity, codex]
review: [claude, codex, pi]
profiles:
cursor:
adapter: cursor
executable: cursor-agent
model: auto
enabled: true
antigravity:
adapter: antigravity
executable: agy
model: auto
enabled: true
claude:
adapter: claude
executable: claude
model: auto
enabled: true
codex:
adapter: codex
executable: codex
model: auto
enabled: true
pi:
adapter: pi
executable: pi
model: auto
enabled: true
kimi:
adapter: kimi
executable: kimi
model: auto
enabled: true
opencode:
adapter: opencode
executable: opencode
model: auto
enabled: true
```
顺序只来自 `roles.<role>`。`profiles` 的排列不表示优先级。一个 profile 可被多个角色引用。未被角色引用的 profile 只能被 `validate` 检查，不会被自动选中。
### 自定义 adapter
`custom` adapter 为未纳入内置注册表的 CLI 提供扩展点。它不接受一整段命令字符串。项目分别声明 executable、固定 argv、模型参数、工作区参数、提示输入方式、结果格式和 `run-everything` argv。执行器通过 argv 直接启动进程，不调用 shell。
允许的占位符限于 `${workspace}`、`${unit_packet}`、`${result_path}` 和 `${model}`。`${model}` 在 `model: auto` 时必须整段省略，不得生成字面量 `auto`。占位符只能占用完整 argv 元素，不做字符串拼接。
## 模块与接口
### 外部 seam
调用者只使用两个命令：
```text
agent-exec validate --repo <path>
agent-exec run --repo <path> --role <role> --unit <packet> --receipt <path>
```
`validate` 检查 Markdown/schema、profile 引用、executable、adapter 能力和模型路由兼容性，不向模型供应商发送请求。`run` 管理选择、隔离、进程、收据、恢复和回退。调用者不拼接任何供应商命令。
### 内部 adapter seam
内置 adapter 实现同一内部契约：
- 检查 executable 和版本能力；
- 将标准 profile 转换为无 shell 的 argv；
- 在 `model: auto` 时省略模型选项，否则验证并传递固定模型；
- 将 `run-everything` 映射为当前 CLI 支持的非交互执行档位；
- 流式或终态解析为标准 receipt；
- 声明是否可验证 served model、沙箱、改动范围和结构化输出。
adapter 是 CLI 差异的唯一实现位置。任务卡、`AGENTS.md`、业务脚本和调用者不再复制参数映射。
## 内置 adapter 基线
下表是适配目标，不是永久硬编码的命令。adapter 必须根据当前安装版本检查所需参数，无法证明时返回 `unavailable`。
| adapter | 非交互入口 | `run-everything` 目标 | 模型 | 结构化输出 |
|---|---|---|---|---|
| Cursor | `cursor-agent -p` | `--force`/`--yolo`，配合可用沙箱和 `--trust` | `--model`；auto 时省略 | `--output-format stream-json` |
| Antigravity | `agy --print` | `--dangerously-skip-permissions`，执行模式 `auto` | `--model`；auto 时省略 | JSON/stream-json 及可选 schema |
| Claude | `claude -p` | `--permission-mode bypassPermissions` 或当前版本的等价无提示模式 | `--model`；auto 时省略 | JSON/stream-json 及 schema |
| Codex | `codex exec` | 外层隔离下的无批准自动执行档 | `--model`；auto 时省略 | JSONL 与 output schema |
| PI | `pi -p` | 当前版本可验证的项目信任/自动工具模式 | `--model`/可选 `--provider`；auto 时省略 | JSON 模式 |
| Kimi | `kimi --prompt` | `--auto` | `--model`；auto 时省略 | stream-json |
| OpenCode | 从已安装版本的非交互入口探测；未安装返回 `unavailable` | 从已安装版本验证无提示档位；无可验证档位返回 `unavailable` | 固定模型只在当前版本支持时传递 | 从当前版本能力探测并归一化 |
本机 2026-10-15 的只读检查发现 Cursor、`agy`、Claude、PI、Codex 和 Kimi；OpenCode 未安装。该观察只用于设计与后续验收准备，不是 adapter 已实现的证据。
## 实施单元与任务包
主模型在调用 `run` 前将工作拆成可独立实施与验证的单元。任务包是 Markdown 或 JSON，至少包含：
- 单元 ID 和可观测目标；
- 允许路径、必要上下文和显式非目标；
- 已批准决定与不得改变的用户意图；
- 验收条件和权威验证命令；
- 是否允许网络、外部成本、新依赖或共享资源；
- 输出大小、超时和停止条件。
任务包不包含整段会话历史、凭据、无关规划或可由 worker 从仓库定位的大文件内容。主模型传路径和精确版本，worker 在隔离工作区读取必要源码。
## 选择、执行与回退
### 选择
1. 解析并验证配置。配置无效直接返回 `invalid-config`，不触发主模型回退。
2. 从 `roles.<role>` 读取有序 profile，过滤 `enabled: false` 和无对应 adapter 的项。
3. 执行无供应商请求的本地能力检查：executable、版本、必需参数和结构化输出能力。
4. 按声明顺序尝试候选。开始后不允许 adapter 内部换供应商、换 CLI 或换模型。
### 终态
| 终态 | 含义 | 下一动作 |
|---|---|---|
| `success` | worker 完成且输出可检查 | host 检查实际 diff，运行权威验证后集成 |
| `unavailable` | CLI/版本/模型/非交互能力不可用，且尚未产生写入 | 尝试下一 profile |
| `failed-clean` | 尝试失败，但隔离工作区和已授权外部对象均已精确恢复 | 保留失败收据，将该 profile 标为对本单元不可用，尝试下一个 |
| `failed-unknown` | 外部请求、副作用或恢复结果不明 | 停止调度并对账，不换 Agent，不回退主模型 |
| `scope-expansion` | worker 要求超出任务包 | 由主模型提交最小扩围决策 |
| `invalid-config` | schema、profile 引用或 custom adapter 不合法 | 修复项目配置，不回退 |
| `cancelled` | 用户、主模型或策略取消 | 保留收据并清理可证明安全的工作区 |
### 主模型回退
当每个候选均以 `unavailable` 或已精确恢复的 `failed-clean` 耗尽，执行器生成 `host-fallback-authorized` 收据。收据包含完整候选顺序、每次失败原因、恢复证明、任务包摘要和主模型可继续的精确范围。主模型只在收到该收据后直接实施。
`failed-unknown`、`scope-expansion`、`invalid-config` 和安全边界失败均不计入“全部不可用”，不能触发主模型回退。
## `run-everything` 与安全边界
`run-everything` 表示候选 CLI 在任务包范围内自动执行编辑和命令，不向用户或主模型逐项请求批准。它必须与以下执行端控制同时使用：
- 每单元独立工作区与独立进程组；
- 输入任务包和允许路径固定；
- worker 不获得主仓索引、推送、PR、合入、部署和安全清理权威；
- 网络、外部成本、共享环境和新依赖按任务包单独授权；
- 超时时终止整个进程组；
- 实际改动路径与允许路径差异触发 fail-stop；
- 命令、输出、摘要和收据统一脱敏。
如果某 CLI 的“全自动”参数同时关闭沙箱或扩大文件访问，adapter 只能在外层隔离已证明时启用该参数。外层隔离不可用时，该 profile 返回 `unavailable`，不静默降低权限档位或更改安全边界。
## 低消耗上下文策略
1. 主模型传递路径、固定 SHA 和有界单元包，不内联整个仓库或会话。
2. worker 自行在隔离工作区定位相关源码，原始事件流写入仓外日志。
3. 正常返回只包含状态、CLI/模型身份、改动路径、有上限的摘要、局部验证、范围请求和收据索引。
4. 主模型先检查改动清单、diff 统计、worker 证据和高风险区域；仅在异常、冲突、审阅 finding 或验证失败时读取详细日志。
5. 代码 Review 和测试分析可按项目配置下放给其他 CLI，但最终验证对象、出口码、证据来源和合入决定仍由 host 核对。
## 收据
每次 `run` 产生一份结构化收据，至少包含：
- schema 版本、run ID、单元 ID、role 和配置摘要；
- 候选 profile、adapter、executable 观察版本、请求/实际模型及可核验状态；
- 权限档位、隔离档位、网络/成本范围和输出上限；
- 开始/终止时间、进程终态、退出码、终态分类和原因；
- 实际改动路径、transport/diff 标识、worker 局部验证和原始日志摘要；
- 恢复、清理、下一 profile 选择或 `host-fallback-authorized` 的依据。
收据摘要不证明 worker 身份或验证权威。任务卡和 PR 仍按 `SELF`/`REPLAY`/`GATE` 标注证据来源。
## 错误与恢复
- 启动前失败不得创建输出改动，可安全转下一 profile。
- 已启动尝试必须先终态化，再判断是否可恢复。进程退出、超时或断连均不证明没有副作用。
- 只有隔离工作区、transport、进程组和已授权外部对象都能对账时，才记为 `failed-clean`。
- 恢复不删除失败收据。每次重试使用同一逻辑 run ID 和新 attempt ID。
- 检查到范围外改动时保留独立工作区和 transport，host 不自动挑选其中部分改动。
- 已完成并集成的单元不因主模型会话中断而重新执行。
## 验证方案
### 配置与解析
- 缺失、重复、未知 schema 和非法 YAML 拒绝；
- 未知 profile、重复 role 引用、非法模型和不合法 custom argv 拒绝；
- 凭据值、shell 字符串和占位符拼接拒绝；
- `model: auto` 证明模型参数整段省略。
### 适配器契约
每个内置 adapter 用 fake CLI 覆盖：
- 实际 argv、工作区、任务包和结果路径；
- `run-everything` 映射；
- auto 和固定模型；
- 结构化与纯文本结果归一化；
- 非零退出、超时、无结果、超大输出和进程组终止；
- 脱敏后不存在 token、Authorization 头或已知 secret 值。
### 路由与回退
- 按 role 顺序选择；
- 缺失 executable 继续下一 profile；
- 一个 profile 失败且精确恢复后继续；
- 候选全部耗尽后生成 `host-fallback-authorized`；
- `failed-unknown`、`scope-expansion` 和 `invalid-config` 不得触发回退；
- 每个单元和每个尝试均使用新进程，不复用 CLI 会话。
### 主模型消耗
- 任务包不包含原始会话或全仓源码；
- 正常收据摘要不超过 `summary_bytes`；
- 原始输出不进入主模型上下文；
- 只有失败、finding、扩围或验证不一致会触发详细日志读取。
### 真实 CLI 最小探针
当前安装的 Cursor、`agy`、Claude、PI、Codex 和 Kimi 分别执行一次无业务副作用的隔离探针，核对启动、非交互执行、输出归一化和收据。探针仍属 `SELF`，不代替对真实实施单元的业务验收。OpenCode 在未安装环境中的期望结果是 `unavailable`。
## 分阶段交付
1. **U1 配置合同**：`AGENT-EXECUTION.md` schema、Markdown 解析、验证器和项目示例。
2. **U2 adapter seam**：通用 adapter 契约、fake CLI 夹具与七个内置 adapter。
3. **U3 执行器**：单元包、隔离工作区、进程监督、范围检查、恢复、路由、收据和主模型回退。
4. **U4 项目接线**：`AGENTS.md` 指针、任务卡生成器、evidence 和交付流程接入。
5. **U5 组合验收**：当前安装 CLI 真实探针、主模型消耗边界、失败/恢复、回退和完整治理回归。
每个增量都必须保持现有 goal-first、严格范围、证据和平台准入边界。U1 不启用新路由；U2 只验证 adapter；U3 建立可用执行闭环；U4 才将新路由接入日常任务；U5 决定是否取代当前固定 Cursor 候选。
## 迁移与兼容
- 当前分支上的 `cursor-per-unit` 是历史候选，不是新架构的并行权威。实施时修订原条款为项目配置驱动的 `agent-per-unit`，不再叠加一套路由规则。
- 新路由只在 `AGENT-EXECUTION.md` 存在、`validate` 通过且项目明确采纳后生效。未采纳项目保持原行为。
- 第一个采纳项目是 Agent-System-Dev。其他组件仓需要各自的配置、预检查、Review 和合入，不因 Dev 配置自动生效。
- 旧任务卡无需批量重写。恢复旧任务时记录它使用的历史执行规则，新实施单元在采纳后使用新收据。
## 备选方案与取舍
### 采用：声明式配置 + 内置 adapter + 受控 custom adapter
该方案将 CLI 差异收敛在一个深模块中。项目配置只表达选择和约束，调用者只学习 `validate` 和 `run` 两个接口。新 CLI 通过新 adapter 或受控 `custom` 加入，不修改每个任务调用点。
### 拒绝：原始 shell 命令模板
这种方案灵活，但会将引号、占位符、凭据、shell 注入、版本差异和输出解析分散到每个项目。它无法保持一致脱敏、恢复和收据，不采用。
### 暂不采用：独立中央调度服务
中央服务可以统一多主机配额和执行者管理，但会引入运行服务、身份、租约和高可用边界。当前问题是单项目的 CLI 路由和主模型消耗，项目内深模块足以解决，不预支多主机复杂度。
## 完成条件
本设计可进入实施计划的条件是：
- 用户审阅并批准本文档；
- 配置路径、schema、回退语义、`run-everything` 边界和五个增量无未决取舍；
- 实施计划将 R1–R10 映射到工作项、测试和可判定出口；
- 实施、正式验证、Review、合入和采纳仍分别保留对象与证据。