mslxdff 0.1.203 → 0.1.207

package/src/plugins.js

@@ -1,107 +1,107 @@
-import { readdirSync, existsSync } from "node:fs";
-import { join, basename, extname } from "node:path";
-import { pathToFileURL } from "node:url";
-import os from "node:os";
-
-// mslxdff 插件系统：约定目录下的 *.mjs / *.js 模块，default export：
-//   { name?, version?, description?, hooks?: { "<hook-name>": async (ctx) => nextValue? } }
-// hook 返回数组时可替换流程值（如 model:select 的候选顺序）；返回 undefined 表示只观察。
-// 插件错误一律隔离：加载失败进 errors，hook 抛错不影响主链路。
-
-export function pluginsDir() {
-  return process.env.MSLXDFF_PLUGINS_DIR ||
-    join(os.homedir(), ".config", "mslxdff", "plugins");
-}
-
-// 安装目录下的 plugins/（随仓库/内置分发；auto-update 重装会丢，仅作开发/内置用）
-export function bundledPluginsDir(pkgRoot) {
-  if (!pkgRoot) return null;
-  return join(pkgRoot, "plugins");
-}
-
-// 解析扫描目录列表：env 完全接管；否则安装目录 plugins/ + 用户目录（同名文件用户目录优先）
-export function resolvePluginDirs({ pkgRoot } = {}) {
-  const env = process.env.MSLXDFF_PLUGINS_DIR;
-  if (env) return [env];
-  const dirs = [];
-  const bundled = bundledPluginsDir(pkgRoot);
-  if (bundled) dirs.push(bundled);
-  dirs.push(pluginsDir());
-  return dirs;
-}
-
-const PLUGIN_EXTS = new Set([".mjs", ".js"]);
-
-async function loadFromDir(dir, skipFiles) {
-  const plugins = [];
-  const errors = [];
-  if (!dir || !existsSync(dir)) return { plugins, errors };
-  let files = [];
-  try {
-    files = readdirSync(dir).filter((f) => PLUGIN_EXTS.has(extname(f).toLowerCase()));
-  } catch (err) {
-    errors.push({ file: dir, error: String(err?.message || err) });
-    return { plugins, errors };
-  }
-  files.sort();
-  for (const f of files) {
-    const file = join(dir, f);
-    if (skipFiles?.has(f)) continue; // 用户目录同名文件优先
-    try {
-      const mod = await import(pathToFileURL(file).href);
-      const plugin = mod?.default;
-      if (!plugin || typeof plugin !== "object") {
-        errors.push({ file, error: "no default export object" });
-        continue;
-      }
-      plugins.push({
-        name: typeof plugin.name === "string" && plugin.name ? plugin.name : basename(f, extname(f)),
-        version: typeof plugin.version === "string" ? plugin.version : "",
-        description: typeof plugin.description === "string" ? plugin.description : "",
-        hooks: plugin.hooks && typeof plugin.hooks === "object" ? plugin.hooks : {},
-        file,
-      });
-    } catch (err) {
-      errors.push({ file, error: String(err?.message || err) });
-    }
-  }
-  return { plugins, errors };
-}
-
-export async function loadPlugins({ dir, dirs } = {}) {
-  // 兼容旧签名 loadPlugins({ dir })；新签名 dirs 数组按优先级从低到高（后者覆盖前者同名文件）
-  const list = dirs || (dir ? [dir] : [pluginsDir()]);
-  let plugins = [];
-  const errors = [];
-  const seen = new Set(); // 已加载的 basename，先扫的目录跳过它们 → 后目录（高优先）覆盖
-  for (let i = list.length - 1; i >= 0; i--) {
-    const r = await loadFromDir(list[i], seen);
-    for (const p of r.plugins) seen.add(basename(p.file));
-    plugins = [...r.plugins, ...plugins]; // 低优先目录在前，目录内保持文件名序
-    errors.push(...r.errors);
-  }
-  return { plugins, errors };
-}
-
-// 串行执行某 hook。返回 { value, changed, errors }：
-// - value：最后一个返回非 undefined 值的插件的返回值（链式传递；数组、对象、布尔均可）
-// - changed：是否有插件返回了非 undefined 值（调用方可据此采用 value）
-export async function runHook(plugins, name, ctx) {
-  let value;
-  let changed = false;
-  const errors = [];
-  for (const p of plugins || []) {
-    const fn = p.hooks?.[name];
-    if (typeof fn !== "function") continue;
-    try {
-      const out = await fn(ctx);
-      if (out !== undefined) {
-        value = out;
-        changed = true;
-      }
-    } catch (err) {
-      errors.push({ plugin: p.name, error: String(err?.message || err) });
-    }
-  }
-  return { value, changed, errors };
-}
+import { readdirSync, existsSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import os from "node:os";
+
+// mslxdff 插件系统：约定目录下的 *.mjs / *.js 模块，default export：
+//   { name?, version?, description?, hooks?: { "<hook-name>": async (ctx) => nextValue? } }
+// hook 返回数组时可替换流程值（如 model:select 的候选顺序）；返回 undefined 表示只观察。
+// 插件错误一律隔离：加载失败进 errors，hook 抛错不影响主链路。
+
+export function pluginsDir() {
+  return process.env.MSLXDFF_PLUGINS_DIR ||
+    join(os.homedir(), ".config", "mslxdff", "plugins");
+}
+
+// 安装目录下的 plugins/（随仓库/内置分发；auto-update 重装会丢，仅作开发/内置用）
+export function bundledPluginsDir(pkgRoot) {
+  if (!pkgRoot) return null;
+  return join(pkgRoot, "plugins");
+}
+
+// 解析扫描目录列表：env 完全接管；否则安装目录 plugins/ + 用户目录（同名文件用户目录优先）
+export function resolvePluginDirs({ pkgRoot } = {}) {
+  const env = process.env.MSLXDFF_PLUGINS_DIR;
+  if (env) return [env];
+  const dirs = [];
+  const bundled = bundledPluginsDir(pkgRoot);
+  if (bundled) dirs.push(bundled);
+  dirs.push(pluginsDir());
+  return dirs;
+}
+
+const PLUGIN_EXTS = new Set([".mjs", ".js"]);
+
+async function loadFromDir(dir, skipFiles) {
+  const plugins = [];
+  const errors = [];
+  if (!dir || !existsSync(dir)) return { plugins, errors };
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => PLUGIN_EXTS.has(extname(f).toLowerCase()));
+  } catch (err) {
+    errors.push({ file: dir, error: String(err?.message || err) });
+    return { plugins, errors };
+  }
+  files.sort();
+  for (const f of files) {
+    const file = join(dir, f);
+    if (skipFiles?.has(f)) continue; // 用户目录同名文件优先
+    try {
+      const mod = await import(pathToFileURL(file).href);
+      const plugin = mod?.default;
+      if (!plugin || typeof plugin !== "object") {
+        errors.push({ file, error: "no default export object" });
+        continue;
+      }
+      plugins.push({
+        name: typeof plugin.name === "string" && plugin.name ? plugin.name : basename(f, extname(f)),
+        version: typeof plugin.version === "string" ? plugin.version : "",
+        description: typeof plugin.description === "string" ? plugin.description : "",
+        hooks: plugin.hooks && typeof plugin.hooks === "object" ? plugin.hooks : {},
+        file,
+      });
+    } catch (err) {
+      errors.push({ file, error: String(err?.message || err) });
+    }
+  }
+  return { plugins, errors };
+}
+
+export async function loadPlugins({ dir, dirs } = {}) {
+  // 兼容旧签名 loadPlugins({ dir })；新签名 dirs 数组按优先级从低到高（后者覆盖前者同名文件）
+  const list = dirs || (dir ? [dir] : [pluginsDir()]);
+  let plugins = [];
+  const errors = [];
+  const seen = new Set(); // 已加载的 basename，先扫的目录跳过它们 → 后目录（高优先）覆盖
+  for (let i = list.length - 1; i >= 0; i--) {
+    const r = await loadFromDir(list[i], seen);
+    for (const p of r.plugins) seen.add(basename(p.file));
+    plugins = [...r.plugins, ...plugins]; // 低优先目录在前，目录内保持文件名序
+    errors.push(...r.errors);
+  }
+  return { plugins, errors };
+}
+
+// 串行执行某 hook。返回 { value, changed, errors }：
+// - value：最后一个返回非 undefined 值的插件的返回值（链式传递；数组、对象、布尔均可）
+// - changed：是否有插件返回了非 undefined 值（调用方可据此采用 value）
+export async function runHook(plugins, name, ctx) {
+  let value;
+  let changed = false;
+  const errors = [];
+  for (const p of plugins || []) {
+    const fn = p.hooks?.[name];
+    if (typeof fn !== "function") continue;
+    try {
+      const out = await fn(ctx);
+      if (out !== undefined) {
+        value = out;
+        changed = true;
+      }
+    } catch (err) {
+      errors.push({ plugin: p.name, error: String(err?.message || err) });
+    }
+  }
+  return { value, changed, errors };
+}

