@codehz/ai 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # nano-ai
 
-统一流式 AI 客户端 — 一套 canonical API，三种后端协议（`responses` / `messages` / `chat.completions`）。
+统一流式 AI 客户端 — 一套 canonical API，支持真实模型后端与面向测试的脚本化 `MockAdapter`（`responses` / `messages` / `chat.completions` / `ollama` / `mock`）。
 
 ## 安装
 
@@ -114,9 +114,11 @@ console.log(response.replay); // 续接材料
 | OpenAI Responses API    | `ResponsesAdapter`       | 🌟🌟🌟   |
 | Anthropic Messages API  | `MessagesAdapter`        | 🌟🌟☆    |
 | OpenAI Chat Completions | `ChatCompletionsAdapter` | 🌟☆☆     |
+| Ollama Chat API         | `OllamaAdapter`          | 🌟☆☆     |
+| Scripted Test Backend   | `MockAdapter`            | 测试夹具 |
 
 ```ts
-import { ResponsesAdapter, MessagesAdapter, ChatCompletionsAdapter } from "nano-ai";
+import { ResponsesAdapter, MessagesAdapter, ChatCompletionsAdapter, OllamaAdapter, MockAdapter } from "nano-ai";
 
 // OpenAI Responses API（能力最强）
 const responses = new ResponsesAdapter({ apiKey: "sk-..." });
@@ -126,6 +128,26 @@ const messages = new MessagesAdapter({ apiKey: "sk-ant-..." });
 
 // OpenAI Chat Completions（兼容层）
 const chat = new ChatCompletionsAdapter({ apiKey: "sk-..." });
+
+// Ollama
+const ollama = new OllamaAdapter({ baseUrl: "http://localhost:11434" });
+
+// 面向测试的脚本化 mock backend
+const mock = new MockAdapter({
+  turns: [
+    {
+      steps: [
+        { type: "message", content: "我先调用天气工具。" },
+        {
+          type: "tool_call",
+          id: "mock-call-weather",
+          name: "get_weather",
+          argumentsText: '{"city":"Hangzhou"}',
+        },
+      ],
+    },
+  ],
+});
 ```
 
 各 adapter 的能力差异通过 `capabilities` 字段暴露：
@@ -136,6 +158,89 @@ adapter.capabilities.toolCallStreaming; // 是否支持工具调用流
 adapter.capabilities.replayFidelity; // "high" | "medium" | "low"
 ```
 
+## Mock 后端
+
+`MockAdapter` 现在不是“按关键词回文本”的通用假后端，而是专门用于测试长流程工具调用、`replay` 续接、以及异常路径的脚本化测试夹具。
+
+核心思路是按 turn 写脚本：
+
+- 每一轮可声明对请求格式的期望
+- 每一轮可脚本化发出 `message` / `reasoning` / `tool_call`
+- 可注入 `warning`、`content_filter`、transport interruption、provider-style error
+- 可验证调用方是否把上一轮 `replay` 和当前 `tool_result` 正确带回
+
+```ts
+import { createAIClient, MockAdapter } from "nano-ai";
+
+const client = createAIClient({
+  adapter: new MockAdapter({
+    turns: [
+      {
+        name: "request-tool",
+        expect: {
+          items: [{ type: "message", role: "user", textIncludes: "weather" }],
+          tools: "present",
+          toolChoice: "present",
+        },
+        steps: [
+          { type: "message", content: "Checking weather now." },
+          {
+            type: "tool_call",
+            id: "mock-call-weather",
+            name: "get_weather",
+            argumentsText: '{"city":"Hangzhou"}',
+          },
+        ],
+      },
+      {
+        name: "consume-tool-result",
+        expect: {
+          requireReplayFromPreviousTurn: true,
+          requireToolResultsForPendingCalls: true,
+        },
+        steps: [{ type: "message", content: "Hangzhou is 28C and sunny." }],
+      },
+    ],
+  }),
+  model: "mock-model",
+});
+```
+
+核心类型：
+
+```ts
+type MockTurn = {
+  name?: string;
+  expect?: MockRequestExpectation | MockTurnValidator;
+  steps: MockStep[];
+};
+```
+
+测试工具循环时，第二轮通常会要求：
+
+- `requireReplayFromPreviousTurn: true`
+- `requireToolResultsForPendingCalls: true`
+
+畸形路径示例：
+
+```ts
+{
+  steps: [
+    { type: "message", content: "partial answer" },
+    { type: "interrupt" }, // 不发 response.completed，collectStream() 应失败
+  ],
+}
+```
+
+```ts
+{
+  steps: [
+    { type: "warning", message: "content filtered by policy", code: "CONTENT_FILTERED" },
+    { type: "complete", stopReason: "content_filter" },
+  ],
+}
+```
+
 ## 多轮对话
 
 库不托管会话状态。调用方自行保留 `response.replay` 并在下一轮带回：

package/package.json

@@ -26,5 +26,5 @@
     "tsdown": "^0.22.3",
     "typescript": "^6"
   },
-  "version": "0.1.0"
+  "version": "0.1.1"
 }

package/src/adapters/chat-completions.ts

@@ -161,6 +161,7 @@ function ensureTextCompatibleBlocks(
 ): import("../index.js").ContentBlock[] {
   for (let i = 0; i < blocks.length; i++) {
     const block = blocks[i];
+    if (!block) continue;
     if (block.type !== "text" && block.type !== "json") {
       throw new AIRequestError(
         `chat-completions does not support ${field}[${i}] of type "${block.type}"; only text/json blocks are supported`,

package/src/adapters/index.ts

@@ -6,6 +6,7 @@
  * - messages
  * - chat.completions
  * - ollama
+ * - mock
  *
  * 每个 adapter 实现 BackendAdapter 内部协议。
  */
@@ -18,3 +19,23 @@ export { ChatCompletionsAdapter } from "./chat-completions.js";
 export type { ChatCompletionsAdapterOptions } from "./chat-completions.js";
 export { OllamaAdapter } from "./ollama.js";
 export type { OllamaAdapterOptions } from "./ollama.js";
+export { MockAdapter } from "./mock.js";
+export type {
+  MockAdapterOptions,
+  MockInputExpectation,
+  MockRequestExpectation,
+  MockTurnContext,
+  MockTurnValidator,
+  MockWarningStep,
+  MockAuxiliaryStep,
+  MockMessageStep,
+  MockReasoningStep,
+  MockToolCallStep,
+  MockOutputStep,
+  MockCompleteStep,
+  MockErrorStep,
+  MockInterruptStep,
+  MockThrowStep,
+  MockStep,
+  MockTurn,
+} from "./mock.js";

package/src/adapters/messages.ts

@@ -78,6 +78,7 @@ function ensureMessagesTextBlocks(
 ): import("../index.js").ContentBlock[] {
   for (let i = 0; i < blocks.length; i++) {
     const block = blocks[i];
+    if (!block) continue;
     if (block.type !== "text" && block.type !== "json") {
       throw new AIRequestError(
         `messages does not support ${field}[${i}] of type "${block.type}"; only text/json blocks are supported`,