mslxdff 0.1.43 → 0.1.45

package/docs/plugins.md

@@ -0,0 +1,185 @@
+# mslxdff 插件开发指南
+
+mslxdff 内置一个零依赖的插件系统：把符合约定的 `.mjs` 模块放进插件目录，daemon 启动时自动加载，在**请求链路的所有关键节点**（hook 点）调用你的代码——包括替换上游 provider 本身。**插件出错只记日志，绝不影响主链路。**
+
+## 快速开始
+
+### 1. 插件目录（双目录，都会被加载）
+
+```
+官方插件:  <mslxdff安装目录>/plugins/     ← 随包分发，auto-update 一起更新
+用户插件:  ~/.config/mslxdff/plugins/    ← 你自己的正式插件，升级永不丢
+完全接管:  环境变量 MSLXDFF_PLUGINS_DIR=/path/to/dir（只扫这一个）
+```
+
+优先级：同名文件时**用户目录覆盖官方目录**；加载顺序官方在前、用户在后。
+
+> 为什么不直接放安装目录？npm 升级会重置包内文件——所以自己的正式插件务必放用户目录。
+
+### 2. 写一个最小插件
+
+创建 `~/.config/mslxdff/plugins/hello.mjs`：
+
+```js
+export default {
+  name: "hello",
+  version: "1.0.0",
+  description: "我的第一个 mslxdff 插件",
+  hooks: {
+    "server:start": (ctx) => {
+      console.log(`[hello] mslxdff 已启动 port=${ctx.port}`);
+    },
+  },
+};
+```
+
+### 3. 查看是否被识别
+
+```bash
+mslxdff -plugins
+# plugins dir: C:\Users\you\.config\mslxdff\plugins
+#   hello@1.0.0  [server:start]
+#     我的第一个 mslxdff 插件
+```
+
+重启 daemon（`mslxdff -stop && mslxdff`）后生效。日志里会出现 `plugins loaded (1): hello@1.0.0`。
+
+## Hook 全表
+
+### 请求链路（按触发顺序）
+
+| Hook | 触发时机 | ctx 内容 | 返回值语义 |
+|---|---|---|---|
+| `request:received` | 读到请求 body 后 | `{ ip, hops, headers, body }` | 返回 `{ respond: { status, body } }` **可短路请求**，直接响应客户端 |
+| `model:select` | 候选顺序确定后 | `{ reqId, requested, useAuto, order, hops, stream }` | 返回数组**替换候选顺序** |
+| `model:beforeTry` | 每个模型尝试前（循环内） | `{ reqId, requested, model, idx, hops }` | 返回 `false` 或 `{ skip: true }` **跳过该候选** |
+| `upstream:request` | 发往上游前 | `{ reqId, requested, model, payload, stream }` | 返回 `{ payload }` **替换本次上游负载**（含 model 字段） |
+| `upstream:response` | 上游响应/错误后 | `{ reqId, requested, model, status, ok, error, timing }` | 只观察 |
+| `relay:first-chunk` | 流式首块到达 | `{ reqId, requested, model, via, ttfMs }` | 只观察 |
+| `request:completed` | 请求结束（所有出口） | `{ reqId, requested, via, status, actual, durationMs, fallback?, interrupted?, error? }` | 只观察 |
+
+> `x-mslxdff-model-lock` 锁定模型时 `model:select` 不触发——锁是硬约束。
+
+### 上游层（upstream 内部，作用于内置 client 的每次 fetch）
+
+| Hook | 触发时机 | ctx 内容 | 返回值语义 |
+|---|---|---|---|
+| `upstream:headers` | 构建请求头后 | `{ url, body, headers }` | 返回 `{ headers }` **替换请求头** |
+| `upstream:before-request` | fetch 调用前 | `{ url, method, body, headers }` | 返回 `{ url?, headers? }` **改目标地址/头** —— 上游不限于 opencode，可指向任意兼容端点 |
+
+### 模型列表 / 组内转发 / 生命周期
+
+| Hook | 触发时机 | ctx 内容 | 返回值语义 |
+|---|---|---|---|
+| `models:list` | `/v1/models` 返回前 | `{ data }` | 返回 id 数组或完整 data 数组**替换对外模型列表** |
+| `peer:beforeForward` | 转发给组员前 | `{ reqId, peer, model, hops }` | 只观察 |
+| `peer:result` | 组员响应后 | `{ reqId, peer, model, ok, status, latencyMs }` | 只观察 |
+| `server:start` | 服务就绪 | `{ port, host, version }` | 只观察 |
+| `server:stop` | 关闭前 | `{ version }` | 只观察 |
+
+### 特殊接口（非 hooks 字段）
+
+```js
+export default {
+  name: "my-plugin",
+  // ① 订阅全部事件流（request/ordered/upstream/fallback/result...每条 evt 都会推给你）
+  onEvent(evt) { /* fire-and-forget，抛错被吞 */ },
+  // ② 整体替换上游 provider（接任意 OpenAI 兼容服务；多个插件声明时取第一个）
+  async createUpstream(ctx) {
+    // ctx = { baseUrl, authToken, env }
+    return {
+      chat(body) { /* 返回 fetch Response，status>=400 会走 fallback */ },
+      preheat() { /* 可选：返回 { ok, status, ms } */ },
+      close() { /* 可选 */ },
+    };
+  },
+  hooks: { /* ...上表全部 hook */ },
+};
+```
+
+## 实战示例
+
+### 改变模型列表设定（首选模型）
+
+```js
+// prefer-model.mjs — 把指定模型排到最前
+const PREFER = "big-pickle"; // 改这里，或读你自己的配置文件
+
+export default {
+  name: "prefer-model",
+  hooks: {
+    "model:select": (ctx) => {
+      if (!ctx.order.includes(PREFER)) return; // 不在列表就不动
+      return [PREFER, ...ctx.order.filter((m) => m !== PREFER)];
+    },
+    "models:list": (ctx) => {
+      // 对外只暴露白名单模型
+      return ctx.data.filter((m) => /big-pickle|deepseek/i.test(m.id ?? m));
+    },
+  },
+};
+```
+
+### 把上游换成任意 OpenAI 兼容服务（不改 URL 配置）
+
+```js
+// redirect-upstream.mjs
+export default {
+  name: "redirect-upstream",
+  hooks: {
+    "upstream:before-request": (ctx) => ({
+      url: ctx.url.replace("https://opencode.ai", "https://my-proxy.example.com"),
+    }),
+  },
+};
+```
+
+### 自定义鉴权 / 限流
+
+```js
+export default {
+  name: "guard",
+  hooks: {
+    "request:received": (ctx) => {
+      if (String(ctx.body?.messages?.[0]?.content || "").includes("BLOCK")) {
+        return { respond: { status: 403, body: { error: "blocked by plugin" } } };
+      }
+    },
+  },
+};
+```
+
+### 监控统计（事件流）
+
+```js
+let total = 0;
+export default {
+  name: "stats",
+  onEvent(evt) {
+    if (evt.type === "request") total++;
+    if (evt.type === "result" && evt.status >= 500) console.log(`[stats] 5xx! ${evt.model}`);
+  },
+};
+```
+
+## 规则与保证
+
+- **文件格式**：仅 `.mjs` / `.js`，ESM，必须有 `export default { ... }`；`name` 缺省取文件名
+- **串行执行**：多个插件的同一 hook 按文件名排序依次执行；返回值链式传递（前一个的输出是后一个的输入）
+- **错误隔离**：
+  - 加载失败 → 不注册，错误进 events.log（`plugin-load-error`）和 `-plugins` 输出
+  - hook 抛错 → 跳过该插件继续执行后续插件，主链路无感
+- **可观测**：hook 生效时 events.log 记 `plugin-hook`；报错记 `plugin-hook-error`；替换上游记 `plugin-upstream-active`
+- **性能**：`request:received / model:select / model:beforeTry / upstream:request` 是 await 串行的，别做慢操作（>100ms 请改 fire-and-forget）；`onEvent / request:completed / relay:first-chunk / upstream:response / peer:*` 本身就是异步不阻塞
+
+## 调试
+
+```bash
+mslxdff -plugins          # 列出已识别插件与其 hooks
+mslxdff -debug            # 前台跑，实时看 plugin-hook / plugin-hook-error 事件
+mslxdff -log 50           # 回看事件日志
+```
+
+## 与 WorkBuddy 集成
+
+WorkBuddy 插件的 SKILL.md 可以教 AI 在用户说"切换首选模型到 xxx"时，自动改写上面的 `prefer-model.mjs` 并重启 daemon —— mslxdff 侧无需任何改动，hook 就是稳定契约。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {
@@ -16,6 +16,8 @@
   "files": [
     "bin/",
     "src/",
+    "plugins/",
+    "docs/",
     "README.md"
   ],
   "keywords": [

package/plugins/README.md

@@ -0,0 +1,14 @@
+# mslxdff 官方插件目录
+
+本目录随 mslxdff 包分发（`*.mjs` 会被自动加载）。**注意：auto-update 重装包时本目录会被重置**——你自己的正式插件请放 `~/.config/mslxdff/plugins/`（升级永不丢）。
+
+优先级：同名文件时用户目录（`~/.config/mslxdff/plugins/`）覆盖本目录。
+
+## 目录约定
+
+- `*.mjs` / `*.js` — 插件模块（default export `{ name, version, hooks, onEvent?, createUpstream? }`）
+- `*.example` — 示例模板，不会被加载；复制成 `.mjs` 并去掉后缀即可启用
+
+## Hook 全表
+
+见 `docs/plugins.md`。

package/plugins/prefer-model.mjs.example

@@ -0,0 +1,14 @@
+// 示例：把首选模型排到最前（复制为 prefer-model.mjs 即生效；或放 ~/.config/mslxdff/plugins/ 永久生效）
+const PREFER = "big-pickle";
+
+export default {
+  name: "prefer-model",
+  version: "1.0.0",
+  description: `auto 时优先使用 ${PREFER}`,
+  hooks: {
+    "model:select": (ctx) => {
+      if (!ctx.order.includes(PREFER)) return;
+      return [PREFER, ...ctx.order.filter((m) => m !== PREFER)];
+    },
+  },
+};

package/src/auto.js

@@ -1,7 +1,29 @@
-import { loadModelErrors, saveModelErrors, loadModelLatencies, saveModelLatencies } from "./state.js";
-
-// auto 的默认首选模型：一处定义，全局生效（可用 MSLXDFF_PREFERRED_MODEL 覆盖）
-export const PREFERRED_MODEL = (process.env.MSLXDFF_PREFERRED_MODEL || "big-pickle").trim();
+import { statSync } from "node:fs";
+import { loadModelErrors, saveModelErrors, loadModelLatencies, saveModelLatencies, loadPreferredModel, defaultStateFile } from "./state.js";
+
+// 出厂默认首选模型（state.json 的 preferredModel / env MSLXDFF_PREFERRED_MODEL 可覆盖）
+export const DEFAULT_PREFERRED_MODEL = "big-pickle";
+// 兼容旧导出名：语义为"出厂默认"，当前生效值请用 getPreferredModel()
+export const PREFERRED_MODEL = DEFAULT_PREFERRED_MODEL;
+
+// 当前生效的首选模型：state.json > env > 出厂默认；mtime 缓存保证 daemon 热生效
+const _prefCache = { mtimeMs: -1, file: null, value: null };
+export function getPreferredModel({ file = defaultStateFile() } = {}) {
+  try {
+    const st = statSync(file);
+    if (_prefCache.file !== file || st.mtimeMs !== _prefCache.mtimeMs) {
+      _prefCache.file = file;
+      _prefCache.mtimeMs = st.mtimeMs;
+      _prefCache.value = loadPreferredModel({ file });
+    }
+  } catch {
+    _prefCache.file = file;
+    _prefCache.mtimeMs = -1;
+    _prefCache.value = null;
+  }
+  const env = (process.env.MSLXDFF_PREFERRED_MODEL || "").trim();
+  return _prefCache.value || env || DEFAULT_PREFERRED_MODEL;
+}
 
 export const DEFAULT_AUTO_MODELS = [
   PREFERRED_MODEL,
@@ -74,14 +96,15 @@ function normLatency(e) {
   return Number.isFinite(ema) && ema > 0 ? ema : null;
 }
 
-export function rankModels(ids, errors = {}, { now = Date.now(), cooldownMs = 0, slowCooldownMs = 0, latencies = {} } = {}) {
+export function rankModels(ids, errors = {}, { now = Date.now(), cooldownMs = 0, slowCooldownMs = 0, latencies = {}, preferred } = {}) {
+  const pref = preferred ?? getPreferredModel();
   return [...new Set(ids)]
     .filter(Boolean)
     .map((id) => ({
       id,
       e: normEntry(errors[id]),
       err: normEntry(errors[id])?.at ?? 0,
-      isPreferred: id === PREFERRED_MODEL,
+      isPreferred: id === pref,
       cooling: inCooldown(id, errors, now, cooldownMs, slowCooldownMs),
       latency: normLatency(latencies[id]) ?? Number.MAX_SAFE_INTEGER,
     }))
@@ -122,7 +145,7 @@ export function createAutoSelector({
   }
 
   async function candidates() {
-    return rankModels(await loadList(), lastErrorAt, { now: now(), cooldownMs, slowCooldownMs, latencies });
+    return rankModels(await loadList(), lastErrorAt, { now: now(), cooldownMs, slowCooldownMs, latencies, preferred: getPreferredModel({ file: file ?? undefined }) });
   }
 
   async function candidatesFor(requested) {
@@ -134,6 +157,7 @@ export function createAutoSelector({
       cooldownMs,
       slowCooldownMs,
       latencies,
+      preferred: getPreferredModel({ file: file ?? undefined }),
     });
     // 显式指定模型：严格优先，永不因冷却被挤到最后（原设计：A deepseek 失败 → B/D deepseek 并发 → 都失败才 fallback）
     // 冷却仅影响 auto 的择优，不影响指定模型的“很难被更改”语义

package/src/chooser.js

@@ -0,0 +1,29 @@
+// 交互式模型选择器的纯渲染逻辑（便于测试）；键盘循环在 bin/mslxdff.js
+
+// items: [{ id, status?, ms?, fail?, current? }]；cursor 当前高亮行
+// 返回行数组（无 ANSI 颜色，纯文本标记，Windows 终端友好）
+export function renderChooser(items, cursor = 0) {
+  return items.map((it, i) => {
+    const arrow = i === cursor ? "❯" : " ";
+    const check = it.current ? " ✓ (current)" : "";
+    let state = "";
+    if (it.fail) state = `  [fail: ${it.fail}]`;
+    else if (it.ms != null) state = `  [${it.ms}ms]`;
+    else if (it.status && it.status !== "normal") state = `  [${it.status}]`;
+    return `${arrow} ${it.id}${check}${state}`;
+  });
+}
+
+export function renderChooserHelp() {
+  return ["", "↑/↓ move · Enter select as default · q/Esc cancel"];
+}
+
+// 解析按键：返回 "up" | "down" | "enter" | "cancel" | null(忽略)
+export function parseKey(str) {
+  if (!str) return null;
+  if (str === "\x1b[A" || str === "k") return "up";
+  if (str === "\x1b[B" || str === "j") return "down";
+  if (str === "\r" || str === "\n") return "enter";
+  if (str === "\x1b" || str === "q" || str === "\x03") return "cancel";
+  return null;
+}

package/src/plugins.js

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

package/src/routes/chat.js

@@ -6,8 +6,9 @@ import { buildFallbackInfo } from "./fallback.js";
 import { relay, SLOW_TOTAL_MS, STREAM_TIMEOUT_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS } from "./stream.js";
 import { racePeerCandidates } from "./peers.js";
 import { tryBroadbandRelay } from "./relay-queue.js";
+import { runHook } from "../plugins.js";
 
-export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHops, groups, bus, token }) {
+export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHops, groups, bus, token, plugins }) {
   let body;
   try {
     body = await readBody(req);
@@ -15,6 +16,16 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
     return json(res, 400, { error: "Invalid JSON body" });
   }
 
+  // 插件 hook：request:received — 读到 body 后触发；返回 { respond:{status,body} } 可短路请求
+  if (plugins?.length) {
+    const rc = await runHook(plugins, "request:received", { ip: clientIp(req), hops: parseHops(req.headers["x-mslxdff-hops"]), headers: { "content-type": req.headers["content-type"] }, body });
+    for (const e of rc.errors) logs?.appendEvent?.({ ts: Date.now(), type: "plugin-hook-error", hook: "request:received", plugin: e.plugin, error: e.error });
+    const respond = rc.value?.respond;
+    if (respond && typeof respond === "object") {
+      return json(res, respond.status || 200, respond.body ?? {});
+    }
+  }
+
   const startedAt = Date.now();
   const reqId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
   const perf0 = performance.now();
@@ -49,14 +60,32 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
     if (bus) bus.emit(entry);
     logs?.appendEvent?.(entry);
   };
+  // 插件 hook：request:completed — 每个请求出口触发一次（只观察）
+  const done = (info) => {
+    if (!plugins?.length) return;
+    runHook(plugins, "request:completed", { reqId, requested, useAuto, hops, stream: Boolean(body.stream), durationMs: Date.now() - startedAt, ...info }).catch(() => {});
+  };
   evt("request", { reqId, hops, ip: clientIp(req), stream: Boolean(body.stream), prompt: summarizePrompt(body), rawModel, requested, lockModel: lockModel || null });
   evt("ordered", { reqId, order, canFallback, canForwardPeers, useAuto, statuses: auto?.statuses?.() ?? null });
 
+  // 插件 hook：model:select — 可返回新数组替换候选顺序（lockModel 时不可改）
+  if (plugins?.length && !lockModel) {
+    const sel = await runHook(plugins, "model:select", { reqId, requested, useAuto, order: [...order], hops, stream: Boolean(body.stream) });
+    if (sel.changed && Array.isArray(sel.value) && sel.value.length) {
+      order = sel.value.filter(Boolean);
+      if (!order.length) order = [requested];
+      evt("plugin-hook", { reqId, hook: "model:select", applied: true, order: [...order] });
+    }
+    for (const e of sel.errors) evt("plugin-hook-error", { reqId, hook: "model:select", plugin: e.plugin, error: e.error });
+  }
+
   const handlerCtx = {
+    reqId,
     model: null,
     body,
     hops,
     peers,
+    plugins,
     evt,
     logError,
     logCall,
@@ -67,8 +96,26 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
     const model = order[idx];
     handlerCtx.model = model;
     evt("model-try", { reqId, model, idx, remaining: order.length - idx });
+    // 插件 hook：model:beforeTry — 返回 false 可跳过该候选
+    if (plugins?.length) {
+      const bt = await runHook(plugins, "model:beforeTry", { reqId, requested, model, idx, hops });
+      for (const e of bt.errors) evt("plugin-hook-error", { reqId, hook: "model:beforeTry", plugin: e.plugin, error: e.error });
+      if (bt.value === false || bt.value?.skip === true) {
+        evt("plugin-hook", { reqId, hook: "model:beforeTry", applied: true, skipped: model });
+        continue;
+      }
+    }
     let upRes = null;
-    const forwarded = { ...injectReasoningContent(model, body), model };
+    let forwarded = { ...injectReasoningContent(model, body), model };
+    // 插件 hook：upstream:request — 返回 { payload } 可替换本次发往上游的负载
+    if (plugins?.length) {
+      const ur = await runHook(plugins, "upstream:request", { reqId, requested, model, payload: forwarded, stream: Boolean(body.stream) });
+      for (const e of ur.errors) evt("plugin-hook-error", { reqId, hook: "upstream:request", plugin: e.plugin, error: e.error });
+      if (ur.changed && ur.value?.payload && typeof ur.value.payload === "object") {
+        forwarded = ur.value.payload;
+        evt("plugin-hook", { reqId, hook: "upstream:request", applied: true, model, rewrittenModel: forwarded.model ?? null });
+      }
+    }
     const tUp = performance.now();
     evt("upstream-try", { reqId, model, attempt: idx + 1 });
     try {
@@ -80,6 +127,16 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
       logError(model, 502, errMsg(err));
       evt("upstream-error", { reqId, model, status: 502, message: errMsg(err), timing: err._t ?? { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - tUp) } });
     }
+    // 插件 hook：upstream:response — 上游响应（或错误）后观察
+    if (plugins?.length) {
+      runHook(plugins, "upstream:response", {
+        reqId, requested, model,
+        status: upRes instanceof Error ? null : upRes instanceof Object ? (upRes.status ?? null) : null,
+        ok: !(upRes instanceof Error) && upRes ? upRes.status < 400 : false,
+        error: upRes instanceof Error ? errMsg(upRes) : null,
+        timing: upRes?._t ?? null,
+      }).catch(() => {});
+    }
     mark(`up-${model}`);
     if (upRes && upRes.status >= 400) {
       if (auto) await auto.recordError(model, { status: upRes.status });
@@ -98,6 +155,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
         onFirstChunk: (delta) => {
           mark(`ttf-${model}`);
           evt("relay-first-chunk", { reqId, model, ttfMs: delta });
+          if (plugins?.length) runHook(plugins, "relay:first-chunk", { reqId, requested, model, via: "local", ttfMs: delta }).catch(() => {});
         },
         onDownstreamAbort: () => {
           evt("client-abort", { reqId, model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] });
@@ -122,6 +180,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
         logCall(model, 200);
         evt("result", { model, status: out.status, via: "local", timing: upRes._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, interrupted: true, detail: out.detail ?? null, fallback, requested, actual: model });
         evt("client-response", { requested, actual: model, via: "local", fallback, status: out.status, interrupted: true, reqId });
+        done({ via: "local", status: out.status, actual: model, interrupted: true, fallback });
         return;
       }
       const elapsed = Date.now() - startedAt;
@@ -146,6 +205,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
       }
       evt("result", { model, status: out.status, via: "local", timing: upRes._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null, fallback, requested, actual: model });
       evt("client-response", { requested, actual: model, via: "local", fallback, status: out.status, reqId });
+      done({ via: "local", status: out.status, actual: model, fallback });
       return;
     }
 
@@ -178,6 +238,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
         }
         evt("result", { model: win.target, status: out.status, via: "peer", timing: win.res._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null, fallback: peerFallback, requested, actual: win.target });
         evt("client-response", { requested, actual: win.target, via: "peer", fallback: peerFallback, status: out.status, reqId });
+        done({ via: "peer", status: out.status, actual: win.target, fallback: peerFallback });
         return;
       }
       evt("peer-race-lose", { reqId, model });
