mslxdff 0.1.174 → 0.1.175

package/src/warp-pool/rotate.js

@@ -0,0 +1,150 @@
+// warp-pool · 轮换 dispatcher：把每个请求委派给不同出口节点的 ProxyAgent。
+// 契约（MODULES.md §1）：只需 dispatch(opts, handler) + close()/destroy()。
+// 注入点：src/transport/index.js 的 extDispatcher —— legacy（transport.request）与 SDK（sdk/attempt.js
+// 的 dispatcherFetch）两条路共用同一个 dispatcher 对象，故一处实现、两条路生效。
+//
+// 空池语义：bootstrap（注册设备/起隧道）完成前 list 为空 → 走直连兜底，行为与未启用本功能时一致；
+// bootstrap 完成后 setNodes() 换上真实出口。这样 daemon 启动不会因注册/下载而被阻塞。
+import { getUndici } from "../compat.js";
+import { createSelector } from "./strategy.js";
+
+const SESSION_HEADER = "x-opencode-session";
+
+/** undici 的 dispatch opts.headers 是扁平数组 [k, v, k, v, ...]。 */
+export function headerValue(headers, name) {
+  if (!Array.isArray(headers)) return "";
+  const target = String(name).toLowerCase();
+  for (let i = 0; i + 1 < headers.length; i += 2) {
+    if (String(headers[i]).toLowerCase() === target) return String(headers[i + 1] ?? "");
+  }
+  return "";
+}
+
+/**
+ * @param {{ nodes?: Array<{port:number, uri:string}>, strategy?: "session"|"request",
+ *           cooldownMs?: number, now?: () => number, log?: (s:string)=>void,
+ *           agentOptions?: object, selector?: object }} [opts]
+ */
+export function createRotatingDispatcher({
+  nodes = [],
+  strategy = "session",
+  cooldownMs = 600_000,
+  now = Date.now,
+  log = () => {},
+  agentFactory,
+  fallbackAgent,
+  agentOptions = { connections: 8, keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000, pipelining: 1 },
+  selector = createSelector({ strategy }),
+} = {}) {
+  const { ProxyAgent, Agent } = getUndici();
+  if (typeof ProxyAgent !== "function") throw new Error("undici ProxyAgent 不可用：无法建立出口池");
+  // 空池兜底：直连（等价 R3 里被顶掉的 keepAlive 池）。
+  const fallback = fallbackAgent !== undefined ? fallbackAgent : typeof Agent === "function" ? new Agent(agentOptions) : null;
+  let list = [];
+
+  function build(nodesIn) {
+    return (nodesIn || []).map((n, i) => ({
+      index: i,
+      port: Number(n.port),
+      uri: String(n.uri),
+      agent: agentFactory ? agentFactory(n.uri) : new ProxyAgent({ uri: n.uri, ...agentOptions }),
+      cooldownUntil: 0,
+      fails: 0,
+    }));
+  }
+
+  function availableIndexes() {
+    const t = now();
+    const out = [];
+    for (const e of list) if (e.cooldownUntil <= t) out.push(e.index);
+    return out;
+  }
+
+  function markFailure(index) {
+    const e = list[index];
+    if (!e) return;
+    e.fails += 1;
+    e.cooldownUntil = now() + cooldownMs;
+    log(`[warp-pool] 节点 :${e.port} 连续失败 ${e.fails} 次，冷却 ${Math.round(cooldownMs / 1000)}s`);
+  }
+
+  function markOk(index) {
+    const e = list[index];
+    if (e) {
+      e.fails = 0;
+      e.cooldownUntil = 0;
+    }
+  }
+
+  async function closePool(entries) {
+    await Promise.all(
+      entries.map((e) => {
+        try {
+          return Promise.resolve(e.agent.close?.()).catch(() => {});
+        } catch {
+          return Promise.resolve();
+        }
+      }),
+    );
+  }
+
+  return {
+    /** 每次请求调一次 = 轮换粒度。 */
+    dispatch(opts, handler) {
+      if (!list.length) {
+        if (fallback) return fallback.dispatch(opts, handler);
+        throw new Error("warp-pool：节点池为空且无直连兜底");
+      }
+      const avail = availableIndexes();
+      // 全池冷却时兜底用第一个，避免直接失败（宁可撞限流也别把请求打死）。
+      if (!avail.length) return list[0].agent.dispatch(opts, handler);
+      const sessionKey = strategy === "session" ? headerValue(opts?.headers, SESSION_HEADER) : "";
+      const idx = selector.pick(avail, sessionKey);
+      return list[idx].agent.dispatch(opts, handler);
+    },
+
+    /** 运行期换上一批出口（bootstrap 完成后调用）；旧 Agent 池关闭。 */
+    async setNodes(nodesIn) {
+      const old = list;
+      list = build(nodesIn);
+      await closePool(old);
+      return list.length;
+    },
+
+    /** 只读快照，供 health 探活用。 */
+    entries() {
+      return list.map((e) => ({ index: e.index, port: e.port, uri: e.uri, cooldownUntil: e.cooldownUntil, fails: e.fails }));
+    },
+
+    async close() {
+      await closePool(list);
+      list = [];
+      if (fallback) {
+        try {
+          await fallback.close?.();
+        } catch {}
+      }
+    },
+
+    async destroy() {
+      return this.close();
+    },
+
+    stats() {
+      const t = now();
+      return list.map((e) => ({
+        port: e.port,
+        uri: e.uri,
+        cooling: e.cooldownUntil > t,
+        cooldownMsLeft: Math.max(0, e.cooldownUntil - t),
+        fails: e.fails,
+      }));
+    },
+
+    markFailure,
+    markOk,
+    get size() {
+      return list.length;
+    },
+  };
+}

package/src/warp-pool/strategy.js

@@ -0,0 +1,43 @@
+// warp-pool · 选节点策略。
+//
+// session（默认）：同一 `x-opencode-session` 恒粘同一出口。
+//   依据 src/upstream.js L14-16 的实测注释——上游按 session 做粘性路由（固定 session 两次请求 ~1.2s；
+//   每次随机时可能撞冷机器 26s+）。故"每请求换出口"会把请求打成冷启动。
+// request：每请求轮转，仅供实验（延迟代价见上）。
+const STICKY_MAX = 2000;
+
+export function createSelector({ strategy = "session" } = {}) {
+  const sticky = new Map();
+  let cursor = 0;
+
+  /** @param {number[]} available 可用节点下标 @param {string} sessionKey */
+  function pick(available, sessionKey) {
+    if (!Array.isArray(available) || available.length === 0) return null;
+    if (strategy === "session" && sessionKey) {
+      const hit = sticky.get(sessionKey);
+      if (hit !== undefined && available.includes(hit)) return hit;
+      const chosen = available[cursor++ % available.length];
+      sticky.set(sessionKey, chosen);
+      if (sticky.size > STICKY_MAX) {
+        const oldest = sticky.keys().next().value;
+        sticky.delete(oldest);
+      }
+      return chosen;
+    }
+    return available[cursor++ % available.length];
+  }
+
+  return {
+    pick,
+    forget(sessionKey) {
+      if (sessionKey === undefined) sticky.clear();
+      else sticky.delete(sessionKey);
+    },
+    get tracked() {
+      return sticky.size;
+    },
+    get strategy() {
+      return strategy;
+    },
+  };
+}

