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

Document U3 r0.6 transport evidence design

Browse Source 
Why: The authorized small tool stream again lacked an observed DONE marker, leaving transport and provider causes unresolved.

Evidence: U3 r0.5 terminal receipt 6b013965 and independent assessment f35d1c17; local links and diff checks passed.

Impact: Design only; the missing-DONE tool gate, runtime behavior, and paid resource boundary remain unchanged.

Refs: Agent-System-Dev feature/fast-slow-u2-u3-plan; Documents PR #95
This commit is contained in:
weichen
2026-10-14 13:00:18 +00:00
parent 04f5046f95
commit 54d39ef130
2 changed files with 53 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/proposals/2026-10-14-fast-slow-u3-r06-transport-completeness-design.md
+51
View File
@@ -0,0 +1,51 @@
# U3 r0.6：当前路由的传输完成性证据设计
状态：**书面设计草案，待阶段 4 人工评审。** 用户在 2026-10-14 的同会话答复“认可证据优先，写设计（推荐）”，只授权编写本设计；不授权产品代码、额外付费请求、A01 复验、合入或部署。负责人 weichen；目标仍是让非专业用户在同一张任务卡上先看到可信收件反馈、再看到有来源的两批阶段成果和准确最终正文。既有[U2/U3 主计划](2026-10-13-fast-slow-u2-u3-plan.md)、[r0.5 设计](2026-10-14-fast-slow-u3-r05-terminal-evidence-and-fast-feedback-design.md)、[核验报告](../reports/2026-10-13-fast-slow-u2-u3-validation.md)及 Dev `feature/fast-slow-u2-u3-plan` 任务卡是本设计的上下文；本版只处理阻断后台工具流的终态归因，不重新设计界面或降低业务质量标准。
## 事实、问题与目标
r0.4 A01 在固定候选上有两次付费 run、三次 provider 调用，工具流返回 `tool_calls` 和 Usage，但客户端未见 `[DONE]`；工具安全拒绝，质量 FAIL。r0.5 随后保留严格门禁、增加无内容终态观察，并把自动材料入口首回合改成可信宿主确认。其零付费实施与阶段 6 已获人工确认。用户另行批准的**唯一**小型 MiniMax-M3 工具流探针在 Dev `0959e1c1566df9766878b2122eccc0ab42af10a3` 上返回 HTTP 200、`finishReason=tool_calls`、`ReadOutcome=clean_eof`、最后一帧已观察到的 JSON 完整、返回 Usage **513 tokens**，但 `StreamComplete=false`，工具放行／执行 **0／0**。一次性授权已消耗，不得补跑；见[作者判定](/tmp/fast-slow-u3-r05-20261014/probe-result-assessment.md)和[独立结果复核](/tmp/fast-slow-u3-r05-20261014/probe-result-independent-assessment.md)。本设计中的“当前路由”只指该探针 `SELF` 预检核对的 MiniMax-M3、`api.minimaxi.com/v1`、无 fallback，受保护路由文件 SHA-256 `2a92569d2416d74e8d07029219af88474cb6f860c2aa897a5ffdd10fcbe9b495`；身份漂移即重新评审，不复制或公开 API key。r0.5 真实 A01 仍 **NOT_RUN**，八个 PR 仍为草稿。
这一次短工具请求重现了“有结束原因和 Usage，但未见 `[DONE]`”的**客户端观察**，排除了“只在三材料长任务中才出现”作为必要条件；它没有原始 SSE、HTTP 尾部元数据或供应商侧记录，无法判断服务端未发送、传输途中结束，还是适配器漏认。`clean_eof` 表示读取器没有报告扫描错误；它不证明供应商已交付预期的全部 SSE 事件。当前 [MiniMax Chat Completions API 文档](https://platform.minimax.cn/docs/api-reference/text-chat-openai)列出流式、工具和 Usage 字段，但没有在这页给出该路由以字面 `[DONE]` 结束工具流的可核验契约；不能把 OpenAI 兼容接口的惯例当作该路由的事实。
本版要回答两个分开的判断：**HTTP 响应体在客户端边界如何结束？SSE 应用层是否有经证实的完整工具调用终态？** 成功标准是形成可重放、无内容的诊断与决策证据，减少原因的不确定性；本版不承诺 r0.6 代码一落地就让工具流成功，也不把一次小探针等同于 A01 质量验收。
## 方案取舍
| 路线 | 能回答什么 | 代价与结论 |
|---|---|---|
| **A. 当前路由上分层观察 HTTP 读取与 SSE 终态，先保守拒绝** | 区分已知长度、分块、HTTP/2、关闭分隔等响应体结束类型；定位解析器是否漏认本地合法终止形式 | **推荐。** 零付费重放先行；真实路由若仍缺应用层契约，保持拒绝，再单独评审兼容规则或替代路由 |
| B. 直接换成另一个终态已验证的模型路由 | 可能绕开当前路由的兼容性问题 | 需要新模型质量基线、路由配置与资源评审；当前证据不足以指定替代对象，作为 A 无法得到可信终态时的后备方向 |
| C. 将 `clean_eof + tool_calls + Usage + JSON` 直接等同 `[DONE]` | 可能放行这类响应 | **不采纳。** 已观察到的最后一帧完整不等于整条业务流完整；尾帧缺失仍可能留下看似合法的参数 |
选择 A 不排斥后续 B。只有在明确证据与另行批准下，才能提出限路由的等价终态；本设计本身不定义一个可直接放行的 EOF 组合。
## 职责、数据流与隐私
Agent-Native 的 `Client.Stream` 已拿到 `http.Response`，`ParseSSE` 已拥有 `[DONE]`、`finishReason`、Usage、帧完整性与工具片段观察；**只有 Agent-Native** 可以在同一次调用中把两层事实关联成一条有界终态观察。Backend 只按现有 run ID／调用序号消费分类和 Usage，保留 r0.5 的拒绝后停止、预算和归档规则。Frontend/UI 沿用已实现的“整理中／未完成／待确认”、同一张任务卡、来源和失败展示；默认不显示协议字段、命令或 token。异步事件仍由原所有者按 seq 丢弃过期项，诊断记录不能成为另一个进度状态源。
建议在 Agent-Native 的内部终态观察中增加**有限枚举与饱和计数**，而非另存一份响应：
- HTTP 层：状态码、协议大类 `http1|http2|other`、响应体定界类别 `known_length|chunked|http2_stream|close_delimited|unknown`、声明长度是否存在、客户端实际读取字节数的有界计数、是否到达 `io.EOF`、读取错误类别、是否发生自动解压。已知长度时可给出“读取字节数与声明长度相符／不符”；未知长度不得伪造相符结论。Go [`net/http.Response`](https://pkg.go.dev/net/http#Response) 暴露 `ContentLength`、`TransferEncoding`、协议版本及 `Uncompressed`，并说明 `Body` 在读取时流式返回；这些字段支持**客户端边界**的分类，不暴露供应商上游到代理之间的完整性。
- SSE 层：沿用 `done_marker|clean_eof|read_error|cancelled|invalid_frame`、`StreamComplete`、受限 `finishReason`、Usage 是否存在及数量、最后一个**已观察**帧是否完整；只增加尾部事件的结构类别与有界计数，如 `done_literal|json_frame|empty_data|comment|unknown_non_json|partial_frame`，用于区分本地解析遗漏与真正未见标记。**不记录未知帧文字、尾部字节、原始 SSE 或其内容哈希。**
- 工具边界：分别记录“工具片段存在”“ID／名称齐全”“参数为 JSON 对象”“放行／实际执行次数”。现有 `ToolArgumentsValid` 只证明 JSON 对象可解析，不能偷换成 schema 或业务语义有效；本版不顺带新增工具 schema 校验器。缺 `[DONE]`、读取错误、取消、半帧、身份／参数不完整时仍为零放行、零执行。
所有字段只允许枚举、布尔和饱和计数；HTTP header/trailer 的名称与值、URL 查询、IP、请求 ID、证书细节、正文、思考、工具名及参数、prompt、API key、原始错误句均不入日志、评测记录或 UI。响应体计数只在流式读取时累计字节，不额外缓冲或复制模型内容。评测文件仍置于任务自有 0700 目录、0600 文件，保留期限沿现有受控评测清理规则；若需新增内部持久字段，实施计划须明确存储 owner、模式兼容与清理期限。公开 Core/HTTP/TaskSnapshot 合同和数据库表默认不变；发现必须改变时回到本设计重审。
`net/http` 可能自动解分块或解压，某些传输细节在 `Response.Body` 之上已不可见。实现计划应先用本地实验确定哪些字段能可靠观察；**不能观测就记 `unknown`**，不能为了满足一张表而声称看到了原始 HTTP 分块终止符或 HTTP/2 帧。响应体按协议完整读到 EOF，也只证明客户端收到的**响应体**结束，不能单独证明提供方本来就打算结束业务 SSE。真实路由的上游代理与供应商侧仍需外部契约或受控证据，不由客户端元数据代签。
## 决策规则与失败恢复
本版实现目标是**诊断，不放宽执行门禁**。终态首先按现有规则确定能否释放工具；新观察字段只给出原因与证据等级，不参与 `toolFinishExecutable` 的放行条件。非工具纯文本目前可以在缺 `[DONE]` 时按旧行为结束，但必须独立标注，不能把文本容忍路径借给工具。已返回 Usage 继续记账；诊断写入失败时保持原失败与停止决定，不让观察故障触发重试。取消、读错或多终态按保守失败处理；单次模型请求最多产生一条受限终态收据，Backend 不建立第二个状态所有者。
后续若要**提出**当前路由的等价终态规则，至少需要同时满足：① 可复核的供应商契约或该路由、模型、版本的授权外部证据，明确没有字面 `[DONE]` 时怎样表示业务完成；② 本地解析器能识别所约定的终止形式，并有正常、截断、半帧、缺 Usage、重定向／错误、取消的正反例；③ 客户端可区分响应体按协议结束与未知关闭，工具身份和参数完整性可验证，预算与停止门禁仍成立；④ 该规则只绑定经核验的路由身份，不对其他 OpenAI 兼容服务泛化。若还需声明 schema 校验，应在该轮方案中明定，不从当前 JSON 对象有效性推得。满足这些条件只进入**另一轮方案／计划评审**，不能自动改代码放行。若外部契约缺失、传输完整性未知或证据彼此矛盾，保持工具拒绝，并评估替代路由；不得因本次 513-token 探针成功返回 Usage 而补跑 A01。
## 零付费验证与阶段出口
详细实施计划获批前，本节只规定验收边界，不分派代码任务：
1. 本地 `httptest`／TLS HTTP/2 假流覆盖有 `[DONE]`、无 `[DONE]` 的完整 JSON、已知长度与字节不符、合法 chunked、连接中断、HTTP/2 正常结束、关闭分隔未知、自动解压、半帧、尾部非 JSON、缺 Usage、重定向、取消。对每例核对 HTTP 与 SSE 分层分类、已返回 Usage、工具放行／执行次数和后继请求数；至少一组证明“响应体按协议结束但无应用终止契约”仍拒绝工具。
2. 以哨兵正文、思考、工具名、参数、header/trailer、凭据与未知错误文字扫描新终态记录、日志和浏览器可见面；不得出现这些原文。计数边界、负值／溢出、未知枚举和多终态都须保守。正常 `[DONE]` 工具调用与 r0.5 快通道确认、排队／失败卡、来源跳转、刷新及按 seq 更新不得回退。
3. 固定 Agent-Native 与消费它的组件 SHA 后，做组件测试、Dev 组合 `make test && make build`、适用的真实 HTTP/浏览器及隔离 PostgreSQL 回归、独立重放和准确 HEAD CI；`SELF`、`REPLAY`、`GATE` 分开标注。零付费测试只证明观测机制，不证明 MiniMax 真实流或 A01 质量。真实模型、供应商账单和业务成果均标 `NOT_RUN`，直至另获资源批准。
阶段 4 的出口是用户审阅本设计的取舍、字段隐私边界、证据充分性门槛和未知项处理方式。**仅在书面设计获批后**写详细实施计划；计划获批后才可零付费改代码和验证。任何新付费探针或 A01 都须在固定新候选、单独资源提案与明确批准后进行；r0.5 一次性授权不能沿用。真实 U3 质量仍要求两条在终态前可感知且有用、有来源的阶段成果、准确完整最终正文及全部调用 Usage／停止规则，宿主收件确认不计入两条。质量未通过时八个 PR 保持草稿，不合入或部署。
docs/proposals/INDEX.md
+2 -1
View File
@@ -17,7 +17,8 @@
2026-10-12 方案设计已批准（阶段 1–4）；首批仅 U1；[U1 实施计划 r1](2026-10-12-fast-slow-channel-display-u1-plan.md) 待阶段 5 批准；业务实施和运行验收 NOT_RUN。 2026-10-12 方案设计已批准（阶段 1–4）；首批仅 U1；[U1 实施计划 r1](2026-10-12-fast-slow-channel-display-u1-plan.md) 待阶段 5 批准；业务实施和运行验收 NOT_RUN。
- [快慢通道 U2/U3 实施计划 r0.1](2026-10-13-fast-slow-u2-u3-plan.md)：阶段 5 已批准；r0.4 的一次性 A01 真实模型质量 FAIL，八个 PR 保持草稿，未合入或部署。详见[核验报告](../reports/2026-10-13-fast-slow-u2-u3-validation.md)。 - [快慢通道 U2/U3 实施计划 r0.1](2026-10-13-fast-slow-u2-u3-plan.md)：阶段 5 已批准；r0.4 的一次性 A01 真实模型质量 FAIL，八个 PR 保持草稿，未合入或部署。详见[核验报告](../reports/2026-10-13-fast-slow-u2-u3-validation.md)。
- [U3 r0.5 安全终态证据与可信快通道反馈设计](2026-10-14-fast-slow-u3-r05-terminal-evidence-and-fast-feedback-design.md)：书面设计与[详细实施计划](2026-10-14-fast-slow-u3-r05-terminal-evidence-and-fast-feedback-implementation-plan.md)已获批准；零付费实施候选及[核验记录](../reports/2026-10-13-fast-slow-u2-u3-validation.md)待阶段 6 评审。新付费复验、合入和部署未获授权。 - [U3 r0.5 安全终态证据与可信快通道反馈设计](2026-10-14-fast-slow-u3-r05-terminal-evidence-and-fast-feedback-design.md)：书面设计、[详细实施计划](2026-10-14-fast-slow-u3-r05-terminal-evidence-and-fast-feedback-implementation-plan.md)及零付费阶段 6 已获批准；唯一另行授权的短工具流探针返回 513 Usage、`clean_eof`、缺 `[DONE]`，工具零执行且授权已用尽。A01 质量仍 NOT_RUN，详见[核验记录](../reports/2026-10-13-fast-slow-u2-u3-validation.md)。
- [U3 r0.6 当前路由的传输完成性证据设计](2026-10-14-fast-slow-u3-r06-transport-completeness-design.md)：用户已认可证据优先方向；本书面设计待阶段 4 人工评审，只提出无内容的 HTTP/SSE 分层观察，缺 `[DONE]` 仍拒绝工具。代码、付费请求、A01、合入和部署均未授权。
- [U3 质量修订设计 r0.2](2026-10-13-fast-slow-u3-quality-revision.md)：三处修订方向和书面设计均已批准，实施计划待人工评审；原样本质量及停止边界仍 FAIL，无新付费样本授权。 - [U3 质量修订设计 r0.2](2026-10-13-fast-slow-u3-quality-revision.md)：三处修订方向和书面设计均已批准，实施计划待人工评审；原样本质量及停止边界仍 FAIL，无新付费样本授权。
- [U3 质量修订实施计划 r0.2](2026-10-13-fast-slow-u3-quality-implementation-plan.md)：书面设计已批准，阶段 5 计划待人工评审；Task 1–5 为零付费实施与验证，Task 6 的真实模型样本另需明确资源授权。 - [U3 质量修订实施计划 r0.2](2026-10-13-fast-slow-u3-quality-implementation-plan.md)：书面设计已批准，阶段 5 计划待人工评审；Task 1–5 为零付费实施与验证，Task 6 的真实模型样本另需明确资源授权。