@codehz/ai 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # nano-ai
 
-统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的脚本化 `MockAdapter`（`responses` / `messages` / `chat.completions` / `ollama` / `mock`）。
+统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的回调驱动 `MockAdapter`（`responses` / `messages` / `chat.completions` / `ollama` / `mock`）。
 
 ## 安装
 
@@ -39,7 +39,7 @@ for await (const event of stream) {
 
 ```ts
 type AIRequest = {
-  instructions?: string; // 系统指令
+  instructions?: string | InstructionBlock[]; // 系统级指令
   input: InputItem[]; // 输入 items
   tools?: ToolDefinition[]; // 工具声明
   toolChoice?: ToolChoice; // 工具选择策略
@@ -53,7 +53,7 @@ type AIRequest = {
 
 | Item 类型     | 用途                                |
 | ------------- | ----------------------------------- |
-| `message`     | 用户 / 助手 / 系统消息              |
+| `message`     | 用户 / 助手消息                     |
 | `reasoning`   | 思维链（输入侧 replay）             |
 | `tool_call`   | 模型发起的工具调用（输入侧 replay） |
 | `tool_result` | 工具执行结果                        |
@@ -109,16 +109,23 @@ 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     |
+| Scripted Test Backend   | `MockAdapter`            | 脚本化测试夹具          |
 
 ```ts
-import { ResponsesAdapter, MessagesAdapter, ChatCompletionsAdapter, OllamaAdapter, MockAdapter } from "nano-ai";
+import {
+  ResponsesAdapter,
+  MessagesAdapter,
+  ChatCompletionsAdapter,
+  OllamaAdapter,
+  MockAdapter,
+  withMockStreaming,
+} from "nano-ai";
 
 // OpenAI Responses API
 const responses = new ResponsesAdapter({ apiKey: "sk-..." });
@@ -132,25 +139,23 @@ const chat = new ChatCompletionsAdapter({ apiKey: "sk-..." });
 // Ollama
 const ollama = new OllamaAdapter({ baseUrl: "http://localhost:11434" });
 
-// 面向测试的脚本化 mock backend
+// 面向测试的回调驱动 mock backend
 const mock = new MockAdapter({
-  stream: {
-    charsPerSecond: 24,
-    chunkSize: 1,
-  },
-  turns: [
+  handler: withMockStreaming(
+    async function* () {
+      yield { type: "message", content: "我先调用天气工具。" };
+      yield {
+        type: "tool_call",
+        id: "mock-call-weather",
+        name: "get_weather",
+        argumentsText: '{"city":"Hangzhou"}',
+      };
+    },
     {
-      steps: [
-        { type: "message", content: "我先调用天气工具。" },
-        {
-          type: "tool_call",
-          id: "mock-call-weather",
-          name: "get_weather",
-          argumentsText: '{"city":"Hangzhou"}',
-        },
-      ],
+      charsPerSecond: 24,
+      chunkSize: 1,
     },
-  ],
+  ),
 });
 ```
 
@@ -165,66 +170,71 @@ adapter.nativeStreaming; // 是否为 provider 原生流，而不是本地模拟
 
 ## Mock 后端
 
-`MockAdapter` 是一个面向测试的脚本化 adapter，用来验证长流程工具调用、`replay` 续接和异常路径。
+`MockAdapter` 是一个面向测试的回调驱动 adapter，用来验证长流程工具调用、`replay` 续接和异常路径。
 
-如果你要调试前端逐字渲染效果，可以给 `MockAdapter` 打开分片流：
+如果你要调试前端逐字渲染效果，可以用 `withMockStreaming()` 给非流式 handler 包一层分片输出：
 
 ```ts
-const mock = new MockAdapter({
-  stream: {
+const handler = withMockStreaming(
+  async function* () {
+    yield { type: "message", content: "Streaming preview for the frontend." };
+  },
+  {
     charsPerSecond: 20, // 每秒约 20 个字符
     chunkSize: 1, // 默认 1，即逐字输出
     initialDelayMs: 150, // 可选：首字前停顿
   },
-  turns: [
-    {
-      steps: [{ type: "message", content: "Streaming preview for the frontend." }],
-    },
-  ],
-});
+);
 ```
 
-默认会发出单个完整 `message.delta`。只有显式配置 `stream` 时，`message` / `reasoning` / `tool_call` 参数才会被拆成多个 delta。单个 step 也可用 `stream: false` 关闭全局流速配置。
+默认会发出单个完整 `message.delta`。只有经 `withMockStreaming()` 注入默认流速后，`message` / `reasoning` / `tool_call` 参数才会被拆成多个 delta。单个 step 也可用 `stream: false` 关闭包装器的默认流速配置。
 
-核心思路是按 turn 写脚本：
+核心思路是每轮请求执行一次 handler：
 
-- 每一轮可声明对请求格式的期望
-- 每一轮可脚本化发出 `message` / `reasoning` / `tool_call`
+- handler 会拿到 `request` 和 `context`
+- `context` 内建 `previousReplay`、`pendingToolCalls`、`history`
+- handler 可脚本化发出 `message` / `reasoning` / `tool_call`
 - 可注入 `warning`、`content_filter`、transport interruption、provider-style error
-- 可验证调用方是否把上一轮 `replay` 和当前 `tool_result` 正确带回
+- 可用 `assertMockRequest()` 验证调用方是否把上一轮 `replay` 和当前 `tool_result` 正确带回
 
 ```ts
-import { createAIClient, MockAdapter } from "nano-ai";
+import { assertMockRequest, 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." },
+    handler: async function* (request, context) {
+      if (context.turnIndex === 0) {
+        assertMockRequest(
+          request,
           {
-            type: "tool_call",
-            id: "mock-call-weather",
-            name: "get_weather",
-            argumentsText: '{"city":"Hangzhou"}',
+            items: [{ type: "message", role: "user", textIncludes: "weather" }],
+            tools: "present",
+            toolChoice: "present",
           },
-        ],
-      },
-      {
-        name: "consume-tool-result",
-        expect: {
+          context,
+        );
+
+        yield { type: "message", content: "Checking weather now." };
+        yield {
+          type: "tool_call",
+          id: "mock-call-weather",
+          name: "get_weather",
+          argumentsText: '{"city":"Hangzhou"}',
+        };
+        return;
+      }
+
+      assertMockRequest(
+        request,
+        {
           requireReplayFromPreviousTurn: true,
           requireToolResultsForPendingCalls: true,
         },
-        steps: [{ type: "message", content: "Hangzhou is 28C and sunny." }],
-      },
-    ],
+        context,
+      );
+
+      yield { type: "message", content: "Hangzhou is 28C and sunny." };
+    },
   }),
   model: "mock-model",
 });
