@codehz/ai 0.1.0 → 0.1.2

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` 并在下一轮带回：
@@ -212,6 +317,8 @@ const { usage, billing, auxiliary, warnings } = collector.build();
 
 ## 开发命令
 
+`examples/` 下的三个示例默认都基于 `MockAdapter`，可直接运行，无需配置真实模型或 API key。
+
 ```bash
 bun run typecheck    # TypeScript 类型检查
 bun run test         # 运行全部测试（228+）

package/dist/index.d.mts

@@ -117,7 +117,7 @@ type AuxiliaryInfo = {
 type BackendTrace = {
   requestId?: string;
   rawResponseId?: string;
-  adapter: "chat-completions" | "messages" | "responses" | "ollama";
+  adapter: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
   isSyntheticStream: boolean;
   metadataSources?: string[];
   warnings?: string[];
@@ -143,7 +143,7 @@ type StreamEventBase = {
   sequence: number;
   timestamp: string;
   backend: {
-    kind: "chat-completions" | "messages" | "responses" | "ollama";
+    kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
     isSynthetic: boolean;
   };
 };
@@ -289,9 +289,21 @@ declare const CAPABILITY_MATRIX: {
     readonly billing: "none";
     readonly providerMetadata: false;
   };
+  readonly mock: {
+    readonly nativeStreaming: false;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "none";
+    readonly replayFidelity: "high";
+    readonly tools: true;
+    readonly usage: "none";
+    readonly billing: "none";
+    readonly providerMetadata: true;
+  };
 };
 interface BackendAdapter {
-  readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
   readonly capabilities: AdapterCapabilities;
   stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
@@ -389,7 +401,7 @@ declare const WarningCode: {
 //#endregion
 //#region src/core/event-factory.d.ts
 type EventFactoryBackend = {
-  kind: "chat-completions" | "messages" | "responses" | "ollama";
+  kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
   isSynthetic: boolean;
 };
 type EventFactoryState = {
@@ -553,7 +565,7 @@ type StreamResult = {
   rawResponseId?: string;
 };
 declare abstract class AdapterBase implements BackendAdapter {
-  abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
   abstract readonly capabilities: AdapterCapabilities;
   /**
    * stream 模板方法：
@@ -854,6 +866,161 @@ declare class OllamaAdapter extends AdapterBase {
   protected runStream(providerRequest: OllamaChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
 //#endregion
+//#region src/adapters/mock.d.ts
+type MockInputExpectation = {
+  type: InputItem["type"];
+  id?: string;
+  role?: MessageItem["role"];
+  name?: string;
+  toolName?: string;
+  callId?: string;
+  outcome?: ToolResultItem["outcome"];
+  visibility?: Extract<InputItem, {
+    type: "reasoning";
+  }>["visibility"];
+  source?: Extract<InputItem, {
+    type: "opaque";
+  }>["source"];
+  purpose?: Extract<InputItem, {
+    type: "opaque";
+  }>["purpose"];
+  textIncludes?: string;
+};
+type MockRequestExpectation = {
+  minItems?: number;
+  maxItems?: number;
+  ordered?: boolean;
+  requireReplayFromPreviousTurn?: boolean;
+  requireToolResultsForPendingCalls?: boolean;
+  tools?: "ignore" | "present" | "absent";
+  toolChoice?: "ignore" | "present" | "absent";
+  items?: MockInputExpectation[];
+};
+type MockTurnContext = {
+  turnIndex: number;
+  previousReplay: ReplayItem[];
+  pendingToolCalls: readonly ToolCallItem[];
+  history: readonly MockTurnRecord[];
+};
+type MockTurnValidator = (request: NormalizedRequest, context: MockTurnContext) => void | Promise<void>;
+type MockWarningStep = {
+  type: "warning";
+  message: string;
+  code?: string;
+};
+type MockAuxiliaryStep = {
+  type: "auxiliary";
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: Partial<AuxiliaryInfo>;
+};
+type MockMessageStep = {
+  type: "message";
+  id?: string;
+  content: string | ContentBlock[];
+};
+type MockReasoningStep = {
+  type: "reasoning";
+  id?: string;
+  visibility?: Extract<OutputItem, {
+    type: "reasoning";
+  }>["visibility"];
+  content: string | ContentBlock[];
+};
+type MockToolCallStep = {
+  type: "tool_call";
+  id: string;
+  name: string;
+  argumentsText: string;
+  argumentsJson?: unknown;
+  streamArguments?: boolean;
+};
+type MockOutputStep = {
+  type: "output";
+  item: Extract<OutputItem, {
+    type: "message" | "reasoning" | "tool_call";
+  }>;
+};
+type MockCompleteStep = {
+  type: "complete";
+  stopReason?: StopReason;
+  replay?: ReplayItem[];
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: Partial<AuxiliaryInfo>;
+  providerMetadata?: Record<string, unknown>;
+  rawResponseId?: string;
+  warnings?: string[];
+};
+type MockErrorStep = {
+  type: "error";
+  message: string;
+  code?: string;
+  stopReason?: StopReason;
+  providerMetadata?: Record<string, unknown>;
+};
+type MockInterruptStep = {
+  type: "interrupt";
+};
+type MockThrowStep = {
+  type: "throw";
+  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 MockAdapterOptions = {
+  turns: MockTurn[];
+  onExhausted?: "throw" | "repeat-last" | "complete-empty";
+  providerMetadata?: Record<string, unknown>;
+};
+type MockTurnRecord = {
+  turnIndex: number;
+  turnName?: string;
+  requestId: string;
+  replay: ReplayItem[];
+  toolCalls: ToolCallItem[];
+};
+type MockProviderRequest = {
+  request: NormalizedRequest;
+  turn: MockTurn;
+  turnIndex: number;
+  turnName?: string;
+  remainingPendingToolCalls: ToolCallItem[];
+};
+declare class MockAdapter extends AdapterBase {
+  readonly kind: "mock";
+  readonly capabilities: {
+    readonly nativeStreaming: false;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "none";
+    readonly replayFidelity: "high";
+    readonly tools: true;
+    readonly usage: "none";
+    readonly billing: "none";
+    readonly providerMetadata: true;
+  };
+  private readonly turns;
+  private readonly onExhausted;
+  private readonly providerMetadata?;
+  private cursor;
+  private previousReplay;
+  private pendingToolCalls;
+  private history;
+  private activeStream;
+  constructor(options: MockAdapterOptions);
+  protected buildRequest(request: NormalizedRequest): Promise<MockProviderRequest>;
+  protected runStream(providerRequest: unknown, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+  private finalizeTurn;
+  private resolveTurn;
+  private buildTurnContext;
+}
+//#endregion
 //#region src/helpers/mapping.d.ts
 declare function mapStopReason(providerReason: string): StopReason;
 declare function mapReasoningVisibility(hasThinking: boolean, hasRedacted: boolean): ReasoningItem["visibility"];
@@ -945,7 +1112,7 @@ type SyntheticStreamOptions = {
   model: string;
   responseId: string;
   backend: {
-    kind: "chat-completions" | "messages" | "responses";
+    kind: "chat-completions" | "messages" | "responses" | "mock";
   };
   output: OutputItem[];
   replay?: ReplayItem[];
@@ -974,5 +1141,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, type AdapterCapabilities, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, CAPABILITY_MATRIX, 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, 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, type AdapterCapabilities, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, CAPABILITY_MATRIX, 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 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 };
 //# sourceMappingURL=index.d.mts.map