From 5fb9af8303d0c8a3ae03834157074f8c80472fe7 Mon Sep 17 00:00:00 2001 From: Linghong Date: Mon, 27 Jul 2026 03:34:39 +0000 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E6=B5=81=E5=BC=8F=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E9=AA=8C=E6=94=B6=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 校正真实端点 smoke 的必填环境变量与可选 API kind 口径 修复 Bash 和 PowerShell 执行示例 明确文本增量字符数仅用于打印观测 --- docs/【开发运维】本地开发验证与生产运维-2026-05-15.md | 10 +++++----- server-rs/crates/platform-llm/README.md | 2 +- .../platform-llm/tests/live_stream_tool_calls.rs | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index a21ae5736..af0493caa 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -653,19 +653,19 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日 流式工具片段按协议 slot 聚合，Responses 允许从 `response.completed.response.output[]` 做 completed-only 工具恢复。收尾时空参数默认 `{}`，非空参数必须是完整 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` 只对真实端点做归一后的工具调用 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 \ -PLATFORM_LLM_LIVE_API_KEY=<从密钥管理处取，勿写入仓库> \ -PLATFORM_LLM_LIVE_MODEL=<模型名> \ +PLATFORM_LLM_LIVE_API_KEY='<从密钥管理处取，勿写入仓库>' \ +PLATFORM_LLM_LIVE_MODEL='<模型名>' \ PLATFORM_LLM_LIVE_API_KIND=anthropic \ cargo test -p platform-llm --manifest-path server-rs/Cargo.toml --test live_stream_tool_calls -- --ignored --nocapture ``` -PowerShell 下先用 `$env:PLATFORM_LLM_LIVE_API_KEY = '...'` 赋值再执行同一条 `cargo test`。切换 `PLATFORM_LLM_LIVE_API_KIND` 逐个跑三种协议，才算覆盖完整；`--nocapture` 会打印解析出的工具名、id 和参数，便于核对。 +PowerShell 下按测试文件头部示例依次设置三个必填变量，并按需设置 `$env:PLATFORM_LLM_LIVE_API_KIND`，再执行同一条 `cargo test`。切换 `PLATFORM_LLM_LIVE_API_KIND` 逐个跑三种协议，才算覆盖完整；`--nocapture` 会打印解析出的工具名、id、参数和文本增量字符数，便于核对。 该用例只从进程环境变量读取凭据，不读 `.env.secrets.local`，也不会写入任何文件。真实 API Key 一律不得提交进仓库，也不要写进 `docs/`、脚本默认值或测试 fixture；临时密钥用完应在上游及时吊销。 diff --git a/server-rs/crates/platform-llm/README.md b/server-rs/crates/platform-llm/README.md index 344ebe33c..3521d3eb3 100644 --- a/server-rs/crates/platform-llm/README.md +++ b/server-rs/crates/platform-llm/README.md @@ -88,5 +88,5 @@ Responses 如果只发送 `response.completed`，解析器会从其中的 `respo ## 9. 验收证据边界 1. `cargo test -p platform-llm` 的确定性用例把 checked-in SSE fixture 交给 parser，验证归一后的文本、工具调用、slot 聚合、Responses completed-only 恢复、参数 JSON 完整性和错误边界。fixture 可以来源于真实端点抓包，但测试不保存原始 SSE，也不逐事件与端点报文比较，因此不能证明抓包转录无偏差。 -2. `tests/live_stream_tool_calls.rs` 是默认 `#[ignore]` 的真实端点工具调用 smoke。它只验证最终归一结果中的工具名、id、完整参数 JSON 和文本增量字符数；工具调用不进入 `on_delta`，也没有原始 SSE 录制或逐事件对比能力。 +2. `tests/live_stream_tool_calls.rs` 是默认 `#[ignore]` 的真实端点工具调用 smoke。它只验证最终归一结果中的工具名、id 和完整参数 JSON；文本增量字符数仅用于打印观测，工具调用不进入 `on_delta`，也没有原始 SSE 录制或逐事件对比能力。 3. 因此验收应分别称为“固定 SSE fixture parser 覆盖”和“真实端点归一工具调用 smoke”，不能把后者描述为原始 SSE fidelity 或转录一致性证明。 diff --git a/server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs b/server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs index 6b45652b8..2f9c2a847 100644 --- a/server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs +++ b/server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs @@ -12,8 +12,8 @@ //! //! 凭据只从进程环境变量读取，不要写进仓库内任何文件。 //! -//! 本用例是实时端点工具调用 smoke，只验证归一后的工具名、id、完整参数 JSON -//! 和文本增量字符数；不录制或逐事件比对原始 SSE，也不承担固定 fixture 转录一致性证明。 +//! 本用例是实时端点工具调用 smoke，只验证归一后的工具名、id 和完整参数 JSON； +//! 文本增量字符数仅用于打印观测，不录制或逐事件比对原始 SSE，也不承担固定 fixture 转录一致性证明。 use platform_llm::{ LlmApiKind, LlmClient, LlmConfig, LlmFunctionTool, LlmMessage, LlmProvider, LlmRunRequest,