@codehz/ai 0.2.3 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
-# nano-ai
+# @codehz/ai
 
-统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的回调驱动 `MockAdapter`（`responses` / `messages` / `chat.completions` / `ollama` / `mock`）。
+统一流式 AI 客户端，提供一套 canonical API，对接真实模型后端与面向测试的回调驱动 `MockAdapter`（`responses` / `messages` / `chat-completions` / `ollama` / `mock`）。
 
 ## 安装
 
 ```bash
-bun add nano-ai
+bun add @codehz/ai
 ```
 
 依赖：Bun（内置 `fetch`、`crypto`），无需额外运行时依赖。
@@ -13,7 +13,7 @@ bun add nano-ai
 ## 快速开始
 
 ```ts
-import { createAIClient, ResponsesAdapter } from "nano-ai";
+import { createAIClient, ResponsesAdapter } from "@codehz/ai";
 
 const client = createAIClient({
   adapter: new ResponsesAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
@@ -69,22 +69,22 @@ 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`                  | 响应结束，内含完整 `AIResponse` |
+| 事件                                  | 含义                                        |
+| ------------------------------------- | ------------------------------------------- |
+| `response.started`                    | 响应开始                                    |
+| `message.{started,delta,completed}`   | 消息输出                                    |
+| `reasoning.{started,delta,completed}` | 思维链                                      |
+| `tool_call.{started,delta,completed}` | 工具调用                                    |
+| `response.warning`                    | 非致命警告                                  |
+| `response.auxiliary`                  | usage / billing 辅助信息                    |
+| `response.completed`                  | 响应结束，携带 replay、终止原因及最终元数据 |
 
 ### 统一终结结果
 
 流结束后可通过 `collectStream()` 聚合为 `AIResponse`：
 
 ```ts
-import { collectStream } from "nano-ai";
+import { collectStream } from "@codehz/ai";
 
 const response = await collectStream(client.stream({ input }));
 console.log(response.text); // 全部文本
@@ -95,17 +95,18 @@ console.log(response.replay); // 续接材料
 
 `AIResponse` 包含：
 
-| 字段         | 类型             | 说明                     |
-| ------------ | ---------------- | ------------------------ |
-| `output`     | `OutputItem[]`   | 当前轮输出               |
-| `replay`     | `ReplayItem[]`   | 续接材料（下次请求带回） |
-| `text`       | `string`         | 全部文本拼接             |
-| `toolCalls`  | `ToolCallItem[]` | 工具调用                 |
-| `stopReason` | `StopReason`     | 终止原因                 |
-| `usage`      | `Usage`          | token 统计               |
-| `billing`    | `BillingInfo`    | 计费信息                 |
-| `warnings`   | `string[]`       | 非致命警告               |
-| `backend`    | `BackendTrace`   | 调用链路元数据           |
+| 字段         | 类型             | 说明                      |
+| ------------ | ---------------- | ------------------------- |
+| `output`     | `OutputItem[]`   | 当前轮输出                |
+| `replay`     | `ReplayItem[]`   | 续接材料（下次请求带回）  |
+| `text`       | `string`         | 全部文本拼接              |
+| `toolCalls`  | `ToolCallItem[]` | 工具调用                  |
+| `stopReason` | `StopReason?`    | 终止原因（可选）          |
+| `usage`      | `Usage?`         | token 统计（可选）        |
+| `billing`    | `BillingInfo?`   | 计费信息（可选）          |
+| `auxiliary`  | `AuxiliaryInfo?` | Provider 辅助信息（可选） |
+| `warnings`   | `string[]?`      | 非致命警告（可选）        |
+| `backend`    | `BackendTrace`   | 调用链路元数据            |
 
 流式 `message.delta` / `reasoning.delta` 保持后端分片粒度；完成态 `output` 中的
 `message` / `reasoning` 会合并相邻 `text` content blocks（直接拼接且不添加分隔符），
@@ -129,7 +130,7 @@ import {
   OllamaAdapter,
   MockAdapter,
   withMockStreaming,
-} from "nano-ai";
+} from "@codehz/ai";
 
 // OpenAI Responses API
 const responses = new ResponsesAdapter({ apiKey: "sk-..." });
@@ -163,20 +164,15 @@ const mock = new MockAdapter({
 });
 ```
 
-公开 adapter 接口暴露稳定标识和各维度能力：
+公开 adapter 接口暴露稳定标识和流来源：
 
 ```ts
 adapter.kind; // "responses" | "messages" | "chat-completions" | ...
-adapter.capabilities.textStreaming; // "native" | "synthetic" | "none"
-adapter.capabilities.reasoningStreaming;
-adapter.capabilities.toolCallStreaming;
-adapter.capabilities.replay; // "canonical" | "opaque" | "none"
-adapter.capabilities.usage; // "stream" | "final" | "none"
-adapter.capabilities.toolResultOutcomes;
+adapter.isSyntheticStream;
 ```
 
