@codehz/ai 0.2.4 → 0.4.0

package/README.md

@@ -164,19 +164,14 @@ 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;
 ```
 
-响应级 `backend.isSyntheticStream` 根据 `textStreaming === "synthetic"` 推导；具体响应内容仍应从
+响应级 `backend.isSyntheticStream` 使用同一标记；具体响应内容仍应从
 本次事件流、warning 和 `replay` 判断。
 
 ## Mock 后端

package/dist/index.d.mts

@@ -42,7 +42,6 @@ type ToolCallItem = {
   id: string;
   name: string;
   argumentsText: string;
-  argumentsJson?: unknown;
 };
 type ToolResultItem = {
   type: "tool_result";
@@ -234,18 +233,9 @@ 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 = {
@@ -503,7 +493,6 @@ declare function emitMalformedStreamWarning(factory: EventFactory, options: {
   providerLabel: string;
   transportLabel: string;
 }): AIStreamEvent | undefined;
-declare function metadataSourceList(...groups: Array<Array<NonNullable<BackendTrace["metadataSources"]>[number]> | undefined>): string[] | undefined;
 //#endregion
 //#region src/helpers/adapter-base.d.ts
 type ProviderResponse = unknown;
@@ -525,7 +514,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
@@ -550,8 +539,11 @@ declare abstract class AdapterBase implements BackendAdapter {
    * 子类可在返回前自定义覆盖。
    */
   protected buildResponse(request: NormalizedRequest, result: StreamResult, _factory: EventFactory): AIResponse;
-  /** 从 output items 中提取文本内容。 */
-  protected extractText(output: OutputItem[]): string;
+  /**
+   * 统一 finalize auxiliary → response.completed。
+   * adapter 在调用前组装 output / replay / stopReason 等业务字段。
+   */
+  protected emitStreamCompleted(factory: EventFactory, request: NormalizedRequest, auxiliary: AdapterAuxiliaryState, result: StreamResult): AsyncIterable<AIStreamEvent>;
   protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState;
 }
 //#endregion
@@ -618,7 +610,7 @@ type ResponsesTool = {
 };
 declare class ResponsesAdapter extends AdapterBase {
   readonly kind: "responses";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -686,7 +678,7 @@ type MessagesAPITool = {
 };
 declare class MessagesAdapter extends AdapterBase {
   readonly kind: "messages";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private apiVersion;
   private baseUrl;
@@ -744,7 +736,7 @@ type ChatTool = {
 };
 declare class ChatCompletionsAdapter extends AdapterBase {
   readonly kind: "chat-completions";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -792,7 +784,7 @@ type OllamaTool = {
 };
 declare class OllamaAdapter extends AdapterBase {
   readonly kind: "ollama";
-  readonly capabilities: AdapterCapabilities;
+  readonly isSyntheticStream = false;
   private baseUrl;
   private apiKey;
   private fetchFn;
@@ -889,7 +881,6 @@ type MockToolCallStep = {
   id: string;
   name: string;
   argumentsText: string;
-  argumentsJson?: unknown;
   streamArguments?: boolean;
   stream?: MockTextStreamOptions | false;
 };
@@ -942,14 +933,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;
@@ -982,7 +966,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;
 /**
@@ -1000,60 +984,11 @@ declare function blockToText(b: ContentBlock): string;
  * 将 ContentBlock 数组拼接为纯文本，块间以换行符分隔。
  */
 declare function contentBlocksToText(blocks: ContentBlock[]): string;
-/**
- * 将 instructions（string | InstructionBlock[]）归一化为纯文本。
- */
-declare function instructionsToText(instructions: string | InstructionBlock[]): string;
 /**
  * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
  */
 declare function extractText(output: OutputItem[]): string;
 //#endregion
-//#region src/helpers/sse-parser.d.ts
-/**
- * 通用 SSE (Server-Sent Events) 解析器
- *
- * 解析标准 SSE 格式（event: + data: 行），适用于：
- * - Anthropic Messages API (messages.ts)
- * - OpenAI Responses API (responses.ts)
- *
- * 注意：OpenAI Chat Completions API 使用简化 SSE（仅有 data: 行），
- * 由 chat-completions.ts 中的 parseChatSSE 处理。
- *
- * 用法：
- * ```ts
- * const { events, rest } = parseSSEEvents(buffer);
- * for (const ev of events) {
- *   // ev.type — 事件类型字符串
- *   // ev.data — 已解析的 JSON 数据
- * }
- * // rest 是未处理的剩余 buffer，需要累积到下次调用
- * ```
- */
-type SSEEvent = {
-  type: string;
-  data: unknown;
-};
-type SSEParseResult = {
-  events: SSEEvent[];
-  rest: string;
-  malformedEvents: number;
-};
-type ParseSSEOptions = {
-  allowEOF?: boolean;
-};
-/**
- * 将 SSE 文本块解析为事件数组。
- * 累积事件行直到遇到空行，支持 [DONE] 标记。
- * 返回已解析的事件和未处理的剩余 buffer（用于增量解析）。
- *
- * 关键行为：
- * - 只解析完整的 event（以空行结尾）
- * - 未完成的行保留在 rest 中，等待下次 chunk 补全
- * - 支持跨 chunk 的 event 分片
- */
-declare function parseSSEEvents(chunk: string, options?: ParseSSEOptions): SSEParseResult;
-//#endregion
 //#region src/helpers/synthetic-stream.d.ts
 type SyntheticStreamOptions = {
   model: string;
@@ -1191,29 +1126,84 @@ declare class IncrementalStreamParser<T> {
 }
 declare function splitLines(buffer: string, allowEOF: boolean): StreamSplitResult;
 declare function splitSSEFrames(buffer: string, allowEOF: boolean): StreamSplitResult;
+type SseJsonEvent = {
+  type: string;
+  data: unknown;
+};
+/** 解析标准 SSE frame（event: + data:），用于 Messages / Responses。 */
+declare function parseSseJsonFrame(frame: string): StreamParseResult<SseJsonEvent>;
+declare function createSseJsonParser<T extends SseJsonEvent = SseJsonEvent>(): IncrementalStreamParser<T>;
+/** OpenAI Chat Completions 简化 SSE：仅 `data: ...` 行，忽略 `[DONE]`。 */
+declare function parseChatCompletionsDataLine(item: string): StreamParseResult<unknown>;
+declare function createChatCompletionsSseParser<T>(): IncrementalStreamParser<T>;
+/** NDJSON 行解析（Ollama 等）：空行忽略，JSON 失败为 malformed。 */
+declare function createNdjsonLineParser<T>(isValid: (value: unknown) => value is T): IncrementalStreamParser<T>;
 //#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;
+//#region src/helpers/provider-stream.d.ts
+type OpenProviderJsonStreamOptions = {
+  fetchFn: FetchFn;
+  url: string;
+  headers: Record<string, string>;
+  body: unknown;
+  signal?: AbortSignal;
+};
+type OpenedProviderStream = {
+  reader: ReadableStreamDefaultReader<Uint8Array>;
+  headers: Headers;
 };
+/** POST JSON 并返回可读 body reader + response headers；统一网络/HTTP/空 body 错误。 */
+declare function openProviderJsonStream(options: OpenProviderJsonStreamOptions): Promise<OpenedProviderStream>;
+type ProviderStreamBatchOptions<T> = {
+  reader: ReadableStreamDefaultReader<Uint8Array>;
+  parser: IncrementalStreamParser<T>;
+  factory: EventFactory;
+  providerLabel: string;
+  transportLabel: string;
+  incompleteMessage: string;
+};
+type ProviderStreamBatch<T> = {
+  items: T[];
+  warnings: AIStreamEvent[];
+};
+/**
+ * 读取并解析 provider 流。
+ * 每个 batch 携带本轮解析出的 items 与（可选）malformed / incomplete warning。
+ * 调用方应 `for await` 消费完毕；reader 在迭代结束时 cancel/release。
+ */
+declare function iterateProviderStreamBatches<T>(options: ProviderStreamBatchOptions<T>): AsyncGenerator<ProviderStreamBatch<T>, void, undefined>;
+/** 一次性 complete 守卫：首次成功，后续返回 false。 */
+declare function createCompletionGate(): {
+  readonly completed: boolean;
+  tryComplete(): boolean;
+};
+//#endregion
+//#region src/helpers/request-mapper.d.ts
 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;
+  /** ensureTextBlocks + contentBlocksToText 的常见组合。 */
+  textFromBlocks(blocks: ContentBlock[], field: string): string;
+  parseToolArguments(item: ToolCallItem): Record<string, unknown>;
   rollbackTrailingAssistantMessages<T extends {
     role: string;
   }>(messages: T[]): void;
+  mapToolsIfPresent<T>(tools: ToolDefinition[] | undefined, map: (tool: ToolDefinition) => T): T[] | undefined;
+  /**
+   * 将 canonical toolChoice 映射为 provider 形状。
+   * 返回 undefined 表示调用方无需写入 body 字段。
+   */
+  mapToolChoice<T>(toolChoice: ToolChoice | undefined, mappers: {
+    auto: T;
+    none: T;
+    tool: (name: string) => T;
+  }): T | undefined;
   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 OpenProviderJsonStreamOptions, type OpenedProviderStream, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, type ProviderStreamBatch, type ProviderStreamBatchOptions, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type SseJsonEvent, 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, createChatCompletionsSseParser, createCompletionGate, createEventFactory, createNdjsonLineParser, createSseJsonParser, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, iterateProviderStreamBatches, jsonBlock, mapReasoningVisibility, mapStopReason, measureJsonDepth, messageItem, normalizeRequest, opaqueBlock, opaqueItem, openProviderJsonStream, parseChatCompletionsDataLine, parseSseJsonFrame, providerHttpError, reasoningItem, replayFromOutput, splitLines, splitSSEFrames, syntheticStream, textBlock, toolCallItem, toolResultItem, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateOpaqueReplayEnvelope, validateRequest, withMockStreaming };
 //# sourceMappingURL=index.d.mts.map