mslxdff 0.1.109 → 0.1.111

package/src/providers/model-id.js

@@ -131,4 +131,33 @@ export function normalizeFullId(id, knownProviders = []) {
     return `${head}/${s.slice(idx + 1)}`;
   }
   return `${DEFAULT_PROVIDER}/${s}`;
+}
+
+const BUILTIN_PROVIDERS = new Set([DEFAULT_PROVIDER, "openrouter"]);
+
+/**
+ * 过滤 provider 已不存在的 picks 孤儿（纯函数，零 IO，可单测）。
+ * - 含 `/` 前缀：head（归一+小写）∉ 已知集合 → stale（如 amddev/*）。
+ * - Bare id：∉ 上游 liveIds ∪ allowlist 展开 → stale（如 laguna-s-2.1-free）。
+ * - provider 存在但未启用（如 deepseek 缺 baseUrl）→ 保留，不可用由 [error] 表达。
+ * - 未知一律保留（默认放行不误删显示）；dash 别名经 resolveAlias 还原后判定；
+ *   上游 liveIds 为空时 bare 一律保留（无法判定则放行）。
+ * 数据不动，只决定进不进 `-models` 交互列表 — 见 .scratch/models-stale-picks/SPEC.md。
+ */
+export function filterStalePicks(pickedIds, { knownProviders = [], liveIds = [], allowedIds = [], resolveAlias = getModelAlias } = {}) {
+  const known = new Set([...BUILTIN_PROVIDERS, ...(knownProviders || []).map((p) => normalizeProviderId(p).toLowerCase())]);
+  const live = new Set((liveIds || []).map((id) => String(id).toLowerCase()));
+  const allowed = new Set((allowedIds || []).map((id) => String(id).toLowerCase()));
+  return (pickedIds || []).filter((pick) => {
+    const raw = String(pick || "").trim();
+    if (!raw) return false;
+    let id = raw;
+    try { id = resolveAlias(raw) || raw; } catch { id = raw; }
+    const slash = String(id).indexOf("/");
+    if (slash > 0) return known.has(normalizeProviderId(id.slice(0, slash)).toLowerCase());
+    // 上游列表为空（刷新与缓存双失败的极端情况）时无法判定 bare 生死 → 保留（默认放行）
+    if (live.size === 0) return true;
+    const low = String(id).toLowerCase();
+    return live.has(low) || allowed.has(low);
+  });
 }

package/src/providers/workbuddy/chat.js

@@ -3,6 +3,8 @@ import { isAuthError, isInsufficientStatus } from "./auth.js";
 import { appendRotationLog as defaultAppend } from "./rotation-log.js";
 import { createTransport } from "../../transport/index.js";
 import { reshapeWorkbuddySse } from "./reshape.js";
