@zaofan/dsh-qqbot 1.8.8 → 1.9.2

package/examples/ext-hooks/session-watch-hook.mjs

@@ -0,0 +1,119 @@
+/**
+ * session-watch-hook.mjs — 演示「注册监听 + dispose 清理」的启动钩子示例
+ *
+ * 放在 `{数据根}/.qqbot-extensions/hooks/session-watch-hook.mjs`
+ * （插件启动时会自动铺一份，只补不覆盖；你改过的版本永远不会被覆盖）。
+ *
+ * 它做三件"必须自己收尾"的事，正是不清理就会在重建网关时不断累积的典型：
+ *   ① `env.ctx.on('session/event', …)` 订阅宿主事件 → 返回 disposer；
+ *   ② 起一个 `setInterval` 定时器 → 自己 clearInterval；
+ *   ③ 用 `env.store.save()` 落盘一个累计计数。
+ *
+ * 收尾入口**两个都写了**（都合法，任选其一即可；这里是为让示例把两条路都展示出来）：
+ *   · `run()` 里 `env.registerDispose(fn)` —— 适合"清理函数是闭包、写在 run 内部"的情形；
+ *   · 模块级 `export function dispose(env)` —— 适合"清理逻辑是模块级的"。
+ * 执行顺序：同一钩子内 registerDispose 的**逆序**先跑，然后跑模块级 dispose()。
+ *
+ * ⚠️ 三条经验（踩出来的）：
+ *   1. **必须真的收尾**：不 dispose 的话，每次"保存连接相关设置 → 重建网关"都会多一份监听；
+ *   2. **run 与 dispose 之间有竞态**：极端情况下 dispose 可能先于 run 的末尾执行 ——
+ *      所以用 `cancelled` 标志兜住（本示例的写法可以直接抄）；
+ *   3. **别在启动路径上做重活**：钩子会拖慢插件启动（虽然有 30s 超时保护，但超时=白等 30s）。
+ */
+
+export const name = 'session-watch-hook';
+
+const TICK_MS = 60_000;
+
+/** 每次 run 的现场（重建网关会有新的一份；旧的由 dispose 清掉） */
+let state = null;
+
+export default {
+  name,
+
+  /** 事件计数与定时器句柄都挂在 state 上，避免模块级散落变量互相踩 */
+  async run(env) {
+    const startAt = Date.now();
+    const prev = env.store.load() ?? {};
+    state = {
+      events: 0,
+      starts: Number(prev.starts ?? 0) + 1,
+      cancelled: false,
+      disposers: [],
+      startAt,
+      timer: undefined,
+    };
+
+    env.logger.info(
+      `[ext-hook:session-watch] 启动第 ${state.starts} 次（插件 v${env.pluginVersion}）——` +
+      `开始订阅 session/event，并起一个 ${TICK_MS / 1000}s 的统计定时器`,
+    );
+
+    // ── ① 订阅宿主事件（有就订，没有就算了：ctx 形状跟随宿主版本，别因为拿不到就崩） ──
+    try {
+      const off = env.ctx?.on?.('session/event', () => {
+        state.events += 1;
+        if (state.events % 10 === 0) {
+          env.logger.info(`[ext-hook:session-watch] 已观察到 ${state.events} 个 session/event`);
+        }
+      });
+      if (typeof off === 'function') state.disposers.push(off);
+      else env.logger.warn('[ext-hook:session-watch] ctx.on 没返回 disposer —— 跳过订阅（宿主版本差异？）');
+    } catch (err) {
+      // 钩子里的失败**不要往外抛**：抛了也只是被引擎记成"失败"，不如自己降级
+      env.logger.warn(`[ext-hook:session-watch] 订阅 session/event 失败(已降级): ${err?.message ?? err}`);
+    }
+
+    // ── ② 定时器（记得 unref：不该因为一个统计定时器让宿主进程退不掉） ──
+    state.timer = setInterval(() => {
+      if (state.cancelled) return;
+      env.logger.info(
+        `[ext-hook:session-watch] 心跳：本次启动已观察 ${state.events} 个事件，` +
+        `存活 ${Math.round((Date.now() - state.startAt) / 1000)}s`,
+      );
+    }, TICK_MS);
+    state.timer.unref?.();
+
+    // ── ③ 登记清理（同时用 registerDispose 展示这条通路） ──
+    env.registerDispose(() => {
+      // 这里只是再打一行日志；真正的清理由下面 cleanup() 统一做（避免两处清理重复）
+      env.logger.info('[ext-hook:session-watch] registerDispose 回调执行');
+    });
+
+    // ── 竞态兜底：如果 run 还没跑完，dispose 就已经被调用了，那就**立刻**收尾 ──
+    if (state.cancelled) {
+      env.logger.warn('[ext-hook:session-watch] 启动与卸载撞上了，立即收尾');
+      cleanup(env);
+      return { cancelled: true };
+    }
+
+    return { starts: state.starts };
+  },
+
+  /** 模块级 dispose：引擎在插件卸载 / 宿主退出 / 重建网关时调用（逆序、逐个 try/catch） */
+  async dispose(env) {
+    if (state) state.cancelled = true;   // 先立标志：run 若还在后面跑，它会自己收尾
+    cleanup(env);
+  },
+};
+
+/** 幂等收尾：disposer 逐个吞错 + 定时器清掉 + 计数字段落盘 */
+function cleanup(env) {
+  const s = state;
+  state = null;
+  if (!s) return;
+  s.cancelled = true;
+  for (const off of s.disposers.splice(0).reverse()) {
+    try { off(); } catch (err) {
+      env.logger.warn(`[ext-hook:session-watch] 取消订阅失败(已忽略): ${err?.message ?? err}`);
+    }
+  }
+  if (s.timer) { clearInterval(s.timer); s.timer = undefined; }
+  env.store.save({
+    starts: s.starts,
+    lastEvents: s.events,
+    lastRunMs: Date.now() - s.startAt,
+    lastStopAt: new Date().toISOString(),
+  });
+  env.logger.info(`[ext-hook:session-watch] 已收尾（观察 ${s.events} 个事件，监听与定时器都已归还）`);
+}

