@qjp88995/provider-client 0.0.0-stage → 0.1.0

package/src/vendors/responses-reasoning-text-shim.ts

@@ -0,0 +1,174 @@
+import type { ResponsesFetch } from './openai-responses.js';
+
+/**
+ * 「推理正文走 `reasoning_text`」这一类 Responses 兼容端点的 HTTP 层垫片——把它们
+ * 与 OpenAI 线格式的**三处差异**在响应侧抹平，让 `@ai-sdk/openai` 的 responses
+ * 模型原样可用。首个使用者是 DeepSeek（本文件前身叫 `deepseek-responses-fetch.ts`），
+ * 2026-08-27 智谱探针抓到的事件序列与它**逐字段一致**，于是升成协议级共享件：
+ * 这不是 DeepSeek 的私有怪癖，而是「非 OpenAI 厂商实现 Responses」的通行做法——
+ * 它们回的是推理**正文**而 OpenAI 只回摘要，字段名自然不同。
+ *
+ * 差异（2026-08-27 对 `deepseek-v4-flash` / `glm-5.2` 真机探针，见 providers.md）：
+ *
+ *   1. 推理**正文**以 reasoning item 的 `content: [{type:'reasoning_text'}]` 返回，
+ *      `summary` 恒空——OpenAI 官方只回 `summary`（摘要），SDK 的 item schema
+ *      也只读 `summary`/`encrypted_content`（4.0.46 dist:3603、6790）。
+ *   2. 流式事件是 `response.reasoning_text.delta / .done`；SDK 的 chunk union 里
+ *      **没有**这两个名字（0 命中，GitHub main 亦然），未知事件按 loose schema
+ *      静默丢弃——推理过程在对话页整段消失。
+ *   3. `encrypted_content` 是 `<response_id>-<n>` 形状的不透明串，文档说不支持、
+ *      实际会返回；对我们无害（SDK 原样塞进 providerMetadata）。
+ *
+ * **请求侧刻意不改写**。探针把六种回传形状（原样 item / 只带 encrypted_content /
+ * 假 encrypted_content / 假 id / 无 id / `item_reference`）全部打过一遍：全部
+ * 200，且 `input_tokens` 分毫不差（多轮 29、工具回环 387）——DeepSeek 根本不消费
+ * 发回去的 reasoning，SDK 默认（`store` 未设＝true）发出的 `item_reference`
+ * 它也照收。没有可走私的东西，也就没有请求侧。
+ *
+ * 映射：`reasoning_text.delta` → `reasoning_summary_text.delta`（`summary_index`
+ * 恒 0——SDK 在 `output_item.added` 时已把第 0 段标成 active，多段 `content_index`
+ * 合并进它就够了，另开段要先发 `summary_part.added`，徒增状态机）；
+ * `reasoning_text.done` → `reasoning_summary_part.done`；`output_item.added/done`、
+ * `response.completed/incomplete/failed` 与非流式响应体里的 reasoning item 一律
+ * `content` → `summary`。`content` 保留不删，SDK schema 会剥。
+ *
+ * 只认 OpenAI 公开的线格式，不碰 SDK 内部结构——SDK 升级不影响它。契约由
+ * `deepseek-responses.sdk-contract.spec.ts` 与 `zhipu.sdk-contract.spec.ts` 用真实
+ * SDK 钉住（后者回放的是带 `event:` 行的原始 SSE——智谱多发这一行，SDK 不看）。
+ */
+export function withReasoningTextResponsesShim(
+  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('text/event-stream')) {
+      return new Response(res.body.pipeThrough(sseRewriter()), {
+        status: res.status,
+        statusText: res.statusText,
+        headers: withoutLength(res.headers),
+      });
+    }
+    if (contentType.includes('application/json')) {
+      const body = (await res.json()) as Record<string, unknown>;
+      rewriteResponseObject(body);
+      return new Response(JSON.stringify(body), {
+        status: res.status,
+        statusText: res.statusText,
+        headers: withoutLength(res.headers),
+      });
+    }
+    return res;
+  };
+}
+
+/** 改写过的 body 长度变了，且已解压；带着原头会让下游按错的长度截断。 */
+export function withoutLength(headers: Headers): Headers {
+  const out = new Headers(headers);
+  out.delete('content-length');
+  out.delete('content-encoding');
+  return out;
+}
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * reasoning item：`content[].reasoning_text` → `summary[].summary_text`。
+ * 已有非空 `summary` 就不动（那是真 OpenAI 形状，别覆盖）。
+ */
+export function rewriteReasoningItem(item: unknown): void {
+  if (!isObject(item) || item.type !== 'reasoning') return;
+  if (Array.isArray(item.summary) && item.summary.length > 0) return;
+  const content = Array.isArray(item.content) ? item.content : [];
+  item.summary = content.flatMap(part =>
+    isObject(part) &&
+    part.type === 'reasoning_text' &&
+    typeof part.text === 'string'
+      ? [{ type: 'summary_text', text: part.text }]
+      : []
+  );
+}
+
+/** 完整的 response 对象（非流式 body，或 `response.completed` 事件里的那份）。 */
+export function rewriteResponseObject(body: unknown): void {
+  if (!isObject(body) || !Array.isArray(body.output)) return;
+  for (const item of body.output) rewriteReasoningItem(item);
+}
+
+/** 一条 SSE 事件对象。返回改写后的对象（可能是同一引用）。 */
+export function rewriteEvent(event: unknown): unknown {
+  if (!isObject(event) || typeof event.type !== 'string') return event;
+  switch (event.type) {
+    case 'response.reasoning_text.delta':
+      return {
+        type: 'response.reasoning_summary_text.delta',
+        item_id: event.item_id,
+        output_index: event.output_index,
+        summary_index: 0,
+        delta: event.delta,
+        sequence_number: event.sequence_number,
+      };
+    case 'response.reasoning_text.done':
+      return {
+        type: 'response.reasoning_summary_part.done',
+        item_id: event.item_id,
+        output_index: event.output_index,
+        summary_index: 0,
+        sequence_number: event.sequence_number,
+      };
+    case 'response.output_item.added':
+    case 'response.output_item.done':
+      rewriteReasoningItem(event.item);
+      return event;
+    case 'response.completed':
+    case 'response.incomplete':
+    case 'response.failed':
+      rewriteResponseObject(event.response);
+      return event;
+    default:
+      return event;
+  }
+}
+
+/**
+ * 按行处理 SSE：只动 `data:` 行且只在它是合法 JSON 时改写，其余字节原样透传。
+ * 半行留在缓冲里等下一块，flush 时把尾巴吐掉。
+ */
+function sseRewriter(): TransformStream<Uint8Array, Uint8Array> {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = '';
+  const rewriteLine = (line: string): string => {
+    if (!line.startsWith('data:')) return line;
+    const payload = line.slice(5).trim();
+    if (!payload || payload === '[DONE]') return line;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      return line;
+    }
+    return `data: ${JSON.stringify(rewriteEvent(parsed))}`;
+  };
+  return new TransformStream({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+      if (lines.length === 0) return;
+      controller.enqueue(
+        encoder.encode(lines.map(rewriteLine).join('\n') + '\n')
+      );
+    },
+    flush(controller) {
+      buffer += decoder.decode();
+      if (buffer) controller.enqueue(encoder.encode(rewriteLine(buffer)));
+    },
+  });
+}

