mslxdff 0.1.42 → 0.1.45

package/bin/mslxdff.js

@@ -8,13 +8,15 @@ import { DEFAULT_PORT, defaultStateFile } from "../src/state.js";
 import { createRouter } from "../src/routes.js";
 import { createUpstreamClient } from "../src/upstream.js";
 import { createModelsService } from "../src/models.js";
-import { loadToken, refreshToken, setPort, getPort, loadGroupsJoined, saveGroupsJoined, loadModelErrors } from "../src/state.js";
+import { loadToken, refreshToken, setPort, getPort, loadGroupsJoined, saveGroupsJoined, loadModelErrors, savePreferredModel } from "../src/state.js";
+import { getPreferredModel } from "../src/auto.js";
 import { startDaemon, stopDaemon, writePid, pidFile, logFile, readPid, readPidVersion, isPidAlive } from "../src/daemon.js";
 import { createAutoSelector } from "../src/auto.js";
 import { createPeersService } from "../src/peers.js";
 import { createEventBus } from "../src/events.js";
 import { createGroupsService, createBansService, refreshGroupMembers, syncPeersFromMembers } from "../src/groups.js";
 import { logDir, recentCalls, lastError, appendCall, appendError, appendEvent, recentEvents, eventsFile, callsFile, errorsFile } from "../src/logs.js";
+import { loadPlugins, runHook, pluginsDir, resolvePluginDirs } from "../src/plugins.js";
 
 const logs = { appendCall, appendError, appendEvent };
 
@@ -108,6 +110,28 @@ if (args.includes("-log") || args.includes("--log") || args.includes("-logs") ||
   process.exit(0);
 }
 
+// -plugins: list plugins in the plugins dirs (and their hooks) without starting the daemon
+if (args.includes("-plugins") || args.includes("--plugins")) {
+  const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const dirs = resolvePluginDirs({ pkgRoot });
+  const labels = ["official (bundled)", "user"];
+  if (dirs.length === 1) labels[0] = "dir";
+  console.log(`plugin dirs:`);
+  dirs.forEach((d, i) => console.log(`  [${labels[i] || `dir${i + 1}`}] ${d}${existsSync(d) ? "" : "  (not created yet)"}`));
+  const { plugins, errors } = await loadPlugins({ dirs });
+  if (!plugins.length && !errors.length) {
+    console.log("(no plugins — drop *.mjs files into a dir above, see docs/plugins.md)");
+  }
+  for (const p of plugins) {
+    const hooks = Object.keys(p.hooks || {});
+    const src = p.file.startsWith(pkgRoot) ? "official" : "user";
+    console.log(`  ${p.name}${p.version ? `@${p.version}` : ""}  [${hooks.join(", ") || "no hooks"}]  (${src})`);
+    if (p.description) console.log(`    ${p.description}`);
+  }
+  for (const e of errors) console.log(`  load error: ${e.file} — ${e.error}`);
+  process.exit(0);
+}
+
 if (args.includes("-status") || args.includes("--status") || args.includes("-s")) {
   await printStatus();
   process.exit(0);
@@ -156,18 +180,24 @@ if (args.includes("-model") || args.includes("-models")) {
     }
     process.exit(0);
   }
