mslxdff 0.1.110 → 0.1.111

package/src/routes/models-route.js

@@ -85,17 +85,45 @@ export async function providerModelsHandler({ req, res, models }) {
   }
 }
 
-// GET /v1/models/capabilities[?provider=opencode][&id=big-pickle]
-// 模型能力元数据（reasoning 档位/图片输入/tool_call/上下文/价格），源 = opencode 官方 models.dev 目录
+// workbuddy 能力目录源：共享 provider 单例（src/model-capabilities/index.js，
+// 与 -setto opencode 能力注入共用），拉上游原生字段全量 + 10min 缓存
+// 不走聚合 models.get()——聚合会按 allowlist 过滤，blocked 模型查能力 404 会误导（能力目录≠可调用目录，与 CLI 全量展示保持一致）
+async function workbuddyAllModels() {
+  const { workbuddyAllModels: wb } = await import("../model-capabilities/index.js");
+  return wb();
+}
+
+// GET /v1/models/capabilities[?provider=opencode|workbuddy][&id=big-pickle]
+// 模型能力元数据（reasoning 档位/图片输入/tool_call/上下文/价格）
+// - provider=opencode（默认）：源 = opencode 官方 models.dev 目录
+// - provider=workbuddy：源 = workbuddy 上游原生字段（maxInputTokens/supportsImages/... first-party 最准），
+//   id 用裸 id（如 glm-5.3-flash）；wbSource 注入仅测试接缝，生产用独立 provider 单例（全量+10min 缓存）
 // jsonFn 注入仅为测试接缝（S3）；生产路径用 helpers.json