package/src/warp-pool/wireproxy.js

@@ -0,0 +1,153 @@
+// warp-pool · wireproxy 进程管理：取二进制 → 生成配置 → 启动 → 守护/销毁。
+// wireproxy（octeep/wireproxy，Go，用户态 WireGuard，无需 root/TUN）把 WARP 隧道暴露为本地 HTTP 代理。
+// 为什么是 [http] 而非 [Socks5]：项目 undici 为 v5（实测 5.29.0），其 ProxyAgent 只接受 http/https，
+// 「SOCKS5 支持」是 undici 后续版本才加的（实测 socks5:// 直接抛 Invalid URL protocol）。
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, createWriteStream, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { compatFetch, getUndici } from "../compat.js";
+import { ensureDir, nodePaths, renderWireproxyConf, writeSecret } from "./nodes.js";
+
+export const WIREPROXY_VERSION = "v1.1.3";
+const RELEASE_BASE = "https://github.com/octeep/wireproxy/releases/download";
+
+const ASSETS = {
+  "linux-x64": "wireproxy_linux_amd64.tar.gz",
+  "linux-arm64": "wireproxy_linux_arm64.tar.gz",
+  "darwin-x64": "wireproxy_darwin_amd64.tar.gz",
+  "darwin-arm64": "wireproxy_darwin_arm64.tar.gz",
+};
+
+/** 依平台选发布包；不支持的平台返回 null（改用 MSLXDFF_WARP_BIN 自备二进制）。 */
+export function resolveAsset(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  return ASSETS[key] || null;
+}
+
+/** 本地二进制路径（bin/ 下按平台固定名）。 */
+export function binaryPath(dir) {
+  return join(dir, "bin", process.platform === "win32" ? "wireproxy.exe" : "wireproxy");
+}
+
+/**
+ * 确保 wireproxy 可用：优先 env 指定 → 本地已下载 → 自动下载解包。
+ * @returns {Promise<string>} 可执行文件绝对路径
+ */
+export async function ensureBinary({ dir, bin = "", autodownload = true, fetchImpl = compatFetch, log = () => {}, platform = process.platform, arch = process.arch } = {}) {
+  if (bin) {
+    if (!existsSync(bin)) throw new Error(`MSLXDFF_WARP_BIN 指向的文件不存在：${bin}`);
+    return bin;
+  }
+  const local = binaryPath(dir);
+  if (existsSync(local)) return local;
+
+  if (!autodownload) throw new Error(`未找到 wireproxy（${local}），且已关闭自动下载：请设 MSLXDFF_WARP_BIN 或开启 MSLXDFF_WARP_AUTODOWNLOAD`);
+  const asset = resolveAsset(platform, arch);
+  if (!asset) throw new Error(`暂不支持自动下载 wireproxy（平台 ${platform}-${arch}）：请自备二进制并设 MSLXDFF_WARP_BIN`);
+
+  ensureDir(join(dir, "bin"));
+  const url = `${RELEASE_BASE}/${WIREPROXY_VERSION}/${asset}`;
+  const tarball = join(dir, "bin", asset);
+  log(`[warp-pool] 下载 wireproxy ${WIREPROXY_VERSION}（${asset}）`);
+  const res = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
+  if (!res.ok) throw new Error(`下载 wireproxy 失败：HTTP ${res.status}`);
+  await pipeline(res.body, createWriteStream(tarball));
+
+  // 解包用系统 tar（Linux/macOS 必带；不引入 npm 依赖去解析 tar 格式）。
+  await runCommand("tar", ["-xzf", tarball, "-C", join(dir, "bin")], { log });
+  try { rmSync(tarball, { force: true }); } catch {}
+
+  const extracted = findWireproxy(join(dir, "bin"));
+  if (!extracted) throw new Error(`解包后未找到 wireproxy 可执行文件（目录：${join(dir, "bin")}）`);
+  if (extracted !== local) {
+    try { chmodSync(extracted, 0o755); } catch {}
+  }
+  try { chmodSync(local, 0o755); } catch {}
+  return existsSync(local) ? local : extracted;
+}
+
+function findWireproxy(binDir) {
+  try {
+    const hit = readdirSync(binDir).find((f) => f === "wireproxy" || f === "wireproxy.exe");
+    return hit ? join(binDir, hit) : null;
+  } catch {
+    return null;
+  }
+}
+
+function runCommand(cmd, args, { log = () => {} } = {}) {
+  return new Promise((resolve, reject) => {
+    let err = "";
+    const p = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    p.stderr.on("data", (d) => { err += String(d); });
+    p.on("error", reject);
+    p.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} 退出码 ${code}${err ? `：${err.slice(0, 200)}` : ""}`));
+    });
+  });
+}
+
+/** 写出某节点的 wireproxy 配置（含私钥 ⇒ 0600）。 */
+export function writeTunnelConf(dir, node) {
+  const { conf } = nodePaths(dir, node.port);
+  return writeSecret(conf, renderWireproxyConf({ ...node, port: node.port }));
+}
+
+/**
+ * 启动一条隧道。返回 { port, conf, stop() }。
+ * 进程退出即视为隧道失效（不自动重启：由 health 层决策重拨换 IP）。
+ */
+export function startTunnel({ binPath: exe, dir, port, log = () => {}, onExit = () => {} } = {}) {
+  const { conf } = nodePaths(dir, port);
+  const child = spawn(exe, ["-c", conf], { stdio: ["ignore", "pipe", "pipe"] });
+  let tail = "";
+  const keepTail = (d) => {
+    tail = (tail + String(d)).slice(-800);
+  };
+  child.stdout.on("data", keepTail);
+  child.stderr.on("data", keepTail);
+
+  let stopped = false;
+  child.on("exit", (code, signal) => {
+    if (!stopped) onExit({ port, code, signal, tail });
+  });
+
+  return {
+    port,
+    conf,
+    get pid() {
+      return child.pid;
+    },
+    get alive() {
+      return !stopped && child.exitCode === null;
+    },
+    get tail() {
+      return tail;
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      try { child.kill("SIGTERM"); } catch {}
+    },
+  };
+}
+
+/** 探活一个已起的隧道：经该端口访问上游 models 路径（不烧 token）。 */
+export async function probeTunnel({ port, baseUrl = "https://opencode.ai", path = "/zen/v1/models", fetchImpl = compatFetch, timeoutMs = 8000, headers = {} } = {}) {
+  const { ProxyAgent } = getUndici();
+  const agent = new ProxyAgent({ uri: `http://127.0.0.1:${port}`, connections: 2, keepAliveTimeout: 10_000 });
+  try {
+    const res = await fetchImpl(`${String(baseUrl).replace(/\/+$/, "")}${path}`, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+      dispatcher: agent,
+    });
+    return { ok: res.ok, status: res.status };
+  } catch (e) {
+    return { ok: false, status: 0, error: String(e?.message || e) };
+  } finally {
+    try { await agent.close(); } catch {}
+  }
+}

package/docs/cli_help_mini.md

