qq-bot-roost 0.9.7 → 0.9.8

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-700%2B%20passed-brightgreen" alt="测试 700+ 项">
+<img src="https://img.shields.io/badge/tests-679%20passed-brightgreen" alt="测试 679 项">
 <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.7-blueviolet" alt="版本 0.9.7">
+<img src="https://img.shields.io/badge/version-0.9.8-blueviolet" alt="版本 0.9.8">
 <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>
 
@@ -23,8 +23,8 @@
 用 Node.js 从零实现 QQ 开放平台 v2 协议，**不依赖任何第三方包**——装个 Node 22 就能跑，
 不需要 `npm install`，**装插件和更新框架也不需要 git**（下载 GitHub 的 tar 包自己解，不调外部命令）。
 
-官方接口比第三方协议严格得多：被动回复只有 5 分钟且同一条最多回 5 次、同一会话每秒最多 5 条、
-主动消息单会话 20 条/分钟且每群每天 1000 条。
+官方接口比第三方协议严格得多：群聊被动回复 5 分钟、同一条最多回 5 次（单聊 60 分钟 / 4 次）、
+发送接口 100 QPS、主动消息单会话 20 条/分钟且每群每天 1000 条。
 这些限制框架已经统一兜住，写插件时不用算时间、不用管额度，调 `msg.reply()` 就行。
 
 插件有两种形态，互不影响：
@@ -62,7 +62,7 @@
 
 **官方接口这一层**
 
-- **限制全兜底**：出站调度器统一处理 5 分钟窗口、每秒 5 条限速、主动消息每日额度、断线拒发、审核中识别——插件只管调 `msg.reply()`
+- **限制全兜底**：出站调度器统一处理被动窗口（群 5 分钟 / 单聊 60 分钟）、会话内限速、主动消息每日额度、断线拒发、审核中识别——插件只管调 `msg.reply()`
 - **`msg_seq` 自动维护**：同一 `msg_id` 被动回复必须递增，这是官方硬要求，漏一次就发不出去
 - **免@粘性**：@ 过一次后 N 分钟内该会话免@ 也算在跟机器人说话
 - **多轮对话**：`ctx.prompt()` 问一句等回答，文字游戏的地基
@@ -124,6 +124,7 @@
 - 5 种作用域 × 数字等级（0 主人 / 1 管理员 / 2 群管 / 3 助手 / 10+ 插件区）
 - 一个人在不同群、不同插件里可以有完全不同的权限，互不干扰
 - 只能授予数字更大的等级，不能给自己或同级提权
+- **权限管的是「谁能让机器人做什么」，不是「插件代码能做什么」。** 内建插件跑在主进程、外部插件跑在子进程，两者都拥有和你相同的文件与网络权限。装来路不明的插件，等于让它的作者以你的身份运行代码。
 
 **群管能力**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "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",
+    "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",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.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/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",
@@ -39,7 +39,8 @@
     "market:index": "node scripts/build-market-index.mjs",
     "sums": "node scripts/build-sums.mjs",
     "sums:check": "node scripts/build-sums.mjs --check",
