qq-bot-roost 0.9.10 → 1.0.0

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-679%20passed-brightgreen" alt="测试 679 项">
+<img src="https://img.shields.io/badge/tests-737%20passed-brightgreen" alt="测试 737 项">
 <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.9.10-blueviolet" alt="版本 0.9.10">
+<img src="https://img.shields.io/badge/version-1.0.0-blueviolet" alt="版本 1.0.0">
 <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>
 
@@ -71,6 +71,14 @@
 - **素材缓存**：同一个图片 url 两天内只上传一次，省富媒体频控和流量
 - **中间件管道**：去重、白名单、限流、命令冷却都可插拔
 
+**身份与记忆**（v1.0.0）
+
+- **QQ号 / 群号 ↔ openid 绑定**：换机器人（换 AppID）之后 openid 会变，而记忆是按 openid 存的。绑定之后，读记忆会把同一个号码名下的所有键一起读——**存量数据一个字节不动**
+- **面板「身份」页**：绑定、追加、改绑、停用；未识别的人也能看到
+- **群内指令（0 / 1 级）**：`/绑定群号 <群号>`、`/绑定成员 @某人 <QQ号>`。只绑当前群和当前群里被 @ 的人，冲突不强制改绑
+- **消息带四个字段**：`uin` / `groupUin` / `userAliases` / `groupAliases`。插件用 `ctx.identity` 只读视图查，绑定表由框架维护
+- 配套升级：`dsh-roost` 1.0.0（别名合并读取 + 账号迁移页）、`ai-chat` 4.4.1（透传字段）。**三个一起升**，少一个号码就传不到 DSH
+
 **连接与容错**
 
 - **两种收事件方式**：WebSocket 长连接（本地默认）或 **Webhook 回调**（公网 / Serverless / 容器）
@@ -302,6 +310,8 @@ node src/main.js --mock --serve
 | `/enable` `/disable` `/reload [id]` | 插件管理（需全局管理员） |
 | `/群插件` | 看 / 改**这个群**能用哪些插件（群管理；面板「群组 → 插件」也能改） |
 | `/whoami` | 查自己的 openid / 群 openid |
+| `/绑定群号 <群号>` | 把**当前群**绑到群号（仅 0 / 1 级；冲突不强制改绑） |
+| `/绑定成员 @某人 <QQ号>` | 把**当前群里被 @ 的人**绑到 QQ号（仅 0 / 1 级） |
 | `/claim <认领码>` | 认领主人身份（`owners` 为空时可用） |
 | `/ping` | 连通性测试 |
 