package/src/providers/AGENTS.md

@@ -0,0 +1,49 @@
+# src/providers — 供应商契约（改任何 provider 前必读）
+
+> 从 `AGENTS.md` 下沉（2026-09-29 分层，就近生效）。改完跑：`npm run docs:check` + 相关 provider 测试 + 裸调验证 `-provider <id> models`。
+> 相关 ADR：0007(前缀路由)/0010(allowlist)/0019(share-keys)/0023(key 直连)/0026(cline id)/0029(qoder)/0033(cline 自动同步)/0037(qwenwork)/0038(zcode)/0041(globalqwenwork)。
+
+## 通用机制（dispatcher / keyring / 门禁）
+
+- `src/providers/` 每供应商一文件，前缀路由 `<provider>/raw`（裸 id 归 opencode），dispatcher 剥前缀转发；`providerKeys: {id:[k1,k2]}` round-robin 30s 冷却；`shareKeys` via `x-mslxdff-share-keys` 瞬时借用且 opencode 恒排除。
+- `providerConfigs.allowAnyModels` 默认 `false`（`opencode:true` 例外）+ `allowlist` 空即 `403`；`isModelAllowed` 对未配置 provider 放行（兼容测试），`listModels` 同步过滤；`providerConfigs.{modelsPath,chatPath}` 可配异形路径（`workbuddy=/v3/config` & `/v2/chat/completions`，其余默认 `/models` & `/chat/completions`，`b.ai=/v1/models`、`cline=/api/v1/models` 已验证）。
+- `src/models.js` 的 `aggLoad`/`get` 二次过滤：`!allowed.length && !allowAny → 跳过整供应商`；`src/routes/chat/index.js` 的 `isAllowlistBlock` 在 `useAuto` 时软跳 `continue`（显式请求才硬 `403`）。
+- 定制 provider 启用门禁下沉为纯函数 `src/runtime/provider-gate.js` —— auth 号型（workbuddy/traework/qoder）**不要求 baseUrl**，旧门禁 `baseUrl && keys` 曾把 qoder 整家静默跳过（表现：`/v1/models` 零条目 + `Model qoder/x is not supported`，无日志）。
+- CLI：`provider <id> models` 与 `model list --provider` 为直查一级答案（`--json` 供脚本），HTTP `GET /v1/providers/:id/models`；价格列 `x0.00/浮动/—` 对齐展示（workbuddy 按 credits 升序）。
+- 新增 provider 三步走：registry 注册 + classify（local-only 判据见 ADR-0023）+ allowlist 只增不减补齐；必须裸调验证 `free` 是否免 Key；`free` 4 个仅目录免 Key ≠ 对话免 Key（cline 教训）。
+
+## qoder（原生 COSY 栈，ADR-0029/0036）
+
+- 凭证单一源 `auths/qoder-<uid>.json`（0600，含每号 `region` —— `state.normalizeAuths` 会剥该字段，故 region 只能存 auths 文件）；签到按每号 region 选域名（cn=`openapi.qoder.com.cn` 走 `daily-check-in/status→claim`，409=今日已领；global=`openapi.qoder.sh` 该端点 404 → 回落 `/sash/api/v1/me/campaigns→/{id}/claim`）；认证只需 `Bearer <device_token>` + `cosy-clienttype: 10`（**无 COSY 签名、claim 空 body**）；默认只领 `CLAIM_BENEFIT`，促销条目 `VIEW_DETAILS` 需 `-provider qoder checkin --any`（实测能 claim，但奖励是订阅折扣、不进 quota）；余额 `GET /api/v2/quota/usage`；daemon 每日 09:00 自动（`MSLXDFF_QODER_CHECKIN=0` 关，`_CHECKIN_HOUR` 改点）。
+- **流式坏号判决面有两条**：①首包 HTTP 非 200；②**HTTP 200 但 SSE 信封内 `statusCodeValue` 非 200**（限流裹成 `200` + `{"code":"403","message":{"isQueued":true,"retryAfterSeconds":30}}`，只盖①会漏掉②——实测后果：94 次 empty turn 502、0 次恢复）。②的取法：返回 Response **前预读上游首帧**取判决（`PEEK_MAX_FRAMES=8`，遇判决或首个有效载荷即停），预读字节原样回灌给 `reshapeQoderStream`（`prefetched` 参数），对外仍恒 200、状态码只走内部头 `x-mslxdff-qoder-upstream-status`（fetch 异常折 502）。`test/qoder-envelope-status.test.js` 4 例。
+- **同请求粘号**（`scope=reqId`，`MSLXDFF_QODER_STICKY_MS` 默认 600s，`0`=关）：一次客户端请求内复用同一号，仅 401/403/429/5xx 冷却才换；`pick=new|sticky|switch|forced` 经 `x-mslxdff-qoder-account` 回显、冷却经 `x-mslxdff-qoder-cooldown` 回显。`test/qoder-cooldown-stream.test.js` 3 例。
+- **wire 四条硬规矩**（openspec qoder-p0-fixes，`test/qoder-p0-fixes.test.js` 19 例）：① 推理模型 `model_config.is_reasoning` 与 `chat_context.extra.modelConfig` 必须**双写**（只写前者上游不吐 reasoning_content）；数据源=`models.js peekModels` 快照（不吃 TTL、chat 路径恒 0 额外上游调用、冷目录降级 false 不阻断，preheat 灌缓存）；② 客户端无 tools 发 `tools:[]`——baseprompt 模板内嵌 14 工具永不出门；③ 上游 `finish_reason` 如实透传（length 截断从此可见），仅全程未给才兜底 stop/tool_calls，stream 与 aggregate 收尾判定同构；④ SSE 未完结行超 2MiB 即断（完整行消费后判、不连坐合法帧；流式流内 error 收尾、聚合 502 走短冷却）。
+- **判决三分类与冷却三档（ADR-0044）**：同一个 `10605` 容器既裹额度也裹排队，`sse.js` 判序固定「先 `findQuotaSignal`（内层 code 110 / Billing 措辞）→ 后 `findQueueSignal`（code 10605 / `isQueued:true` / `serviceAvailable:false`）」。排队**不新增 kind**（仍 `upstream`，只挂 `err.queued`），经内部头 `x-mslxdff-qoder-queued` 交出门面，对外仍恒 200。门面冷却分三档：额度 `quotaCooldownMs`(1h) > **排队 `queueCooldownMs`(300s)** > 其它 `cooldownMs`(30s)，且额度与排队**都在同一请求内当场换号**（`isQuota || isQueued` 且 `ring.available()>0` → `continue`）；空转（模型零输出）仍不换号不冷却（ADR-0036 否决方案 D 的口径不变，别把两者混为一谈）。全号都在冷却时 `pickKey` 的 `ring.next() || keys[0]` 仍会 `forced` 补一发（冷却是轮转偏好不是硬拒）。`test/qoder-queue-switch.test.js` 8 例；`test/qoder-envelope-status.test.js` 现为 5 例（前者首已按新行为改写）。
+- `GET /v1/models` 在 `modelPicks` 非空时按勾选集裁剪（`filterByPicks`，空勾选=不裁剪，`?all=1` 绕过），`-models` 交互候选取数恒走 `?all=1`；交互选择器按终端行高开窗分页（`src/chooser.js`，多选行形状 `❯ [✓] <id>`）。
+
+
+## qwenwork（cn）与 globalqwenwork（国际站）— 同协议两租户（ADR-0037/0041）
+
+- 千问办公两站 `gateway.qwenwork.cn` / `gateway.qwenwork.ai`：COSY 签名（**同一枚 RSA 模数**）、SSE 端点 `/algo/api/v2/service/pro/sse/agent_chat_generation`、chat body、refresh `{refresh_token}` **逐字同构**（现网双站实测 200），故 globalqwenwork 的协议模块从 qwenwork 逐字 vendor（仓库约定：provider 目录自包含、不跨目录 import）。**差异只在三处租户参数**：auth 域名、OAuth `client_id`（cn `e883ade2…` / intl `cc65e5fc…`）、深链 `redirect_uri`（`qwenwork-cn://` / `qwenwork://`）；**凭证与积分池两站不互通**（cn token 打 .ai → 401 INVALID_TOKEN）。
+- ⚠ **registry.js 子串陷阱**：qwenwork 的 matcher 是 `includes("qwenwork")`，而 `globalqwenwork` / `globalqwenwork://native` 都含该子串且 `getCustomProviderFactory` first-match-wins —— **globalqwenwork 条目必须排在 qwenwork 之前**，否则国际站 token 被 cn 工厂接管（乱 401 + refresh 污染 cn 号）。`test/globalqwenwork-provider.test.js` 第 2 例锁死该顺序；动 registry 顺序前先跑它。
+- 模型池零交集：cn `flash`/`pro`/`qwen3.8-max-preview`（pf 0.1/1/1.8，reasoning）↔ intl 仅 `qwork-auto`(→qwen3.8-flash)/`qwork-advanced`(→gpt-5.6-sol)（pf 0，非 reasoning，is_vl，max_input 180000）。登录各自种 allowlist、`allowAnyModels=false`（额度池防 auto 烧分）。国际站官方客户端自身走 gRPC `model.chat.ChatService/ChatCompletionStream`（其 `region/endpoints` 在 .ai 404），本仓不走 —— 见 ADR-0041 决策 1。
+## workbuddy
+
+- 专用 `POST /v2/chat/completions` **强制 `stream:true`** + `GET /v3/config` 按 credits 升序前缀 `workbuddy/`（**2026-10-10 换端点**：旧 `GET /console/enterprises/personal/models` 对多数 token 恒 401/500 → 目录 0 条 → `aggLoad` 判 `!allowed.length` 把整家跳过；`/v3/config` 返回**随 UA 变**，本仓 UA 与 chat 同身份故目录即"自己能调的那套"；`listModels` 已改逐 key 轮换，单个坏 token 不再清空目录）；401/403 自动 `POST /v2/plugin/auth/token/refresh` 回写 `state.json`+`auths/workbuddy-<uid>.json`（0600 tmp+rename）。
+- 凭据目录 `authDirFor()` 跟账本走 + `authDirCandidates()` 只读兜底旧位置 + `listAccountDocs()` 单一读取出口（provider/CLI/token-auto 四处复制品合一）；`-workbuddy remove` 扫全部候选目录防旧副本「复活」（ADR-0025，`test/workbuddy-authdir.test.js` 6 例）。
+- 接入禁手填 `<key>`，必须 `node workbuddy-token-auto.js` 自动化（whistle MITM :8899；whistle/MITM 取 codex token 路径已证伪）；桌面登录态跨平台发现 `src/providers/workbuddy/desktop-info.js`（显式 `--file`/env > 后缀快查 > 文件名 BFS depth≤6；Win `%LOCALAPPDATA%`/`%APPDATA%`、mac `~/Library/Application Support`、Linux `~/.config`）；设备授权加号（0.1.93）：`POST /v2/plugin/auth/state?platform=CLI` → 浏览器登录 → 轮询 `token?state=`，UA `CLI/2.63.2 CodeBuddy/2.63.2` 可 `MSLXDFF_WORKBUDDY_UA` 覆盖；每日 `workbuddy-checkin.js` 双域幂等 `code 10001` 视为成功。
+- `share` 默认 `off` 需 `MSLXDFF_WORKBUDDY_SHARE_KEYS=1`；`-setto workbuddy [modelId]` 原子写 `~/.workbuddy/models.json`（仅 127.0.0.1/v1）。
+- 出网 11128 指纹剥离（`payload.js` CC_SENTENCES 清单式）：上游扫 system/assistant，命中行首 `x-anthropic-billing-header:` 整行或官方固定整句（"You are Claude Code…" / "To give feedback…anthropics/claude-code/issues"）即 400 "unapproved channel"（实测整句纯子串匹配、user/tool 不扫、换说法放行）——只剥固定形态，新拦句加清单。
+
+## cline
+
+- 指纹头：UA `Cline/3.0.47` + `X-CLIENT-TYPE: cline-sdk` + `X-CLIENT-VERSION` 同 UA；对话链 = `POST /api/v1/auth/refresh`（**每次 refresh 轮换 refreshToken 必须回写**）→ `Bearer workos:<accessToken>` + 固定 `<base>/api/v1/chat/completions`（**baseUrl 已含 /api/v1 时只拼 `/chat/completions`，否则双 /api/v1 会 401/empty response**）；deepseek/z-ai 免费通道必须 `stream:true` + SSE 聚合否则 `500 empty response content`；`X-Task-ID`/`session_id` 每次唯一。
+- 发上游剥 `provider/` 前缀（`cline/deepseek/X→deepseek/X`）恢复 forceStream 聚合 + 非 JSON 响应体 TypeError 加固（`test/cline-chat-id.test.js` 4 用例，0.1.91）。
+- 白名单自动同步（ADR-0033）：`allowlist-sync.js` 纯函数 `planMerge`（只增不减）+ `createAllowlistSync`（无新增不写盘、异常吞掉留痕），由 `cline/index.js` 注入；`cline/models.js` 仅在**上游成功取数**路径调 `notifyRefresh`（内置兜底常量不写盘，防污染）；`MSLXDFF_CLINE_AUTOSYNC=0` 关；**教训：`saveProviderAllowedModels`/`saveProviderConfig` 重建 cfg 时起手 `{baseUrl,keys}` 未带 `allowAnyModels` 会静默抹成 false**（已修，勿回退）。
+- 登录走 WorkOS 设备授权流（client_id `client_01K3A541FN8TA3EPPHTD2325AR`），refreshToken 落 `providerConfigs.{cline}.keys`；bench 检测 keys 含 refreshToken 即走 refresh→指纹头→stream 测速专用分支。
+
+## bench 与额度保护（`src/bench/`）
+
+- `bench/bench --via` 仅测（allowlist ∩ 全局 picks）交集（`filterBenchModels`，picks 空回退 allowlist）；计费模型（无 `-free` 后缀）需显式点名才测（`max_tokens=5` 也计费）；`--via` 额度保护默认跳过 `opencode` 需 `--include-opencode` 且 TTY 二次确认 `y/N`；0.1.84 起完全串行 `直连→逐 peer`（`MSLXDFF_BENCH_DELAY_MS=120`）逐模型实时打印（`--json` 进度走 `stderr`）。
+- `aihubmix gemini 400 no_available_channel` 为上游无通道非 bench bug；peer name 统一短化 `host:port`。
+- **烧额度的实测必须先经用户明确同意**：付费/订阅/按量计费上游的裸调、A/B 长文生成一律先问（2026-09-23 教训）；免费池探针（public 免费模型、短 prompt 微量）可直接跑。

