@codehz/ai 0.4.5 → 0.7.0

package/src/core/aggregator.ts

@@ -1,428 +0,0 @@
-/**
- * 流聚合器
- *
- * 将 AIStreamEvent 序列聚合为统一的 AIResponse。
- *
- * 职责：
- * - 严格 item 状态机：started 创建 active item，delta 累积，completed 构建 OutputItem
- * - 校验：未 started 的 delta/completed、ID 重用、类型错配、response.completed 时 active items 非空
- * - 响应级 sequence/responseId/started/completed 校验
- * - usage/billing/auxiliary 仅来自 response.auxiliary
- * - warning 仅来自 response.warning
- * - 最终 AIResponse 由聚合器唯一构建
- *
- * 约束：
- * - replay 由 adapter 显式提供，聚合器不猜测
- * - 不伪造 reasoning
- * - 不解释 opaque payload
- */
-
-import type {
-  AIStreamEvent,
-  AIResponse,
-  MessageItem,
-  ToolCallItem,
-  OutputItem,
-  Usage,
-  BillingInfo,
-  AuxiliaryInfo,
-  BackendTrace,
-  StopReason,
-  ContentBlock,
-} from "../types/index.js";
-import { AIStreamError } from "./errors.js";
-import { mergeAuxiliary } from "./merge-auxiliary.js";
-
-// ── Active item types ─────────────────────────────────────────
-
-type ActiveMessage = {
-  type: "message";
-  id: string;
-  role: "assistant";
-  content: ContentBlock[];
-};
-
-type ActiveReasoning = {
-  type: "reasoning";
-  id: string;
-  visibility: "full" | "summary" | "redacted" | "opaque";
-  content: ContentBlock[];
-};
-
-type ActiveToolCall = {
-  type: "tool_call";
-  id: string;
-  name: string;
-  argumentsText: string;
-};
-
-type ActiveItem = ActiveMessage | ActiveReasoning | ActiveToolCall;
-
-// ── 聚合器状态 ────────────────────────────────────────────────
-
-export interface AggregatorState {
-  responseId?: string;
-  model?: string;
-  backendInfo?: { kind: BackendTrace["adapter"]; isSynthetic: boolean };
-
-  usage?: Usage;
-  billing?: BillingInfo;
-  auxiliary: AuxiliaryInfo;
-  warnings: string[];
-  warningSet: Set<string>;
-  output: OutputItem[];
-  textParts: string[];
-  toolCalls: ToolCallItem[];
-  lastEventType?: AIStreamEvent["type"];
-  started: boolean;
-  completed: boolean;
-  nextSequence?: number;
-  activeItems: Map<string, ActiveItem>;
-  itemOrder: string[];
-  completedItems: Map<string, OutputItem>;
-
-  /** adapter 在 response.completed 中提供的 replay */
-  replayFromAdapter?: import("../types/index.js").ReplayItem[];
-  stopReasonFromAdapter?: StopReason;
-  backendFromAdapter?: Partial<BackendTrace>;
-}
-
-export function createAggregatorState(): AggregatorState {
-  return {
-    auxiliary: {},
-    warnings: [],
-    warningSet: new Set(),
-    output: [],
-    textParts: [],
-    toolCalls: [],
-    started: false,
-    completed: false,
-    activeItems: new Map(),
-    itemOrder: [],
-    completedItems: new Map(),
-  };
-}
-
-// ── Active item helpers ───────────────────────────────────────
-
-function getActiveItem(state: AggregatorState, itemId: string, expectedType: ActiveItem["type"]): ActiveItem {
-  const item = state.activeItems.get(itemId);
-  if (!item) {
-    throw streamProtocolError(`Received ${expectedType} delta/completed for unknown item: ${itemId}`);
-  }
-  if (item.type !== expectedType) {
-    throw streamProtocolError(`Item ${itemId} started as ${item.type} but received ${expectedType} event`);
-  }
-  return item;
-}
-
-function coalesceContentBlocks(blocks: readonly ContentBlock[]): ContentBlock[] {
-  const result: ContentBlock[] = [];
-  for (const block of blocks) {
-    const previous = result[result.length - 1];
-    if (block.type === "text" && previous?.type === "text") {
-      previous.text += block.text;
-    } else {
-      result.push({ ...block });
-    }
-  }
-  return result;
-}
-
-function finalizeMessage(active: ActiveMessage): MessageItem {
-  return {
-    type: "message",
-    id: active.id,
-    role: active.role,
-    content: coalesceContentBlocks(active.content),
-  };
-}
-
-function finalizeReasoning(active: ActiveReasoning): import("../types/index.js").ReasoningItem {
-  return {
-    type: "reasoning",
-    id: active.id,
-    visibility: active.visibility,
-    content: coalesceContentBlocks(active.content),
-  };
-}
-
-function finalizeToolCall(active: ActiveToolCall): ToolCallItem {
-  return {
-    type: "tool_call",
-    id: active.id,
-    name: active.name,
-    argumentsText: active.argumentsText,
-  };
-}
-
-// ── Event handlers ────────────────────────────────────────────
-
-function handleResponseStarted(state: AggregatorState, event: AIStreamEvent & { type: "response.started" }): void {
-  if (state.started) {
-    throw streamProtocolError("Stream must contain exactly one response.started event");
-  }
-  state.started = true;
-  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 {
-  const id = event.item.id;
-  if (state.activeItems.has(id)) {
-    throw streamProtocolError(`Item with id ${id} is already active`);
-  }
-  state.activeItems.set(id, {
-    type: "message",
-    id,
-    role: event.item.role,
-    content: [],
-  });
-  state.itemOrder.push(id);
-}
-
-function handleMessageDelta(state: AggregatorState, event: AIStreamEvent & { type: "message.delta" }): void {
-  const active = getActiveItem(state, event.itemId, "message") as ActiveMessage;
-  active.content.push(event.delta);
-}
-
-function handleMessageCompleted(state: AggregatorState, event: AIStreamEvent & { type: "message.completed" }): void {
-  const active = getActiveItem(state, event.itemId, "message") as ActiveMessage;
-  state.activeItems.delete(event.itemId);
-  const item = finalizeMessage(active);
-  state.completedItems.set(event.itemId, item);
-  pushMessageText(state, item);
-}
-
-function handleReasoningStarted(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.started" }): void {
-  const id = event.item.id;
-  if (state.activeItems.has(id)) {
-    throw streamProtocolError(`Item with id ${id} is already active`);
-  }
-  state.activeItems.set(id, {
-    type: "reasoning",
-    id,
-    visibility: event.item.visibility,
-    content: [],
-  });
-  state.itemOrder.push(id);
-}
-
-function handleReasoningDelta(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.delta" }): void {
-  const active = getActiveItem(state, event.itemId, "reasoning") as ActiveReasoning;
-  active.content.push(event.delta);
-}
-
-function handleReasoningCompleted(
-  state: AggregatorState,
-  event: AIStreamEvent & { type: "reasoning.completed" },
-): void {
-  const active = getActiveItem(state, event.itemId, "reasoning") as ActiveReasoning;
-  state.activeItems.delete(event.itemId);
-  state.completedItems.set(event.itemId, finalizeReasoning(active));
-}
-
-function handleToolCallStarted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.started" }): void {
-  const id = event.item.id;
-  if (state.activeItems.has(id)) {
-    throw streamProtocolError(`Item with id ${id} is already active`);
-  }
-  state.activeItems.set(id, {
-    type: "tool_call",
-    id,
-    name: event.item.name,
-    argumentsText: "",
-  });
-  state.itemOrder.push(id);
-}
-
-function handleToolCallDelta(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.delta" }): void {
-  const active = getActiveItem(state, event.itemId, "tool_call") as ActiveToolCall;
-  if (event.delta.argumentsText) {
-    active.argumentsText += event.delta.argumentsText;
-  }
-}
-
-function handleToolCallCompleted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.completed" }): void {
-  const active = getActiveItem(state, event.itemId, "tool_call") as ActiveToolCall;
-  state.activeItems.delete(event.itemId);
-  const item = finalizeToolCall(active);
-  state.completedItems.set(event.itemId, item);
-  state.toolCalls.push(item);
-}
-
-function handleResponseCompleted(state: AggregatorState, event: AIStreamEvent & { type: "response.completed" }): void {
-  if (state.activeItems.size > 0) {
-    throw streamProtocolError("response.completed received while active items still pending");
-  }
-  state.completed = true;
-  state.replayFromAdapter = event.replay;
-  state.stopReasonFromAdapter = event.stopReason;
-  state.backendFromAdapter = event.trace;
-  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) ?? {};
-  if (event.warnings) pushWarnings(state, event.warnings);
-  if (event.opaqueOutput) state.output.push(...event.opaqueOutput);
-}
-
-// ── 从聚合状态构建最终 AIResponse ─────────────────────────────
-
-function buildResponse(state: AggregatorState): AIResponse {
-  const backendFromCompleted = state.backendFromAdapter;
-  const backend: BackendTrace = {
-    adapter: backendFromCompleted?.adapter ?? state.backendInfo?.kind ?? ("unknown" as BackendTrace["adapter"]),
-    isSyntheticStream: backendFromCompleted?.isSyntheticStream ?? state.backendInfo?.isSynthetic ?? false,
-    requestId: backendFromCompleted?.requestId ?? state.responseId,
-    rawResponseId: backendFromCompleted?.rawResponseId,
-    metadataSources: backendFromCompleted?.metadataSources,
-    warnings: backendFromCompleted?.warnings,
-  };
-  const orderedOutput = state.itemOrder.map((id) => {
-    const item = state.completedItems.get(id);
-    if (!item) {
-      throw streamProtocolError(`Item ${id} was started but not completed`);
-    }
-    return item;
-  });
-
-  return {
-    id: state.responseId,
-    output: [...orderedOutput, ...state.output],
-    replay: state.replayFromAdapter ?? [],
-    text: state.textParts.join(""),
-    toolCalls: state.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: readonly AIStreamEvent[]): AIResponse {
-  const state = createAggregatorState();
-  for (const event of events) {
-    aggregateEvent(state, event);
-  }
-  return finalizeAggregation(state);
-}
-
-export function aggregateEvent(state: AggregatorState, event: AIStreamEvent): void {
-  validateEventEnvelope(state, event);
-  state.lastEventType = event.type;
-
-  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;
-  }
-}
-
-export function finalizeAggregation(state: AggregatorState): AIResponse {
-  if (!state.started) {
-    throw streamProtocolError("Stream must start with response.started event");
-  }
-  if (!state.completed || state.lastEventType !== "response.completed") {
-    throw streamProtocolError("Stream must end with response.completed event to produce a valid AIResponse");
-  }
-
-  return buildResponse(state);
-}
-
-function pushWarnings(state: AggregatorState, warnings: readonly string[]): void {
-  for (const warning of warnings) {
-    if (!state.warningSet.has(warning)) {
-      state.warningSet.add(warning);
-      state.warnings.push(warning);
-    }
-  }
-}
-
-function pushMessageText(state: AggregatorState, item: MessageItem): void {
-  for (const block of item.content) {
-    if (block.type === "text") {
-      state.textParts.push(block.text);
-    }
-  }
-}
-
-function validateEventEnvelope(state: AggregatorState, event: AIStreamEvent): void {
-  if (state.completed) {
-    throw streamProtocolError("response.completed must be the final stream event");
-  }
-  if (!state.started && event.type !== "response.started") {
-    throw streamProtocolError("Stream must start with response.started event");
-  }
-  if (state.responseId !== undefined && event.responseId !== state.responseId) {
-    throw streamProtocolError("All stream events must use the same responseId");
-  }
-  if (state.nextSequence !== undefined && event.sequence !== state.nextSequence) {
-    throw streamProtocolError(`Expected event sequence ${state.nextSequence}, received ${event.sequence}`);
-  }
-  state.nextSequence = event.sequence + 1;
-}
-
-function streamProtocolError(message: string): AIStreamError {
-  return new AIStreamError(message, "STREAM_PROTOCOL_ERROR");
-}