+import { attemptOnceSdk } from "./sdk-chat.js";
+import { resolveEngineMode } from "../../upstream-engine/mode.js";
 
 function buildAuthHeaders(key, auth) {
   const h = {
@@ -79,7 +81,24 @@ export function createChatService({
     return { uid: "", domain: "www.codebuddy.cn", enterpriseId: "", refreshToken: "" };
   }
 
+  // SDK 通道（缺省启用）：缺省底层走 @ai-sdk/openai-compatible，`legacy`/关闭词
+  // （局部 MSLXDFF_WORKBUDDY_SDK，未设则继承全局 MSLXDFF_UPSTREAM_ENGINE）回退原生 transport；
+  // 不可用（Node16/未安装）自动回退并告警一次。上层轮换/刷新/reshape 全链复用。
+  // Note: 为什么默认 SDK、翻译层代价与回退语义 — 见 .agents/notes/implemented/feature/2026-09-12-workbuddy-sdk-channel.md
+  const engineMode = resolveEngineMode(process.env, "MSLXDFF_WORKBUDDY_SDK");
+  let sdkFallbackLogged = false;
   async function fetchOnce(url, body, key, auth) {
+    if (engineMode === "sdk") {
+      try {
+        return await attemptOnceSdk({ url, body, key, auth, buildHeaders: buildAuthHeaders });
+      } catch (e) {
+        if (!e || !e._sdkLoadFailed) throw e;
+        if (!sdkFallbackLogged) {
+          sdkFallbackLogged = true;
+          try { console.error(`[workbuddy] ${e.message} — 回退原生通道`); } catch {}
+        }
+      }
+    }
     return transport.request({ url, headers: buildAuthHeaders(key, auth), body: { ...body, stream: true }, stream: true });
   }
 

package/src/providers/workbuddy/reshape.js

@@ -107,24 +107,31 @@ export function reshapeWorkbuddySse(res) {
     async pull(controller) {
       if (closed) { try { controller.close(); } catch {} return; }
       try {
-        const { done, value } = await reader.read();
-        if (done) {
-          closed = true;
+        // 循环读源，直到"有输出 / 流结束 / 出错"才返回。
+        // WHATWG 流规范：pull 的 promise 解析后若未 enqueue，规范不会再自动调度 pull
+        // （仅当解析期间有新读请求触发 pullAgain 才重调）——消费者只挂一个待处理 read 时，
+        // 任何一次"只吞帧不出数据"的拉取都会让整流永久停摆。workbuddy 思考流按帧到达
+        // （role 帧后每个 reasoning 碎片都不足 150 字符阈值）时必现，即"首帧后卡死"根因。
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) {
+            closed = true;
+            const out = [];
+            if (buf) { processInto(buf + "\n", out); buf = ""; }
+            flushReasoningInto(out);
+            if (out.length) controller.enqueue(encoder.encode(out.join("")));
+            controller.close();
+            return;
+          }
+          buf += decoder.decode(value, { stream: true });
+          const idx = buf.lastIndexOf("\n");
+          if (idx < 0) continue;
+          const complete = buf.slice(0, idx + 1);
+          buf = buf.slice(idx + 1);
           const out = [];
-          if (buf) { processInto(buf + "\n", out); buf = ""; }
-          flushReasoningInto(out);
-          if (out.length) controller.enqueue(encoder.encode(out.join("")));
-          controller.close();
-          return;
+          processInto(complete, out);
+          if (out.length) { controller.enqueue(encoder.encode(out.join(""))); return; }
         }
-        buf += decoder.decode(value, { stream: true });
-        const idx = buf.lastIndexOf("\n");
-        if (idx < 0) return;
-        const complete = buf.slice(0, idx + 1);
-        buf = buf.slice(idx + 1);
-        const out = [];
-        processInto(complete, out);
-        if (out.length) controller.enqueue(encoder.encode(out.join("")));
       } catch {
         closed = true;
         try { controller.close(); } catch {}

package/src/providers/workbuddy/sdk-chat.js

@@ -0,0 +1,25 @@
+// workbuddy SDK 实验通道（薄壳）：转调共用执行器 upstream-engine/sdk/attempt.js。
+// 契约保持：attemptOnceSdk({url, body, key, auth, buildHeaders}) → Response（SSE）。
+// HTTP 错误映射与 _sdkLoadFailed 语义在共用层；本壳只注入 workbuddy 特有参数。
+// 见 .scratch/workbuddy-sdk-channel/SPEC.md。
+import { attemptOnceSdk as attemptGeneric, sdkBaseFromUrl } from "../../upstream-engine/sdk/attempt.js";
+
+export { sdkBaseFromUrl };
+
+let channelLogged = false;
+
+export async function attemptOnceSdk({ url, body, key, auth, buildHeaders, clock = Date.now } = {}) {
+  const out = await attemptGeneric({
+    url,
+    body,
+    headers: buildHeaders ? buildHeaders(key, auth) : {},
+    providerName: "workbuddy",
+    marker: { name: "x-mslxdff-workbuddy-channel", value: "sdk" },
+    clock,
+  });
+  if (!channelLogged) {
+    channelLogged = true;
+    try { console.error(`[workbuddy-sdk-channel] active via @ai-sdk/openai-compatible (model=${body?.model || ""} uid=${auth?.uid || ""})`); } catch {}
+  }
+  return out;
+}

package/src/routes/hedge.js

@@ -18,8 +18,8 @@ function shouldHedge({ isStream, canForwardPeers, hedgeDelayMs: d, hasPeers, mod
   if (!canForwardPeers) return false;
   if (!hasPeers) return false;
   if (!d || d <= 0) return false;
-  // 不做供应商级禁对冲特判：对冲仅按 useGroup/流式/peer 可用性决定
-  // muse-spark 走 /responses 流式（event: 包装 + 加密 reasoning），组员旧版无此整形且聚合 JSON 带错 header，必抢赢本地慢首块，需本地直出
+  // 供应商级禁对冲在 shouldUseGroupForModel 层收敛（workbuddy local-only 硬禁，见 ADR-0015）；
+  // 这里只留 muse-spark 特判：走 /responses 流式（event: 包装 + 加密 reasoning），组员旧版无此整形且聚合 JSON 带错 header，必抢赢本地慢首块，需本地直出
   if (String(model || "").toLowerCase().startsWith("muse-spark")) return false;
   return true;
 }

package/src/routes/index.js

@@ -4,7 +4,7 @@ import { json, notFound, authorized } from "./helpers.js";
 import { chatHandler } from "./chat.js";
 import { joinHandler, leaveHandler } from "./groups.js";
 import { heartbeatHandler, pollHandler, resultHandler, forwardHandler, streamHandler } from "./groups-relay.js";
-import { modelsHandler, modelsStatusHandler, providerModelsHandler } from "./models-route.js";
+import { modelsHandler, modelsStatusHandler, providerModelsHandler, capabilitiesHandler } from "./models-route.js";
 import { relayHandler } from "./relay.js";
 import { responsesHandler } from "./responses-route.js";
 
@@ -110,6 +110,12 @@ const ROUTES = [
     requiresAuth: true,
     handler: modelsStatusHandler,
   },
+  {
+    method: "GET",
+    path: "/v1/models/capabilities",
+    requiresAuth: true,
+    handler: capabilitiesHandler,
+  },
 ];
 
 // re-export for facade & tests

package/src/routes/models-route.js

@@ -1,6 +1,7 @@
 import { json, errMsg } from "./helpers.js";
 import { runHook } from "../plugins.js";
 import { isModelAllowed } from "../state.js";
+import { globalCapabilities } from "../model-capabilities/index.js";
 
 // Codex 自定义 provider 拉目录要顶层 `models` 数组（codex-rs endpoint/models.rs 解 ModelsResponse{models}），
 // 给它 OpenAI 标准 {object,data} 会报 missing field `models`。学 OmniRoute：仅 codex 调用者追加空数组
@@ -83,3 +84,56 @@ export async function providerModelsHandler({ req, res, models }) {
     json(res, 502, { error: errMsg(err) });
   }
 }
+
+// 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, wbSource, jsonFn = json }) {
+  // 仅未注入（生产）时用全局单例；显式 null 视作服务不可用（测试可复现 502 空状态）
+  const svc = capabilities === undefined ? globalCapabilities() : capabilities;
+  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) {
+    return jsonFn(res, 502, { error: `capabilities source unavailable: ${errMsg(err)}` });
+  }
+  if (id) {
+    const caps = svc.get(provider, id);
+    if (!caps) return jsonFn(res, 404, { error: `model '${id}' not found in capabilities catalog (provider=${provider})` });
+    return jsonFn(res, 200, { object: "model.capabilities", id, provider, capabilities: caps });
+  }
+  const data = svc.list(provider);
+  return jsonFn(res, 200, { object: "list", provider, data });
+}

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

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
 import { dirname, join } from "node:path";
 import os from "node:os";
+import { enrichOpencodeEntry, capsSummary as capsSummaryText } from "./model-capabilities/enrich.js";
 
 export function opencodeConfigPath() {
   const env = process.env.OPENCODE_CONFIG || process.env.OPENCODE_CONFIG_PATH;
@@ -79,21 +80,36 @@ export function pruneOpencodeModels(models, keep, currentKey) {
 }
 
 // 补齐：把 ensureAll（picks 口径）里缺失的键写入 models（slash → dash + alias 注册）。
-// 返回 { nextModels, backfilled }；ensureAll 非数组或为空时原样返回（backfilled=0）。
+// 已存在但为旧格式（缺 limit 能力字段）的条目也自动补注能力（upgraded 计数）。
+// 返回 { nextModels, backfilled, upgraded }；ensureAll 非数组或为空时原样返回。
 // 注意：需在剪枝之前调用——先补 picks 缺失，再剪 picks 外旧键，结果集恰为 picks ∪ currentKey。
-export async function ensureAllOpencodeModels(models, ensureAll) {
+// capsSvc 透传给能力注入（undefined=全局单例；补齐的条目同样带能力）。
+export async function ensureAllOpencodeModels(models, ensureAll, capsSvc) {
   if (!Array.isArray(ensureAll) || !ensureAll.length || !models || typeof models !== "object") {
-    return { nextModels: models, backfilled: 0 };
+    return { nextModels: models, backfilled: 0, upgraded: 0 };
   }
   const existing = new Set(Object.keys(models).map(normalizeOpencodeKey));
   let backfilled = 0;
+  let upgraded = 0;
   let aliasDirty = false;
   for (const raw of ensureAll) {
     const internal = toInternalId(String(raw || "").trim());
     if (!internal || internal === "auto") continue;
     const storageKey = internal.includes("/") ? internal.replace(/\//g, "-") : internal;
-    if (!storageKey || existing.has(storageKey)) continue;
-    models[storageKey] = { name: storageKey };
+    if (!storageKey) continue;
+    if (existing.has(storageKey)) {
+      // 已存在：旧格式条目（仅 name、无能力字段）或缺档位（variants，ctrl+t 推理档切换）自动重注入；
+      // enrich 幂等（字段覆盖一致），重复注入无害
+      const cur = models[storageKey];
+      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++;
+      }
+      continue;
+    }
+    const enriched = await enrichOpencodeEntry({ name: storageKey }, internal, capsSvc);
+    models[storageKey] = enriched.entry;
     existing.add(storageKey);
     backfilled++;
     if (internal.includes("/") && storageKey !== internal) {
@@ -111,10 +127,10 @@ export async function ensureAllOpencodeModels(models, ensureAll) {
       persistModelAliases();
     } catch {}
   }
-  return { nextModels: models, backfilled };
+  return { nextModels: models, backfilled, upgraded };
 }
 
-export async function syncToOpencode({ id, token, port, file, keep, ensureAll } = {}) {
+export async function syncToOpencode({ id, token, port, file, keep, ensureAll, capabilities } = {}) {
   const targetFile = file || opencodeConfigPath();
   const normalizedRaw = String(id || "").trim();
   if (!normalizedRaw) throw new Error("model id required");
@@ -156,6 +172,8 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
   let effectiveId = storageKey;
   let pruned = 0;
   let backfilled = 0;
+  let upgraded = 0;
+  let currentCaps = null;
   if (oldProvider) {
     const oldModels = oldProvider.models && typeof oldProvider.models === "object" && !Array.isArray(oldProvider.models)
       ? oldProvider.models
@@ -187,16 +205,21 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
         if (nextModels[legacyAlias]) delete nextModels[legacyAlias];
         if (legacyInternal !== legacyAlias && nextModels[legacyInternal]) delete nextModels[legacyInternal];
       }
-      nextModels[storageKey] = { ...merged, name: storageKey };
+      const enriched = await enrichOpencodeEntry({ ...merged, name: storageKey }, internal, capabilities);
+      nextModels[storageKey] = enriched.entry;
+      currentCaps = enriched.caps;
       effectiveId = storageKey;
       action = "updated";
     } else {
-      nextModels[storageKey] = { name: storageKey };
+      const enriched = await enrichOpencodeEntry({ name: storageKey }, internal, capabilities);
+      nextModels[storageKey] = enriched.entry;
+      currentCaps = enriched.caps;
       effectiveId = storageKey;
       action = "inserted";
     }
-    const ensured = await ensureAllOpencodeModels(nextModels, ensureAll);
+    const ensured = await ensureAllOpencodeModels(nextModels, ensureAll, capabilities);
     backfilled = ensured.backfilled;
+    upgraded = ensured.upgraded || 0;
     pruned = pruneOpencodeModels(nextModels, keep, storageKey);
     const nextProvider = {
       ...oldProvider,
@@ -216,8 +239,12 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
     if (!data.provider.mslxdff.models[storageKey]) {
       data.provider.mslxdff.models = { [storageKey]: { name: storageKey } };
     }
-    const ensured = await ensureAllOpencodeModels(data.provider.mslxdff.models, ensureAll);
+    const enrichedNew = await enrichOpencodeEntry(data.provider.mslxdff.models[storageKey], internal, capabilities);
+    data.provider.mslxdff.models[storageKey] = enrichedNew.entry;
+    currentCaps = enrichedNew.caps;
+    const ensured = await ensureAllOpencodeModels(data.provider.mslxdff.models, ensureAll, capabilities);
     backfilled = ensured.backfilled;
+    upgraded = ensured.upgraded || 0;
     action = "inserted";
   }
 
@@ -249,5 +276,5 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
     }
   } catch {}
 
-  return { action, file: targetFile, id: effectiveId, alias: storageKey, internal, corrupted, storageKey, pruned, backfilled };
+  return { action, file: targetFile, id: effectiveId, alias: storageKey, internal, corrupted, storageKey, pruned, backfilled, upgraded, caps: currentCaps, capsSummaryText: capsSummaryText(currentCaps) };
 }

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,
+      });
+    },
+  };
+}