@codehz/ai 0.1.0

package/src/core/validation.ts

@@ -0,0 +1,341 @@
+/**
+ * 请求校验
+ *
+ * 在请求进入 adapter 前对参数合法性做基础检查。
+ * 校验失败时抛 AIRequestError。
+ */
+
+import type { AIRequest } from "../types/index.js";
+import { AIRequestError } from "./errors.js";
+
+export type ValidationIssue = {
+  field: string;
+  code: string;
+  message: string;
+};
+
+const MESSAGE_ROLES = new Set(["user", "assistant", "system", "developer"]);
+const REASONING_VISIBILITIES = new Set(["full", "summary", "redacted", "opaque"]);
+const TOOL_RESULT_OUTCOMES = new Set(["success", "error", "rejected"]);
+const INCLUDE_MODES = new Set(["off", "best_effort"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function pushIssue(issues: ValidationIssue[], field: string, code: string, message: string): void {
+  issues.push({ field, code, message });
+}
+
+function validateContentBlock(block: unknown, field: string, issues: ValidationIssue[]): void {
+  if (!isRecord(block) || typeof block.type !== "string") {
+    pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field} must be a valid ContentBlock`);
+    return;
+  }
+
+  switch (block.type) {
+    case "text":
+      if (typeof block.text !== "string") {
+        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.text must be a string`);
+      }
+      return;
+    case "json":
+      if (!("json" in block)) {
+        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.json must be present`);
+      }
+      return;
+    case "image":
+      if (typeof block.imageUrl !== "string" || block.imageUrl.length === 0) {
+        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.imageUrl must be a non-empty string`);
+      }
+      return;
+    case "binary_ref":
+      if (typeof block.ref !== "string" || block.ref.length === 0) {
+        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.ref must be a non-empty string`);
+      }
+      return;
+    case "opaque":
+      if (!("payload" in block)) {
+        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.payload must be present`);
+      }
+      return;
+    default:
+      pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.type "${block.type}" is not supported`);
+  }
+}
+
+function validateContentArray(content: unknown, field: string, issues: ValidationIssue[], code: string): void {
+  if (!Array.isArray(content)) {
+    pushIssue(issues, field, code, `${field} must be a ContentBlock[]`);
+    return;
+  }
+
+  for (let i = 0; i < content.length; i++) {
+    validateContentBlock(content[i], `${field}[${i}]`, issues);
+  }
+}
+
+function validateInputItem(item: unknown, field: string, issues: ValidationIssue[]): void {
+  if (!isRecord(item)) {
+    pushIssue(issues, field, "INPUT_INVALID_ITEM", `${field} must be a valid InputItem`);
+    return;
+  }
+
+  if (typeof item.type !== "string") {
+    pushIssue(issues, field, "INPUT_ITEM_UNKNOWN_TYPE", `${field}.type must be a supported InputItem type`);
+    return;
+  }
+
+  switch (item.type) {
+    case "message":
+      if (typeof item.role !== "string" || !MESSAGE_ROLES.has(item.role)) {
+        pushIssue(issues, `${field}.role`, "MESSAGE_ROLE_INVALID", `${field}.role must be a valid message role`);
+      }
+      validateContentArray(item.content, `${field}.content`, issues, "MESSAGE_CONTENT_INVALID");
+      return;
+    case "reasoning":
+      if (typeof item.visibility !== "string" || !REASONING_VISIBILITIES.has(item.visibility)) {
+        pushIssue(
+          issues,
+          `${field}.visibility`,
+          "REASONING_VISIBILITY_INVALID",
+          `${field}.visibility must be a valid reasoning visibility`,
+        );
+      }
+      validateContentArray(item.content, `${field}.content`, issues, "REASONING_CONTENT_INVALID");
+      return;
+    case "tool_call":
+      if (typeof item.id !== "string" || item.id.length === 0) {
+        pushIssue(issues, `${field}.id`, "TOOL_CALL_ID_INVALID", `${field}.id must be a non-empty string`);
+      }
+      if (typeof item.name !== "string" || item.name.length === 0) {
+        pushIssue(issues, `${field}.name`, "TOOL_CALL_NAME_INVALID", `${field}.name must be a non-empty string`);
+      }
+      if (typeof item.argumentsText !== "string") {
+        pushIssue(
+          issues,
+          `${field}.argumentsText`,
+          "TOOL_CALL_ARGUMENTS_INVALID",
+          `${field}.argumentsText must be a string`,
+        );
+      }
+      return;
+    case "tool_result":
+      if (typeof item.callId !== "string" || item.callId.length === 0) {
+        pushIssue(issues, `${field}.callId`, "TOOL_RESULT_CALL_ID_INVALID", `${field}.callId must be a non-empty string`);
+      }
+      if (typeof item.toolName !== "string" || item.toolName.length === 0) {
+        pushIssue(issues, `${field}.toolName`, "TOOL_RESULT_NAME_INVALID", `${field}.toolName must be a non-empty string`);
+      }
+      if (typeof item.outcome !== "string" || !TOOL_RESULT_OUTCOMES.has(item.outcome)) {
+        pushIssue(
+          issues,
+          `${field}.outcome`,
+          "TOOL_RESULT_OUTCOME_INVALID",
+          `${field}.outcome must be success, error, or rejected`,
+        );
+      }
+      validateContentArray(item.content, `${field}.content`, issues, "TOOL_RESULT_CONTENT_INVALID");
+      return;
+    case "opaque":
+      if (typeof item.source !== "string" || item.source.length === 0) {
+        pushIssue(issues, `${field}.source`, "OPAQUE_SOURCE_INVALID", `${field}.source must be a non-empty string`);
+      }
+      if (typeof item.purpose !== "string" || item.purpose.length === 0) {
+        pushIssue(issues, `${field}.purpose`, "OPAQUE_PURPOSE_INVALID", `${field}.purpose must be a non-empty string`);
+      }
+      return;
+    default:
+      pushIssue(issues, `${field}.type`, "INPUT_ITEM_UNKNOWN_TYPE", `${field}.type "${item.type}" is not supported`);
+  }
+}
+
+function validateTools(tools: unknown, issues: ValidationIssue[]): void {
+  if (tools === undefined) return;
+  if (!Array.isArray(tools)) {
+    pushIssue(issues, "tools", "TOOLS_INVALID", "tools must be an array");
+    return;
+  }
+
+  const seenNames = new Set<string>();
+  for (let i = 0; i < tools.length; i++) {
+    const tool = tools[i];
+    const field = `tools[${i}]`;
+    if (!isRecord(tool)) {
+      pushIssue(issues, field, "TOOL_INVALID", `${field} must be a valid ToolDefinition`);
+      continue;
+    }
+
+    if (typeof tool.name !== "string" || tool.name.length === 0) {
+      pushIssue(issues, `${field}.name`, "TOOL_NAME_INVALID", `${field}.name must be a non-empty string`);
+    } else {
+      if (seenNames.has(tool.name)) {
+        pushIssue(issues, `${field}.name`, "TOOLS_DUPLICATE_NAME", `tool name "${tool.name}" is duplicated`);
+      }
+      seenNames.add(tool.name);
+    }
+
+    if (tool.description !== undefined && typeof tool.description !== "string") {
+      pushIssue(issues, `${field}.description`, "TOOL_DESCRIPTION_INVALID", `${field}.description must be a string`);
+    }
+
+    if (!isRecord(tool.inputSchema)) {
+      pushIssue(
+        issues,
+        `${field}.inputSchema`,
+        "TOOL_INPUT_SCHEMA_INVALID",
+        `${field}.inputSchema must be an object`,
+      );
+    }
+  }
+}
+
+function validateToolChoice(toolChoice: unknown, issues: ValidationIssue[]): void {
+  if (toolChoice === undefined) return;
+  if (toolChoice === "auto" || toolChoice === "none") return;
+  if (!isRecord(toolChoice) || toolChoice.type !== "tool" || typeof toolChoice.name !== "string" || toolChoice.name.length === 0) {
+    pushIssue(issues, "toolChoice", "TOOL_CHOICE_INVALID", "toolChoice must be auto, none, or { type: \"tool\", name }");
+  }
+}
+
+/**
+ * 校验 AIRequest，返回校验问题列表。
+ * 空数组表示无问题。
+ */
+export function validateRequest(request: AIRequest): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (request.instructions !== undefined) {
+    if (typeof request.instructions === "string") {
+      // no-op
+    } else if (Array.isArray(request.instructions)) {
+      validateContentArray(request.instructions, "instructions", issues, "INSTRUCTIONS_INVALID");
+    } else {
+      pushIssue(
+        issues,
+        "instructions",
+        "INSTRUCTIONS_INVALID",
+        "instructions must be a string or ContentBlock[]",
+      );
+    }
+  }
+
+  // input 非空约束
+  if (!Array.isArray(request.input) || request.input.length === 0) {
+    pushIssue(issues, "input", "INPUT_EMPTY", "input must be a non-empty array");
+  }
+
+  // input 元素类型检查
+  if (Array.isArray(request.input)) {
+    for (let i = 0; i < request.input.length; i++) {
+      validateInputItem(request.input[i], `input[${i}]`, issues);
+    }
+  }
+
+  // temperature 范围
+  if (request.temperature !== undefined) {
+    if (typeof request.temperature !== "number" || isNaN(request.temperature)) {
+      issues.push({
+        field: "temperature",
+        code: "TEMPERATURE_NOT_NUMBER",
+        message: "temperature must be a number",
+      });
+    } else if (request.temperature < 0 || request.temperature > 2) {
+      issues.push({
+        field: "temperature",
+        code: "TEMPERATURE_OUT_OF_RANGE",
+        message: "temperature must be between 0 and 2",
+      });
+    }
+  }
+
+  // maxOutputTokens 合法性
+  if (request.maxOutputTokens !== undefined) {
+    if (typeof request.maxOutputTokens !== "number" || isNaN(request.maxOutputTokens)) {
+      issues.push({
+        field: "maxOutputTokens",
+        code: "MAX_OUTPUT_TOKENS_NOT_NUMBER",
+        message: "maxOutputTokens must be a number",
+      });
+    } else if (!Number.isInteger(request.maxOutputTokens) || request.maxOutputTokens < 1) {
+      issues.push({
+        field: "maxOutputTokens",
+        code: "MAX_OUTPUT_TOKENS_INVALID",
+        message: "maxOutputTokens must be a positive integer",
+      });
+    }
+  }
+
+  if (request.include !== undefined) {
+    if (!isRecord(request.include)) {
+      pushIssue(issues, "include", "INCLUDE_INVALID", "include must be an object");
+    } else {
+      if (request.include.usage !== undefined && !INCLUDE_MODES.has(request.include.usage)) {
+        pushIssue(issues, "include.usage", "INCLUDE_USAGE_INVALID", "include.usage must be off or best_effort");
+      }
+      if (request.include.billing !== undefined && !INCLUDE_MODES.has(request.include.billing)) {
+        pushIssue(issues, "include.billing", "INCLUDE_BILLING_INVALID", "include.billing must be off or best_effort");
+      }
+      if (request.include.providerMetadata !== undefined && !INCLUDE_MODES.has(request.include.providerMetadata)) {
+        pushIssue(
+          issues,
+          "include.providerMetadata",
+          "INCLUDE_PROVIDER_METADATA_INVALID",
+          "include.providerMetadata must be off or best_effort",
+        );
+      }
+    }
+  }
+
+  if (request.metadata !== undefined) {
+    if (!isRecord(request.metadata)) {
+      pushIssue(issues, "metadata", "METADATA_INVALID", "metadata must be an object");
+    } else {
+      for (const [key, value] of Object.entries(request.metadata)) {
+        if (typeof value !== "string") {
+          pushIssue(issues, `metadata.${key}`, "METADATA_VALUE_INVALID", `metadata.${key} must be a string`);
+        }
+      }
+    }
+  }
+
+  validateTools(request.tools, issues);
+  validateToolChoice(request.toolChoice, issues);
+
+  // toolChoice 与 tools 的一致性
+  if (
+    request.toolChoice &&
+    typeof request.toolChoice === "object" &&
+    "type" in request.toolChoice &&
+    request.toolChoice.type === "tool"
+  ) {
+    const chosenName = request.toolChoice.name;
+    if (!request.tools || request.tools.length === 0) {
+      issues.push({
+        field: "toolChoice",
+        code: "TOOL_CHOICE_NO_TOOLS",
+        message: `toolChoice specifies tool "${chosenName}" but no tools are defined`,
+      });
+    } else if (!request.tools.some((t) => t.name === chosenName)) {
+      issues.push({
+        field: "toolChoice",
+        code: "TOOL_CHOICE_UNKNOWN_TOOL",
+        message: `toolChoice specifies tool "${chosenName}" which is not in tools array`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * 校验请求并抛出首个问题。
+ * 适用于客户端入口的快速失败检查。
+ */
+export function assertValidRequest(request: AIRequest): void {
+  const issues = validateRequest(request);
+  const first = issues[0];
+  if (first) {
+    throw new AIRequestError(first.message, first.code);
+  }
+}

package/src/helpers/adapter-auxiliary.ts

@@ -0,0 +1,181 @@
+import { WarningCode } from "../core/errors.js";
+import type { EventFactory } from "../core/event-factory.js";
+import type {
+  AdapterCapabilities,
+  AIStreamEvent,
+  BillingInfo,
+  NormalizedRequest,
+  Usage,
+  AuxiliaryInfo,
+  BackendTrace,
+} from "../types/index.js";
+import { AuxiliaryCollector, type BillingSource, type LookupResult, type UsageSource } from "./auxiliary-collector.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type BillingPostprocessHook = (context: {
+  request: NormalizedRequest;
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  capabilities: AdapterCapabilities;
+}) => MaybePromise<Partial<BillingInfo> | undefined>;
+
+export type AuxiliaryFinalizeOptions = {
+  lookup?: () => Promise<LookupResult>;
+  lookupTimeoutMs?: number;
+  postprocessBilling?: BillingPostprocessHook;
+  postprocessBillingSource?: BillingSource;
+};
+
+export type AuxiliaryFinalizeResult = {
+  events: AIStreamEvent[];
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  warnings?: string[];
+  metadataSources?: string[];
+};
+
+export class AdapterAuxiliaryState {
+  private readonly collector = new AuxiliaryCollector();
+  private readonly metadataSources = new Set<string>();
+
+  constructor(
+    private readonly request: NormalizedRequest,
+    private readonly capabilities: AdapterCapabilities,
+  ) {}
+
+  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): void {
+    if (this.request.include?.usage === "off" || isEmptyRecord(usage)) return;
+    this.collector.recordUsage(usage, source, raw);
+  }
+
+  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): void {
+    if (this.request.include?.billing === "off" || isEmptyRecord(billing)) return;
+    this.collector.recordBilling(billing, source, raw);
+  }
+
+  recordProviderMetadata(source: string, metadata: Record<string, unknown> | undefined): void {
+    if (this.request.include?.providerMetadata === "off" || !metadata || isEmptyRecord(metadata)) return;
+    this.collector.recordMetadata(metadata);
+    this.metadataSources.add(source);
+  }
+
+  async finalize(factory: EventFactory, options: AuxiliaryFinalizeOptions = {}): Promise<AuxiliaryFinalizeResult> {
+    if (options.lookup && this.shouldAttemptLookup()) {
+      await this.collector.tryLookup(options.lookup, options.lookupTimeoutMs);
+    }
+
+    if (this.request.include?.billing !== "off" && options.postprocessBilling) {
+      const snapshot = this.collector.build();
+      if (!snapshot.billing) {
+        const derived = await options.postprocessBilling({
+          request: this.request,
+          usage: snapshot.usage,
+          billing: snapshot.billing,
+          auxiliary: snapshot.auxiliary,
+          capabilities: this.capabilities,
+        });
+        if (derived && !isEmptyRecord(derived)) {
+          this.collector.recordBilling(
+            {
+              ...derived,
+              isEstimated: derived.isEstimated ?? true,
+              source: derived.source ?? "derived",
+            },
+            options.postprocessBillingSource ?? "derived",
+            derived,
+          );
+        }
+      }
+    }
+
+    const built = this.collector.build();
+    const events: AIStreamEvent[] = [];
+
+    if (built.usage || built.billing || built.auxiliary) {
+      events.push(
+        factory.responseAuxiliary({
+          usage: built.usage,
+          billing: built.billing,
+          auxiliary: built.auxiliary,
+        }),
+      );
+    }
+
+    if (this.request.include?.usage !== "off" && !built.usage) {
+      events.push(factory.responseWarning("Usage information was not provided by the provider", WarningCode.USAGE_MISSING));
+    }
+
+    if (this.request.include?.billing !== "off") {
+      if (!built.billing) {
+        events.push(
+          factory.responseWarning("Billing information was not provided by the provider", WarningCode.BILLING_MISSING),
+        );
+      } else if (built.billing.isEstimated) {
+        events.push(factory.responseWarning("Billing amount is an estimate", WarningCode.BILLING_ESTIMATED));
+      }
+    }
+
+    return {
+      events,
+      usage: built.usage,
+      billing: built.billing,
+      auxiliary: built.auxiliary,
+      warnings: built.warnings,
+      metadataSources: this.metadataSources.size > 0 ? [...this.metadataSources] : undefined,
+    };
+  }
+
+  private shouldAttemptLookup(): boolean {
+    if (
+      this.request.include?.usage === "off" &&
+      this.request.include?.billing === "off" &&
+      this.request.include?.providerMetadata === "off"
+    ) {
+      return false;
+    }
+
+    const snapshot = this.collector.build();
+    return (
+      (this.request.include?.usage !== "off" && !snapshot.usage) ||
+      (this.request.include?.billing !== "off" && !snapshot.billing) ||
+      (this.request.include?.providerMetadata !== "off" && !snapshot.auxiliary?.providerMetadata)
+    );
+  }
+}
+
+export function emitMalformedStreamWarning(
+  factory: EventFactory,
+  options: {
+    count: number;
+    providerLabel: string;
+    transportLabel: string;
+  },
+): AIStreamEvent | undefined {
+  if (options.count < 1) return undefined;
+  return factory.responseWarning(
+    `Skipped ${options.count} malformed ${options.providerLabel} ${options.transportLabel}`,
+    "STREAM_ERROR",
+  );
+}
+
+export function metadataSourceList(
+  ...groups: Array<Array<NonNullable<BackendTrace["metadataSources"]>[number]> | undefined>
+): string[] | undefined {
+  const sources = new Set<string>();
+
+  for (const group of groups) {
+    if (!group) continue;
+    for (const source of group) {
+      sources.add(source);
+    }
+  }
+
+  return sources.size > 0 ? [...sources] : undefined;
+}
+
+function isEmptyRecord(value: object): boolean {
+  return Object.keys(value).length === 0;
+}

package/src/helpers/adapter-base.ts

@@ -0,0 +1,184 @@
+/**
+ * Adapter 抽象基类
+ *
+ * 约定 adapter 的内部职责分层（build / invoke / parse / emit）：
+ * 1. buildRequest    — 将 NormalizedRequest 转换为 provider 请求格式
+ * 2. invokeProvider  — 调用 provider API
+ * 3. parseResponse   — 解析 provider 响应为 canonical 中间态
+ * 4. emitEvents      — 产出 canonical 事件流
+ *
+ * 子类实现 buildRequest() 和 runStream()，
+ * runStream 返回 AsyncIterable，事件实时发射给消费者。
+ */
+
+import type {
+  NormalizedRequest,
+  BackendAdapter,
+  AdapterCapabilities,
+  AIStreamEvent,
+  AIResponse,
+  AuxiliaryInfo,
+  OutputItem,
+  ReplayItem,
+  StopReason,
+  Usage,
+  BillingInfo,
+  ToolCallItem,
+} from "../types/index.js";
+import { createEventFactory } from "../core/event-factory.js";
+import { AIMappingError, AIRequestError, AIStreamError } from "../core/errors.js";
+import type { EventFactory } from "../core/event-factory.js";
+import { extractText } from "./mapping.js";
+import { AdapterAuxiliaryState } from "./adapter-auxiliary.js";
+
+// ── Adapter 解析中间结果 ──────────────────────────────────────
+
+export type ProviderResponse = unknown;
+
+/**
+ * adapter 完成一轮处理后返回的最终结果。
+ * 用于 buildResponse() 构建 AIResponse。
+ */
+export type StreamResult = {
+  output: OutputItem[];
+  replay: ReplayItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  providerMetadata?: Record<string, unknown>;
+  auxiliary?: Partial<AuxiliaryInfo>;
+  warnings?: string[];
+  metadataSources?: string[];
+  rawResponseId?: string;
+};
+
+// ── 抽象基类 ──────────────────────────────────────────────────
+
+export abstract class AdapterBase implements BackendAdapter {
+  abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  abstract readonly capabilities: AdapterCapabilities;
+
+  /**
+   * stream 模板方法：
+   * 1. 创建事件工厂，发射 response.started
+   * 2. 构建 provider 请求
+   * 3. 委托 runStream 发射全部流事件（含 response.completed）
+   */
+  async *stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent> {
+    const factory = createEventFactory({
+      responseId: request.requestId,
+      backend: { kind: this.kind, isSynthetic: !this.capabilities.nativeStreaming },
+    });
+
+    yield factory.responseStarted(request.model);
+
+    try {
+      const providerRequest = await this.buildRequest(request);
+      yield* this.runStream(providerRequest, factory, request);
+    } catch (err) {
+      if (err instanceof AIRequestError || err instanceof AIStreamError || err instanceof AIMappingError) {
+        throw err;
+      }
+      yield factory.responseWarning(err instanceof Error ? err.message : String(err), "PROVIDER_ERROR");
+      yield factory.responseCompleted(this.buildResponse(request, { output: [], replay: [] }, factory));
+    }
+  }
+
+  // ── 子类必须实现 ──────────────────────────────────────────
+
+  /** 将 NormalizedRequest 转换为 provider 请求格式。 */
+  protected abstract buildRequest(request: NormalizedRequest): ProviderResponse | Promise<ProviderResponse>;
+
+  /**
+   * 执行流式请求，发射全部事件（含 response.completed）。
+   * 子类负责：
+   * - 调用 provider
+   * - 解析每个 chunk
+   * - 通过 factory 发射 item 事件
+   * - 构建 StreamResult
+   * - 发射 factory.responseCompleted(buildResponse(…))
+   */
+  protected abstract runStream(
+    providerRequest: ProviderResponse,
+    factory: EventFactory,
+    request: NormalizedRequest,
+  ): AsyncIterable<AIStreamEvent>;
+
+  // ── 共享构造方法 ──────────────────────────────────────────
+
+  /**
+   * 从 StreamResult 构建完整 AIResponse。
+   * 子类可在返回前自定义覆盖。
+   */
+  protected buildResponse(request: NormalizedRequest, result: StreamResult, _factory: EventFactory): AIResponse {
+    const text = this.extractText(result.output);
+    const warnings = mergeWarnings(result.warnings, _factory.warnings);
+    const auxiliary = mergeAuxiliary(result.auxiliary, result.providerMetadata ? { providerMetadata: result.providerMetadata } : undefined);
+
+    return {
+      id: request.requestId,
+      output: result.output,
+      replay: result.replay,
+      text,
+      toolCalls: result.output.filter((item): item is ToolCallItem => item.type === "tool_call"),
+      stopReason: result.stopReason,
+      usage: result.usage,
+      billing: result.billing,
+      auxiliary,
+      warnings,
+      backend: {
+        requestId: request.requestId,
+        rawResponseId: result.rawResponseId,
+        adapter: this.kind,
+        isSyntheticStream: !this.capabilities.nativeStreaming,
+        metadataSources: result.metadataSources,
+        warnings,
+      },
+    };
+  }
+
+  /** 从 output items 中提取文本内容。 */
+  protected extractText(output: OutputItem[]): string {
+    return extractText(output);
+  }
+
+  protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState {
+    return new AdapterAuxiliaryState(request, this.capabilities);
+  }
+}
+
+function mergeAuxiliary(
+  base?: Partial<AuxiliaryInfo>,
+  patch?: Partial<AuxiliaryInfo>,
+): AuxiliaryInfo | undefined {
+  if (!base && !patch) return undefined;
+
+  const merged: AuxiliaryInfo = {
+    ...(base ?? {}),
+    ...(patch ?? {}),
+  };
+
+  if (base?.providerMetadata || patch?.providerMetadata) {
+    merged.providerMetadata = {
+      ...(base?.providerMetadata ?? {}),
+      ...(patch?.providerMetadata ?? {}),
+    };
+  }
+
+  return merged;
+}
+
+function mergeWarnings(...groups: Array<string[] | undefined>): string[] | undefined {
+  const merged: string[] = [];
+
+  for (const group of groups) {
+    if (!group) continue;
+    for (const warning of group) {
+      if (!merged.includes(warning)) {
+        merged.push(warning);
+      }
+    }
+  }
+
+  return merged.length > 0 ? merged : undefined;
+}