@codehz/ai 0.1.0

package/src/core/aggregator.ts

@@ -0,0 +1,349 @@
+/**
+ * 流聚合器
+ *
+ * 将 AIStreamEvent 序列聚合为统一的 AIResponse。
+ * 职责：
+ * - 合并 message.delta / reasoning.delta / tool_call.delta
+ * - 合并多次 response.auxiliary 补丁
+ * - 生成 output / text / toolCalls
+ * - 保持 output 顺序稳定
+ *
+ * 约束：
+ * - replay 由 adapter 显式提供，聚合器不猜测
+ * - 不伪造 reasoning
+ * - 不解释 opaque payload
+ */
+
+import type {
+  AIStreamEvent,
+  AIResponse,
+  ContentBlock,
+  MessageItem,
+  ReasoningItem,
+  ToolCallItem,
+  OutputItem,
+  Usage,
+  BillingInfo,
+  AuxiliaryInfo,
+  BackendTrace,
+  StopReason,
+} from "../types/index.js";
+
+// ── 内部 pending item 状态 ────────────────────────────────────
+
+interface PendingMessage {
+  role: "assistant";
+  texts: string[];
+}
+
+interface PendingReasoning {
+  visibility: ReasoningItem["visibility"];
+  blocks: ContentBlock[];
+}
+
+interface PendingToolCall {
+  name: string;
+  argsParts: string[];
+}
+
+// ── 聚合器状态 ────────────────────────────────────────────────
+
+interface AggregatorState {
+  responseId?: string;
+  model?: string;
+  backendInfo?: { kind: BackendTrace["adapter"]; isSynthetic: boolean };
+
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary: AuxiliaryInfo;
+  warnings: string[];
+
+  pendingMessages: Map<string, PendingMessage>;
+  pendingReasonings: Map<string, PendingReasoning>;
+  pendingToolCalls: Map<string, PendingToolCall>;
+
+  /** 已完成 item 的 id 列表，保持输出顺序 */
+  outputOrder: string[];
+  completedMessages: Map<string, MessageItem>;
+  completedReasonings: Map<string, ReasoningItem>;
+  completedToolCalls: Map<string, ToolCallItem>;
+
+  /** adapter 在 response.completed 中提供的 replay */
+  replayFromAdapter?: import("../types/index.js").ReplayItem[];
+  responseIdFromAdapter?: string;
+  stopReasonFromAdapter?: StopReason;
+  backendFromAdapter?: BackendTrace;
+}
+
+function createInitialState(): AggregatorState {
+  return {
+    pendingMessages: new Map(),
+    pendingReasonings: new Map(),
+    pendingToolCalls: new Map(),
+    outputOrder: [],
+    completedMessages: new Map(),
+    completedReasonings: new Map(),
+    completedToolCalls: new Map(),
+    auxiliary: {},
+    warnings: [],
+  };
+}
+
+// ── Event handlers ────────────────────────────────────────────
+
+function handleResponseStarted(state: AggregatorState, event: AIStreamEvent & { type: "response.started" }): void {
+  state.responseId = event.responseId;
+  state.model = event.model;
+  state.backendInfo = event.backend;
+}
+
+function handleResponseWarning(state: AggregatorState, event: AIStreamEvent & { type: "response.warning" }): void {
+  pushWarnings(state, [event.message]);
+}
+
+function handleResponseAuxiliary(state: AggregatorState, event: AIStreamEvent & { type: "response.auxiliary" }): void {
+  if (event.usage) {
+    state.usage = { ...state.usage, ...event.usage };
+  }
+  if (event.billing) {
+    state.billing = { ...state.billing, ...event.billing };
+  }
+  if (event.auxiliary) {
+    state.auxiliary = mergeAuxiliary(state.auxiliary, event.auxiliary);
+  }
+}
+
+function handleMessageStarted(state: AggregatorState, event: AIStreamEvent & { type: "message.started" }): void {
+  state.pendingMessages.set(event.item.id, {
+    role: event.item.role,
+    texts: [],
+  });
+}
+
+function handleMessageDelta(state: AggregatorState, event: AIStreamEvent & { type: "message.delta" }): void {
+  const pending = state.pendingMessages.get(event.itemId);
+  if (pending) {
+    pending.texts.push(event.delta.text);
+  }
+}
+
+function handleMessageCompleted(state: AggregatorState, event: AIStreamEvent & { type: "message.completed" }): void {
+  const item = event.item;
+  const itemId = item.id ?? `msg-${state.outputOrder.length}`;
+  state.completedMessages.set(itemId, item);
+  state.outputOrder.push(itemId);
+  state.pendingMessages.delete(itemId);
+}
+
+function handleReasoningStarted(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.started" }): void {
+  state.pendingReasonings.set(event.item.id, {
+    visibility: event.item.visibility,
+    blocks: [],
+  });
+}
+
+function handleReasoningDelta(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.delta" }): void {
+  const pending = state.pendingReasonings.get(event.itemId);
+  if (pending) {
+    pending.blocks.push(event.delta);
+  }
+}
+
+function handleReasoningCompleted(
+  state: AggregatorState,
+  event: AIStreamEvent & { type: "reasoning.completed" },
+): void {
+  const item = event.item;
+  const stableId = item.id ?? `reason-${state.outputOrder.length}-${Date.now()}`;
+  state.completedReasonings.set(stableId, item);
+  state.outputOrder.push(stableId);
+  state.pendingReasonings.delete(item.id ?? "");
+}
+
+function handleToolCallStarted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.started" }): void {
+  state.pendingToolCalls.set(event.item.id, {
+    name: event.item.name,
+    argsParts: [],
+  });
+}
+
+function handleToolCallDelta(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.delta" }): void {
+  const pending = state.pendingToolCalls.get(event.itemId);
+  if (pending && event.delta.argumentsText) {
+    pending.argsParts.push(event.delta.argumentsText);
+  }
+}
+
+function handleToolCallCompleted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.completed" }): void {
+  const item = event.item;
+  state.completedToolCalls.set(item.id, item);
+  state.outputOrder.push(item.id);
+  state.pendingToolCalls.delete(item.id);
+}
+
+function handleResponseCompleted(state: AggregatorState, event: AIStreamEvent & { type: "response.completed" }): void {
+  state.replayFromAdapter = event.response.replay;
+  state.responseIdFromAdapter = event.response.id;
+  state.stopReasonFromAdapter = event.response.stopReason;
+  state.backendFromAdapter = event.response.backend;
+
+  // 从 response.completed 中提取 usage/billing（适配器可能未发 auxiliary 事件）
+  if (event.response.usage) {
+    state.usage = { ...state.usage, ...event.response.usage };
+  }
+  if (event.response.billing) {
+    state.billing = { ...state.billing, ...event.response.billing };
+  }
+  if (event.response.auxiliary) {
+    state.auxiliary = mergeAuxiliary(state.auxiliary, event.response.auxiliary);
+  }
+  if (event.response.warnings) {
+    pushWarnings(state, event.response.warnings);
+  }
+}
+
+// ── 从聚合状态构建最终 AIResponse ─────────────────────────────
+
+function buildResponse(state: AggregatorState): AIResponse {
+  // 按 outputOrder 组装 output
+  const output: OutputItem[] = [];
+  for (const id of state.outputOrder) {
+    const msg = state.completedMessages.get(id);
+    if (msg) {
+      output.push(msg);
+      continue;
+    }
+    const reason = state.completedReasonings.get(id);
+    if (reason) {
+      output.push(reason);
+      continue;
+    }
+    const tc = state.completedToolCalls.get(id);
+    if (tc) {
+      output.push(tc);
+      continue;
+    }
+  }
+
+  // 汇总 text
+  const text = output
+    .filter((item): item is MessageItem => item.type === "message")
+    .flatMap((m) => m.content)
+    .filter((b): b is ContentBlock & { type: "text" } => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+
+  // toolCalls
+  const toolCalls = output.filter((item): item is ToolCallItem => item.type === "tool_call");
+
+  // 合并 backend trace
+  const backendFromResponse = state.backendFromAdapter;
+  const backend: BackendTrace = {
+    adapter: backendFromResponse?.adapter ?? state.backendInfo?.kind ?? ("unknown" as BackendTrace["adapter"]),
+    isSyntheticStream: backendFromResponse?.isSyntheticStream ?? state.backendInfo?.isSynthetic ?? false,
+    requestId: backendFromResponse?.requestId ?? state.responseId,
+    rawResponseId: backendFromResponse?.rawResponseId,
+    metadataSources: backendFromResponse?.metadataSources,
+    warnings: backendFromResponse?.warnings,
+  };
+
+  return {
+    id: state.responseIdFromAdapter ?? state.responseId,
+    output,
+    replay: state.replayFromAdapter ?? [],
+    text,
+    toolCalls,
+    stopReason: state.stopReasonFromAdapter,
+    usage: state.usage,
+    billing: state.billing,
+    auxiliary: state.auxiliary,
+    warnings: state.warnings.length > 0 ? state.warnings : undefined,
+    backend,
+  };
+}
+
+// ── 公开 API ──────────────────────────────────────────────────
+
+/**
+ * 将事件数组聚合为 AIResponse。
+ * 适用于测试和离线处理场景。
+ */
+export function aggregateEvents(events: AIStreamEvent[]): AIResponse {
+  const state = createInitialState();
+
+  for (const event of events) {
+    switch (event.type) {
+      case "response.started":
+        handleResponseStarted(state, event);
+        break;
+      case "response.warning":
+        handleResponseWarning(state, event);
+        break;
+      case "response.auxiliary":
+        handleResponseAuxiliary(state, event);
+        break;
+      case "message.started":
+        handleMessageStarted(state, event);
+        break;
+      case "message.delta":
+        handleMessageDelta(state, event);
+        break;
+      case "message.completed":
+        handleMessageCompleted(state, event);
+        break;
+      case "reasoning.started":
+        handleReasoningStarted(state, event);
+        break;
+      case "reasoning.delta":
+        handleReasoningDelta(state, event);
+        break;
+      case "reasoning.completed":
+        handleReasoningCompleted(state, event);
+        break;
+      case "tool_call.started":
+        handleToolCallStarted(state, event);
+        break;
+      case "tool_call.delta":
+        handleToolCallDelta(state, event);
+        break;
+      case "tool_call.completed":
+        handleToolCallCompleted(state, event);
+        break;
+      case "response.completed":
+        handleResponseCompleted(state, event);
+        break;
+    }
+  }
+
+  // 用 response.completed 中的 response 做最终构建
+  const lastEvent = events[events.length - 1];
+  if (!lastEvent || lastEvent.type !== "response.completed") {
+    throw new Error("Stream must end with response.completed event to produce a valid AIResponse");
+  }
+
+  return buildResponse(state);
+}
+
+function mergeAuxiliary(base: AuxiliaryInfo, patch: Partial<AuxiliaryInfo>): AuxiliaryInfo {
+  const merged: AuxiliaryInfo = {
+    ...base,
+    ...patch,
+  };
+
+  if (base.providerMetadata || patch.providerMetadata) {
+    merged.providerMetadata = {
+      ...(base.providerMetadata ?? {}),
+      ...(patch.providerMetadata ?? {}),
+    };
+  }
+
+  return merged;
+}
+
+function pushWarnings(state: AggregatorState, warnings: readonly string[]): void {
+  for (const warning of warnings) {
+    if (!state.warnings.includes(warning)) {
+      state.warnings.push(warning);
+    }
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,23 @@
+/**
+ * AI 客户端入口
+ *
+ * 打通 createAIClient() 到 adapter 调用之间的公共入口。
+ */
+
+import type { AIRequest, AIStreamEvent, AIClient, CreateAIClientOptions } from "../types/index.js";
+import { normalizeRequest } from "./normalize.js";
+
+export function createAIClient(options: CreateAIClientOptions): AIClient {
+  const { adapter, model, defaults } = options;
+
+  const client: AIClient = {
+    stream(request: AIRequest): AsyncIterable<AIStreamEvent> {
+      const normalized = normalizeRequest(request, { model, defaults });
+      return adapter.stream(normalized);
+    },
+  };
+
+  return client;
+}
+
+export type { AIClient, CreateAIClientOptions } from "../types/index.js";

package/src/core/collect-stream.ts

@@ -0,0 +1,19 @@
+/**
+ * collectStream — 流收集 helper
+ *
+ * 将 AsyncIterable<AIStreamEvent> 消费完毕并聚合力 AIResponse。
+ * 适用于不需要逐事件处理的调用方。
+ */
+
+import type { AIStreamEvent, AIResponse } from "../types/index.js";
+import { aggregateEvents } from "./aggregator.js";
+
+export async function collectStream(stream: AsyncIterable<AIStreamEvent>): Promise<AIResponse> {
+  const events: AIStreamEvent[] = [];
+
+  for await (const event of stream) {
+    events.push(event);
+  }
+
+  return aggregateEvents(events);
+}

package/src/core/errors.ts

@@ -0,0 +1,99 @@
+/**
+ * 公共错误模型
+ *
+ * 把失败、降级、断流三类情况明确区分：
+ * - 致命错误 → 同步抛错或迭代器抛错
+ * - 非致命差异 → warning 通道
+ * - 流中断 → 不伪造 response.completed
+ */
+
+// ── 错误类型 ──────────────────────────────────────────────────
+
+export type ErrorCode =
+  | "INPUT_EMPTY"
+  | "TEMPERATURE_OUT_OF_RANGE"
+  | "MAX_OUTPUT_TOKENS_INVALID"
+  | "TOOL_CHOICE_NO_TOOLS"
+  | "TOOL_CHOICE_UNKNOWN_TOOL"
+  | "PROVIDER_ERROR"
+  | "AUTH_ERROR"
+  | "STREAM_ERROR"
+  | "MAPPING_ERROR"
+  | "STREAM_INCOMPLETE"
+  | "LOOKUP_FAILED"
+  | "LOOKUP_TIMEOUT"
+  | string;
+
+export class AIError extends Error {
+  override readonly name: string;
+
+  constructor(
+    message: string,
+    public readonly code: ErrorCode,
+    name?: string,
+  ) {
+    super(message);
+    this.name = name ?? "AIError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** 请求构造失败 — 参数校验不通过。在进入 adapter 前同步抛错。 */
+export class AIRequestError extends AIError {
+  constructor(message: string, code: ErrorCode) {
+    super(message, code, "AIRequestError");
+  }
+}
+
+/** Provider 调用失败 — HTTP 非 2xx、网络错误。由 AdapterBase 捕获转为 warning。 */
+export class AIProviderError extends AIError {
+  constructor(
+    message: string,
+    code: ErrorCode,
+    public readonly statusCode?: number,
+    public readonly responseBody?: string,
+  ) {
+    super(message, code, "AIProviderError");
+  }
+}
+
+/** 流协议损坏 — SSE 解析失败、chunk 格式异常。 */
+export class AIStreamError extends AIError {
+  constructor(message: string, code: ErrorCode) {
+    super(message, code, "AIStreamError");
+  }
+}
+
+/** Canonical 映射失败 — 无法将 provider 响应映射到 canonical 类型。 */
+export class AIMappingError extends AIError {
+  constructor(message: string, code: ErrorCode) {
+    super(message, code, "AIMappingError");
+  }
+}
+
+// ── Warning 辅助 ──────────────────────────────────────────────
+
+/**
+ * 标准 warning 代码列表。
+ * 用于非致命差异的记录。
+ */
+export const WarningCode = {
+  /** replay fidelity 低于预期 */
+  REPLAY_FIDELITY_LOW: "REPLAY_FIDELITY_LOW",
+  /** usage 字段缺失 */
+  USAGE_MISSING: "USAGE_MISSING",
+  /** billing 字段缺失 */
+  BILLING_MISSING: "BILLING_MISSING",
+  /** billing 只能给估算值 */
+  BILLING_ESTIMATED: "BILLING_ESTIMATED",
+  /** follow-up lookup 失败 */
+  LOOKUP_FAILED: "LOOKUP_FAILED",
+  /** lookup 超时 */
+  LOOKUP_TIMEOUT: "LOOKUP_TIMEOUT",
+  /** 流提前中断 */
+  STREAM_INCOMPLETE: "STREAM_INCOMPLETE",
+  /** 能力降级 */
+  CAPABILITY_DOWNGRADE: "CAPABILITY_DOWNGRADE",
+  /** 模拟流式 */
+  SYNTHETIC_STREAM: "SYNTHETIC_STREAM",
+} as const;

package/src/core/event-factory.ts

@@ -0,0 +1,141 @@
+/**
+ * 共享事件工厂
+ *
+ * 负责创建带有统一 sequence / timestamp / responseId / backend 的事件对象。
+ * 每个 factory 实例管理一个单调递增的 sequence 计数器。
+ */
+
+import type {
+  ResponseStartedEvent,
+  ResponseWarningEvent,
+  ResponseAuxiliaryEvent,
+  ResponseCompletedEvent,
+  MessageStartedEvent,
+  MessageDeltaEvent,
+  MessageCompletedEvent,
+  ReasoningStartedEvent,
+  ReasoningDeltaEvent,
+  ReasoningCompletedEvent,
+  ToolCallStartedEvent,
+  ToolCallDeltaEvent,
+  ToolCallCompletedEvent,
+  MessageItem,
+  ReasoningItem,
+  ToolCallItem,
+  ContentBlock,
+  Usage,
+  BillingInfo,
+  AuxiliaryInfo,
+  AIResponse,
+} from "../types/index.js";
+
+export type EventFactoryBackend = {
+  kind: "chat-completions" | "messages" | "responses" | "ollama";
+  isSynthetic: boolean;
+};
+
+export type EventFactoryState = {
+  responseId: string;
+  backend: EventFactoryBackend;
+};
+
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+export function createEventFactory(state: EventFactoryState) {
+  let seq = 0;
+  const warnings: string[] = [];
+
+  function next(): number {
+    return seq++;
+  }
+
+  function base(): Pick<ResponseStartedEvent, "responseId" | "sequence" | "timestamp" | "backend"> {
+    return {
+      responseId: state.responseId,
+      sequence: next(),
+      timestamp: timestamp(),
+      backend: { ...state.backend },
+    };
+  }
+
+  return {
+    // ── 响应级事件 ──────────────────────────────────────────
+
+    responseStarted(model: string): ResponseStartedEvent {
+      return { ...base(), type: "response.started", model };
+    },
+
+    responseWarning(message: string, code?: string): ResponseWarningEvent {
+      warnings.push(message);
+      return { ...base(), type: "response.warning", message, code };
+    },
+
+    responseAuxiliary(data: {
+      usage?: Usage;
+      billing?: BillingInfo;
+      auxiliary?: Partial<AuxiliaryInfo>;
+    }): ResponseAuxiliaryEvent {
+      return { ...base(), type: "response.auxiliary", ...data };
+    },
+
+    responseCompleted(response: AIResponse): ResponseCompletedEvent {
+      return { ...base(), type: "response.completed", response };
+    },
+
+    // ── 消息流事件 ──────────────────────────────────────────
+
+    messageStarted(id: string): MessageStartedEvent {
+      return { ...base(), type: "message.started", item: { id, role: "assistant" } };
+    },
+
+    messageDelta(itemId: string, text: string): MessageDeltaEvent {
+      return { ...base(), type: "message.delta", itemId, delta: { type: "text", text } };
+    },
+
+    messageCompleted(item: MessageItem): MessageCompletedEvent {
+      return { ...base(), type: "message.completed", item };
+    },
+
+    // ── 思维链流事件 ────────────────────────────────────────
+
+    reasoningStarted(id: string, visibility: ReasoningItem["visibility"]): ReasoningStartedEvent {
+      return { ...base(), type: "reasoning.started", item: { id, visibility } };
+    },
+
+    reasoningDelta(itemId: string, delta: ContentBlock): ReasoningDeltaEvent {
+      return { ...base(), type: "reasoning.delta", itemId, delta };
+    },
+
+    reasoningCompleted(item: ReasoningItem): ReasoningCompletedEvent {
+      return { ...base(), type: "reasoning.completed", item };
+    },
+
+    // ── 工具调用流事件 ──────────────────────────────────────
+
+    toolCallStarted(id: string, name: string): ToolCallStartedEvent {
+      return { ...base(), type: "tool_call.started", item: { id, name } };
+    },
+
+    toolCallDelta(itemId: string, delta: { argumentsText?: string }): ToolCallDeltaEvent {
+      return { ...base(), type: "tool_call.delta", itemId, delta };
+    },
+
+    toolCallCompleted(item: ToolCallItem): ToolCallCompletedEvent {
+      return { ...base(), type: "tool_call.completed", item };
+    },
+
+    /** 返回当前已发出的 sequence 计数（用于断言） */
+    get sequence(): number {
+      return seq;
+    },
+
+    /** 返回当前已记录的 warning 副本。 */
+    get warnings(): string[] {
+      return [...warnings];
+    },
+  };
+}
+
+export type EventFactory = ReturnType<typeof createEventFactory>;

package/src/core/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 核心运行时
+ *
+ * 模块边界：客户端入口、请求归一化、事件工厂、流聚合器。
+ * 不依赖具体 adapter 实现。
+ */
+
+export { createAIClient } from "./client.js";
+export type { AIClient } from "./client.js";
+export { normalizeRequest } from "./normalize.js";
+export type { NormalizeOptions } from "./normalize.js";
+export { validateRequest, assertValidRequest } from "./validation.js";
+export type { ValidationIssue } from "./validation.js";
+export { AIError, AIRequestError, AIProviderError, AIStreamError, AIMappingError, WarningCode } from "./errors.js";
+export { createEventFactory } from "./event-factory.js";
+export type { EventFactory, EventFactoryState, EventFactoryBackend } from "./event-factory.js";
+export { aggregateEvents } from "./aggregator.js";
+export { collectStream } from "./collect-stream.js";

package/src/core/normalize.ts

@@ -0,0 +1,51 @@
+/**
+ * 请求归一化
+ *
+ * 将 AIRequest + client 配置归一化为 NormalizedRequest，
+ * 包括默认值合并、requestId 生成、include 默认值填充。
+ */
+
+import type { AIRequest, NormalizedRequest } from "../types/index.js";
+import { assertValidRequest } from "./validation.js";
+
+export type NormalizeOptions = {
+  model: string;
+  defaults?: Partial<AIRequest>;
+};
+
+const DEFAULT_INCLUDE = {
+  usage: "best_effort" as const,
+  billing: "best_effort" as const,
+  providerMetadata: "best_effort" as const,
+};
+
+/**
+ * 归一化请求：
+ * 1. 合并 defaults
+ * 2. 填充 include 默认值
+ * 3. 生成 requestId
+ * 4. 校验请求合法性
+ */
+export function normalizeRequest(request: AIRequest, options: NormalizeOptions): NormalizedRequest {
+  const { model, defaults } = options;
+
+  // 合并 defaults（浅合并，input/tools 由 request 完全覆盖）
+  const merged: AIRequest = {
+    ...defaults,
+    ...request,
+    include: {
+      ...DEFAULT_INCLUDE,
+      ...defaults?.include,
+      ...request.include,
+    },
+  };
+
+  // 校验
+  assertValidRequest(merged);
+
+  return {
+    ...merged,
+    model,
+    requestId: crypto.randomUUID(),
+  };
+}