qq-bot-roost 0.9.6 → 0.9.8

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 };
 }

package/src/tarball.js

@@ -34,18 +34,32 @@ export function parseTar(buf) {
   let off = 0;
 
   while (off + 512 <= buf.length) {
+    /** 本轮起点：用来判断「有没有真的往前走」，见下面的 next 检查 */
+    const start = off;
     const header = buf.subarray(off, off + 512);
     // 全零块 = 结束
     if (header.every((b) => b === 0)) break;
 
-    const readStr = (start, len) => {
-      const slice = header.subarray(start, start + len);
+    /**
+     * 参数叫 `pos` 而不是 `start`：外层那个 `start` 是「本轮在 buf 里的起点」，
+     * 两者含义完全不同，同名遮蔽会让人以为能互相引用。
+     */
+    const readStr = (pos, len) => {
+      const slice = header.subarray(pos, pos + len);
       const end = slice.indexOf(0);
       return slice.subarray(0, end === -1 ? len : end).toString('utf8');
     };
 
     const name = readStr(0, 100);
-    const size = parseInt(readStr(124, 12).trim(), 8) || 0;
+    /**
+     * size 必须夹到非负。
+     *
+     * 八进制字段里出现 `-` 时 `parseInt` 会给出负数，后面
+     * `Math.ceil(size / 512) * 512` 就是负的，游标「前进 512 又倒退 512」
+     * 原地打转——而这个循环每轮都 push 一条条目，于是**内存直接爆掉**。
+     * 一个几十字节的畸形 tar 就能把机器人打死（2026-10-31 用 fuzz 撞出来的）。
+     */
+    const size = Math.max(0, parseInt(readStr(124, 12).trim(), 8) || 0);
     const type = String.fromCharCode(header[156]) || '0';
     // ustar 前缀，长路径会用它
     const prefix = readStr(345, 155);
@@ -53,7 +67,21 @@ export function parseTar(buf) {
 
     off += 512;
     const content = buf.subarray(off, off + size);
-    off += Math.ceil(size / 512) * 512;
+    /**
+     * 游标必须严格前进。即使 size 已经夹到非负，这里再兜一道：
+     * 畸形头导致的任何「原地踏步」都会变成死循环 + 内存爆炸，
+     * 而正常的 tar 每轮至少前进 512 字节，不可能触发。
+     */
+    const next = off + Math.ceil(size / 512) * 512;
+    /**
+     * 和**本轮起点**比，不是和 `off` 比。
+     *
+     * `size = 0`（目录条目）时 `next` 正好等于 `off`，拿 `off` 比会把
+     * 正常的空条目误判成「没前进」而提前结束——第一版就是这么写的，
+     * 结果一个含目录的正常 tar 只解析出第一条。
+     */
+    if (next <= start) break;
+    off = next;
 
     if (type === '5') entries.push({ name: fullName, dir: true });
     else if (type === '0' || type === '\0') entries.push({ name: fullName, dir: false, content });

package/src/trace.js

@@ -0,0 +1,28 @@
+/**
+ * 链路追踪 id
+ * ===========
+ *
+ * 一条消息要穿过四段：QQ 事件 → Roost 内核 → ai-chat 插件 → dsh-roost → 模型。
+ * 出问题时现在只能翻四个日志文件对时间戳——用户说「刚才那条没回」，
+ * 根本不知道该看哪一段。
+ *
+ * 这里生成一个短 id，进站时打上，每段日志都带着它，面板也能按它串起来。
+ *
+ * 为什么不是 UUID：要能在日志里一眼扫到、能手打、能贴进群里问。
+ * 时间前缀（36 进制）让同一秒内的 id 也有序，后面 6 位十六进制够区分。
+ * 碰撞概率：同一毫秒内 1/1677 万，对一个群聊机器人足够。
+ */
+import crypto from 'node:crypto';
+
+/**
+ * @returns {string} 形如 `m3k9x2a1f3c4`
+ */
+export function newTraceId() {
+  return `${Date.now().toString(36)}${crypto.randomBytes(3).toString('hex')}`;
+}
+
+/** 日志前缀：统一成 `[trace:xxxx]`，方便 grep */
+export function traceTag(id) {
+  const t = String(id ?? '').trim();
+  return t ? `[trace:${t}]` : '';
+}