package/examples/ext-inbound/README.md

@@ -0,0 +1,230 @@
+# 入站中间件（`{数据根}/.qqbot-extensions/inbound/`）
+
+> 这一套扩展能**影响每一条入站消息的命运**：让它别进来、把它的文本换掉、让它一定要叫醒她、或者反过来"这条不算 @ 她"。
+> v1.9.0+。
+> **这一套里"会自动铺到你目录"的只有 `no-wake-on-child-quote.mjs` 一个**（插件首次启动铺一份，只补不存在、绝不覆盖你改过的）。
+> 其余示例（尤其 `class-advisor.mjs` —— 它会**真删消息、真封人**）**不自动铺**，想看想用自己拷过去。
+> 理由：示例是给人**看和抄**的，不该在你没读过它之前就自己跑起来。
+
+---
+
+## 一、两个挂点：链上位置决定你能做什么
+
+```
+… → messageFilter → accessPolicy → quoteRef
+   → ★① 早挂点 onInbound ★            ← 记群历史之前！
+   → 引用图预取 → 群历史缓冲（store）→ 表情包/台账
+   → mentionGate（@ 门控）
+   → ★② 晚挂点 onDecide / export default ★
+   → contentSanitizer → debounce（延迟聚合）→ 命令 → 群冷却 → 并发合并 → envelope → AI
+```
+
+| | **① 早：`onInbound`** | **② 晚：`onDecide` / `export default`** |
+|---|---|---|
+| 链上位置 | `quoteRef` 之后、**记群历史之前** | `mentionGate` 之后、`contentSanitizer` 之前 |
+| 读得到 | `ctx.message` / `ctx.state.quote` / `ctx.platform.mentioned` | 上面全部 **＋ `ctx.state.mention`**（@ 判定） |
+| 做得了 | **消灭**、**改写**、**强制入站**、查/写禁言名单 | **覆盖 @ 判定**、改写、强制入站、查/写禁言名单 |
+| 做不到 | `ctx.decide`（`ctx.state.mention` 还没写出来，调了会被拒 + 告警） | `ctx.annihilate`（群历史已经记过了，调了会被拒 + 告警） |
+
+一个文件可以**同时导出两个挂点**（互不影响）；只导出 `export default` 就是最早那份契约，**语义等同 `onDecide`**，老扩展不用改。
+
+```js
+// {数据根}/.qqbot-extensions/inbound/my-rule.mjs
+export async function onInbound(ctx, next) {   // ① 早
+  return next();
+}
+export default async function onDecide(ctx, next) {   // ② 晚（= 原来的写法）
+  return next();
+}
+export function dispose() { /* 可选：插件卸载/重建网关时清理 */ }
+```
+
+四种写法都认（挑一种就行）：
+
+```js
+export default async (ctx, next) => next();          // 裸函数默认导出（= 晚挂点）
+export async function onDecide(ctx, next) { … }      // 具名晚挂点
+export async function onInbound(ctx, next) { … }     // 具名早挂点
+export const onInbound = async (ctx, next) => next();// 箭头式也行
+export default { name: 'x', onInbound, onDecide, dispose() {} };   // 对象默认导出
+```
+
+> ⚠️ 一个扩展文件里，晚挂点只认一个：**具名 `onDecide` ＞ 裸函数 `export default` ＞ 对象里的 `onDecide`/`middleware` ＞ 具名 `middleware`**。
+
+## 二、为什么"改写 / 消灭"必须写在**早挂点**（这是最容易踩的一处）
+
+链上第 4 步是**群历史缓冲**：它把每条消息的正文写进 store（AI 的 `[历史]` 段就是从这来的），而它读的是 `ctx.message.content`。
+所以：
+
+* **改写**写在早挂点 → 进 store 的就是改后文本（AI 看到的、历史里存的都是和谐版）；
+  写在晚挂点 → **store 里已经是原文了**，只有"当前这条"是改后的（要连历史一起改，只能在早挂点）。
+* **消灭**（`ctx.annihilate()`，等价于"不调 `next()`"）写在早挂点 → 链停在这里，**群历史、@ 门控、价值评分、群冷却全都不跑**，这条消息等于没来过；
+  写在晚挂点 → 历史已经记了、门控已经过了，就算拦住派发，它也已经躺在历史里了。
+* **@ 判定覆盖**（`ctx.decide`）只能写在晚挂点 —— 早挂点跑的时候 `mentionGate` 还没执行。
+
+## 三、动作 API 完整签名表（用户看到的就是这些）
+
+### 消息维
+
+| 调用 | 作用 | 用在哪 |
+|---|---|---|
+| `ctx.annihilate({ reason })` | **消灭**这条：不进群历史、不进上下文、不占群冷却。内部 = 让引擎不再 `next()` | 早挂点（晚挂点会被拒 + 告警） |
+| `ctx.rewrite({ text, reason })` | **替换文本**（改的是 `ctx.message.content`） | 早挂点（历史也是改后文本）；晚挂点只改"当前这条" |
+| `ctx.forceWake({ reason })` | **强制入站**：跳过 @ 门控、价值评分、群冷却等一切"值不值得回"的判断；**不伪造 @**（不会多出假的 `(@you)`） | 两个挂点都能调；要连"没 @ 也放行"必须用早挂点 |
+| `ctx.decide({ mention: 'ignore' \| 'force', reason })` | **覆盖 @ 判定**：`ignore` = 这条不按被 @ 处理；`force` = 按被 @ 处理（会被当"点名"） | 晚挂点（早挂点会被拒 + 告警） |
+
+返回值：成功 `true`，被拒/参数不合法 `false`（并在日志里留一条 warn）。
+
+### 用户维（名单，两块挂点都能用）
+
+| 调用 | 作用 |
+|---|---|
+| `ctx.muteUser({ id?, minutes, reason? })` | 禁言：`id` 缺省 = **当前发送者**；`minutes > 0` = 这么多分钟，**`minutes <= 0` = 永久**。成功返回名单项 `{ id, until, reason, by, at }`，失败 `false` |
+| `ctx.unmuteUser({ id? })` | 解禁（可撤销通道）；返回是否真的解掉了一条 |
+| `ctx.isMuted(id?)` | 查一条（缺省 = 当前发送者）：命中返回 `{ id, until, reason, by, at, permanent, remainingMs, remainingMinutes }`，没命中 `null` |
+| `ctx.mutedUsers()` | 整份名单（已做过期清理，带剩余时间，按到期时间升序，永久排最后） |
+
+### 通用取值 / 工具
+
+| 字段 | 说明 |
+|---|---|
+| `ctx.text` | 当前消息文本（**可写**：赋值 = 直接改 `ctx.message.content`，但不会落审计，建议用 `ctx.rewrite`） |
+| `ctx.scope` | `'group' \| 'c2c'` |
+| `ctx.sender` / `ctx.senderName` / `ctx.isOwner` | 发送者 openid / 昵称 / 是否主人（`config.groupAdmin.owners`） |
+| `ctx.groupId` | 群 openid（私聊是 `''`） |
+| `ctx.mentions` | SDK 的 mentions 数组原样 |
+| `ctx.quoted` | 被引原文：`{ text, id, fromSelf }`。`id` = 被引那条的发送者 openid（"回复某人再下令"用它）；`fromSelf` = 是不是她自己说的（**启发式**，靠"她最近一条发言"的文本比对，可能不准）。也可以写成 `ctx.quoted()` 拿一份快照 |
+| `ctx.platform` | `{ mentioned }`：**平台**认为这条 @ 了她吗（判据与 SDK `mentionGate` 一致：`rawEventType` / `mentions[].is_you` / 正文里的 `<@appId>`）。早挂点读不到 `ctx.state.mention`，要判 @ 就用它。也可以写成 `ctx.platform()` |
+| `ctx.logger` | 插件 logger（`info/warn/error/debug`） |
+| `ctx.dataRoot` | 数据根路径（放自己的文件用） |
+| `ctx.kv.get(key)` / `ctx.kv.set(key, value)` | **每个扩展自己的持久化**（与禁言名单同一个文件）；`set(key, undefined)` = 删掉这个键 |
+
+> 所有动作**内部都有 try/catch，任何情况下都不会抛到链上**；出错只 warn 并返回 `false`。
+> `ctx` 上这些属性是**不可枚举**的（不会跟着 `{...ctx}` 被复制走、也不会被 JSON 序列化抓走）。
+
+## 四、禁言名单存哪、怎么过期
+
+```
+{数据根}/.qqbot-extensions/inbound/.state/<你的扩展文件名>.json
+{
+  "mutes": [ { "id": "群友openid", "until": 1760000000000, "reason": "广告", "by": "class-advisor", "at": 1759999000000 } ],
+  "kv":    { "spam:<openid>": [1759999000000, 1759999010000] }
+}
+```
+
+* `until` = 到期时间戳（ms）；**`until: 0` = 永久**（`minutes <= 0` 时写 0，永远不会被清理）。
+* **惰性清理**：每次读名单都会剔掉已过期的项，并把清理结果写回文件。
+* **跨重启有效**：名单在盘上，插件重启/网关重建都还在。
+* **坏文件不崩**：JSON 坏了、形状不对、没权限 —— 一律当空（`mutes: []`、`kv: {}`），插件与消息链照常跑。
+* `.state/` 是**子目录**，不会被当扩展装载（扫描只看 `inbound/` 根下的直接子文件）。
+* 审计账本是**共用**的一个文件：`{数据根}/.qqbot-extensions/inbound/.state/audit.jsonl`。
+
+## 五、四条保命件（插件侧强制，写错也兜得住）
+
+1. **白名单最高优先** —— 主人（`config.groupAdmin.owners` 里的 openid）**永不可被静默/消灭**。
+   扩展对主人调 `ctx.annihilate()` 或 `ctx.muteUser({ id: 主人 })` ⇒ **拒绝执行** + 一条 warn（消息照常放行），审计里记 `result: "refused-owner"`。
+   > ⚠️ 光"拒绝动作"是不够的：最常见的写法是 `if (该消灭) { ctx.annihilate(); return; }` ——
+   > 那个 `return`（不调 `next()`）本来会把链停住，等于"插件说拒绝了、消息还是被吞了"。
+   > 所以引擎还有一条**兜底放行**：扩展既没调 `next()`、又没有一次成功的消灭时 ——
+   > ① 消灭**被拒**过（主人/熔断/挂点不允许）⇒ 引擎替它放行；② 发送者是**主人** ⇒ 引擎替它放行。
+   > 两种情况都会写一条 warn。⇒ **主人的消息永远不会被入站扩展吞掉**（要拦主人请自己去改插件）。
+   > 其余情况（普通群友、扩展自己有意 `return`）保持老契约：链停在这里，消息不进后续任何环节。
+2. **强唤醒优先于静默** —— `ctx.forceWake()` 不会被 `annihilate` 之外的东西抵消；
+   **顺序由你自己排**：把"求助关键词 → forceWake"写在"禁言名单 → annihilate"**之前**，
+   否则会出现"被禁言的人喊救命没人理"（`class-advisor.mjs` 就是照这个顺序写的）。
+3. **熔断** —— 按**每个扩展**统计破坏性动作（消灭/静默）的密度：
+   * 该扩展参与的最近 50 条里，破坏性动作 > 50% ⇒ 熔断；
+   * 该扩展 10 秒内破坏性动作 ≥ 20 次 ⇒ 熔断。
+
+   熔断后：**只停掉该扩展的破坏性动作**（`annihilate`/`muteUser` 返回 `false` + warn，消息照常放行，
+   同样由上面的"兜底放行"保证真的放行），`rewrite`/`forceWake`/`decide` 不受影响；告警里带扩展名与原因。
+   **复位**：改文件后 `/tools-reload`（或重启插件）即可 —— 每次装载都会清掉该扩展的熔断记录。
+4. **审计 + 可撤销** —— 每次 `annihilate / rewrite / forceWake / decide / muteUser / unmuteUser`（含被拒的那种）
+   都往 `audit.jsonl` 追加一行：`{ at, file, name, action, target, reason, text, result }`；
+   `text` 是**截断后的**摘要（120 字），不会把整条消息塞进去；文件超过 512KB 自动轮转成 `audit.jsonl.1`（只留一代）。
+   `muteUser` 随时可以用 `unmuteUser` 解掉。
+
+## 六、从零写一个自己的规则（走查）
+
+**目标**：群里有人发"@她 + 名字"时必须有回应；有人刷同样的句子三次以上就禁言 5 分钟；正文里的手机号要打码。
+
+1. **建文件**：在 `{数据根}/.qqbot-extensions/inbound/` 下新建 `my-rule.mjs`（扩展名只认 `.js/.mjs/.cjs`；文件名就是排序与状态文件的名字）。
+2. **先只写"放行"**，确认能装载：
+
+   ```js
+   export const name = 'my-rule';
+   export async function onInbound(ctx, next) {
+     ctx.logger.info?.('[my-rule] 看到一条：' + ctx.text.slice(0, 20));
+     return next();
+   }
+   ```
+   存盘 → 群里发一句 → `/tools-reload`（或重启插件）。启动日志里会出现
+   `[ext-inbound] 已装载 N 个入站中间件: …, my-rule（其中 M 个含早挂点 onInbound）`；
+   没有这行就看日志里的 `[ext-inbound] ✗ my-rule …`（装载失败会说原因）。
+3. **加规则**（都在早挂点里，因为要影响历史/是否进站）：
+
+   ```js
+   export async function onInbound(ctx, next) {
+     const text = String(ctx.text ?? '');
+
+     // ① 求助/点名优先 —— 必须写在"静默"判断之前
+     if (text.includes('救命') || /在吗|求助/.test(text)) {
+       ctx.forceWake({ reason: '求助关键词' });   // 跳过 @门控/评分/冷却
+       return next();
+     }
+
+     // ② 复读刷屏 → 禁言 5 分钟 + 消灭这条
+     const key = 'say:' + ctx.sender;
+     if (ctx.kv.get(key) === text) {
+       ctx.muteUser({ minutes: 5, reason: '复读刷屏' });
+       ctx.annihilate({ reason: '复读刷屏' });
+       return;                                   // ★ 不调 next() = 不进历史、不进上下文
+     }
+     ctx.kv.set(key, text);
+
+     // ③ 手机号打码（改写：历史里也是打码后的）
+     const masked = text.replace(/(?<!\d)(1[3-9]\d)\d{4}(\d{4})(?!\d)/g, '$1****$2');
+     if (masked !== text) ctx.rewrite({ text: masked, reason: '手机号打码' });
+
+     return next();
+   }
+   ```
+4. **验证**（每条都看一眼）：
+   * 刷屏的那条**没有**出现在 `[历史]` 里（说明消灭真的生效）；
+   * `{数据根}/.qqbot-extensions/inbound/.state/audit.jsonl` 里有一行 `{"action":"annihilate", …}`；
+   * `{数据根}/.qqbot-extensions/inbound/.state/my-rule.mjs.json` 里有 `mutes` 项；
+   * 用主人账号发同样的话 → **不该**被禁言（白名单），日志里有一条 warn。
+5. **调参/关掉**：改文件 → `/tools-reload` 生效；把文件改名成 `my-rule.mjs.bak`（非 `.js/.mjs/.cjs` 不扫描）→ 立即失效。
+
+## 七、本目录的示例
+
+| 文件 | 会自动铺到你的目录吗 | 演示什么 |
+|---|---|---|
+| `no-wake-on-child-quote.mjs` | ✅ **会**（只铺这一个） | **两个挂点同时演示**。晚挂点：引用"子会话转发"的消息不算 @（`ctx.decide`）。早挂点：只读观测 + 两个默认关闭的开关（改写转发头 / 消灭纯转发空壳） |
+| `class-advisor.mjs` | ❌ **不会**，要自己拷 | **辅导员**：① 按发送者禁言（名单+时长，含主人 `/禁言` `/解禁` 指令）② 敏感词/手机号改写 ③ 求助关键词强制到场（**写在黑名单之前**）④ 广告/刷屏直接消灭。**默认 `DRY_RUN = true` 只观察不动手**，看完日志再改 |
+
+> 为什么 `class-advisor` 不自动铺：它会**真删消息、真封人**。插件不该替用户决定"我的群要不要开这套规则"，
+> 更不该在用户数据目录里凭空多出一个会写状态的文件。想看、想用，自己拷过去（记得先留 `DRY_RUN = true`）。
+
+## 八、`hooks/`、`tools/` 与它的区别
+
+| | `hooks/` | **`inbound/`** | `tools/` |
+|---|---|---|---|
+| 跑几次 | **启动时一次** | **每条入站消息一次** | LLM 调一次 |
+| 拿到什么 | `env`（`{ctx, logger, dataRoot, …}`） | `(ctx, next)`（与 `bot.use(mw)` 同签名） | 工具参数 |
+| 干什么 | 起定时器 / 注册监听 / 恢复任务 | **处理这条消息**：消灭 / 改写 / 强制入站 / 管名单 | 查数据、发消息 |
+| 写错了 | 启动少跑一段 | 那条消息处理受影响（引擎兜底：抛错只告警并继续 `next()`） | 那次调用失败 |
+
+一句话：**hooks 管"起什么"，inbound 管"这条怎么处理"**。两者不通用。
+
+## 九、排查速查
+
+| 现象 | 先看这里 |
+|---|---|
+| 扩展没生效 | 文件名扩展名对不对（`.js/.mjs/.cjs`）、日志里有没有 `[ext-inbound] ✗ …`、是否忘了 `/tools-reload` |
+| 消息被吞了 | 你自己的 `annihilate` / 没调 `next()`；审计里有 `annihilate` 行；熔断告警也在日志里 |
+| `ctx.decide` 没反应 | 是不是写在早挂点了（会被拒 + warn：`decide 只在晚挂点 onDecide 有效`） |
+| `ctx.annihilate` 没反应 | 是不是写在晚挂点了（会被拒 + warn：`annihilate 只在早挂点 onInbound 有效`）；或者对方是主人（`refused-owner`） |
+| 低分消息还是回话了 | 日志里搜 `强制入站(入站扩展 forceWake…` —— 可能是你自己的扩展要求的；也可能是 `forceWake` 之后 debounce 把标记带下去了（正常） |
+| 禁言没生效 | `isMuted()` 是不是写在"消灭"之前却被后面的分支覆盖了；名单文件在 `.state/<你的文件名>.json` |
+| 熔断了 | 日志搜 `⚠ 熔断「…」`；复位 = 改文件 + `/tools-reload` |

