qq-bot-roost 0.8.13 → 0.8.14

package/README.md

@@ -8,9 +8,9 @@
 
 <img src="https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22.13+">
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
-<img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
+<img src="https://img.shields.io/badge/tests-700%2B%20passed-brightgreen" alt="测试 700+ 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-0.8.13-blueviolet" alt="版本 0.8.13">
+<img src="https://img.shields.io/badge/version-0.8.14-blueviolet" alt="版本 0.8.14">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 <a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 
@@ -424,8 +424,8 @@ bot/
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（431 项）
-│   ├── e2e.mjs                 端到端测试（168 项，起真实服务打接口）
+│   ├── selftest.mjs            框架自检（511 项）
+│   ├── e2e.mjs                 端到端测试（185 项，起真实服务打接口）
 │   ├── qrlogin.mjs             扫码建机器人（8 项）
 │   └── deps.mjs                插件依赖安装（11 项）
 ├── web/                        面板前端（原生 JS/CSS，无构建）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.13",
+  "version": "0.8.14",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -10,8 +10,11 @@ const log = createLogger('api');
 export const FILE_TYPE = { IMAGE: 1, VIDEO: 2, VOICE: 3, FILE: 4 };
 
 /**
- * 官方硬限制：同一条消息最多被动回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端返回 40034128「被动回复时间或次数超限」。
+ * 被动回复序号的**最后一道**兜底上限。
+ *
+ * 官方口径按会话类型不同：群聊 5 次（`msg_seq` 1–5），单聊 4 次（1–4）。
+ * 这里只按 `msgId` 记，拿不到会话类型，所以取两者较大的 5 当「绝不可能超过」的硬顶。
+ * 精确拦截在 `outbound.js`（`PASSIVE_MAX_REPLIES[kind]`），正常流程走不到这里。
  */
 const PASSIVE_MAX_SEQ = 5;
 
@@ -164,6 +167,16 @@ export class QQApi {
       const err = new Error(`HTTP ${res.status} ${method} ${path}: ${msg}`);
       err.status = res.status;
       err.body = data;
+      /**
+       * QQ 的业务错误码，和 HTTP 状态码是两回事。
+       *
+       * 同样是 400，`40054004`（无好友关系）和 `40034006`（内容违规）
+       * 该做的事完全不同：前者要更新可达性状态，后者只能改文案。
+       * 上层拿不到这个码就只能瞎猜，所以在这里就拆出来。
+       *
+       * 常见值见 `docs/官方接口限制.md` 与 `src/reach.js`。
+       */
+      err.qqCode = Number(data?.code ?? data?.err_code ?? 0) || 0;
       throw err;
     }
     return data;
@@ -946,14 +959,14 @@ export class QQApi {
   }
 
   /**
-   * 被动回复序号。官方硬限制：**同一条消息最多回复 5 次**（msg_seq 取 1–5），
-   * 第 6 次返回 40034128。这里兜一道，正常流程由 outbound.js 先拦。
+   * 被动回复序号。硬顶见 `PASSIVE_MAX_SEQ`（群聊 5 / 单聊 4，这里取 5 兜底），
+   * 超了服务端返回 40034128。正常流程由 outbound.js 按会话类型先拦。
    */
   #nextSeq(msgId) {
     const cur = this.seqMap.get(msgId) ?? 0;
     if (cur >= PASSIVE_MAX_SEQ) {
       throw new Error(
-        `同一条消息最多回复 ${PASSIVE_MAX_SEQ} 次（QQ 官方限制），这条已经回了 ${cur} 次`,
+        `同一条消息最多回复 5 次（群聊）/ 4 次（单聊），这条已经回了 ${cur} 次`,
       );
     }
     const next = cur + 1;

package/src/bot.js

@@ -16,6 +16,7 @@ import { BotMetrics } from './runtime.js';
 import { claimInstance, releaseInstance } from './instance.js';
 import { botPaths, DIRS, rel } from './paths.js';
 import { StatsStore } from './storage/index.js';
+import { createReach } from './reach.js';
 
 /**
  * 一个机器人的完整运行时。
@@ -86,6 +87,14 @@ export class BotRuntime {
      */
     this.groupNames = new Map();
     this.roles = new RoleStore(this.paths.roles);
+    /**
+     * 可达性：谁能私聊、哪个群能主动推。
+     *
+     * 官方没有查好友的接口，只能靠 6 个事件维护（FRIEND_ADD/DEL、
+     * C2C_MSG_REJECT/RECEIVE、GROUP_MSG_REJECT/RECEIVE）。
+     * 插件可以通过 `bot.reach` 直接问，不用自己监听一遍。
+     */
+    this.reach = createReach({ file: this.paths.reach });
     this.outbound = null;
     this.session = null;
     this.pipeline = null;
