mslxdff 0.1.55 → 0.1.56

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

@@ -1,53 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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

@@ -1,51 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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

@@ -1,15 +0,0 @@
-# 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.

package/docs/plugins.md

@@ -1,185 +0,0 @@
-# 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 就是稳定契约。