package/src/core/client.ts

@@ -1,36 +0,0 @@
-/**
- * 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, signal: defaultSignal } = options;
-
-  const client: AIClient = {
-    stream(request: AIRequest): AsyncIterable<AIStreamEvent> {
-      // 合并 client 级别的默认 signal 和请求级别的 signal
-      const signal = mergeAbortSignals(defaultSignal, request.signal);
-      const normalized = normalizeRequest({ ...request, signal }, { model, defaults });
-      return adapter.stream(normalized);
-    },
-  };
-
-  return client;
-}
-
-/**
- * 合并多个 AbortSignal：任一 signal abort 即触发。
- * 如果没有 signal 需要合并则返回 undefined。
- */
-function mergeAbortSignals(...signals: (AbortSignal | undefined)[]): AbortSignal | undefined {
-  const valid = signals.filter((s): s is AbortSignal => s != null);
-  if (valid.length === 0) return undefined;
-  if (valid.length === 1) return valid[0];
-  return AbortSignal.any(valid);
-}
-
-export type { AIClient, CreateAIClientOptions } from "../types/index.js";

package/src/core/collect-stream.ts

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

package/src/core/errors.ts

@@ -1,105 +0,0 @@
-/**
- * 公共错误模型
- *
- * 把失败、降级、断流三类情况明确区分：
- * - 致命错误 → 同步抛错或迭代器抛错
- * - 非致命差异 → 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,
-    public readonly issues?: readonly { field: string; code: string; message: string }[],
-  ) {
-    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",
-  /** 工具调用以批量方式到达（非 token 级流式） */
-  TOOL_CALL_BATCHED: "TOOL_CALL_BATCHED",
-} as const;