@zaofan/dsh-qqbot 1.8.6 → 1.9.2

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();
+// }

package/examples/ext-inbound/no-wake-on-child-quote.mjs

@@ -0,0 +1,192 @@
+/**
+ * no-wake-on-child-quote.mjs — 示例入站中间件：引用「子会话转发」的消息时不按 @ 处理
+ * （2026-10-12 升级：**同时演示早/晚两个挂点**；晚挂点那段逻辑一个字没改）
+ *
+ * 放在 `{数据根}/.qqbot-extensions/inbound/no-wake-on-child-quote.mjs`
+ * （插件启动时会自动铺一份，只补不覆盖）。
+ *
+ * ── 它解决什么 ──────────────────────────────────────────────────────────────
+ * 群里有人把别的会话（子会话）的转发消息**引用**过来，再顺带 @ 一下她 ——
+ * 平台信号上这确实是「被 @ 了」，于是：
+ *   · 门控放行；· debounce 认为"窗口里有 @" → **绕过群冷却、静默 3 秒后强制唤醒**；
+ *   · 上下文里那条还会被标成 `(@you)`、结构化标记 `mentioned:true`。
+ * 但那条被引用的原文其实只是「另一个会话的转发内容」，不该因此强行叫醒她 ——
+ * 她照常看到这条消息（进历史、进上下文），只是**不按"被点名"处理**（该不该开口交给她自己按守则判断）。
+ *
+ * ── 两个挂点各干什么（本文件同时演示）──────────────────────────────────────
+ *
+ * ```
+ * … → quoteRef → ★onInbound（早，本文件的 export function onInbound）★
+ *   → 引用图预取 → 群历史缓冲 → … → mentionGate（@ 门控）
+ *   → ★默认导出 / onDecide（晚，本文件的 export default）★ → contentSanitizer → debounce → …
+ * ```
+ *
+ * | | 早（`onInbound`） | 晚（`export default` / `onDecide`） |
+ * |---|---|---|
+ * | 能读 | `ctx.message` / `ctx.state.quote` / `ctx.platform.mentioned` | 以上全部 **+ `ctx.state.mention`**（门控判定） |
+ * | 能做 | 消灭 · 改写 · 强制入站 · 查/写禁言名单 | 覆盖 @ 判定 · 改写 · 强制入站 · 查/写禁言名单 |
+ * | 不能做 | `ctx.decide`（mention 还没写出来） | `ctx.annihilate`（群历史已经记过了，会被拒绝） |
+ *
+ * 晚挂点怎么做到"降级 @ 判定"：链上位置在 mentionGate **之后**，所以这里：
+ *   ① 读得到 `ctx.state.mention`（门控刚写下的判定）；
+ *   ② **改得动**它 —— `ctx.decide({ mention: 'ignore' })`（等价于直接写 `wasMentioned = false`，
+ *      但会落审计、也会把"早挂点误调"这种用法明确拒绝掉）；
+ *   ③ 还能直接不调 `next()` 把这条**整条拦掉**（本示例不用，它只是"降级"不是"拦截"）。
+ * 被引原文的来源是现成的 `ctx.state.quote.text`（quoteRef 中间件在链前部赋的值，
+ * media-history 与 debounce 都在读它）——**别自己写引用解析**。
+ *
+ * 早挂点在本文件里做什么：**只读观测 + 两个默认关闭的可选动作**。
+ *   它是链上唯一"还没记群历史"的位置 —— 所以消灭（`ctx.annihilate`）、改写（`ctx.rewrite`）、
+ *   强制入站（`ctx.forceWake`）都只在这里才是"真动作"。本示例默认**不做**破坏性动作
+ *   （它是插件自动铺给每个用户的示例，不能悄悄吞消息），把写法留在下面两个开关里：
+ *   想用就把开关改成 true，改完 `/tools-reload` 立即生效。
+ *
+ * ── 用法/契约速查 ──────────────────────────────────────────────────────────
+ *   · 早挂点：`export async function onInbound(ctx, next)`（也可以是 `export const onInbound = …`）；
+ *   · 晚挂点：`export default async (ctx, next)`，**语义等同 `export async function onDecide(ctx, next)`**；
+ *     一个文件可以同时导出两个，互不影响；只导出其一也完全可以；
+ *   · 可选导出 `dispose()`，插件卸载时调用（本示例没有需要收尾的东西，故不导出）；
+ *   · `{数据根}/.qqbot-extensions/inbound/` 目录不存在或为空 = 完全安静（不打任何日志）；
+ *   · 单个扩展抛错只告警并继续 `next()` —— 用户脚本坏了**绝不会**把入站消息吞掉；
+ *   · 任何动作（annihilate/rewrite/forceWake/decide/muteUser…）内部都有 try/catch，**不会抛到链上**；
+ *   · 改完文件后：`/tools-reload`（或工具 `tools_reload`）即可热重载；重启插件当然也生效。
+ */
+
+/** 只用于日志展示（不写就用文件名） */
+export const name = 'no-wake-on-child-quote';
+
+/**
+ * 子会话转发前缀的宽松匹配。
+ *
+ * 宽松是刻意的：**不抠 id、不要求右括号** —— 被引原文可能被平台按 60 字截断，
+ * 于是 `【子会话 abc1`（无 `】`）与光秃秃的 `【子会话`（正好截在前缀处）都要命中。
+ * 普通文本里出现"子会话"三个字但**没有 `【`** 一律不命中（避免误伤正常聊天）。
+ */
+const CHILD_SESSION_QUOTE_RE = /【子会话(?:\s|\u3000|$)/;
+
+/**
+ * 纯函数（可单测、也可被别的扩展/debug 复用）：
+ * 这段"被引用的原文"是不是一条子会话转发消息？
+ *
+ * @param {string|null|undefined} quotedText 被引原文（= `ctx.state.quote?.text`）
+ * @returns {boolean} true = 命中子会话转发前缀
+ */
+export function isChildSessionForwardQuote(quotedText) {
+  const t = String(quotedText ?? '');
+  if (!t) return false;
+  return CHILD_SESSION_QUOTE_RE.test(t);
+}
+
+// ══════════════════════════════════════════════════════════════
+// 开关：早挂点里两个**默认关闭**的动作示范
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * true = 把"纯转发壳"消息**消灭**掉（不进群历史、不进上下文、不占群冷却）。
+ *
+ * 什么算纯转发壳：正文去掉 @ 之后**什么都不剩**，且**没有附件**。
+ * 这种消息对她没有任何信息量，却会占到一次群历史与一枚群冷却。
+ * ⚠️ 默认 **false**：本文件是插件自动铺给每个用户的示例，不能悄悄吞消息 ——
+ *    想用请自己改成 true，并确认你知道"消灭 = 这条连历史都不进"。
+ */
+const ANNIHILATE_EMPTY_CHILD_FORWARD = false;
+
+/**
+ * true = 把正文开头的转发头 `【子会话 xxx】` **改写**掉（群历史里存的就是改后文本）。
+ * ⚠️ 默认 **false**：转发头有时是用户自己想要的线索，先看清楚再开。
+ */
+const REWRITE_STRIP_CHILD_PREFIX = false;
+
+/** 转发头（比"引用判定"严格：要求带 id 与右括号）—— 只给上面两个开关用 */
+const CHILD_SESSION_PREFIX_RE = /^【子会话\s*[0-9a-fA-F]{1,32}】\s*/;
+
+/** 只留"真正的内容"：去掉 @ 标记与空白，用来判断"这条是不是空壳" */
+function contentWithoutMentions(ctx) {
+  return String(ctx?.text ?? '')
+    .replace(/<@!?[^>]+>/g, '')   // QQ 的 @ 标记：<@openid> / <@!openid>
+    .replace(/@bot/g, '')          // 进上下文前后插件会把 @她 换成 @bot（这里只是保险）
+    .replace(/\s+/g, '');
+}
+
+/**
+ * ★ 早挂点 `onInbound`（2026-10-12 新增）★
+ *
+ * 位置：**quoteRef 之后、记群历史之前**。这一层能读、能做的东西与晚挂点不同：
+ *   · 读得到 `ctx.message` / `ctx.state.quote`（被引原文）/ `ctx.platform.mentioned`（平台 @ 信号）；
+ *   · **读不到** `ctx.state.mention`（那是后面 mentionGate 才写的，这里永远是 undefined —— 别读）；
+ *   · 只有在这里：`ctx.rewrite()` 能改到**群历史**里存的文本；`ctx.annihilate()` 能真的"消灭"
+ *     （不调 next() ⇒ 后面的群历史缓冲、门控、评分、冷却全都不会跑）。
+ *
+ * ⚠️ 要把 `next()` 交出去（`return next()`）：除非你**确实**想消灭这条消息。
+ */
+export async function onInbound(ctx, next) {
+  try {
+    // 这里读不到 ctx.state.mention —— 想看"平台认为这条 @ 了她吗"，用 ctx.platform.mentioned
+    // （判据与 SDK 的 mentionGate 完全一致：rawEventType / mentions[].is_you / 正文里的 <@appId>）
+    const mentioned = ctx?.platform?.mentioned === true;
+    const quoted = ctx?.quoted?.text ?? '';
+
+    if (ctx?.scope === 'group' && isChildSessionForwardQuote(quoted)) {
+      // 只读观测（debug 级，别刷屏）：这一步群历史**还没记** —— 对照晚挂点那条日志的时间序
+      ctx?.logger?.debug?.(
+        `[ext-inbound:${name}] 早挂点：引用的是子会话转发（平台@=${mentioned}，正文"${String(ctx.text).slice(0, 20)}"）` +
+        ' → 群历史尚未记录，改写/消灭只能在这里做',
+      );
+
+      // ── 可选动作 ①：改写（把转发头从**要进群历史**的正文里去掉）──
+      if (REWRITE_STRIP_CHILD_PREFIX && CHILD_SESSION_PREFIX_RE.test(String(ctx.text ?? ''))) {
+        ctx.rewrite({
+          text: String(ctx.text).replace(CHILD_SESSION_PREFIX_RE, ''),
+          reason: '去掉子会话转发头（历史里不必留机器前缀）',
+        });
+      }
+
+      // ── 可选动作 ②：消灭（纯转发空壳：没正文、没附件，只剩一个 @）──
+      const atts = Array.isArray(ctx?.message?.attachments) ? ctx.message.attachments : [];
+      if (ANNIHILATE_EMPTY_CHILD_FORWARD && atts.length === 0 && contentWithoutMentions(ctx) === '') {
+        ctx.annihilate({ reason: '子会话转发空壳（无正文无附件）' });
+        return;   // ★ 不调 next() = 这条不进历史、不进上下文、不占冷却
+      }
+
+      // ── 可选动作 ③：强制入站（确定要她看到这条时）──
+      // ctx.forceWake({ reason: '引用里点名了她' });   // 跳过 @门控 / 价值评分 / 群冷却
+    }
+  } catch {
+    /* 兜底：本扩展出任何问题都绝不影响主链 */
+  }
+  return next();
+}
+
+/**
+ * ★ 晚挂点（默认导出 = `onDecide`）★ —— 只做编排，判定逻辑在上面的纯函数里。
+ *
+ * ⚠️ 只在**群聊**生效：私聊的 `wasMentioned=true` 是 SDK 的 passthrough 标记（`reason: 'passthrough'`），
+ * 不是"被 @ 了"的判定；压它只会让上下文丢掉 `(@you)` 标签，而私聊本来每条都唤醒 ⇒
+ * 既拦不住也不该动。
+ *
+ * ⚠️ 永远 `await next()`（这里直接 `return next()`）：本示例是"降级"不是"拦截"，
+ * 绝不能把消息吞掉 —— 吞掉会让这条既不进上下文也不进历史。
+ */
+export default async function noWakeOnChildQuote(ctx, next) {
+  try {
+    if (ctx?.message?.kind === 'group') {
+      const quoted = ctx?.state?.quote?.text;
+      if (isChildSessionForwardQuote(quoted)) {
+        const mention = ctx?.state?.mention;
+        // 只压「确实是 @ 判定为 true」的那种；别的（本来就没@）不用动
+        if (mention && mention.wasMentioned === true) {
+          // 走动作 API（而不是直接改 ctx.state.mention）：会落一行审计，
+          // 而且"在早挂点调 decide"这种用法会被明确拒绝 + 告警。
+          ctx.decide({ mention: 'ignore', reason: '引用的是子会话转发消息' });
+          // debug 级 —— 别刷屏（群消息多，这条规则会经常命中）
+          ctx.log?.debug?.(
+            `[ext-inbound:${name}] 引用的是子会话转发消息 → 不按 @ 处理: ${String(quoted).slice(0, 40)}`,
+          );
+        }
+      }
+    }
+  } catch {
+    /* 兜底：本扩展出任何问题都绝不影响主链 */
+  }
+  return next();
+}

