2026-10-20 01:21:48 +00:00
3 changed files with 359 additions and 0 deletions
@@ -0,0 +1,161 @@
+# feature/fast-slow-o2-route-contract-eof 任务卡
+
+任务主记录：PR #639 https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/639；状态：已完成（合入前闭合）；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 2b7fdc39a1f44163f4766701429d61ffd6926f1a
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-fast-slow-o2-route-contract-eof（worktree）；分支：feature/fast-slow-o2-route-contract-eof
+- 分支类型：standalone；root_target：main；immediate_target：main；accepting_requirements：false
+- 需求分流：verdict=NEW；selected_initiative=无；requirement_sha256=6fc124cc90d04f78b09f649f482b1d37e33158e1a6f6f4821e252654a7bf3a1c；triage_receipt=/tmp/leftover-20261019b/o2-triage.json；receipt_sha256=b93713ab306413aaa7ea484be10767631a3b04db22b133818012ffef3019a19c
+
+- 授权与交付终点：用户 2026-10-19“授权…另起 O2”（选定评估稿方案 O2）；本轮终点：阶段 4 方案 + 阶段 5 计划经独立 Review、PR/CI 后经 #518 合入 main，并提交用户阶段 4/5 人审。未授权：产品代码、付费/真实模型请求、A01 复验、部署、设置写入。
+- 交付模式：goal-first（目标、范围和交付终点一次确认；范围内连续推进）
+- 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）
+- 合入执行：agent（已授权交付范围内，Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入）
+- 人工决策点：仅限目标/范围/验收变更、重大取舍、高后果操作或无法自动判定的业务验收
+- 当前阶段：方案设计/实施计划（待阶段 4/5 人审）；当前增量：无（I1–I3 待人审通过后启动，P1 付费另行授权）
+- 流程依据：仓库根目录 policy/delivery.md（归档后仍按仓库根目录定位）
+
+## 目标与非目标
+
+- 目标：为一条经核验的 MiniMax 路由定义默认关闭的等价终态 `route_contract_eof`，在缺 `[DONE]` 但满足 C1–C9 时放行工具调用；其余情形保持拒绝。
+- 本轮产物：方案 `docs/superpowers/specs/2026-10-19-fast-slow-o2-route-contract-eof-design.md`、计划 `docs/superpowers/plans/2026-10-19-fast-slow-o2-route-contract-eof-plan.md`。
+- 非目标：不改代码、不泛化到其他路由、不改 `StreamComplete` 语义、不发付费请求。
+
+## Agent 实施收据
+
+路由与 fail-stop 规则见根目录 AGENT-EXECUTION.md 与 policy/delivery.md；每次尝试一行，原始日志留在源码外收据路径。
+
+| 单元 ID | 预期范围 | 配置摘要 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 待定义 | — | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
+
+## 关联方向与规划
+
+- 适用状态：待核对（无适用规划时说明原因）
+- 主记录路径/版本：待核对（路径按仓库根目录定位，归档后不变；只引用唯一正文）
+- 对应里程碑：待核对
+
+## 需求分析
+
+| ID | 描述 | 项目符合度及依据 | 优先级 | 验收条件 | 依赖 | 结论 |
+|---|---|---|---|---|---|---|
+| R1 | 限路由等价终态 O2 的方案与计划 | 符合：用户 2026-10-19 选定 O2；r0.6 设计要求先另行方案评审 | P1 | 方案覆盖评估稿 O2 全部条件且只绑定单一路由；计划给出零付费单元、测试矩阵与停止条件；独立 Review 无阻塞项 | 评估稿 #633 | 待阶段 4/5 人审 |
+
+## 方案与计划
+
+- 方案引用：docs/superpowers/specs/2026-10-19-fast-slow-o2-route-contract-eof-design.md（本分支）
+- 实施计划引用：docs/superpowers/plans/2026-10-19-fast-slow-o2-route-contract-eof-plan.md（I1–I3 零付费、P1 付费另批；R1）
+- 测试计划引用：同上计划 §2 测试矩阵、§3 Backend 用例（R1）
+
+## 阶段记录
+
+| 阶段 | 对象版本 | 状态 | 决策/执行者 | 时间 | 依据 |
+|---|---|---|---|---|---|
+| 需求拆解 | 待定 | 待执行 | — | — | — |
+| 需求评估 | 待定 | 待执行 | — | — | — |
+| 需求表确认 | 待定 | 待执行 | — | — | — |
+| 方案设计 | 5a7a0da | 待阶段 4 人审 | host 撰写 | 2026-10-19 | 用户选定 O2 |
+| 实施计划 | 5a7a0da | 待阶段 5 人审 | host 撰写 | 2026-10-19 | 同上 |
+| 实施与自检 | 待定 | 待执行 | — | — | — |
+| 正式测试与验收 | 待定 | 待执行 | — | — | — |
+| 代码 Review | 待定 | 待执行 | — | — | — |
+| 合入 | 待定 | 待执行 | — | — | — |
+| 合入核验与收口 | 待定 | 待执行 | — | — | — |
+
+## 探索试验与迭代
+
+| 增量/试验 | 假设 | 范围 | 判断和停止条件 | 授权/决策依据 | 结果 | 变更影响 | 需重审补测 |
+|---|---|---|---|---|---|---|---|
+| 待定义 | — | — | — | 待核对 | NOT_RUN | 待评估 | 待评估 |
+
+## 同步记录
+
+| 节点 | sync_base_sha | tested_head_sha | checked_at |
+|---|---|---|---|
+| 启动 | 2b7fdc39a1f44163f4766701429d61ffd6926f1a | 2b7fdc39a1f44163f4766701429d61ffd6926f1a | 2026-10-19T16:17:05Z |
+
+## 证据（Evidence）
+
+<!-- CMD="<命令>" make evidence 写入；手抄/转写输出视为无效证据（AGENTS.md 证据与验证门禁）。 -->
+| 时间(UTC) | 命令 | 被测HEAD | exit | 来源 | sha256(16) |
+|---|---|---|---|---|---|
+
+## 交付调度
+
+- 调度状态：未入队；调度记录：无
+- entry_id：无；attempt_id：无；窗口执行者：无
+- 固定候选：无（base/head、组件与相关配置引用实际尝试）
+- 调度依据：policy/delivery.md#合入调度
+- 固定后证据：源码外 RECEIPT；实际结果后按授权原样导入和闭合
+
+## 结果与验证
+
+- 结果：O2 阶段 4 方案与阶段 5 计划完成并经独立 Review（PASS-with-fixes，已闭合）；本轮交付终点为文档合入 main，**待阶段 4/5 人审**。
+- 验证：文档类变更；独立 Review PASS-with-fixes；PR CI（GATE）见合入记录；产品测试 NOT_RUN（无代码）。
+- 影响与剩余项：仅文档与任务卡。剩余：阶段 4/5 人审；通过后另起 I1（Agent-Native）→ I2（Backend）→ I3（Dev 改钉）；P1 付费另提资源方案。
+
+## 规划进展与下一步
+
+- 本次推进/剩余：待核对（依据实际成果更新适用方案/规划）
+- 首选下一任务：O2 I1 Agent-Native `route_contract_eof`（阶段 4/5 人审通过后）
+- 推荐依据：待填写
+- 前置条件/待确认：待核对
+- 预期产物/验收条件：待定义
+- 重复任务核对：待核对（已有/在途任务、PR 与规划记录）
+- 启动授权：未授权（须阶段 4/5 人审通过）
+
+## 合入与清理
+
+- Review 记录：独立 Review（Cursor Task 子代理 code-reviewer，fresh_session=true，session=fdb9367a-08bb-4e87-ae9d-ac8608290886；只接收需求、base 2b7fdc3/head 5a7a0da 与两份文档，未转交实施会话）；结论 PASS-with-fixes，0 阻塞、8 非阻塞（截断用例、C4/C6 定义、重定向与基址规范化、schema 语义整体迁移、拒绝事件逐字段一致、系统层扁平键与 5 个调用点、哨兵扫描、前提①风险引用），已在后续提交全部闭合。
+- 冲突记录：NOT_RUN（最新目标同步、冲突处置、组合兼容核验及复审/补测）
+- CI 记录：NOT_RUN（当前 HEAD 完整 SHA、全部必需检查、运行链接、执行身份及 GATE 结果）
+- 合入记录：NOT_RUN（交付授权范围、PR、被核验 HEAD、合入 SHA、目标分支及内容核验）
+- 清理记录：NOT_RUN（授权依据、写者退出确认、worktree/分支/任务卡处置）
+
+<!-- Local receipt: SELF. Digests detect corruption; they do not authenticate a reviewer or CI. -->
+```json
+{
+  "summary_schema": 1,
+  "source": "SELF",
+  "timestamp": "2026-10-19T16:16:15.823972+00:00",
+  "command": "make precheck",
+  "exit_code": 0,
+  "cwd": "/home/weichen/projects/Agent-System-Dev",
+  "before_head": "2b7fdc39a1f44163f4766701429d61ffd6926f1a",
+  "after_head": "2b7fdc39a1f44163f4766701429d61ffd6926f1a",
+  "branch": "main",
+  "target_branch": "main",
+  "target_head": "2b7fdc39a1f44163f4766701429d61ffd6926f1a",
+  "root_target": "main",
+  "immediate_target": "main",
+  "before_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "after_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "output_tail": [
+    "make[1]: Entering directory '/home/weichen/projects/Agent-System-Dev'",
+    "[repo]   branch=main head=2b7fdc39a1",
+    "[remote] origin/main=2b7fdc39a1 ahead=0 behind=0",
+    "[tree]   clean submodules_drift=0 uninit=0",
+    "[worktrees] linked=5",
+    "[recycle] merged un-recycled branches: feature/layered-python-env",
+    "[initiatives] local cards (not authoritative): none",
+    "[hooks]   core.hooksPath=scripts/hooks（pre-commit/post-merge 实际接线）",
+    "[facts]   policy/facts.md 6 条事实均在有效期内",
+    "[required-reading] core/baseline.md, workflows/delivery.md §1, policy/delivery.md",
+    "[R0] 2b7fdc39a1（完整：2b7fdc39a1f44163f4766701429d61ffd6926f1a）",
+    "[worktree] before-sync: recursive component checks passed",
+    "[verdict] READY — 保留本次 precheck receipt 后建任务工作区：PRECHECK_RECEIPT=/tmp/task-precheck.json make task-start NAME=feature/your-branch",
+    "make[1]: Leaving directory '/home/weichen/projects/Agent-System-Dev'"
+  ],
+  "output_sha256": "3a96e0c9643e0dc8fb45bb9ca5dfa9e57c34d0ff3c11a46864d4d6df5116c012",
+  "receipt_sha256": "242b51c81c4c825292cfacbdf27b212b74ed684dea9484aa239b1d83139449b2",
+  "receipt_path": "/home/weichen/.cache/agent-system-dev/evidence/242b51c81c4c825292cfacbdf27b212b74ed684dea9484aa239b1d83139449b2.json"
+}
+```
+
+## 闭合记录（合入前折叠）
+
+- 本卡在 PR #639（https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/639）合入前闭合并归档，随该 PR 一同合入。
+- 该 PR 的合并提交即本任务的落地记录。
+- 合入后无需回填，也无需单独的闭合 PR。
@@ -0,0 +1,75 @@
+# 快慢通道 O2：限路由等价终态 阶段 5 实施与测试计划
+
+- 状态：**阶段 5 计划稿，待人审**（与[阶段 4 方案](../specs/2026-10-19-fast-slow-o2-route-contract-eof-design.md)同批评审）。人审通过前不派 worker、不改产品代码。
+- 日期：2026-10-19；作者：host；来源等级：SELF。
+- 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）；worker 不提交、不推送、不开 PR；host 负责范围审阅、权威验证、PR/CI/合入。
+- 付费与真实模型：**本计划零付费部分不需要任何付费请求**；P1 付费验证另提资源方案并单独批准。
+
+## 1. 交付切分与顺序
+
+| 增量 | 仓 | 内容 | 依赖 | 合入方式 |
+|---|---|---|---|---|
+| I1 | Agent-Native | `runtime/argschema` 提炼 + 解析器延后判定 + `RouteContractEOF` 传输层判定 + 夹具 | 无 | 组件仓 PR，CI 通过后合入（组件仓无需 #518 窗口） |
+| I2 | Backend | 系统层设置键、`openLLMClient` 按身份挂合同、运行记录透传 `CompletionBasis` | I1 合入且 Backend `deps/agent-native` 改钉 | 组件仓 PR |
+| I3 | Dev | 改钉 Agent-Native 与 Backend，组合验证 `make test` | I1、I2 | #518 窗口合入 |
+| P1 | — | 1 次短工具探针 + 1 次 A01（付费） | I3 合入、资源方案获批、系统层配置写入 | 另行授权 |
+
+各增量阶段 6 评审包写入 `docs/superpowers/specs/`；I1–I3 每个增量完成后先交用户阶段 6 再合入（与快慢通道既往 manual 口径一致）。
+
+## 2. I1 Agent-Native（单元 `o2-i1-agent-native-route-contract`）
+
+- **允许路径**：`runtime/llm/**`、`runtime/argschema/**`（新）、`runtime/tools/registry.go`、`runtime/tools/registry_test.go`。
+- **动作**：
+  1. 新包 `runtime/argschema`：`Validate(schema, args json.RawMessage) error`，整体迁移现 `validateArgs` 与 `matchesType`，语义逐项相同；`registry.validateArgs` 改为委托，现有 registry 测试不改断言。
+  2. 解析器：内部选项 `deferMissingDone`；新增计数 `finishChunks`、标志 `toolAfterFinish`。只有在“除缺 `[DONE]` 外全部现有检查通过”时才返回候选终态，否则行为同今。公开 `ParseSSE` 签名与零值行为不变。
+  3. 传输层：`Client.RouteContract`；在 `bodyObserver` 快照后按方案 §4.2 的 C1–C9 判定；放行发 `message_end`（`CompletionBasis=route_contract_eof`，`StreamComplete=false`），拒绝发与今天相同文案的终态失败并附 `ContractCheck`。
+  4. `Event`/`TerminalObservation` 新增 `CompletionBasis`、`ContractCheck`（JSON 字段名 `completionBasis`、`contractCheck`）。
+- **测试**（`httptest`；HTTP/2 用 `httptest.NewUnstartedServer` + `EnableHTTP2` + TLS）：
+
+| 用例 | 期望 |
+|---|---|
+| 有 `[DONE]`（合同开/关） | 放行，`CompletionBasis=done_marker`，与现状一致 |
+| 无 `[DONE]`、合同关 | 拒绝，文案不变 |
+| 无 `[DONE]`、合同开、HTTP/2 正常结束、全部条件成立 | **放行**，`route_contract_eof`，工具调用逐字节等于输入 |
+| 同上但 `known_length`+`match` / `mismatch` | 依人审 §6.1 结论放行 / 拒绝（C2） |
+| `close_delimited`、`chunked`、`unknown` | 拒绝（C2） |
+| 缺 Usage | 拒绝（C5） |
+| Usage 在 `finish_reason` 块之前 / 之后 | 均放行（顺序不作要求，评估稿 §3） |
+| 两个非空 `finish_reason` 块；`finish_reason=stop` 或 `length` 却有工具；一块含多个 choice | 拒绝（C4） |
+| 在帧边界截断、无 `finish_reason`，但 HTTP/2 正常结束 | 拒绝（C4） |
+| HTTP/2 `RST_STREAM` 或连接中途断开导致读错 | 拒绝（C3） |
+| 与 `finish_reason` 同一块内的工具片段 / 后续块再出现工具片段 | 放行 / 拒绝（C6） |
+| 合同开但任一条件不满足 vs 合同关 | 两个终态事件除 `contractCheck` 外 deep-equal |
+| 哨兵扫描 | `contractCheck`、`completionBasis` 不含正文、工具名、参数或错误原文 |
+| 半帧 / 无效帧 / 供应商错误帧 | 拒绝（C3/C9） |
+| ID 或名称缺失、参数非 JSON 对象 | 拒绝（C7） |
+| 工具名不在请求 `tools`；缺 required；属性类型不符 | 拒绝（C8） |
+| 模型名不符、基址不符（含 http、userinfo、query）、摘要不符、`APIBase` 覆盖到他址、重定向（他主机、同主机改路径、降级） | 拒绝（C1） |
+| 读取中取消 | 中止事件，无放行 |
+
+  每个用例同时断言 Usage 保留与“放行次数/工具调用数”。
+- **验证**：`gofmt -l runtime`；`go vet ./runtime/...`；`go test ./runtime/llm/... ./runtime/argschema/... ./runtime/tools/... -count=1`；`git diff --check`。
+- **停止条件**：若延后判定需要改变公开 `ParseSSE` 的零值行为或既有测试断言，停止并回到方案评审。
+
+## 3. I2 Backend（单元 `o2-i2-backend-route-contract-config`）
+
+- **允许路径**：`internal/runtime/**`、`internal/settings/**`、`internal/runmgr/**`（仅透传字段）、Backend `deps/agent-native` gitlink（host 改钉，不由 worker 改）。
+- **动作**：`settings.Schema()` 以 `SettingScopeSystem` 声明三个扁平键 `models.routeContractEOF.model/.baseUrl/.identitySha256`（任一为空即关闭；用户/项目层由 `ManagedPaths` 剥除）；`openLLMClient` 增参 `ResolvedModel` 与配置，三元组与摘要全部精确一致才挂合同（按三元组、不看 `Kind`），5 个调用点 `llm.go`、`sub_loop.go`、`squad_runner.go`、`verify.go`、`workflow_compiled.go` 全部覆盖；轻量档、视觉改模、子代理独立判断；运行记录与快慢通道收据透传 `completionBasis`。
+- **测试**：缺省关闭；用户层写入被忽略；模型/基址/摘要任一不符不挂合同；视觉改模后不继承；挂合同后假流放行一次工具并记录 `route_contract_eof`；删除配置后恢复拒绝。
+- **验证**：`gofmt`；`go vet ./internal/runtime ./internal/settings ./internal/runmgr`；`go test ./internal/runtime ./internal/settings ./internal/runmgr -count=1`。
+
+## 4. I3 Dev 组合
+
+- host 改钉 `deps/agent-native`（I1 合入 SHA）与 `modules/backend`（I2 合入 SHA）；`make test` + `make build` 由 PR CI（GATE）确认；无产品代码改动。
+- 注意与同期 IAM 链路 initiative（Dev #628）对 Backend gitlink 的合入顺序：以合入时最新 main 为准重新组合验证，冲突由 host 选择包含双方的 Backend SHA，不回退对方提交。
+
+## 5. P1 付费验证（不在本计划授权内）
+
+- 前提：I3 合入；系统层配置写入目标路由三元组；核对 r0.6 证据身份（受保护路由文件 SHA-256 `2a92569d…`）与生产三元组指向同一模型/基址。
+- 内容：1 次短工具探针（预期约 500 tokens，参考 r0.5/r0.6），期望 `route_contract_eof` 放行且工具执行恰好一次；通过后 1 次 A01，规模参考 r0.4。
+- 另提资源方案（预算上限、停止条件、收据路径），用户批准后执行；失败即停、不补跑。
+
+## 6. 完成与停止
+
+- 零付费完成：I1–I3 合入，夹具全绿，配置缺省关闭时线上行为不变（以既有 `[DONE]` 与拒绝用例为回归证据）。
+- 停止并回到方案评审：需要改变 `StreamComplete` 语义、泛化到其他路由、或任何条件无法在本地确定性观察。
@@ -0,0 +1,123 @@
+# 快慢通道 O2：限路由等价终态（`route_contract_eof`）方案
+
+- 状态：**阶段 4 方案稿，待人审。** 本文不授权产品代码改动、付费请求、A01 复验或部署；阶段 4/5 人审通过后才按配套计划派 worker 实施零付费部分，付费探针另行提资源方案。
+- 日期：2026-10-19；作者：host（只读调查与文档撰写）；来源等级：SELF。
+- 决策来源：用户 2026-10-19 在[完成信号口径评估](2026-10-19-fast-slow-completion-signal-evaluation.md)中选定 **O2**（另起任务）。
+- 配套计划：[阶段 5 实施与测试计划](../plans/2026-10-19-fast-slow-o2-route-contract-eof-plan.md)。
+- 上游约束：[r0.6 传输完整性设计](../../../modules/documents/docs/proposals/2026-10-14-fast-slow-u3-r06-transport-completeness-design.md)的四个前提（评估稿第 4 节逐项对照）；本方案是该设计要求的“另一轮方案评审”，不改变 r0.6 已批准的观察字段。
+
+## 1. 目标与非目标
+
+**目标**：对**一条经核验的 MiniMax 路由**，在流缺少字面 `[DONE]`、但能证明“按协议结束且工具调用完整”时，放行该轮工具调用；其余一切情形保持现行拒绝。
+
+**非目标**：
+
+- 不改变有 `[DONE]` 的现有放行路径与 `StreamComplete` 语义。
+- 不对其他 OpenAI 兼容服务、其他 MiniMax 模型或其他主机泛化；不提供“全局放宽”开关。
+- 不在本轮跑真实 A01 或任何付费请求；不改 Anthropic 协议路径。
+- 不引入完整 JSON Schema 引擎（见 §4.3 的子集约定）。
+
+## 2. 现状（代码定位，Agent-Native `origin/main` 9c24e22 / Dev 钉 28f3ea7 同文件）
+
+| 位置 | 现行行为 |
+|---|---|
+| `runtime/llm/sse.go` `emitParsed` 第 260 行起 | 有工具调用且 `!sawDone` → `sendTerminalFailure("tool call stream ended before [DONE]")`，工具全部丢弃，Usage 保留 |
+| `runtime/llm/sse.go` 第 300 行 | 正常结束发 `message_end`，`StreamComplete = sawDone` |
+| `runtime/llm/client.go` `run` 第 129–139 行 | 用 `bodyObserver` 包住响应体；`ParseSSE` 的终态事件发出后才补 `TerminalObservation.BodyBoundary` |
+| `runtime/llm/body_observation.go` | 只按 `net/http` 可见信息分类：`http2_stream` / `known_length` / `chunked` / `close_delimited` / `unknown`；`LengthRelation` 仅在已知长度、未解压、未饱和且见 EOF 时为 `match`/`mismatch` |
+| `runtime/tools/registry.go` `validateArgs` | 工具**执行前**按 schema 子集（`type`、`required`、属性类型）校验参数；失败返回错误结果、不执行 |
+| Backend `internal/runtime/model.go` `ResolvedModel` | 路由身份 = `Kind` + `Model` + `Base`（设置层 → 画像覆盖）；生产无独立“路由文件” |
+| Backend `internal/runtime/llm.go` `openLLMClient` | 构造 `agentllm.Client`；`MiniMax-M*` 置 `ReasoningSplit` |
+
+关键约束：**判定所需的传输边界只在 `client.go` 可见**，`ParseSSE` 看不到；因此终态判定不能只放在解析器里。
+
+## 3. 方案总览
+
+```
+ParseSSE（解析器）                       Client.run（传输层）
+──────────────────                       ────────────────────
+既有检查全部照旧                          bodyObserver 快照
+仅当“唯一缺陷 = 缺 [DONE]”且               ↓
+调用方声明了路由合同时 →                  RouteContractEOF.Evaluate(candidate, boundary, tools)
+  返回 候选终态（不外发）  ────────────▶    全部条件成立 → message_end（CompletionBasis=route_contract_eof）
+                                           任一不成立 → 与今天相同的终态失败（Usage 保留）
+```
+
+- 合同未配置（零值）时，解析器与客户端的行为**逐字节等同现状**。
+- 解析器只做“延后判定”，不做放行；放行只在传输层、且只对绑定身份。
+
+## 4. 设计细节
+
+### 4.1 路由合同与身份绑定（Agent-Native `runtime/llm`）
+
+新增导出类型（命名可在计划阶段微调，语义固定）：
+
+```go
+// RouteContractEOF 只对一条经核验路由生效；零值/nil 表示关闭。
+type RouteContractEOF struct {
+    Model          string // 精确模型名，例如 MiniMax-M3
+    BaseURL        string // 规范化后的精确基址，例如 https://api.minimaxi.com/v1
+    IdentitySHA256 string // sha256("openai-chat\n" + Model + "\n" + BaseURL)
+}
+```
+
+`Client` 增加可选字段 `RouteContract *RouteContractEOF`。生效前提（任一不满足即视为关闭，回到现行拒绝）：
+
+1. `Protocol` 为 openai-chat；
+2. 本次请求实际使用的 `model` 与 `Model` 精确相等；
+3. 本次请求实际使用的基址（含 `StreamOptions.APIBase` 覆盖）规范化后与 `BaseURL` 精确相等。规范化规则：只允许 `https`；scheme 与 host 转小写；去掉末尾 `/`；含 userinfo、query 或 fragment 一律视为不匹配（规则只会失败关闭，不放宽）；
+4. 由 1–3 重算的摘要等于 `IdentitySHA256`（防止宿主误配一半字段）；
+5. 请求没有被重定向：`resp.Request.URL`（net/http 的最终请求）的 scheme、host、port、path 与原始请求逐项相等；同主机改路径或 https 降级都视为不匹配。
+
+r0.6 探针所记的受保护路由文件 SHA-256（`2a92569d…`）是**证据身份**，用于核对“被观察的就是这条路由”；生产绑定用上面的三元组摘要，二者在计划的付费探针前做一次映射核对。
+
+### 4.2 放行条件（全部成立才放行）
+
+| # | 条件 | 数据来源 |
+|---|---|---|
+| C1 | 路由合同生效（§4.1 的 1–5） | `Client` + 请求 + 响应 |
+| C2 | 传输按协议结束：`FramingClass=http2_stream` 且 `EOFSeen`，或 `known_length` 且 `LengthRelation=match` | `BodyBoundaryObservation` |
+| C3 | `ReadOutcome=clean_eof`；无取消、读错、无效帧、供应商错误 | `TerminalObservation` |
+| C4 | 恰好一个带非空 `finish_reason` 的块，且其值为 `tool_calls`；合同生效时每块 `len(choices) <= 1`（解析器只读 `choices[0]`，多 choice 不得被静默丢弃） | 解析器新增计数 |
+| C5 | 请求开启 `include_usage`（客户端恒开）且收到 Usage | `UsagePresent` |
+| C6 | `finish_reason` 块之后的**后续块**中没有任何工具片段（与 `finish_reason` 同一块内的片段允许） | 解析器新增标志 |
+| C7 | 每个工具调用 ID、名称齐全，参数为 JSON 对象 | 现有检查 |
+| C8 | 每个调用的名称在本次请求声明的 `tools` 中，参数通过该工具 schema 子集校验（§4.3） | 请求 `tools` |
+| C9 | 最后一帧 JSON 完整，`TailEventKind=json_frame` | `TerminalObservation` |
+
+`chunked`、`close_delimited`、`unknown`、`known_length` 但 `mismatch`/`unknown` 一律不满足 C2。
+
+### 4.3 参数 schema 子集
+
+C8 采用与 `tools.registry.validateArgs` **相同**的语义：整体迁移 `validateArgs` 与 `matchesType`，语义不变——顶层 `type: object`、`required` 必填项（空白字符串视为缺失）、已声明属性的基本类型、声明了 `properties` 时拒绝未知参数。实现上把该校验提炼到新的无依赖小包 `runtime/argschema` 中的单一函数，`runtime/llm` 与 `runtime/tools` 都调用它（两包当前互不导入，放进任一方都会引入新的包依赖方向），避免两套语义漂移。超出子集的约束（枚举、格式、嵌套）不在本轮，registry 执行前校验仍保留作为第二道门。
+
+### 4.4 输出与可观测性
+
+- 放行时：`message_end` 正常携带工具调用；`StreamComplete` **保持 false**（字面含义仍是“未见 `[DONE]`”）；新增 `Event.CompletionBasis`：`done_marker`（现有路径）或 `route_contract_eof`。
+- `TerminalObservation` 新增 `CompletionBasis` 与 `ContractCheck`（失败时记录第一个不满足的条件编号，例如 `C2`），不保存正文、参数或密钥。
+- 拒绝时：除 `TerminalObservation.ContractCheck` 外，终态事件与“合同关闭”时**逐字段一致**（Content、Thinking、`StopError`、Usage、FinishReason、错误文案 `tool call stream ended before [DONE]`）。实现上解析器的候选终态同时携带预先构造的失败事件，`Client.run` 判定失败即原样发出。
+- `CompletionBasis`、`ContractCheck` 只取枚举值，不含正文、工具名、参数或供应商错误原文。
+- 下游（Backend 运行记录、快慢通道收据）只把 `CompletionBasis` 作为新增字段透传，不把 `route_contract_eof` 计作 `StreamComplete=true`。
+
+### 4.5 宿主配置（Backend）
+
+- 三个扁平设置键 `models.routeContractEOF.model`、`.baseUrl`、`.identitySha256`，在 `settings.Schema()` 中以 `Scope: SettingScopeSystem` 声明（`ManagedPaths` 会剥除并拒绝用户/项目层写入），画像覆盖不参与；任一为空 = 关闭（默认）。
+- `openLLMClient` 在实际解析出的 `(model, base)` 与配置三元组全部精确一致时才挂合同，按三元组判定、不看 `Kind`；轻量档、视觉改模、子代理按各自解析结果独立判断，不继承。全部调用点（`llm.go`、`sub_loop.go`、`squad_runner.go`、`verify.go`、`workflow_compiled.go`）统一经过同一判定。
+- 回滚：删除该设置键即恢复现行拒绝，无需发版；身份漂移（换模型、换基址）自动失效。
+
+## 5. 风险与取舍
+
+| 风险 | 处置 |
+|---|---|
+| 截断被误判为完成 | C4 要求 `finish_reason` 已到达；C2 要求传输按协议结束；C6 拒绝 `finish_reason` 之后再出现片段 |
+| 前提 ① 只部分满足（文档写明 `finish_reason` 非空即结束，但无 Usage 顺序与版本承诺） | 以精确身份绑定、默认关闭和 P1 付费探针兜底；P1 不通过即保持关闭 |
+| 供应商行为漂移、无版本承诺 | 合同只绑定精确身份；默认关闭；`ContractCheck` 使漂移在收据中可见；必要时直接删配置回滚 |
+| 参数语义错误进入执行 | C8 在放行前校验；registry 执行前再校验一次 |
+| `known_length` 是否纳入 | 方案纳入（仅 `match`）；r0.6 观察到的是 `http2_stream`。**请人审确认**是否只保留 `http2_stream` |
+| 两套 schema 校验漂移 | §4.3 提炼为单一函数 |
+
+## 6. 需人审确认的取舍
+
+1. C2 是否同时接受 `known_length`+`match`（建议接受），还是只接受 `http2_stream`。
+2. 宿主配置键仅系统层可写、默认关闭（建议如此）。
+3. 付费验证（1 次短工具探针 + 1 次 A01）在零付费部分合入后另提资源方案，不随本方案授权。