@@ -233,10 +243,13 @@ const client = createAIClient({
 核心类型：
 
 ```ts
-type MockTurn = {
-  name?: string;
-  expect?: MockRequestExpectation | MockTurnValidator;
-  steps: MockStep[];
+type MockHandler = (request: NormalizedRequest, context: MockHandlerContext) => AsyncIterable<MockStep>;
+
+type MockHandlerContext = {
+  turnIndex: number;
+  previousReplay: ReplayItem[];
+  pendingToolCalls: readonly ToolCallItem[];
+  history: readonly MockHistoryRecord[];
 };
 ```
 
@@ -248,21 +261,13 @@ type MockTurn = {
 畸形路径示例：
 
 ```ts
-{
-  steps: [
-    { type: "message", content: "partial answer" },
-    { type: "interrupt" }, // 不发 response.completed，collectStream() 应失败
-  ],
-}
+yield { type: "message", content: "partial answer" };
+yield { type: "interrupt" }; // 不发 response.completed，collectStream() 应失败
 ```
 
 ```ts
-{
-  steps: [
-    { type: "warning", message: "content filtered by policy", code: "CONTENT_FILTERED" },
-    { type: "complete", stopReason: "content_filter" },
-  ],
-}
+yield { type: "warning", message: "content filtered by policy", code: "CONTENT_FILTERED" };
+yield { type: "complete", stopReason: "content_filter" };
 ```
 
 ## 多轮对话

package/dist/index.d.mts

@@ -4,13 +4,16 @@
  *
  * 覆盖文本、JSON、图片、二进制引用和后端私有内容。
  */
-type ContentBlock = {
+type TextContentBlock = {
   type: "text";
   text: string;
-} | {
+};
+type JsonContentBlock = {
   type: "json";
   json: unknown;
-} | {
+};
+type InstructionBlock = TextContentBlock | JsonContentBlock;
+type ContentBlock = InstructionBlock | {
   type: "image";
   imageUrl: string;
 } | {
@@ -25,7 +28,7 @@ type ContentBlock = {
 type MessageItem = {
   type: "message";
   id?: string;
-  role: "user" | "assistant" | "system" | "developer";
+  role: "user" | "assistant";
   content: ContentBlock[];
 };
 type ReasoningItem = {
@@ -78,7 +81,7 @@ type IncludeSettings = {
   providerMetadata?: "off" | "best_effort";
 };
 type AIRequest = {
-  instructions?: string | ContentBlock[];
+  instructions?: string | InstructionBlock[];
   input: InputItem[];
   tools?: ToolDefinition[];
   toolChoice?: ToolChoice;
@@ -542,7 +545,7 @@ type ResponsesAPIRequest = {
 };
 type ResponsesInputItem = {
   type: "message";
-  role: "user" | "assistant" | "system" | "developer";
+  role: "user" | "assistant";
   content: string;
 } | {
   type: "message";
@@ -797,13 +800,18 @@ type MockRequestExpectation = {
   toolChoice?: "ignore" | "present" | "absent";
   items?: MockInputExpectation[];
 };
-type MockTurnContext = {
+type MockHistoryRecord = {
+  turnIndex: number;
+  requestId: string;
+  replay: ReplayItem[];
+  toolCalls: ToolCallItem[];
+};
+type MockHandlerContext = {
   turnIndex: number;
   previousReplay: ReplayItem[];
   pendingToolCalls: readonly ToolCallItem[];
-  history: readonly MockTurnRecord[];
+  history: readonly MockHistoryRecord[];
 };
-type MockTurnValidator = (request: NormalizedRequest, context: MockTurnContext) => void | Promise<void>;
 type MockWarningStep = {
   type: "warning";
   message: string;
@@ -886,38 +894,25 @@ type MockThrowStep = {
   error: string | Error;
 };
 type MockStep = MockWarningStep | MockAuxiliaryStep | MockMessageStep | MockReasoningStep | MockToolCallStep | MockOutputStep | MockCompleteStep | MockErrorStep | MockInterruptStep | MockThrowStep;
-type MockTurn = {
-  name?: string;
-  expect?: MockRequestExpectation | MockTurnValidator;
-  steps: MockStep[];
-};
+type MockHandler = (request: NormalizedRequest, context: MockHandlerContext) => AsyncIterable<MockStep>;
+type MockHandlerSource = Iterable<MockStep> | AsyncIterable<MockStep>;
+type MockStaticHandler = (request: NormalizedRequest, context: MockHandlerContext) => MockHandlerSource | Promise<MockHandlerSource>;
 type MockAdapterOptions = {
-  turns: MockTurn[];
-  onExhausted?: "throw" | "repeat-last" | "complete-empty";
+  handler: MockHandler;
   providerMetadata?: Record<string, unknown>;
-  stream?: MockTextStreamOptions;
-};
-type MockTurnRecord = {
-  turnIndex: number;
-  turnName?: string;
-  requestId: string;
-  replay: ReplayItem[];
-  toolCalls: ToolCallItem[];
 };
 type MockProviderRequest = {
   request: NormalizedRequest;
-  turn: MockTurn;
+  handlerResult: AsyncIterable<MockStep>;
   turnIndex: number;
-  turnName?: string;
   remainingPendingToolCalls: ToolCallItem[];
 };
+declare function assertMockRequest(request: NormalizedRequest, expectation: MockRequestExpectation, context: MockHandlerContext): void;
 declare class MockAdapter extends AdapterBase {
   readonly kind: "mock";
   readonly nativeStreaming = false;
-  private readonly turns;
-  private readonly onExhausted;
+  private readonly handler;
   private readonly providerMetadata?;
-  private readonly defaultStream?;
   private cursor;
   private previousReplay;
   private pendingToolCalls;
@@ -927,9 +922,9 @@ declare class MockAdapter extends AdapterBase {
   protected buildRequest(request: NormalizedRequest): Promise<MockProviderRequest>;
   protected runStream(providerRequest: unknown, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
   private finalizeTurn;
-  private resolveTurn;
-  private buildTurnContext;
+  private buildHandlerContext;
 }
+declare function withMockStreaming(handler: MockStaticHandler, options: MockTextStreamOptions): MockHandler;
 //#endregion
 //#region src/helpers/mapping.d.ts
 declare function mapStopReason(providerReason: string): StopReason;
@@ -967,9 +962,9 @@ declare function blockToText(b: ContentBlock): string;
  */
 declare function contentBlocksToText(blocks: ContentBlock[]): string;
 /**
- * 将 instructions（string | ContentBlock[]）归一化为纯文本。
+ * 将 instructions（string | InstructionBlock[]）归一化为纯文本。
  */
-declare function instructionsToText(instructions: string | ContentBlock[]): string;
+declare function instructionsToText(instructions: string | InstructionBlock[]): string;
 /**
  * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
  */
@@ -1051,5 +1046,5 @@ type SyntheticStreamOptions = {
  */
 declare function syntheticStream(options: SyntheticStreamOptions): AsyncIterable<AIStreamEvent>;
 //#endregion
-export { type AIClient, AIError, AIMappingError, AIProviderError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, type InputItem, type LookupResult, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockErrorStep, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockTurn, type MockTurnContext, type MockTurnValidator, type MockWarningStep, type NormalizeOptions, type NormalizedRequest, OllamaAdapter, type OllamaAdapterOptions, type OpaqueItem, type OutputItem, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type SSEEvent, type StopReason, type StreamEventBase, type StreamResult, type SyntheticStreamOptions, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type Usage, type UsageSource, type ValidationIssue, WarningCode, aggregateEvents, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, reasoningItem, replayFromOutput, syntheticStream, textBlock, toolCallItem, toolResultItem, validateRequest };
+export { type AIClient, AIError, AIMappingError, AIProviderError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, type InputItem, type InstructionBlock, type JsonContentBlock, type LookupResult, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockErrorStep, type MockHandler, type MockHandlerContext, type MockHistoryRecord, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockStaticHandler, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockWarningStep, type NormalizeOptions, type NormalizedRequest, OllamaAdapter, type OllamaAdapterOptions, type OpaqueItem, type OutputItem, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type SSEEvent, type StopReason, type StreamEventBase, type StreamResult, type SyntheticStreamOptions, type TextContentBlock, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type Usage, type UsageSource, type ValidationIssue, WarningCode, aggregateEvents, assertMockRequest, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, reasoningItem, replayFromOutput, syntheticStream, textBlock, toolCallItem, toolResultItem, validateRequest, withMockStreaming };
 //# sourceMappingURL=index.d.mts.map