package/examples/ext-tools/README.md

@@ -46,6 +46,28 @@
 | 抓取通道 | 先走 Bing 的 RSS 端点（`?format=rss`，解析最稳、不需要 key），失败回退 HTML 抓取；国内可直连 `cn.bing.com` |
 | 暴露范围 | 声明了 `expose: 'all'` ⇒ 全部会话可用（含 web / 终端）；只想在 QQ 会话可见就删掉那一行 |
 
+## 跨会话四件套 — `session_create` / `session_send` / `session_watch` / `sessions_list`
+
+演示「**让一个会话去开另一个会话、把话投过去、再把结果收回来**」。四个配合用；`lib/` 里是它们
+按 mtime 版本化加载的内部模块（**子目录不参与工具扫描**，放那里最安全；插件铺设时也会连子目录一起搬）。
+
+| 工具 | 作用 | 关键点 |
+|---|---|---|
+| `session_create` | 建**子会话**并把初始任务投进去 | 可指定工作区与人设 —— 工作区名、人设的**显示名或 id** 都认（忽略大小写、唯一子串也认） |
+| `session_send` | 往**任意会话**投消息（发送工具） | 照抄本插件的**入站模式**：忙时插话（`inject`）/ 空闲唤醒（`followup`）；首行带来源会话 id |
+| `session_watch` | 挂 / 摘「回合结束回灌」钩子 | 子会话跑完自动把末段正文送回来；`action:"list"` 看钩子名单 |
+| `sessions_list` | 列工作区与会话（只读） | 工作区按**子串**过滤（注意「A」也会命中「AB」） |
+
+**三条经验（都是踩出来的）**
+
+1. **别自己拼消息对象** —— 往会话塞消息用宿主原语（`agent.inject` / `agent.followup`）；
+   手拼 `user/message` 容易写坏会话（本项目实测触发过 `agent/inbox/spliced requires message objects`，
+   只能靠离线修数据恢复）。
+2. **投递前先 resume** —— 非 live 的会话直接 `append` 会被**静默丢弃**（不报错，最难查的一种）。
+3. **可见性靠 `expose` 控** —— `expose:'all'` 会被挂到插件根、**所有会话都能看到**（含 web / 终端）；
+   不写该字段（或写别的值）则**只在 QQ 会话注册**，子会话看不到。建议：建会话/挂钩子这类
+   **父会话专用**件不给子会话看（免得无限套娃），只把「投递/回执」那一个开放给子会话。
+
 ## 写自己的「按钮回调」工具，只要记住三件事
 
 1. **发卡前登记卡片**（不登记 = 按钮点了没人认）：

