qq-bot-roost 0.8.3 → 0.8.6

package/src/qq/qrlogin.js

@@ -0,0 +1,151 @@
+/**
+ * 扫码一键创建 QQ 官方机器人。
+ *
+ * 官方开放平台提供了一套「绑定」接口，扫一下手机 QQ 就能拿到 AppID / AppSecret，
+ * 不用去 q.qq.com 手动建机器人、再手动复制两个值。
+ *
+ * 三个接口（都是 POST，JSON）：
+ *
+ *   1. /lite/create_bind_task   { key }        → { data: { task_id } }
+ *      key 是我们自己生成的 base64(32 字节随机数)，后面用它解密 secret
+ *
+ *   2. 二维码内容不是图片，是一个 URL，前端自己画成二维码：
+ *      https://q.qq.com/qqbot/openclaw/connect.html?task_id=<id>&_wv=2
+ *
+ *   3. /lite/poll_bind_result   { task_id }    → { data: { status, bot_appid, bot_encrypt_secret } }
+ *      status: 0 无 / 1 待扫码 / 2 完成 / 3 过期
+ *
+ * 完成时 `bot_encrypt_secret` 是 AES-256-GCM 密文：
+ *   base64 解开 = nonce(12) + ciphertext + tag(16)，key 就是第 1 步的 bindKey。
+ *
+ * 为什么不用第三方库：`node:crypto` 自带 aes-256-gcm，零依赖。
+ *
+ * 参考实现：AstrBot 的 `qqofficial/login_registration.py`（协议一致，值得致敬）。
+ */
+
+import { randomBytes, createDecipheriv } from 'node:crypto';
+
+/** 绑定接口的域名。留个常量，方便以后换成测试环境 */
+const BIND_HOST = 'q.qq.com';
+const TIMEOUT_MS = 10_000;
+
+/** 轮询状态码 */
+export const BIND_STATUS = {
+  NONE: 0,
+  PENDING: 1,
+  DONE: 2,
+  EXPIRED: 3,
+};
+
+async function postJson(url, payload) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(payload),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      throw new Error(`绑定接口返回的不是 JSON（HTTP ${res.status}）：${text.slice(0, 120)}`);
+    }
+    if (!res.ok) throw new Error(`绑定接口失败（HTTP ${res.status}）：${data?.msg ?? text.slice(0, 120)}`);
+    if (data && data.retcode != null && Number(data.retcode) !== 0) {
+      throw new Error(data.msg || data.message || `绑定接口返回 retcode=${data.retcode}`);
+    }
+    return data ?? {};
+  } catch (e) {
+    if (e?.name === 'AbortError') throw new Error('连不上 q.qq.com（超时 10 秒），检查网络或代理');
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 二维码里要放的内容 */
+export function connectUrl(taskId) {
+  return `https://${BIND_HOST}/qqbot/openclaw/connect.html?task_id=${encodeURIComponent(taskId)}&_wv=2`;
+}
+
+/**
+ * 建一个绑定任务。
+ *
+ * @returns {Promise<{taskId:string, bindKey:string, qrUrl:string}>}
+ */
+export async function createBindTask() {
+  // 32 字节随机数当 AES-256 的 key，base64 后发给官方
+  const bindKey = randomBytes(32).toString('base64');
+  const data = await postJson(`https://${BIND_HOST}/lite/create_bind_task`, { key: bindKey });
+  const taskId = String(data?.data?.task_id ?? '').trim();
+  if (!taskId) throw new Error('绑定任务没返回 task_id，可能是接口变了');
+  return { taskId, bindKey, qrUrl: connectUrl(taskId) };
+}
+
+/**
+ * 解 AppSecret。
+ *
+ * 密文格式：base64( nonce[12] + ciphertext + tag[16] )
+ * 少了任何一段都会解不开——所以长度不够就直接报错，别硬解。
+ */
+export function decryptSecret(encrypted, bindKey) {
+  let key;
+  let raw;
+  try {
+    key = Buffer.from(bindKey, 'base64');
+    raw = Buffer.from(String(encrypted), 'base64');
+  } catch {
+    throw new Error('凭证解码失败（bindKey 或密文不是合法 base64）');
+  }
+  if (key.length !== 32) throw new Error(`bindKey 长度不对（要 32 字节，实际 ${key.length}）`);
+  if (raw.length <= 28) throw new Error(`密文太短（${raw.length} 字节，至少要 29）`);
+
+  const nonce = raw.subarray(0, 12);
+  const tag = raw.subarray(raw.length - 16);
+  const ciphertext = raw.subarray(12, raw.length - 16);
+
+  const d = createDecipheriv('aes-256-gcm', key, nonce);
+  d.setAuthTag(tag);
+  try {
+    return Buffer.concat([d.update(ciphertext), d.final()]).toString('utf8');
+  } catch {
+    throw new Error('AppSecret 解不开（密钥不匹配或数据被改动）');
+  }
+}
+
+/**
+ * 查一次扫码结果。
+ *
+ * @returns {Promise<{status:'pending'|'done'|'expired'|'error', appId?:string, appSecret?:string, message?:string}>}
+ */
+export async function pollBindResult({ taskId, bindKey }) {
+  if (!taskId) throw new Error('缺 task_id');
+  if (!bindKey) throw new Error('缺 bind_key');
+
+  const data = await postJson(`https://${BIND_HOST}/lite/poll_bind_result`, { task_id: taskId });
+  const p = data?.data ?? {};
+  const status = Number(p.status ?? BIND_STATUS.NONE);
+
+  if (status === BIND_STATUS.DONE) {
+    const appId = String(p.bot_appid ?? '').trim();
+    const encrypted = String(p.bot_encrypt_secret ?? '').trim();
+    if (!appId || !encrypted) {
+      return { status: 'error', message: '扫码成功了，但官方没返回完整凭证（缺 appid 或 secret）' };
+    }
+    try {
+      return { status: 'done', appId, appSecret: decryptSecret(encrypted, bindKey) };
+    } catch (e) {
+      return { status: 'error', message: e.message };
+    }
+  }
+
+  if (status === BIND_STATUS.EXPIRED) {
+    return { status: 'expired', message: '二维码过期了，重新生成一个' };
+  }
+
+  return { status: 'pending' };
+}

package/src/qq/qrsvg.js

@@ -0,0 +1,39 @@
+/**
+ * 把一段文字画成二维码（SVG 字符串）。
+ *
+ * 为什么**服务端画**：DSH 的插件前端只有一个 client.js 入口，
+ * 再往里塞一个 QR 库既占体积又要改加载方式。服务端画好直接给 `<svg>` 字符串，
+ * 前端一句 innerHTML 就完事。
+ *
+ * 库是 `qrcode-generator` 1.4.4（MIT，Kazuhiko Arase），放在 web/vendor/。
+ * 它是 UMD：本仓是 ESM（package.json "type": "module"），直接 import 拿不到，
+ * 所以在 vm 里当浏览器脚本跑一遍，取全局 `qrcode`——不需要任何依赖。
+ */
+
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+let qrcode = null;
+
+function lib() {
+  if (qrcode) return qrcode;
+  const src = readFileSync(new URL('../../web/vendor/qrcode.js', import.meta.url), 'utf8');
+  const sandbox = {};
+  vm.createContext(sandbox);
+  vm.runInContext(src, sandbox);
+  if (typeof sandbox.qrcode !== 'function') throw new Error('QR 库没加载上（vendor/qrcode.js 坏了？）');
+  qrcode = sandbox.qrcode;
+  return qrcode;
+}
+
+/**
+ * @param {string} text 要编码的内容
+ * @param {{cellSize?:number, margin?:number}} [opt]
+ * @returns {string} 完整 `<svg>…</svg>`
+ */
+export function toSvg(text, { cellSize = 4, margin = 6 } = {}) {
+  const qr = lib()(0, 'M'); // 0 = 自动选版本，M = 中等纠错
+  qr.addData(String(text));
+  qr.make();
+  return qr.createSvgTag({ cellSize, margin });
+}

package/src/web/server.js

@@ -30,6 +30,8 @@ import { suspendPluginWatch } from '../services/plugin-watch.js';
 import { onMessage as onBusMessage } from '../message-bus.js';
 import { handleQqCall, capabilityPayload } from './qq-call.js';
 import { runDoctor, summarize } from '../doctor.js';
+import { createBindTask, pollBindResult } from '../qq/qrlogin.js';
+import { toSvg as qrToSvg } from '../qq/qrsvg.js';
 import {
   PRESETS,
   PROBE_URL,
@@ -96,6 +98,9 @@ async function readBody(req, limit = 1024 * 256) {
  *
  * @returns {Promise<number>} 实际监听成功的端口
  */
+/** 扫码建机器人的临时任务表：taskId → { bindKey, at } */
+const qrTasks = new Map();
+
 function listenWithFallback(server, host, startPort, { tries = 20, onBusy } = {}) {
   return new Promise((resolve, reject) => {
     let attempt = 0;
@@ -704,6 +709,46 @@ export async function startWebServer({
           return json(res, 200, { bots: list, current: rt?.id ?? null });
         }
 
+        /**
+         * 扫码建机器人：两步（建任务 / 轮询）。
+         *
+         * bindKey 是解 AppSecret 的密钥，**只在服务端留着**，
+         * 下发出去等于把密钥给了浏览器，没必要。
+         * 任务 10 分钟后自动清掉，免得 Map 无限涨。
+         */
+        if (pathname === '/api/bots/qr/start' && req.method === 'POST') {
+          for (const [k, v] of qrTasks) {
+            if (Date.now() - v.at > 10 * 60_000) qrTasks.delete(k);
+          }
+          try {
+            const t = await createBindTask();
+            qrTasks.set(t.taskId, { bindKey: t.bindKey, at: Date.now() });
+            // qrSvg 给不装 QR 库的调用方（比如 dsh-roost 面板）直接用
+            let qrSvg = '';
+            try {
+              qrSvg = qrToSvg(t.qrUrl);
+            } catch {}
+            return json(res, 200, { taskId: t.taskId, qrUrl: t.qrUrl, qrSvg });
+          } catch (e) {
+            return json(res, 502, { error: e.message });
+          }
+        }
+
+        if (pathname === '/api/bots/qr/poll' && req.method === 'POST') {
+          const body = await readBody(req);
+          const taskId = String(body.taskId ?? '').trim();
+          const rec = qrTasks.get(taskId);
+          if (!rec) return json(res, 400, { error: '这个二维码已经失效了，重新生成一个' });
+          try {
+            const r = await pollBindResult({ taskId, bindKey: rec.bindKey });
+            // 有结论就把任务删掉，别让它一直轮询
+            if (r.status !== 'pending') qrTasks.delete(taskId);
+            return json(res, 200, r);
+          } catch (e) {
+            return json(res, 502, { error: e.message });
+          }
+        }
+
         if (pathname === '/api/bots' && req.method === 'POST') {
           if (!onBotAdd) return json(res, 501, { error: '当前模式不支持新建机器人' });
           const body = await readBody(req);

package/src/webhook.js

@@ -234,7 +234,27 @@ export class WebhookServer {
     });
 
     if (isInteraction) {
-      // 我们的 putInteraction 是插件主动调的，这里先给 0 兜底
+      /**
+       * 按钮点击要**两层**确认，少一层客户端就一直转圈：
+       *   1. HTTP ACK `{op:12, code:0}` —— 告诉平台「我收到了」
+       *   2. `PUT /interactions/{id}` —— 告诉客户端「这次点击处理完了」
+       *
+       * 以前只做了第 1 层（下面那行注释以为 putInteraction 插件会自己调，
+       * 实际上没人调），所以按钮点下去会一直转。
+       *
+       * **只有 type 11（消息按钮）和 12（快捷菜单）需要回执**，
+       * 其他类型（消息反馈 13、清空会话 14、切模型 16、授权 18/19）官方明确不用回。
+       * 所以这里按 type 收紧——乱回可能被判非法，而且同一 id 只能回一次。
+       */
+      const t = Number(d?.type ?? d?.data?.type ?? 0);
+      if (t === 11 || t === 12) {
+        try {
+          const r = bot.api?.putInteraction?.(d?.id, 0);
+          if (r && typeof r.catch === 'function') r.catch(() => {});
+        } catch {
+          /* 回执失败不影响主流程 */
+        }
+      }
       return this.#json(res, 200, { op: 12, code: 0 });
     }
   }

package/web/app.js

@@ -273,6 +273,94 @@ async function deleteBot(id) {
   if (CURRENT_BOT) await selectBot(CURRENT_BOT);
 }
 
+/* ---------------- 扫码一键创建 ---------------- */
+
+/**
+ * 官方有「绑定」接口，手机 QQ 扫一下就能拿到 AppID / AppSecret，
+ * 不用去 q.qq.com 手动建机器人、再手动复制两个值。
+ *
+ * 二维码内容是官方给的一个 URL，我们本地画成二维码（web/vendor/qrcode.js）。
+ * 密钥（bindKey）留在服务端，前端只拿到 taskId。
+ */
+let qrTaskId = '';
+let qrTimer = null;
+
+function stopQrPoll() {
+  if (qrTimer) {
+    clearInterval(qrTimer);
+    qrTimer = null;
+  }
+}
+
+function resetQr() {
+  stopQrPoll();
+  qrTaskId = '';
+  const box = $('#nbQr');
+  if (box) box.hidden = true;
+  const code = $('#nbQrCode');
+  if (code) code.innerHTML = '';
+  const tip = $('#nbQrTip');
+  if (tip) tip.textContent = '';
+}
+
+function drawQr(url) {
+  const code = $('#nbQrCode');
+  if (!code || typeof qrcode !== 'function') return false;
+  const qr = qrcode(0, 'M'); // 0 = 自动选版本
+  qr.addData(url);
+  qr.make();
+  code.innerHTML = qr.createSvgTag({ cellSize: 4, margin: 6 });
+  return true;
+}
+
+async function startQr() {
+  const btn = $('#nbQrStart');
+  const box = $('#nbQr');
+  const tip = $('#nbQrTip');
+  box.hidden = false;
+  tip.textContent = '正在生成二维码…';
+  btn.disabled = true;
+  try {
+    const r = await api('/api/bots/qr/start', { method: 'POST', body: '{}' });
+    qrTaskId = r.taskId;
+    if (!drawQr(r.qrUrl)) {
+      tip.textContent = '二维码库没加载上，刷新页面再试一次';
+      return;
+    }
+    tip.textContent = '用手机 QQ 扫码，确认后会自动填好 AppID / AppSecret';
+    stopQrPoll();
+    qrTimer = setInterval(pollQr, 2000);
+  } catch (e) {
+    tip.textContent = e.message;
+  } finally {
+    btn.disabled = false;
+  }
+}
+
+async function pollQr() {
+  if (!qrTaskId) return stopQrPoll();
+  const tip = $('#nbQrTip');
+  try {
+    const r = await api('/api/bots/qr/poll', {
+      method: 'POST',
+      body: JSON.stringify({ taskId: qrTaskId }),
+    });
+    if (r.status === 'pending') return;
+    stopQrPoll();
+    if (r.status === 'done') {
+      $('#nbAppId').value = r.appId || '';
+      $('#nbSecret').value = r.appSecret || '';
+      tip.textContent = `✓ 已拿到 AppID ${r.appId}，填个 ID 就能创建`;
+      $('#nbId').focus();
+    } else {
+      tip.textContent = r.message || '二维码失效了，重新生成一个';
+    }
+  } catch (e) {
+    stopQrPoll();
+    if (tip) tip.textContent = e.message;
+  }
+}
+
 /* ---------------- 新建机器人 ---------------- */
 
 function openNewBot() {
@@ -282,11 +370,13 @@ function openNewBot() {
   $('#nbAppId').value = '';
   $('#nbSecret').value = '';
   $('#nbErr').hidden = true;
+  resetQr();
   $('#newBotMask').hidden = false;
   $('#nbId').focus();
 }
 
 function closeNewBot() {
+  resetQr();
   $('#newBotMask').hidden = true;
 }
 
@@ -326,6 +416,8 @@ async function submitNewBot() {
   }
 }
 
+$('#nbQrStart')?.addEventListener('click', startQr);
+
 $('#botTrigger')?.addEventListener('click', () => {
   if ($('#botMenu').hidden) openBotMenu();
   else closeBotMenu();