@@ -368,6 +378,7 @@ export default {
 | `ctx.storage.get/set/all` | 插件私有存档 |
 | `ctx.config` / `ctx.setConfig()` | 插件配置读写 |
 | `ctx.can` / `ctx.levelOf` / `ctx.scopeOf` | 权限判断 |
+| `ctx.identity` | **只读**身份视图：`openidOf(uin)` / `uinOf(openid)` / `aliasesOf(uin)` / `groupOf(openid)`。绑定表由框架维护，插件不能写 |
 | `ctx.registerTool(工具)` | 注册一个 AI 可调用的工具（跨插件，0.8.6+），返回注销函数 |
 | `ctx.tools()` / `ctx.callTool(名, 参数)` | 列出 / 调用别插件注册的工具 |
 | `msg.reply` / `push` / `replyMarkdown` / `replyImage` / … | 各种发送方式 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.9.10",
+  "version": "1.0.0",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,9 +29,9 @@
     "start": "node src/main.js",
     "mock": "node src/main.js --mock",
     "check": "node src/main.js --check",
-    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs",
+    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node test/e2e.mjs && node test/live-driver.mjs",
+    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node --test test/identity.mjs && node --test test/identity-commands.mjs && node test/e2e.mjs && node test/live-driver.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",

package/src/api.js

@@ -284,14 +284,22 @@ export class QQApi {
     const body = { file_type: fileType, srv_send_msg: false };
     if (url) body.url = url;
     if (fileData) body.file_data = fileData;
+    /**
+     * `file_name` **不只分片合并要**。
+     *
+     * 官方字段说明：「文件名（分片上传或者二进制上传时必填）」。
+     * 以前只在 `upload_id` 那条路带上，于是小文件走 base64 直传时是**无名文件**——
+     * QQ 客户端拿不到名字，显示出来就没有扩展名（`报告` 而不是 `报告.docx`），
+     * 对方还得自己猜怎么打开。2026-11-02 线上真踩过。
+     *
+     * URL 上传不用带：那种路径平台自己下载转存，名字从 URL 里取。
+     */
+    if (fileName) body.file_name = fileName;
     /**
      * 分片合并：`upload_id` 一进，服务端就走「合并已上传分片」那条路，
-     * `url` 可以为空。但 `file_name` 这条路径**必填**（官方字段说明）。
+     * `url` 可以为空。
      */
-    if (uploadId) {
-      body.upload_id = uploadId;
-      if (fileName) body.file_name = fileName;
-    }
+    if (uploadId) body.upload_id = uploadId;
     const r = await this.#request('POST', path, body);
 
     if (cacheKey && r?.file_info) {
@@ -348,6 +356,11 @@ export class QQApi {
     const up = await this.uploadMedia(scene, target, {
       fileType,
       fileData: buf.toString('base64'),
+      /**
+       * 二进制直传**必须带文件名**（官方字段说明：分片上传或二进制上传时必填）。
+       * 少了它 QQ 侧就是个无名文件，客户端连扩展名都显示不出来。
+       */
+      fileName: filePath.split(/[\\/]/).pop() || 'file',
       reuse: false,
     });
     if (cacheKey && up?.file_info) {
@@ -967,7 +980,21 @@ export class QQApi {
       content_raw: String(p.contentRaw ?? ''),
     };
     if (p.streamMsgId) payload.stream_msg_id = p.streamMsgId;
-    if (p.msgId) payload.msg_id = p.msgId;
+    if (p.msgId) {
+      payload.msg_id = p.msgId;
+      /**
+       * `msg_seq` 必须显式给，而且**所有分片用同一个值**。
+       *
+       * 流式消息是「一条消息在长」，不是多条——官方示例里首片、续片、结束片
+       * 都是同一个 `msg_seq`。不传的话服务端按 1 处理，而我们自己的普通回复
+       * 也从 1 开始递增，于是「先流式、再发图/文件」会撞
+       * `40054005 消息被去重`。
+       *
+       * 取值由调用方先算好传进来（`replyStream` 会在首片前调 `takeSeq`）。
+       */
+      if (p.msgSeq != null) payload.msg_seq = Number(p.msgSeq);
+      else payload.msg_seq = this.#nextSeq(p.msgId);
+    }
     if (p.eventId) payload.event_id = p.eventId;
     if (p.isWakeup) payload.is_wakeup = true;
     return this.#request('POST', `/v2/users/${enc(openid)}/stream_messages`, payload);
@@ -1198,6 +1225,18 @@ export class QQApi {
 
   /* ---------------- 内部 ---------------- */
 
+  /**
+   * 先占一个 `msg_seq`，供流式消息这种「一条消息发好几次」的场景用。
+   *
+   * 为什么要有：流式接口不走 `#payload`，所以以前完全不占序号——首片按默认 1 算，
+   * 而我们自己后续的普通回复也从 1 开始递增，两边撞上就是
+   * `40054005 消息被去重`（用户那边表现为「发了但没出现」）。
+   * 流式所有分片共用这一个值（一条消息一个序号）。
+   */
+  takeSeq(msgId) {
+    return this.#nextSeq(msgId);
+  }
+
   #payload(opts) {
     return buildSendPayload(opts, (id) => this.#nextSeq(id));
   }

package/src/bot.js

@@ -20,6 +20,7 @@ import { createReach } from './reach.js';
 import { createLedger } from './ledger.js';
 import { createGate } from './gate.js';
 import { createDeliveryLedger } from './delivery.js';
+import { sharedIdentity } from './identity.js';
 
 /**
  * 一个机器人的完整运行时。
@@ -68,6 +69,14 @@ export class BotRuntime {
     this.gateway = null;
     this.registry = new Registry();
     this.groups = new GroupStore(this.paths.groups);
+    /**
+     * 身份对照表（QQ号 / 群号 ↔ openid）。
+     *
+     * **进程级单例、不按机器人拆**——它的全部意义就是横跨机器人。
+     * 在这里建而不是在 `init()` 里：`buildMessage()` 要用它，
+     * 不能依赖「init 已经跑过」。真正的读盘在 `init()` 里 `await load()`。
+     */
+    this.identity = sharedIdentity();
 
     /**
      * 最近说过话的人：openid -> { openid, name, chatId, scope, at }
@@ -166,13 +175,21 @@ export class BotRuntime {
       });
     }
 
+    /**
+     * 身份表要在**插件加载和收消息之前**读好。
+     *
+     * 晚一步的话，启动后第一批消息就没有 `uin`，AI 会把老朋友当陌生人；
+     * 插件 setup 里想用 `ctx.identity` 也会查到空。
+     * 载入失败不拦启动——`load()` 内部已经把坏文件降级成空表并留了档。
+     */
+    await this.identity.load().catch((e) => this.log.warn(`身份表载入失败：${e.message}`));
+
     if (this.mock) {
       this.api = this.makeMockApi ? this.makeMockApi(this) : null;
     } else {
       this.tokens = new TokenManager(cfg);
       this.api = new QQApi({ tokenManager: this.tokens, baseUrl: cfg.baseUrl, metrics: this.metrics });
     }
-
     this.outbound = new Outbound({
       api: this.api,
       cfg,
@@ -233,6 +250,8 @@ export class BotRuntime {
       reach: this.reach,
       ledger: this.ledger,
       gate: this.gate,
+      /** 身份对照表：插件通过 ctx.identity 只读查询（QQ号 → openid） */
+      identity: this.identity,
       isOwner: (uid) => cfg.owners.includes(uid),
       // 插件声明了 frameworkVersion 就做兼容校验；作者本地调试可以关掉
       ignoreCompat: this.globalCfg.plugins?.ignoreFrameworkVersion === true,
@@ -770,7 +789,7 @@ export class BotRuntime {
     }
 
     /* ---- 消息事件 ---- */
-    const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session });
+    const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session, identity: this.identity });
 
     /**
      * 群名不在官方事件里（只有 `group_openid`），但框架有缓存。

package/src/identity-commands.js

@@ -0,0 +1,99 @@
+/**
+ * 群里的绑定指令（内核命令的实现）。
+ *
+ * ## 为什么单独一个文件
+ *
+ * `main.js` 里的命令 handler 拿不到可测的上下文（registry / roles / cfg / 真消息），
+ * 逻辑写在里面只能靠端到端测。这里只做「消息 → 结果文本」的纯逻辑，
+ * 权限由调用方算好传进来（`allowed`），身份表通过参数注入。
+ *
+ * ## 三条硬规矩
+ *
+ * 1. **只绑当前群、以及当前群里被 @ 的人。** 不接受任何「把别的群的 openid
+ *    绑过来」的参数——群里发一句话就能改别人身份的入口，范围必须收到最小。
+ * 2. **不做 force。** 冲突就停，让用户去面板确认。群里一句话把别人的身份
+ *    改掉，代价比多点两下鼠标高得多。
+ * 3. **永远返回文本，不抛。** 聊天命令抛异常等于用户什么都收不到，
+ *    而发指令的人只会以为「机器人没反应」。
+ */
+
+import { isValidUin } from './identity.js';
+
+/** 参数里可能混着 `<@openid>` 这样的 token，取**最后一个**合法号码 */
+export function parseTargetUin(args = []) {
+  const list = Array.isArray(args) ? args : [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const v = String(list[i] ?? '').trim();
+    if (isValidUin(v)) return v;
+  }
+  return '';
+}
+
+/** 被 @ 的人里第一个不是机器人的 */
+export function pickMember(mentions = []) {
+  for (const m of Array.isArray(mentions) ? mentions : []) {
+    if (!m || m.isBot) continue;
+    const id = String(m.id ?? '').trim();
+    if (id) return { id, name: String(m.name || '') };
+  }
+  return null;
+}
+
+const NEED_ADMIN = '只有主人和管理员（0 / 1 级）能改绑定。';
+const ONLY_GROUP = '这个指令只能在群里用。';
+
+function bindErrorText(e) {
+  if (e?.code === 'CONFLICT') {
+    return `${e.message}。要改绑请去 Roost 面板 →「身份」页，群里不做强制改绑。`;
+  }
+  if (e?.code === 'INVALID') return `绑定失败：${e.message}`;
+  return `绑定失败：${e?.message || e}`;
+}
+
+/**
+ * `绑定群号 <群号>`：把**当前群**的 openid 绑到群号。
+ */
+export async function runBindGroup({ msg, identity, botId = '', allowed = false, log = () => {} } = {}) {
+  if (msg?.kind !== 'group') return { ok: false, text: ONLY_GROUP };
+  if (!allowed) return { ok: false, text: NEED_ADMIN };
+
+  const uin = parseTargetUin(msg.args);
+  if (!uin) return { ok: false, text: '用法：绑定群号 763366431（5–12 位数字，首位不能是 0）' };
+
+  /** 群聊时 `chatId` 就是群的 openid；只认这一个来源 */
+  const openid = String(msg.chatId || '').trim();
+  if (!openid) return { ok: false, text: '拿不到本群的 openid，让群里有人先说句话再试。' };
+
+  try {
+    await identity.bind({ kind: 'group', uin, openid, botId });
+  } catch (e) {
+    return { ok: false, text: bindErrorText(e) };
+  }
+  log(`绑定指令：${msg.userId} 在 ${openid} 把本群绑到群号 ${uin}`);
+  return {
+    ok: true,
+    text: `已把本群绑到群号 ${uin}。以后换机器人，新群的 openid 也要绑到同一个群号。`,
+  };
+}
+
+/**
+ * `绑定成员 @某人 <QQ号>`：把**当前群里被 @ 的那个人**绑到 QQ号。
+ */
+export async function runBindUser({ msg, identity, botId = '', allowed = false, log = () => {} } = {}) {
+  if (msg?.kind !== 'group') return { ok: false, text: ONLY_GROUP };
+  if (!allowed) return { ok: false, text: NEED_ADMIN };
+
+  const member = pickMember(msg.mentions);
+  if (!member) return { ok: false, text: '用法：绑定成员 @某人 10001（先 @ 要绑的人，再写 QQ号）' };
+
+  const uin = parseTargetUin(msg.args);
+  if (!uin) return { ok: false, text: '缺 QQ号。用法：绑定成员 @某人 10001' };
+
+  try {
+    await identity.bind({ kind: 'user', uin, openid: member.id, botId });
+  } catch (e) {
+    return { ok: false, text: bindErrorText(e) };
+  }
+  log(`绑定指令：${msg.userId} 在 ${msg.chatId} 把 ${member.id} 绑到 QQ号 ${uin}`);
+  return { ok: true, text: `已把 ${member.name ? `@${member.name} ` : '这个人'}绑到 QQ号 ${uin}。` };
+}