@codehz/ai 0.1.1 → 0.1.2

package/README.md

@@ -317,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