package/src/vendors/vendor-adapter.ts

@@ -0,0 +1,294 @@
+import type { JSONValue, LanguageModel } from 'ai';
+
+import { ProtocolUnavailableError } from '../errors.js';
+import type {
+  LlmCapability,
+  LlmProtocol,
+  ReasoningEffort,
+  VendorKind,
+} from '../types.js';
+
+/**
+ * providerOptions 的形状是 `Record<string, JSONObject>`（@ai-sdk/provider 的
+ * `SharedV3ProviderOptions`，`ai` 包本身不导出这个类型名，只导出组成它的
+ * `JSONValue`——故本地重建一个结构等价的别名）。
+ */
+export type ProviderOptions = Record<string, Record<string, JSONValue>>;
+
+/**
+ * 采样参数支持度。**默认全支持，禁止的家覆盖**——Kimi 全系禁止 temperature/top_p，
+ * 传参直接返回参数非法（见 `referenes/kimi-request.md` 的避坑提示第 1 条），
+ * 而 AI SDK 不会替我们挡（实测 `generateText({temperature})` 原样发出）。
+ */
+export interface SamplingSupport {
+  temperature: boolean;
+  topP: boolean;
+}
+
+/** 调用方给的采样参数；`filterSampling` 按支持度剥。 */
+export interface SamplingParams {
+  temperature?: number;
+  topP?: number;
+}
+
+/**
+ * 档位的 SSOT 在 `types.ts`（`REASONING_EFFORTS`）——这里只 re-export，
+ * 让各子类从同一处 import。**它是严格 union 而非 `string`**：加一个档位时，
+ * 凡是对档位做穷举分支的家会在编译期报错，而不是在真机上撞 vendor 的枚举校验。
+ */
+export type { ReasoningEffort };
+
+/** `createModel` 的入参：一条已选定的 (协议, 端点) + 凭证 + 厂商侧模型名。 */
+export interface CreateModelInput {
+  protocol: LlmProtocol;
+  baseUrl: string;
+  apiKey: string;
+  modelId: string;
+  /**
+   * 出站 fetch：中心模式下是 `createCenterFetch` 造的（改写到中心、换鉴权头），直连模式下是调用方给的
+   * （网络代理）或省略 = 全局 fetch。**这家的每一个出站请求都要用它**：SDK 工厂的 `fetch` 选项、responses 垫片的
+   * base、自己手写的 `fetch`。漏一处不报错，只是那一处悄悄直连——在国内表现成
+   * 超时。`vendors.spec` 逐家逐协议钉着句柄确实用了它。
+   */
+  fetch?: VendorFetch;
+}
+
+/** 厂商出站请求用的 fetch；与全局 `fetch` 同签名。 */
+export type VendorFetch = typeof globalThis.fetch;
+
+/**
+ * 厂商 Files API 的最小面：传一份字节上去、拿回它在厂商侧的 id。
+ *
+ * `referenceKey` 是 `FilePart.data.reference` 里的命名空间 key，**跟承载包走不跟
+ * 厂商走**（同 `reasoning()` 的 `optionsKey`）：DeepSeek 的 chat-completions 由
+ * `@ai-sdk/deepseek` 承载、key 是 `deepseek`；responses 由 `@ai-sdk/openai` 承载、
+ * key 是 `openai`。给错不报错——包解析引用时找不到自己的 key 才抛，那时错误信息
+ * 只说「missing reference」。
+ */
+export interface VendorFileStore {
+  referenceKey: string;
+  upload(input: {
+    data: Uint8Array;
+    mediaType: string;
+    filename?: string;
+    /** 省略 = 厂商默认（DeepSeek 是永久）。 */
+    ttlSeconds?: number;
+  }): Promise<{ fileId: string; expiresAt: Date | null }>;
+  /** 尽力而为的删除；缓存失效时顺手清厂商侧副本。 */
+  delete(fileId: string): Promise<void>;
+}
+
+/** `chooseEndpoint` 看的模型字段：只要协议声明，签名上刻意不带「这一轮要什么」。 */
+export interface EndpointModelView {
+  modelId: string;
+  protocols: string[];
+}
+
+/**
+ * `adviseModel` 看的模型字段。`effectiveProtocol` 是解析链此刻会选的协议
+ * （`chooseEndpoint` 对同一批端点算出来的；调不通时为 null）——提醒要按「实际会
+ * 走哪条」说话，而不是按声明的第一个。
+ */
+export interface AdviceModelView {
+  modelId: string;
+  protocols: readonly LlmProtocol[];
+  capabilities: readonly LlmCapability[];
+  effectiveProtocol: LlmProtocol | null;
+}
+
+/** `chooseEndpoint` 看的端点字段。 */
+export interface EndpointView {
+  protocol: string;
+  baseUrl: string;
+  /** 省略 = 启用（中心目录里只有启用的端点）。 */
+  isActive?: boolean;
+}
+
+/** 配置提醒：`warn` = 照这样配会出错或静默降质，`info` = 值得知道。 */
+export interface ModelAdvice {
+  severity: 'warn' | 'info';
+  message: string;
+}
+
+/**
+ * 一家 LLM **厂商**的全部差异都收在它自己的子类里。
+ *
+ * 前身叫 `LlmProtocolAdapter`，但它的 `protocol` 字段装的一直是厂商标识——真正的
+ * 线协议（openai-chat-completions / openai-responses / anthropic-messages）是另一个
+ * 维度：一家厂商可以同时开多个协议端点（`createDeepSeek()(id)` 走 chat-completions、
+ * `createOpenAI({baseURL}).responses(id)` 走 responses，两者都是 DeepSeek 一家的事）。
+ * `kind` 对应中心的 `vendor.kind`。
+ *
+ * 从 agent-base 搬来时去掉了中心那一侧的事：显示名、接入提示、推荐模型、默认端点（在 `@pc/shared` 的
+ * `VENDOR_KIND_INFOS`）与余额 / 目录接口（在中心 api）。适配器只管「怎么造句柄、怎么翻译推理与采样」。
+ *
+ * 换掉早先那两个"协议无关"纯函数的理由不是代码整洁，是那个形状**在事实层面站不住**：
+ *
+ *   - "接不接受采样参数"是各家自己的规矩（Kimi 禁止 temperature/top_p，DeepSeek 可调）。
+ *   - "怎么开关推理"甚至是**模型级**的：`kimi-k3` 不支持 `thinking` 参数、传入报错，
+ *     只认顶层 `reasoning_effort`；而 `kimi-k2.x` 恰好相反。DeepSeek 各版本对档位的
+ *     支持度也不同（v4-pro 仅 high/max，low 自动映射 high）。
+ *
+ * 所以 `reasoning()` 收 modelId——家内差异真实存在，判据放在各家自己的子类里，
+ * 模型名变了只改那一个文件。**不**给 `llm_model` 加一列让运营选"推理控制方式"：
+ * 那是个技术概念，运营答不上来，答错了还是静默出错。
+ *
+ * 加一家厂商 = 新增一个子类 + 进 `VENDOR_ADAPTERS` 数组 + 中心 `VENDOR_KIND_INFOS` 加一条
+ * （`vendors.spec` 钉着两边的 kind 与 `supportedProtocols` 一致）。
+ */
+export abstract class LlmVendorAdapter {
+  abstract readonly kind: VendorKind;
+
+  /**
+   * 本适配器**已实现**的协议分支。取值域是 `LLM_PROTOCOLS`（外部事实，三种全占），
+   * 但实现是我们的活：模型声明了、厂商端点也有、而这里没写分支的协议，
+   * `chooseEndpoint` 会跳过它而不是让 `createModel` 在造句柄时炸。
+   */
+  readonly supportedProtocols: readonly LlmProtocol[] = [
+    'openai-chat-completions',
+  ];
+
+  /**
+   * 按型号的配置提醒（模型表单实时显示、详情页体检汇总）。默认没有；子类按自己
+   * 探出来的坑写——判据与 `reasoning()` / `chooseEndpoint` 住在同一个文件里，
+   * 改一边就看得见另一边。
+   */
+  adviseModel(_model: AdviceModelView): ModelAdvice[] {
+    return [];
+  }
+
+  /** 造 AI SDK 句柄。 */
+  abstract createModel(input: CreateModelInput): LanguageModel;
+
+  /**
+   * 这家厂商在该 (协议, 端点, 凭证) 下的 Files API。**默认 null = 没有**，图片
+   * 递送层据此退到下一档（公网 URL / base64）。「有没有」由子类有没有覆盖决定，
+   * 不另加布尔字段让两处声明漂移。
+   */
+  createFileStore(_input: CreateModelInput): VendorFileStore | null {
+    return null;
+  }
+
+  readonly sampling: SamplingSupport = { temperature: true, topP: true };
+
+  /**
+   * 工具调用的 `providerMetadata` 里要随 part 落库、重放时原样发回的命名空间。
+   * **默认空 = 一个字节都不存**：别家的 metadata 原样回放会改变请求形状（openai
+   * responses 的 `itemId` 会让 SDK 发 `item_reference`）。只有「不带回去下一步就
+   * 400 / 降质」的家才声明（google 的思考签名）。
+   */
+  readonly replayedMetadataKeys: readonly string[] = [];
+
+  /**
+   * 从该模型支持的协议与厂商的可用端点里选一个。默认实现：按 `model.protocols`
+   * 的顺序取第一个「厂商有活跃端点 且 本适配器已实现」的协议，所以那个数组的
+   * 顺序有语义。各厂商真要接第二个协议时在子类里定自己的策略。
+   *
+   * **入参刻意只有 model 与 endpoints，没有「这一轮要什么能力」**——同一个会话里
+   * 协议必须稳定：按轮次切协议会让请求体形状完全不同（前缀缓存全线 miss，DeepSeek
+   * 命中与未命中差 30 倍），reasoning 的还原路径也不一致。签名上就堵死那种写法。
+   *
+   * 交集为空明确报 422，不静默退回某个协议。
+   */
+  chooseEndpoint(
+    model: EndpointModelView,
+    endpoints: readonly EndpointView[]
+  ): { protocol: LlmProtocol; baseUrl: string } {
+    for (const protocol of model.protocols) {
+      if (!this.supportedProtocols.includes(protocol as LlmProtocol)) continue;
+      const hit = endpoints.find(
+        e => e.isActive !== false && e.protocol === protocol
+      );
+      if (hit)
+        return { protocol: protocol as LlmProtocol, baseUrl: hit.baseUrl };
+    }
+    throw new ProtocolUnavailableError(
+      model.modelId,
+      model.protocols,
+      this.kind
+    );
+  }
+
+  /**
+   * providerOptions 的命名空间 key。默认取 kind——`@ai-sdk/deepseek`、
+   * `@ai-sdk/moonshotai`、`@ai-sdk/alibaba` 都由包内 provider 名首段
+   * （`moonshotai.chat` / `alibaba.chat` …）写死，恰好等于我们的 kind 值。
+   * 唯一的例外是 generic：SDK 3.x 把 openai-compatible 的 key 固定成驼峰
+   * `openaiCompatible`，故那个子类覆盖此 getter。**写错不会报错，只是推理开关
+   * 静默不下发。**
+   */
+  protected get optionsKey(): string {
+    return this.kind;
+  }
+
+  /**
+   * 推理控制。默认实现＝在自己的命名空间下发 `reasoningEffort` 档位字符串，
+   * `off` 不发任何东西（没有统一的关闭语义可发明）。
+   *
+   * 覆盖它的家要记住一条：**`off` 要发的是真正的关闭指令，而不是什么都不发**
+   * ——"不发"会让 provider 落到自己的默认值，而 deepseek 默认开着推理
+   * （已用真实 API 实测，见 `.superpowers/sdd/fix-reasoning-off-report.md`）。
+   * 只有当该家**根本没有关闭开关**时（如 kimi-k3），不发才是如实反映。
+   *
+   * **`protocol` 是必填的**，因为 providerOptions 的命名空间 key 跟着协议走、
+   * 不跟着厂商走：同一家 DeepSeek，chat-completions 由 `@ai-sdk/deepseek` 承载、
+   * key 是 `deepseek`；responses 由 `@ai-sdk/openai` 承载、key 是 `openai`。
+   * 不知道协议就选不对 key，而选错 key 不报错、只是档位静默不下发。resolver
+   * 用 `chooseEndpoint` 算出协议，造句柄与翻译推理用的是同一个结果。
+   */
+  reasoning(
+    _modelId: string,
+    effort: ReasoningEffort,
+    _protocol: LlmProtocol
+  ): ProviderOptions | undefined {
+    if (effort === 'off') return undefined;
+    return { [this.optionsKey]: { reasoningEffort: effort } };
+  }
+
+  /**
+   * 按本家支持度剥掉不能发的采样参数。返回的对象直接展开进 `generateText`/
+   * `generateObject` 的入参。
+   *
+   * 剥掉时**不报错**——调用方很可能只是换了模型，让整个节点失败太重；由调用方
+   * 记一条 warn（它知道自己是谁、在跑哪个节点）。
+   */
+  filterSampling(params: SamplingParams): {
+    accepted: SamplingParams;
+    dropped: (keyof SamplingParams)[];
+  } {
+    const accepted: SamplingParams = {};
+    const dropped: (keyof SamplingParams)[] = [];
+    for (const key of ['temperature', 'topP'] as const) {
+      const value = params[key];
+      if (value === undefined) continue;
+      if (this.sampling[key]) accepted[key] = value;
+      else dropped.push(key);
+    }
+    return { accepted, dropped };
+  }
+}
+
+/**
+ * 没实现某协议分支的家共用的守卫：`chooseEndpoint` 已经把别的协议筛掉，
+ * 这里再钉一道是为了让「有人绕过 chooseEndpoint 直接调 createModel」响亮失败，
+ * 而不是把 responses 的 baseUrl 喂给 chat-completions 的包。放在 `createModel`
+ * 的 `switch` 的 `default` 分支里；`reasoning()` 里也一样用它兜底。
+ */
+export function unsupportedProtocol(
+  adapter: LlmVendorAdapter,
+  protocol: LlmProtocol
+): Error {
+  return new Error(
+    `vendor adapter "${adapter.kind}" has no ${protocol} implementation`
+  );
+}
+
+/** 只实现了 chat-completions 的家在 `createModel` 开头调一下即可。 */
+export function assertChatCompletions(
+  adapter: LlmVendorAdapter,
+  protocol: LlmProtocol
+): void {
+  if (protocol !== 'openai-chat-completions') {
+    throw unsupportedProtocol(adapter, protocol);
+  }
+}