@@ -183,6 +192,7 @@ export class BotRuntime {
       outbound: this.outbound,
       session: this.session,
       pipeline: this.pipeline,
+      reach: this.reach,
       isOwner: (uid) => cfg.owners.includes(uid),
       // 插件声明了 frameworkVersion 就做兼容校验；作者本地调试可以关掉
       ignoreCompat: this.globalCfg.plugins?.ignoreFrameworkVersion === true,
@@ -344,6 +354,51 @@ export class BotRuntime {
     return this.groupNames.get(groupOpenid)?.name || undefined;
   }
 
+  /**
+   * 用 6 个事件维护可达性。
+   *
+   * 官方**没有查好友列表的接口**（sitemap 里 `friend` 只有两个事件页），
+   * 所以「接入之前就存在的关系」永远是未知的，只能维护「接入之后的变化」。
+   * 三态语义与判定顺序见 `src/reach.js` 头注释。
+   */
+  async #noteReach(eventName, d) {
+    const openid = d?.openid ?? '';
+    switch (eventName) {
+      case 'FRIEND_ADD':
+        await this.reach.noteFriendAdd({
+          openid,
+          unionOpenid: d?.author?.union_openid ?? '',
+          scene: d?.scene ?? 0,
+        });
+        break;
+      case 'FRIEND_DEL':
+        await this.reach.noteFriendDel({ openid });
+        break;
+      case 'C2C_MSG_REJECT':
+        await this.reach.noteC2cPush({ openid, on: false });
+        break;
+      case 'C2C_MSG_RECEIVE':
+        await this.reach.noteC2cPush({ openid, on: true });
+        break;
+      case 'GROUP_MSG_REJECT':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: false,
+          by: d?.op_member_openid,
+        });
+        break;
+      case 'GROUP_MSG_RECEIVE':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: true,
+          by: d?.op_member_openid,
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
   /**
    * 补一个群的名字（给面板调的公开入口，内部走带缓存的那份）。
    * 不会抛异常，调用方不用 try/catch。
@@ -415,6 +470,7 @@ export class BotRuntime {
     await this.outbound?.flush().catch(() => {});
     await this.groups?.flush().catch(() => {});
     await this.roles?.flush().catch(() => {});
+    await this.reach?.flush().catch(() => {});
     this.stats?.close();
     if (!this.mock) await releaseInstance(this.cfg.appId).catch(() => {});
     this.state = 'stopped';
@@ -456,6 +512,12 @@ export class BotRuntime {
         await groups.onRemoved(d?.group_openid);
       }
 
+      // 可达性：官方没有查询接口，只能靠这 6 个事件维护（见 src/reach.js）
+      // 放在插件监听器之前，插件读到的就是最新状态
+      await this.#noteReach(eventName, d).catch((e) => {
+        this.log.warn(`可达性更新失败: ${e.message}`);
+      });
+
       const meta = EVENTS[eventName] ?? null;
       for (const l of registry.listeners.get(eventName) ?? []) {
         // 事件里的群：有 group_openid 就按群开关过滤，没有（如私聊事件）就放行
@@ -478,6 +540,14 @@ export class BotRuntime {
 
     /* ---- 消息事件 ---- */
     const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session });
+
+    // 收到私聊 = 好友关系存在的强证据。不置 c2cPush：他能发不等于他允许机器人主动推
+    if (msg.kind === 'c2c' && msg.userId) {
+      this.reach
+        .noteC2cObserved({ openid: msg.userId, unionOpenid: d?.author?.union_openid })
+        .catch(() => {});
+    }
+
     /**
      * 先播出去，再做业务处理。
      *

package/src/message-bus.js

@@ -104,7 +104,7 @@ export function serializeMessage(botId, msg) {
     mentioned: Boolean(msg.mentioned),
     addressed: Boolean(msg.addressed),
     isCommand: Boolean(msg.isCommand),
-    /** 被动回复用（5 分钟窗口，同一条最多 5 次） */
+    /** 被动回复用（群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次） */
     msgId: msg.id,
     /** 引用回复用（message_reference.message_id） */
     msgIdx: msg.msgIdx,

package/src/message.js

@@ -362,7 +362,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   }
 
   // 底层发送：group 走群接口，c2c 走单聊接口。