package/examples/ext-inbound/class-advisor.mjs

@@ -0,0 +1,306 @@
+/**
+ * class-advisor.mjs — 「辅导员」示例：把群当班级管（2026-10-12）
+ *
+ * 抄这个文件就能改出自己的群规：它是**四个动作全都用上**的完整样例，
+ * 每个动作都标了"为什么必须在这一步"。
+ *
+ * 放在 `{数据根}/.qqbot-extensions/inbound/class-advisor.mjs`
+ * （插件启动时会自动铺一份，只补不覆盖）。
+ *
+ * ✅ **本示例默认「只观察、不动手」**：`DRY_RUN = true`（见下面「一、可调参数」）。
+ *     装上之后它会正常跑，但**只往日志里写"我本来会做什么"**，不会消灭消息、不会禁言、不会改文本。
+ *     你先看几天日志（`[class-advisor] DRY` 开头那些行），确认规则符合预期，再把 `DRY_RUN` 改成 `false`。
+ *
+ *     改成 false 之后就真的会动手，默认规则只有两类，都由关键词/频率触发：
+ *       · 广告特征（加微信 / 兼职刷单日赚 / "点击链接" / 短链）→ 消灭 + 临时禁言 10 分钟；
+ *       · 同一人 30 秒内连发 8 条 → 消灭 + 临时禁言 10 分钟（阈值见下面 SPAM_*）。
+ *     **不确定就先别开**：保持 `DRY_RUN = true`，或把文件名改成 `class-advisor.mjs.bak`
+ *     （非 .mjs 不扫描），或把 `AD_MUTE_MINUTES` 设成 0（只删不封）、把 `SPAM_MAX` 调大。
+ *     每一次动作（含被白名单/熔断拒绝的）都会写进
+ *     `{数据根}/.qqbot-extensions/inbound/.state/audit.jsonl`，随时可回看；
+ *     主人（`config.groupAdmin.owners`）**永远不会**被它消灭或禁言（插件强制）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ *  辅导员要的四件事，粒度与位置各不相同：
+ *
+ *  | 能力 | 粒度 | 本文件在哪做（为什么） |
+ *  |---|---|---|
+ *  | **禁言群友**（按发送者静默一段时间，跨重启仍有效） | 用户维 | 早挂点，**最前**（名单必须在"要不要回/@没@/冷却"之前生效） |
+ *  | **替换/和谐入站文本** | 消息维 | 早挂点，`ctx.rewrite` —— **必须在记群历史之前**，否则库里存的是原文 |
+ *  | **强制入站**（不管值不值得回、有没有@、冷却到没到） | 消息维 | 早挂点，`ctx.forceWake`（它同时压过 @门控 与价值评分/冷却） |
+ *  | **直接不入站**（消灭：不进历史、不进上下文、不占冷却） | 消息维 | 早挂点，`ctx.annihilate` + **不调 next()** |
+ *  | （附加）**@ 覆盖**：引用转发不算 @ | 消息维 | 晚挂点（`export default` / `onDecide`），见同目录 no-wake-on-child-quote.mjs |
+ *
+ *  ⚠️ **顺序即优先级**（这是本文件最要紧的一条）：
+ *     ① 主人指令 → ② **求助关键词（必须写在黑名单判断之前！）** → ③ 广告/刷屏 → ④ 禁言名单 → ⑤ 敏感词改写
+ *     把"求助"排在"名单"后面，就会出现"被禁言的人喊救命没人理"——
+ *     强唤醒要压过静默，这是主人点名的保命件之一。
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * ── 你能用的东西（完整清单见同目录 README.md）──────────────────────────────
+ *   ctx.text / ctx.scope / ctx.sender / ctx.senderName / ctx.isOwner / ctx.groupId / ctx.mentions
+ *   ctx.quoted.text / .id / .fromSelf            被引原文、被引那条的发送者、是不是她自己说的
+ *   ctx.platform.mentioned                        平台 @ 信号（早挂点读不到 ctx.state.mention）
+ *   ctx.logger / ctx.dataRoot / ctx.kv.get|set    日志、数据根、每个扩展自己的持久化
+ *   ctx.annihilate / ctx.rewrite / ctx.forceWake / ctx.decide
+ *   ctx.muteUser / ctx.unmuteUser / ctx.isMuted / ctx.mutedUsers
+ *
+ * ── 四条保命件（插件侧强制，你写错也兜得住）───────────────────────────────
+ *   · 白名单最高优先：主人（`config.groupAdmin.owners`）**永不可被静默/消灭**，
+ *     调 `annihilate`/`muteUser` 会被拒 + 告警，消息照常放行；
+ *   · 强唤醒优先于静默：`forceWake` 不被 `annihilate` 以外的东西抵消（顺序由你排，见上面 ⚠️）；
+ *   · 熔断：本扩展短期内消灭/静默占比过高（>50%）或 10 秒内超过 20 次 ⇒
+ *     停掉**本扩展的破坏性动作**（消息照常放行）+ 一条 warn；改文件后 `/tools-reload` 即复位；
+ *   · 审计 + 可撤销：每次动作追加一行
+ *     `{数据根}/.qqbot-extensions/inbound/.state/audit.jsonl`；
+ *     `ctx.muteUser` 随时可以用 `ctx.unmuteUser({ id })` 解掉。
+ *
+ * ── 本文件**不会被自动铺到你的目录**（2026-10-12 主人定）────────────────────
+ *   同目录的 `no-wake-on-child-quote.mjs` 属"装上就该有"的规则，插件首次启动会替你铺一份；
+ *   本文件不铺 —— 因为它会**真动手删消息、封人**，不该替你决定。要试就自己拷：
+ *     copy 本文件 → `{数据根}/.qqbot-extensions/inbound/class-advisor.mjs`
+ *   （拷完 `/tools-reload` 或重启即生效；**记得先留 `DRY_RUN = true` 观察几天**。）
+ *
+ * ── 它会往你数据目录里写什么（就这两样，别的一样不碰）──────────────────────
+ *   · `{数据根}/.qqbot-extensions/inbound/.state/<本文件名>.json`
+ *     形状：`{ "mutes": [{ "id", "until", "reason", "by", "at" }], "kv": {} }`
+ *     **只在真的禁言/解禁时才写**；`until = 0` 表示永久（`minutes <= 0`）；读名单时惰性清理过期项；
+ *     文件坏了当空处理（插件不会因为一个坏 JSON 崩掉）。
+ *   · `{数据根}/.qqbot-extensions/inbound/.state/audit.jsonl`
+ *     每次真动作（含被白名单/熔断拒绝的）追加一行，摘要截断、512KB 轮转。
+ *   ⚠️ **刷屏计数不写盘**（只在内存里存 30 秒窗口）—— 早先版本用 `ctx.kv` 落盘，
+ *      而它对每一条消息都会被调到 ⇒ 每条群消息写一次文件。已改掉，这条路径不碰磁盘。
+ *   ⚠️ **`DRY_RUN = true` 时上面两个文件都不会出现**（只打日志、不动手）。
+ */
+
+/** 日志展示名 */
+export const name = 'class-advisor';
+
+// ══════════════════════════════════════════════════════════════
+// 一、可调参数（抄去改这里）
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * ★★ **安全默认：`true` = 只观察不动手**（本文件唯一的"总闸"）★★
+ *
+ *   true  —— 下面所有**自动规则**（广告/刷屏/禁言名单/敏感词和谐）都只往日志写一行
+ *            `[class-advisor] DRY …`，说明"我本来会做什么"，**不消灭、不禁言、不改文本**。
+ *           消息照常入站，等于一份"这个规则在我群里会怎么判"的体检报告。
+ *   false —— 真的动手。
+ *
+ *   为什么默认 true：**装上不等于放权**。一个从网上抄来的规则文件不该在你没看过它判断之前
+ *   就开始删消息、封人。
+ *
+ *   推荐节奏：先留 true 观察几天 → 翻日志确认它只在你想拦的那些消息上命中 → 改成 false。
+ *
+ *   ⚠️ 例外：**主人亲口下的指令不受总闸影响**（下面 ① 的 `/禁言`、`/解禁` 照常执行）——
+ *      那是你明确下的令，不是这条规则自己判断的。
+ */
+let DRY_RUN = true;
+
+/**
+ * 运行时切换总闸（`setLive(true)` = 真的动手）；返回"这次之前是不是 live"。
+ * 平时用不着 —— 直接改上面那行 `let DRY_RUN` 更直观；
+ * 这个出口是给**测试**和"想临时开一下 / 临时关掉"的场景用的。
+ */
+export function setLive(live) {
+  const wasLive = !DRY_RUN;
+  DRY_RUN = !live;
+  return wasLive;
+}
+
+/** 当前是不是"真的动手"（`false` = 只观察不动手） */
+export function isLive() {
+  return !DRY_RUN;
+}
+
+/**
+ * **求助关键词** —— 命中就 `forceWake`：不管有没有 @ 她、分数多低、群冷却到没到，都要让她看到。
+ * ⚠️ 判断必须放在**禁言名单之前**（见文件头"顺序即优先级"）。
+ * 注：`forceWake` 属于"让消息更可能被看见"，不是破坏性动作，**不受 DRY_RUN 影响**（它只会多看见、不会漏看）。
+ */
+const HELP_KEYWORDS = ['求助', '救命', '急', '报错', '怎么解决', '谁来帮', '帮我看下', '大佬救命', '卡住了'];
+
+/** 广告/刷屏特征（正则）。命中 → 消灭；连续刷屏的还会被临时禁言 */
+const AD_PATTERNS = [
+  /加\s*微\s*信/i,
+  /(?:兼职|刷单|日赚|躺赚|带赚)/,
+  /(?:点击|戳)\s*(?:链接|这里)/,
+  /https?:\/\/\S*(?:t\.cn|dwz|url\.cn|sourl)/i,   // 短链（自己群里正常的网盘长链不受影响）
+];
+
+/** 刷屏判定：同一人 SPAM_WINDOW_MS 内发到 SPAM_MAX 条 → 算刷屏
+ *  ⚠️ 阈值刻意保守（30 秒内 8 条）：正常连发几句不会被误伤；真的要灌水才会命中。
+ *     觉得太严就调大 SPAM_MAX / 调小窗口，或者干脆把下面那段 `noteAndCheckSpam` 去掉。 */
+const SPAM_WINDOW_MS = 30_000;
+const SPAM_MAX = 8;
+
+/** 广告初犯禁言多久（分钟）；`<= 0` = 永久。想"只删不封"就把这里设成 0 并删掉 muteUser 那两行 */
+const AD_MUTE_MINUTES = 10;
+
+/** 敏感词 → 和谐成 `***`（**改写在记群历史之前**，所以 AI 与历史里看到的都是和谐后的文本） */
+const SENSITIVE_WORDS = ['傻逼', '妈的', '滚蛋'];   // ← 按自己群的情况改
+
+/** 手机号打码（11 位，1 开头）—— 群里晒号很常见，顺手和谐掉 */
+const PHONE_RE = /(?<!\d)(1[3-9]\d)\d{4}(\d{4})(?!\d)/g;
+
+// ══════════════════════════════════════════════════════════════
+// 二、纯函数（可单测、可以单独抄走）
+// ══════════════════════════════════════════════════════════════
+
+/** 这条文本是不是在求助？ */
+export function isHelpText(text) {
+  const t = String(text ?? '');
+  if (!t) return false;
+  return HELP_KEYWORDS.some((k) => t.includes(k));
+}
+
+/** 这条文本像不像广告？ */
+export function isAdText(text) {
+  const t = String(text ?? '');
+  if (!t) return false;
+  return AD_PATTERNS.some((re) => re.test(t));
+}
+
+/** 和谐敏感词与手机号；没有可和谐的返回 null（省一次 rewrite） */
+export function maskText(text) {
+  let out = String(text ?? '');
+  const before = out;
+  for (const w of SENSITIVE_WORDS) {
+    if (!w) continue;
+    out = out.split(w).join('*'.repeat(w.length));
+  }
+  out = out.replace(PHONE_RE, '$1****$2');
+  return out === before ? null : out;
+}
+
+/**
+ * 刷屏判定：**只存在内存里**（30 秒的窗口，重启清零完全没影响）。
+ *
+ * ⚠️ 2026-10-12 改（主人："别给我拉屎"）：原来这里用 `ctx.kv` **落盘**，而这个函数对
+ *   **每一条**入站消息都会被调到 ⇒ **每来一条群消息就同步写一次状态文件**。
+ *   那既没必要（窗口只有 30 秒，重启还留着它毫无意义），也是在用户数据目录里拉屎。
+ *   改成进程内的 Map 之后，**这条路径彻底不碰磁盘**。
+ */
+const spamHits = new Map();   // senderId -> 最近发言时刻数组
+
+export function noteAndCheckSpam(ctx) {
+  const key = String(ctx.sender ?? '');
+  const now = Date.now();
+  const prev = spamHits.get(key) ?? [];
+  const recent = prev.filter((t) => now - t < SPAM_WINDOW_MS);
+  recent.push(now);
+  spamHits.set(key, recent.slice(-SPAM_MAX));   // 只留最近 SPAM_MAX 个时刻
+  // 顺带把"早就不说话了"的人清掉，别让 Map 无限涨（几百人规模也只是个小 Map）
+  if (spamHits.size > 500) {
+    for (const [k, v] of spamHits) {
+      if (!v.some((t) => now - t < SPAM_WINDOW_MS)) spamHits.delete(k);
+    }
+  }
+  return recent.length >= SPAM_MAX;
+}
+
+// ══════════════════════════════════════════════════════════════
+// 三、早挂点：四件事全在这（记群历史之前）
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * `onInbound` —— 挂在 **quoteRef 之后、记群历史之前**。
+ * 这里做的每一步都会**改变"群里到底存了什么/她到底看不看得到"**，所以要按优先级排好。
+ */
+export async function onInbound(ctx, next) {
+  try {
+    const text = String(ctx.text ?? '');
+
+    // ── ① 主人指令（只有主人能下令；`ctx.isOwner` 就是 `config.groupAdmin.owners` 里有没有他）──
+    //   用法：主人**回复**某个群友的消息，然后发 `/禁言 30`（分钟；0 或省略 = 永久）。
+    //   ⚠️ 注意这里用 `rewrite` 而不是 `annihilate`：**主人的消息永远不被入站扩展吞掉**
+    //      （白名单最高优先，引擎发现"消灭被拒"或"没放行主人的消息"会替它放行并告警）。
+    //      指令消息改成一行留痕，既不污染上下文、又符合"主人消息必须放行"的规矩。
+    const cmd = /^\/禁言\s*(\d+)?\s*$/.exec(text.trim());
+    if (cmd && ctx.isOwner) {
+      const target = ctx.quoted.id;           // 被回复那条的作者 openid（拿不到是空串）
+      const minutes = cmd[1] === undefined ? 0 : Number(cmd[1]);
+      if (!target) {
+        ctx.logger.warn?.('[class-advisor] /禁言：要**回复**某个群友的消息再发这条指令（拿不到被回复人）');
+      } else {
+        const m = ctx.muteUser({ id: target, minutes, reason: '主人指令 /禁言' });
+        ctx.logger.info?.(`[class-advisor] 主人禁言 ${target}：${m ? (m.until === 0 ? '永久' : minutes + ' 分钟') : '失败(见审计)'}`);
+      }
+      ctx.rewrite({ text: '（辅导员：禁言指令已处理）', reason: '主人指令' });
+      return next();
+    }
+    // 解禁：`/解禁` + 回复某人
+    if (/^\/解禁\s*$/.test(text.trim()) && ctx.isOwner) {
+      const target = ctx.quoted.id;
+      if (target) ctx.unmuteUser({ id: target });
+      ctx.rewrite({ text: '（辅导员：解禁指令已处理）', reason: '主人指令' });
+      return next();
+    }
+
+    // ── ② 求助优先（**必须写在黑名单判断之前**）──
+    //   被禁言的人喊"救命"也要放行：强唤醒优先于静默。
+    if (isHelpText(text)) {
+      ctx.forceWake({ reason: '求助关键词' });
+      ctx.logger.debug?.(`[class-advisor] 求助关键词命中 → 强制入站: "${text.slice(0, 30)}"`);
+      return next();     // ★ 仍然往下走（forceWake 只是"必须进站"，不是"拦掉别人"）
+    }
+
+    // ── ③ 广告 / 刷屏 → 消灭（顺手临时禁言；白名单与熔断会兜住误伤）──
+    if (isAdText(text) || noteAndCheckSpam(ctx)) {
+      const why = isAdText(text) ? '广告特征' : `${SPAM_WINDOW_MS / 1000}s 内连发 ${SPAM_MAX} 条`;
+      if (DRY_RUN) {
+        // 只观察：说清"本来会做什么"，然后把消息放过去（绝不 return）
+        ctx.logger.info?.(`[class-advisor] DRY 本来要【消灭${AD_MUTE_MINUTES !== 0 ? ` + 禁言 ${AD_MUTE_MINUTES} 分钟` : ''}】`
+          + `（${why}）sender=${ctx.senderName || ctx.sender} text="${text.slice(0, 40)}"`);
+      } else {
+        if (AD_MUTE_MINUTES !== 0) {
+          ctx.muteUser({ minutes: AD_MUTE_MINUTES, reason: `广告/刷屏：${why}` });
+        }
+        ctx.annihilate({ reason: `广告/刷屏：${why}` });
+        return;          // ★ 不调 next() = 不进群历史、不进上下文、不占群冷却
+      }
+    }
+
+    // ── ④ 禁言名单 → 静默（名单是持久的，重启仍在；`isMuted()` 缺省查当前发送者）──
+    const muted = ctx.isMuted();
+    if (muted) {
+      const left = muted.permanent ? '永久' : `还剩 ${muted.remainingMinutes} 分钟`;
+      if (DRY_RUN) {
+        ctx.logger.info?.(`[class-advisor] DRY 本来要【静默】sender=${ctx.senderName || ctx.sender}`
+          + `（禁言中 · ${left} · ${muted.reason ?? '未写原因'}）`);
+      } else {
+        ctx.annihilate({ reason: `禁言中（${left}）：${muted.reason ?? '未写原因'}` });
+        return;          // ★ 同样是不调 next()
+      }
+    }
+
+    // ── ⑤ 敏感词/手机号 → 改写（**必须在记群历史之前**：库里存的就是和谐后的文本）──
+    const masked = maskText(text);
+    if (masked !== null) {
+      if (DRY_RUN) {
+        ctx.logger.info?.(`[class-advisor] DRY 本来要【改写】"${text.slice(0, 40)}" → "${masked.slice(0, 40)}"`);
+      } else {
+        ctx.rewrite({ text: masked, reason: '敏感词/手机号和谐' });
+        ctx.logger.debug?.(`[class-advisor] 已和谐入站文本（历史与上下文都用改后文本）`);
+      }
+    }
+  } catch {
+    /* 兜底：本扩展出任何问题都绝不影响主链（引擎也还有一层 try/catch） */
+  }
+  return next();
+}
+
+// ══════════════════════════════════════════════════════════════
+// 四、可选：晚挂点（@ 覆盖）
+// ══════════════════════════════════════════════════════════════
+// 本文件**故意不导出**晚挂点：上面四件事全都必须发生在"记群历史之前"。
+// 需要"引用转发不算 @"这类**改 @ 判定**的规则，请照抄同目录的
+// no-wake-on-child-quote.mjs（它同时演示了两个挂点），或者在本文件里额外加：
+//
+// export default async function onDecide(ctx, next) {
+//   if (ctx.state?.mention?.wasMentioned === true && ctx.quoted.fromSelf === false && /【子会话/.test(ctx.quoted.text)) {
+//     ctx.decide({ mention: 'ignore', reason: '引用的是子会话转发' });
+//   }
+//   return next();
+// }