package/src/vendors/volcengine.adapter.ts

@@ -0,0 +1,166 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { type LanguageModel, wrapLanguageModel } from 'ai';
+
+import type { LlmProtocol } from '../types.js';
+import { withArkResponsesShim } from './ark-responses-shim.js';
+import {
+  COMPATIBLE_RESPONSES_OPTIONS,
+  createResponsesModel,
+  responsesDefaultsMiddleware,
+} from './openai-responses.js';
+import {
+  type CreateModelInput,
+  LlmVendorAdapter,
+  type ProviderOptions,
+  type ReasoningEffort,
+  unsupportedProtocol,
+} from './vendor-adapter.js';
+
+/**
+ * 工厂 `name`。决定 provider id（`volcengine.chat`）与 providerOptions 的命名空间
+ * key（单词无连字符，`name` 与 `toCamelCase(name)` 相同），恰好等于 `kind`，
+ * 基类默认的 `optionsKey` 直接可用。
+ */
+const FACTORY_NAME = 'volcengine';
+
+/**
+ * responses 协议下每次调用都必须带上的两项 providerOptions——不带就是 400，
+ * 且**与有没有推理无关**，所以不能只放在 `reasoning()` 里（没标 `reasoning`
+ * 能力的模型行根本不会被问推理选项），而是由 `createModel` 挂的中间件兜底：
+ *
+ *   - **`store: false`**：SDK 在 `store` 为 true（默认）时把上一轮带 itemId 的
+ *     assistant 正文 / reasoning 发成 `{type:'item_reference', id}`，方舟对它回
+ *     400「The parameter `input` … not valid: `<nil>`」——多步工具回环第二步必炸。
+ *     `store:false` 让 SDK 改发完整 item；探针里 `store:false` 本身方舟 200。
+ *   - **`reasoningSummary: null`**：SDK 对推理模型默认附带 `reasoning.summary:
+ *     'detailed'`，方舟回 400「json: unknown field "summary"」。传 null 让 SDK
+ *     整个不发这个键（4.0.46 dist:6491 `!== undefined` 判断）。
+ *
+ * 调用方显式给的同名选项优先（spread 在后）；挂法见 `responsesDefaultsMiddleware`。
+ */
+export const ARK_RESPONSES_DEFAULTS = {
+  store: false,
+  reasoningSummary: null,
+} as const;
+
+/**
+ * 火山引擎方舟（Ark，豆包 Doubao-Seed 系）。
+ *
+ * **AI SDK 没有它的语言模型 provider**：`@ai-sdk/bytedance`（2.0.39，2026-09-02）
+ * 只做 Seedream 图像 / Seedance 视频，`languageModel()` 直接抛 `NoSuchModelError`；
+ * npm 也没有别的官方或社区包。承载包与智谱同一套：chat-completions 走
+ * `@ai-sdk/openai-compatible`（私有的 `thinking` 靠它把未知键展开进请求体，
+ * `reasoning_content` 是它原生读的字段），responses 走 `@ai-sdk/openai`。
+ *
+ * 全部判据来自 2026-09-07 对 `doubao-seed-2-1-pro-260628` / `doubao-seed-2-0-lite-260428`
+ * 的真 key 探针（方舟文档站是纯客户端渲染、抓不到正文；类型定义核对的是
+ * `volcengine-python-sdk` 的 `volcenginesdkarkruntime`）：
+ *
+ *   - 推理开关是**模型无关**的两个参数：`thinking:{type:'enabled'|'disabled'}`
+ *     （`auto` 在 Seed 2.x 上 400「Unsupported thinking type」，永远不发）与
+ *     `reasoning_effort: minimal|low|medium|high`（`minimal` = 不思考；`xhigh`/`max`
+ *     也 200 但不在 SDK 类型里，不赌）。**默认开着推理**（不发任何参数时
+ *     `reasoning_tokens` 1154），「不发 ≠ 关闭」在这家同样成立。
+ *     `thinking:disabled` 与非 minimal 的 effort 同发 → 400「Invalid combination」。
+ *     不按 modelId 分支——方舟的模型 id 可能是接入点 `ep-…`，按名字判什么都判不出来。
+ *   - 响应侧：非流式 `message.reasoning_content` / 流式 `delta.reasoning_content`，
+ *     另有一个 `encrypted_content`（SDK 忽略）。工具回环不要求回传推理；SDK
+ *     （openai-compatible）会把 `reasoning_content` 发回去，方舟收并计费。
+ *   - `temperature` 范围 `[0, 2]`（2.5 → 400），`top_p` 收。
+ *   - `GET /models` 存在，但返回的是**全平台目录**（含 `status: Shutdown` 的死
+ *     模型），不是账号已开通清单；账号未开通的模型调用回 404 `ModelNotOpen`。
+ *   - 余额接口 `QueryBalanceAcct` 走 `open.volcengineapi.com` 的 AK/SK 签名体系，
+ *     不是 Ark API key，中心的凭证模型做不了。
+ *
+ * 只关注文本模型；Seedream / Seedance 归 media-provider，不在这里。
+ */
+export class VolcengineAdapter extends LlmVendorAdapter {
+  readonly kind = 'volcengine' 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;
+        return createOpenAICompatible({
+          name: FACTORY_NAME,
+          baseURL: baseUrl,
+          apiKey,
+          fetch,
+        })(modelId);
+      }
+      case 'openai-responses':
+        return wrapLanguageModel({
+          model: createResponsesModel(
+            input,
+            withArkResponsesShim(input.fetch)
+          ) as Exclude<LanguageModel, string>,
+          middleware: responsesDefaultsMiddleware(ARK_RESPONSES_DEFAULTS),
+        });
+      default:
+        throw unsupportedProtocol(this, input.protocol);
+    }
+  }
+
+  /**
+   * **chat-completions**：`off` 发显式的 `thinking:{type:'disabled'}`（探针
+   * `reasoning_tokens: 0`；它默认开着推理）；非 off 发 `thinking:enabled` +
+   * `reasoning_effort`。我们的 `minimal` 映到它的 `low`——方舟的 `minimal`
+   * 是「不思考」，与我们「最少思考」语义不同；`max` 映到 `high`（它文档化的
+   * 最高档）。
+   *
+   * **responses**：只发 `reasoning.effort`，`off`→`none`（探针 `reasoning_tokens:
+   * 0`、不出 reasoning item，是真正的关闭指令）；`minimal`/`max` 同上映射。
+   * key 随承载包换成 `openai`，带 `COMPATIBLE_RESPONSES_OPTIONS`（不带则 SDK
+   * 按模型名判成非推理模型、`reasoning` 整个不发，而它默认开着推理；system 与
+   * developer 角色实测都收，只保证 `system`）。`store:false` / `reasoningSummary:null`
+   * 由中间件兜底，这里不重复。
+   */
+  override reasoning(
+    _modelId: string,
+    effort: ReasoningEffort,
+    protocol: LlmProtocol
+  ): ProviderOptions {
+    switch (protocol) {
+      case 'openai-chat-completions':
+        if (effort === 'off') {
+          return { [this.optionsKey]: { thinking: { type: 'disabled' } } };
+        }
+        return {
+          [this.optionsKey]: {
+            thinking: { type: 'enabled' },
+            reasoningEffort: toArkEffort(effort),
+          },
+        };
+      case 'openai-responses':
+        return {
+          openai: {
+            reasoningEffort: effort === 'off' ? 'none' : toArkEffort(effort),
+            ...COMPATIBLE_RESPONSES_OPTIONS,
+          },
+        };
+      default:
+        throw unsupportedProtocol(this, protocol);
+    }
+  }
+}
+
+/** 我们的档位 → 方舟文档化的三档 `low/medium/high`。 */
+function toArkEffort(
+  effort: Exclude<ReasoningEffort, 'off'>
+): 'low' | 'medium' | 'high' {
+  switch (effort) {
+    case 'minimal':
+    case 'low':
+      return 'low';
+    case 'medium':
+      return 'medium';
+    case 'high':
+    case 'max':
+      return 'high';
+  }
+}