qq-bot-roost 0.8.13 → 0.9.0

package/src/web/server.js

@@ -24,6 +24,7 @@ import {
 } from '../updater.js';
 // 面板改插件启停时要同步机器人配置里的过滤器，两边不能各说各的
 import { pluginFilterOf, pluginAllowedIn } from '../bot.js';
+import { userFacingSendError } from '../outbound.js';
 import { runRoute } from '../plugin/routes.js';
 import { toggleGroupPlugin } from '../plugin/groupscope.js';
 import { suspendPluginWatch } from '../services/plugin-watch.js';
@@ -561,6 +562,13 @@ export async function startWebServer({
      * 页面令牌和会话都已作废，需要立刻重载插件页而不是等下轮轮询。
      */
     snap.instanceId = `${process.pid}-${PROCESS_STARTED_AT}`;
+    /**
+     * 闸状态。
+     *
+     * 放进每 2 秒推一次的 status 里，是为了面板能**立刻**画出「已暂停」横幅——
+     * 暂停是个紧急操作，等用户点进某个页签才发现「原来还暂停着」就太晚了。
+     */
+    snap.gate = rt?.gate?.peek?.() ?? null;
     return snap;
   };
 
@@ -2021,6 +2029,138 @@ 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()) });
+        }
+
+        /**
+         * 事件账本：官方没有历史消息接口，这是唯一能翻到「刚才说了什么」的地方。
+         *
+         * 三条路由：
+         *   GET /api/ledger/stats              总量、时间范围、保留天数
+         *   GET /api/ledger?chatId=&limit=     某会话最近 N 条（正序）
+         *   GET /api/ledger/context?chatId=&seq=  以某条为锚点的前后邻文
+         *
+         * `payload`（原始报文）**一律不返回**：里面虽然有脱敏过的凭证，
+         * 但整包给前端没有意义（前端只要正文和元信息），只会把面板变成数据外泄面。
+         */
+        if (pathname === '/api/ledger/stats' && req.method === 'GET') {
+          const st = rt?.ledger?.stats?.() ?? { available: false, total: 0 };
+          return json(res, 200, st);
+        }
+
+        if (pathname === '/api/ledger/context' && req.method === 'GET') {
+          const chatId = String(url.searchParams.get('chatId') ?? '').trim();
+          const seq = Number(url.searchParams.get('seq') ?? 0);
+          if (!chatId || !seq) return json(res, 400, { error: '需要 chatId 和 seq' });
+          const before = Number(url.searchParams.get('before') ?? 2);
+          const after = Number(url.searchParams.get('after') ?? 2);
+          const list = rt?.ledger?.timeline?.({ chatId, anchorSeq: seq, before, after }) ?? [];
+          return json(res, 200, { items: list, empty: list.length === 0 });
+        }
+
+        if (pathname === '/api/ledger' && req.method === 'GET') {
+          const chatId = String(url.searchParams.get('chatId') ?? '').trim();
+          if (!chatId) return json(res, 400, { error: '需要 chatId' });
+          const limit = Number(url.searchParams.get('limit') ?? 50);
+          const beforeSeq = Number(url.searchParams.get('beforeSeq') ?? 0) || undefined;
+          const items = rt?.ledger?.recent?.({ chatId, limit, beforeSeq }) ?? [];
+          return json(res, 200, { items });
+        }
+
         if (pathname === '/api/groups' && req.method === 'GET') {
           const list = await groups.list();
           /**
@@ -2204,6 +2344,95 @@ export async function startWebServer({
           return json(res, 200, { ok: true, level: getLevel() });
         }
 
+        /* ---------------- 暂停闸 ---------------- */
+
+        /**
+         * 闸的读与写。
+         *
+         * `GET /api/gate?chatId=` 一次给全：全局闸、每只鸟的闸、每个会话的闸，
+         * 以及（给了 chatId 时）这只鸟现在能不能对它说话、为什么不能。
+         *
+         * 一次给全是有意的：面板要同时显示「全局暂停着」和「这只鸟也暂停着」，
+         * 分两个接口查就会出现「一个说能、一个说不能」的错位。
+         */
+        if (pathname === '/api/gate' && req.method === 'GET') {
+          const chatId = url.searchParams.get('chatId') || '';
+          /**
+           * `kind` 决定要不要查可达性：私聊查好友关系 + 主动推送开关，
+           * 群聊查群管理员的推送开关。**不传就不查**——不知道是群还是私聊
+           * 就查不了，而「不知道」不该变成「不能」。
+           */
+          const kind = url.searchParams.get('kind') || '';
+          const bots = [];
+          for (const r of runtimes) {
+            const snap = await r.gate?.snapshot?.().catch(() => null);
+            bots.push({
+              id: r.id,
+              name: r.name,
+              state: r.state,
+              paused: Boolean(snap?.bot?.paused),
+              pausedAt: snap?.bot?.at ?? 0,
+              pausedBy: snap?.bot?.by ?? '',
+              reason: snap?.bot?.reason ?? '',
+              chats: snap?.chats ?? [],
+              silence: snap?.silence ?? [],
+              canSpeak: chatId ? await r.canSpeak(chatId, { kind }).catch(() => null) : null,
+            });
+          }
+          const first = await rt.gate?.snapshot?.().catch(() => null);
+          return json(res, 200, {
+            ok: true,
+            global: first?.global ?? { paused: false, at: 0, by: '', reason: '' },
+            bots,
+          });
+        }
+
+        if (pathname === '/api/gate' && req.method === 'POST') {
+          const body = await readBody(req);
+          const scope = String(body.scope ?? 'bot');
+          const paused = Boolean(body.paused);
+          const reason = String(body.reason ?? '').slice(0, 200);
+          const meta = { by: 'panel', reason };
+
+          if (scope === 'global') {
+            if (!rt.gate) return json(res, 501, { error: '当前环境不支持暂停闸' });
+            await rt.gate.setGlobal(paused, meta);
+            /**
+             * 每只鸟各有一个 gate 实例、各缓存一份全局闸。写完必须让
+             * 其他实例重读——否则「全局暂停」要等重启才对其他鸟生效。
+             */
+            for (const r of runtimes) {
+              if (r !== rt) await r.gate?.reloadGlobal?.().catch(() => {});
+            }
+            return json(res, 200, { ok: true, scope, paused });
+          }
+
+          const target = body.botId ? runtimes.find((r) => r.id === body.botId) : rt;
+          if (!target) return json(res, 404, { error: `没有这只鸟：${body.botId}` });
+          if (!target.gate) return json(res, 501, { error: '当前环境不支持暂停闸' });
+
+          if (scope === 'bot') {
+            await target.gate.setBot(paused, meta);
+            return json(res, 200, { ok: true, scope, botId: target.id, paused });
+          }
+
+          const chatId = String(body.chatId ?? '');
+          if (!chatId) return json(res, 400, { error: `scope=${scope} 需要 chatId` });
+
+          if (scope === 'chat') {
+            await target.gate.setChat(chatId, paused, meta);
+            return json(res, 200, { ok: true, scope, botId: target.id, chatId, paused });
+          }
+
+          if (scope === 'silence') {
+            const minutes = Math.max(0, Number(body.minutes) || 0);
+            const r2 = await target.gate.setSilence(chatId, minutes * 60_000, meta);
+            return json(res, 200, { ok: true, scope, botId: target.id, chatId, until: r2.until });
+          }
+
+          return json(res, 400, { error: `不认识的 scope：${scope}（global / bot / chat / silence）` });
+        }
+
         // 网关操作
         if (pathname === '/api/gateway/reconnect' && req.method === 'POST') {
           // 已经下线时没有「重连」可言，直接当上线处理，免得点了没反应
@@ -2223,12 +2452,45 @@ export async function startWebServer({
         }
 
         // 主动发消息（调试用）
+        /**
+         * 面板手动发消息（调试用）。
+         *
+         * **必须走 outbound**。这条以前直连 `api.sendGroup` / `api.sendC2C`，
+         * 绕过了每秒限速、主动消息额度记账（20/分 + 1000/天）和离线判断。
+         * 面板随手点几下就能把额度打满，而额度账本里一条记录都没有——
+         * **半真的账本比没有账本更糟**，因为你会相信它。
+         *
+         * 错误按 SendError 的 code 分开回：`quota` 用 429（等一会儿能好），
+         * 其余用 400（重试也不会好，比如离线、被动窗口已过）。
+         */
         if (pathname === '/api/send' && req.method === 'POST') {
           const body = await readBody(req);
           const { scene, target, content } = body;
           if (!target || !content) return json(res, 400, { error: '需要 target 和 content' });
-          const sender = scene === 'c2c' ? api?.sendC2C : api?.sendGroup;
+          const kind = scene === 'c2c' ? 'c2c' : 'group';
+          const sender = kind === 'c2c' ? api?.sendC2C : api?.sendGroup;
           if (!sender) return json(res, 503, { error: '未连接' });
+
+          if (rt.outbound) {
+            try {
+              const r = await rt.outbound.send({
+                kind,
+                target,
+                chatKey: `${kind}:${target}`,
+                payload: { content },
+              });
+              // pending = 主动消息进了审核。既不是失败，也不是「已经送达」
+              return json(res, 200, { ok: true, id: r?.id ?? '', pending: Boolean(r?.pending) });
+            } catch (e) {
+              const hint = userFacingSendError(e);
+              if (!hint) throw e; // 真正的接口错误交给外层兜底（500 + 原始信息）
+              // quota（等跨天）和 rate（等一分钟）都是「等会儿能好」，用 429 让调用方知道可以重试
+              const retriable = e.code === 'quota' || e.code === 'rate';
+              return json(res, retriable ? 429 : 400, { error: hint, code: e.code });
+            }
+          }
+
+          // 只有自造 Bot 实例（没建调度器）才会走到这里，直发兜底
           const r = await sender.call(api, target, { content });
           return json(res, 200, { ok: true, id: r?.id });
         }

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(); }
 }
 
@@ -690,6 +692,7 @@ function renderStatus(s) {
     (s.counters.dedup ?? 0) +
     (s.counters.limited ?? 0) +
     (s.counters.rejected ?? 0) +
+    (s.counters.gated ?? 0) +
     (s.counters.ignored ?? 0);
   $('#c-err').textContent = `${s.counters.errors} / ${blocked}`;
 
@@ -711,6 +714,14 @@ function renderStatus(s) {
   // 框架版本：status 里直接带，不用等用户点「检查更新」
   if (s.version) $('#updCurrent').textContent = s.version;
 
+  /**
+   * 闸状态跟着每 2 秒的 status 一起刷。
+   *
+   * 不单独开一个轮询接口：暂停是紧急操作，如果面板要等用户点进某一页
+   * 才去查，「原来还暂停着」就会拖很久才被发现。
+   */
+  renderGate(s.gate);
+
   const body = $('#chatBody');
   if (!s.chats?.length) {
     body.innerHTML = '<tr><td colspan="4" class="empty">暂无数据</td></tr>';
@@ -934,6 +945,70 @@ $('#btnRefreshCred').addEventListener('click', async (e) => {
   finally { e.target.disabled = false; }
 });
 
+/* ---------------- 暂停闸 ---------------- */
+
+/** 最近一次拿到的闸状态。按钮要靠它判断「现在点下去是开还是关」 */
+let LAST_GATE = null;
+
+/**
+ * 画闸状态。
+ *
+ * 按钮文案跟着状态走（「暂停」/「放开」），而不是固定文案 + 一个指示灯——
+ * 指示灯那种设计，用户点之前得先抬头看灯，点错了还要再点一次。
+ */
+function renderGate(gate) {
+  LAST_GATE = gate ?? null;
+  const el = $('#gateState');
+  const bg = $('#btnGateGlobal');
+  const bb = $('#btnGateBot');
+  if (!el || !bg || !bb) return;
+
+  const g = gate?.global ?? {};
+  const b = gate?.bot ?? {};
+
+  bg.textContent = g.paused ? '放开全局' : '全局暂停';
+  bg.classList.toggle('primary', Boolean(g.paused));
+  bb.textContent = b.paused ? '放开这只鸟' : '暂停这只鸟';
+  bb.classList.toggle('primary', Boolean(b.paused));
+
+  const why = [];
+  if (g.paused) why.push(`全局已暂停${g.reason ? `（${g.reason}）` : ''}`);
+  if (b.paused) why.push(`这只鸟已暂停${b.reason ? `（${b.reason}）` : ''}`);
+
+  if (why.length) {
+    el.innerHTML = `<b style="color:var(--warn-text)">${escapeHtml(why.join(' · '))}</b>`;
+    el.title = '暂停期间消息照样进账本，恢复后能补看';
+  } else {
+    el.textContent = '运行中';
+    el.title = '';
+  }
+}
+
+async function setGate(scope, paused) {
+  try {
+    await api('/api/gate', { method: 'POST', body: JSON.stringify({ scope, paused }) });
+    /**
+     * 本地先翻转，不等下一次 status 推送。
+     * status 是 2 秒一轮，点完等两秒才变，用户会以为没点上、再点一次，
+     * 结果又翻回去了——这种「点了没反应」最容易被当成 bug。
+     */
+    if (LAST_GATE) {
+      const k = scope === 'global' ? 'global' : 'bot';
+      renderGate({ ...LAST_GATE, [k]: { ...(LAST_GATE[k] ?? {}), paused } });
+    }
+  } catch (e) {
+    alert(`操作失败: ${e.message}`);
+  }
+}
+
+$('#btnGateGlobal')?.addEventListener('click', () => {
+  setGate('global', !LAST_GATE?.global?.paused);
+});
+
+$('#btnGateBot')?.addEventListener('click', () => {
+  setGate('bot', !LAST_GATE?.bot?.paused);
+});
+
 $('#btnSend').addEventListener('click', async (e) => {
   const scene = $('#sendScene').value;
   const target = $('#sendTarget').value.trim();
@@ -2911,6 +2986,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;
+  }
+});
+
 /**
  * 分群插件开关。
  *