@codehz/ai 0.2.0 → 0.2.1

package/README.md

@@ -159,14 +159,20 @@ const mock = new MockAdapter({
 });
 ```
 
-公开 adapter 接口只暴露稳定的标识与流式来源：
+公开 adapter 接口暴露稳定标识和各维度能力：
 
 ```ts
 adapter.kind; // "responses" | "messages" | "chat-completions" | ...
-adapter.nativeStreaming; // 是否为 provider 原生流，而不是本地模拟分片
+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;
 ```
 
-像 reasoning、tool call、`replay` 材料这类响应特征，应直接从本次事件流、warning 和 `replay` 内容判断。
+`nativeStreaming` 已由 `capabilities` 直接替代。响应级 `backend.isSyntheticStream` 根据
+`textStreaming === "synthetic"` 推导；具体响应内容仍应从本次事件流、warning 和 `replay` 判断。
 
 ## Mock 后端
 

package/dist/index.d.mts

@@ -165,7 +165,14 @@ type ResponseAuxiliaryEvent = StreamEventBase & {
 };
 type ResponseCompletedEvent = StreamEventBase & {
   type: "response.completed";
-  response: AIResponse;
+  replay: ReplayItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  warnings?: string[];
+  opaqueOutput?: OpaqueItem[];
+  trace?: Partial<BackendTrace>;
 };
 type MessageStartedEvent = StreamEventBase & {
   type: "message.started";
@@ -177,14 +184,11 @@ type MessageStartedEvent = StreamEventBase & {
 type MessageDeltaEvent = StreamEventBase & {
   type: "message.delta";
   itemId: string;
-  delta: {
-    type: "text";
-    text: string;
-  };
+  delta: ContentBlock;
 };
 type MessageCompletedEvent = StreamEventBase & {
   type: "message.completed";
-  item: MessageItem;
+  itemId: string;
 };
 type ReasoningStartedEvent = StreamEventBase & {
   type: "reasoning.started";
@@ -200,7 +204,7 @@ type ReasoningDeltaEvent = StreamEventBase & {
 };
 type ReasoningCompletedEvent = StreamEventBase & {
   type: "reasoning.completed";
-  item: ReasoningItem;
+  itemId: string;
 };
 type ToolCallStartedEvent = StreamEventBase & {
   type: "tool_call.started";
@@ -218,7 +222,7 @@ type ToolCallDeltaEvent = StreamEventBase & {
 };
 type ToolCallCompletedEvent = StreamEventBase & {
   type: "tool_call.completed";
-  item: ToolCallItem;
+  itemId: string;
 };
 type AIStreamEvent = ResponseStartedEvent | ResponseWarningEvent | ResponseAuxiliaryEvent | MessageStartedEvent | MessageDeltaEvent | MessageCompletedEvent | ReasoningStartedEvent | ReasoningDeltaEvent | ReasoningCompletedEvent | ToolCallStartedEvent | ToolCallDeltaEvent | ToolCallCompletedEvent | ResponseCompletedEvent;
 //#endregion
@@ -229,9 +233,18 @@ 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 nativeStreaming: boolean;
+  readonly capabilities: AdapterCapabilities;
   stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
 type CreateAIClientOptions = {
@@ -294,7 +307,16 @@ declare class AIError extends Error {
 }
 /** 请求构造失败 — 参数校验不通过。在进入 adapter 前同步抛错。 */
 declare class AIRequestError extends AIError {
-  constructor(message: string, code: ErrorCode);
+  readonly issues?: readonly {
+    field: string;
+    code: string;
+    message: string;
+  }[] | undefined;
+  constructor(message: string, code: ErrorCode, issues?: readonly {
+    field: string;
+    code: string;
+    message: string;
+  }[] | undefined);
 }
 /** Provider 调用失败 — HTTP 非 2xx、网络错误。由 AdapterBase 捕获转为 warning。 */
 declare class AIProviderError extends AIError {
@@ -323,7 +345,8 @@ declare const WarningCode: {
   readonly LOOKUP_TIMEOUT: "LOOKUP_TIMEOUT"; /** 流提前中断 */
   readonly STREAM_INCOMPLETE: "STREAM_INCOMPLETE"; /** 能力降级 */
   readonly CAPABILITY_DOWNGRADE: "CAPABILITY_DOWNGRADE"; /** 模拟流式 */
-  readonly SYNTHETIC_STREAM: "SYNTHETIC_STREAM";
+  readonly SYNTHETIC_STREAM: "SYNTHETIC_STREAM"; /** 工具调用以批量方式到达（非 token 级流式） */
+  readonly TOOL_CALL_BATCHED: "TOOL_CALL_BATCHED";
 };
 //#endregion
 //#region src/core/event-factory.d.ts
@@ -343,18 +366,27 @@ declare function createEventFactory(state: EventFactoryState): {
     billing?: BillingInfo;
     auxiliary?: Partial<AuxiliaryInfo>;
   }): ResponseAuxiliaryEvent;
-  responseCompleted(response: AIResponse): ResponseCompletedEvent;
+  responseCompleted(completion: {
+    replay: ReplayItem[];
+    stopReason?: StopReason;
+    usage?: Usage;
+    billing?: BillingInfo;
+    auxiliary?: AuxiliaryInfo;
+    warnings?: string[];
+    opaqueOutput?: OpaqueItem[];
+    trace?: Partial<BackendTrace>;
+  }): ResponseCompletedEvent;
   messageStarted(id: string): MessageStartedEvent;
-  messageDelta(itemId: string, text: string): MessageDeltaEvent;
-  messageCompleted(item: MessageItem): MessageCompletedEvent;
+  messageDelta(itemId: string, delta: ContentBlock): MessageDeltaEvent;
+  messageCompleted(itemId: string): MessageCompletedEvent;
   reasoningStarted(id: string, visibility: ReasoningItem["visibility"]): ReasoningStartedEvent;
   reasoningDelta(itemId: string, delta: ContentBlock): ReasoningDeltaEvent;
-  reasoningCompleted(item: ReasoningItem): ReasoningCompletedEvent;
+  reasoningCompleted(itemId: string): ReasoningCompletedEvent;
   toolCallStarted(id: string, name: string): ToolCallStartedEvent;
   toolCallDelta(itemId: string, delta: {
     argumentsText?: string;
   }): ToolCallDeltaEvent;
-  toolCallCompleted(item: ToolCallItem): ToolCallCompletedEvent; /** 返回当前已发出的 sequence 计数（用于断言） */
+  toolCallCompleted(itemId: string): ToolCallCompletedEvent; /** 返回当前已发出的 sequence 计数（用于断言） */
   readonly sequence: number; /** 返回当前已记录的 warning 副本。 */
   readonly warnings: string[];
 };
@@ -365,7 +397,7 @@ type EventFactory = ReturnType<typeof createEventFactory>;
  * 将事件数组聚合为 AIResponse。
  * 适用于测试和离线处理场景。
  */
-declare function aggregateEvents(events: AIStreamEvent[]): AIResponse;
+declare function aggregateEvents(events: readonly AIStreamEvent[]): AIResponse;
 //#endregion
 //#region src/core/collect-stream.d.ts
 declare function collectStream(stream: AsyncIterable<AIStreamEvent>): Promise<AIResponse>;
@@ -491,7 +523,7 @@ type StreamResult = {
 };
 declare abstract class AdapterBase implements BackendAdapter {
   abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  abstract readonly nativeStreaming: boolean;
+  abstract readonly capabilities: AdapterCapabilities;
   /**
    * stream 模板方法：
    * 1. 创建事件工厂，发射 response.started
@@ -584,7 +616,7 @@ type ResponsesTool = {
 };
 declare class ResponsesAdapter extends AdapterBase {
   readonly kind: "responses";
-  readonly nativeStreaming = true;
+  readonly capabilities: AdapterCapabilities;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -652,14 +684,12 @@ type MessagesAPITool = {
 };
 declare class MessagesAdapter extends AdapterBase {
   readonly kind: "messages";
-  readonly nativeStreaming = true;
+  readonly capabilities: AdapterCapabilities;
   private apiKey;
   private apiVersion;
   private baseUrl;
   private fetchFn;
-  private warningAccumulator;
   constructor(options: MessagesAdapterOptions);
-  protected warn(message: string, _code?: string): void;
   protected buildRequest(request: NormalizedRequest): MessagesAPIRequest;
   protected runStream(providerRequest: MessagesAPIRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
 }
@@ -684,6 +714,7 @@ type ChatRequest = {
   temperature?: number;
   max_tokens?: number;
   stream: true;
+  n: 1;
 };
 type ChatMessage = {
   role: "system" | "user" | "assistant" | "tool";
@@ -711,7 +742,7 @@ type ChatTool = {
 };
 declare class ChatCompletionsAdapter extends AdapterBase {
   readonly kind: "chat-completions";
-  readonly nativeStreaming = true;
+  readonly capabilities: AdapterCapabilities;
   private apiKey;
   private baseUrl;
   private fetchFn;
@@ -759,7 +790,7 @@ type OllamaTool = {
 };
 declare class OllamaAdapter extends AdapterBase {
   readonly kind: "ollama";
-  readonly nativeStreaming = true;
+  readonly capabilities: AdapterCapabilities;
   private baseUrl;
   private apiKey;
   private fetchFn;
@@ -908,7 +939,14 @@ type MockProviderRequest = {
 declare function assertMockRequest(request: NormalizedRequest, expectation: MockRequestExpectation, context: MockHandlerContext): void;
 declare class MockAdapter extends AdapterBase {
   readonly kind: "mock";
-  readonly nativeStreaming = false;
+  readonly capabilities: {
+    readonly textStreaming: "synthetic";
+    readonly reasoningStreaming: "synthetic";
+    readonly toolCallStreaming: "synthetic";
+    readonly replay: "canonical";
+    readonly usage: "final";
+    readonly toolResultOutcomes: readonly ["success", "error", "rejected"];
+  };
   private readonly handler;
   private readonly providerMetadata?;
   private cursor;
@@ -998,6 +1036,9 @@ type SSEParseResult = {
   rest: string;
   malformedEvents: number;
 };
+type ParseSSEOptions = {
+  allowEOF?: boolean;
+};
 /**
  * 将 SSE 文本块解析为事件数组。
  * 累积事件行直到遇到空行，支持 [DONE] 标记。
@@ -1008,7 +1049,7 @@ type SSEParseResult = {
  * - 未完成的行保留在 rest 中，等待下次 chunk 补全
  * - 支持跨 chunk 的 event 分片
  */
-declare function parseSSEEvents(chunk: string): SSEParseResult;
+declare function parseSSEEvents(chunk: string, options?: ParseSSEOptions): SSEParseResult;
 //#endregion
 //#region src/helpers/synthetic-stream.d.ts
 type SyntheticStreamOptions = {
@@ -1088,5 +1129,88 @@ declare function usageFromOllama(raw: {
   eval_count?: number;
 }): Partial<Usage>;
 //#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 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, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateRequest, withMockStreaming };
+//#region src/helpers/adapter-security.d.ts
+declare const MAX_OPAQUE_PAYLOAD_BYTES = 65536;
+declare const MAX_OPAQUE_JSON_DEPTH = 8;
+declare const PROVIDER_ERROR_MESSAGE_MAX_LEN = 500;
+declare const PROVIDER_ERROR_RAW_BODY_THRESHOLD = 200;
+type OpaqueEnvelopeResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: string;
+};
+/** 测量 JSON 值嵌套深度（对象/数组）；循环引用按已访问节点深度计。 */
+declare function measureJsonDepth(value: unknown, seen?: WeakSet<object>): number;
+/**
+ * Opaque replay 通用 envelope：必须是 object、体积 ≤ 64KB、深度 ≤ 8。
+ * 不校验 adapter 专用字段形状。
+ */
+declare function validateOpaqueReplayEnvelope(payload: unknown): OpaqueEnvelopeResult;
+/** envelope 失败时抛 AIRequestError。 */
+declare function assertOpaqueReplayEnvelope(payload: unknown): void;
+/**
+ * 从 provider HTTP 错误 body 提取可对外暴露的短消息，避免泄漏 HTML / 内部路径等。
+ */
+declare function extractProviderErrorMessage(body: string, status: number): string;
+/** 统一构造脱敏后的 AIProviderError。 */
+declare function providerHttpError(status: number, body: string): AIProviderError;
+//#endregion
+//#region src/helpers/incremental-stream-parser.d.ts
+type StreamSplitResult = {
+  items: string[];
+  rest: string;
+};
+type StreamParseResult<T> = {
+  status: "parsed";
+  value: T;
+} | {
+  status: "ignored";
+} | {
+  status: "malformed";
+};
+declare class IncrementalStreamParser<T> {
+  private readonly split;
+  private readonly parse;
+  private buffer;
+  private readonly decoder;
+  constructor(split: (buffer: string, allowEOF: boolean) => StreamSplitResult, parse: (item: string) => StreamParseResult<T>);
+  feed(value: Uint8Array): {
+    items: T[];
+    malformed: number;
+  };
+  flush(): {
+    items: T[];
+    malformed: number;
+  };
+  getRemaining(): string;
+  private consume;
+}
+declare function splitLines(buffer: string, allowEOF: boolean): StreamSplitResult;
+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);
+  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;
+  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 };
 //# sourceMappingURL=index.d.mts.map