@codehz/ai 0.1.2 → 0.1.3

package/.oxlintrc.json

@@ -11,6 +11,7 @@
     "import/no-duplicates": "error",
     "import/named": "error",
     "import/namespace": "error",
+    "no-await-in-loop": "off",
     "typescript/no-non-null-assertion": "warn",
     "unicorn/no-null": "off",
     "unicorn/no-array-for-each": "off",
@@ -24,22 +25,6 @@
         "typescript/no-non-null-assertion": "off",
         "unicorn/no-array-reverse": "off"
       }
-    },
-    {
-      "files": ["examples/**/*.ts"],
-      "rules": {
-        "no-await-in-loop": "off"
-      }
-    },
-    {
-      "files": [
-        "src/adapters/chat-completions.ts",
-        "src/adapters/messages.ts",
-        "src/adapters/responses.ts"
-      ],
-      "rules": {
-        "no-await-in-loop": "off"
-      }
     }
   ],
   "env": {

package/AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`src/` contains the library source. Keep canonical request/response logic in `src/core/`, provider integrations in `src/adapters/`, reusable stream utilities in `src/helpers/`, and shared types in `src/types/`. The public entrypoint is `src/index.ts`.
+
+`tests/` holds Bun test suites plus shared fixtures such as `tests/fixtures.ts`. `examples/` contains runnable usage samples like `examples/basic.ts` and `examples/tool-loop.ts`. `dist/` is generated output from the packaging build and should not be edited by hand.
+
+## Build, Test, and Development Commands
+
+- `bun install` installs dependencies.
+- `bun run typecheck` runs strict TypeScript validation without emitting files.
+- `bun run lint` checks the codebase with `oxlint`; use `bun run lint:fix` for safe autofixes.
+- `bun run format` applies `oxfmt`; `bun run format:check` verifies formatting in CI style.
+- `bun test` runs the full Bun test suite.
+- `bun run example:basic`, `bun run example:multi-turn`, and `bun run example:tool-loop` execute sample integrations.
+- `bun run prepack` builds the package with `tsdown` into `dist/`.
+
+## Coding Style & Naming Conventions
+
+This repository uses TypeScript ESM with 2-space indentation, semicolons, double quotes, trailing commas, and LF line endings. `oxfmt` enforces formatting, and `oxlint` enforces import correctness and general safety rules.
+
+Follow existing naming patterns: kebab-case filenames such as `chat-completions.ts`, PascalCase for exported classes and types, and camelCase for functions, variables, and helpers. Add public exports through the existing index files instead of reaching into deep paths from consumers.
+
+## Testing Guidelines
+
+Tests use `bun:test` and live in `tests/*.test.ts`. Name suites after the unit or scenario under test, for example `responses-adapter.test.ts` or `scenarios.test.ts`. Favor behavior-focused `describe`/`it` blocks and cover event ordering, replay round-trips, warnings, and adapter-specific edge cases. Use `MockAdapter` and shared fixtures when validating streaming behavior.
+
+## Commit & Pull Request Guidelines
+
+Recent history follows conventional prefixes such as `feat(mock): ...`, `refactor(types): ...`, `docs: ...`, `build: ...`, and `chore: ...`. Keep scopes aligned with the subsystem you changed.
+
+Pull requests should summarize behavior changes, list verification commands run locally, and link the relevant issue when applicable. Include example output or event traces when changing stream semantics or adapter behavior.
+
+## Configuration & Secrets
+
+Use environment variables for provider credentials, such as `OPENAI_API_KEY`. Do not hardcode secrets in source, examples, or tests.

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`）。
 
 ## 安装
 
@@ -109,24 +109,24 @@ console.log(response.replay); // 续接材料
 
 ## 后端 Adapter
 
-| Adapter                 | 类                       | 能力评级 |
-| ----------------------- | ------------------------ | -------- |
-| OpenAI Responses API    | `ResponsesAdapter`       | 🌟🌟🌟   |
-| Anthropic Messages API  | `MessagesAdapter`        | 🌟🌟☆    |
-| OpenAI Chat Completions | `ChatCompletionsAdapter` | 🌟☆☆     |
-| Ollama Chat API         | `OllamaAdapter`          | 🌟☆☆     |
-| 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";
 
-// OpenAI Responses API（能力最强）
+// OpenAI Responses API
 const responses = new ResponsesAdapter({ apiKey: "sk-..." });
 
 // Anthropic Messages API
 const messages = new MessagesAdapter({ apiKey: "sk-ant-..." });
 
-// OpenAI Chat Completions（兼容层）
+// OpenAI Chat Completions
 const chat = new ChatCompletionsAdapter({ apiKey: "sk-..." });
 
 // Ollama
@@ -134,6 +134,10 @@ const ollama = new OllamaAdapter({ baseUrl: "http://localhost:11434" });
 
 // 面向测试的脚本化 mock backend
 const mock = new MockAdapter({
+  stream: {
+    charsPerSecond: 24,
+    chunkSize: 1,
+  },
   turns: [
     {
       steps: [
@@ -150,17 +154,37 @@ const mock = new MockAdapter({
 });
 ```
 
-各 adapter 的能力差异通过 `capabilities` 字段暴露：
+公开 adapter 接口只暴露稳定的标识与流式来源：
 
 ```ts
-adapter.capabilities.reasoningStreaming; // 是否支持思维链流
-adapter.capabilities.toolCallStreaming; // 是否支持工具调用流
-adapter.capabilities.replayFidelity; // "high" | "medium" | "low"
+adapter.kind; // "responses" | "messages" | "chat-completions" | ...
+adapter.nativeStreaming; // 是否为 provider 原生流，而不是本地模拟分片
 ```
 
+像 reasoning、tool call、`replay` 材料这类响应特征，应直接从本次事件流、warning 和 `replay` 内容判断。
+
 ## Mock 后端
 
-`MockAdapter` 现在不是“按关键词回文本”的通用假后端，而是专门用于测试长流程工具调用、`replay` 续接、以及异常路径的脚本化测试夹具。
+`MockAdapter` 是一个面向测试的脚本化 adapter，用来验证长流程工具调用、`replay` 续接和异常路径。
+
+如果你要调试前端逐字渲染效果，可以给 `MockAdapter` 打开分片流：
+
+```ts
+const mock = new MockAdapter({
+  stream: {
+    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` 关闭全局流速配置。
 
 核心思路是按 turn 写脚本：
 
@@ -321,7 +345,7 @@ const { usage, billing, auxiliary, warnings } = collector.build();
 
 ```bash
 bun run typecheck    # TypeScript 类型检查
-bun run test         # 运行全部测试（228+）
+bun run test         # 运行全部测试
 bun run example:basic
 bun run example:multi-turn
 bun run example:tool-loop

package/dist/index.d.mts

@@ -228,83 +228,9 @@ type NormalizedRequest = AIRequest & {
   model: string;
   requestId: string;
 };
-type AdapterCapabilities = {
-  nativeStreaming: boolean;
-  messageStreaming: boolean;
-  reasoningStreaming: boolean;
-  toolCallStreaming: boolean;
-  hiddenReasoningReplay: "full" | "partial" | "none";
-  replayFidelity: "high" | "medium" | "low";
-  tools: boolean;
-  usage: "full" | "partial" | "none";
-  billing: "direct" | "lookup" | "derived" | "none";
-  providerMetadata: boolean;
-};
-declare const CAPABILITY_MATRIX: {
-  readonly responses: {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: true;
-    readonly toolCallStreaming: true;
-    readonly hiddenReasoningReplay: "full";
-    readonly replayFidelity: "high";
-    readonly tools: true;
-    readonly usage: "full";
-    readonly billing: "lookup";
-    readonly providerMetadata: true;
-  };
-  readonly messages: {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: false;
-    readonly toolCallStreaming: true;
-    readonly hiddenReasoningReplay: "partial";
-    readonly replayFidelity: "medium";
-    readonly tools: true;
-    readonly usage: "full";
-    readonly billing: "lookup";
-    readonly providerMetadata: true;
-  };
-  readonly "chat.completions": {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: false;
-    readonly toolCallStreaming: false;
-    readonly hiddenReasoningReplay: "none";
-    readonly replayFidelity: "low";
-    readonly tools: true;
-    readonly usage: "full";
-    readonly billing: "derived";
-    readonly providerMetadata: false;
-  };
-  readonly ollama: {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: false;
-    readonly toolCallStreaming: false;
-    readonly hiddenReasoningReplay: "none";
-    readonly replayFidelity: "low";
-    readonly tools: true;
-    readonly usage: "partial";
-    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" | "mock";
-  readonly capabilities: AdapterCapabilities;
+  readonly nativeStreaming: boolean;
   stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
 type CreateAIClientOptions = {
@@ -511,7 +437,6 @@ type BillingPostprocessHook = (context: {
   usage?: Usage;
   billing?: BillingInfo;
   auxiliary?: AuxiliaryInfo;
-  capabilities: AdapterCapabilities;
 }) => MaybePromise<Partial<BillingInfo> | undefined>;
 type AuxiliaryFinalizeOptions = {
   lookup?: () => Promise<LookupResult>;
@@ -529,10 +454,9 @@ type AuxiliaryFinalizeResult = {
 };
 declare class AdapterAuxiliaryState {
   private readonly request;
-  private readonly capabilities;
   private readonly collector;
   private readonly metadataSources;
-  constructor(request: NormalizedRequest, capabilities: AdapterCapabilities);
+  constructor(request: NormalizedRequest);
   recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): void;
   recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): void;
   recordProviderMetadata(source: string, metadata: Record<string, unknown> | undefined): void;
@@ -566,7 +490,7 @@ type StreamResult = {
 };
 declare abstract class AdapterBase implements BackendAdapter {
   abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  abstract readonly capabilities: AdapterCapabilities;
+  abstract readonly nativeStreaming: boolean;
   /**
    * stream 模板方法：
    * 1. 创建事件工厂，发射 response.started
@@ -659,18 +583,7 @@ type ResponsesTool = {
 };
 declare class ResponsesAdapter extends AdapterBase {
   readonly kind: "responses";
-  readonly capabilities: {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: true;
-    readonly toolCallStreaming: true;
-    readonly hiddenReasoningReplay: "full";
-    readonly replayFidelity: "high";
-    readonly tools: true;
-    readonly usage: "full";
-    readonly billing: "lookup";
-    readonly providerMetadata: true;
-  };
+  readonly nativeStreaming = true;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -738,18 +651,7 @@ type MessagesAPITool = {
 };
 declare class MessagesAdapter extends AdapterBase {
   readonly kind: "messages";
-  readonly capabilities: {
-    readonly nativeStreaming: true;
-    readonly messageStreaming: true;
-    readonly reasoningStreaming: false;
-    readonly toolCallStreaming: true;
-    readonly hiddenReasoningReplay: "partial";
-    readonly replayFidelity: "medium";
-    readonly tools: true;
-    readonly usage: "full";
-    readonly billing: "lookup";
-    readonly providerMetadata: true;
-  };
+  readonly nativeStreaming = true;
   private apiKey;
   private apiVersion;
   private baseUrl;
@@ -808,11 +710,10 @@ type ChatTool = {
 };
 declare class ChatCompletionsAdapter extends AdapterBase {
   readonly kind: "chat-completions";
-  readonly capabilities: AdapterCapabilities;
+  readonly nativeStreaming = true;
   private apiKey;
   private baseUrl;
   private fetchFn;
-  private markReasoningCompatibility;
   constructor(options: ChatCompletionsAdapterOptions);
   protected buildRequest(request: NormalizedRequest): ChatRequest;
   protected runStream(providerRequest: ChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
@@ -857,7 +758,7 @@ type OllamaTool = {
 };
 declare class OllamaAdapter extends AdapterBase {
   readonly kind: "ollama";
-  readonly capabilities: AdapterCapabilities;
+  readonly nativeStreaming = true;
   private baseUrl;
   private apiKey;
   private fetchFn;
@@ -914,10 +815,25 @@ type MockAuxiliaryStep = {
   billing?: BillingInfo;
   auxiliary?: Partial<AuxiliaryInfo>;
 };
+type MockTextStreamOptions = {
+  /**
+   * 每秒吐出的字符数。未设置时仍会按 chunk 拆分，但不会额外等待。
+   */
+  charsPerSecond?: number;
+  /**
+   * 每个 delta 最多包含多少个字符，默认 1。
+   */
+  chunkSize?: number;
+  /**
+   * 首个 delta 发出前的延迟。
+   */
+  initialDelayMs?: number;
+};
 type MockMessageStep = {
   type: "message";
   id?: string;
   content: string | ContentBlock[];
+  stream?: MockTextStreamOptions | false;
 };
 type MockReasoningStep = {
   type: "reasoning";
@@ -926,6 +842,7 @@ type MockReasoningStep = {
     type: "reasoning";
   }>["visibility"];
   content: string | ContentBlock[];
+  stream?: MockTextStreamOptions | false;
 };
 type MockToolCallStep = {
   type: "tool_call";
@@ -934,12 +851,14 @@ type MockToolCallStep = {
   argumentsText: string;
   argumentsJson?: unknown;
   streamArguments?: boolean;
+  stream?: MockTextStreamOptions | false;
 };
 type MockOutputStep = {
   type: "output";
   item: Extract<OutputItem, {
     type: "message" | "reasoning" | "tool_call";
   }>;
+  stream?: MockTextStreamOptions | false;
 };
 type MockCompleteStep = {
   type: "complete";
@@ -976,6 +895,7 @@ type MockAdapterOptions = {
   turns: MockTurn[];
   onExhausted?: "throw" | "repeat-last" | "complete-empty";
   providerMetadata?: Record<string, unknown>;
+  stream?: MockTextStreamOptions;
 };
 type MockTurnRecord = {
   turnIndex: number;
@@ -993,21 +913,11 @@ type MockProviderRequest = {
 };
 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;
-  };
+  readonly nativeStreaming = false;
   private readonly turns;
   private readonly onExhausted;
   private readonly providerMetadata?;
+  private readonly defaultStream?;
   private cursor;
   private previousReplay;
   private pendingToolCalls;
@@ -1141,5 +1051,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, 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 };
+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 };
 //# sourceMappingURL=index.d.mts.map