diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 4fa13155e..8541f1154 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -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 能力。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 915403353..689dfbdc6 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -694,11 +694,11 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs,但本地日 `platform-llm` 请求默认使用 Responses 协议;需要接旧 OpenAI Chat Completions 兼容网关时,调用方必须显式选择 Chat Completions。三种协议(`openai_chat`、`openai_responses`、`anthropic`)都使用原生 function tools,并统一从最终 `LlmRunResponse.tool_calls` 读取工具调用;流式 `on_delta` 只发送文本,不能把工具参数当作文本增量转发。Anthropic 工具请求使用 `input_schema`,`Required` 使用对象形态 `{ "type": "any" }`;Anthropic 当前不支持 `web_search`、图片内容和纯 system 消息。AI 游戏创作独立 App 是客户端,不读取 `.env`;发布 App 启动时会在 Tauri 应用配置目录生成 `game-creator.config.json`,主窗口“配置”面板读写该运行时文件,真实密钥和本机覆盖项写入该文件,仓库内 `apps/ai-game-creator-shell/game-creator.config.json` 只作为默认模板,开发 CLI 无 AppHandle 时才回退读取仓库旁边的 gitignored 覆盖文件。LLM 维度由 `llm.apiKind` 控制,默认 `openai_responses`,可设为 `openai_chat` 接旧 Chat Completions 兼容网关,或 `anthropic` 接 Anthropic Messages。 -流式工具片段按协议 slot 聚合,Responses 允许从 `response.completed.response.output[]` 做 completed-only 工具恢复。收尾时空参数默认 `{}`,非空参数必须是完整 JSON;解析失败、流式工具缺少身份或参数截断属于 `Deserialize`。流式已声明工具调用但没有聚合出工具 slot 属于 `StreamUnavailable`,由调用方决定是否回退非流式;文本和工具调用均为空才是 `EmptyResponse`。 +流式工具片段按协议 slot 聚合,Responses 允许从 `response.completed` / `response.incomplete` 的 `response.output[]` 恢复只在整体终态事件中携带的工具调用与正文。`response.incomplete` 中的工具调用即使参数是完整 JSON 也返回 `Deserialize`,截断正文则保留为可用的降级结果。收尾时空参数默认 `{}`,非空参数必须是完整 JSON;解析失败、流式工具缺少身份或参数截断属于 `Deserialize`。流式已声明工具调用但没有聚合出工具 slot 属于 `StreamUnavailable`,由调用方决定是否回退非流式;文本和工具调用均为空才是 `EmptyResponse`。 -验收证据分为两类:`cargo test -p platform-llm` 的确定性用例验证 checked-in SSE fixture 的 parser 行为;默认忽略的 `tests/live_stream_tool_calls.rs` 只对真实端点做归一后的工具调用 smoke,检查最终工具名、id 和完整参数 JSON,文本增量字符数仅用于打印观测。该 smoke 不录制或逐事件比较原始 SSE,fixture 即使来源于真实抓包也不能据此宣称转录无偏差。 +验收证据分为三类:`cargo test -p platform-llm` 的确定性用例验证 checked-in SSE fixture 的 parser 行为;`tests/live_stream_tool_calls.rs` 中默认执行的本地解析测试验证 `PLATFORM_LLM_LIVE_API_KIND` 归一与失败关闭;同文件默认忽略的真实端点用例只做归一后的工具调用 smoke,检查最终工具名、id 和完整参数 JSON,文本增量字符数仅用于打印观测。该 smoke 不录制或逐事件比较原始 SSE,fixture 即使来源于真实抓包也不能据此宣称转录无偏差。 -真实端点 smoke 必填 `PLATFORM_LLM_LIVE_BASE_URL`、`PLATFORM_LLM_LIVE_API_KEY` 和 `PLATFORM_LLM_LIVE_MODEL`;`PLATFORM_LLM_LIVE_API_KIND` 可选,取值为 `anthropic` / `openai_chat` / `openai_responses`,省略或使用其它值时按 `openai_responses` 处理。仓库根目录没有 `Cargo.toml`,必须显式指定 workspace manifest: +真实端点 smoke 必填 `PLATFORM_LLM_LIVE_BASE_URL`、`PLATFORM_LLM_LIVE_API_KEY` 和 `PLATFORM_LLM_LIVE_MODEL`;`PLATFORM_LLM_LIVE_API_KIND` 可选,取值为 `anthropic` / `openai_chat` / `openai_responses`,省略或仅含空白时默认 `openai_responses`,未知非空值直接失败,避免拼写错误静默测到另一种协议。仓库根目录没有 `Cargo.toml`,必须显式指定 workspace manifest: ```bash PLATFORM_LLM_LIVE_BASE_URL=https://api.example.com/anthropic \