@@ -208,6 +269,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
           }
           evt("result", { model, status: out.status, via: "broadband", timing: bb.result._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null, fallback: bbFallback, requested, actual: model });
           evt("client-response", { requested, actual: model, via: "broadband", fallback: bbFallback, status: out.status, reqId });
+          done({ via: "broadband", status: out.status, actual: model, fallback: bbFallback });
           return;
         } else if (bb.result && typeof bb.result.status === "number") {
           const fakeRes = {
@@ -235,6 +297,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
           evt("relay-done", { reqId, model, via: "broadband-local", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
           evt("result", { model, status: out.status, via: "broadband", timing: null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null, fallback: bbLocalFallback, requested, actual: model });
           evt("client-response", { requested, actual: model, via: "broadband", fallback: bbLocalFallback, status: out.status, reqId });
+          done({ via: "broadband", status: out.status, actual: model, fallback: bbLocalFallback });
           return;
         }
       }
@@ -258,6 +321,7 @@ export async function chatHandler({ req, res, upstream, auto, logs, peers, maxHo
       return;
     }
     evt("result", { reqId, model, status: lastErr?.status ?? 502, via: "none", timing: null });
+    done({ via: "none", status: lastErr?.status ?? 502, error: lastErr?.message || "all auto models failed" });
     return json(res, 502, { error: lastErr?.message || "all auto models failed" });
   }
 

package/src/routes/index.js

@@ -6,7 +6,7 @@ import { joinHandler, leaveHandler } from "./groups.js";
 import { heartbeatHandler, pollHandler, resultHandler, forwardHandler } from "./groups-relay.js";
 import { modelsHandler, modelsStatusHandler } from "./models-route.js";
 
-export function createRouter({ token, upstream, models, auto, logs, peers, maxHops = DEFAULT_MAX_HOPS, groups, bans, bus }) {
+export function createRouter({ token, upstream, models, auto, logs, peers, maxHops = DEFAULT_MAX_HOPS, groups, bans, bus, plugins }) {
   return async function router(req, res) {
     const method = req.method || "GET";
     const path = (req.url || "").split("?")[0];
@@ -17,7 +17,7 @@ export function createRouter({ token, upstream, models, auto, logs, peers, maxHo
       res.setHeader("WWW-Authenticate", "Bearer");
       return json(res, 401, { error: "Unauthorized" });
     }
-    await route.handler({ req, res, upstream, models, auto, logs, peers, maxHops, groups, bans, token, bus });
+    await route.handler({ req, res, upstream, models, auto, logs, peers, maxHops, groups, bans, token, bus, plugins });
   };
 }
 

package/src/routes/models-route.js

@@ -1,9 +1,22 @@
 import { json, errMsg } from "./helpers.js";
+import { runHook } from "../plugins.js";
 
-export async function modelsHandler({ res, models }) {
+export async function modelsHandler({ res, models, plugins }) {
   if (!models) return json(res, 501, { error: "Models service not configured" });
   try {
-    const data = await models.get();
+    let data = await models.get();
+    // 插件 hook：models:list — 返回数组可替换对外模型列表（{object:"list",data:[...]} 或纯 id 数组）
+    if (plugins?.length) {
+      const ml = await runHook(plugins, "models:list", { data });
+      for (const e of ml.errors) console.log(`plugin models:list error (${e.plugin}): ${e.error}`);
+      if (ml.changed && Array.isArray(ml.value)) {
+        const idsOnly = ml.value.every((x) => typeof x === "string");
+        const out = idsOnly
+          ? { object: "list", data: ml.value.map((id) => ({ id, object: "model", owned_by: "plugin" })) }
+          : { object: "list", data: ml.value };
+        return json(res, 200, out);
+      }
+    }
     json(res, 200, data);
   } catch (err) {
     json(res, 502, { error: errMsg(err) });