-`nativeStreaming` 已由 `capabilities` 直接替代。响应级 `backend.isSyntheticStream` 根据
-`textStreaming === "synthetic"` 推导；具体响应内容仍应从本次事件流、warning 和 `replay` 判断。
+响应级 `backend.isSyntheticStream` 使用同一标记；具体响应内容仍应从
+本次事件流、warning 和 `replay` 判断。
 
 ## Mock 后端
 
@@ -208,7 +204,7 @@ const handler = withMockStreaming(
 - 可用 `assertMockRequest()` 验证调用方是否把上一轮 `replay` 和当前 `tool_result` 正确带回
 
 ```ts
-import { assertMockRequest, createAIClient, MockAdapter } from "nano-ai";
+import { assertMockRequest, createAIClient, MockAdapter } from "@codehz/ai";
 
 const client = createAIClient({
   adapter: new MockAdapter({
@@ -325,7 +321,7 @@ const r2 = await collectStream(client.stream({ input, tools }));
 非流式后端可通过 `syntheticStream()` 包装为规范事件流：
 
 ```ts
-import { syntheticStream } from "nano-ai";
+import { syntheticStream } from "@codehz/ai";
 
 const events = syntheticStream({
   model: "gpt-4o",
@@ -345,7 +341,7 @@ for await (const event of events) {
 `AuxiliaryCollector` 提供分层 best-effort 采集（流事件 → headers → lookup → derived）：
 
 ```ts
-import { AuxiliaryCollector } from "nano-ai";
+import { AuxiliaryCollector } from "@codehz/ai";
 
 const collector = new AuxiliaryCollector();
 collector.recordUsage({ inputTokens: 10, outputTokens: 5 }, "stream");

package/dist/index.d.mts

@@ -42,7 +42,6 @@ type ToolCallItem = {
   id: string;
   name: string;
   argumentsText: string;
-  argumentsJson?: unknown;
 };
 type ToolResultItem = {
   type: "tool_result";
@@ -88,7 +87,8 @@ type AIRequest = {
   include?: IncludeSettings;
   metadata?: Record<string, string>;
   temperature?: number;
-  maxOutputTokens?: number;
+  maxOutputTokens?: number; /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
+  signal?: AbortSignal;
 };
 //#endregion
 //#region src/types/response.d.ts
@@ -233,24 +233,16 @@ type NormalizedRequest = AIRequest & {
   model: string;
   requestId: string;
 };
-type StreamingCapability = "native" | "synthetic" | "none";
-type AdapterCapabilities = {
-  readonly textStreaming: StreamingCapability;
-  readonly reasoningStreaming: StreamingCapability;
-  readonly toolCallStreaming: StreamingCapability;
-  readonly replay: "canonical" | "opaque" | "none";
-  readonly usage: "stream" | "final" | "none";
-  readonly toolResultOutcomes: ReadonlyArray<"success" | "error" | "rejected">;
-};
 interface BackendAdapter {
   readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream: boolean;
   stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
 type CreateAIClientOptions = {
   adapter: BackendAdapter;
   model: string;
-  defaults?: Partial<AIRequest>;
+  defaults?: Partial<AIRequest>; /** 全局默认 AbortSignal，当 request.signal 未设置时生效。 */
+  signal?: AbortSignal;
 };
 interface AIClient {
   stream(request: AIRequest): AsyncIterable<AIStreamEvent>;
@@ -523,7 +515,7 @@ type StreamResult = {
 };
 declare abstract class AdapterBase implements BackendAdapter {
   abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  abstract readonly capabilities: AdapterCapabilities;
+  abstract readonly isSyntheticStream: boolean;
   /**
    * stream 模板方法：
    * 1. 创建事件工厂，发射 response.started
@@ -616,7 +608,7 @@ type ResponsesTool = {
 };
 declare class ResponsesAdapter extends AdapterBase {
   readonly kind: "responses";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -684,7 +676,7 @@ type MessagesAPITool = {
 };
 declare class MessagesAdapter extends AdapterBase {
   readonly kind: "messages";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private apiVersion;
   private baseUrl;
@@ -742,7 +734,7 @@ type ChatTool = {
 };
 declare class ChatCompletionsAdapter extends AdapterBase {
   readonly kind: "chat-completions";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -790,7 +782,7 @@ type OllamaTool = {
 };
 declare class OllamaAdapter extends AdapterBase {
   readonly kind: "ollama";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private baseUrl;
   private apiKey;
   private fetchFn;
@@ -839,7 +831,8 @@ type MockHandlerContext = {
   turnIndex: number;
   previousReplay: ReplayItem[];
   pendingToolCalls: readonly ToolCallItem[];
-  history: readonly MockHistoryRecord[];
+  history: readonly MockHistoryRecord[]; /** 请求的 AbortSignal，handler 可检查 signal.aborted 提前退出。 */
+  signal?: AbortSignal;
 };
 type MockWarningStep = {
   type: "warning";
@@ -886,7 +879,6 @@ type MockToolCallStep = {
   id: string;
   name: string;
   argumentsText: string;
-  argumentsJson?: unknown;
   streamArguments?: boolean;
   stream?: MockTextStreamOptions | false;
 };
@@ -939,14 +931,7 @@ type MockProviderRequest = {
 declare function assertMockRequest(request: NormalizedRequest, expectation: MockRequestExpectation, context: MockHandlerContext): void;
 declare class MockAdapter extends AdapterBase {
   readonly kind: "mock";
-  readonly capabilities: {
-    readonly textStreaming: "synthetic";
-    readonly reasoningStreaming: "synthetic";
-    readonly toolCallStreaming: "synthetic";
-    readonly replay: "canonical";
-    readonly usage: "final";
-    readonly toolResultOutcomes: readonly ["success", "error", "rejected"];
-  };
+  readonly isSyntheticStream = true;
   private readonly handler;
   private readonly providerMetadata?;
   private cursor;
@@ -979,7 +964,7 @@ declare function opaqueBlock(payload: unknown): ContentBlock & {
 };
 declare function messageItem(content: ContentBlock[], overrides?: Partial<Omit<MessageItem, "type" | "content">>): MessageItem;
 declare function reasoningItem(content: ContentBlock[], visibility?: ReasoningItem["visibility"], id?: string): ReasoningItem;
-declare function toolCallItem(id: string, name: string, argumentsText: string, argumentsJson?: unknown): ToolCallItem;
+declare function toolCallItem(id: string, name: string, argumentsText: string): ToolCallItem;
 declare function toolResultItem(callId: string, toolName: string, outcome: ToolResultItem["outcome"], content: ContentBlock[]): ToolResultItem;
 declare function opaqueItem(source: OpaqueItem["source"], purpose: OpaqueItem["purpose"], payload: unknown, id?: string): OpaqueItem;
 /**
@@ -1190,27 +1175,20 @@ declare function splitLines(buffer: string, allowEOF: boolean): StreamSplitResul
 declare function splitSSEFrames(buffer: string, allowEOF: boolean): StreamSplitResult;
 //#endregion
 //#region src/helpers/request-mapper.d.ts
-type ProviderProfile = {
-  readonly kind: string;
-  readonly instructionsMode: "system_message" | "instructions_field" | "none";
-  readonly supportedBlockTypes: ReadonlyArray<ContentBlock["type"]>;
-  readonly reasoningBlockTypes: ReadonlyArray<ContentBlock["type"]>;
-  readonly capabilities: AdapterCapabilities;
-};
 declare class NormalizedRequestMapper {
-  readonly profile: ProviderProfile;
-  constructor(profile: ProviderProfile);
+  readonly kind: string;
+  constructor(kind: string);
   mapInstructions(instructions: string | InstructionBlock[]): string;
   ensureTextBlocks(blocks: ContentBlock[], field: string): ContentBlock[];
   ensureReasoningBlocks(blocks: ContentBlock[], field: string): Array<Extract<ContentBlock, {
     type: "text";
   }>>;
-  assertToolResultOutcome(outcome: ToolResultItem["outcome"]): void;
+  parseToolArguments(item: ToolCallItem): Record<string, unknown>;
   rollbackTrailingAssistantMessages<T extends {
     role: string;
   }>(messages: T[]): void;
   private ensureBlocks;
 }
 //#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, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, IncrementalStreamParser, type InputItem, type InstructionBlock, type JsonContentBlock, type LookupResult, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, 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, NormalizedRequestMapper, OllamaAdapter, type OllamaAdapterOptions, type OpaqueEnvelopeResult, type OpaqueItem, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, type ProviderProfile, 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 StreamParseResult, type StreamResult, type StreamSplitResult, type StreamingCapability, 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, assertOpaqueReplayEnvelope, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, measureJsonDepth, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, providerHttpError, reasoningItem, replayFromOutput, splitLines, splitSSEFrames, syntheticStream, textBlock, toolCallItem, toolResultItem, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateOpaqueReplayEnvelope, validateRequest, withMockStreaming };
+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, IncrementalStreamParser, type InputItem, type InstructionBlock, type JsonContentBlock, type LookupResult, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, 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, NormalizedRequestMapper, OllamaAdapter, type OllamaAdapterOptions, type OpaqueEnvelopeResult, type OpaqueItem, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, 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 StreamParseResult, type StreamResult, type StreamSplitResult, 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, assertOpaqueReplayEnvelope, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, measureJsonDepth, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, providerHttpError, reasoningItem, replayFromOutput, splitLines, splitSSEFrames, syntheticStream, textBlock, toolCallItem, toolResultItem, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateOpaqueReplayEnvelope, validateRequest, withMockStreaming };
 //# sourceMappingURL=index.d.mts.map