+  if (sub === "set" && args[idx + 2]) {
+    const id = args[idx + 2];
+    savePreferredModel(id);
+    console.log(`default model set to: ${id} (daemon hot-reloads on next request)`);
+    process.exit(0);
+  }
   if (sub !== undefined && sub !== "list") {
-    console.error("usage: mslxdff -model list | mslxdff -model status | mslxdff -model refresh");
+    console.error("usage: mslxdff -models (interactive picker) | mslxdff -model list | mslxdff -model set <id> | mslxdff -model status | mslxdff -model refresh");
     process.exit(1);
   }
   const cacheFile = join(logDir(), "models.json");
   try {
+    let ids = [];
+    let cachedAt = null;
     const cached = readModelsCache(cacheFile);
     if (cached) {
-      const ids = (cached.data || []).map((m) => m.id).filter(Boolean);
-      const at = cached.cachedAt ? ` (cached ${new Date(cached.cachedAt).toISOString().slice(0, 16).replace("T", " ")})` : "";
-      console.log(`${ids.length} free model(s)${at}:`);
-      for (const id of ids) console.log(`  ${id}`);
+      ids = (cached.data || []).map((m) => m.id).filter(Boolean);
+      cachedAt = cached.cachedAt || null;
     } else {
       const models = createModelsService({
         baseUrl: process.env.UPSTREAM_BASE_URL || "https://opencode.ai",
@@ -176,10 +206,37 @@ if (args.includes("-model") || args.includes("-models")) {
         cacheFile,
       });
       const list = await models.get();
-      const ids = (list.data || []).map((m) => m.id).filter(Boolean);
-      console.log(`${ids.length} free model(s):`);
-      for (const id of ids) console.log(`  ${id}`);
+      ids = (list.data || []).map((m) => m.id).filter(Boolean);
     }
+    if (!ids.length) {
+      console.log("no models available — try: mslxdff -model refresh");
+      process.exit(0);
+    }
+    // TTY：交互式箭头选择默认模型；非 TTY（管道/脚本）：保持纯列表
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const statuses = loadModelErrors();
+      const current = getPreferredModel();
+      const items = ids.map((id) => {
+        const e = statuses[id];
+        return {
+          id,
+          status: typeof e === "number" ? "error" : e?.status || "normal",
+          current: id === current,
+        };
+      });
+      const picked = await pickInteractive(items, Math.max(0, items.findIndex((x) => x.current)));
+      if (!picked) {
+        console.log("cancelled — default model unchanged");
+        process.exit(0);
+      }
+      savePreferredModel(picked);
+      console.log(`default model set to: ${picked} (daemon hot-reloads on next request)`);
+      process.exit(0);
+    }
+    const at = cachedAt ? ` (cached ${new Date(cachedAt).toISOString().slice(0, 16).replace("T", " ")})` : "";
+    console.log(`${ids.length} free model(s)${at}:`);
+    for (const id of ids) console.log(`  ${id}`);
+    console.log(`\ninteractive pick needs a TTY; set directly with: mslxdff -model set <id>`);
   } catch (err) {
     console.error(`could not fetch models: ${String(err?.message || err)}`);
     process.exit(1);
@@ -187,6 +244,46 @@ if (args.includes("-model") || args.includes("-models")) {
   process.exit(0);
 }
 
+// 交互式选择器：↑/↓ 移动，Enter 确认，q/Esc 取消；ANSI 原地重绘
+async function pickInteractive(items, startCursor = 0) {
+  const { renderChooser, renderChooserHelp, parseKey } = await import("../src/chooser.js");
+  let cursor = Math.min(Math.max(startCursor, 0), items.length - 1);
+  const draw = () => {
+    const lines = [...renderChooser(items, cursor), ...renderChooserHelp()];
+    process.stdout.write("\x1b[G\x1b[J" + lines.join("\n"));
+  };
+  draw();
+  return new Promise((resolve) => {
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      const key = parseKey(String(chunk));
+      if (key === "up") {
+        cursor = (cursor - 1 + items.length) % items.length;
+        draw();
+      } else if (key === "down") {
+        cursor = (cursor + 1) % items.length;
+        draw();
+      } else if (key === "enter") {
+        cleanup();
+        resolve(items[cursor].id);
+      } else if (key === "cancel") {
+        cleanup();
+        resolve(null);
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
 // -debug: stop the background daemon and run the server in THIS terminal
 // (foreground), printing every event to stdout in real time via the in-memory
 // event bus — no filesystem polling. Ctrl+C / SIGTERM restarts the daemon in
@@ -648,7 +745,36 @@ if (!process.env.MSLXDFF_DAEMON) {
 }
 
 const { token, created } = await loadToken();
-const upstream = createUpstreamClient({});
+// 插件系统：加载（在 upstream 创建前，插件可整体替换上游实现）
+// 双目录：<安装目录>/plugins/（官方插件，随包分发）+ ~/.config/mslxdff/plugins/（用户自定义，升级不丢）
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const pluginDirs = resolvePluginDirs({ pkgRoot });
+const { plugins: loadedPlugins, errors: pluginErrors } = await loadPlugins({ dirs: pluginDirs });
+for (const e of pluginErrors) {
+  console.log(`plugin load failed: ${e.file} — ${e.error}`);
+  appendEvent({ ts: Date.now(), type: "plugin-load-error", file: e.file, error: e.error });
+}
+if (loadedPlugins.length) {
+  console.log(`plugins loaded (${loadedPlugins.length}): ${loadedPlugins.map((p) => `${p.name}${p.version ? `@${p.version}` : ""}`).join(", ")}`);
+  appendEvent({ ts: Date.now(), type: "plugins-loaded", plugins: loadedPlugins.map((p) => ({ name: p.name, version: p.version })) });
+}
+const upstreamHooks = loadedPlugins.length
+  ? (name, ctx) => runHook(loadedPlugins, name, ctx)
+  : null;
+// 插件可提供 createUpstream(ctx) 整体替换上游（接任意 provider）；取第一个声明者
+const providerPlugin = loadedPlugins.find((p) => typeof p.createUpstream === "function");
+let upstream;
+if (providerPlugin) {
+  try {
+    upstream = await providerPlugin.createUpstream({ baseUrl: process.env.UPSTREAM_BASE_URL || "https://opencode.ai", authToken: process.env.UPSTREAM_AUTH_TOKEN || "public", env: process.env });
+    console.log(`upstream provider replaced by plugin: ${providerPlugin.name}`);
+    appendEvent({ ts: Date.now(), type: "plugin-upstream-active", plugin: providerPlugin.name });
+  } catch (err) {
+    console.log(`plugin upstream (${providerPlugin.name}) failed: ${errMsg(err)} — falling back to default`);
+    appendEvent({ ts: Date.now(), type: "plugin-upstream-error", plugin: providerPlugin.name, error: errMsg(err) });
+  }
+}
+if (!upstream) upstream = createUpstreamClient({ hooks: upstreamHooks });
 const baseUrl = process.env.UPSTREAM_BASE_URL || "https://opencode.ai";
 const models = createModelsService({
   baseUrl,
@@ -673,9 +799,16 @@ const bans = createBansService({ windowMs: banWindowMs(), threshold: banThreshol
 
 const isDebug = process.env.MSLXDFF_DEBUG === "1";
 const bus = createEventBus();
-const router = createRouter({ token, upstream, models, auto, logs, peers, maxHops: maxHopsValue(), groups, bans, bus });
+const router = createRouter({ token, upstream, models, auto, logs, peers, maxHops: maxHopsValue(), groups, bans, bus, plugins: loadedPlugins });
 const listenHost = effectiveHost();
-const srv = startServer({ router, signals: !isDebug, host: listenHost });
+const srv = startServer({
+  router,
+  signals: !isDebug,
+  host: listenHost,
+  onBeforeClose: loadedPlugins.length
+    ? () => runHook(loadedPlugins, "server:stop", { version: VERSION }).then(() => {})
+    : undefined,
+});
 
 // -debug: push every event straight to this terminal.
 if (isDebug) {
@@ -703,6 +836,20 @@ if (isDebug) {
 
 await srv.ready();
 
+// 插件 hook：server:start — 服务就绪后触发（只观察）
+if (loadedPlugins.length) {
+  runHook(loadedPlugins, "server:start", { port: srv.server.address()?.port, host: listenHost, version: VERSION }).catch(() => {});
+  // 插件 onEvent(evt) — 订阅全部事件流（fire-and-forget，错误隔离）
+  const eventPlugins = loadedPlugins.filter((p) => typeof p.onEvent === "function");
+  if (eventPlugins.length) {
+    bus.subscribe((e) => {
+      for (const p of eventPlugins) {
+        try { p.onEvent(e); } catch {}
+      }
+    });
+  }
+}
+
 // 上游 Keep-Alive 预热：首条 TCP+TLS 暖好，100ms 后异步触发，不阻塞 ready
 setTimeout(() => {
   upstream.preheat().then((r) => {
@@ -1018,7 +1165,9 @@ Usage:
   mslxdff -d                       start as a background daemon
   mslxdff -status                  show current status (daemon, models, recent calls, last error)
   mslxdff -log [N]                 show last N events (default 10, e.g. -log 100)
-  mslxdff -model list              list the free models this proxy serves (cached)
+  mslxdff -models                interactive picker: ↑/↓ select a model, Enter sets it as the default (non-TTY: plain list)
+  mslxdff -model list            list the free models this proxy serves (cached)
+  mslxdff -model set <id>        set the default (preferred) model without the interactive picker
   mslxdff -model status            show per-model health status (normal/limit/error)
   mslxdff -model refresh           force-refresh the model cache from the upstream
   mslxdff -debug                   live-follow the daemon event stream (requests, errors, peer forwards)

package/docs/adr/0001-reasoning-content-injection.md

@@ -0,0 +1,14 @@
+# ADR-0001: Inject a reasoning_content placeholder on outbound assistant messages
+
+The Zen upstream's thinking-mode models (deepseek-family at minimum) return
+`400 "The reasoning_content in the thinking mode must be passed back"` when a
+multi-turn request echoes an assistant message without its `reasoning_content`.
+Clients speaking plain OpenAI format never send that field, so the proxy writes
+a `" "` placeholder into assistant messages before forwarding. Scope is `all`
+for deepseek-family models and `tool_calls` for kimi-family models; messages
+that already carry non-empty `reasoning_content` are left untouched.
+
+The alternative — telling clients to manage `reasoning_content` themselves —
+would break standard OpenAI-compatible clients, so the proxy eats this
+compatibility cost instead. Matches `/root/9router` v0.5.45
+`open-sse/utils/reasoningContentInjector.js`.

package/docs/adr/0002-models-free-filter.md

@@ -0,0 +1,12 @@
+# ADR-0002: /v1/models exposes only free models, matched by suffix or whitelist
+
+The upstream `/zen/v1/models` list contains ~60 models; exposing them all would
+pollute clients with paid models this proxy can't serve for free. `/v1/models`
+therefore filters to: `id` ending in `-free`, OR the explicit whitelist entry
+`big-pickle`. The whitelist exists because `big-pickle` is a free model without
+the `-free` suffix, and a suffix-only filter would silently drop it.
+
+A plain `endsWith("-free")` filter was considered and rejected for exactly that
+reason. Matches `/root/9router` v0.5.45
+`src/app/api/providers/suggested-models/filters.js`
+(`KNOWN_FREE_OPENCODE_MODELS = ["big-pickle"]`).

package/docs/adr/0003-zero-state-no-auth.md

@@ -0,0 +1,10 @@
+# ADR-0003: Zero-state, no-DB, no-account local proxy
+
+Status: partially superseded by [ADR-0004](./0004-bearer-token.md) — the
+no-auth clause below is replaced; the zero-DB / no-account / no-cloud principles
+stand.
+
+By design this proxy holds no database, no token store, no account rotation,
+and no cloud sync. A single static bearer token is the only credential, kept
+in a 0600 state file (see ADR-0004); everything else is stateless per-process
+memory at most.

package/docs/adr/0004-bearer-token.md

@@ -0,0 +1,18 @@
+# ADR-0004: Single static bearer token, persisted in a 0600 state file
+
+The proxy requires a bearer token on `/v1/*` so an accidentally-exposed port
+isn't an open relay. There is no account system: the token is a random
+`crypto` 32-byte value (hex), generated once on first run, persisted to a
+state file (default `~/.config/mslxdff/state.json`, `0600`, path overridable
+via `MSLXDFF_STATE_FILE`), and printed to stdout on creation. Rotate with
+`mslxdff -refresh-token`, which regenerates, rewrites the file, prints the
+new token, and exits (does not start the server).
+
+Auth is enforced with a constant-time string compare on
+`Authorization: Bearer <token>`; mismatches get `401` with `WWW-Authenticate`.
+`/health` stays public (no token). Tokens never appear in logs.
+
+Alternatives rejected: a fixed default token (same key on every install),
+per-user accounts (needs a DB — that's the 9Router provisioning surface we
+rejected in ADR-0003), and unauthenticated local-only binding (fragile;
+a proxy relay deserves an explicit secret even on localhost).

package/docs/adr/0005-peer-mesh.md

@@ -0,0 +1,53 @@
+# ADR-0005: Peer mesh for same-model failover across machines
+
+> **Update (group model):** peers are now configured through named groups, and the
+> group name doubles as the join password (supersedes the random join key). CLI:
+> `-creategroup <name>` on the leader (no address needed — the first joiner seeds
+> the leader's own entry from the address it connects from), `-addtogroup <leader-host> <name>`
+> elsewhere. Every member (leader included) re-registers with the leader on a timer
+> (`MSLXDFF_GROUP_SYNC_MS`, default 60s) and rebuilds its local peer list from the
+> freshest member map, so membership changes propagate to all nodes automatically.
+> The `-peer` commands are removed; peers are an internal mechanism. Wrong group
+> names/tokens are counted per source IP: `MSLXDFF_BAN_THRESHOLD` (default 5)
+> failures ban the IP for `MSLXDFF_BAN_WINDOW_MS` (default 48h); `-resetban [ip]`
+> clears bans.
+
+A single mslxdff instance depends on one upstream quota; when that upstream
+starts rate-limiting or failing for a model, the only local fallback is
+switching to a *different* model. That changes the model out from under the
+client. To keep the requested model working while the local path recovers,
+multiple instances can be joined into a group: when the local upstream
+fails for model X, the instance forwards the request (still model X) to a
+group member that runs its own mslxdff and has its own upstream quota.
+
+## Design
+
+- **Peers are plain mslxdff instances.** Each peer is identified by
+  `{ url, token }` (its bearer token, per ADR-0004). Configured with
+  `mslxdff -peer add <token> <url> [name]`, removed with `-peer remove`,
+  listed with `-peer list`; persisted in the state file. No new protocol —
+  forwarding is a normal authenticated `POST /v1/chat/completions` to the
+  peer, reusing the existing API surface.
+- **Local-first routing.** A request always tries the local upstream first.
+  Only on local failure (network error or HTTP ≥ 400) does it iterate peers
+  for the *same model*, round-robin over currently-available peers.
+- **Model lock.** Forwarded requests carry `x-mslxdff-model-lock: <model>`
+  so the receiving peer uses exactly that model — it must not re-select or
+  fall back to another model, keeping "same model, different machine" true.
+- **Hop bound.** Forwarded requests carry `x-mslxdff-hops` (incremented each
+  hop). A peer receiving hops ≥ `maxHops` (default 3, `MSLXDFF_MAX_HOPS`)
+  stops forwarding further, bounding mesh depth and preventing loops.
+- **Peer cooldown.** A peer that fails a request enters a cooldown window
+  (default 30s, `MSLXDFF_PEER_COOLDOWN_MS`), during which it is skipped by
+  the round-robin, so the mesh rotates to healthy peers instead of
+  hammering a down one. Mirrors the model cooldown in ADR-0001.
+
+## Why not alternatives
+
+- **Point the whole proxy at another machine** (client-side failover): the
+  client can't detect per-model upstream failure, and every request pays the
+  cross-machine latency even when local is healthy.
+- **Different model per machine**: violates the requirement of keeping the
+  same model, and hides the model-change from the client.
+- **Central coordinator / service discovery**: overkill for a handful of
+  private instances; static peer config is zero-config and debuggable.

package/docs/adr/0006-broadband-member.md

@@ -0,0 +1,103 @@
+# ADR-0006: 宽带动态IP成员（broadband）经 Leader 中继共享配额
+
+> **状态**：规划完成，待实现（基于 v0.1.33）。用户确认：`--broadband` 为唯一语义，不设 `--relay` 别名；默认 `127.0.0.1` 监听。
+
+## 1. 背景与问题
+
+现有组模型（ADR-0005）假设组员均为公网 VPS，`A->D` 直连 `http://D公网IP:8989/v1/chat/completions` 用 `D` 的出口 IP 打 `opencode.ai`，实现 `IP级免费池` 分散。家庭宽带 `D` 有公网 IP 但：
+
+1. **入站不可达**：无端口映射/CGNAT，`probeHealth GET http://D:8989/health` 恒 `fail`，`peer-race` 直接跳过，`D` 的配额永不被用。
+2. **IP 动态**：`refreshGroupMembers` 透传旧 `myUrl`，IP 变更后 60s 同步期内全组仍用旧 IP。
+3. **语义缺失**：组内无法区分 `static(VPS直连)` 与 `broadband(家庭中继)`，`-group list` 无标识。
+
+需求：家庭 `D` 以 `broadband` 类型加入，无需公网入站，经 `Leader` 中继仍用 `D` 的家庭出口打上游，且全程可观测。
+
+## 2. 决策
+
+新增成员类型 `kind: "broadband"`（默认 `kind: "static"` 兼容老数据），`broadband` 隐含 `relay` 中继：
+
+* **加入**：`mslxdff -addtogroup <leader-host> <group> --broadband`（唯一旗标，不设 `--relay`）。
+* **监听**：`--broadband` 下默认 `listen 127.0.0.1:8989`，仅本机 `WorkBuddy` 可用；不加该旗标的为 `static` 走 `0.0.0.0`。
+* **共享**：`D --WS--> Leader` 常驻出站，`A(429) -> Leader -> D -> opencode.ai -> D -> Leader -> A`，上游仍见 `D` 家庭 IP。
+* **展示**：`-help` 新增用法行，`-group list / -status / -log` 标注 `[broadband] via leader Xs ago ip=...`。
+
+## 3. 设计
+
+### 3.1 成员模型
+
+`state.json groups[name].members[id]` 扩展：
+
+```json
+"home-D": {
+  "url": "relay://home-D",
+  "token": "...",
+  "kind": "broadband",
+  "publicIp": "183.14.22.78",
+  "lastSeen": 1724212345678,
+  "status": {"upstreamOk": true, "latencyMs": 4200}
+}
+```
+
+* `static`：`url: http://IP:8989`，参与 `probeHealth`。
+* `broadband`：`url: relay://id`，不探活，只看 `lastSeen`（`>90s` 标 `cooling`）+ `status`，`rankModels` 同 `slow` 5m 冷却共用。
+
+### 3.2 连接与心跳
+
+**D 端（家庭）**
+* 解析 `--broadband`，建 `WS wss://Leader/v1/groups/relay/connect?group=my@mslxd`，`Authorization: Bearer <token>`。
+* `hello {group, token, kind:"broadband", version}` → Leader 回 `welcome {memberId}`。
+* `heartbeat 30s {status:{upstreamOk, models, load}}`，`publicIp` 由 Leader 的 `clientIp(req)` 填，不靠 `ifconfig.me`。
+* 断线指数退避 `1s/2s/4s...` 重连，IP 变更导致 `TCP RST` 自动重建即完成 IP 更新。
+
+**Leader 端（VPS）**
+* `GET /v1/groups/relay/connect` 升级 WS，鉴权 `membersForToken`，存 `relayConns[group][id]=ws`，`ws.remoteIp=clientIp`。
+* 每条 `heartbeat` 对比 `remoteIp` vs `members[id].publicIp`，变则 `saveGroups` + `evt relay-ip-change` 入 `events.log`。
+* `lastSeen >90s` 或 `WS断开` 立即标 `cooling`，`A` 下次 `candidatesFor` 自动避开。
+
+### 3.3 转发路径
+
+```
+用户 -> A: POST /v1/chat/completions {model: deepseek, stream:true}
+A -> opencode.ai (用A IP) 429
+A选 candidatesFor -> [B(static), home-D(broadband via Leader), ...] 按 latency EMA
+A -> Leader: POST /v1/groups/relay/forward {target: home-D, body, hops:1, reqId}
+Leader -> D (WS): {reqId, body:{model,messages}}
+D -> opencode.ai (用D家庭IP) 200 SSE chunk*
+D --WS {reqId, data:chunk}--> Leader --HTTP chunk--> A --SSE--> 用户
+A断开 -> Leader --WS {abort reqId}--> D controller.abort()
+```
+
+* `hops` 每跳 +1，`MAX_HOPS=3` 防环；`broadband` 节点自身 `429` 时可直接 `fetch` 到 VPS `static` 节点（出站直连，无需中继）。
+* 多请求复用一条 WS，`reqId` 复用现有 `relay` 日志的 `reqId/detail` 串联。
+
+### 3.4 可观测
+
+* `-help`：` -addtogroup <host> <name> [--broadband]  宽带动态IP成员（经Leader中继，无需公网入站，默认127.0.0.1）`
+* `-group list`：`3. relay://home-D [broadband] ok via leader 12s ago ip=183.14.22.78`
+* `-log [N]`：`relay-ip-change / relay-forward / relay-heartbeat / client-abort` 均带 `reqId/detail`。
+
+## 4. 实现清单
+
+| 文件 | 改动 |
+|---|---|
+| `bin/mslxdff.js` | `-addtogroup` 解析 `--broadband`，`WS` 客户端+心跳+重连，`listen` 在 `broadband` 下绑 `127.0.0.1`，`printHelp` 新增行，`groupSyncTimer` 对 `broadband` 组 30s |
+| `src/groups.js` | 成员结构 `kind/publicIp/lastSeen/status`，`addGroupMember/upsertMember/syncPeersFromMembers` 支持 `broadband`，`refreshGroupMembers` 透传 `kind` |
+| `src/peers.js` | 新增 `relayVia` 字段，`add({relayVia, kind}) / isRelay`，`broadband` 不进 `ordered()` 直连池 |
+| `src/routes.js` | 新增 `WS /v1/groups/relay/connect` + `POST /v1/groups/relay/forward`，`forwardToPeer` 中继分支，`hops` 处理 |
+| `src/state.js` | 持久化 `kind/publicIp/lastSeen`，新增 `load/save` 兼容 |
+| `src/logs.js` | `relay-*` 事件类型 |
+
+依赖：`ws`（或 Node 22 原生 `WebSocket`，服务端需 `upgrade` 处理）。
+
+## 5. 验证
+
+1. **IP变更**：`D` 拨号重拨，`WS` 重连，`events.log` 出现 `relay-ip-change old->new`，`-group list` IP 更新，`A` 经 `Leader` 仍命中 `D`。
+2. **配额共享**：`A` 指定 `deepseek 429`，`-log` 显示 `peer-race via=relay-leader target=home-D`，`D` 的 `upstream-done 200` 且 `detail.exitReason:normal`，回包完整。
+3. **本地可用**：`D` 本机 `curl http://127.0.0.1:8989/v1/chat/completions` 200，外网 `curl http://家庭公网IP:8989` 超时（符合预期）。
+4. **`-help` / `-group list`** 均含 `broadband` 标识。
+
+## 6. 风险与取舍
+
+* `Leader` 单点中继增加 `10-30ms` 延迟，可接受；`Leader` 宕则 `broadband` 配额暂不可用（`static` 组员仍直连可用）。
+* 多并发复用单 `WS` 需 `reqId` 复用与背压控制，首版可限并发 3（复用 `PEER_RACE_LIMIT`）。
+* 不设 `--relay` 别名，术语统一为 `broadband`，内部变量 `relay` 仅作实现名。

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.