From 5ff0a4d510a7a910969004e30d5f7732103d062b Mon Sep 17 00:00:00 2001 From: weichen Date: Thu, 15 Oct 2026 01:45:15 +0000 Subject: [PATCH] Design project-level execution agent routing 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 --- .task/feature-goal-first-delivery.md | 41 ++- ...26-10-15-project-agent-execution-design.md | 331 ++++++++++++++++++ 2 files changed, 353 insertions(+), 19 deletions(-) create mode 100644 docs/superpowers/specs/2026-10-15-project-agent-execution-design.md diff --git a/.task/feature-goal-first-delivery.md b/.task/feature-goal-first-delivery.md index 722d0f26..2a8bd84e 100644 --- a/.task/feature-goal-first-delivery.md +++ b/.task/feature-goal-first-delivery.md @@ -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 计划；实施和采纳后续分别交付。 - 重复任务核对：未发现需另建任务的重复范围。 - 启动授权：未授权（建议不自动启动新任务，仍须明确授权） diff --git a/docs/superpowers/specs/2026-10-15-project-agent-execution-design.md b/docs/superpowers/specs/2026-10-15-project-agent-execution-design.md new file mode 100644 index 00000000..6be59bc1 --- /dev/null +++ b/docs/superpowers/specs/2026-10-15-project-agent-execution-design.md @@ -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.`。`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 +agent-exec run --repo --role --unit --receipt +``` + +`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.` 读取有序 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、合入和采纳仍分别保留对象与证据。