文档:同步流式工具验收口径

补充 Responses incomplete 的终态恢复与拒绝语义

修正真实端点协议参数的默认与失败关闭说明

同步开发运维文档与长期决策记录
This commit is contained in:
2026-07-27 12:08:51 +00:00
parent ea2e1c96d2
commit d4bce0677f
2 changed files with 5 additions and 5 deletions
@@ -5534,7 +5534,7 @@
- 背景:`platform-llm` 的 Anthropic 分支从未实现工具——请求体没有 `tools` / `tool_choice` 字段,`validate()` 还会以「Anthropic api_kind 暂不支持 function tools」本地拒绝,响应解析只取 `text` block 并硬编码 `tool_calls: Vec::new()`。App 侧因此在 `provider_request_builders.rs``interaction.rs``api_kind != Anthropic` 绕开原生工具,改用长提示词描述工具并要求模型输出单个 JSON object,等于让 Anthropic 退回 V1.26 之前的状态。三种协议的流式路径同样恒返回空工具调用,靠「无文本 → EmptyResponse → 非流式重打」兜底;模型若在工具调用前先输出解说文本,该兜底不触发,工具调用会被静默丢弃并把解说当成最终回复。
- 前提验证:MiniMax 的 Anthropic 兼容层与真实 OpenAI 均完整支持工具调用,说明这是本地实现缺口而非上游限制。实测覆盖 `tools` + 四种 `tool_choice`、并行多工具、`tool_result` 回传与流式增量;`tool_choice` 必须是对象,裸字符串返回 400。
- 决策:Anthropic 与 Chat / Responses 使用同一套原生工具目录。请求体顶层发送 `tools``name / description / input_schema`,无 `function` 包装层与 `strict`)与对象形态 `tool_choice``Auto → {"type":"auto"}``Required → {"type":"any"}`),响应解析 `tool_use` block 并把 `input` 序列化成 `arguments`;解除 `validate()` 对 Anthropic function tools 的拦截,`web_search`、图片内容和至少一条非 system 消息三条校验保留。App 侧删除两处 `api_kind != Anthropic` 守卫与对应的「Provider 不提供 function tools」提示词分支。
- 流式:三种协议的工具增量统一按槽位聚合成完整调用——Chat 用 `delta.tool_calls[].index`、Responses 用 `output_index``output_item.added` 给身份、`function_call_arguments.delta` 拼参数、`.done` 覆盖为权威值,并从 `response.completed``output[]` 再兜底一次)、Anthropic 用 content block `index``content_block_start` 给身份,`input_json_delta` 拼参数,`content_block_start` 里的空 `input` 不得用于初始化)。收尾必须校验参数为完整 JSON,截断流不返回半截参数。`LlmStreamDelta` 仍只承载文本,工具调用不进增量回调。上游已表明本轮是工具调用却一个都没聚合出来时返回 `StreamUnavailable`,让调用方回退非流式,不允许静默丢弃。
- 流式:三种协议的工具增量统一按槽位聚合成完整调用——Chat 用 `delta.tool_calls[].index`、Responses 用 `output_index``output_item.added` 给身份、`function_call_arguments.delta` 拼参数、`.done` 覆盖为权威值,并从 `response.completed` / `response.incomplete``output[]` 再兜底一次)、Anthropic 用 content block `index``content_block_start` 给身份,`input_json_delta` 拼参数,`content_block_start` 里的空 `input` 不得用于初始化)。收尾必须校验参数为完整 JSON,截断流不返回半截参数`response.incomplete` 携带的工具调用按未完成响应拒绝,纯正文可作为降级结果保留`LlmStreamDelta` 仍只承载文本,工具调用不进增量回调。上游已表明本轮是工具调用却一个都没聚合出来时返回 `StreamUnavailable`,让调用方回退非流式,不允许静默丢弃。
- 兼容边界:旧 wrapper 与 text JSON parser 只保留为历史响应、确定性 fixture 和模型不守协议时的降级解析,**不再是任何 Provider 的正常请求路径**`agent.runtime.tool_plan.protocol` 审计在 Anthropic 正常路径下取值为 `native_runtime_tools`。Chat 的 `ChatCompletionsToolCall` 字段放宽为可选并新增 `index`,否则流式后续分片(只带 `index``arguments`)会直接反序列化失败。
- 影响范围:`server-rs/crates/platform-llm``apps/ai-game-creator-shell/src-tauri/src/agent/interaction.rs`、同目录 `runtime_actions/provider_request_builders.rs`,以及 Runtime V1.1 与 App 实施计划两份技术方案。取代 2026-07-16「使用 Provider 原生工具目录」中把 Anthropic 与历史 fixture 并列的兼容描述、2026-07-12 关于 Anthropic 文本 JSON 回退的补充,以及 2026-07-24「统一 Interaction Loop」中「非原生 tool Provider 使用同构严格 JSON envelope 适配」的表述。
- 验证方式(当时记录):`cargo test -p platform-llm` 52 项通过,其中 8 个流式工具用例的 SSE 原文取自真实抓包;`server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs` 为默认 `#[ignore]` 的真实端点验收,靠 `PLATFORM_LLM_LIVE_*` 环境变量运行,已对 MiniMax(anthropic / openai_chat / openai_responses) 与 OpenAI(gpt-4.1 openai_chat / gpt-5.5 openai_responses) 五种配置确认流式解析出完整工具调用。App 侧回归用 stash 对比法确认无新增失败——本机该测试套件存在大量与改动无关的既有失败,不能直接看绝对失败数。
@@ -5544,4 +5544,4 @@
- 更正:上一条把固定 SSE fixture 的真实抓包来源、确定性 parser 覆盖和真实端点 smoke 合并描述,并写成“证明转录没有偏差”,超出了实际测试证据。从仓库根目录运行 `cargo test --manifest-path server-rs/Cargo.toml -p platform-llm` 当前为 `98 passed / 0 failed / 1 ignored`;其中固定 fixture 和本地解析测试只验证 parser / 配置归一结果,实时测试只验证最终归一后的工具名、id、完整参数 JSON 和文本增量字符数。
- 当前口径:`server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs` 是默认忽略的真实端点工具调用 smoke;`on_delta` 只接收文本,工具调用从最终 `LlmRunResponse.tool_calls` 读取。现有测试没有原始 SSE 录制、事件类型/slot/分片顺序保存或逐事件比较,因此两类测试都不能证明 raw SSE fidelity 或抓包转录无偏差。
- 现有确定性流式工具覆盖应与普通 Anthropic 文本流测试分开统计:三协议真实来源 fixture、Responses completed-only 恢复、并行 slot 聚合、截断参数和无片段 `StreamUnavailable` 等用例共同覆盖 parser 边界;未来若需证明转录一致性,必须另行增加受控原始 SSE capture/compare 能力。
- 现有确定性流式工具覆盖应与普通 Anthropic 文本流测试分开统计:三协议真实来源 fixture、Responses 仅有 completed / incomplete 终态事件时的恢复、并行 slot 聚合、截断参数和无片段 `StreamUnavailable` 等用例共同覆盖 parser 边界;未来若需证明转录一致性,必须另行增加受控原始 SSE capture/compare 能力。