@qjp88995/provider-client 0.0.0-stage → 0.1.1

package/src/model-handle.ts

@@ -0,0 +1,197 @@
+import type { LanguageModel } from 'ai';
+
+import { ProviderClientError } from './errors.js';
+import {
+  type CatalogModel,
+  type CatalogVendor,
+  type LlmCapability,
+  type LlmProtocol,
+  type ModelPricing,
+  REASONING_EFFORTS,
+  type ReasoningEffort,
+} from './types.js';
+import {
+  findVendorAdapter,
+  type LlmVendorAdapter,
+  type ProviderOptions,
+  type SamplingParams,
+  type VendorFetch,
+  type VendorFileStore,
+} from './vendors/index.js';
+
+/** 指向一个模型：厂商 slug + 厂商侧的模型名。 */
+export interface ModelRef {
+  vendor: string;
+  modelId: string;
+}
+
+export interface ResolveOptions {
+  /**
+   * 推理档位（`REASONING_EFFORTS`）。省略或不认识的值 = **什么都不发**（不是关闭）；非推理模型也什么都不发
+   * ——给不会推理的模型发关闭指令有 400 风险。是 `string` 不是 `ReasoningEffort`：调用方的配置常是裸字符串，
+   * 不认识时不替它猜档位。
+   */
+  reasoningEffort?: string;
+  /** 会话 id。中心据此把同一会话固定在同一把 key 上（前缀缓存、厂商侧文件与状态都绑账号）。直连模式忽略。 */
+  affinity?: string;
+  /**
+   * 钉住某把 key（上传文件时 `fileStore.upload` 回的 `credentialRef`）。那把 key 不可用时请求报
+   * `pinned_credential_unavailable`，不切换——调用方重新上传后不带 pin 重试。直连模式忽略。
+   */
+  pin?: string;
+}
+
+/** 上传结果；`credentialRef` 是中心模式下文件落在哪把 key 的账号上（直连为 null），之后引用它的请求要 pin 这把。 */
+export interface UploadedFile {
+  fileId: string;
+  expiresAt: Date | null;
+  credentialRef: string | null;
+}
+
+export interface ModelFileStore {
+  /** `FilePart.data.reference` 的命名空间 key（跟承载包走，不跟厂商走）。 */
+  referenceKey: string;
+  upload(
+    input: Parameters<VendorFileStore['upload']>[0]
+  ): Promise<UploadedFile>;
+  delete(fileId: string): Promise<void>;
+}
+
+/** 一轮要的全部模型材料，一次解析出来、同源。 */
+export interface ModelHandle {
+  ref: ModelRef;
+  /** `厂商名 / 模型显示名`。 */
+  label: string;
+  model: LanguageModel;
+  /** 实际选中的线协议（按模型声明的顺序取第一个「有端点且适配器已实现」的）。 */
+  protocol: LlmProtocol;
+  /** 推理档位已翻译成这家的参数；可以是 undefined（见 `ResolveOptions.reasoningEffort`）。 */
+  providerOptions: ProviderOptions | undefined;
+  /** 调用方给的档位，原样。 */
+  reasoningEffort: string | undefined;
+  limits: { maxContextTokens: number | null; maxOutputTokens: number | null };
+  capabilities: LlmCapability[];
+  /** 单价（每百万 token）。给接入方自己算用量。 */
+  pricing: ModelPricing | null;
+  /**
+   * 工具调用 `providerMetadata` 里要随 part 落库、重放时放回 `providerOptions` 的命名空间（google 的思考签名）。
+   * 别家为空：它们的 metadata 原样回放会改变请求形状。
+   */
+  replayedMetadataKeys: readonly string[];
+  /** 厂商 Files API；没有为 null（调用方退到公网 URL / base64）。 */
+  fileStore: ModelFileStore | null;
+  /** 剥掉这家不接受的采样参数（Kimi 禁 temperature / top_p，AI SDK 不替我们挡）。不抛，调用方按 `dropped` 记 warn。 */
+  filterSampling(params: SamplingParams): {
+    accepted: SamplingParams;
+    dropped: (keyof SamplingParams)[];
+  };
+}
+
+export interface ModelResolver {
+  /** 解析出一轮要用的句柄。厂商 / 模型不在目录里、协议对不上 → `ProviderClientError`。 */
+  resolve(ref: ModelRef, options?: ResolveOptions): Promise<ModelHandle>;
+  /** 只要能力、不造句柄。模型不在目录里给空数组。 */
+  capabilitiesOf(ref: ModelRef): Promise<LlmCapability[]>;
+}
+
+const EFFORTS = new Set<string>(REASONING_EFFORTS);
+
+export function findModel(
+  vendors: readonly CatalogVendor[],
+  ref: ModelRef
+): { vendor: CatalogVendor; model: CatalogModel } {
+  const vendor = vendors.find(v => v.slug === ref.vendor);
+  if (!vendor) {
+    throw new ProviderClientError(
+      'unknown_vendor',
+      `vendor "${ref.vendor}" is not in the catalog`,
+      null
+    );
+  }
+  const model = vendor.models.find(m => m.modelId === ref.modelId);
+  if (!model) {
+    throw new ProviderClientError(
+      'unknown_model',
+      `model "${ref.modelId}" is not in vendor "${ref.vendor}"`,
+      null
+    );
+  }
+  return { vendor, model };
+}
+
+export function adapterFor(vendor: CatalogVendor): LlmVendorAdapter {
+  const adapter = findVendorAdapter(vendor.kind);
+  if (!adapter) {
+    throw new ProviderClientError(
+      'unsupported_vendor_kind',
+      `this provider-client has no adapter for vendor kind "${vendor.kind}" (vendor "${vendor.slug}"); upgrade the package`,
+      null
+    );
+  }
+  return adapter;
+}
+
+/** 两种模式共用：从目录条目、凭证与出站 fetch 造句柄。 */
+export function buildHandle(input: {
+  ref: ModelRef;
+  vendor: CatalogVendor;
+  model: CatalogModel;
+  apiKey: string;
+  /**
+   * 造出站 fetch。中心模式下 `onCredential` 收到这次实际用的 key；上传文件时每次单独造一个，
+   * 并发的请求互不串（文件落在哪把 key 上要拿准，之后引用它要 pin 这把）。
+   */
+  fetchFor: (onCredential?: (ref: string) => void) => VendorFetch | undefined;
+  reasoningEffort: string | undefined;
+}): ModelHandle {
+  const { ref, vendor, model, reasoningEffort } = input;
+  const adapter = adapterFor(vendor);
+  const { protocol, baseUrl } = adapter.chooseEndpoint(model, vendor.endpoints);
+  const createInput = {
+    protocol,
+    baseUrl,
+    apiKey: input.apiKey,
+    modelId: model.modelId,
+    fetch: input.fetchFor(),
+  };
+  const store = adapter.createFileStore(createInput);
+  return {
+    ref,
+    label: `${vendor.name} / ${model.displayName}`,
+    model: adapter.createModel(createInput),
+    protocol,
+    providerOptions:
+      model.capabilities.includes('reasoning') &&
+      reasoningEffort !== undefined &&
+      EFFORTS.has(reasoningEffort)
+        ? adapter.reasoning(
+            model.modelId,
+            reasoningEffort as ReasoningEffort,
+            protocol
+          )
+        : undefined,
+    reasoningEffort,
+    limits: {
+      maxContextTokens: model.maxContextTokens,
+      maxOutputTokens: model.maxOutputTokens,
+    },
+    capabilities: [...model.capabilities],
+    pricing: model.pricing,
+    replayedMetadataKeys: adapter.replayedMetadataKeys,
+    fileStore: store && {
+      referenceKey: store.referenceKey,
+      async upload(file) {
+        let credentialRef: string | null = null;
+        const once = adapter.createFileStore({
+          ...createInput,
+          fetch: input.fetchFor(ref => (credentialRef = ref)),
+        });
+        if (!once) throw new Error('file store disappeared');
+        const r = await once.upload(file);
+        return { ...r, credentialRef };
+      },
+      delete: fileId => store.delete(fileId),
+    },
+    filterSampling: params => adapter.filterSampling(params),
+  };
+}