-export async function capabilitiesHandler({ req, res, capabilities, jsonFn = json }) {
+export async function capabilitiesHandler({ req, res, capabilities, wbSource, jsonFn = json }) {
   // 仅未注入（生产）时用全局单例；显式 null 视作服务不可用（测试可复现 502 空状态）
   const svc = capabilities === undefined ? globalCapabilities() : capabilities;
-  if (!svc) return jsonFn(res, 502, { error: "capabilities service unavailable" });
+  if (!svc && !wbSource) return jsonFn(res, 502, { error: "capabilities service unavailable" });
   const q = String(req?.url || "").split("?")[1] || "";
   const params = new URLSearchParams(q);
   const provider = (params.get("provider") || "opencode").toLowerCase();
   const id = params.get("id") || "";
+  // workbuddy 动态源分支：上游原生字段映射，不查 models.dev
+  if (provider === "workbuddy") {
+    try {
+      const { workbuddyCapsFromModels } = await import("../model-capabilities/index.js");
+      const map = await workbuddyCapsFromModels(wbSource || workbuddyAllModels)();
+      const rawId = id.replace(/^workbuddy\//i, "");
+      if (id) {
+        const caps = map[rawId];
+        if (!caps) return jsonFn(res, 404, { error: `model '${id}' not found in capabilities catalog (provider=workbuddy)` });
+        return jsonFn(res, 200, { object: "model.capabilities", id: rawId, provider, capabilities: caps });
+      }
+      const data = Object.entries(map).map(([mid, capabilities]) => ({ id: mid, capabilities }));
+      return jsonFn(res, 200, { object: "list", provider, data });
+    } catch (err) {
+      return jsonFn(res, 502, { error: `capabilities source unavailable: ${errMsg(err)}` });
+    }
+  }
   try {
     await svc.ready();
   } catch (err) {

package/src/runtime/providers-setup.js

@@ -2,6 +2,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultStateFile, loadToken } from "../state.js";
 import { createUpstreamClient } from "../upstream.js";
+import { createUpstreamEngine } from "../upstream-engine/index.js";
 import { createModelsService } from "../models.js";
 import { createAutoSelector } from "../auto.js";
 import { createPeersService } from "../peers.js";
@@ -50,7 +51,7 @@ export async function setupProviders() {
     }
     if (!upstream) upstream = createUpstreamClient({ hooks: upstreamHooks });
   } else {
-    const opencodeClient = createUpstreamClient({ hooks: upstreamHooks });
+    const opencodeClient = createUpstreamEngine({ hooks: upstreamHooks });
     const opencodeModels = createModelsService({
       baseUrl,
       headers: opencodeClient.headers,

package/src/state/schemas/use-group.js

@@ -1,4 +1,5 @@
 import { defaultStateFile, readState, writeStateImmediate } from "../store.js";
+import { classifyProvider } from "../../providers/classify.js";
 
 function parseBool(v) {
   if (typeof v === "boolean") return v;
@@ -36,7 +37,22 @@ export function getEffectiveUseGroup({ file = defaultStateFile() } = {}) {
 }
 
 // 全局开关：off 则所有供应商都不走组员网络（via-route/hedge/peer/broadband 全禁），仅本机直连
+// workbuddy 硬禁组员（ADR-0015 local-only）：本机账号绑定（auths/workbuddy-*.json + uid），
+// 组员没有该账号转过去也用不了，且本地直连最快——无论全局开关一律仅本机直连。
+// model 兼容 canonical（workbuddy/xxx）与 dash（workbuddy-xxx）两种形态。
+export function isHardLocalOnly(model) {
+  const s = String(model || "").trim().toLowerCase();
+  const slash = s.indexOf("/");
+  const head = slash > 0 ? s.slice(0, slash) : s.split("-")[0];
+  try {
+    return classifyProvider(head) === "local-only";
+  } catch {
+    return head === "workbuddy";
+  }
+}
+
 export function shouldUseGroupForModel(model, { file = defaultStateFile() } = {}) {
+  if (isHardLocalOnly(model)) return false;
   return getEffectiveUseGroup({ file });
 }
 

package/src/sync-opencode.js

@@ -98,9 +98,10 @@ export async function ensureAllOpencodeModels(models, ensureAll, capsSvc) {
     const storageKey = internal.includes("/") ? internal.replace(/\//g, "-") : internal;
     if (!storageKey) continue;
     if (existing.has(storageKey)) {
-      // 已存在：旧格式条目（仅 name、无能力字段）自动升级注入；已带 limit 的新格式不动
+      // 已存在：旧格式条目（仅 name、无能力字段）或缺档位（variants，ctrl+t 推理档切换）自动重注入；
+      // enrich 幂等（字段覆盖一致），重复注入无害
       const cur = models[storageKey];
-      if (cur && typeof cur === "object" && !Array.isArray(cur) && cur.limit === undefined) {
+      if (cur && typeof cur === "object" && !Array.isArray(cur) && (cur.limit === undefined || cur.variants === undefined)) {
         const en = await enrichOpencodeEntry(cur, internal, capsSvc);
         models[storageKey] = en.entry;
         if (en.caps) upgraded++;

package/src/upstream-engine/index.js

@@ -0,0 +1,69 @@
+// 上游引擎选择（ADR-0017）：sdk=AI SDK wire 层（缺省），legacy=原实现（显式/Node16 回退）。
+// Note: 缺省即 sdk；chat 类走 /chat/completions（@ai-sdk/openai-compatible），
+// responses 类（muse-spark*）走 /responses（@ai-sdk/openai）；非流式与 anon 重试委派 legacy，
+// SDK 不可用自动回退并告警一次 — 见 .scratch/ai-sdk-upstream/{SPEC.md,SPEC-p4-turnon.md,SPEC-p3-responses.md} 与 docs/adr/0017
+import { createUpstreamClient, createOpencodeHeaderBuilder } from "../upstream.js";
+import { isResponsesModel } from "../upstream-responses.js";
+import { isFreeModel } from "../models.js";
+import { createSdkChat } from "./sdk/chat.js";
+import { createSdkResponses } from "./sdk/responses.js";
+import { dispatcherFetch } from "./sdk/attempt.js";
+import { resolveEngineMode } from "./mode.js";
+
+export { resolveEngineMode };
+
+export function createUpstreamEngine(opts = {}) {
+  const legacy = createUpstreamClient(opts);
+  const env = opts.env ?? process.env;
+  if (resolveEngineMode(env) !== "sdk") return legacy;
+
+  const baseUrl = opts.baseUrl || process.env.UPSTREAM_BASE_URL || "https://opencode.ai";
+  const sdkFactory = opts.sdkFactory ?? createSdkChat;
+  const responsesFactory = opts.responsesFactory ?? createSdkResponses;
+  const { buildHeaders, anonFirst } = createOpencodeHeaderBuilder({
+    authToken: opts.authToken || process.env.UPSTREAM_AUTH_TOKEN || "public",
+  });
+  const dispatcher = legacy.dispatcher;
+  const fetchImpl = dispatcher ? dispatcherFetch(dispatcher) : undefined;
+  const sdk = sdkFactory({ baseUrl, buildHeaders, providerName: "opencode", fetchImpl });
+  const responses = responsesFactory({ baseUrl, buildHeaders, providerName: "opencode", fetchImpl });
+
+  let sdkDown = false;
+  let logged = false;
+
+  async function chat(body) {
+    if (sdkDown) return legacy.chat(body);
+    // doGenerate 聚合未实现：非流式（含 responses 非流式）委派 legacy，避免把 JSON 客户端 SSE 化
+    if (body?.stream === false) return legacy.chat(body);
+    const useResponses = isResponsesModel(body?.model);
+    try {
+      const res = useResponses ? await responses.chat(body) : await sdk.chat(body);
+      if (!logged) {
+        logged = true;
+        const via = useResponses ? "@ai-sdk/openai · responses" : "@ai-sdk/openai-compatible · chat";
+        try { console.error(`[upstream-engine] sdk 引擎生效（${via}）`); } catch {}
+      }
+      // 保留 legacy 的匿名重试语义（仅 !anonFirst 配置下存在）
+      if (res.status === 429 && !anonFirst && isFreeModel(body?.model)) return legacy.chat(body);
+      return res;
+    } catch (e) {
+      if (e && e._sdkLoadFailed) {
+        sdkDown = true;
+        try { console.error(`[upstream-engine] ${e.message} — 回退 legacy 引擎`); } catch {}
+        return legacy.chat(body);
+      }
+      throw e;
+    }
+  }
+
+  return {
+    chat,
+    preheat: (args) => legacy.preheat(args),
+    close: () => legacy.close(),
+    headers: legacy.headers,
+    buildHeaders: legacy.buildHeaders,
+    get dispatcher() { return legacy.dispatcher; },
+    get agent() { return legacy.agent; },
+    [Symbol.asyncDispose]: () => legacy.close(),
+  };
+}

package/src/upstream-engine/mode.js

@@ -0,0 +1,13 @@
+// 引擎模式解析（纯函数，零依赖）：缺省 sdk，legacy/关闭词回退原实现。
+// 供应商级开关未设置时继承全局总闸，使 MSLXDFF_UPSTREAM_ENGINE=legacy 成为一键熔断。
+// 供 upstream-engine/index.js（opencode 上游）与 providers/workbuddy/chat.js 共用。
+// 见 docs/adr/0017。
+const ENGINE_OFF_WORDS = new Set(["0", "off", "false", "no", "disable", "disabled"]);
+
+export function resolveEngineMode(env = process.env, varName = "MSLXDFF_UPSTREAM_ENGINE") {
+  const pick = (name) => String(env?.[name] ?? "").trim().toLowerCase();
+  let raw = pick(varName);
+  if (!raw && varName !== "MSLXDFF_UPSTREAM_ENGINE") raw = pick("MSLXDFF_UPSTREAM_ENGINE");
+  if (raw === "legacy" || ENGINE_OFF_WORDS.has(raw)) return "legacy";
+  return "sdk";
+}

package/src/upstream-engine/sdk/attempt.js

@@ -0,0 +1,136 @@
+// AI SDK 请求执行器（共用）：@ai-sdk/openai-compatible 的懒加载与调用点。
+// 契约：attemptOnceSdk({url, body, headers, providerName, marker, fetchImpl}) → Response（OpenAI SSE）。
+// headers 由调用方完整构造（Authorization 原样透传，不走 apiKey 注入）；
+// HTTP 错误就地映射为带状态码的 Response；装载失败抛 _sdkLoadFailed 由引擎回退 legacy。
+// responses 适配器（sdk/responses.js）复用本文件的 baseURL 解析、错误映射与流序列化。
+// 见 .scratch/ai-sdk-upstream/{SPEC.md,SPEC-p3-responses.md} 与 docs/adr/0017。
+import { toModelPrompt, toModelTools, toModelToolChoice, toModelParams } from "./convert.js";
+import { createSseSerializer } from "./sse.js";
+import { getUndici } from "../../compat.js";
+
+let sdkPromise = null;
+
+export function loadOpenAICompatibleSdk() {
+  if (!sdkPromise) sdkPromise = import("@ai-sdk/openai-compatible");
+  return sdkPromise;
+}
+
+// legacy 的 keep-alive 连接池以 fetch 形式注入 SDK（P4 转正：延迟与 legacy 同量级，不另建连接）。
+export function dispatcherFetch(dispatcher) {
+  const f = getUndici().fetch;
+  return (url, init = {}) => f(url, { ...init, dispatcher });
+}
+
+// 剥掉 url 末尾的协议段，得到 SDK baseURL（chat 走 /chat/completions，responses 走 /responses）。
+export function sdkBaseFromUrl(url, suffix = "/chat/completions") {
+  const s = String(url || "");
+  const esc = String(suffix).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`${esc}/?$`);
+  if (!re.test(s)) return null;
+  return s.replace(re, "");
+}
+
+// 只剥 Content-Type（由 SDK 固定 application/json）；其余头（含 Authorization）原样透传
+export function sanitizeHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    if (String(k).toLowerCase() === "content-type") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+export function markerHeaders(marker) {
+  return marker && marker.name ? { [marker.name]: marker.value } : {};
+}
+
+// SDK 抛出的 APICallError → 带状态码的 Response；非 HTTP 错误返回 null 由调用方 rethrow。
+export function errorResponseFromSdkError(e, { marker = null } = {}) {
+  const status = Number(e?.statusCode ?? e?.status);
+  if (!Number.isFinite(status) || status < 400) return null;
+  const text = typeof e.responseBody === "string"
+    ? e.responseBody
+    : JSON.stringify({ error: { message: e?.message || String(e) } });
+  return new Response(text, {
+    status,
+    headers: { "content-type": "application/json", ...markerHeaders(marker) },
+  });
+}
+
+// SDK parts → OpenAI SSE Response（chat/responses 共用同一序列化器）。
+export function streamResponseFromParts(parts, { marker = null, clock = Date.now, t0 = clock() } = {}) {
+  const ser = createSseSerializer();
+  const enc = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const part of parts) {
+          const text = ser.push(part);
+          if (text) controller.enqueue(enc.encode(text));
+        }
+      } catch (e) {
+        controller.enqueue(enc.encode(`data: ${JSON.stringify({ error: { message: String(e?.message || e) } })}\n\n`));
+      }
+      controller.enqueue(enc.encode(ser.end()));
+      controller.close();
+    },
+    cancel() {
+      try { parts.cancel?.(); } catch {}
+    },
+  });
+  const out = new Response(stream, {
+    status: 200,
+    headers: { "content-type": "text/event-stream", ...markerHeaders(marker) },
+  });
+  try { out._t = { attempts: [{ type: "http200", ms: Math.round(clock() - t0) }], waitMs: 0, totalMs: Math.round(clock() - t0) }; } catch {}
+  return out;
+}
+
+export async function attemptOnceSdk({
+  url,
+  body,
+  headers = {},
+  providerName = "opencode",
+  marker = null,
+  clock = Date.now,
+  sdkLoader = loadOpenAICompatibleSdk,
+  fetchImpl,
+} = {}) {
+  const t0 = clock();
+  const baseURL = sdkBaseFromUrl(url);
+  if (!baseURL) {
+    // 异形 chatPath（非 /chat/completions 结尾）：标 _sdkUnsupported 由分派层静默回退原生
+    const err = new Error(`sdk-channel: chatPath 非 /chat/completions，暂不支持（${url}）`);
+    err._sdkUnsupported = true;
+    throw err;
+  }
+  let createOpenAICompatible;
+  try {
+    ({ createOpenAICompatible } = await sdkLoader());
+  } catch (e) {
+    const err = new Error(`sdk-channel: @ai-sdk/openai-compatible 不可用（需 Node>=18 且已安装）: ${e?.message || e}`);
+    err._sdkLoadFailed = true;
+    throw err;
+  }
+  const provider = createOpenAICompatible({
+    name: providerName,
+    baseURL,
+    headers: sanitizeHeaders(headers),
+    ...(fetchImpl ? { fetch: fetchImpl } : {}),
+  });
+  const model = provider.chatModel(String(body?.model || ""));
+  let res;
+  try {
+    res = await model.doStream({
+      prompt: toModelPrompt(body?.messages),
+      ...toModelParams(body, providerName),
+      tools: toModelTools(body?.tools),
+      toolChoice: toModelToolChoice(body?.tool_choice),
+    });
+  } catch (e) {
+    const mapped = errorResponseFromSdkError(e, { marker });
+    if (mapped) return mapped;
+    throw e;
+  }
+  return streamResponseFromParts(res.stream, { marker, clock, t0 });
+}

package/src/upstream-engine/sdk/chat.js

@@ -0,0 +1,28 @@
+// SDK 引擎的 chat 适配器工厂：拼 URL → attemptOnceSdk。
+// buildHeaders(body) 由调用方注入（身份头随供应商而异，单一来源在引擎侧）。
+import { attemptOnceSdk } from "./attempt.js";
+
+export const ENGINE_MARKER = { name: "x-mslxdff-upstream-engine", value: "sdk" };
+
+export function createSdkChat({
+  baseUrl,
+  chatPath = "/zen/v1/chat/completions",
+  buildHeaders,
+  providerName = "opencode",
+  marker = ENGINE_MARKER,
+  fetchImpl,
+} = {}) {
+  const base = String(baseUrl || "").replace(/\/+$/, "");
+  return {
+    async chat(body) {
+      return attemptOnceSdk({
+        url: `${base}${chatPath}`,
+        body,
+        headers: buildHeaders ? buildHeaders(body) : {},
+        providerName,
+        marker,
+        fetchImpl,
+      });
+    },
+  };
+}

package/src/upstream-engine/sdk/convert.js

@@ -0,0 +1,133 @@
+// OpenAI 请求体 → @ai-sdk/openai-compatible 入参（仅 chat）。
+// 显式映射常用面；未映射字段经 toProviderExtras 原样透传（providerOptions.<providerName> 会被 spread 进请求体）。
+// 共用库：workbuddy 实验通道与 upstream-engine 同源。见 .scratch/ai-sdk-upstream/SPEC.md。
+
+const HANDLED_KEYS = new Set([
+  "model", "messages", "stream", "tools", "tool_choice",
+  "temperature", "top_p", "max_tokens", "stop",
+  "presence_penalty", "frequency_penalty", "seed", "reasoning_effort",
+]);
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.filter((p) => p?.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
+  }
+  return "";
+}
+
+function userContentParts(content) {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (!Array.isArray(content)) return [{ type: "text", text: String(content ?? "") }];
+  const parts = [];
+  for (const p of content) {
+    if (!p || typeof p !== "object") continue;
+    if (p.type === "text" || p.type === "input_text") {
+      parts.push({ type: "text", text: String(p.text ?? "") });
+    } else if (p.type === "image_url") {
+      const url = typeof p.image_url === "string" ? p.image_url : p.image_url?.url;
+      if (!url) continue;
+      try { parts.push({ type: "file", mediaType: "image/*", data: new URL(url) }); } catch {}
+    }
+  }
+  if (!parts.length) parts.push({ type: "text", text: "" });
+  return parts;
+}
+
+function parseToolArgs(raw) {
+  if (raw && typeof raw === "object") return raw;
+  try { return JSON.parse(String(raw)); } catch { return {}; }
+}
+
+export function toModelPrompt(messages) {
+  const out = [];
+  for (const m of Array.isArray(messages) ? messages : []) {
+    if (!m || typeof m !== "object") continue;
+    const role = String(m.role || "");
+    if (role === "system" || role === "developer") {
+      out.push({ role: "system", content: textOf(m.content) });
+    } else if (role === "user") {
+      out.push({ role: "user", content: userContentParts(m.content) });
+    } else if (role === "assistant") {
+      const parts = [];
+      const text = textOf(m.content);
+      if (text) parts.push({ type: "text", text });
+      if (m.reasoning_content) parts.push({ type: "reasoning", text: String(m.reasoning_content) });
+      for (const tc of Array.isArray(m.tool_calls) ? m.tool_calls : []) {
+        if (!tc || typeof tc !== "object") continue;
+        parts.push({
+          type: "tool-call",
+          toolCallId: String(tc.id || ""),
+          toolName: String(tc.function?.name || ""),
+          input: parseToolArgs(tc.function?.arguments),
+        });
+      }
+      out.push({ role: "assistant", content: parts });
+    } else if (role === "tool") {
+      out.push({
+        role: "tool",
+        content: [{
+          type: "tool-result",
+          toolCallId: String(m.tool_call_id || ""),
+          toolName: String(m.name || "tool"),
+          output: { type: "text", value: typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? "") },
+        }],
+      });
+    }
+  }
+  return out;
+}
+
+export function toModelTools(tools) {
+  if (!Array.isArray(tools)) return undefined;
+  const out = tools
+    .filter((t) => t && t.type === "function" && t.function?.name)
+    .map((t) => ({
+      type: "function",
+      name: String(t.function.name),
+      description: t.function.description ? String(t.function.description) : undefined,
+      inputSchema: t.function.parameters && typeof t.function.parameters === "object"
+        ? t.function.parameters
+        : { type: "object", properties: {} },
+    }));
+  return out.length ? out : undefined;
+}
+
+export function toModelToolChoice(choice) {
+  if (!choice) return undefined;
+  if (typeof choice === "string") {
+    return ["auto", "none", "required"].includes(choice) ? { type: choice } : undefined;
+  }
+  if (choice.type === "function" && choice.function?.name) {
+    return { type: "tool", toolName: String(choice.function.name) };
+  }
+  return undefined;
+}
+
+export function toProviderExtras(body) {
+  const extras = {};
+  for (const [k, v] of Object.entries(body || {})) {
+    if (!HANDLED_KEYS.has(k) && v !== undefined) extras[k] = v;
+  }
+  return Object.keys(extras).length ? extras : undefined;
+}
+
+export function toModelParams(body, providerName = "opencode") {
+  const params = {};
+  if (body?.max_tokens != null) params.maxOutputTokens = body.max_tokens;
+  if (body?.temperature != null) params.temperature = body.temperature;
+  if (body?.top_p != null) params.topP = body.top_p;
+  if (body?.presence_penalty != null) params.presencePenalty = body.presence_penalty;
+  if (body?.frequency_penalty != null) params.frequencyPenalty = body.frequency_penalty;
+  if (Array.isArray(body?.stop)) params.stopSequences = body.stop;
+  else if (typeof body?.stop === "string" && body.stop) params.stopSequences = [body.stop];
+  if (body?.seed != null) params.seed = body.seed;
+  const providerOptions = {};
+  if (body?.reasoning_effort != null) {
+    providerOptions.openaiCompatible = { reasoningEffort: String(body.reasoning_effort) };
+  }
+  const extras = toProviderExtras(body);
+  if (extras) providerOptions[providerName] = extras;
+  if (Object.keys(providerOptions).length) params.providerOptions = providerOptions;
+  return params;
+}

package/src/upstream-engine/sdk/dispatch.js

@@ -0,0 +1,55 @@
+// 供应商级 SDK 分派（薄壳）：通用 OpenAI 兼容上游的"请求发出口"共用。
+// 缺省 sdk（attemptOnceSdk 走 @ai-sdk/openai-compatible）；varName 显式设 legacy/关闭词即回退，
+// 未设置则继承全局 MSLXDFF_UPSTREAM_ENGINE（一键熔断）。
+// SDK 不可用抛 _sdkLoadFailed → 回退原生并告警一次；其它错误 rethrow 交调用方重试语义。
+// 见 .scratch/ai-sdk-providers-rest/SPEC.md 与 docs/adr/0017。
+import { resolveEngineMode } from "../mode.js";
+import { attemptOnceSdk } from "./attempt.js";
+
+export function sdkEnvName(id) {
+  return `MSLXDFF_${String(id || "").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}_SDK`;
+}
+
+export function createSdkDispatch({
+  id,
+  varName,
+  providerName,
+  markerName = "x-mslxdff-upstream-engine",
+  label,
+  env = process.env,
+  logger = console,
+  attemptImpl = attemptOnceSdk,
+} = {}) {
+  const name = varName || sdkEnvName(id);
+  const provider = providerName || id || "provider";
+  const tag = label || provider;
+  const mode = resolveEngineMode(env, name);
+  let fallbackLogged = false;
+
+  return {
+    varName: name,
+    enabled: mode === "sdk",
+    // 成功返回 Response；_sdkLoadFailed → null（调用方回退原生）；其它错误 rethrow
+    async trySdk({ url, body, headers, fetchImpl, clock } = {}) {
+      try {
+        return await attemptImpl({
+          url,
+          body,
+          headers,
+          providerName: provider,
+          marker: markerName ? { name: markerName, value: "sdk" } : null,
+          fetchImpl,
+          clock,
+        });
+      } catch (e) {
+        if (e && e._sdkUnsupported) return null; // 异形 chatPath：静默回退原生
+        if (!e || !e._sdkLoadFailed) throw e;
+        if (!fallbackLogged) {
+          fallbackLogged = true;
+          try { logger.error(`[${tag}] ${e.message} — 回退原生通道`); } catch {}
+        }
+        return null;
+      }
+    },
+  };
+}

package/src/upstream-engine/sdk/responses.js

@@ -0,0 +1,85 @@
+// Responses API 适配器（@ai-sdk/openai）：models.dev 里模型级 npm=@ai-sdk/openai 的模型
+// （如 muse-spark*，打 /zen/v1/responses）。与 chat 适配器同契约：输出 OpenAI chat SSE 帧。
+// 复用 attempt.js 的 baseURL 解析 / 错误映射 / 流序列化，不复制实现。
+// 见 .scratch/ai-sdk-upstream/SPEC-p3-responses.md 与 docs/adr/0017。
+import { toModelPrompt, toModelTools, toModelToolChoice, toModelParams } from "./convert.js";
+import { sdkBaseFromUrl, sanitizeHeaders, errorResponseFromSdkError, streamResponseFromParts } from "./attempt.js";
+import { ENGINE_MARKER } from "./chat.js";
+
+export const RESPONSES_CHAT_PATH = "/zen/v1/responses";
+
+let sdkPromise = null;
+
+export function loadOpenAISdk() {
+  if (!sdkPromise) sdkPromise = import("@ai-sdk/openai");
+  return sdkPromise;
+}
+
+export async function attemptOnceResponsesSdk({
+  url,
+  body,
+  headers = {},
+  providerName = "opencode",
+  marker = null,
+  clock = Date.now,
+  sdkLoader = loadOpenAISdk,
+  fetchImpl,
+} = {}) {
+  const t0 = clock();
+  const baseURL = sdkBaseFromUrl(url, "/responses");
+  if (!baseURL) throw new Error(`sdk-channel: responsesPath 非 /responses，暂不支持（${url}）`);
+  let createOpenAI;
+  try {
+    ({ createOpenAI } = await sdkLoader());
+  } catch (e) {
+    const err = new Error(`sdk-channel: @ai-sdk/openai 不可用（需 Node>=18 且已安装）: ${e?.message || e}`);
+    err._sdkLoadFailed = true;
+    throw err;
+  }
+  // headers 由调用方构造（含 Authorization），headers 优先于 apiKey 默认头
+  const provider = createOpenAI({
+    name: providerName,
+    baseURL,
+    apiKey: "public",
+    headers: sanitizeHeaders(headers),
+    ...(fetchImpl ? { fetch: fetchImpl } : {}),
+  });
+  const model = provider.responses(String(body?.model || ""));
+  let res;
+  try {
+    res = await model.doStream({
+      prompt: toModelPrompt(body?.messages),
+      ...toModelParams(body, providerName),
+      tools: toModelTools(body?.tools),
+      toolChoice: toModelToolChoice(body?.tool_choice),
+    });
+  } catch (e) {
+    const mapped = errorResponseFromSdkError(e, { marker });
+    if (mapped) return mapped;
+    throw e;
+  }
+  return streamResponseFromParts(res.stream, { marker, clock, t0 });
+}
+
+export function createSdkResponses({
+  baseUrl,
+  chatPath = RESPONSES_CHAT_PATH,
+  buildHeaders,
+  providerName = "opencode",
+  marker = ENGINE_MARKER,
+  fetchImpl,
+} = {}) {
+  const base = String(baseUrl || "").replace(/\/+$/, "");
+  return {
+    async chat(body) {
+      return attemptOnceResponsesSdk({
+        url: `${base}${chatPath}`,
+        body,
+        headers: buildHeaders ? buildHeaders(body) : {},
+        providerName,
+        marker,
+        fetchImpl,
+      });
+    },
+  };
+}