package/examples/ext-tools/lib/preset_resolve.mjs

@@ -0,0 +1,85 @@
+/**
+ * preset_resolve.mjs — 把「人设」输入解析成宿主的 preset **id**
+ *
+ * ── 为什么单独成库（2026-10-12）────────────────────────────────────────────
+ * 解析规则还会变，而工具文件**一旦落名就不能再改**（宿主扫描后按 `name@tag`
+ * 幂等跳过，改了不生效 ⇒ 只能再升一个版本号）。把易变逻辑放这里，用
+ * `?v=<mtimeMs>` 版本化加载，改本文件即时生效，工具名不用动。
+ *
+ * ── 主人指定的匹配顺序（2026-10-12）──────────────────────────────────────
+ *   收**任何字符**，依次尝试：
+ *     ① 预设名（显示名）精确匹配  → 反查 id
+ *     ② id 精确匹配
+ *     ③ 两者的「忽略大小写」精确匹配
+ *     ④ 唯一子串匹配（名或 id 包含输入）——唯一才用，多个则报歧义
+ *   都失败 → 返回 error，并把可用清单带上（供调用方直接回给用户）。
+ *
+ * 输入的容忍度：去首尾空白；剥掉成对的「」『』【】《》""'' 方括号/引号。
+ */
+export const __LIB_VERSION__ = 'preset-resolve-v1-20261012-先名后id';
+
+/** 归一化输入：trim + 剥掉包裹的引号/书名号 */
+export function normPresetKey(s) {
+  let t = String(s ?? '').trim();
+  for (let i = 0; i < 3; i += 1) {
+    const before = t;
+    t = t.replace(/^[「『【《〈（(\["'“‘]+/, '').replace(/[」』】》〉）)\]"'”’]+$/, '').trim();
+    if (t === before) break;
+  }
+  return t;
+}
+
+/** 取全部预设（id + 显示名）——权威来源是宿主服务 `ctx.agentPresets` */
+export async function listPresets(root) {
+  const get = (k) => { try { return root?.get?.(k); } catch { return undefined; } };
+  const reg = get('agentPresets');
+  if (!reg || typeof reg.list !== 'function') return [];
+  let all = [];
+  try { all = (await reg.list()) || []; } catch { return []; }
+  if (!Array.isArray(all)) return [];
+  return all
+    .map((p) => ({ id: String(p?.id ?? '').trim(), name: String(p?.name ?? '').trim() }))
+    .filter((p) => p.id);
+}
+
+/** 一行展示：id(显示名) */
+export function presetLabel(p) {
+  return p && p.id ? p.id + (p.name ? '(' + p.name + ')' : '') : String(p ?? '');
+}
+
+/**
+ * 解析人设输入 → preset id。
+ * @returns {{id:string, via:string, all:Array, error?:string}}
+ *   via: 'name' | 'id' | 'name(i)' | 'id(i)' | 'substring' | ''（失败）
+ */
+export async function resolvePreset(root, want) {
+  const raw = String(want ?? '');
+  const all = await listPresets(root);
+  // 拿不到注册表 → 原样放行（交给宿主报错，至少不阻断）
+  if (!all.length) return { id: normPresetKey(raw), via: 'passthrough', all };
+  const k = normPresetKey(raw);
+  if (!k) return { id: '', via: '', all, error: '人设参数是空的' };
+  const lk = k.toLowerCase();
+
+  // ① 预设名（显示名）精确 → 反查 id   ★主人指定优先
+  const n1 = all.find((p) => p.name === k);
+  if (n1) return { id: n1.id, via: 'name', all };
+
+  // ② id 精确
+  const i1 = all.find((p) => p.id === k);
+  if (i1) return { id: i1.id, via: 'id', all };
+
+  // ③ 忽略大小写的精确（名 → id）
+  const n2 = all.find((p) => p.name.toLowerCase() === lk);
+  if (n2) return { id: n2.id, via: 'name(i)', all };
+  const i2 = all.find((p) => p.id.toLowerCase() === lk);
+  if (i2) return { id: i2.id, via: 'id(i)', all };
+
+  // ④ 唯一子串（名或 id 包含输入）
+  const subs = all.filter((p) => (p.name && p.name.toLowerCase().includes(lk)) || p.id.toLowerCase().includes(lk));
+  if (subs.length === 1) return { id: subs[0].id, via: 'substring', all };
+  if (subs.length > 1) {
+    return { id: '', via: '', all, error: '「' + raw + '」匹配到多个人设，请说得更准: ' + subs.map(presetLabel).join('、') };
+  }
+  return { id: '', via: '', all, error: '没找到人设「' + raw + '」。可用: ' + all.map(presetLabel).join('、') };
+}