package/src/providers/base.js

@@ -1,164 +1,164 @@
-import { createKeyRing } from "./keyring.js";
-import { joinModelId } from "./model-id.js";
-import { getUndici as compatGetUndici, compatFetch } from "../compat.js";
-import { createSdkDispatch } from "../upstream-engine/sdk/dispatch.js";
-
-const { fetch: UndiciFetch, Agent: UndiciAgent } = compatGetUndici();
-
-export function envInt(name, fallback) {
-  const v = Number(process.env[name]);
-  return Number.isInteger(v) && v > 0 ? v : fallback;
-}
-
-export function joinUrl(base, path) {
-  const b = String(base || "").trim().replace(/\/+$/, "");
-  const p = String(path || "").trim();
-  if (!p) return b;
-  const pp = p.startsWith("/") ? p : `/${p}`;
-  return `${b}${pp}`;
-}
-
-export function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-export function getUndici() {
-  return { UndiciAgent, UndiciFetch, fetch: UndiciFetch || compatFetch, Agent: UndiciAgent };
-}
-
-export function createAgent({ keepAliveTimeout = 30_000, keepAliveMaxTimeout = 60_000, connections = 20 } = {}) {
-  if (!UndiciAgent) return { agent: null, dispatcher: null };
-  try {
-    const agent = new UndiciAgent({ keepAliveTimeout, keepAliveMaxTimeout, connections, pipelining: 1 });
-    return { agent, dispatcher: agent };
-  } catch {
-    return { agent: null, dispatcher: null };
-  }
-}
-
-export function collectApiKeysGeneric(id, apiKeys, apiKey, loadKeys) {
-  const list = [
-    ...(Array.isArray(apiKeys) ? apiKeys : [apiKeys].filter(Boolean)),
-    apiKey,
-    ...(apiKeys === undefined && apiKey === undefined ? loadKeys(id) : []),
-  ].filter((k) => typeof k === "string" && k.trim().length);
-  return [...new Set(list.map((k) => k.trim()))];
-}
-
-export function createChatRunner({ id, ring, cooldownMs, retry, fetchImpl, dispatcher, buildHeaders, getUrl, connectTimeoutMs = 30_000, sdkDispatch } = {}) {
-  // SDK 通道（缺省）：仅流式；非流式委派原生，避免把 JSON 客户端 SSE 化。
-  const sdk = sdkDispatch === undefined ? createSdkDispatch({ id, providerName: id }) : sdkDispatch;
-
-  async function attemptOnce(url, body, key, activeRing) {
-    if (sdk?.enabled && body?.stream !== false) {
-      let r;
-      try { r = await sdk.trySdk({ url, body, headers: buildHeaders(body, key), fetchImpl }); }
-      catch (err) { return err; } // 交 runChat 的 network 重试/冷却
-      if (r) return r.status === 401 && !activeRing.size ? { __needKey: true } : r;
-    }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error(`${id} timed out after ${connectTimeoutMs}ms`)), connectTimeoutMs);
-    try {
-      const opts = { method: "POST", headers: buildHeaders(body, key), body: JSON.stringify(body), signal: controller.signal };
-      if (dispatcher) opts.dispatcher = dispatcher;
-      const res = await fetchImpl(url, opts);
-      if (res.status === 401 && !activeRing.size) return { __needKey: true };
-      return res;
-    } catch (err) {
-      return err;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async function runChat(body, activeRing, sourceKey) {
-    const url = getUrl();
-    const t0 = performance.now();
-    const attempts = [];
-    let waitMs = 0;
-    const key = activeRing.next();
-    if (!key && activeRing.size > 0) {
-      const err = new Error(`${id}: all API keys are in cooldown (last error < ${cooldownMs}ms ago) — provider temporarily unavailable`);
-      err._t = { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - t0), cooldownMs };
-      throw err;
-    }
-    for (let attempt = 0; ; attempt++) {
-      const t = performance.now();
-      const result = await attemptOnce(url, body, key, activeRing);
-      const type = result instanceof Error ? "network" : `http${result?.status}`;
-      attempts.push({ attempt, type, ms: Math.round(performance.now() - t) });
-      if (result?.__needKey) {
-        const err = new Error(`${id}: missing ${sourceKey} (chat requires a real key)`);
-        err._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
-        throw err;
-      }
-      if (result instanceof Error) {
-        const entry = retry?.network;
-        if (entry && attempt < entry.attempts) { await sleep(entry.delayMs); waitMs += entry.delayMs; continue; }
-        activeRing.onError(key);
-        result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
-        throw result;
-      }
-      const entry = retry?.[result.status];
-      if (entry && attempt < entry.attempts) { await sleep(entry.delayMs); waitMs += entry.delayMs; continue; }
-      if (result.status === 401 || result.status === 403 || result.status === 429 || result.status >= 500) activeRing.onError(key);
-      result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
-      return result;
-    }
-  }
-
-  return { attemptOnce, runChat };
-}
-
-export function createListModelsRunner({ id, ring, dispatcher, fetchImpl, getUrl, mapModel }) {
-  const CACHE_TTL_MS = 10 * 60 * 1000;
-  let cache = null;
-  let fetchedAt = 0;
-  async function listModels() {
-    const now = Date.now();
-    if (cache && now - fetchedAt < CACHE_TTL_MS) return cache;
-    const url = getUrl();
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error(`${id} models timed out`)), 15_000);
-    try {
-      const headers = { Accept: "application/json" };
-      const key = ring.next();
-      if (key) headers["Authorization"] = `Bearer ${key}`;
-      const opts = { headers, signal: controller.signal };
-      if (dispatcher) opts.dispatcher = dispatcher;
-      const res = await fetchImpl(url, opts);
-      if (!res.ok) return [];
-      const json = await res.json().catch(() => ({}));
-      const raw = Array.isArray(json.data) ? json.data : Array.isArray(json) ? json : [];
-      const mapped = mapModel ? mapModel(raw) : raw;
-      cache = mapped.filter((m) => m && typeof m.id === "string").map((m) => ({ ...m, id: joinModelId(id, m.id) }));
-      fetchedAt = now;
-      return cache;
-    } catch {
-      return [];
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  return { listModels, _cache: () => cache };
-}
-
-export function createPreheatRunner({ dispatcher, fetchImpl, getUrl, id, ring, loadKeys }) {
-  async function preheat() {
-    const url = getUrl();
-    const t0 = performance.now();
-    try {
-      const headers = { Accept: "application/json" };
-      const key = (loadKeys ? loadKeys(id)[0] : ring.next()) || ring.next();
-      if (key) headers["Authorization"] = `Bearer ${key}`;
-      const opts = { headers };
-      if (dispatcher) opts.dispatcher = dispatcher;
-      const res = await fetchImpl(url, opts);
-      try { if (res.body) await res.text().catch(() => {}); } catch {}
-      return { ok: res.ok, status: res.status, ms: Math.round(performance.now() - t0) };
-    } catch (err) {
-      return { ok: false, error: String(err?.message || err), ms: Math.round(performance.now() - t0) };
-    }
-  }
-  return { preheat };
-}
+import { createKeyRing } from "./keyring.js";
+import { joinModelId } from "./model-id.js";
+import { getUndici as compatGetUndici, compatFetch } from "../compat.js";
+import { createSdkDispatch } from "../upstream-engine/sdk/dispatch.js";
+
+const { fetch: UndiciFetch, Agent: UndiciAgent } = compatGetUndici();
+
+export function envInt(name, fallback) {
+  const v = Number(process.env[name]);
+  return Number.isInteger(v) && v > 0 ? v : fallback;
+}
+
+export function joinUrl(base, path) {
+  const b = String(base || "").trim().replace(/\/+$/, "");
+  const p = String(path || "").trim();
+  if (!p) return b;
+  const pp = p.startsWith("/") ? p : `/${p}`;
+  return `${b}${pp}`;
+}
+
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export function getUndici() {
+  return { UndiciAgent, UndiciFetch, fetch: UndiciFetch || compatFetch, Agent: UndiciAgent };
+}
+
+export function createAgent({ keepAliveTimeout = 30_000, keepAliveMaxTimeout = 60_000, connections = 20 } = {}) {
+  if (!UndiciAgent) return { agent: null, dispatcher: null };
+  try {
+    const agent = new UndiciAgent({ keepAliveTimeout, keepAliveMaxTimeout, connections, pipelining: 1 });
+    return { agent, dispatcher: agent };
+  } catch {
+    return { agent: null, dispatcher: null };
+  }
+}
+
+export function collectApiKeysGeneric(id, apiKeys, apiKey, loadKeys) {
+  const list = [
+    ...(Array.isArray(apiKeys) ? apiKeys : [apiKeys].filter(Boolean)),
+    apiKey,
+    ...(apiKeys === undefined && apiKey === undefined ? loadKeys(id) : []),
+  ].filter((k) => typeof k === "string" && k.trim().length);
+  return [...new Set(list.map((k) => k.trim()))];
+}
+
+export function createChatRunner({ id, ring, cooldownMs, retry, fetchImpl, dispatcher, buildHeaders, getUrl, connectTimeoutMs = 30_000, sdkDispatch } = {}) {
+  // SDK 通道（缺省）：仅流式；非流式委派原生，避免把 JSON 客户端 SSE 化。
+  const sdk = sdkDispatch === undefined ? createSdkDispatch({ id, providerName: id }) : sdkDispatch;
+
+  async function attemptOnce(url, body, key, activeRing) {
+    if (sdk?.enabled && body?.stream !== false) {
+      let r;
+      try { r = await sdk.trySdk({ url, body, headers: buildHeaders(body, key), fetchImpl }); }
+      catch (err) { return err; } // 交 runChat 的 network 重试/冷却
+      if (r) return r.status === 401 && !activeRing.size ? { __needKey: true } : r;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`${id} timed out after ${connectTimeoutMs}ms`)), connectTimeoutMs);
+    try {
+      const opts = { method: "POST", headers: buildHeaders(body, key), body: JSON.stringify(body), signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (res.status === 401 && !activeRing.size) return { __needKey: true };
+      return res;
+    } catch (err) {
+      return err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function runChat(body, activeRing, sourceKey) {
+    const url = getUrl();
+    const t0 = performance.now();
+    const attempts = [];
+    let waitMs = 0;
+    const key = activeRing.next();
+    if (!key && activeRing.size > 0) {
+      const err = new Error(`${id}: all API keys are in cooldown (last error < ${cooldownMs}ms ago) — provider temporarily unavailable`);
+      err._t = { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - t0), cooldownMs };
+      throw err;
+    }
+    for (let attempt = 0; ; attempt++) {
+      const t = performance.now();
+      const result = await attemptOnce(url, body, key, activeRing);
+      const type = result instanceof Error ? "network" : `http${result?.status}`;
+      attempts.push({ attempt, type, ms: Math.round(performance.now() - t) });
+      if (result?.__needKey) {
+        const err = new Error(`${id}: missing ${sourceKey} (chat requires a real key)`);
+        err._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw err;
+      }
+      if (result instanceof Error) {
+        const entry = retry?.network;
+        if (entry && attempt < entry.attempts) { await sleep(entry.delayMs); waitMs += entry.delayMs; continue; }
+        activeRing.onError(key);
+        result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw result;
+      }
+      const entry = retry?.[result.status];
+      if (entry && attempt < entry.attempts) { await sleep(entry.delayMs); waitMs += entry.delayMs; continue; }
+      if (result.status === 401 || result.status === 403 || result.status === 429 || result.status >= 500) activeRing.onError(key);
+      result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+      return result;
+    }
+  }
+
+  return { attemptOnce, runChat };
+}
+
+export function createListModelsRunner({ id, ring, dispatcher, fetchImpl, getUrl, mapModel }) {
+  const CACHE_TTL_MS = 10 * 60 * 1000;
+  let cache = null;
+  let fetchedAt = 0;
+  async function listModels() {
+    const now = Date.now();
+    if (cache && now - fetchedAt < CACHE_TTL_MS) return cache;
+    const url = getUrl();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`${id} models timed out`)), 15_000);
+    try {
+      const headers = { Accept: "application/json" };
+      const key = ring.next();
+      if (key) headers["Authorization"] = `Bearer ${key}`;
+      const opts = { headers, signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (!res.ok) return [];
+      const json = await res.json().catch(() => ({}));
+      const raw = Array.isArray(json.data) ? json.data : Array.isArray(json) ? json : [];
+      const mapped = mapModel ? mapModel(raw) : raw;
+      cache = mapped.filter((m) => m && typeof m.id === "string").map((m) => ({ ...m, id: joinModelId(id, m.id) }));
+      fetchedAt = now;
+      return cache;
+    } catch {
+      return [];
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return { listModels, _cache: () => cache };
+}
+
+export function createPreheatRunner({ dispatcher, fetchImpl, getUrl, id, ring, loadKeys }) {
+  async function preheat() {
+    const url = getUrl();
+    const t0 = performance.now();
+    try {
+      const headers = { Accept: "application/json" };
+      const key = (loadKeys ? loadKeys(id)[0] : ring.next()) || ring.next();
+      if (key) headers["Authorization"] = `Bearer ${key}`;
+      const opts = { headers };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      try { if (res.body) await res.text().catch(() => {}); } catch {}
+      return { ok: res.ok, status: res.status, ms: Math.round(performance.now() - t0) };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err), ms: Math.round(performance.now() - t0) };
+    }
+  }
+  return { preheat };
+}