-  // 一律经过 outbound，由它处理 5 分钟窗口、每秒限速、主动消息额度。
+  // 一律经过 outbound，由它处理被动窗口（群聊 5 分钟 / 单聊 60 分钟）、每秒限速、主动消息额度。
   const send = (opts, passive) => {
     if (kind !== 'group' && kind !== 'c2c') return Promise.resolve(null);
     const body = passive ? { msgId: msg.id, ...opts } : { ...opts };
@@ -410,7 +410,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   const MAX_CHUNK = 1500; // 单条上限，超了按行切成多条
 
   /**
-   * 被动回复（带 msg_id，5 分钟内有效）。
+   * 被动回复（带 msg_id，群聊 5 分钟内、单聊 60 分钟内有效）。
    * **不会立刻发出**，而是攒到本次处理结束，由 flushReplies() 合并成一条。
    * 想立刻发用 msg.replyNow()。
    */
@@ -446,7 +446,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
    * 引用回复：以「引用某条消息」的样式发出去（官方 `message_reference`）。
    *
    * 跟 `reply()` 不是一回事：
-   *   - `reply()` 是**被动回复**，靠 msg_id，5 分钟内、同一条最多 5 次
+   *   - `reply()` 是**被动回复**，靠 msg_id，群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次
    *   - 这个是**引用**，靠 `REFIDX`，视觉上带"回复某某"的引用块
    *
    * 默认引用当前这条消息（用它的 `msg_idx`）。想引用别的传 `refIdx`。

package/src/outbound.js

@@ -20,15 +20,36 @@ const log = createLogger('outbound');
  * 插件只管调 msg.reply()，剩下的交给这里。
  */
 
-/** 官方给的有效期是 5 分钟，留 15 秒给网络和服务端时钟差 */
-const PASSIVE_WINDOW_MS = 5 * 60 * 1000;
-const PASSIVE_SAFE_MS = PASSIVE_WINDOW_MS - 15_000;
+/**
+ * 被动回复窗口。**两个接口不一样，别再用一个值。**
+ *
+ *   群聊 `/v2/groups/{group_openid}/messages`：5 分钟、最多 5 次
+ *   单聊 `/v2/users/{user_openid}/messages`：**60 分钟、最多 4 次**
+ *
+ * 以前两者共用「5 分钟 / 5 次」（群聊的口径），单聊的后果是：
+ *   · 5 分钟后就降级成主动消息，白吃「每个好友 1000 条/天」的额度，
+ *     而被动回复本来不占主动额度；
+ *   · 第 5 次回复会被服务端拒（40034128）。
+ *
+ * 各留 15 秒给网络和服务端时钟差。
+ */
+const PASSIVE_WINDOW_MS = {
+  group: 5 * 60 * 1000,
+  c2c: 60 * 60 * 1000,
+};
+const PASSIVE_SAFE_MS = {
+  group: PASSIVE_WINDOW_MS.group - 15_000,
+  c2c: PASSIVE_WINDOW_MS.c2c - 15_000,
+};
 
 /**
- * 官方硬限制：同一条消息最多回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端会返回 40034128「被动回复时间或次数超限」。
+ * 同一条消息最多回复次数：群聊 5、单聊 4。
+ * 超过会返回 40034128「被动回复时间或次数超限」。
  */
-const PASSIVE_MAX_REPLIES = 5;
+const PASSIVE_MAX_REPLIES = {
+  group: 5,
+  c2c: 4,
+};
 
 /** 主动消息进入审核的返回码，属于正常结果 */
 const CODE_AUDIT = 304023;
@@ -245,11 +266,12 @@ export class Outbound {
     // 1) 被动窗口检查：快过期就别发请求了，直接按主动消息处理
     if (wantPassive) {
       const age = receivedAt ? Date.now() - receivedAt : 0;
-      if (age > PASSIVE_SAFE_MS) {
+      const safeMs = PASSIVE_SAFE_MS[kind];
+      if (age > safeMs) {
         if (!this.downgrade) {
           this.stats.expired += 1;
           throw new SendError(
-            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 5 分钟被动回复窗口，回复发不出去了`,
+            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 ${Math.round(safeMs / 1000)} 秒被动回复窗口，回复发不出去了`,
             'expired',
           );
         }
@@ -267,17 +289,18 @@ export class Outbound {
     // 2) 排队 + 限速 + 额度扣减 + 实际发送
     //    额度的「查」和「扣」都放在队列里，避免两个并发推送同时通过检查后超额
     return this.#enqueue(chatKey, async () => {
-      // 2a) 被动回复次数上限：官方「每个消息最多回复 5 次」
+      // 2a) 被动回复次数上限：群聊 5 次、单聊 4 次
       //     同一条消息被多个插件连着回、或用户一句话触发多轮时很容易撞上，
       //     本地先拦，省得服务端返回 40034128 再兜底
       let passiveNow = wantPassive && !active;
       if (passiveNow) {
+        const maxReplies = PASSIVE_MAX_REPLIES[kind];
         const used = this.passiveCount.get(body.msgId) ?? 0;
-        if (used >= PASSIVE_MAX_REPLIES) {
+        if (used >= maxReplies) {
           if (!this.downgrade) {
             this.stats.expired += 1;
             throw new SendError(
-              `同一条消息最多回复 ${PASSIVE_MAX_REPLIES} 次（QQ 官方限制），这条已经回满了。\n` +
+              `同一条消息最多回复 ${maxReplies} 次（QQ 官方限制），这条已经回满了。\n` +
                 `等用户再说一句，就能继续用被动回复。`,
               'expired',
             );

package/src/paths.js

@@ -113,6 +113,8 @@ export function botPaths(id) {
     groups: path.join(base, 'groups.json'),
     roles: path.join(base, 'roles.json'),
     quota: path.join(base, 'quota.json'),
+    /** 可达性（好友关系 / 主动推送开关），官方无查询接口，靠事件维护 */
+    reach: path.join(base, 'reach.json'),
     /** 统计库（SQLite，存消息计数与成员活跃，不存正文） */
     stats: path.join(base, 'stats.db'),
     pluginState: path.join(base, 'plugins.json'),

package/src/plugin/context.js

@@ -302,7 +302,7 @@ export class PluginStorage {
 /**
  * 插件上下文：插件能用的全部能力都在这里，不暴露内部实现。
  */
-export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, isOwner, pages = null, routes = null, state = null }) {
+export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, reach, isOwner, pages = null, routes = null, state = null }) {
   const id = meta.id;
   // 日志 tag 带机器人 id，多机器人下同名插件的日志不会串
   const logger = createLogger(`plugin:${paths?.id ?? '-'}:${id}`);
@@ -343,6 +343,13 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
     state: state ?? {},
     api,
     logger,
+    /**
+     * 可达性：`ctx.reach.canC2C(openid)` / `ctx.reach.canGroupPush(groupOpenid)`。
+     *
+     * 返回 `{ verdict: 'yes'|'no'|'unknown', reason? }`。
+     * **`unknown` 不能当 `no` 用**——未知是「不知道」，不是「不行」。
+     */
+    reach,
     storage: new PluginStorage(paths.pluginData(id)),
 
     /**

package/src/plugin/loader.js

@@ -27,7 +27,7 @@ const log = createLogger('plugins');
  * 启用状态存在 data/bots/<机器人id>/plugins.json，删掉文件夹即等于卸载。
  */
 export class PluginManager {
-  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, ignoreCompat }) {
+  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, reach, ignoreCompat }) {
     this.dir = pluginsDir;
     // 该机器人的全套路径（配置/数据/日志），多机器人下互不干扰
     this.paths = paths;
@@ -41,6 +41,8 @@ export class PluginManager {
     this.outbound = outbound;
     this.session = session;
     this.pipeline = pipeline;
+    /** 可达性（能不能私聊/能不能往这个群主动推），见 src/reach.js */
+    this.reach = reach;
     this.isOwner = isOwner;
     /** 跳过插件声明的 frameworkVersion 校验（作者本地调试用） */
     this.ignoreCompat = Boolean(ignoreCompat);
@@ -407,6 +409,7 @@ export class PluginManager {
       outbound: this.outbound,
       session: this.session,
       pipeline: this.pipeline,
+      reach: this.reach,
       isOwner: this.isOwner,
       pages: this.pages,
       routes: this.routes,

package/src/reach.js

@@ -0,0 +1,364 @@
+/**
+ * 可达性：这个人能不能私聊、这个群能不能主动推。
+ * ==============================================
+ *
+ * 为什么需要单独一个模块：官方**没有查好友列表的接口**（sitemap 里 `friend`
+ * 只有两个事件页，没有任何 API）。但官方会把变化**推**过来，所以状态能维护，
+ * 只是「接入之前就已经存在的关系」永远是未知的。
+ *
+ * ── 两层开关，不是一层 ──
+ *
+ * 很多人以为「加了好友就能发私聊」。官方文档里 `C2C_MSG_REJECT` 的原话是：
+ *
+ *   > 用户在机器人资料卡手动关闭「主动消息」推送时触发。
+ *   > **关闭后机器人无法向该用户发送主动消息。**
+ *
+ * 也就是说：**有好友 ≠ 能主动发**。用户可以在资料卡里单独关掉推送。
+ * 所以这里必须分两列存，判定时先看好友、再看推送开关。
+ *
+ * 群聊同理，`GROUP_MSG_REJECT` / `GROUP_MSG_RECEIVE` 是**群的属性**
+ * （事件体只有 `group_openid` + `op_member_openid`，没有目标用户），
+ * 所以群维度单独一张表，不挂在人身上。
+ *
+ * ── 三个值，不是两个 ──
+ *
+ * `1` 已知可以、`0` 已知不可以、`null` 未知。
+ *
+ * **`null` 绝不能当 `0` 用**：群里聊过的人很可能早就加了好友，只是还没私聊过。
+ * 把未知当不可，会让主动搭话永远开不了口；把未知当可，最多发失败一次
+ * ——两害相权，未知应该放行，失败再记下来。
+ *
+ * ── 存 JSON 不存 SQLite ──
+ *
+ * 一个机器人几百个好友，几十 KB，读多写少。框架里已有 `quota.json`
+ * 的先例（`outbound.js` 的 QuotaLedger），同一套「内存缓存 + 延迟落盘」，
+ * 不引迁移、能手改、出问题能直接删。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createLogger } from './logger.js';
+
+const log = createLogger('reach');
+
+/** 落盘延迟。好友变动是低频事件，攒一下再写，避免连续事件写多次盘 */
+const SAVE_DELAY_MS = 500;
+
+/**
+ * 用户档案条数上限。正常部署远远到不了，纯粹防「事件风暴把文件写爆」。
+ * 超了按 `updatedAt` 丢最旧的。
+ */
+const MAX_USERS = 5000;
+
+/** 值归一：只认 1 / 0 / null，别的一律当未知 */
+function tri(v) {
+  if (v === 1 || v === true) return 1;
+  if (v === 0 || v === false) return 0;
+  return null;
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.file  reach.json 的路径（每鸟一份）
+ */
+export function createReach({ file }) {
+  /** @type {{users: Record<string, object>, groups: Record<string, object>}|null} */
+  let data = null;
+  let dirty = false;
+  let timer = null;
+
+  async function load() {
+    if (data) return data;
+    try {
+      const raw = JSON.parse(await fs.readFile(file, 'utf8'));
+      const users = raw?.users && typeof raw.users === 'object' ? raw.users : {};
+      // 手改文件写错类型时不至于让判定崩掉，一律归一成 1 / 0 / null
+      for (const u of Object.values(users)) {
+        if (!u || typeof u !== 'object') continue;
+        u.friend = tri(u.friend);
+        u.c2cPush = tri(u.c2cPush);
+      }
+      const groups = raw?.groups && typeof raw.groups === 'object' ? raw.groups : {};
+      for (const g of Object.values(groups)) {
+        if (!g || typeof g !== 'object') continue;
+        g.push = tri(g.push);
+      }
+      data = { users, groups };
+    } catch {
+      data = { users: {}, groups: {} };
+    }
+    return data;
+  }
+
+  function scheduleSave() {
+    dirty = true;
+    if (timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      flush().catch((e) => log.warn('可达性写盘失败:', e.message));
+    }, SAVE_DELAY_MS);
+    timer.unref?.();
+  }
+
+  async function flush() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (!dirty || !data) return;
+    dirty = false;
+    try {
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, JSON.stringify(data, null, 2), 'utf8');
+    } catch (e) {
+      log.warn('可达性写盘失败:', e.message);
+    }
+  }
+
+  /** 取或建一个用户档案 */
+  function slot(users, openid) {
+    const id = String(openid ?? '').trim();
+    if (!id) return null;
+    users[id] ??= { friend: null, c2cPush: null, unionOpenid: '', evidence: '', updatedAt: 0 };
+    return users[id];
+  }
+
+  /** 超出上限时按 updatedAt 丢最旧的 */
+  function trim(users) {
+    const ids = Object.keys(users);
+    if (ids.length <= MAX_USERS) return;
+    ids
+      .sort((a, b) => (users[a].updatedAt ?? 0) - (users[b].updatedAt ?? 0))
+      .slice(0, ids.length - MAX_USERS)
+      .forEach((id) => delete users[id]);
+  }
+
+  return {
+    /**
+     * `FRIEND_ADD`：用户加了机器人。
+     *
+     * 这是**唯一能拿到 `union_openid` 的地方**（消息事件里也可能有，但经常是空串）。
+     * 顺手存下来，将来跨机器人关联人物时用得上。
+     */
+    async noteFriendAdd({ openid, unionOpenid = '', scene = 0 } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      u.friend = 1;
+      // 空串不覆盖已有的值——消息事件里 union_openid 常常是空的
+      if (unionOpenid) u.unionOpenid = String(unionOpenid);
+      u.evidence = `friend_add:${scene}`;
+      u.updatedAt = Date.now();
+      trim(d.users);
+      scheduleSave();
+      return true;
+    },
+
+    /** `FRIEND_DEL`：用户删了机器人。这时私聊一定发不出去 */
+    async noteFriendDel({ openid } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      u.friend = 0;
+      u.evidence = 'friend_del';
+      u.updatedAt = Date.now();
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * `C2C_MSG_REJECT` / `C2C_MSG_RECEIVE`：用户在资料卡里关/开了主动推送。
+     *
+     * 注意这是**独立于好友关系**的一层：好友还在，但推送被关了，照样发不出去。
+     */
+    async noteC2cPush({ openid, on } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      u.c2cPush = on ? 1 : 0;
+      u.evidence = on ? 'c2c_msg_receive' : 'c2c_msg_reject';
+      u.updatedAt = Date.now();
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * `GROUP_MSG_REJECT` / `GROUP_MSG_RECEIVE`：群管理员关/开了机器人通知。
+     *
+     * 存群维度，不存人——事件体里只有 `group_openid` 和操作人，
+     * 没有「这个开关对谁生效」的概念，它就是对整个群生效。
+     */
+    async noteGroupPush({ groupOpenid, on, by = '' } = {}) {
+      const gid = String(groupOpenid ?? '').trim();
+      if (!gid) return false;
+      const d = await load();
+      d.groups[gid] = {
+        push: on ? 1 : 0,
+        by: String(by ?? ''),
+        evidence: on ? 'group_msg_receive' : 'group_msg_reject',
+        updatedAt: Date.now(),
+      };
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * 收到这个人的单聊消息 —— 最强证据：他能发，说明好友一定在。
+     *
+     * 同时把 `c2cPush` 留空而不是置 1：他主动发消息不代表他允许机器人主动推。
+     */
+    async noteC2cObserved({ openid, unionOpenid = '' } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      u.friend = 1;
+      if (unionOpenid) u.unionOpenid = String(unionOpenid);
+      u.evidence = 'observed_c2c';
+      u.updatedAt = Date.now();
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * 主动发送失败了 —— 按 QQ 业务错误码更新状态。
+     *
+     * 这些码是官方文档里明写的（`/v2/users/{user_openid}/messages` 错误码表），
+     * 所以能**精确判定**，不用再靠人猜：
+     *
+     *   40054004 无好友关系           → is_friend = 0
+     *   40054006 验证好友关系失败      → 不改状态（官方建议「重试」）
+     *   40054013 用户拒收消息          → c2c_push = 0（对应 C2C_MSG_REJECT）
+     *
+     * 其它码（频控 40034100、内容违规 40034006、审核……）**一律不改状态**：
+     * 它们跟「这个人能不能收到」无关，改了就等于一次抖动永久封掉一个人。
+     *
+     * @param {object} p
+     * @param {string} p.openid
+     * @param {number} p.qqCode QQ 业务错误码（不是 HTTP 状态码）
+     */
+    async noteSendError({ openid, qqCode } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      const code = Number(qqCode) || 0;
+      u.lastFailAt = Date.now();
+      u.lastFailCode = code;
+
+      if (code === 40054004) {
+        u.friend = 0;
+        u.evidence = 'send:no-friend';
+      } else if (code === 40054013) {
+        u.c2cPush = 0;
+        u.evidence = 'send:rejected';
+      }
+      // 40054006 只记时间：官方自己都说「请重试」
+      u.updatedAt = Date.now();
+      scheduleSave();
+      return true;
+    },
+
+    /** 主动发送成功了 —— 反证「可达」 */
+    async noteSendOk({ openid } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      u.friend = 1;
+      u.lastOkAt = Date.now();
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * 人工标注 —— 面板上手动纠正状态。
+     *
+     * 为什么必须有这个口子：好友关系的事件是**增量**的，接入之前就存在的关系
+     * 永远拿不到事件，状态会一直停在 `null`。线上真出问题时，运维只能靠
+     * 「手动发一条试试」来试，而失败的证据又常常和网络/限流混在一起分不清。
+     * 与其让人去改 JSON，不如给一个能校验的入口。
+     *
+     * `friend` / `c2cPush` 传 `undefined` 表示「这项不动」，传 `null` 表示「重置为未知」。
+     * 两者语义不同，所以不能用 `??` 或真值判断。
+     *
+     * @param {object} p
+     * @param {string} p.openid
+     * @param {1|0|null} [p.friend]
+     * @param {1|0|null} [p.c2cPush]
+     */
+    async noteManual({ openid, friend, c2cPush } = {}) {
+      const d = await load();
+      const u = slot(d.users, openid);
+      if (!u) return false;
+      if (friend !== undefined) u.friend = tri(friend);
+      if (c2cPush !== undefined) u.c2cPush = tri(c2cPush);
+      u.evidence = 'manual';
+      u.updatedAt = Date.now();
+      trim(d.users);
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * 群维度的人工标注。`push` 传 `undefined` 不动、`null` 重置为未知。
+     *
+     * @param {object} p
+     * @param {string} p.groupOpenid
+     * @param {1|0|null} [p.push]
+     */
+    async noteGroupManual({ groupOpenid, push } = {}) {
+      const gid = String(groupOpenid ?? '').trim();
+      if (!gid) return false;
+      const d = await load();
+      const g = d.groups[gid] ?? { push: null, by: '', evidence: '', updatedAt: 0 };
+      if (push !== undefined) g.push = tri(push);
+      g.evidence = 'manual';
+      g.updatedAt = Date.now();
+      d.groups[gid] = g;
+      scheduleSave();
+      return true;
+    },
+
+    /**
+     * 能不能给这个人发私聊。
+     *
+     * @returns {{verdict:'yes'|'no'|'unknown', reason?:string}}
+     */
+    async canC2C(openid) {
+      const d = await load();
+      const u = d.users[String(openid ?? '').trim()];
+      if (!u) return { verdict: 'unknown' };
+      if (u.friend === 0) return { verdict: 'no', reason: 'reach:not-friend' };
+      if (u.c2cPush === 0) return { verdict: 'no', reason: 'reach:push-off' };
+      if (u.friend === 1) return { verdict: 'yes' };
+      return { verdict: 'unknown' };
+    },
+
+    /**
+     * 能不能往这个群主动推。
+     *
+     * @returns {{verdict:'yes'|'no'|'unknown', reason?:string}}
+     */
+    async canGroupPush(groupOpenid) {
+      const d = await load();
+      const g = d.groups[String(groupOpenid ?? '').trim()];
+      if (!g) return { verdict: 'unknown' };
+      if (g.push === 0) return { verdict: 'no', reason: 'reach:group-push-off' };
+      return { verdict: 'yes' };
+    },
+
+    /** 单个人档案，面板用 */
+    async get(openid) {
+      const d = await load();
+      return d.users[String(openid ?? '').trim()] ?? null;
+    },
+
+    /** 面板用：全量快照（只读副本） */
+    async snapshot() {
+      const d = await load();
+      return { users: { ...d.users }, groups: { ...d.groups } };
+    },
+
+    flush,
+  };
+}
+
+export { tri };

package/src/web/qq-call.js

@@ -29,7 +29,7 @@ const RISK_BY_API = (() => {
 
 /** 官方错误码 → 人话。AI 拿到的是这句，不是一串数字 */
 const ERR_HINTS = {
-  40034128: '被动回复超限（5 分钟窗口，同一条最多 5 次）。等用户再说一句，或改用主动消息',
+  40034128: '被动回复超限（群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次）。等用户再说一句，或改用主动消息',
   40034100: '被官方限流了，稍后再试',
   40034008: '消息内容不合法（markdown 和 content 不能同时给）',
   304023: '消息已进入审核（这不是失败，会正常发出）',

package/src/web/server.js

@@ -2021,6 +2021,103 @@ export async function startWebServer({
           }
         }
 
+        /**
+         * 可达性：谁能私聊、哪个群能主动推。
+         *
+         * 官方**没有查好友的接口**，这些状态全部来自 6 个事件
+         * （FRIEND_ADD/DEL、C2C_MSG_REJECT/RECEIVE、GROUP_MSG_REJECT/RECEIVE）。
+         * 接入之前就存在的关系是 `null`（未知）——**未知不等于不可达**，
+         * 面板要把它显示成「未知」而不是「不能」。
+         */
+        if (pathname === '/api/reach' && (req.method === 'GET' || req.method === 'POST')) {
+          /**
+           * 判定结论在服务端算，前端只负责显示。
+           *
+           * 判定顺序（和 `reach.canC2C` 必须一致，否则面板说的和实际发的会打架）：
+           * 无好友 → 关了推送 → 有好友 → 未知。
+           * **`null` 是「未知」不是「不能」**，单独一个分支。
+           */
+          const snapshot = async () => {
+            const snap = (await rt?.reach?.snapshot?.()) ?? { users: {}, groups: {} };
+            const people = rt?.listRecentPeople?.(200) ?? [];
+            const nameOf = (id) => people.find((p) => p.openid === id)?.name || '';
+
+            const users = Object.entries(snap.users).map(([openid, u]) => ({
+              openid,
+              name: nameOf(openid),
+              friend: u.friend ?? null,
+              c2cPush: u.c2cPush ?? null,
+              unionOpenid: u.unionOpenid || '',
+              evidence: u.evidence || '',
+              updatedAt: u.updatedAt || 0,
+              lastFailAt: u.lastFailAt || 0,
+              lastFailCode: u.lastFailCode || 0,
+              lastOkAt: u.lastOkAt || 0,
+              verdict:
+                u.friend === 0
+                  ? 'not-friend'
+                  : u.c2cPush === 0
+                    ? 'push-off'
+                    : u.friend === 1
+                      ? 'ok'
+                      : 'unknown',
+            }));
+
+            const groups = Object.entries(snap.groups).map(([groupOpenid, g]) => ({
+              groupOpenid,
+              name: rt?.groupName?.(groupOpenid) || '',
+              push: g.push ?? null,
+              by: g.by || '',
+              evidence: g.evidence || '',
+              updatedAt: g.updatedAt || 0,
+              verdict: g.push === 0 ? 'push-off' : g.push === 1 ? 'ok' : 'unknown',
+            }));
+
+            return { users, groups };
+          };
+
+          if (req.method === 'GET') return json(res, 200, await snapshot());
+
+          /**
+           * 人工标注。
+           *
+           * 好友事件是增量的，接入之前的老关系永远是 `unknown`，只能人工纠正。
+           * `friend` / `c2cPush` / `push` 三个字段的约定：
+           *   - 不传     → 这项不动
+           *   - `1`/`0`  → 明确设定
+           *   - `null`   → 重置为未知（**撤销标注用这个**）
+           */
+          if (!rt?.reach?.noteManual) {
+            return json(res, 503, { error: '机器人没在运行，改不了可达性状态' });
+          }
+          const body = await readBody(req);
+          const triOf = (v) => (v === 1 || v === true ? 1 : v === 0 || v === false ? 0 : v === null ? null : undefined);
+
+          const gid = String(body?.groupOpenid ?? '').trim();
+          if (gid) {
+            const push = triOf(body?.push);
+            if (push === undefined && body?.push !== undefined) {
+              return json(res, 400, { error: 'push 只能是 1、0 或 null' });
+            }
+            await rt.reach.noteGroupManual({ groupOpenid: gid, push });
+            return json(res, 200, { ok: true, ...(await snapshot()) });
+          }
+
+          const openid = String(body?.openid ?? '').trim();
+          if (!openid) return json(res, 400, { error: 'openid 或 groupOpenid 不能为空' });
+
+          const friend = triOf(body?.friend);
+          const c2cPush = triOf(body?.c2cPush);
+          if (friend === undefined && body?.friend !== undefined) {
+            return json(res, 400, { error: 'friend 只能是 1、0 或 null' });
+          }
+          if (c2cPush === undefined && body?.c2cPush !== undefined) {
+            return json(res, 400, { error: 'c2cPush 只能是 1、0 或 null' });
+          }
+          await rt.reach.noteManual({ openid, friend, c2cPush });
+          return json(res, 200, { ok: true, ...(await snapshot()) });
+        }
+
         if (pathname === '/api/groups' && req.method === 'GET') {
           const list = await groups.list();
           /**

package/web/app.js

@@ -232,6 +232,7 @@ async function selectBot(id) {
   if (tab === 'config') loadConfig();
   if (tab === 'plugins') loadPlugins();
   if (tab === 'events') loadEvents();
+  if (tab === 'reach') loadReach();
   if (tab === 'groups') loadGroups();
   if (tab === 'roles') { loadRoles(); loadPeople(); }
   if (tab === 'stats') loadStats();
@@ -597,6 +598,7 @@ function activateTab(name) {
   }
   if (name === 'config') loadConfig();
   if (name === 'groups') loadGroups();
+  if (name === 'reach') loadReach();
   if (name === 'roles') { loadRoles(); loadPeople(); }
 }
 
@@ -2911,6 +2913,175 @@ function renderGroups(list) {
   });
 }
 
+/* ---------------- 可达性 ---------------- */
+
+/**
+ * 能不能主动找到人。
+ *
+ * 这块数据的特殊之处：**三个值不是两个**。`1` 可以、`0` 不可以、`null` 未知。
+ *
+ * 面板上必须把「未知」和「不可以」显示得完全不一样。如果两者都是灰色、
+ * 或者都写「否」，用户会以为这些人真的发不出去，然后跑去手动放开——
+ * 而实际情况只是「机器人上线之前就加的好友，事件补不回来」。
+ */
+
+/** 依据的英文 key → 中文。事件里带参数（`friend_add:0`），所以按冒号前匹配 */
+const REACH_EVIDENCE = {
+  friend_add: '加好友事件',
+  friend_del: '删好友事件',
+  c2c_msg_reject: '用户关了推送',
+  c2c_msg_receive: '用户开了推送',
+  observed_c2c: '收到过私聊',
+  group_msg_reject: '群管理员关了推送',
+  group_msg_receive: '群管理员开了推送',
+  'send:no-friend': '发送失败·无好友',
+  'send:rejected': '发送失败·被拒收',
+  manual: '人工标注',
+};
+
+function evidenceText(ev) {
+  const raw = String(ev || '').trim();
+  if (!raw) return '-';
+  return REACH_EVIDENCE[raw.split(':')[0]] ?? raw;
+}
+
+/** 一句话结论。和后端 `reach.canC2C` 的判定顺序必须一致 */
+const REACH_VERDICT = {
+  ok: { text: '能发', cls: 'on' },
+  'not-friend': { text: '不能：没加好友', cls: 'off' },
+  'push-off': { text: '不能：关了推送', cls: 'off' },
+  unknown: { text: '未知，照常尝试', cls: '' },
+};
+
+/**
+ * 行内三态下拉。
+ *
+ * 用下拉而不是「标为好友 / 标为陌生人」两个按钮：后者没法表达「撤销标注」，
+ * 而且改错了只能改到另一个错的值上。`value=""` 就是回到未知。
+ */
+function triSelect(field, v, yes = '是', no = '否') {
+  const sel = (val, text) =>
+    `<option value="${val}"${String(v ?? '') === val ? ' selected' : ''}>${text}</option>`;
+  return `<select class="mini-select" data-field="${field}" title="人工标注">${
+    sel('', '未知') + sel('1', yes) + sel('0', no)
+  }</select>`;
+}
+
+async function loadReach() {
+  const ub = $('#reachUserBody');
+  const gb = $('#reachGroupBody');
+  if (!ub || !gb) return;
+  try {
+    renderReach(await api('/api/reach'));
+  } catch (e) {
+    ub.innerHTML = `<tr><td colspan="6" class="empty">加载失败: ${escapeHtml(e.message)}</td></tr>`;
+    gb.innerHTML = `<tr><td colspan="5" class="empty">加载失败: ${escapeHtml(e.message)}</td></tr>`;
+  }
+}
+
+function renderReach(d) {
+  const ub = $('#reachUserBody');
+  const gb = $('#reachGroupBody');
+  if (!ub || !gb) return;
+
+  const users = d?.users ?? [];
+  const groups = d?.groups ?? [];
+
+  ub.innerHTML = users.length
+    ? users
+        .map((u) => {
+          const v = REACH_VERDICT[u.verdict] ?? REACH_VERDICT.unknown;
+          const extra = u.lastFailCode ? ` · 失败码 ${u.lastFailCode}` : '';
+          return `<tr data-openid="${escapeHtml(u.openid)}">
+            <td title="${escapeHtml(u.openid)}">${labelWithId(u.name, u.openid)}</td>
+            <td>${triSelect('friend', u.friend)}</td>
+            <td>${triSelect('c2cPush', u.c2cPush)}</td>
+            <td><span class="badge ${v.cls}">${v.text}</span></td>
+            <td title="${escapeHtml(u.evidence || '')}">${escapeHtml(evidenceText(u.evidence))}${escapeHtml(extra)}</td>
+            <td>${u.updatedAt ? fmtAgo(u.updatedAt) : '-'}</td>
+          </tr>`;
+        })
+        .join('')
+    : '<tr><td colspan="6" class="empty">还没有记录。收到私聊消息、或被加好友之后才会出现。</td></tr>';
+
+  gb.innerHTML = groups.length
+    ? groups
+        .map(
+          (g) => `<tr data-group="${escapeHtml(g.groupOpenid)}">
+            <td title="${escapeHtml(g.groupOpenid)}">${labelWithId(g.name, g.groupOpenid)}</td>
+            <td>${triSelect('push', g.push, '开', '关')}</td>
+            <td title="${escapeHtml(g.by || '')}">${g.by ? labelWithId('', g.by) : '-'}</td>
+            <td title="${escapeHtml(g.evidence || '')}">${escapeHtml(evidenceText(g.evidence))}</td>
+            <td>${g.updatedAt ? fmtAgo(g.updatedAt) : '-'}</td>
+          </tr>`,
+        )
+        .join('')
+    : '<tr><td colspan="5" class="empty">还没有记录。群管理员改过推送开关之后才会出现。</td></tr>';
+}
+
+/**
+ * 行内标注：改下拉即提交。
+ *
+ * 委托绑在 tbody 上，因为 `renderReach` 每次都整个重建 innerHTML，
+ * 逐行 `addEventListener` 会随着重绘丢掉。
+ */
+async function saveReachPatch(sel, body) {
+  sel.disabled = true;
+  try {
+    renderReach(await api('/api/reach', { method: 'POST', body: JSON.stringify(body) }));
+  } catch (e) {
+    alert('标注失败: ' + e.message);
+    sel.disabled = false;
+  }
+}
+
+$('#reachUserBody')?.addEventListener('change', (e) => {
+  const sel = e.target.closest('select[data-field]');
+  if (!sel) return;
+  const openid = sel.closest('tr')?.dataset.openid;
+  if (!openid) return;
+  // 空字符串 = 撤销标注，要显式传 null，不能传 ''（后端会当成非法值）
+  saveReachPatch(sel, { openid, [sel.dataset.field]: sel.value === '' ? null : Number(sel.value) });
+});
+
+$('#reachGroupBody')?.addEventListener('change', (e) => {
+  const sel = e.target.closest('select[data-field]');
+  if (!sel) return;
+  const groupOpenid = sel.closest('tr')?.dataset.group;
+  if (!groupOpenid) return;
+  saveReachPatch(sel, {
+    groupOpenid,
+    push: sel.value === '' ? null : Number(sel.value),
+  });
+});
+
+$('#btnReloadReach')?.addEventListener('click', loadReach);
+
+/** 列表里没有的人（比如老好友、从没私聊过）手动登记一条 */
+$('#btnReachSave')?.addEventListener('click', async () => {
+  const openid = $('#reachOpenidInput')?.value.trim() ?? '';
+  if (!openid) return alert('先填 openid');
+  const friend = $('#reachFriendSel')?.value ?? '';
+  const c2cPush = $('#reachPushSel')?.value ?? '';
+  if (friend === '' && c2cPush === '') return alert('好友和推送至少选一个，不然登记了也是未知');
+
+  const btn = $('#btnReachSave');
+  btn.disabled = true;
+  try {
+    const body = { openid };
+    if (friend !== '') body.friend = Number(friend);
+    if (c2cPush !== '') body.c2cPush = Number(c2cPush);
+    renderReach(await api('/api/reach', { method: 'POST', body: JSON.stringify(body) }));
+    $('#reachOpenidInput').value = '';
+    $('#reachFriendSel').value = '';
+    $('#reachPushSel').value = '';
+  } catch (e) {
+    alert('登记失败: ' + e.message);
+  } finally {
+    btn.disabled = false;
+  }
+});
+
 /**
  * 分群插件开关。
  *

package/web/index.html

@@ -56,6 +56,7 @@
       <div class="tab-menu" hidden>
         <button class="tab-item" data-tab="stats">统计</button>
         <button class="tab-item" data-tab="events">事件</button>
+        <button class="tab-item" data-tab="reach">可达性</button>
         <button class="tab-item" data-tab="logs">日志</button>
       </div>
     </div>
@@ -494,6 +495,93 @@
     </div>
   </section>
 
+  <!-- 可达性 -->
+  <section id="tab-reach" class="panel">
+    <div class="box">
+      <div class="box-hd">
+        <h3>能不能主动找到人</h3>
+        <span class="hint">两道门：先得是好友，还得开着主动推送</span>
+      </div>
+      <ul class="tips">
+        <li><b>好友</b>是用户把机器人加为好友；<b>主动推送</b>是用户在机器人资料卡里单独开的开关——
+          <b>有好友也可能被关掉</b>，关了就发不出去</li>
+        <li>官方<b>没有查询好友的接口</b>，这里的值全部来自事件推送。机器人启动之前就存在的老关系拿不到事件，
+          会一直是「未知」</li>
+        <li><b>未知不等于不可达</b>——未知会照常尝试发送，失败了才记下来。把未知当成「不能」，
+          所有老用户就都被静音了</li>
+      </ul>
+    </div>
+
+    <div class="box">
+      <div class="box-hd">
+        <h3>单聊</h3>
+        <div class="btn-row" style="margin:0">
+          <button class="btn small" id="btnReloadReach">刷新</button>
+        </div>
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th>用户</th>
+              <th>好友</th>
+              <th>主动推送</th>
+              <th>结论</th>
+              <th>依据</th>
+              <th>更新</th>
+            </tr>
+          </thead>
+          <tbody id="reachUserBody">
+            <tr><td colspan="6" class="empty">还没有记录。收到私聊消息、或被加好友之后才会出现。</td></tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="hint" style="margin-top:8px">
+        每行的两个下拉框就是<b>人工标注</b>，改完立刻生效并覆盖事件推断的值；选「未知」等于撤销标注。
+      </div>
+      <div class="form-inline" style="margin-top:12px">
+        <input id="reachOpenidInput" placeholder="openid（列表里没有的人可以直接登记）">
+        <select id="reachFriendSel" class="mini-select">
+          <option value="">好友：未知</option>
+          <option value="1">好友：是</option>
+          <option value="0">好友：否</option>
+        </select>
+        <select id="reachPushSel" class="mini-select">
+          <option value="">推送：未知</option>
+          <option value="1">推送：开</option>
+          <option value="0">推送：关</option>
+        </select>
+        <button class="btn primary" id="btnReachSave">登记</button>
+      </div>
+    </div>
+
+    <div class="box">
+      <div class="box-hd">
+        <h3>群主动推送</h3>
+        <span class="hint">群管理员可以整个群关掉机器人的主动消息</span>
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th>群</th>
+              <th>主动推送</th>
+              <th>操作人</th>
+              <th>依据</th>
+              <th>更新</th>
+            </tr>
+          </thead>
+          <tbody id="reachGroupBody">
+            <tr><td colspan="5" class="empty">还没有记录。群管理员改过推送开关之后才会出现。</td></tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="hint" style="margin-top:8px">
+        没记录过的群按「未知」处理，照常尝试推送。
+      </div>
+    </div>
+  </section>
+
   <!-- 群组 -->
   <section id="tab-groups" class="panel">
     <div class="box">