mslxdff 0.1.158 → 0.1.159

package/docs/plans/bench-via-latency-2026-09-01.md

@@ -1,215 +0,0 @@
-# 规划：家宽 A 直连 vs 经组员 B/C/D 借道 的上游延迟对比（bench-via）
-
-> 状态：规划中（未落代码） | 作者：mslxdff | 日期：2026-09-01
-> 关联：`AGENTS.md` 先拆后写、`docs/ARCHITECTURE.md` §5/§6/§7、`docs/adr/`、`src/bench/*`、`src/providers/dispatcher.js`、`src/routes/chat/*`
-
----
-
-## 1. 背景与动机
-
-- **场景**：机器 A 在家宽，无固定公网 IP，出口质量抖动；A 与 B/C/D 组成 mslxdff 群组（`src/routes/chat/peer*`、`src/routes/groups.js`）。用户想知道“**A 直连上游** vs **A 经 B/C/D 接力到同一上游**”谁更快，以便选最优出口。
-- **现有能力**：`mslxdff -provider <id> bench` 已能测直连 TTFB/TPS（`src/bench/probe|runner|report`），但**不覆盖“经 peer 接力”**链路；群组接力已有（`peer/broadband`），但无对比视图。
-- **核心矛盾**：`opencode` 免费池靠出口 IP 限额（`src/upstream.js:429→冷却+匿名重试`），**A 经 B 打 opencode 会消耗 B 的额度**，测一次亏一次。必须把“额度保护”做成一等公民，否则 bench-via 会把组员额度测没。
-
----
-
-## 2. 目标（Goals）
-
-1. 一条命令给出**直连 vs 经每个在线组员**到各上游的延迟对比表，首屏可读，脚本可解析。
-2. 默认**不消耗组员的 opencode 额度**；显式才测 opencode，且有二次确认与最小化消耗。
-3. 复用现有 `bench` 与 `dispatcher` 链路，不引入新协议；结果**不污染** `state.json` 的 `latency EMA / preferred`。
-4. 失败隔离：某 peer 离线/超时不阻塞全表；空组/无在线 peer 有空状态引导。
-5. 体验闭环四态：`空→加载（进度）→成功（表格+建议）→失败（人话+重试）`。
-
-## 3. 非目标（Non-Goals）
-
-- 不做持续后台探测/定时任务（首版仅按需触发）。
-- 不改 `state.json` 的长期择优（`src/auto.js` 排序保持直连 EMA，不写 via 结果）。
-- 不新增 peer 认证/计费；额度保护仅做提示与默认跳过。
-- 不支持“多跳”（A→B→C→上游），仅一跳接力。
-
----
-
-## 4. 用户故事
-
-- **US1 - 快速选路**：作为 A 的主人，我执行一次对比就能看到 `direct 820ms | via B 310ms | via C timeout`，知道以后让 A 的默认出口走 B。
-- **US2 - 额度不被误伤**：作为 B 的主人，我不希望 A 随便把我的 opencode 额度测掉；默认 via 不含 opencode，必须显式+确认才测。
-- **US3 - 脚本化**：作为自动化脚本，我用 `--json` 拿到机器可读的对比结果，择优写入配置。
-- **US4 - 组为空**：A 未加组时，命令直接告诉我“先加组”，而不是假装在测。
-
----
-
-## 5. 现状与约束分析
-
-- **Bench 现状**：`src/cli/commands/provider/bench.js` 调 `src/bench/{probe,runner,report}`，串行测已勾选 `allowlist` 模型，30s 超时，空 allowlist 则探活 `GET /v1/models→/models`。输出表格+`--json`。
-- **群组现状**：`src/routes/chat/peer*` 已支持 `A→peer→upstream` 转发，带 `x-mslxdff-via`；`src/providers/dispatcher.js` 前缀路由，`share-keys` 默认排除 opencode（`ADR-0008`），`workbuddy` 默认 `share=off`。
-- **文件体积约束**：`AGENTS.md` 要求 `src/**/*.js ≤10KB 愉悦、>20KB 必拆`，`npm run docs:check` 校验；`src/bench/*` 与 `src/cli/commands/provider/*` 均需保持在限额内，via 必须拆独立模块而非塞进 bench.js。
-- **已验证风险**：`workbuddy` 多号 429 切号、`cline` 指纹头、`auto` 冷却 60s/慢 5min、`STREAM_TIMEOUT_MS 25s` 首块对冲 1s（`src/upstream.js`/`src/routes/chat/hedge.js`）。
-
----
-
-## 6. 方案设计
-
-### 6.1 命令形态（CLI 契约）
-
-> 归属：`docs/ARCHITECTURE.md §6 CLI 表` + `docs/cli_help.md` + `docs/cli_help_mini.md`（三处同步）
-
-**首选形态（复用 bench，不新增顶级动词）：**
-
-```bash
-mslxdff -provider bench --via                 # 对比：direct vs 经每个在线 peer（默认跳过 opencode）
-mslxdff -provider <id> bench --via            # 只对比指定供应商（如 openrouter / workbuddy / clinebot）
-mslxdff -provider bench --via --include-opencode  # 显式把 opencode 纳入对比（需二次确认）
-mslxdff -provider bench --via --json          # 机器可读
-mslxdff -provider bench --via --samples 1 --timeout 15000  # 可调样本/超时（默认 samples=1, timeout=30000）
-```
-
-**备选（若 bench 参数拥挤）：**
-
-```bash
-mslxdff --bench-via [--provider <id>] [--include-opencode] [--json]
-```
-
-> 决策：首选前者，保持“bench 家族”心智；若用户反馈参数过长，再补 `--bench-via` 别名。规划阶段两者都保留为兼容目标，定稿时二选一。
-
-**参数表：**
-
-| 参数 | 默认 | 说明 |
-|---|---|---|
-| `--via` | off | 开启“经 peer”对比；未加组时直接空状态退出 |
-| `--include-opencode` | off | 显式才把 `opencode` 纳入 via；否则 via 仅测非 opencode 供应商 |
-| `--provider <id>` | 全部已启用且 allowlist 非空的供应商 | 缩小对比范围 |
-| `--samples N` | 1 | 每个路径的样本数（via 场景默认 1 以省额度，直连可 1-3） |
-| `--timeout N` | 30000 | 单次请求超时 ms |
-| `--json` | off | 输出 JSON（stdout 纯 JSON，进度走 stderr） |
-
-### 6.2 输出契约
-
-**人类表格（TTY）：**
-
-```
-bench-via: direct vs via peers (samples=1, timeout=30s, opencode=skipped)
-
-Provider      Model                     direct   via B(家)  via C(云)  best
-openrouter    google/gemma-3-27b:free   820ms    310ms★     540ms      via B -62%
-workbuddy     hy3                       410ms    380ms      — offline  direct
-clinebot      deepseek-v3.2             610ms    590ms      720ms      via B -3%
-
-建议：A 经 B 打 openrouter 最快；workbuddy 走 direct 即可。
-提示：via 已跳过 opencode（省额度），需对比 opencode 请加 --include-opencode
-```
-
-**JSON（--json）：**
-
-```json
-{
-  "meta": { "at": "2026-09-01T02:00:00+08:00", "samples": 1, "timeout": 30000, "includeOpencode": false, "direct": "A", "peers": ["B","C"] },
-  "results": [
-    { "provider": "openrouter", "model": "google/gemma-3-27b:free", "direct": { "ttfb": 820, "total": 1100 }, "via": { "B": { "ttfb": 310 }, "C": { "ttfb": 540 } }, "best": "via:B", "deltaMs": -510 },
-    { "provider": "workbuddy", "model": "hy3", "direct": { "ttfb": 410 }, "via": { "B": { "ttfb": 380 }, "C": { "error": "offline" } }, "best": "direct" }
-  ],
-  "advice": "A via B for openrouter is fastest (-62%)"
-}
-```
-
-### 6.3 架构与数据流
-
-```
-CLI: src/cli/commands/provider/bench.js --via
-  ├─ 1) 解析组员：src/state.js groups/peers → 在线 peer 列表（probeHealth 1.2s）
-  ├─ 2) 解析待测集合：src/models.js listModels + provider allowlist 过滤
-  │     └─ 默认排除 opencode；--include-opencode 才纳入
-  ├─ 3) src/bench/via.js  orchestrator
-  │     ├─ 对每个 (provider,model)：
-  │     │   ├─ direct: src/bench/runner.js 直连打一次（复用 probe 的最小 prompt）
-  │     │   └─ via peer_i: 复用 src/routes/chat/* 的 “A→peer→upstream” 链路
-  │     │       └─ 经 dispatcher 剥前缀转发，peer 侧走现有 upstream 逻辑
-  │     └─ 汇总：best/delta，生成 report
-  └─ 4) src/bench/report.js 渲染（人类表 / JSON）
-```
-
-**模块清单（先拆后写，≤10KB/文件）：**
-
-```
-src/bench/
-  probe.js        现有：探活
-  runner.js       现有：单模型 TTFB/TPS
-  report.js       现有：表格渲染（via 复用，新增 via 列渲染分支）
-  via.js          新增：via 编排（peer 发现→并发/串行调度→结果聚合），≤300 行
-  via-probe.js    新增：单次 via 探针（A→peer→upstream 的轻量 chat.completions，max_tokens=5），≤200 行
-src/cli/commands/provider/
-  bench.js        改动：新增 --via/--include-opencode/--samples/--timeout 解析与二次确认
-```
-
-> Mermaid Before/After（落代码前在 `.scratch/bench-via/MODULES.md` 补全）：Before `bench.js 39KB 单文件` 已拆，现 via 再拆 `via.js+via-probe.js`，保持每文件 <10KB，`docs:check` >20KB 零容忍。
-
-### 6.4 额度矛盾的解法（必做）
-
-1. **默认跳过 opencode 的 via**：`via.js` 在组装待测集合时 `if (!includeOpencode) filter out provider=opencode`。
-2. **显式二次确认**：`--include-opencode` 时，TTY 下 `readline` 问 `将消耗 B/C/D 的 opencode 额度，确认测 opencode via？y/N`，N 则回落到“仅测非 opencode”。
-3. **最小化消耗**：via 探针统一 `max_tokens=5`、`prompt="hi"`、`temperature=0`，单样本；直连 bench 保持现有 3 样本，via 强制 1 样本（`--samples` 显式覆盖除外）。
-4. **提示常驻**：表格底部与 `--json.meta` 均带 `opencodeSkipped:true` 与文案，`--json` 也不静默消耗。
-
-### 6.5 状态与持久化
-
-- **不写 `state.json`**：via 结果仅本次输出，不写 `modelLatencies/preferredModel`，避免污染 `src/auto.js` 的长期择优。
-- 可选：`--save`（非首版）再考虑落盘 `daemon` 日志或 `~/.config/mslxdff/via-history.json`，首版不做。
-
-### 6.6 错误与空状态
-
-| 场景 | 表现 |
-|---|---|
-| 未加组 / 无在线 peer | 空状态：`未加入组或无在线 peer，--via 无意义。先 mslxdff -group list / -addtogroup`，exit 0 |
-| 某 peer 离线/超时 | 该格 `— offline/timeout`，不阻塞其他格；底部汇总 `2/3 peers reachable` |
-| 上游 401/429/5xx | 复用 `src/bench/runner` 的错误分类，格内显示 `401/429/5xx`，不重试放大额度消耗 |
-| 组员不支持某 provider（如未配 key） | 该格 `— no key` |
-| 网络抖动 | 单样本 via 天生抖动，报告附 `* via 单样本，仅作参考，多次 --samples 2 取均值更稳` |
-
-### 6.7 性能与成本
-
-- **串行优先**：via 对 `peers × models` 串行打，避免并发把 peer 打 429；`--samples` 仅在直连侧并发，via 侧恒串行。
-- **超时**：单次 30s，超时记 `timeout` 不重试。
-- **成本**：默认 via 不含 opencode，workbuddy/openrouter/clinebot 的探针均为最小 token，成本可忽略；opencode 显式才 1 次/peer。
-
-### 6.8 安全
-
-- 复用现有 `Authorization: Bearer <token>` 鉴权与 `x-mslxdff-share-keys` 瞬时共享；opencode 恒不共享（`src/providers/share-keys.js`），via 不绕过。
-- 不新增持久化 key，不新增网络监听面。
-
----
-
-## 7. 变更记账（落地时必做）
-
-- `docs/ARCHITECTURE.md`：§5 功能地图新增 “bench-via” 行；§6 CLI 表新增 `--via/--include-opencode`；§7 目录导览补 `src/bench/via.js、via-probe.js`。
-- `docs/cli_help.md` + `docs/cli_help_mini.md`：同步 CLI 段落。
-- `docs/adr/`：新增 `0011-bench-via.md`（记录“默认跳过 opencode + 二次确认”决策）。
-- `npm run docs:check` 绿。
-
----
-
-## 8. 测试计划（不写代码，仅约定）
-
-- **单元**：`test/bench-via.test.js` — 空组/离线 peer/跳过 opencode/二次确认分支、`via-probe` 最小 prompt 约束、串行调度验证（mock peer）。
-- **集成**：本地起两个 daemon 组网，`--via --json` 真实 A→B→upstream 打通，断开 B 后重测为 `offline`。
-- **回归**：现有 `test/bench-*.test.js` 全绿；`--include-opencode` 分支需 mock 确认输入。
-
----
-
-## 9. 里程碑
-
-- **M1 规划定稿**：本文件评审通过，确定 CLI 形态（bench --via vs 独立 --bench-via）。
-- **M2 拆分清单**：`.scratch/bench-via/MODULES.md` + Mermaid，`npm run docs:check` 预检。
-- **M3 实现**：`via.js/via-probe.js` + `bench.js` 参数 + `report.js` via 列 + 空/加载/成功/失败四态。
-- **M4 自测与发布**：组网 2 节点实测 → 文档同步 → `0.1.74` 发版。
-
----
-
-## 10. 开放问题（需你拍板）
-
-1. **CLI 形态**：`mslxdff -provider bench --via` 还是 `mslxdff --bench-via`？推荐前者（bench 家族），是否接受或两者兼容？
-2. **默认样本数**：via 默认 1 次是否足够，还是要 2 次取均值更稳但多耗一次额度？
-3. **是否需要 `--save` 落盘历史**：首版不做，是否现在就加上？
-
-> 你确认后，我按 `先拆后写` 直接落代码，不再追问细节。
-
-> 备注（2026-09-20 追加，原文不改）：0.1.x 起 Cline 供应商 id 统一为 `cline`（历史 `clinebot` 仅作一次性入站归一）。

package/docs/plugins.md

@@ -1,187 +0,0 @@
-# mslxdff 插件开发指南
-
-mslxdff 内置一个零依赖的插件系统：把符合约定的 `.mjs` 模块放进插件目录，daemon 启动时自动加载，在**请求链路的所有关键节点**（hook 点）调用你的代码——包括替换上游 provider 本身。**插件出错只记日志，绝不影响主链路。**
-
-> **内置多供应商**：0.1.56 起默认走 `src/providers/` 的多 Provider 架构（opencode 恒启用 + openrouter 可选，见 AGENTS.md）。插件 `createUpstream` 仍是"整体替换式"制造商供应，与内置多 Provider 二选一（有 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 就是稳定契约。