@zaofan/dsh-qqbot 1.6.1 → 1.6.2

package/docs/USER-GUIDE.md

@@ -130,6 +130,48 @@ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 - **`target_group`(v1.2.0)**: **分组管理** —— list/create/rename/delete/add/remove, 读写的正是 dock「📇 群组管理 → 🗂 分组」那份数据 → **AI 与主人共用同一份分组**: 主人在面板分好组, AI 直接"发给群友"就能群发。
 - **`group_join_auto`(v1.3.0)**: **按关键词自动审批入群申请** —— 命中任一关键词的**直接放行**、未命中的**直接拒绝**(不可逆, 可 `dry_run` 预览); 源数据是**官方待审列表**(非本地流水), 同一人重复申请**去重按最新一条判**; 仅在主人明确要求时使用。
 
+**🔨 锤子面板: 禁言 / 踢人 (v1.6.2+)**
+
+dock 里的「🔨 锤子」（原「🔇 禁言」）下面分两页：**🔇 禁言**（走官方接口，机器人为管理员即可）和 **👢 踢人**（官方**没开放**踢人接口，改走**你自己的 QQ 号** + 群官网 `qun.qq.com`）。
+
+**怎么用（踢人）**:
+
+1. 面板 → 🔨 锤子 → 👢 踢人 → 点「📱 刷新二维码」；
+2. 页面里直接出二维码 —— 手机 QQ「扫一扫」，**摄像头对着电脑屏幕**扫
+   （腾讯只认摄像头：相册选图 / 长按识别会提示「本次请求不支持图片识别或长按扫描二维码授权」）；
+3. 扫完自动切到已登录页：**选群 + 搜成员（uin 精确 / 昵称模糊）+ 点 👢 踢**（点前有确认框）。
+
+![🔨 锤子 · 踢人面板](screenshots/hammer-kick-panel.png)
+
+**免扫码是怎么做到的**: 登录成功后的凭据存 `{dataRoot}/qun-cookie.json`。此后每次需要登录时，插件会：
+`静默起无头浏览器 → 用 CDP 把已存凭据注入进去 → 页面直接就是已登录 → 读出凭据 → 关掉浏览器`，
+**全程不弹窗口、不用扫码**。只有**第一次**（或 `skey` 约 1 天过期后彻底失效）才要扫一次，重登同样走这套静默流程。
+💡 本机开着 **QQ 客户端**时，登录页会直接给出你的头像，点一下就登 —— 连第一次都不用扫。
+
+**登录态与 AI 共享**: 面板和 AI 读写的是**同一份** `qun-cookie.json` —— 面板登过 AI 立刻能用；AI 登过面板打开即已登录。
+
+**AI 侧工具 `qq_group_admin`**（v1.6.2+）:
+
+| action | 作用 |
+|---|---|
+| `status` | 查登录状态 / 继续等扫码 |
+| `login` | 登录（静默优先；需要扫码时给出二维码文件的本地路径） |
+| `groups` | 列出你创建 / 管理的群 |
+| `members` | 查成员（`keyword` 给 uin = 服务端精确查；给昵称 = 全量拉取后本地过滤） |
+| `kick` | 踢人（`uins` 逗号分隔；**必须带 `confirmed=true`**，否则只回「请先跟主人核对群和人」） |
+
+**HTTP 端点**（面板走这些，也可自行调用；前缀 `/api/qqbot-settings`）:
+`GET /qun/status`、`POST /qun/login`、`GET /qun/poll`、`GET /qun/members?gc=&q=`、`POST /qun/kick`、`POST /qun/logout`、`GET /qun-qr`（直接返回二维码 PNG）。
+
+**进程与隐私**: 浏览器用**独立 profile**（放在插件数据目录里，**看不到你日常浏览器的任何东西**）；**不常驻** —— 拿到凭据立刻关、等扫码最多留 5 分钟、宿主退出时一起带走（不留孤儿进程）。若启动撞上 `profile 被占用`（code=21），会先杀掉占用该 profile 的残留进程 + 清锁，再重试一次。
+
+**踩过的坑（供维护者参考）**:
+
+- 踢人 `delete_group_member` 的成员参数是 **`ul`**（不是 `uin` —— 传 `uin` 返回 `ec:5`），且要放 **POST body**；返回 `ec:0` 成功 / `ec:3` 人不在群里 / `-100005` 群不存在或没权限。
+- 成员分页 `st/end` 是**闭区间**（`st=0&end=20` 回 21 条），必须按**实际返回条数**步进，否则每页重叠 1 条、去重后总数偏少（683 人的群只拉回 661）。
+- 宿主进程 spawn 出来的**浏览器窗口到不了用户桌面**（`headless=False` 也一样，进程查不到可见窗口），所以"弹窗口让用户扫"这条路不通 —— 二维码只能走**本地文件路径 / 网页端点**。
+- 浏览器 profile 里的 **session cookie 不会持久化**，所以凭据的唯一真相源是 `qun-cookie.json`，每次启动靠 CDP 注入恢复登录态。
+
 **配置项**(Web 面板 ⑥ 可改, 见下表 `groupAdmin.*`)
 
 ## 🧠 智能回复（本地小模型 · 可选，省 token）(v1.4.5+)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaofan/dsh-qqbot",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "QQ Bot IM channel plugin for deepseek-harness (dsh)",
   "type": "module",
   "main": "./entry.js",