@@ -1,143 +0,0 @@
-# mslxdff CLI 精简手册（AI 专用）
-
-> 给 `mslxdff -chat` 的大模型看。含全部可用命令的**精确语法**，模型必须照此输出，禁止自创参数。人类详版见 `cli_help.md`。
-
-## 约定
-
-- 单/双横线等价：`-status`=`--status`，`-help`=`--help`/`-h`。
-- 所有命令前缀 `mslxdff`，工具调用时传 `command` 字段，值形如 `"-model set big-pickle"`（不含 `mslxdff` 前缀，执行侧自动补）。
-- `read_file` 仅限项目内：相对路径 `src/...`、`docs/...`、`package.json`、`logs` 等；绝对路径必须在 `D:\www\wwwroot\mslxdff` 或 `~/.config/mslxdff` 下，否则拒绝。
-- 禁止执行的唯一命令：`-uninstall` / `--uninstall`（任何包含此的是拒绝）。
-- 模糊匹配由你完成：用户说 `hy3` 你必须查模型列表找到 `hy3-free` 再输出，全称以实时 `可用模型` 为准。
-
-## 可用命令全表
-
-| 命令 | 语法 | 说明 |
-|---|---|---|
-| 无参启动 | `mslxdff` | 已有 daemon 显示 status，否则后台启动 |
-| daemon | `-d` / `--daemon` | 后台启动（只升不降，低版本不覆盖高版本） |
-| 状态 | `-status` / `--status` / `-s` | 打印 daemon/health/port/config、upstream providers（启用/key/baseUrl/allowlist/共享）、models（含 v0.1.59 体检表 avg首字/tps/啰嗦/p95）/群组/failover/recent calls(ts/model/status/dur)/last error/autostart/plugins — 全量聚合体检 |
-| 用量报表 | `-stats` / `--stats` `[--hours N] [--json] [--model <id>]` | 默认统计**今日 0 点至现在**，`--hours N` 切近 N 小时滚动（上限 168）；输出 `Token 用量`（请求/输入/输出/思考/合计）与 `响应性能`（首字/总耗时/加权速度/**首字样本 n/N**）两张自适应边框表并含合计，长 id 不截断；k/M 缩写，`--json` 精确值。**首字 = 本次上游尝试开始 → 网关转发首个真实数据帧**（含排队/建连/判决预读，ADR-0039），`0ms` 有效、非流式不进分子与分母，N=0 显示 `—`；**思考四态**：上报值 / `~` 估算（思考字符÷4）/ `0` 真无 / `—` 未知（不再拿 0 冒充「不思考」）；与 `-status`/`-model stats` 的 EMA 首字**不同源**；速度仍为窗口加权 `Σ输出÷Σ生成耗时`；不含失败请求与 `-chat` 直连 |
-| 日志 | `-log [N]` / `--log [N]` / `-logs N` | 最近 N 条事件 + `timeline.log` 人读时间线；按模型链路日志为 `logDir/<provider>-<model>.log`，逐阶段记录 request/route/upstream/peer/relay/result（安全摘要，不落 prompt/正文/凭据）。**事件面用黑名单**：默认全部可见，只排除 `peer-health`/`heartbeat`/`client-session`/`upstream-probe*`；决定类事件只渲染登记字段，含上游回显 `upstream=`/`account=`/`pick=`/`cooled=` |
-| 回路语料捕获（第四条观测通道，**缺省开**） | `MSLXDFF_TALK_FULL`（**未设置即捕获**；只有显式关闭词 `0`/`off`/`false`/`no`/`disable`（trim+lowercase）才停写、且不建目录；`1`/`true`/`on`/`yes` 与任意其它取值=开，旧 `=1` 姿势继续有效；改 env 后必须 `cmd /c .\restart-daemon.bat` 重启才生效）+ `MSLXDFF_TALK_CAP_CHARS`（响应正文桶上限：缺省开 2000000／显式关 400000，正数 env 覆盖优先）+ `MSLXDFF_TALK_FULL_MAX_MB`(50)/`MSLXDFF_TALK_FULL_KEEP`(3，`0`=不留旧份)/`MSLXDFF_TALK_FULL_MAX_LINE_MB`(16) | 机读全量语料落 `<日志根>/talk/full/<供应商>-<模型>-talkfull.jsonl`（`0600`、按字节轮转，不是 1h 环形）：一行 = 一次上游尝试的 `system prompt` 全文 + 工具定义 + 完整历史（含往轮 tool 结果）+ 思考/正文/工具调用。**只捕 `hops=0` 的本机自发流量**——组员 `forwardToPeer` 转进来的对话（`hops>0`）**不落盘**，别把它当「全部流量」；`mslxdff -chat` 属 `hops=0` 会被捕。磁盘/内存账：缺省开 ⇒ 单模型最坏 `(KEEP+1)×MAX_MB`=200MB、在途请求正文桶上界 200 万字符。凭据落盘前双层脱敏；截断必显式（`meta.truncated`/`meta.cap`，`talk.log` 头行 `truncated=1`）。**读数（ADR-0046）**：`talk/*.log` 头行新增 `finish=<值>`（缺值 `finish=-`）与条件性 `relayMs=`（仅当 ≠`elapsed` 时出现），`elapsed=` 取**本次上游尝试墙钟**（缓冲重放不再报 2ms），零正文轮显式落 `[回答 · 0 字 · 本轮无正文（finish=…）]`，语料恒写 `meta.relayMs`；`events.log`（写前剥正文）、`<provider>-<model>.log`（不落正文）两条口径逐字不变，`talk/*.log` 除头行新字段与 `elapsed` 口径外不变（仍 1h+5MB、只留末条 user 提问）。止血 = 设 `MSLXDFF_TALK_FULL=0` 重启 + 删 `<日志根>/talk/full`。ADR-0045/0046 |
-| 回路语料视图（**不是** mslxdff 子命令，禁止当 CLI 命令幻觉） | `node scripts/talkfull-view.js [--file <path>] [--model <供应商/模型id>] [--session <key>] [--tail N] [--all]` | 只读脚本（不建目录/不写文件/不改权限）：首行打印 `talk/full/` 目录总占用并提示**缺省已开**（`MSLXDFF_TALK_FULL=0` 可关）→ 按会话拼回路（`sessionKey` 形态 `sha1尾12-原值前8`）渲染 system 全文/工具清单/逐轮（与上一条前缀 diff 只打新增尾巴；逐轮 `elapsed` = 本次上游尝试墙钟，旧记录回落 `meta.relayMs` 并标注），并给「回路体检」五项读数（① 上下文膨胀曲线 ② 重复工具调用 同 name+同参数 ≥3 次 ③ 连续零输出轮 ≥2 ④ 思考循环措辞 ≥3 轮 ⑤ `finishReason=length` 且思考占比 ≥0.9），阈值随输出打印、缺判据不下结论；坏行跳过不致命；`--tail` 缺省 50，`--all` 出全文 |
-| 网关代跑 WebSearch（Claude Code 内置搜索的唯一活路） | `MSLXDFF_WEB_SEARCH`（缺省 `tavily,exa,parallel`；`off`/`none`/`0`=关）+ `_TIMEOUT_MS`(15000，**整条后端链共享**)+ `_MAX_RESULTS`(8)/`_MAX_CHARS`(700)+ `_TAVILY_URL`/`_PARALLEL_URL`/`_EXA_URL`（换自建/内网）+ `_TAVILY_KEY`/`_PARALLEL_KEY`/`_EXA_KEY` | Claude Code 的 `WebSearch` 是 Anthropic **server tool**（搜索由推理服务端执行），接第三方模型后没人跑搜索 → 网关认出那发**搜索旁路请求**（`tools` 里有 `web_search_*` server tool + 消息以 `Perform a web search for the query: ` 开头）后自己搜，合成 `server_tool_use`+`web_search_tool_result` 直接回，**不打模型**；搜不到/关了/空查询一律 **400** 带原因（不把没工具的旁路丢给模型＝不编 URL）。其余不实现的 server tool 发上游前剥除，`tool_choice` 点名未声明工具降 `auto`（修订 ADR-0047）。**隐私账**：查询词与本机公网 IP 会离开本机到第三方免 key 端点；不缓存（Zero-state）、不进 token 账与 `talk/full`，只落 `events.log` 的 `web-search`/`web-search-unavailable` 行（含 `chain` 逐后端耗时）+ 回显头 `x-mslxdff-web-search`。ADR-0049 |
-| 调试 | `-debug` / `--debug` | 前台跟随事件流，Ctrl+C 恢复后台 |
-| 插件 | `-plugins` / `--plugins` | 列插件与 hooks |
-| 停止 | `-stop` / `--stop` | 停 daemon |
-| 重启 | `-restart` / `--restart` | 重启 daemon |
-| 端口 | `-port N` / `--port N` | 持久化端口，运行中重启 |
-| token 读 | `-showtoken` / `--showtoken` | 打印 Bearer token |
-| token 刷 | `-refresh-token` / `--refresh-token` | 轮换并打印新 token |
-| 更新 | `-update` / `--update` | 更新到 npm latest |
-| 模型交互 | `-models` | TTY 交互多选勾常用模型（↑↓移动 ←→翻页 Space勾选 Enter保存，勾选框在名字前 `❯ [✓] <id>`；候选池=opencode免费池+已启用供应商allowlist原名/别名+已勾选+allowAny空白名单者的网关live模型，不存在/未启用provider不列出，启用后回来）；**勾选集即 `GET /v1/models` 对外目录**（非空只暴露勾选项，空=全量，`?all=1` 绕过取全量） |
-| 模型列表 | `-model list [--provider <id>] [--json]` | 列免费模型：默认先列 opencode 免费池，`────────────────────────────────────────` 分隔后列其他供应商 allowlist（原名 + 别名 `别名: dash`）；`--provider cline` 只看该供应商 allowlist，`--json` 输出 `{"object":"list","data":[...]}` |
-| 模型设默认 | `-model set <id>` | 设首选模型，自动入 picks |
-| 模型健康 | `-model status` | 每模型 normal/limit/error |
-| 模型刷新 | `-model refresh` | 强制拉上游刷新 |
-| 模型勾选 | `-model pick <id>` | 勾选入 picks |
-| 模型去勾 | `-model unpick <id>` | 从 picks 移除 |
-| 模型查勾 | `-model picks` | 列 picks |
-| 模型清空 | `-model pick clear` | 清空 picks |
-| 模型探活（必用 curl） | `curl` POST `http://localhost:8989/v1/chat/completions` body `{"model":"<id>","messages":[{"role":"user","content":"hi"}]}` | 测试指定模型是否通，**禁止** `mslxdff "hi" --model X` / `mslxdff --model X "hi"` 等幻觉命令 |
-| 供应商新增 | `-provider add <id> <baseUrl> <key> [allowedModel...] [--models-path <path>] [--chat-path <path>]` | 一键添加通用 OpenAI 兼容供应商（末尾可带白名单；默认 `allowAny OFF` 空名单=禁用，需 `allowlist set` 或 `allowAny on` 否则 `403`；`workbuddy`除外；`--models-path`/`--chat-path` 可配异形路径如 `/v1/models`） |
-| 供应商 | `-provider <id> [keys]` | 批量设 keys（覆盖） |
-| 供应商增 | `-provider <id> add <key>` | 追加单 key |
-| 供应商删 | `-provider <id> remove <seq\|key> [more]` | 按序号或值删，逗号/空格均可 |
- | 供应商列表 | `-provider <id> list` / `status` | 脱敏列 keys/baseUrl/共享（`codearts`/`cline` 等硬排除显示"不借出"；codearts 每条 key 带 user/uid/domain 摘要） |
-| 供应商模型 | `-provider <id> models [--json]` | 列该供应商可用模型（按 allowlist 过滤，`workbuddy/xxx` 前缀；`cline` 与聚合目录同源走 `recommended-models` 的 `free`+`clinePass`，**每次成功取数即把上游 id 自动并入 allowlist（只增不减，`MSLXDFF_CLINE_AUTOSYNC=0` 关）**，daemon 启动自检 free 增删写 `daemon.log`；`--json` 供脚本） |
-| 供应商测速 | `-provider <id> bench [--json] [--prompt <text>] [--max-tokens N] [--timeout N]` | 仅测（allowlist ∩ 全局 picks）交集的速度（TTFB/总耗时/TPS），空则探活 `/v1/models→/models` 并提示先 pick；**deepseek 网页通道不支持 bench**（防禁言，改用 `-provider deepseek health` 体检） |
-| 供应商选路 | `-provider <id> bench --via [--include-opencode] [--json] [--samples N] [--timeout N] [--apply]` / `-provider bench --via` | **家宽选路**：对比 `direct` vs 经每个在线 `peer` 的 `TTFB`（仅测 picks∩allowlist 交集，串行轻探针 `max_tokens=5`，`--json` 时进度走 `stderr`；默认跳过 `opencode`需 `--include-opencode`+TTY `y/N`；**deepseek 一律跳过**（防禁言）；结果不写 state；空组直接引导；`--apply` 落盘 `via-routes.json` 供显式锁模型单路径择路） |
-  | Cline 登录 | `-provider cline login` | Cline WorkOS 设备授权拿 refreshToken 落盘；`cline` 走 `refresh→workos:token`+指纹头，deepseek 家族免 403（含 `cline-free/deepseek-*`；非流式内部强制 stream 聚合成 JSON，对外仍按请求方 stream）；多账号重复 login 追加（同邮箱替换不追加，`list` 显示邮箱）；直连 workos 被墙则 `set HTTPS_PROXY=http://127.0.0.1:7890` 后重试 |
-| Cline 免费目录 | `-provider cline free [--json]` | 上游免费目录只读（`recommended-models` 的 `free`，5 个）：列目录 + 与当前 allowlist 的差异，不写 state |
-| Cline 免费同步 | `-provider cline free sync [--yes] [--json] [--keep-extra]` | 把免费目录同步为 `cline` 的 allowlist（写裸 id）：**默认 dry-run，`--yes` 才落盘**；`--keep-extra` 只增不删；**全量替换**（会挤掉 daemon auto-sync 并入的 `cline-pass/*`）；**上游不可达时拒绝写盘**（不把内置兜底落成白名单） |
-| Cline 用量 | `-provider cline quota [--json] [--account <hash>] [--model <substr>]` | 账号×模型双口径只读统计（`cline-usage.jsonl`）：free 显示本周期/已完成周期/累计，pass 显示近 24h/累计；`--json` 供脚本；空账本给引导 |
-| Cline 迁移 | `-provider cline migrate [--dry-run]` | 旧 `providerConfigs.clinebot` 合并进 `cline`（keys 去重 + 剔 `sk_`、allowlist 求并）后删旧键，幂等、改前备份；**cline 恒 local-only**（不走组员、不借 key、只走本地直连，历史别名同样硬排除） |
-| CodeArts 登录 | `-provider codearts login` | 华为云 CodeArts Agent（盘古助手）PKCE 浏览器授权：凭证 blob（refreshToken/codeVerifier/dpopJwk）落盘 `providerConfigs.codearts.keys`（一账号一 blob，多账号 keyring 轮转，默认 `allowAnyModels=true`）；此后 `codearts/<modelId>` 前缀（恒 `stream:true`，STS 临期自动刷新 + refresh_token 轮换原位写回，死号提示重登）；**恒 local-only** 不借 key（ADR-0027） |
-| CodeArts 模型 | `-provider codearts models [--json]` | 三路发现（builtin 归一 + 代理型 + 福利网关），benefit 模型自动 claim（幂等 `0000`），对外带 `tags:["free:benefit"]` |
-| TraeWork 登录 | `-provider traework login` | TRAE SOLO 通道浏览器授权（复刻 traework2api login.sh）：打印 trae.cn 授权链接 → 登录后粘贴 `127.0.0.1` 回调链接 → ExchangeToken → 落盘 `auths/trae-<uid>.json`（0600）+state 双写，自动签到+查积分；此后 `traework/<modelId>` 前缀（恒 `stream:true` SOLO SSE 透传/聚合，模型空/auto→`glm-5.2`，动态表+静态 32 回退；1005 plan 长冷却 12h、401 换号、429 短冷，过期前 24h 预刷新）；**恒 local-only** 不借出 key |
-| DeepSeek 登录 | `-provider deepseek login --token <userToken>` 或 `login <email\|mobile> <password>` | DeepSeek 官网免费对话接入（ADR-0014）：userToken 在 chat.deepseek.com F12→Local Storage；无参数打印图文引导；落盘后 `allowAny on` + `-restart`；模型 `deepseek/{chat,reasoner,chat-search,reasoner-search}`；单账号 1 路并发，多号轮换 |
-| DeepSeek 探活 | `-provider deepseek health [--json]` | 逐账号体检（防禁言）：检测禁言（自动冷却 5min）/限频前兆/凭据坏；网络失败不误伤；禁言解封后再探自动恢复 |
-| 供应商改址 | `-provider <id> set-url <baseUrl>` | 改通用供应商地址 |
-| 供应商改模型路径 | `-provider <id> set-models-path <path>` | 改 `models` 路径（如 `/v1/models`、`/v3/config`） |
-| 供应商改对话路径 | `-provider <id> set-chat-path <path>` | 改 `chat` 路径（如 `/v1/chat/completions`、`/v2/chat/completions`） |
-| 供应商清空 | `-provider <id> clear` | 清空该供应商 keys |
-| 供应商共享 | key 随转发自动借出（ADR-0019，无开关无白名单） | 借道时自动附带；opencode/workbuddy/cline/codearts/traework 硬排除 |
-| 供应商白名单 | `-provider <id> allowlist [list\|set\|add\|remove\|clear]` | 白名单空=阻塞除非 `allowAny on`，非空仅名单内可用（防昂贵模型） |
-| 空名单开关 | `-provider <id> allowAny on\|off` | 空 allowlist 时放行或阻塞（默认 `OFF`，`opencode` 例外 `ON`） |
-| 供应商总览 | `-providers list` / `-provider list` | 列所有已部署供应商及启用状态（含 allowlist 摘要） |
-| WorkBuddy 接入（禁手填） | `禁止直接 -provider add workbuddy` | 用户说“接入/配置/登录 workbuddy / key哪里来 / 怎么用workbuddy”时**禁止**让用户手填`<key>`或执行`-provider add workbuddy ...`，必须**直接文字回复**（不调工具）：`请在项目根目录执行 node workbuddy-token-auto.js（前提已装 WorkBuddy 5.3.14 并浏览器登录 https://copilot.tencent.com 一次），脚本会自动抓 token、写 auths/workbuddy-*.json + state.json、自动签到`；仅当用户已贴出以`eyJ`开头的JWT时才可用`-provider add workbuddy https://copilot.tencent.com <贴的key>` |
-| WorkBuddy 桌面导入 | `mslxdff -provider workbuddy import [--file=路径]` | 桌面已登录新号时最快：跨平台自动发现登录态（找不到时 `--file`/env `MSLXDFF_WORKBUDDY_DESKTOP_INFO` 显式指定），无需浏览器/抓包 |
-| WorkBuddy 多号追加（路径A） | `mslxdff -provider workbuddy login` | 用户说“追加/添加 workbuddy 账号/多号/再加一个号”时**必须走路径A**：`run_command: "mslxdff -provider workbuddy login"`（设备授权：打印浏览器链接→用户用新账号登录→自动轮询落盘 `auths/workbuddy-<newUid>.json` + `state.json keys/auths`，不走抓包，桌面端不用退旧号）③ `run_command: "-workbuddy list"` 验证多号 ④ `run_command: "-workbuddy balance"` 看余额；新号次日自动纳入 daemon 每日签到；抓包兜底路径B：`node workbuddy-token-auto.js --force`（需桌面先切新号登录）；**禁止**让用户手贴 JWT（除非用户主动贴 `eyJ` 则走 `-provider add workbuddy` 路径C） |
-| WorkBuddy 签到 | `-workbuddy checkin` / `-wb checkin` | 用户说“签到/每日签到/100积分/领积分”时**调用 run_command**；多号并行3，双域幂等 `code 10001 已签到`视为成功，`--json` 聚合余额；daemon 每日 09:00 自动全号签到（`MSLXDFF_WORKBUDDY_CHECKIN=0` 关，`_HOUR` 改时间） |
-| Qoder 签到 | `-provider qoder checkin [--json] [--region cn\|global] [--any] [--dry]` | 用户说“qoder 签到/领积分”时**调用 run_command**；**按每号 region 选域名**（cn=`openapi.qoder.com.cn` 走 `daily-check-in`，409=今日已领；global=`openapi.qoder.sh` 无该端点→回落 campaigns），默认只领 `CLAIM_BENEFIT`（`--any` 才含 VIEW_DETAILS 促销），`--dry` 只查不领；daemon 每日 09:00 自动（`MSLXDFF_QODER_CHECKIN=0` 关，`_CHECKIN_HOUR` 改时间） |
-| Qoder 接入 | `-provider qoder login [--region cn\|global]` | Qoder 设备授权（PKCE+poll）：打印兑换链接→浏览器登录→落盘 `auths/qoder-<uid>.json`+state；`--region cn` 走国内站 `qoder.com.cn`（默认国际站）；多号重复 login 追加，`qoder/<modelId>` 前缀路由，恒 local-only 不借出 |
-| 千问办公接入 | `-provider qwenwork login` | 千问办公设备授权（PKCE+poll，`gateway.qwenwork.cn`）：打印兑换链接→浏览器确认→落盘 `auths/qwenwork-<uid>.json`+state；**默认 `allowAnyModels=false` + 只种 `flash/pro/qwen3.8-max-preview`**（额度是账号积分池，防 auto 烧分）；登录尾部显示套餐名+积分剩余；`qwenwork/<modelId>` 前缀路由，恒 local-only 不借出 |
-| zcode 接入 | `-provider zcode login [--bigmodel]` | ZCode（智谱官方编程工作台）免费额度授权：打印 chat.z.ai 授权链接→浏览器登录→CLI 轮询（`oauth/cli/init`→`poll`）拿 JWT，落盘 `auths/zcode-<uid>.json`+state 并把内置目录（`GLM-5.3`/`GLM-5.3-Flash`/`GLM-5.2`/`GLM-5-Turbo`）并入 allowlist；`zcode/<modelId>` 前缀路由（Anthropic 网关，恒上游 stream，**免验证码**）；`--bigmodel` 切 bigmodel.cn；恒 local-only 不借出 |
-| zcode 额度 | `-provider zcode quota [--json]` | 查 ZCode 套餐名/状态/有效期 + 各模型余量（`billing/balance` 分组表格）；空套餐给领取指引、401 给重登指引 |
-| raccoon 接入 | `-provider raccoon login` | Raccoon（商汤小浣熊）扫码登录：生成 `qrcode_code`→终端二维码 + `login/mp?code=` 链接→**用微信「扫一扫」扫**并确认（浏览器直接打开链接会 404，站点 SPA 无该路由）→轮询拿 token，落盘 `auths/raccoon-<uid>.json`+state（`keys` 一律以文档为准，续期后自愈）并把兜底 6 模型并入 allowlist；`raccoon/<modelId>` 前缀路由（**OpenAI 兼容网关**，**免验证码**）；多号自动轮换：请求内撞积分不足/限流就当场换下一个号，**暂不支持手动指定用哪个号**；积分不足长冷 1h、限流短冷 30s；恒 local-only 不借出 |
-| raccoon 积分 | `-provider raccoon quota [--json]` / `checkin` | 逐号查积分五分项 / 领「桌面端登录奖励」——**这家没有每日签到**：每日 300 与注册礼包 3000 由服务端自动发（无端点，每日 300 当天 23:59:59 清零），唯一要领的登录奖励 3000 是**每号一次性**且 `login` 时已自动领掉，`checkin` 只是补领兜底；判据只认账单、不认上游 `code:0`（重复领会虚回成功）；未登录给 login 指引；daemon 每日 09:00 兜底扫描未领过的号（`MSLXDFF_RACCOON_CHECKIN=0` 关，`_CHECKIN_HOUR` 改点） |
-| WorkBuddy 成长任务 | `-workbuddy growth [--json]` / `-wb growth` | 成长任务全自动（拉列表→参与→触发→领奖，串行 1.2s/1s，已领幂等跳过）；可自动 `chat_5`/`automation_1`/`skill_1`/`Model_chat_GLM5.2`，需客户端任务标 MANUAL 不发包；daemon 每日 09:30 自动（`MSLXDFF_WORKBUDDY_GROWTH=0` 关，`_GROWTH_HOUR`/`_GROWTH_MODEL` 可配） |
-| WorkBuddy 猫猫旅行 | `-workbuddy travel [--json]` / `-wb travel` | 无猫自动同意协议+领养（+300，门槛未达自动补一次对话解锁）；到站领奖 / 空闲派出（location 4）/ 旅行中跳过 |
-| WorkBuddy 余额 | `-workbuddy balance [--json]` / `-wb balance` | 查多号余额（`total/dailyPacks/nextExpire`，TTL 5min） |
-| WorkBuddy 列表 | `-workbuddy list` / `-wb list` | 列账号（`uid/domain/enterpriseId`） |
-| WorkBuddy SDK 通道（缺省启用） | `MSLXDFF_WORKBUDDY_SDK`（未设置则继承 `MSLXDFF_UPSTREAM_ENGINE`） | 底层缺省走 `@ai-sdk/openai-compatible`（optionalDependencies，需 Node>=18，不可用自动回退原生）；设 `legacy`/关闭词回退原生 transport，上层轮换/刷新/reshape 不变 |
-| 上游引擎（默认，ADR-0017） | `MSLXDFF_UPSTREAM_ENGINE`（缺省 `sdk`） | opencode 流式 chat 走 `@ai-sdk/openai-compatible`、`muse-spark*` 走 `@ai-sdk/openai` 的 responses 适配器（响应标记头 `x-mslxdff-upstream-engine: sdk`，复用 legacy 连接池）；通用 OpenAI 兼容族与 cline 同源（供应商级 `MSLXDFF_<ID>_SDK` 未设置即继承本变量）；非流式自动委派 legacy，SDK 不可用回退并告警；显式 `legacy`/关闭词回退原实现 |
-| responses 类模型路由（ADR-0032） | `MSLXDFF_<ID>_RESPONSES_PATH`（缺省 `/responses`） | 通用带 key 供应商遇 responses 类模型（`muse-spark*` 等，判定与 `/v1/models` 的 `capabilities.upstreamApi` 同源）自动改打 `<baseUrl>/responses`（此前固定打 `chatPath` → 上游 503 `Endpoint is unavailable`）；流式走 `@ai-sdk/openai` responses 适配器（含加密思考往返），非流式/SDK 不可用走原生 `chatToResponsesBody` 转换，出参恒 chat 形状；异形上游用该 env 覆盖路径 |
-| SDK 通道 headers 超时 | `MSLXDFF_SDK_HEADERS_TIMEOUT_MS`（缺省 `120000`） | 防 SDK 通道挂死：`doStream` 到点仍未返回响应头即判挂死抛错（由调用方回退/换路），`0`=关闭；错误文案**不含 "timed out"**（避免 cline runChat 按文案重试放大挂死） |
-| 空转重试阶梯 | `MSLXDFF_EMPTY_TURN_RETRY_STEPS`（缺省 `[2000,8000,30000]`）/`MSLXDFF_EMPTY_TURN_RETRIES`/`MSLXDFF_EMPTY_TURN_MAX_WAIT_MS`（缺省 60000） | 上游 200 但零正文（客户端表现为 "The model ended its turn without producing any output"）时同模型重拉：按阶梯逐档 2s→8s→30s 等待，次数缺省跟随档数（`0`=关，空串=未设）；上游报 `retryAfterSeconds` 时本次等待被抬到不低于该窗口（封顶 `MAX_WAIT_MS`，防上游文本把请求挂 1 小时）；`STEPS=[]`=逃生阀回旧式固定 2s×2；非法值告警一次并落回默认阶梯（手滑不清零恢复能力）；事件 `empty-turn-retry` 带 `step/delayMs/waitedMs(累计)` |
-| 空轮留口与终局收场（ADR-0043） | `MSLXDFF_EMPTY_TURN_HOLD_END`（默认开）/`MSLXDFF_EMPTY_TURN_BUDGET_MS`（45000）/`MSLXDFF_EMPTY_TURN_MIN_RAISE_TO`（16384） | 「200 但零正文」的空轮曾先 `res.end()` 再判定，重拉/换候选写的是已终结响应（客户端只看到空白）。现把「可撤销」定义为**尚未提交模型产出**：空 delta 帧与 `[DONE]` 暂扣不写、流结束不封口，交回重拉续写同一条连接；思考已刷出的一类撤不回 → 不留口，改在流尾补 `EMPTY_MODEL_RESPONSE` SSE 错误帧 + `[DONE]`（客户端看到具体原因而非莫名空白）。终局按 `res.headersSent` 分叉（未 flush→502 JSON / 已 flush→SSE 错误帧），单一出口 + `writableEnded` 守卫保证恰好一次；预算=请求级跨候选累计封顶；`MIN_RAISE_TO` 给"客户端没设额度"的主流空轮兜底抬一次（`0`=回旧口径不发明）；`HOLD_END=0` 逐字节回退旧行为 |
-| 首发输出额度托底 | `MSLXDFF_EMPTY_TURN_MIN_TOKENS`（缺省 8192，`0`/负数=关）/`MSLXDFF_EMPTY_TURN_TINY_MAX`（缺省 64） | 客户端额度 < 门槛（算爆，实测 `max_completion_tokens=1` 被上游截成 1 token 碎渣、agent 循环停摆）→ 首发上游前托到托底值；只加不减、没设额度不发明、0/负数（上游默认语义）不托；serial-trial、auto-race 与宽带成员三处 `upstream.chat` 出口都托；事件 `output-floor`（`key/raiseFrom/raiseTo`） |
-| 免费层形状门禁（ADR-0020） | `MSLXDFF_FREE_LANE`（缺省 1）/`MSLXDFF_FREE_LANE_DEBUG=1` | zen 免费模型必须 `stream:true` + tools 含 bash/edit/glob/grep/read 五名且 UA≥`opencode/1.18.0`（否则 403/426）；`src/free-lane.js` 自动补形状、非流式聚合回 JSON；`0`=关（逃生阀），DEBUG 打 `[free-lane]` 日志 |
-| WorkBuddy 摘除 | `-workbuddy remove <uid> [--keep-file]` / `-wb remove` | 按 `uid`（前缀6位）摘除，删 `keys/auths` 与 `auths/workbuddy-<uid>.json` |
-| 定号消耗 | `header x-mslxdff-workbuddy-uid: <uid>` 或 `model workbuddy/<uid>:<model>` | 钉死指定账号消耗，`x-mslxdff-workbuddy-uid` 回显实际账号 |
-| 同步 WB | `-setto workbuddy [modelId]` | 同步到 WorkBuddy（原子写 `~/.workbuddy/models.json`，`127.0.0.1/v1`，多模型累积；picks 非空时摘除失效本地条目） |
-| 同步 opencode | `-setto opencode [modelId\|--all]` | 把本地网关注册为 opencode 供应商（`provider.mslxdff`，`http://127.0.0.1:<port>/v1`，直写裸名如 `deepseek-v4-flash-free`，`/`→`-` 如 `bai/deepseek`→`bai-deepseek` 到 8989 自动还原，`--all` 批量同步全部 picks；picks 非空时摘除失效模型；自动附模型能力：models.dev 目录 + workbuddy 走上游原生字段，opencode 原生识别；写 variants 档位供 ctrl+t 切换（effort 型按档位写，toggle 型不写，TUI 改配置后需重启）） |
-| 同步 chatgpt | `-setto chatgpt [modelId]` | 写 Codex 三端共用 `~/.codex/config.toml`（`model_providers.mslxdff` → `127.0.0.1/v1/responses`，鉴权走 `mslxdff -showtoken` 不落盘），换模型重跑 setto 或 `codex exec -m <id>` 单次覆盖，`codex exec "hi"` 验证；排障 `MSLXDFF_RESPONSES_DEBUG=1` 看 daemon.log `[responses]` |
-| 同步 Claude Code | `-setto claude [modelId] [--behaves-as <id>]` | 写 Claude Code 用户设置 `~/.claude/settings.json`（`CLAUDE_CONFIG_DIR` 可改址）：`env.ANTHROPIC_BASE_URL=http://127.0.0.1:<port>`（**不带 /v1**）+ 明文 `ANTHROPIC_AUTH_TOKEN` + `CLAUDE_CODE_ATTRIBUTION_HEADER=0`/`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`/`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` + `model` + `modelPicker.options`；**不带 modelId = 写入 `modelPicks` 勾选集全集**（顶层 `model` 也只在勾选集内取，picks 空则报错退出，不兜底到可能已失效的 `preferredModel`；`--all` 与之同义）；`behavesAs` 只给客户端不认识的 id（缺省 `claude-sonnet-5`，`claude-*` 行不写；实测无映射的未知 id 会被本机 Claude Code 直接拒跑）（ADR-0047 `/v1/messages` 外壳）；只动这些键、其余键与键序保留，首写前一次性备份 `settings.pre-mslxdff.json`（不覆盖），JSON 解析失败拒写、写不进即报错不谎报；排障 `MSLXDFF_ANTHROPIC_DEBUG=1` 看 daemon.log `[messages]` |
-| 接 Claude Desktop（3P） | `-setto claude-desktop [modelId ...] [--max N] [--max-effort <lvl>] [--1m <off|auto|all|列表>] [--no-alias] [--check] [--official]`、`-claude-desktop status\\|slots\\|check` | 桌面端**不读** `ANTHROPIC_BASE_URL`/`settings.json`，只读自家 3P profile 且只认「三档角色 ID」→ 一次写两处：① `%LOCALAPPDATA%\Claude-3p\configLibrary\<uuid>.json` + `_meta.json`（uuid 由端口派生、只 upsert 自家条目、他人 entry 不动、损坏拒写、幂等按**原文 vs 原文**、明文 token `0600`、baseUrl **不带 /v1**、`authScheme=bearer`（本仓 `authorized()` 只认 Bearer）、`inferenceModels[{name:角色槽,labelOverride:真模型名}]`）② `model-aliases.json` 写「角色槽 → 真模型」（入站 `src/chat-pipeline/policy.js` 生效、`getModelAlias` 未命中即重读 → **不重启 daemon**）；槽位上限 12（取 App 签名 `model-catalog`，前三档 sonnet/opus/haiku，Haiku 供子 agent），缺 alias 时 App 探活 30–90 s 后 502；`--1m` 打标（ADR-0056，缺省 auto：证据=本机 `/v1/models` 已裁决窗口 ≥1M → 打官方成对键 `supports1m+prefer1m`＝菜单单条默认 1M，不打标被 App 按 200K 封顶；网关不可达 ℹ 降级不阻塞写盘；`off`=历史三键、`all`=担保全打、列表=只打命中行）；`--official` 摘登记不删配置；不写 `preferredModel`、不碰 `claude_desktop_config.json` 与注册表策略；⚠ **App 不热重载**，写完须完全退出重开并选 3P 入口（免 claude.ai 登录）（ADR-0048） |
-| 建组 | `-creategroup <name>` / `-group create <name>` | 建组，本机为 leader |
-| 加组 | `-addtogroup <host> <name> [--broadband]` | 加远端组，broadband 走中继（不占端口纯出站）；**零参数/单参数进手机宽带向导**：问组长地址+组名，自动起服务，回报出口 IP |
-| 组同步 | `-group sync` | 刷新全组成员 |
-| 组离开单 | `-group leave <name>` | 离开单组 |
-| 组列表 | `-group list` | 列组+成员+健康/序号 |
-| 组踢人 | `-group remove <seq>` | 仅 leader 按序号踢人 |
-| 全部离开 | `-leavegroup` / `--leavegroup` | 离开所有成员组 |
-| 解散组 | `-delgroup <name>` / `--delgroup` | 仅 leader 解散 |
-| 解封禁 | `-resetban [ip]` / `--resetban [ip]` | 清加组封禁 |
-| 组员开关 | `-use-group [on\|off]` / `--use-group [on\|off]` | opencode 失败时是否走组员（默认 on，off 则所有供应商仅本机；key 供应商默认恒直连，`MSLXDFF_USE_GROUP_KEYS=1` 可开回；cline/workbuddy 恒禁） |
-| 白嫖雷达 | `-free` / `--free` / `-free-check` / `--free-check` | V2EX 单源白嫖雷达（`latest.json + hot.json` 按白嫖|限免|免费额度过滤） |
-| 白嫖 watch | `-free-watch` / `--free-watch` | V2EX 白嫖雷达 watch（每 5 分钟轮询） |
-| 自启开 | `-enable-autostart` / `--enable-autostart` | 开机自启（Windows 任务计划 / Linux systemd） |
-| 自启关 | `-disable-autostart` / `--disable-autostart` | 关闭开机自启 |
-| 自启状态 | `-autostart status` / `--autostart status` | 查看自启状态 |
-| 时区 | `-timezone [set <tz>\|clear\|status]` / `-tz` | 时区配置，默认 `Asia/Shanghai`，可设 `UTC` 等（`MSLXDFF_TZ` 覆盖） |
-| 帮助 | `-help` / `--help` / `-h` | 打印帮助 |
-
-## 模型说明
-
-- 裸 id 如 `big-pickle` 走默认供应商 opencode；带前缀如 `bai/glm-5.3-flash`、`openrouter/google/gemma-3-27b-it:free`、`workbuddy/hy3`、`cline/z-ai/glm-5.3-flash` 走指定供应商。
-- 实时可用模型由 `可用模型` 列表给出（已按供应商聚合，含 bai/ 等前缀），必须照列表精确输出。
-- 查“某供应商有哪些模型”**优先用 CLI 直查**：`run_command: "-provider workbuddy models"` 或 `run_command: "-model list --provider workbuddy"`（表格含能力列：上下文/📷读图/🧠推理/🔧工具调用，`--json` 供脚本），或 `curl local/models` 后前缀过滤；查模型能力（推理档位/读图/上下文/价格）用 `curl local/models/capabilities?id=<模型id>`（opencode 默认源 models.dev；workbuddy 用 `?provider=workbuddy&id=<裸id>` 走上游原生字段、全量含 blocked，ADR-0016）；**禁止**调 `-provider workbuddy list`（这是查配置，不是查模型！）。**错误示例**：`workbuddy有哪些模型` → 调 `-provider workbuddy list` → 错。**正确**：`run_command: "-provider workbuddy models"` 直接列 `workbuddy/` 前缀模型。严禁为此调用 `-showtoken`。
-
-## 工具调用规范
-
-- 时机：用户意图明确需执行命令时，调用 `run_command`；需查看文件时调用 `read_file`；需探活网络/服务时调用 `curl`。
-- `run_command` 参数：`command: "-model set hy3-free"`（不含 mslxdff 前缀）；`-showtoken` 仅用户明确要求看 token 时才用，查模型/供应商禁止用。
-- **严禁幻觉命令**：`mslxdff "hi" --model X` / `mslxdff --model X "hi"` / `mslxdff -chat --model X` 等**不存在**，一律禁止。探活模型**必须**用 `curl` POST 本机网关，见下一条。
-- `read_file` 参数：`path: "src/logs.js"` 或 `path: "~/.config/mslxdff/events.log"`（项目内或日志目录）
-- `curl` 参数：`url: "upstream"` / `"local/health"` / `"local/models"` / `"bai/models"` / `"https://api.b.ai/v1/models"`，可选 `method`/`headers`/`body`/`timeoutMs`；简写自动补全完整 URL，上游自动补头（含 UA `opencode/<semver>` + opencode 形状 session/request，zen 免费层门禁需要）、本机 /v1/* 自动带 token、已配置供应商（bai/openrouter 等）自动带对应 key
-- **模型探活固定写法**：`curl` 工具 `url:"http://localhost:8989/v1/chat/completions"` `method:"POST"` `headers:{"Content-Type":"application/json"}` `body:'{"model":"<前缀/模型>","messages":[{"role":"user","content":"hi"}],"stream":false}'`（如 `cline/z-ai/glm-5.3-flash`、`workbuddy/hy3`）；成功 `200 + x-mslxdff-via:local` 即通，`401` 代表本机 token 失效需提示用户 `mslxdff -stop && mslxdff`，`403 + x-mslxdff-allowlist:1` 代表白名单未放行需 `allowlist add`，`429/5xx` 代表上游限流/故障。
-- **禁止重复调用（最高优先级）**：同一 `run_command`/`curl`/`read_file` 在本轮只执行一次，重复会被 `SKIPPED_DUP` 拦截；**查询类（-showtoken/-status/-provider list/-providers list/-model list/-group list/-log 等）调用一次即答案**，拿到 `OK` 后必须**立即用中文直接回答**，禁止再调同类命令。收到 `SKIPPED_DUP` 或“请直接回答”时必须 0 工具直接回答。
-- 一次一工具，执行后看结果再决定下一步；拿到工具结果后优先直接回答，不要无故再调。
-
-## 示例
-
-- 用户：`设置hy3为默认模型` → 你先查可用模型确认 `hy3-free` 存在 → `run_command: "-model set hy3-free"`
-- 用户：`看看最近日志` → `run_command: "-log 20"` 或 `read_file: "logs"` 视情况
-- 用户：`查看组列表` → `run_command: "-group list"`
-- 用户：`把 deepseek 加到 opencode` → 先查可用模型确认 `deepseek-v4-flash-free` 全称 → `run_command: "-setto opencode deepseek-v4-flash-free"`（存 `deepseek-v4-flash-free`，选 `mslxdff/deepseek-v4-flash-free` 直达）
-- 用户：`把 bai 模型加到 opencode` → 确认 `bai/deepseek-v4-flash` → `run_command: "-setto opencode bai/deepseek-v4-flash"`（存 `bai-deepseek-v4-flash`，到 8989 自动还原 `bai/deepseek-v4-flash`）
-- 用户：`把所有模型同步到 opencode` → `run_command: "-setto opencode --all"`（批量 picks 全进菜单）
-- 用户：`把当前模型同步到 opencode` → `run_command: "-setto opencode"`（无参取 preferredModel）
-- 用户：`测试z-ai/glm-5.3-flash连通性` → **禁止** `run_command: "\"hi\" --model cline/z-ai/glm-5.3-flash"`，必须 `curl: {url:"http://localhost:8989/v1/chat/completions", method:"POST", headers:{"Content-Type":"application/json"}, body:"{\"model\":\"cline/z-ai/glm-5.3-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}],\"stream\":false}"}`

package/src/providers/AGENTS.md

@@ -1,49 +0,0 @@
-# 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 微量）可直接跑。