@codehz/ai 0.4.6 → 0.7.1

package/README.md

@@ -1,6 +1,48 @@
 # @codehz/ai
 
-统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的回调驱动 `MockAdapter`（`responses` / `messages` / `chat-completions` / `ollama` / `mock`）。
+统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的回调驱动 `MockAdapter`（`responses` / `messages` / `chat-completions` / `ollama` / `gemini` / `mock`）。
+
+## 0.6.0 迁移说明
+
+小 breaking：warnings 形状、tool_call 校验与 Chat Completions opaque 入站。
+
+### `warnings` 结构化
+
+`AIResponse.warnings` / `response.warning` / `response.completed.warnings` 由 `string[]` 改为：
+
+```ts
+type StreamWarning = { message: string; code?: WarningCode };
+// AIResponse.warnings?: StreamWarning[]
+```
+
+迁移：原先 `for (const w of response.warnings ?? []) console.log(w)` 改为读取 `w.message`（及可选 `w.code`）。
+
+### `tool_call.argumentsText` 校验
+
+运行时 `validateRequest` **不再**对 `tool_call.argumentsText` 做 `JSON.parse`；只校验为 `string`。object-wire adapter（ollama / messages / gemini）在入站映射（`parseToolArguments` / `parseJsonStrictObject`）时若参数不是合法 JSON object，抛 `AIRecoverableError`（`TOOL_CALL_ARGUMENTS_INVALID`）：`AdapterBase` soft-complete 为 `response.warning` + `response.completed`（`stopReason: "error"`），不向调用方抛错、也不发 provider HTTP。chat-completions / responses 仍按字符串透传。
+
+### Chat Completions opaque
+
+入站 opaque 仅接受 `messages` 形（`{ messages: ChatMessage[] }`）。单条 `{ role, content }` 已 **deprecate**（有效 envelope 下未识别 shape 会被跳过，不再当完整 assistant turn 还原）。出站仍写 `messages: [assistantReplayMessage]`。
+
+### 其余行为（0.6 一并落地，多为兼容增强）
+
+- HTTP adapter 错误码与 incomplete 流完成路径收敛；Chat Completions 支持 arguments-before-id 与 `function_call`/`tool_calls` 互斥 warning。
+- Aggregator 在 finalize 时从 `output` 派生 `text` / `toolCalls` / `serverTool*`；`argumentsText` 分块累积。
+- 四家厚 adapter 拆为 `map-request` / `map-stream`（对齐 `responses`）；opaque 恒尾置。
+
+## 0.5.0 迁移说明（摘要）
+
+`0.5.0` 收紧了根入口公开面：`AdapterBase`、`createEventFactory`、`aggregateEvents`、`normalizeRequest`、transport / `syntheticStream` 等**不再**从 `@codehz/ai` 根导出（内部模块）。
+
+**仍从根导出：** `createAIClient`、`collectStream`、错误类型与 `WarningCode`、全部 adapters 与 Mock 夹具、canonical 构造、`REASONING_LEVELS`，以及 canonical 类型。自定义 adapter 请实现 `BackendAdapter`。
+
+### 错误通道语义
+
+- `AIRequestError` / `AIProviderError` / `AIStreamError`：致命，同步或在异步迭代中抛出，不伪造 `response.completed`。
+- `AIMappingError`：由内部 `AdapterBase` 捕获后降级为 `response.warning`（`WarningCode.MAPPING_ERROR`）+ 空 output 的 `response.completed`（无 `stopReason`）；生产 adapter 原则上不抛。
+- `AIRecoverableError`：由内部 `AdapterBase` 捕获后 soft-complete 为 `response.warning`（code 取自错误）+ 空 replay 的 `response.completed`（`stopReason` 默认 `"error"`）。用于可清理历史后重试的回合失败（如 object-wire 入站非法 `tool_call.argumentsText`）。
+- 非致命差异走 `response.warning` 与 `WarningCode`（0.6 起为结构化对象）。
 
 ## 安装
 