package/settings-host.js

@@ -410,6 +410,173 @@ export function apply(ctx) {
     return mod;
   }
 
+  // ── QQ 群管理登录二维码 → 直接送到 dsh web 界面 ──
+  //   为什么需要它（2026-10-02）：AI 登录 qun.qq.com 时用的是**无头**浏览器（没有窗口），
+  //   二维码只能"发图"给主人；而主人在手机上收到图后**扫不了自己的屏幕**
+  //   （腾讯只认摄像头对着另一块屏幕扫："不支持图片识别或长按扫描二维码授权"）。
+  //   把二维码挂到 dsh web 上，主人就能在**自己电脑的浏览器**里打开、用手机对着屏幕扫。
+  //   用法：http://127.0.0.1:<dsh端口>/api/qqbot-settings/qun-qr
+  route(ctx, 'GET', '/api/qqbot-settings/qun-qr', async (_req, res) => {
+    try {
+      const cands = [];
+      const dr = resolveContextlessDataRoot();
+      if (dr) cands.push(join(dr, 'qun-login-qr.png'));
+      // 兜底：插件写二维码用的 dataRoot 可能与桥推出来的不一致（实测出现过两个数据根）
+      try {
+        const parsed = parsePatch();
+        for (const b of ((parsed && parsed.bots) || [])) {
+          const c = (b && b.cfg && (b.cfg.dataRoot || b.cfg.cwd)) || '';
+          if (c) cands.push(join(String(c), 'dshqqbot', 'qun-login-qr.png'));
+        }
+      } catch { /* ignore */ }
+      let hit = '';
+      for (const c of cands) {
+        try { if (c && existsSync(c)) { hit = c; break; } } catch { /* ignore */ }
+      }
+      if (!hit) {
+        return writeJson(res, 404, { ok: false, error: '还没有二维码（先让 AI 调 qq_group_admin 的 action=login）', tried: cands });
+      }
+      const buf = readFileSync(hit);
+      res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'no-store, must-revalidate' });
+      res.end(buf);
+    } catch (e) {
+      writeJson(res, 500, { ok: false, error: String((e && e.message) || e) });
+    }
+  });
+
+  // ── 🔨 锤子 · 踢人面板（2026-10-02 主人定）──
+  //   登录态与 AI **完全共享**：两边读写同一个 {dataRoot}/qun-cookie.json，
+  //   所以「面板登录完 AI 立刻能用 / AI 登录完面板立刻已登录」，不需要任何同步逻辑。
+  async function qunAdminMod() { return import('./dist/features/qun-admin.js'); }
+  async function qunLoginMod() { return import('./dist/features/qun-login.js'); }
+  /** 踢人面板统一取数据根（与插件/工具同源） */
+  function qunRoot() { return resolveContextlessDataRoot() || ''; }
+  function qunErrHuman(m) {
+    return m.indexOf('NOT_LOGGED_IN') >= 0 ? '还没登录（先刷新二维码扫码）' : m;
+  }
+
+  /** 登录状态（顺手拿群列表验证凭据是否还有效） */
+  route(ctx, 'GET', '/api/qqbot-settings/qun/status', async (_req, res) => {
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 200, { ok: true, logged: false, hint: '推不出数据根' });
+      const mod = await qunAdminMod();
+      const c = mod.loadQunCookie(dr);
+      if (!c) return writeJson(res, 200, { ok: true, logged: false });
+      let valid = true;
+      let groups = [];
+      try { groups = await mod.qunGroups(dr); } catch { valid = false; }
+      writeJson(res, 200, {
+        ok: true, logged: true, valid, uin: c.uin,
+        groups: (groups || []).map((g) => ({ gc: g.gc, gn: g.gn, role: g.role })),
+      });
+    } catch (e) { writeJson(res, 500, { ok: false, error: String((e && e.message) || e) }); }
+  });
+
+  /** 触发/刷新登录：静默无头先试（有凭据或有本机 QQ 头像就免扫码），需要扫码就写出二维码文件 */
+  route(ctx, 'POST', '/api/qqbot-settings/qun/login', async (_req, res) => {
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 400, { ok: false, error: '推不出数据根' });
+      const admin = await qunAdminMod();
+      let qr = false;
+      let msg = '';
+      try {
+        const lg = await qunLoginMod();
+        const r = await lg.qunBrowserLoginStart(dr, { headless: true });
+        msg = r.msg || '';
+        if (r.cookie) {
+          admin.saveQunCookie(dr, { ...r.cookie, at: Date.now() });
+          return writeJson(res, 200, { ok: true, logged: true, uin: r.cookie.uin, msg });
+        }
+        qr = !!r.qrPath;
+      } catch (e) { msg = String((e && e.message) || e); }
+      if (!qr) {
+        // 浏览器这条路不通 → 退回纯网络二维码（写的是同一个文件路径）
+        try {
+          const s = await admin.qunLoginStart(dr);
+          qr = !!(s && s.ok && s.qrPath);
+          if (s && s.msg) msg = (msg ? msg + ' / ' : '') + s.msg;
+        } catch { /* ignore */ }
+      }
+      writeJson(res, 200, { ok: true, logged: false, needScan: qr, msg });
+    } catch (e) { writeJson(res, 500, { ok: false, error: String((e && e.message) || e) }); }
+  });
+
+  /** 轮询扫码结果（顺带把挂着的登录会话推进一次） */
+  route(ctx, 'GET', '/api/qqbot-settings/qun/poll', async (_req, res) => {
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 200, { ok: true, logged: false });
+      const admin = await qunAdminMod();
+      try {
+        const lg = await qunLoginMod();
+        if (lg.qunLoginSessionAlive(dr)) {
+          const w = await lg.qunBrowserLoginWait(dr, 2500);
+          if (w.cookie) {
+            admin.saveQunCookie(dr, { ...w.cookie, at: Date.now() });
+            return writeJson(res, 200, { ok: true, logged: true, uin: w.cookie.uin });
+          }
+        }
+      } catch { /* ignore */ }
+      try {
+        if (admin.qunLoginPending(dr)) {
+          const p = await admin.qunLoginPoll(dr, 2500);
+          if (p.done) return writeJson(res, 200, { ok: true, logged: true });
+        }
+      } catch { /* ignore */ }
+      const c = admin.loadQunCookie(dr);
+      writeJson(res, 200, { ok: true, logged: !!(c && c.skey), uin: c ? c.uin : '' });
+    } catch (e) { writeJson(res, 500, { ok: false, error: String((e && e.message) || e) }); }
+  });
+
+  /** 成员搜索：?gc=群号&q=uin或昵称（q 可空 = 全量） */
+  route(ctx, 'GET', '/api/qqbot-settings/qun/members', async (req, res) => {
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 400, { ok: false, error: '推不出数据根' });
+      const u = new URL(req.url ?? '/', 'http://x');
+      const gc = String(u.searchParams.get('gc') || '').trim();
+      const q = String(u.searchParams.get('q') || '').trim();
+      if (!gc) return writeJson(res, 400, { ok: false, error: 'gc 必填' });
+      const mod = await qunAdminMod();
+      const r = await mod.qunMembers(dr, gc, q || undefined);
+      writeJson(res, 200, { ok: true, count: r.count, note: r.note, members: (r.members || []).slice(0, 300) });
+    } catch (e) { writeJson(res, 200, { ok: false, error: qunErrHuman(String((e && e.message) || e)) }); }
+  });
+
+  /** 踢人 {gc, uins:[...]} */
+  route(ctx, 'POST', '/api/qqbot-settings/qun/kick', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { ok: false, error: 'bad body' });
+    const gc = String(body.gc || '').trim();
+    const list = (Array.isArray(body.uins) ? body.uins : []).map((x) => String(x).trim()).filter(Boolean);
+    if (!gc || !list.length) return writeJson(res, 400, { ok: false, error: 'gc / uins 必填' });
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 400, { ok: false, error: '推不出数据根' });
+      const mod = await qunAdminMod();
+      const rs = await mod.qunKick(dr, gc, list.slice(0, 20));
+      const okCount = rs.filter((x) => x.ec === 0).length;
+      writeJson(res, 200, { ok: okCount > 0, results: rs, msg: '成功 ' + okCount + '/' + rs.length });
+    } catch (e) { writeJson(res, 200, { ok: false, error: qunErrHuman(String((e && e.message) || e)) }); }
+  });
+
+  /** 退出登录（清掉本地凭据，下次要重新扫码） */
+  route(ctx, 'POST', '/api/qqbot-settings/qun/logout', async (_req, res) => {
+    try {
+      const dr = qunRoot();
+      if (!dr) return writeJson(res, 400, { ok: false, error: '推不出数据根' });
+      const mod = await qunAdminMod();
+      mod.clearQunCookie(dr);
+      try {
+        const lg = await qunLoginMod();
+        lg.qunLoginSessionClose(dr);
+      } catch { /* ignore */ }
+      writeJson(res, 200, { ok: true, msg: '已退出登录' });
+    } catch (e) { writeJson(res, 500, { ok: false, error: String((e && e.message) || e) }); }
+  });
+
   // ── 无上下文模式（2026-09-27 主人定）──
   //   会话级开关：dock 面板里对**某个会话**开启；开启后该会话每轮只带
   //   「@ 之前 N 条群消息 + 系统规则」，历史对话全部丢弃（大幅省 token）。