-    "sums:verify": "node scripts/build-sums.mjs --verify"
+    "sums:verify": "node scripts/build-sums.mjs --verify",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=95 --test-coverage-branches=80 --test-coverage-include=src/trust.js --test-coverage-include=src/plugin/manifest.js --test-coverage-include=src/trace.js --test test/trust.mjs test/manifest.mjs test/trace.mjs"
   },
   "author": {
     "name": "倦飞之鸟"

package/src/ledger.js

@@ -225,8 +225,8 @@ export class EventLedger {
           `INSERT OR IGNORE INTO events
             (id, bot_id, kind, chat_id, msg_id, user_id, user_name, content,
              at, observed_at, time_basis, dedupe,
-             msg_idx, ref_msg_idx, union_openid, quoted, payload)
-           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+             msg_idx, ref_msg_idx, union_openid, quoted, payload, trace)
+           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
         )
         .run(
           id,
@@ -246,6 +246,8 @@ export class EventLedger {
           String(msg.raw?.author?.union_openid ?? '') || null,
           String(msg.quoted ?? '') || null,
           payload,
+          // 链路 id：来自 buildMessage（见 src/trace.js）。老调用方没有就给空串
+          String(msg.traceId ?? ''),
         );
       // changes === 0 说明撞了 dedupe 唯一约束 = 官方重推的同一条消息
       if (!r?.changes) {
@@ -419,14 +421,14 @@ export class EventLedger {
     const rows = beforeSeq
       ? this.db
           .prepare(
-            `SELECT seq, id, kind, chat_id, user_id, user_name, content, at, time_basis, msg_idx, quoted
+            `SELECT seq, id, kind, chat_id, user_id, user_name, content, at, time_basis, msg_idx, quoted, trace
                FROM events WHERE bot_id = ? AND chat_id = ? AND seq < ?
               ORDER BY seq DESC LIMIT ?`,
           )
           .all(this.botId, String(chatId), Number(beforeSeq), lim)
       : this.db
           .prepare(
-            `SELECT seq, id, kind, chat_id, user_id, user_name, content, at, time_basis, msg_idx, quoted
+            `SELECT seq, id, kind, chat_id, user_id, user_name, content, at, time_basis, msg_idx, quoted, trace
                FROM events WHERE bot_id = ? AND chat_id = ?
               ORDER BY seq DESC LIMIT ?`,
           )
@@ -442,6 +444,8 @@ export class EventLedger {
       timeBasis: r.time_basis,
       msgIdx: r.msg_idx,
       quoted: r.quoted,
+      // 链路 id：调用方拿它去查"这条消息后来发生了什么"
+      trace: r.trace ?? '',
       content: contentOf(r),
     }));
   }

package/src/message.js

@@ -3,6 +3,7 @@ import { createLogger } from './logger.js';
 import { FILE_TYPE, MEDIA_SOFT_LIMIT, MEDIA_HARD_LIMIT, DIRECT_UPLOAD_LIMIT } from './api.js';
 import { messageKindOf, EVENTS } from './events.js';
 import { renderMenuMd, mdToPlain } from './markdown.js';
+import { newTraceId } from './trace.js';
 
 const log = createLogger('message');
 
@@ -210,7 +211,7 @@ export function parseElements(list, depth = 0) {
 /**
  * 把官方事件体统一成好用的 Message 对象，插件只跟它打交道。
  */
-export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
+export function buildMessage(eventName, d, { api, cfg, outbound, session, traceId }) {
   const kind = messageKindOf(eventName) ?? 'unknown';
 
   let groupId = '';
@@ -251,6 +252,13 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
 
   const msg = {
     id: d.id ?? '',
+    /**
+     * 链路 id：这一条消息从进站到回话的唯一标识。
+     *
+     * 生成点必须在内核——它先看到原始事件；插件只是路过，
+     * 让插件生成会出现「同一条消息被两个插件各生成一个 id」。
+     */
+    traceId: String(traceId || newTraceId()),
     kind,
     event: eventName,
     // 事件元信息（属于哪个 intent、中文说明），来自 src/events.js

package/src/outbound.js

@@ -13,7 +13,7 @@ const log = createLogger('outbound');
  *
  *   1. 被动回复只有 5 分钟有效期，超时必失败 → 快过期时降级为主动消息
  *   2. 同一条消息最多被动回复 5 次（msg_seq 1–5）→ 用满后同样降级
- *   3. 同一会话每秒最多 5 条 → 本地令牌队列，超出的排队等
+ *   3. 发送接口 100 QPS（「每秒 5 条」只属于文字子频道，群聊 / 单聊没有这条）→ 本地令牌队列，超出的排队等
  *   4. 主动消息有两个维度：单关系 20/分钟 + 每群 1000/天 → 本地记账，用完直接拒绝
  *   5. 必须 WebSocket 在线才能发 → 离线时直接拒绝，不浪费一次网络请求
  *   6. 主动消息返回 304023 表示「已进入审核」 → 这不是失败，不能当错误处理
@@ -254,7 +254,8 @@ export class Outbound {
     this.isOnline = isOnline;
 
     const o = cfg.outbound ?? {};
-    // 官方是 5 条/秒，默认压到 4 条，给其他来源留一点余量
+    // 官方没有「每会话每秒 N 条」这条限制（那只适用于文字子频道），接口级是 100 QPS；
+    // 这里压到 4 条/秒纯属自家的保守策略，给其他来源留一点余量
     this.perSec = Math.max(1, o.perSec ?? 4);
     /**
      * 主动消息额度。官方文档（`autogen/api/.../messages.post`）写的是两个维度：

package/src/plugin/loader.js

@@ -13,6 +13,7 @@ import { ensurePluginDeps } from './deps.js';
 import { satisfies, frameworkVersion } from '../semver.js';
 import { PageRegistry } from './pages.js';
 import { RouteRegistry } from './routes.js';
+import { Declarations, normalizeManifest, checkEngines } from './manifest.js';
 
 const log = createLogger('plugins');
 
@@ -29,6 +30,8 @@ const log = createLogger('plugins');
 export class PluginManager {
   constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, reach, ledger, gate, delivery, ignoreCompat }) {
     this.dir = pluginsDir;
+    /** 插件声明的名字占用表（命令/工具/钩子），加载前查冲突、卸载时释放 */
+    this.decl = new Declarations();
     // 该机器人的全套路径（配置/数据/日志），多机器人下互不干扰
     this.paths = paths;
     // 全局配置里的 go 可执行文件路径（机器人配置里没有这一项）
@@ -240,6 +243,49 @@ export class PluginManager {
     );
   }
 
+  /**
+   * 清单检查：版本要求 + 名字声明。
+   *
+   * 放在 `setup()` 之前，理由和 `#assertCompatible` 一样——跑起来才发现
+   * 「这个命令被别的插件占了」太晚，用户看到的是「插件好像没生效」。
+   *
+   * 三件事：
+   *   1. `engines` 不满足就拒绝加载（roost / node / dsh，查不到的键跳过）
+   *   2. `provides` 有冲突就拒绝加载，并说清是谁占了哪个名字
+   *   3. **没声明 `provides` 的老插件照常加载**，只记一条 debug
+   */
+  #assertManifest(id, rawMeta) {
+    const m = normalizeManifest(rawMeta);
+
+    if (!this.ignoreCompat) {
+      const r = checkEngines(
+        m.engines,
+        { roost: frameworkVersion(), node: process.versions.node },
+        satisfies,
+      );
+      if (!r.ok) {
+        throw new Error(`${r.why}。升级后再启用，或者把插件里的 engines 改成兼容的范围`);
+      }
+    }
+
+    const total = m.provides.commands.length + m.provides.tools.length + m.provides.hooks.length;
+    if (!total) {
+      log.debug(`插件 ${id} 没有声明 provides，跳过预检（老插件正常加载）`);
+      return;
+    }
+
+    const conflicts = this.decl.claim(id, m.provides);
+    if (!conflicts.length) return;
+
+    const label = { commands: '命令', tools: '工具名', hooks: '钩子' };
+    const first = conflicts[0];
+    const extra = conflicts.length > 1 ? `（另有 ${conflicts.length - 1} 项冲突）` : '';
+    throw new Error(
+      `和插件 ${first.owner} 抢同一个${label[first.kind] ?? first.kind}「${first.name}」${extra}。` +
+        '两个插件都声明了它，后加载的这一个不会生效——先停用其中一个，或者让作者改个名字',
+    );
+  }
+
   async #detectKind(dir) {
     try {
       await fs.access(path.join(dir, 'plugin.json'));
@@ -301,6 +347,8 @@ export class PluginManager {
       }
       this.errors.set(id, e.message);
       this.errorStacks.set(id, e.stack || e.message);
+      // 声明在 setup 之前就认领了，加载失败必须还回去，否则下次重试会「自己和自己冲突」
+      this.decl.release(id);
       log.error(`插件 ${id} 加载失败: ${e.stack || e.message}`);
       /**
        * 失败时把已经建起来的东西收干净。
@@ -381,6 +429,7 @@ export class PluginManager {
     meta.id = id;
     // 版本兼容在 setup 之前拦——跑起来才发现「ctx.xxx 不是函数」就太晚了
     this.#assertCompatible(id, meta);
+    this.#assertManifest(id, meta);
 
     // 每个插件一份自己的日志文件：logs/bots/<机器人>/plugins/<id>.log
     if (this.cfg.logs?.enabled !== false) {
@@ -461,6 +510,11 @@ export class PluginManager {
       repo: raw.repo ?? '',
       supportPlatforms: Array.isArray(raw.supportPlatforms) ? raw.supportPlatforms : [],
       frameworkVersion: raw.frameworkVersion ?? raw.requires?.framework ?? '',
+      /** 清单声明（engines / provides），见 manifest.js */
+      ...(() => {
+        const mf = normalizeManifest(raw);
+        return { engines: mf.engines, provides: mf.provides };
+      })(),
       /**
        * 监听器优先级：高的先跑。见 bot.js 里的排序说明。
        * 外部插件在 plugin.json 里写 `"priority": -100` 就能排到最后。
@@ -471,6 +525,8 @@ export class PluginManager {
     };
 
     this.#assertCompatible(id, meta);
+    // 用 raw 而不是 meta：meta 是逐字段拼的，没有 provides / engines
+    this.#assertManifest(id, raw);
 
     // 每个插件一份自己的日志文件：logs/bots/<机器人>/plugins/<id>.log
     if (this.cfg.logs?.enabled !== false) {
@@ -576,6 +632,8 @@ export class PluginManager {
   /* ---------------- 卸载与重载 ---------------- */
 
   async unload(id) {
+    // 先释放声明：加载失败时也可能已经认领过（claim 在 setup 之前）
+    this.decl.release(id);
     const item = this.loaded.get(id);
     if (!item) return false;
 
@@ -625,6 +683,8 @@ export class PluginManager {
    * 重装之后会被这条旧记录挡住不加载，用户会以为装坏了。
    */
   async forget(id) {
+    // 目录已经删了，但声明可能还占着名字——不释放会让重装的同名插件「和自己冲突」
+    this.decl.release(id);
     let dirty = false;
     if (this.state && id in this.state) {
       delete this.state[id];
@@ -684,6 +744,8 @@ export class PluginManager {
       repo: meta?.repo || '',
       supportPlatforms: Array.isArray(meta?.supportPlatforms) ? meta.supportPlatforms : [],
       frameworkVersion: meta?.frameworkVersion || meta?.requires?.framework || '',
+      engines: normalizeManifest(meta).engines,
+      provides: normalizeManifest(meta).provides,
       kind,
       runtime,
     });
@@ -910,9 +972,13 @@ export class PluginManager {
     // diskIds 是「装了但没启用」的那批（include 模式下常见），
     // 也要列出来——否则用户在面板里根本看不到它，也就没法启用。
     const ids = new Set([...this.loaded.keys(), ...this.meta.keys(), ...this.diskIds]);
+    /** 一次算好再进循环：byPlugin() 每次都重建整张表，放进 map 里就是 O(n²) */
+    const claimed = this.decl.byPlugin();
     return [...ids].map((id) => {
       const item = this.loaded.get(id);
       const cached = this.meta.get(id) ?? null;
+      /** 清单声明统一从这里取：加载中用 meta，禁用中用缓存，两者字段一致 */
+      const mf = normalizeManifest(item?.meta ?? cached ?? {});
       const ext = item?.kind === 'external' ? item.host.status : null;
       return {
         id,
@@ -925,6 +991,17 @@ export class PluginManager {
         repo: item?.meta?.repo ?? cached?.repo ?? '',
         supportPlatforms: item?.meta?.supportPlatforms ?? cached?.supportPlatforms ?? [],
         frameworkVersion: item?.meta?.frameworkVersion ?? cached?.frameworkVersion ?? '',
+        /**
+         * 声明与兼容性。`provides` 优先用**实际认领**的那份（decl），
+         * 因为插件可能声明了却没用上；没加载时退回声明原文。
+         */
+        provides: claimed.get(id) ?? mf.provides,
+        engines: mf.engines,
+        enginesOk: checkEngines(
+          mf.engines,
+          { roost: frameworkVersion(), node: process.versions.node },
+          satisfies,
+        ).ok,
         enabled: this.isEnabled(id),
         loaded: Boolean(item),
         // 未加载时用缓存里的类型，别一律当成 internal

package/src/plugin/manifest.js

@@ -0,0 +1,149 @@
+/**
+ * 插件清单：能力声明与版本要求
+ * ============================
+ *
+ * 为什么需要它：命名冲突现在只在**注册那一刻**才炸——命令重复要等用户敲到
+ * 那条命令、工具重复要等 AI 真的去调。用户看到的是「这个插件好像没生效」，
+ * 而不是「A 和 B 都声明了 dice」。更麻烦的是 `hooks`：多个插件都能监听消息，
+ * 没有任何一处会告诉你「这两个插件在抢同一件事」。
+ *
+ * 这里把「我占哪些名字」提前成**声明**，加载前就能对表。
+ *
+ * 三个原则：
+ *   1. **声明可选**。老插件不写 `provides` 照常加载，只是不参与预检（会 warn）。
+ *   2. **冲突 fail-closed**。后加载的那个拒绝加载，并说清是谁占了。
+ *   3. **只声明不强制**。`provides` 是「我打算用」，真正的注册仍走原有路径，
+ *      两边对不上时以实际注册为准——声明不能变成第二套权限。
+ */
+
+/** 三类可声明的名字。`hooks` 只是提示，多个插件监听同一条消息是合法的。 */
+export const KINDS = ['commands', 'tools', 'hooks'];
+
+/** 把任意输入压成 `{ commands: [], tools: [], hooks: [] }`，去掉空值与非字符串 */
+export function normalizeProvides(raw) {
+  const out = { commands: [], tools: [], hooks: [] };
+  if (!raw || typeof raw !== 'object') return out;
+  for (const k of KINDS) {
+    const v = raw[k];
+    if (!Array.isArray(v)) continue;
+    out[k] = [...new Set(v.map((x) => String(x ?? '').trim()).filter(Boolean))];
+  }
+  return out;
+}
+
+/**
+ * 解析整个清单。`engines` 只保留认识的键，值统一成字符串。
+ *
+ * 兼容两种写法：顶层 `provides`，或 `requires.provides`（后者是给
+ * `frameworkVersion` 那套 `requires.*` 习惯留的）。
+ */
+export function normalizeManifest(raw = {}) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const req = src.requires && typeof src.requires === 'object' ? src.requires : {};
+  const enginesRaw = src.engines && typeof src.engines === 'object' ? src.engines : {};
+  const engines = {};
+  for (const k of ['roost', 'node', 'dsh']) {
+    const v = enginesRaw[k];
+    if (v !== undefined && v !== null && String(v).trim()) engines[k] = String(v).trim();
+  }
+  return {
+    provides: normalizeProvides(src.provides ?? req.provides),
+    consumes: normalizeProvides(src.consumes ?? req.consumes),
+    engines,
+  };
+}
+
+/**
+ * 版本要求检查。
+ *
+ * `actual` 里缺的键**跳过**：比如 Roost 进程里根本不知道 DSH 版本，
+ * 那就不能因为「查不到」判定不兼容——那会把所有声明了 dsh 的插件全拒掉。
+ *
+ * @param {Record<string,string>} engines
+ * @param {{roost?:string, node?:string, dsh?:string}} actual
+ * @param {(v:string, r:string)=>boolean} satisfies
+ * @returns {{ok:boolean, why?:string}}
+ */
+export function checkEngines(engines, actual, satisfies) {
+  for (const [k, range] of Object.entries(engines ?? {})) {
+    const cur = actual?.[k];
+    if (!cur) continue; // 不知道就不判
+    let ok = false;
+    try {
+      ok = satisfies(cur, range);
+    } catch {
+      return { ok: false, why: `engines.${k} 不是合法的版本范围：${range}` };
+    }
+    if (!ok) return { ok: false, why: `要求 ${k} ${range}，当前是 ${cur}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * 声明占用表。
+ *
+ * 用法：加载前 `claim()`，卸载时 `release()`。
+ * `claim` **不注册冲突项**——调用方拿到 conflicts 后应拒绝加载，
+ * 这样表里永远只有「真正生效」的声明，不会因为一次失败加载留下幽灵条目。
+ */
+export class Declarations {
+  constructor() {
+    /** @type {Map<string, {kind:string, name:string, pluginId:string}>} */
+    this.map = new Map();
+  }
+
+  static key(kind, name) {
+    return `${kind}:${name}`;
+  }
+
+  /**
+   * 认领一组名字。
+   * @param {string} pluginId
+   * @param {{commands?:string[], tools?:string[], hooks?:string[]}} provides
+   * @returns {Array<{kind:string, name:string, owner:string}>} 冲突项（空数组=全部拿到）
+   */
+  claim(pluginId, provides) {
+    const p = normalizeProvides(provides);
+    const conflicts = [];
+    const mine = [];
+
+    for (const kind of KINDS) {
+      for (const name of p[kind]) {
+        const k = Declarations.key(kind, name);
+        const held = this.map.get(k);
+        if (held && held.pluginId !== pluginId) {
+          conflicts.push({ kind, name, owner: held.pluginId });
+        } else {
+          mine.push([k, { kind, name, pluginId }]);
+        }
+      }
+    }
+
+    // 有冲突就整批不落：半套声明比没有更难查
+    if (conflicts.length) return conflicts;
+    for (const [k, v] of mine) this.map.set(k, v);
+    return [];
+  }
+
+  /** 卸载时释放这个插件的全部声明 */
+  release(pluginId) {
+    let n = 0;
+    for (const [k, v] of this.map) {
+      if (v.pluginId === pluginId) {
+        this.map.delete(k);
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /** 面板「资源占用」用：按插件分组 */
+  byPlugin() {
+    const out = new Map();
+    for (const v of this.map.values()) {
+      if (!out.has(v.pluginId)) out.set(v.pluginId, { commands: [], tools: [], hooks: [] });
+      out.get(v.pluginId)[v.kind].push(v.name);
+    }
+    return out;
+  }
+}

package/src/plugin/market.js

@@ -10,6 +10,7 @@ import { hashDir } from '../hashdir.js';
 import { compareVersion } from '../semver.js';
 import { fetchViaMirror, currentMirror } from '../mirror.js';
 import { fetchGiteeTree } from '../gitee.js';
+import { resolveTrust, checkTrust } from '../trust.js';
 
 const log = createLogger('market');
 
@@ -20,6 +21,25 @@ const indexInFlight = new Map();
 export const DEFAULT_INDEX_URL =
   'https://raw.githubusercontent.com/tdcq9594/qq-bot-roost-plugins/main/index.json';
 
+/**
+ * 这个索引地址算不算「官方源」。
+ *
+ * 只有官方源强制验签。用户把 `plugins.marketUrl` 指向自己的仓库时，
+ * 那是他自己的信任决定——我们拦他，等于不让他分享自己的插件包。
+ *
+ * 自建代理 / 镜像可以通过 `security.trust.officialUrls` 声明进来，
+ * 否则它会被当成第三方源（不拦，但也不享受强制保护）。
+ *
+ * @param {string} [url]
+ * @param {object} [cfg]
+ */
+export function isOfficialSource(url, cfg = {}) {
+  const u = String(url || DEFAULT_INDEX_URL);
+  const extra = cfg?.security?.trust?.officialUrls;
+  const list = [DEFAULT_INDEX_URL, ...(Array.isArray(extra) ? extra.map(String) : [])];
+  return list.includes(u);
+}
+
 /**
  * 拉取插件市场的索引。
  *
@@ -59,13 +79,17 @@ function assertSafeIndexUrl(raw) {
   throw new Error(`插件市场地址必须用 https${hint}：${u.protocol}//${host}`);
 }
 
-export async function fetchIndex(url = DEFAULT_INDEX_URL) {
+/**
+ * @param {string} [url]
+ * @param {{trust?: object}} [opts] 信任策略；不传就按「没配公钥」处理（本版不验签）
+ */
+export async function fetchIndex(url = DEFAULT_INDEX_URL, opts = {}) {
   const key = String(url || DEFAULT_INDEX_URL);
   assertSafeIndexUrl(key);
   const running = indexInFlight.get(key);
   if (running) return running;
 
-  const task = fetchIndexOnce(key)
+  const task = fetchIndexOnce(key, opts)
     .then(async (data) => {
       await writeIndexCache(key, data).catch(() => {});
       return data;
@@ -112,7 +136,33 @@ async function readIndexCache(url) {
   return { data: obj.data, age };
 }
 
-async function fetchIndexOnce(url) {
+/**
+ * 拉 `.sig`。**只有配了公钥才拉**——没配就是本版不验签，多一次请求纯属浪费，
+ * 也会让离线/镜像用户多等一次超时。
+ *
+ * 地址构造用 `URL` 而不是字符串拼接：自定义市场源可能带 query，
+ * 直接拼 `.sig` 会拼到 query 后面去。
+ */
+async function fetchIndexSig(url, bust) {
+  let sigUrl;
+  try {
+    const u = new URL(url);
+    u.pathname = `${u.pathname}.sig`;
+    u.searchParams.set('_t', bust);
+    sigUrl = u.toString();
+  } catch {
+    return '';
+  }
+  try {
+    const res = await fetchViaMirror(sigUrl, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) return '';
+    return await res.text();
+  } catch {
+    return '';
+  }
+}
+
+async function fetchIndexOnce(url, opts = {}) {
   let lastErr = null;
   for (let attempt = 0; attempt < 2; attempt++) {
     if (attempt > 0) await new Promise((r) => setTimeout(r, 1500));
@@ -151,6 +201,23 @@ async function fetchIndexOnce(url) {
     }
     if (!Array.isArray(data?.plugins)) throw new Error('插件市场索引格式不对（缺少 plugins 数组）');
 
+    /**
+     * 验签。**默认不阻断**（`trust.enforce` 为 false），只把结论挂在 `_trust` 上，
+     * 由安装接口决定拦不拦。这是两段式上线的第一段：先把签名铺出去，
+     * 让生态有时间跟上，下一版才默认拒绝。
+     */
+    const trust = opts.trust ?? resolveTrust({});
+    let sigText = '';
+    if (trust.pubkey) sigText = await fetchIndexSig(url, `${Date.now()}-${attempt}`);
+
+    const verdict = checkTrust({ data, sigText, trust, kind: '插件索引' });
+    data._trust = verdict;
+    // `why` 里已经带了「插件索引」前缀，这里不要再加一遍
+    if (verdict.status === 'bad') log.error(verdict.why);
+    else if (verdict.status === 'invalid') log.error(verdict.why);
+    else if (verdict.status === 'unsigned') log.warn(`${verdict.why}（本版只警告，不阻断）`);
+    else if (verdict.status === 'ok') log.info('插件索引签名校验通过');
+
     return data;
   }
   throw lastErr ?? new Error('连不上插件市场');

package/src/plugin/protocol.js

@@ -38,6 +38,8 @@ export const DEFAULTS = {
 export function serializeMessage(msg, extra = {}) {
   return {
     id: msg.id,
+    // 外部插件也要能拿到，否则「任意语言插件」这条路上链路就断了
+    trace: msg.traceId ?? '',
     kind: msg.kind,
     group: msg.groupId || '',
     user: msg.userId || '',

package/src/storage/events-schema.js

@@ -12,7 +12,7 @@
  * 合表等于把统计库那句「不存消息正文」变成假话。
  */
 
-export const EVENTS_SCHEMA_VERSION = 1;
+export const EVENTS_SCHEMA_VERSION = 2;
 
 const V1 = `
 CREATE TABLE IF NOT EXISTS events (
@@ -59,6 +59,29 @@ CREATE INDEX IF NOT EXISTS refs_from ON event_refs(from_id);
 CREATE INDEX IF NOT EXISTS refs_to   ON event_refs(to_id) WHERE resolved = 1;
 `;
 
+/**
+ * v2：链路 id。
+ *
+ * 一条消息从进站到回话的唯一标识（见 `src/trace.js`）。加它的理由很具体：
+ * 用户说"刚才那条没回"，现在只能翻四个日志文件对时间戳；有了这一列，
+ * 拿 traceId 一条 SQL 就能找到那次请求对应的原文。
+ *
+ * 老库补空串——空串表示"这条早于 traceId 上线"，不是"查不到"。
+ */
+const V2 = `
+ALTER TABLE events ADD COLUMN trace TEXT NOT NULL DEFAULT '';
+CREATE INDEX IF NOT EXISTS events_trace ON events(bot_id, trace) WHERE trace != '';
+`;
+
+/** 表里有没有这一列（迁移要幂等，重复 ALTER 会抛） */
+function hasColumn(db, table, col) {
+  try {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === col);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {object} db DatabaseSync
  */
@@ -66,6 +89,11 @@ export function migrateEvents(db) {
   const cur = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
   if (cur >= EVENTS_SCHEMA_VERSION) return { from: cur, to: cur };
   if (cur < 1) db.exec(V1);
+  /**
+   * 幂等：老库里如果已经手工加过这一列，`ALTER` 会抛 duplicate column。
+   * 版本号可能因为半途失败停在 1，所以这里必须按「列在不在」判断，不能只看版本。
+   */
+  if (!hasColumn(db, 'events', 'trace')) db.exec(V2);
   db.exec(`PRAGMA user_version = ${EVENTS_SCHEMA_VERSION}`);
   return { from: cur, to: EVENTS_SCHEMA_VERSION };
 }