@@ -41,8 +83,9 @@ for await (const event of stream) {
 type AIRequest = {
   instructions?: string | InstructionBlock[]; // 系统级指令
   input: InputItem[]; // 输入 items
-  tools?: ToolDefinition[]; // 工具声明
-  toolChoice?: ToolChoice; // 工具选择策略
+  tools?: ToolDefinition[]; // 客户端函数工具（由调用方执行）
+  serverTools?: ServerToolDefinition[]; // Provider 托管工具（web_search / code_execution / mcp）
+  toolChoice?: ToolChoice; // 客户端工具选择策略
   temperature?: number; // 温度 (0–2)
   maxOutputTokens?: number; // 最大输出 token
   reasoningLevel?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; // 可移植思考力度
@@ -50,25 +93,31 @@ type AIRequest = {
 };
 ```
 
+`tools` 与 `serverTools` 可在同一请求中共存。客户端 `tool_call` / 手动 tool-loop 语义不变；服务端工具由 provider 在请求内执行，**不会**把 `stopReason` 设为 `tool_call`。
+
 `reasoningLevel` 是 portable 枚举，由各 adapter 映射到 provider 原生字段；未设置时不写相关 wire 字段。adapter 无法映射的 level（如 Ollama 的 `minimal` / `xhigh` / `max`）会抛 `AIRequestError`（`UNSUPPORTED_REASONING_LEVEL`）。需要 budget / summary 等特化参数时，仍可用构造期 `extraBody` 覆盖同名顶层键。
 
-| Adapter | 映射 |
-| --- | --- |
-| `ResponsesAdapter` | `reasoning: { effort }` |
-| `ChatCompletionsAdapter` | 顶层 `reasoning_effort` |
-| `MessagesAdapter` | `thinking: { type: "disabled" }` 或 `{ type: "enabled", budget_tokens }`（由 `maxOutputTokens` 按比例推导，默认 4096） |
-| `OllamaAdapter` | `think: false \| "low" \| "medium" \| "high"` |
-| `MockAdapter` | 透传到 `MockHandlerContext.reasoningLevel` |
+| Adapter                  | 映射                                                                                                                               |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ResponsesAdapter`       | `reasoning: { effort }`                                                                                                            |
+| `ChatCompletionsAdapter` | 顶层 `reasoning_effort`                                                                                                            |
+| `MessagesAdapter`        | `thinking: { type: "disabled" }` 或 `{ type: "enabled", budget_tokens }`（由 `maxOutputTokens` 按比例推导，默认 4096）             |
+| `OllamaAdapter`          | `think: false \| "low" \| "medium" \| "high"`                                                                                      |
+| `GeminiAdapter`          | `generationConfig.thinkingConfig`（`none` 关闭 thoughts；`minimal`/`low`/`medium`/`high` → `thinkingLevel`；`xhigh`/`max` 不支持） |
+| `MockAdapter`            | 透传到 `MockHandlerContext.reasoningLevel`                                                                                         |
 
 `input` 是 item 数组，每个 item 可以是：
 
-| Item 类型     | 用途                                |
-| ------------- | ----------------------------------- |
-| `message`     | 用户 / 助手消息                     |
-| `reasoning`   | 思维链（输入侧 replay）             |
-| `tool_call`   | 模型发起的工具调用（输入侧 replay） |
-| `tool_result` | 工具执行结果                        |
-| `opaque`      | Provider 私有续接材料               |
+| Item 类型               | 用途                                |
+| ----------------------- | ----------------------------------- |
+| `message`               | 用户 / 助手消息（可带 `citations`） |
+| `reasoning`             | 思维链（输入侧 replay）             |
+| `tool_call`             | 客户端工具调用（输入侧 replay）     |
+| `tool_result`           | 客户端工具执行结果                  |
+| `server_tool_call`      | Provider 托管工具调用               |
+| `server_tool_result`    | Provider 托管工具结果               |
+| `server_tool_discovery` | MCP 等远端工具发现列表              |
+| `opaque`                | Provider 私有续接材料               |
 
 ### 统一事件流
 
@@ -80,18 +129,24 @@ response.started → (item.started → item.delta* → item.completed)* → resp
 
 事件类型：
 
-| 事件                                  | 含义                                        |
-| ------------------------------------- | ------------------------------------------- |
-| `response.started`                    | 响应开始                                    |
-| `message.{started,delta,completed}`   | 消息输出                                    |
-| `reasoning.{started,delta,completed}` | 思维链                                      |
-| `tool_call.{started,delta,completed}` | 工具调用                                    |
-| `response.warning`                    | 非致命警告                                  |
-| `response.auxiliary`                  | usage / billing 辅助信息                    |
-| `response.completed`                  | 响应结束，携带 replay、终止原因及最终元数据 |
+| 事件                                    | 含义                                        |
+| --------------------------------------- | ------------------------------------------- |
+| `response.started`                      | 响应开始                                    |
+| `message.{started,delta,completed}`     | 消息输出（`completed` 可带 `citations`）    |
+| `reasoning.{started,delta,completed}`   | 思维链                                      |
+| `tool_call.{started,delta,completed}`   | 客户端工具调用                              |
+| `server_tool.{started,delta,completed}` | 服务端工具调用                              |
+| `server_tool_result.completed`          | 服务端工具结果（原子）                      |
+| `server_tool_discovery.completed`       | MCP 工具发现（原子）                        |
+| `response.warning`                      | 非致命警告                                  |
+| `response.auxiliary`                    | usage / billing 辅助信息                    |
+| `response.completed`                    | 响应结束，携带 replay、终止原因及最终元数据 |
 
 ### 统一终结结果
 
+**`AIResponse` 的完整形态以 `collectStream()` / 事件聚合器为唯一真相源。**
+流式消费者读 `AIStreamEvent`；`response.completed` 只携带 `replay`、终止原因、usage/billing 等元数据，**不**携带完整 `output`/`text`/`toolCalls` 账本。
+
 流结束后可通过 `collectStream()` 聚合为 `AIResponse`：
 
 ```ts
@@ -106,18 +161,20 @@ console.log(response.replay); // 续接材料
 
 `AIResponse` 包含：
 
-| 字段         | 类型             | 说明                      |
-| ------------ | ---------------- | ------------------------- |
-| `output`     | `OutputItem[]`   | 当前轮输出                |
-| `replay`     | `ReplayItem[]`   | 续接材料（下次请求带回）  |
-| `text`       | `string`         | 全部文本拼接              |
-| `toolCalls`  | `ToolCallItem[]` | 工具调用                  |
-| `stopReason` | `StopReason?`    | 终止原因（可选）          |
-| `usage`      | `Usage?`         | token 统计（可选）        |
-| `billing`    | `BillingInfo?`   | 计费信息（可选）          |
-| `auxiliary`  | `AuxiliaryInfo?` | Provider 辅助信息（可选） |
-| `warnings`   | `string[]?`      | 非致命警告（可选）        |
-| `backend`    | `BackendTrace`   | 调用链路元数据            |
+| 字段                | 类型                     | 说明                               |
+| ------------------- | ------------------------ | ---------------------------------- |
+| `output`            | `OutputItem[]`           | 当前轮输出                         |
+| `replay`            | `ReplayItem[]`           | 续接材料（下次请求带回）           |
+| `text`              | `string`                 | 全部文本拼接                       |
+| `toolCalls`         | `ToolCallItem[]`         | 客户端工具调用                     |
+| `serverToolCalls`   | `ServerToolCallItem[]`   | 服务端工具调用                     |
+| `serverToolResults` | `ServerToolResultItem[]` | 服务端工具结果                     |
+| `stopReason`        | `StopReason?`            | 终止原因（可选）                   |
+| `usage`             | `Usage?`                 | token 统计（可选）                 |
+| `billing`           | `BillingInfo?`           | 计费信息（可选）                   |
+| `auxiliary`         | `AuxiliaryInfo?`         | Provider 辅助信息（可选）          |
+| `warnings`          | `StreamWarning[]?`       | 非致命警告（`{ message; code? }`） |
+| `backend`           | `BackendTrace`           | 调用链路元数据                     |
 
 流式 `message.delta` / `reasoning.delta` 保持后端分片粒度；完成态 `output` 中的
 `message` / `reasoning` 会合并相邻 `text` content blocks（直接拼接且不添加分隔符），
@@ -125,13 +182,14 @@ console.log(response.replay); // 续接材料
 
 ## 后端 Adapter
 
-| Adapter                 | 类                       | 说明                    |
-| ----------------------- | ------------------------ | ----------------------- |
-| OpenAI Responses API    | `ResponsesAdapter`       | OpenAI Responses 端点   |
-| Anthropic Messages API  | `MessagesAdapter`        | Anthropic Messages 端点 |
-| OpenAI Chat Completions | `ChatCompletionsAdapter` | Chat Completions 端点   |
-| Ollama Chat API         | `OllamaAdapter`          | 本地或自托管 Ollama     |
-| Scripted Test Backend   | `MockAdapter`            | 脚本化测试夹具          |
+| Adapter                 | 类                       | 说明                           |
+| ----------------------- | ------------------------ | ------------------------------ |
+| OpenAI Responses API    | `ResponsesAdapter`       | OpenAI Responses 端点          |
+| Anthropic Messages API  | `MessagesAdapter`        | Anthropic Messages 端点        |
+| OpenAI Chat Completions | `ChatCompletionsAdapter` | Chat Completions 端点          |
+| Ollama Chat API         | `OllamaAdapter`          | 本地或自托管 Ollama            |
+| Google Gemini API       | `GeminiAdapter`          | Gemini `streamGenerateContent` |
+| Scripted Test Backend   | `MockAdapter`            | 脚本化测试夹具                 |
 
 ```ts
 import {
@@ -139,6 +197,7 @@ import {
   MessagesAdapter,
   ChatCompletionsAdapter,
   OllamaAdapter,
+  GeminiAdapter,
   MockAdapter,
   withMockStreaming,
 } from "@codehz/ai";
@@ -172,6 +231,15 @@ const ollama = new OllamaAdapter({
   extraBody: { keep_alive: "10m" },
 });
 
+// Google Gemini Developer API（原生 generateContent 流，非 OpenAI 兼容层）
+const gemini = new GeminiAdapter({
+  apiKey: process.env.GEMINI_API_KEY!,
+  // 可选：代理 / Vertex 兼容端点
+  // baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+  headers: { "X-Custom": "..." },
+  extraBody: { safetySettings: [] },
+});
+
 // 面向测试的回调驱动 mock backend
 const mock = new MockAdapter({
   handler: withMockStreaming(
@@ -202,6 +270,49 @@ adapter.isSyntheticStream;
 响应级 `backend.isSyntheticStream` 使用同一标记；具体响应内容仍应从
 本次事件流、warning 和 `replay` 判断。
 
+### 上下文压缩（可选能力）
+
+部分 adapter 原生支持上下文压缩，通过独立接口暴露，**不**挂在 `BackendAdapter` / `AIClient` 上：
+
+| Adapter            | `supportsContextCompress` | 说明                                                                    |
+| ------------------ | ------------------------- | ----------------------------------------------------------------------- |
+| `ResponsesAdapter` | 是                        | `POST /responses/compact`；结果为 opaque `compacted_window`             |
+| `MockAdapter`      | 是                        | 构造期可选 `compressHandler`；未配置则抛 `MOCK_COMPRESS_NOT_CONFIGURED` |
+| 其余内置 adapter   | 否                        | 本期无客户端摘要 fallback                                               |
+
+```ts
+import { ResponsesAdapter, supportsContextCompress, createAIClient, collectStream } from "@codehz/ai";
+import type { InputItem } from "@codehz/ai";
+
+const adapter = new ResponsesAdapter({ apiKey: process.env.OPENAI_API_KEY! });
+const client = createAIClient({ adapter, model: "gpt-5.1" });
+
+let transcript: InputItem[] = [/* 多轮累积 */];
+
+if (supportsContextCompress(adapter)) {
+  // 用 replay 替换旧 transcript（不要 append 全文）
+  const { replay } = await adapter.compress({
+    model: "gpt-5.1",
+    input: transcript,
+  });
+  transcript = [...replay];
+}
+
+transcript.push({
+  type: "message",
+  role: "user",
+  content: [{ type: "text", text: "继续上一任务" }],
+});
+
+const response = await collectStream(client.stream({ input: transcript }));
+```
+
+边界：
+
+- 本期仅覆盖 **独立** `compress()`；不支持在 `stream` 请求里自动 `context_management` / `compact_threshold`。
+- Anthropic Messages 的请求内 compaction 未接入（无独立端点，另期）。
+- 调用方负责何时压缩与 transcript 替换；库不托管会话状态。
+
 ## Mock 后端
 
 `MockAdapter` 是一个面向测试的回调驱动 adapter，用来验证长流程工具调用、`replay` 续接和异常路径。
@@ -227,9 +338,10 @@ const handler = withMockStreaming(
 
 - handler 会拿到 `request` 和 `context`
 - `context` 内建 `previousReplay`、`pendingToolCalls`、`history`
-- handler 可脚本化发出 `message` / `reasoning` / `tool_call`
+- handler 可脚本化发出 `message` / `reasoning` / `tool_call` / `server_tool_*`
+- message step 可附带 `citations`
 - 可注入 `warning`、`content_filter`、transport interruption、provider-style error
-- 可用 `assertMockRequest()` 验证调用方是否把上一轮 `replay` 和当前 `tool_result` 正确带回
+- 可用 `assertMockRequest()` 验证 `replay` / `tool_result` / `serverTools` 等期望
 
 ```ts
 import { assertMockRequest, createAIClient, MockAdapter } from "@codehz/ai";
@@ -300,7 +412,7 @@ yield { type: "interrupt" }; // 不发 response.completed，collectStream() 应
 ```
 
 ```ts
-yield { type: "warning", message: "content filtered by policy", code: "CONTENT_FILTERED" };
+yield { type: "warning", message: "content filtered by policy", code: "CONTENT_FILTER" };
 yield { type: "complete", stopReason: "content_filter" };
 ```
 
@@ -320,6 +432,64 @@ const r2 = await collectStream(client.stream({ input: transcript }));
 
 详细示例见 [examples/multi-turn.ts](./examples/multi-turn.ts)。
 
+## 服务端工具（`serverTools`）
+
+Provider 托管工具（不进客户端 tool loop）。首版由 `ResponsesAdapter` 落地：
+
+| Canonical `serverTools` | Responses wire             | 说明                                           |
+| ----------------------- | -------------------------- | ---------------------------------------------- |
+| `web_search`            | `type: "web_search"`       | 域名过滤、`userLocation`、`searchContextSize`  |
+| `code_execution`        | `type: "code_interpreter"` | 仅 auto container（`memoryLimit` / `fileIds`） |
+| `mcp`                   | `type: "mcp"`              | 远程 MCP；**仅** `requireApproval: "never"`    |
+
+```ts
+const stream = client.stream({
+  input: [{ type: "message", role: "user", content: [{ type: "text", text: "杭州今天天气？" }] }],
+  serverTools: [
+    {
+      type: "web_search",
+      allowedDomains: ["example.com"],
+      searchContextSize: "low",
+    },
+    {
+      type: "code_execution",
+      container: { type: "auto", memoryLimit: "4g" },
+    },
+    {
+      type: "mcp",
+      serverLabel: "dmcp",
+      serverUrl: "https://dmcp-server.example/mcp",
+      requireApproval: "never",
+      // authorization 每请求由调用方重传；不会写入 opaque 回放
+      authorization: process.env.MCP_TOKEN,
+    },
+  ],
+});
+
+const result = await collectStream(stream);
+console.log(result.serverToolCalls);
+console.log(result.serverToolResults);
+// 消息 citations（url / container_file）挂在 MessageItem.citations
+```
+
+支持矩阵：
+
+| Adapter                                              | `serverTools`                                                          |
+| ---------------------------------------------------- | ---------------------------------------------------------------------- |
+| `ResponsesAdapter`                                   | 请求映射 + SSE 解析                                                    |
+| `MockAdapter`                                        | 可脚本化产出 `server_tool_*` 事件与 citations                          |
+| `ChatCompletions` / `Messages` / `Ollama` / `Gemini` | 传入非空 `serverTools` → `AIRequestError`（`UNSUPPORTED_SERVER_TOOL`） |
+
+范围说明（刻意不做）：
+
+- 客户端自动 tool-loop（仍由调用方编排）
+- computer_use / shell 托管
+- Chat Completions 搜索专用模型
+- MCP approval 交互回路（出现 `mcp_approval_request` 会 `response.warning`）
+- Containers REST 管理 API
+
+多轮续写推荐用 Responses 的 `previous_response_id` opaque replay，无需把 server tool result 当客户端 `tool_result` 回传。Mock 演示见 [examples/server-tools.ts](./examples/server-tools.ts)。
+
 ## 手动工具循环
 
 模型返回 `tool_call` → 调用方执行工具 → 下一轮带入 `tool_result`：
@@ -346,37 +516,13 @@ const r2 = await collectStream(client.stream({ input, tools }));
 
 ## 模拟流式
 
-非流式后端可通过 `syntheticStream()` 包装为规范事件流：
-
-```ts
-import { syntheticStream } from "@codehz/ai";
-
-const events = syntheticStream({
-  model: "gpt-4o",
-  responseId: "req-1",
-  backend: { kind: "chat-completions" },
-  output: [messageItem([textBlock("Hello")])],
-  stopReason: "end_turn",
-});
+真实 adapter 在原生流不可用时，库内部会用 synthetic 路径包装为规范事件流。应用层一般只需消费 `client.stream()` / `collectStream()`；`0.5.0` 起 `syntheticStream` 不再从根入口导出（test-first helper，不展开 `server_tool_*`）。
 
-for await (const event of events) {
-  // 消费规范事件
-}
-```
+若只需前端逐字预览效果，请优先使用 `MockAdapter` + `withMockStreaming()`（见上文 Mock 后端）。
 
 ## 辅助信息采集
 
-`AuxiliaryCollector` 提供分层 best-effort 采集（流事件 → headers → lookup → derived）：
-
-```ts
-import { AuxiliaryCollector } from "@codehz/ai";
-
-const collector = new AuxiliaryCollector();
-collector.recordUsage({ inputTokens: 10, outputTokens: 5 }, "stream");
-collector.recordBilling({ amount: 0.002, currency: "USD", isEstimated: false, source: "provider" }, "final");
-
-const { usage, billing, auxiliary, warnings } = collector.build();
-```
+usage / billing / providerMetadata 由 adapter 在流结束时经 `response.auxiliary` 与 `AIResponse` 字段交付。`AuxiliaryCollector` 是 provider 内部实现细节，`0.5.0` 起不再从根入口导出。`lookup` / `postprocessBilling` 为 experimental 扩展点，库内 HTTP adapter 默认未接线。
 
 ## 开发命令