@codehz/ai 0.1.0

package/src/helpers/auxiliary-collector.ts

@@ -0,0 +1,166 @@
+/**
+ * 辅助信息采集器 (AuxiliaryCollector)
+ *
+ * 为 usage、billing、providerMetadata 提供统一的 best-effort 采集。
+ *
+ * 采集优先级（分层）：
+ *   1. 主响应 body / terminal event
+ *   2. headers / trailers
+ *   3. SDK metadata
+ *   4. 一次 follow-up lookup
+ *   5. derived estimate
+ *
+ * 约束：
+ *   - lookup 最多一次有界补查
+ *   - lookup 失败只记录 warning
+ *   - 不阻断主生成链路
+ */
+
+import type { Usage, BillingInfo, AuxiliaryInfo } from "../types/index.js";
+
+// ── 来源类型 ──────────────────────────────────────────────────
+
+export type UsageSource = NonNullable<AuxiliaryInfo["usageSource"]>;
+export type BillingSource = NonNullable<AuxiliaryInfo["billingSource"]>;
+
+export type LookupResult = {
+  usage?: Partial<Usage>;
+  billing?: Partial<BillingInfo>;
+  providerMetadata?: Record<string, unknown>;
+};
+
+// ── Collector ─────────────────────────────────────────────────
+
+export class AuxiliaryCollector {
+  private usage: Partial<Usage> = {};
+  private usageSource: UsageSource | undefined;
+  private billing: Partial<BillingInfo> | undefined;
+  private billingSource: BillingSource | undefined;
+  private providerMetadata: Record<string, unknown> = {};
+  private providerUsage: unknown;
+  private providerBilling: unknown;
+  private warnings: string[] = [];
+  private lookupAttempted = false;
+
+  // ── 记录方法 ──────────────────────────────────────────────
+
+  /**
+   * 记录 usage 信息。
+   * 后调用的覆盖先调用的（优先级由调用方控制）。
+   */
+  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): this {
+    this.usage = { ...this.usage, ...usage };
+    this.usageSource = source;
+    if (raw !== undefined) this.providerUsage = raw;
+    return this;
+  }
+
+  /**
+   * 记录 billing 信息。
+   * 后调用的覆盖先调用的。
+   */
+  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): this {
+    this.billing = { ...this.billing, ...billing };
+    this.billingSource = source;
+    if (raw !== undefined) this.providerBilling = raw;
+    return this;
+  }
+
+  /**
+   * 记录 provider 元数据（非 canonical 的 key-value 信息）。
+   */
+  recordMetadata(metadata: Record<string, unknown>): this {
+    this.providerMetadata = { ...this.providerMetadata, ...metadata };
+    return this;
+  }
+
+  /**
+   * 记录一条 warning。
+   */
+  recordWarning(message: string): this {
+    this.warnings.push(message);
+    return this;
+  }
+
+  // ── 有界 Lookup ───────────────────────────────────────────
+
+  /**
+   * 执行一次有界 follow-up lookup。
+   * 最多调用一次；后续调用被忽略。
+   * lookup 失败（抛错）仅记录 warning，不传播异常。
+   */
+  async tryLookup(lookupFn: () => Promise<LookupResult>, timeoutMs = 5_000): Promise<void> {
+    if (this.lookupAttempted) return;
+    this.lookupAttempted = true;
+
+    try {
+      const result = await withTimeout(lookupFn(), timeoutMs);
+      if (result.usage) {
+        this.recordUsage(result.usage, "lookup", result.usage);
+      }
+      if (result.billing) {
+        const bill: Partial<BillingInfo> = {
+          ...result.billing,
+          source: result.billing?.source ?? "lookup",
+        };
+        this.recordBilling(bill, "lookup", result.billing);
+      }
+      if (result.providerMetadata) {
+        this.recordMetadata(result.providerMetadata);
+      }
+    } catch (err) {
+      this.recordWarning(`Auxiliary lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ── 构建最终结果 ──────────────────────────────────────────
+
+  /**
+   * 构建最终的 usage / billing / auxiliary。
+   * 所有字段均为可选的 — 拿不到就不给。
+   */
+  build(): { usage?: Usage; billing?: BillingInfo; auxiliary?: AuxiliaryInfo; warnings?: string[] } {
+    const result: { usage?: Usage; billing?: BillingInfo; auxiliary?: AuxiliaryInfo; warnings?: string[] } = {};
+
+    if (Object.keys(this.usage).length > 0) {
+      result.usage = this.usage as Usage;
+    }
+
+    if (this.billing) {
+      result.billing = this.billing as BillingInfo;
+    }
+
+    const aux: AuxiliaryInfo = {};
+    if (this.usageSource) aux.usageSource = this.usageSource;
+    if (this.billingSource) aux.billingSource = this.billingSource;
+    if (this.providerUsage !== undefined) aux.providerUsage = this.providerUsage;
+    if (this.providerBilling !== undefined) aux.providerBilling = this.providerBilling;
+    if (Object.keys(this.providerMetadata).length > 0) aux.providerMetadata = this.providerMetadata;
+
+    if (Object.keys(aux).length > 0) {
+      result.auxiliary = aux;
+    }
+
+    if (this.warnings.length > 0) {
+      result.warnings = [...this.warnings];
+    }
+
+    return result;
+  }
+
+  /**
+   * 已使用的来源列表（用于 debugging）。
+   */
+  get sources(): { usage?: UsageSource; billing?: BillingSource } {
+    return { usage: this.usageSource, billing: this.billingSource };
+  }
+}
+
+// ── Helper ────────────────────────────────────────────────────
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(`Lookup timed out after ${ms}ms`)), ms)),
+  ]);
+}

package/src/helpers/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 共享工具模块
+ *
+ * 模块边界：adapter 间共享的映射 helper、adapter 基类、模拟流式、辅助信息采集等。
+ */
+
+export {
+  mapStopReason,
+  mapReasoningVisibility,
+  textBlock,
+  jsonBlock,
+  imageBlock,
+  opaqueBlock,
+  blockToText,
+  contentBlocksToText,
+  instructionsToText,
+  extractText,
+  messageItem,
+  reasoningItem,
+  toolCallItem,
+  toolResultItem,
+  opaqueItem,
+  replayFromOutput,
+} from "./mapping.js";
+
+export { parseSSEEvents } from "./sse-parser.js";
+export type { SSEEvent } from "./sse-parser.js";
+
+export { AdapterBase } from "./adapter-base.js";
+export type { StreamResult } from "./adapter-base.js";
+export {
+  AdapterAuxiliaryState,
+  emitMalformedStreamWarning,
+  metadataSourceList,
+} from "./adapter-auxiliary.js";
+export type { AuxiliaryFinalizeOptions, AuxiliaryFinalizeResult, BillingPostprocessHook } from "./adapter-auxiliary.js";
+export { syntheticStream } from "./synthetic-stream.js";
+export type { SyntheticStreamOptions } from "./synthetic-stream.js";
+export { AuxiliaryCollector } from "./auxiliary-collector.js";
+export type { UsageSource, BillingSource, LookupResult } from "./auxiliary-collector.js";

package/src/helpers/mapping.ts

@@ -0,0 +1,200 @@
+/**
+ * Adapter 共享映射 helper
+ *
+ * 提供 adapter 间通用的类型映射函数：
+ * - stop reason 映射
+ * - content block 映射
+ * - item 映射
+ * - warning 记录
+ * - replay 构造工具
+ */
+
+import type {
+  StopReason,
+  ContentBlock,
+  MessageItem,
+  ReasoningItem,
+  ToolCallItem,
+  ToolResultItem,
+  OpaqueItem,
+  InputItem,
+  OutputItem,
+  ReplayItem,
+} from "../types/index.js";
+
+// ── Stop reason 映射 ──────────────────────────────────────────
+
+/**
+ * 常见 provider stop_reason / finish_reason 到 canonical StopReason 的映射表。
+ * adapter 可先查此表，未覆盖时走 fallback 规则。
+ */
+const STOP_REASON_MAP: Record<string, StopReason> = {
+  // OpenAI / Azure
+  stop: "end_turn",
+  length: "max_output_tokens",
+  content_filter: "content_filter",
+  tool_calls: "tool_call",
+  // Anthropic
+  end_turn: "end_turn",
+  max_tokens: "max_output_tokens",
+  tool_use: "tool_call",
+  // Generic
+  error: "error",
+};
+
+export function mapStopReason(providerReason: string): StopReason {
+  return STOP_REASON_MAP[providerReason] ?? "unknown";
+}
+
+// ── Reasoning visibility 映射 ──────────────────────────────────
+
+export function mapReasoningVisibility(hasThinking: boolean, hasRedacted: boolean): ReasoningItem["visibility"] {
+  if (hasRedacted) return "redacted";
+  if (hasThinking) return "full";
+  return "opaque";
+}
+
+// ── Content block 构造 helper ─────────────────────────────────
+
+export function textBlock(text: string): ContentBlock & { type: "text" } {
+  return { type: "text", text };
+}
+
+export function jsonBlock(json: unknown): ContentBlock & { type: "json" } {
+  return { type: "json", json };
+}
+
+export function imageBlock(imageUrl: string): ContentBlock & { type: "image" } {
+  return { type: "image", imageUrl };
+}
+
+export function opaqueBlock(payload: unknown): ContentBlock & { type: "opaque" } {
+  return { type: "opaque", payload };
+}
+
+// ── Item 构造 helper ──────────────────────────────────────────
+
+export function messageItem(
+  content: ContentBlock[],
+  overrides?: Partial<Omit<MessageItem, "type" | "content">>,
+): MessageItem {
+  return {
+    type: "message",
+    role: "assistant",
+    ...overrides,
+    content,
+  };
+}
+
+export function reasoningItem(
+  content: ContentBlock[],
+  visibility: ReasoningItem["visibility"] = "full",
+  id?: string,
+): ReasoningItem {
+  return {
+    type: "reasoning",
+    id,
+    visibility,
+    content,
+  };
+}
+
+export function toolCallItem(id: string, name: string, argumentsText: string, argumentsJson?: unknown): ToolCallItem {
+  return {
+    type: "tool_call",
+    id,
+    name,
+    argumentsText,
+    argumentsJson,
+  };
+}
+
+export function toolResultItem(
+  callId: string,
+  toolName: string,
+  outcome: ToolResultItem["outcome"],
+  content: ContentBlock[],
+): ToolResultItem {
+  return {
+    type: "tool_result",
+    callId,
+    toolName,
+    outcome,
+    content,
+  };
+}
+
+export function opaqueItem(
+  source: OpaqueItem["source"],
+  purpose: OpaqueItem["purpose"],
+  payload: unknown,
+  id?: string,
+): OpaqueItem {
+  return {
+    type: "opaque",
+    id,
+    source,
+    purpose,
+    payload,
+  };
+}
+
+// ── Replay 构造工具 ──────────────────────────────────────────
+
+/**
+ * 从 output items 构建标准 replay items。
+ * 简单场景下 replay 与 output 一致。
+ * 复杂场景（需要 opaque continuation）由 adapter 自行扩展。
+ */
+export function replayFromOutput(output: readonly OutputItem[]): ReplayItem[] {
+  return output.map((item): InputItem => {
+    switch (item.type) {
+      case "message":
+      case "reasoning":
+      case "tool_call":
+        return item as InputItem;
+      case "opaque":
+        return item;
+    }
+  });
+}
+
+// ── Content block 提取 helper ──────────────────────────────────
+
+/**
+ * 将单个 ContentBlock 转为纯文本。
+ * text 块直接返回文本，json 块序列化，其余返回空串。
+ */
+export function blockToText(b: ContentBlock): string {
+  if (b.type === "text") return b.text;
+  if (b.type === "json") return JSON.stringify(b.json);
+  return "";
+}
+
+/**
+ * 将 ContentBlock 数组拼接为纯文本，块间以换行符分隔。
+ */
+export function contentBlocksToText(blocks: ContentBlock[]): string {
+  return blocks.map(blockToText).join("\n");
+}
+
+/**
+ * 将 instructions（string | ContentBlock[]）归一化为纯文本。
+ */
+export function instructionsToText(instructions: string | ContentBlock[]): string {
+  return typeof instructions === "string" ? instructions : contentBlocksToText(instructions);
+}
+
+// ── Output 文本提取 ───────────────────────────────────────────
+
+/**
+ * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
+ */
+export function extractText(output: OutputItem[]): string {
+  return 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("");
+}

package/src/helpers/sse-parser.ts

@@ -0,0 +1,87 @@
+/**
+ * 通用 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，需要累积到下次调用
+ * ```
+ */
+
+export type SSEEvent = { type: string; data: unknown };
+
+export type SSEParseResult = {
+  events: SSEEvent[];
+  rest: string;
+  malformedEvents: number;
+};
+
+/**
+ * 将 SSE 文本块解析为事件数组。
+ * 累积事件行直到遇到空行，支持 [DONE] 标记。
+ * 返回已解析的事件和未处理的剩余 buffer（用于增量解析）。
+ *
+ * 关键行为：
+ * - 只解析完整的 event（以空行结尾）
+ * - 未完成的行保留在 rest 中，等待下次 chunk 补全
+ * - 支持跨 chunk 的 event 分片
+ */
+export function parseSSEEvents(chunk: string): SSEParseResult {
+  const events: SSEEvent[] = [];
+  let eventType = "";
+  let dataLines: string[] = [];
+  let consumedUntil = 0;
+  let cursor = 0;
+  let malformedEvents = 0;
+
+  while (cursor < chunk.length) {
+    const lineEnd = chunk.indexOf("\n", cursor);
+    if (lineEnd === -1) break;
+
+    let line = chunk.slice(cursor, lineEnd);
+    cursor = lineEnd + 1;
+
+    if (line.endsWith("\r")) {
+      line = line.slice(0, -1);
+    }
+
+    if (line.startsWith("event: ")) {
+      eventType = line.slice(7).trim();
+    } else if (line.startsWith("data: ")) {
+      dataLines.push(line.slice(6));
+    } else if (line === "" && eventType && dataLines.length > 0) {
+      // 完整的 event（以空行结尾）
+      const dataStr = dataLines.join("\n");
+      if (dataStr === "[DONE]") {
+        eventType = "";
+        dataLines = [];
+        consumedUntil = cursor;
+        continue;
+      }
+      try {
+        const data = JSON.parse(dataStr);
+        events.push({ type: eventType, data });
+      } catch {
+        malformedEvents++;
+      }
+      eventType = "";
+      dataLines = [];
+      consumedUntil = cursor;
+    } else if (line === "" && !eventType && dataLines.length === 0) {
+      consumedUntil = cursor;
+    }
+  }
+
+  return { events, rest: chunk.slice(consumedUntil), malformedEvents };
+}

package/src/helpers/synthetic-stream.ts

@@ -0,0 +1,196 @@
+/**
+ * 模拟流式 (Synthetic Streaming)
+ *
+ * 将一组已解析的 canonical OutputItem 包装为规范事件流。
+ * 适用于非原生流式后端：adapter 拿到完整响应后，调用此函数
+ * 即可产出一致的事件序列，无需自己逐事件组装。
+ *
+ * 约束：
+ * - 每个 item 只发一块完整 delta（不模拟逐 token）
+ * - 保持 item 边界
+ * - 保持后端原始顺序
+ * - 不发明 reasoning
+ * - 不改写工具参数
+ */
+
+import { createEventFactory } from "../core/event-factory.js";
+import { replayFromOutput, extractText } from "./mapping.js";
+
+import type {
+  OutputItem,
+  ReplayItem,
+  StopReason,
+  Usage,
+  BillingInfo,
+  AIStreamEvent,
+  AIResponse,
+  MessageItem,
+  ReasoningItem,
+  ToolCallItem,
+} from "../types/index.js";
+
+// ── 输入参数 ──────────────────────────────────────────────────
+
+export type SyntheticStreamOptions = {
+  model: string;
+  responseId: string;
+  backend: {
+    kind: "chat-completions" | "messages" | "responses";
+    /** syntheticStream 强制设为 true */
+  };
+  output: OutputItem[];
+  replay?: ReplayItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  providerMetadata?: Record<string, unknown>;
+  rawResponseId?: string;
+  warnings?: string[];
+};
+
+// ── Synthetic Stream ──────────────────────────────────────────
+
+/**
+ * 将已解析的 output items 包装为完整规范事件流。
+ *
+ * 用法示例（在 adapter 的 runStream 中）：
+ * ```ts
+ * const result = parseNonStreamingResponse(data);
+ * yield* syntheticStream({
+ *   model: request.model,
+ *   responseId: request.requestId,
+ *   backend: { kind: "chat-completions" },
+ *   output: result.output,
+ *   stopReason: result.stopReason,
+ *   usage: result.usage,
+ * });
+ * ```
+ */
+export async function* syntheticStream(options: SyntheticStreamOptions): AsyncIterable<AIStreamEvent> {
+  const {
+    model,
+    responseId,
+    backend,
+    output,
+    replay,
+    stopReason,
+    usage,
+    billing,
+    providerMetadata,
+    rawResponseId,
+    warnings: extraWarnings,
+  } = options;
+
+  const factory = createEventFactory({
+    responseId,
+    backend: { kind: backend.kind, isSynthetic: true },
+  });
+
+  // 1. 响应开始
+  yield factory.responseStarted(model);
+
+  // 2. item 级事件 — 每个 item 只发一块完整 delta
+  for (const item of output) {
+    yield* emitItemEvents(item, factory);
+  }
+
+  // 3. auxiliary 事件（如有）
+  if (usage || billing) {
+    yield factory.responseAuxiliary({ usage, billing });
+  }
+
+  // 4. 构建最终 response
+  const finalReplay = replay ?? replayFromOutput(output);
+
+  // 收集警告
+  const allWarnings: string[] = [];
+  allWarnings.push("Response is synthetically streamed; delta granularity may differ from native streaming");
+  if (extraWarnings) allWarnings.push(...extraWarnings);
+
+  const response: AIResponse = {
+    id: responseId,
+    output,
+    replay: finalReplay,
+    text: extractText(output),
+    toolCalls: output.filter((item): item is ToolCallItem => item.type === "tool_call"),
+    stopReason,
+    usage,
+    billing,
+    auxiliary: providerMetadata ? { providerMetadata } : undefined,
+    warnings: allWarnings.length > 0 ? allWarnings : undefined,
+    backend: {
+      requestId: responseId,
+      rawResponseId,
+      adapter: backend.kind,
+      isSyntheticStream: true,
+    },
+  };
+
+  yield factory.responseCompleted(response);
+}
+
+// ── Item 事件发射 ─────────────────────────────────────────────
+
+function* emitItemEvents(item: OutputItem, factory: ReturnType<typeof createEventFactory>): Generator<AIStreamEvent> {
+  switch (item.type) {
+    case "message":
+      yield* emitMessageEvents(item, factory);
+      break;
+    case "reasoning":
+      yield* emitReasoningEvents(item, factory);
+      break;
+    case "tool_call":
+      yield* emitToolCallEvents(item, factory);
+      break;
+    case "opaque":
+      // Opaque items in output have no streaming events
+      break;
+  }
+}
+
+function* emitMessageEvents(
+  item: MessageItem,
+  factory: ReturnType<typeof createEventFactory>,
+): Generator<AIStreamEvent> {
+  const id = item.id ?? `syn-msg-${crypto.randomUUID()}`;
+  yield factory.messageStarted(id);
+
+  for (const block of item.content) {
+    if (block.type === "text") {
+      yield factory.messageDelta(id, block.text);
+    }
+  }
+
+  yield factory.messageCompleted(item);
+}
+
+function* emitReasoningEvents(
+  item: ReasoningItem,
+  factory: ReturnType<typeof createEventFactory>,
+): Generator<AIStreamEvent> {
+  const id = item.id ?? `syn-reason-${crypto.randomUUID()}`;
+  yield factory.reasoningStarted(id, item.visibility);
+
+  for (const block of item.content) {
+    if (block.type === "text") {
+      yield factory.reasoningDelta(id, block);
+    }
+  }
+
+  yield factory.reasoningCompleted(item);
+}
+
+function* emitToolCallEvents(
+  item: ToolCallItem,
+  factory: ReturnType<typeof createEventFactory>,
+): Generator<AIStreamEvent> {
+  yield factory.toolCallStarted(item.id, item.name);
+
+  if (item.argumentsText) {
+    yield factory.toolCallDelta(item.id, { argumentsText: item.argumentsText });
+  }
+
+  yield factory.toolCallCompleted(item);
+}
+
+// ── Helper ────────────────────────────────────────────────────

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * nano-ai — 统一流式 AI 客户端
+ *
+ * 对外只暴露一个 canonical 主入口：client.stream()
+ */
+
+// Re-export all canonical types
+export * from "./types/index.js";
+
+// Re-export core client API
+export * from "./core/index.js";
+
+// Re-export adapters
+export * from "./adapters/index.js";
+
+// Re-export helpers
+export * from "./helpers/index.js";