package/src/provider-client.ts

@@ -0,0 +1,136 @@
+import { createCenterFetch } from './center-fetch.js';
+import { errorFromResponse, ProviderClientError } from './errors.js';
+import {
+  buildHandle,
+  findModel,
+  type ModelHandle,
+  type ModelRef,
+  type ModelResolver,
+  type ResolveOptions,
+} from './model-handle.js';
+import { type CatalogResponse, PC_HEADERS } from './types.js';
+import type { VendorFetch } from './vendors/index.js';
+
+export interface ProviderClientOptions {
+  /** 中心的根地址，如 `https://provider.example.com`。 */
+  centerUrl: string;
+  /** 接入方 API key（`pc_…`）。 */
+  apiKey: string;
+  /**
+   * 目录在这段时间内直接用缓存、不去中心复核（毫秒，默认 60 秒）。过期后带 `If-None-Match` 复核，
+   * 没变只回 304。中心改了目录最多这么久才被看到。
+   */
+  catalogTtlMs?: number;
+  /** 目录请求的超时（毫秒，默认 10 秒）。透传请求不受它管（流式回答可以很长）。 */
+  timeoutMs?: number;
+  /** 发往中心用的 fetch（测试替身、自定义代理）；默认全局 fetch。 */
+  fetch?: VendorFetch;
+}
+
+/**
+ * 中心模式：模型目录从中心拉，所有厂商请求经中心透传（中心换上真 key、坏了自动换下一把）。
+ * 本进程从头到尾不碰厂商 key。
+ */
+export class ProviderClient implements ModelResolver {
+  private readonly center: string;
+  private readonly send: VendorFetch;
+  private readonly ttlMs: number;
+  private readonly timeoutMs: number;
+  private cached: {
+    etag: string | null;
+    body: CatalogResponse;
+    checkedAt: number;
+  } | null = null;
+  private inflight: Promise<CatalogResponse> | null = null;
+
+  constructor(private readonly options: ProviderClientOptions) {
+    this.center = options.centerUrl.replace(/\/+$/, '');
+    this.send = options.fetch ?? globalThis.fetch;
+    this.ttlMs = options.catalogTtlMs ?? 60_000;
+    this.timeoutMs = options.timeoutMs ?? 10_000;
+  }
+
+  /** 这个接入方能用的厂商与模型（按白名单过滤过）。 */
+  catalog(): Promise<CatalogResponse> {
+    if (this.cached && Date.now() - this.cached.checkedAt < this.ttlMs) {
+      return Promise.resolve(this.cached.body);
+    }
+    this.inflight ??= this.fetchCatalog().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+
+  /** 丢掉目录缓存（中心改了配置、想立刻看到时）。 */
+  invalidateCatalog(): void {
+    this.cached = null;
+  }
+
+  async resolve(
+    ref: ModelRef,
+    options: ResolveOptions = {}
+  ): Promise<ModelHandle> {
+    const { vendor, model } = findModel((await this.catalog()).vendors, ref);
+    const baseUrls = vendor.endpoints.map(e => e.baseUrl);
+    return buildHandle({
+      ref,
+      vendor,
+      model,
+      // 厂商 SDK 要求有 key 才肯造句柄；它放进的鉴权头会被中心模式 fetch 剥掉。
+      apiKey: 'via-provider-center',
+      fetchFor: onCredential =>
+        createCenterFetch({
+          centerUrl: this.center,
+          apiKey: this.options.apiKey,
+          vendor: vendor.slug,
+          baseUrls,
+          affinity: options.affinity,
+          pin: options.pin,
+          onCredential,
+          fetch: this.send,
+        }),
+      reasoningEffort: options.reasoningEffort,
+    });
+  }
+
+  async capabilitiesOf(ref: ModelRef) {
+    const vendor = (await this.catalog()).vendors.find(
+      v => v.slug === ref.vendor
+    );
+    const model = vendor?.models.find(m => m.modelId === ref.modelId);
+    return model ? [...model.capabilities] : [];
+  }
+
+  private async fetchCatalog(): Promise<CatalogResponse> {
+    const headers: Record<string, string> = {
+      [PC_HEADERS.key]: this.options.apiKey,
+    };
+    if (this.cached?.etag) headers['if-none-match'] = this.cached.etag;
+    let res: Response;
+    try {
+      res = await this.send(`${this.center}/v1/catalog`, {
+        headers,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      throw new ProviderClientError(
+        'network',
+        `provider center unreachable: ${err instanceof Error ? err.message : String(err)}`,
+        null,
+        { cause: err }
+      );
+    }
+    if (res.status === 304 && this.cached) {
+      this.cached.checkedAt = Date.now();
+      return this.cached.body;
+    }
+    if (!res.ok) throw await errorFromResponse(res);
+    const body = (await res.json()) as CatalogResponse;
+    this.cached = {
+      etag: res.headers.get('etag'),
+      body,
+      checkedAt: Date.now(),
+    };
+    return body;
+  }
+}

package/src/to-error.ts

@@ -0,0 +1,39 @@
+import { APICallError, RetryError } from 'ai';
+
+import { parseCenterError, ProviderClientError } from './errors.js';
+import { PC_HEADERS } from './types.js';
+
+/**
+ * 把一次 AI SDK 调用的错误里**中心自己报的**那部分认出来（`no_credential`、`vendor_not_allowed`、
+ * `pinned_credential_unavailable`、`upstream_error` ……），变成 `ProviderClientError`；别的错误（厂商原样回的
+ * 4xx / 5xx、网络、取消）给 null，调用方照旧处理。
+ *
+ * 判据：响应体是中心的 `{ code, message }`，**且没有 `x-pc-credential` 响应头**——中心只在把厂商的响应
+ * 原样回传时才带这个头，厂商自己的错误体碰巧长得像也不会被误认。AI SDK 重试耗尽时包在 `RetryError` 里，
+ * 看它的最后一次。
+ */
+export function toProviderClientError(
+  error: unknown
+): ProviderClientError | null {
+  const last = RetryError.isInstance(error) ? error.lastError : error;
+  if (!APICallError.isInstance(last)) return null;
+  const headers = last.responseHeaders ?? {};
+  const fromVendor = Object.keys(headers).some(
+    k => k.toLowerCase() === PC_HEADERS.credential
+  );
+  if (fromVendor || !last.responseBody) return null;
+  let body: unknown;
+  try {
+    body = JSON.parse(last.responseBody);
+  } catch {
+    return null;
+  }
+  const known = parseCenterError(body);
+  if (!known) return null;
+  return new ProviderClientError(
+    known.code,
+    known.message,
+    last.statusCode ?? null,
+    { cause: error }
+  );
+}

package/src/types.ts

@@ -0,0 +1,126 @@
+/**
+ * 与中心的契约。`@pc/shared` 是私有包发不出去，这里是它的手抄本——`contract.spec.ts` 逐项对照两边，
+ * 服务端改了契约这里当场红。
+ */
+
+/** 线协议（wire 上的请求 / 响应格式）。 */
+export const LLM_PROTOCOLS = [
+  'openai-chat-completions',
+  'openai-responses',
+  'anthropic-messages',
+  'google-generate-content',
+  'google-interactions',
+] as const;
+export type LlmProtocol = (typeof LLM_PROTOCOLS)[number];
+
+/** 模型能力（目录元数据：发不发图片 / 开不开推理由调用方据此决定）。 */
+export const LLM_CAPABILITIES = ['vision', 'video', 'reasoning'] as const;
+export type LlmCapability = (typeof LLM_CAPABILITIES)[number];
+
+/** 厂商类型。一种类型对应一个适配器（`VENDOR_ADAPTERS`）。 */
+export const VENDOR_KINDS = [
+  'openai',
+  'generic',
+  'deepseek',
+  'moonshotai',
+  'alibaba',
+  'zhipu',
+  'volcengine',
+  'minimax',
+  'dots',
+  'google',
+] as const;
+export type VendorKind = (typeof VENDOR_KINDS)[number];
+
+/**
+ * 推理档位——**我们自己的抽象**，不是任何一家的原生枚举，各家适配器的 `reasoning()` 把它翻译成自己的形状：
+ *
+ *   - `off` 发**真正的关闭指令**（deepseek 默认开着推理，「不发」≠ 关闭）；只有厂商根本没有关闭开关时
+ *     （如 kimi-k3）才不发。
+ *   - `minimal` 只有 openai 有，其余家降档 `low`。
+ *   - `max` 是 deepseek 与 kimi-k3 的原生最高档，openai 映射到 `xhigh`。
+ *   - 只有开关没有档位的家（alibaba、kimi-k2.x），非 `off` 一律塌缩成「开」。
+ */
+export const REASONING_EFFORTS = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'max',
+] as const;
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+/** 每百万 token 的单价，十进制字符串（这是钱，别过 `Number`）。给接入方自己算用量用。 */
+export interface ModelPricing {
+  currency: string;
+  input: string;
+  output: string;
+  cacheRead?: string | null;
+  cacheWrite?: string | null;
+}
+
+/** `GET /v1/catalog`：这个接入方能用的厂商、端点、模型。不含任何凭证信息。 */
+export interface CatalogResponse {
+  vendors: CatalogVendor[];
+}
+
+export interface CatalogVendor {
+  /** 透传路由段，也是 `ModelRef.vendor`。 */
+  slug: string;
+  name: string;
+  kind: VendorKind;
+  endpoints: CatalogEndpoint[];
+  models: CatalogModel[];
+}
+
+export interface CatalogEndpoint {
+  protocol: LlmProtocol;
+  baseUrl: string;
+}
+
+export interface CatalogModel {
+  /** 厂商侧的模型名（请求体里的 `model`）。 */
+  modelId: string;
+  displayName: string;
+  capabilities: LlmCapability[];
+  /** 有序：解析时按这个顺序取第一个「有端点且适配器已实现」的协议。 */
+  protocols: LlmProtocol[];
+  maxContextTokens: number | null;
+  maxOutputTokens: number | null;
+  pricing: ModelPricing | null;
+}
+
+/** 中心的错误码（响应体 `{ code, message }`）。 */
+export const CENTER_ERROR_CODES = [
+  'unauthorized',
+  'forbidden',
+  'tenant_disabled',
+  'not_found',
+  'invalid_request',
+  'conflict',
+  'unprocessable',
+  'upstream_error',
+  'admin_unavailable',
+  'vendor_not_allowed',
+  'no_credential',
+  'pinned_credential_unavailable',
+] as const;
+export type CenterErrorCode = (typeof CENTER_ERROR_CODES)[number];
+
+/** 中心的请求头 / 响应头。 */
+export const PC_HEADERS = {
+  /** 接入方 API key（`pc_…`）。 */
+  key: 'x-pc-key',
+  /** 会话粘性键：同一个键在健康的 key 里固定落到同一把。 */
+  affinity: 'x-pc-affinity',
+  /** 钉住某把 key（值是 `credential` 响应头给过的 ref），不可用时报错不切换。 */
+  pin: 'x-pc-pin',
+  /** 响应头：这次实际用的 key（不透明 ref）。 */
+  credential: 'x-pc-credential',
+  /** 响应头：这次换过几次 key。 */
+  switches: 'x-pc-switches',
+} as const;
+
+/** 透传路由前缀：`<中心>/v1/proxy/<厂商 slug>/<厂商 URL 的完整 pathname>`。 */
+export const PROXY_ROUTE_PREFIX = '/v1/proxy';

package/src/vendors/alibaba.adapter.ts

@@ -0,0 +1,101 @@
+import { createAlibaba } from '@ai-sdk/alibaba';
+import type { LanguageModel } from 'ai';
+
+import type { LlmProtocol } from '../types.js';
+import {
+  COMPATIBLE_RESPONSES_OPTIONS,
+  createResponsesModel,
+} from './openai-responses.js';
+import { withReasoningTextResponsesShim } from './responses-reasoning-text-shim.js';
+import {
+  type CreateModelInput,
+  LlmVendorAdapter,
+  type ProviderOptions,
+  type ReasoningEffort,
+  unsupportedProtocol,
+} from './vendor-adapter.js';
+
+/**
+ * 阿里云百炼（DashScope）。两条协议**同一个根** `/compatible-mode/v1`，SDK 各自拼
+ * `/chat/completions` 与 `/responses`（文档 `referenes/alibaba-model.md`；百炼另有
+ * 业务空间专属域名 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`，公共域名
+ * 「现有域名仍可正常使用」，预填公共域名——专属域名要填业务空间 ID，运营自己换）。
+ *
+ * **responses 面的判据来自 2026-08-27 对 `qwen3.8-flash` 的探针**，文档与实况有一处
+ * 出入必须以实况为准：文档示例里流式推理事件写的是 OpenAI 原生的
+ * `response.reasoning_summary_text.delta`，**真机回的是 `response.reasoning_text.delta`
+ * / `.done`（带 `content_index`）**——与 DeepSeek、智谱同一形状，所以同样挂
+ * `withReasoningTextResponsesShim`；而 `output_item.added/done`、`response.completed`
+ * 与非流式响应体里的 reasoning item 用的**是**原生 `summary[{summary_text}]`，垫片
+ * 对已有非空 `summary` 的 item 不动，两种形状在同一条流里各自落到位。SSE 还多发
+ * `id:` 与 `:HTTP_STATUS/200` 两行，SDK 的解析器按规范忽略。
+ */
+export class AlibabaAdapter extends LlmVendorAdapter {
+  readonly kind = 'alibaba' as const;
+
+  override readonly supportedProtocols: readonly LlmProtocol[] = [
+    'openai-chat-completions',
+    'openai-responses',
+  ];
+
+  createModel(input: CreateModelInput): LanguageModel {
+    switch (input.protocol) {
+      case 'openai-chat-completions': {
+        const { baseUrl, apiKey, modelId, fetch } = input;
+        // baseUrl 指 OpenAI 兼容端点（`/compatible-mode/v1`）。该包另有
+        // embedding/video 两条走 DashScope 原生端点的支线（`embeddingBaseURL`/
+        // `videoBaseURL`），本仓只用 languageModel，不配。
+        return createAlibaba({ baseURL: baseUrl, apiKey, fetch })(modelId);
+      }
+      case 'openai-responses':
+        return createResponsesModel(
+          input,
+          withReasoningTextResponsesShim(input.fetch)
+        );
+      default:
+        throw unsupportedProtocol(this, input.protocol);
+    }
+  }
+
+  /**
+   * **chat-completions** 只有开关，没有档位：`alibabaLanguageModelChatOptions` 就
+   * `enableThinking`（布尔）+ `thinkingBudget`（token 数），没有 `reasoningEffort`。
+   * 非 off 的四个档位一律塌缩成"开"——**如实映射，不发明厂商没有的粒度**
+   * （thinking budget 是 token 数，不是档位，替用户拍一个数没有依据）。
+   *
+   * **responses** 只有 `reasoning.effort` 一个开关，厂商原生七档
+   * `none/minimal/low/medium/high/xhigh/max`（默认 `xhigh`；文档：`xhigh`/`max`
+   * 仅北京、新加坡地域）。我们的六档**逐个都有同名原生档**，一律直通、不映射：
+   * `off`→`none` 是真正的关闭指令（探针 `reasoning_tokens: 0`、不出 reasoning
+   * item），`minimal` 与 `max` 各自 200。文档还说 `enable_thinking` 将废弃、
+   * `reasoning.effort` 优先级更高，所以这个面上只发 effort。key 随承载包换成
+   * `openai`，并带 `COMPATIBLE_RESPONSES_OPTIONS`（不带则 SDK 按模型名判成非推理
+   * 模型、`reasoning` 整个不发——它默认 `xhigh`，「不发 ≠ 关闭」在这家也成立；
+   * `developer` 角色实测也收，但只保证 `system`）。代价同 DeepSeek：SDK 在
+   * `forceReasoning` 下剥掉 `temperature`/`top_p`（厂商本身收），记为已知限制。
+   *
+   * 请求侧回传：四种形状（原样 output / 只回 function_call / `item_reference` /
+   * `previous_response_id`）与 `store:false` 全部 200；它**会消费**回传的 reasoning
+   * item（带着回传比不带多出恰好上一轮 reasoning_tokens 的 input_tokens），SDK 默认
+   * 发什么就发什么。
+   */
+  override reasoning(
+    _modelId: string,
+    effort: ReasoningEffort,
+    protocol: LlmProtocol
+  ): ProviderOptions {
+    switch (protocol) {
+      case 'openai-chat-completions':
+        return { alibaba: { enableThinking: effort !== 'off' } };
+      case 'openai-responses':
+        return {
+          openai: {
+            reasoningEffort: effort === 'off' ? 'none' : effort,
+            ...COMPATIBLE_RESPONSES_OPTIONS,
+          },
+        };
+      default:
+        throw unsupportedProtocol(this, protocol);
+    }
+  }
+}

package/src/vendors/ark-responses-shim.ts

@@ -0,0 +1,60 @@
+import type { ResponsesFetch } from './openai-responses.js';
+import { withoutLength } from './responses-reasoning-text-shim.js';
+
+/**
+ * 火山方舟（Ark）Responses 端点的 HTTP 层垫片——**只改响应、只改非流式**。
+ *
+ * 方舟的 Responses 面在推理形状上是 OpenAI 原生的（reasoning item 用
+ * `summary[{summary_text}]`、流式事件是 `response.reasoning_summary_text.delta`，
+ * 2026-09-07 对 `doubao-seed-2-1-pro` / `2-0-lite` 的探针逐字段核对过），所以
+ * **不**用 `withReasoningTextResponsesShim`。它与 OpenAI 唯一会让 SDK 炸的差异是：
+ * 非流式响应体里 `output_text` 内容块**没有 `annotations` 字段**，而
+ * `@ai-sdk/openai` 4.0.46 的非流式 zod schema 把它写成必填数组（dist:4107），
+ * 于是 `generateText` / `generateObject` 一律 `Invalid JSON response`——请求明明
+ * 200、钱也扣了，SDK 却报错。流式路径不受影响：SSE 事件的 schema 里这个字段是
+ * 可选的（真实 SDK 回放过，见 `volcengine.sdk-contract.spec.ts`），所以流式原样透传。
+ *
+ * 请求侧的两处差异（拒收 `reasoning.summary`、拒收 `item_reference`）不在这里
+ * 改：它们由 SDK 的 providerOptions 就能关掉（`reasoningSummary: null` /
+ * `store: false`），改请求体去猜 SDK 内部结构没有必要——见 `volcengine.adapter.ts`。
+ */
+export function withArkResponsesShim(
+  base?: ResponsesFetch
+): NonNullable<ResponsesFetch> {
+  return async (url, init) => {
+    // 延迟到调用时再取全局 fetch：测试用 vi.stubGlobal 换掉的才是这一个。
+    const res = await (base ?? globalThis.fetch)(url, init);
+    if (!res.ok || !res.body) return res;
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) return res;
+    const body: unknown = await res.json();
+    fillOutputTextAnnotations(body);
+    return new Response(JSON.stringify(body), {
+      status: res.status,
+      statusText: res.statusText,
+      headers: withoutLength(res.headers),
+    });
+  };
+}
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * 给 response 对象里每个 `message.content[].output_text` 补上缺失的
+ * `annotations: []`。已有的不动；别的类型的 item / part 不碰。
+ */
+export function fillOutputTextAnnotations(body: unknown): void {
+  if (!isObject(body) || !Array.isArray(body.output)) return;
+  for (const item of body.output) {
+    if (!isObject(item) || item.type !== 'message') continue;
+    if (!Array.isArray(item.content)) continue;
+    for (const part of item.content) {
+      if (!isObject(part) || part.type !== 'output_text') continue;
+      if (part.annotations == null) part.annotations = [];
+    }
+  }
+}