qq-bot-roost 0.8.3 → 0.8.7

package/README.md

@@ -6,11 +6,11 @@
 
 **填 AppID + AppSecret 就能连上 QQ 官方机器人。零依赖，插件可写任意语言，自带可视化面板。**
 
-<img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22+">
+<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-551%20passed-brightgreen" alt="测试 551 项">
+<img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
 <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.6.14-blueviolet" alt="版本 0.6.14">
+<img src="https://img.shields.io/badge/version-0.8.7-blueviolet" alt="版本 0.8.7">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 
 [快速开始](#3-分钟跑起来) ｜ [写插件](docs/插件开发规范.md) ｜ [外部插件协议](docs/插件协议.md) ｜ [配置参考](docs/配置参考.md) ｜ [常见问题](docs/常见问题.md) ｜ [贡献](CONTRIBUTING.md)
@@ -106,6 +106,10 @@
 - **面板页能读自己的数据**：`ctx.registerRoute()` 注册 REST 接口（`/api/plugins/<id>/r/…`），
   鉴权/CSRF/同源校验全复用面板那套，插件拿不到裸 req/res
 - **元数据能表达兼容性**：`frameworkVersion` 声明需要的框架版本，不满足时**在加载前拦住**并说清原因，而不是跑起来才报「xxx 不是函数」
+- **插件能给 AI 贡献工具（0.8.6+）**：`ctx.registerTool()` 注册一个带 JSON Schema 的工具
+  （名字全局唯一，建议带插件前缀），别的插件用 `ctx.tools()` 拿清单、`ctx.callTool()` 直接调用。
+  于是「AI 能查斗罗玩家数据」这种事，**AI 插件和斗罗插件两边不用互相认识**——都只认这张工具表。
+  工具还能标 `ownerOnly` / `admin` 限权限，`timeoutMs` 限超时，插件卸载时自动注销
 
 **统计**
 
@@ -142,16 +146,20 @@
 
 ## 3 分钟跑起来
 
-### 1. 装 Node.js 22+
+### 1. 装 Node.js 22.13+
 
 ```bash
-node -v      # 需要 >= 22
+node -v      # 需要 >= 22.13
 ```
 
 > 用到了 Node 22 内置的全局 `WebSocket`，所以不用装 `ws`，也不需要 `npm install`。
 
 ### 2. 拿凭证
 
+**扫码最省事（0.8.4+）**：面板 → 「新建机器人」 → 点「**扫码一键创建**」，
+用手机 QQ 扫一下，AppID / AppSecret **自动填好**，不用去网页复制。
+扫码用不了、或已有机器人时，同一处还有「或者手动填」：
+
 1. <https://q.qq.com> → 创建机器人
 2. 「开发设置」里拿到 **AppID** 和 **AppSecret**
 3. **关键**：「功能配置」里开通 **群聊** 能力，否则连接会被拒（关闭码 4014）
@@ -358,6 +366,8 @@ export default {
 | `ctx.storage.get/set/all` | 插件私有存档 |
 | `ctx.config` / `ctx.setConfig()` | 插件配置读写 |
 | `ctx.can` / `ctx.levelOf` / `ctx.scopeOf` | 权限判断 |
+| `ctx.registerTool(工具)` | 注册一个 AI 可调用的工具（跨插件，0.8.6+），返回注销函数 |
+| `ctx.tools()` / `ctx.callTool(名, 参数)` | 列出 / 调用别插件注册的工具 |
 | `msg.reply` / `push` / `replyMarkdown` / `replyImage` / … | 各种发送方式 |
 
 ---
@@ -400,6 +410,7 @@ bot/
 │   ├── gateway.js              WebSocket 网关
 │   ├── webhook.js              Webhook 接收服务（多机器人共用一个端口）
 │   ├── sign.js                 Webhook 回调签名（Ed25519）
+│   ├── qq/                     扫码一键建机器人（qrlogin.js / qrsvg.js）
 │   ├── tarball.js              tar.gz 下载解包（不依赖 git）
 │   ├── updater.js              框架自身检查更新与升级
 │   ├── semver.js               版本比较与范围匹配（框架更新/市场/兼容校验共用）
@@ -412,8 +423,9 @@ bot/
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（322 项）
-│   └── e2e.mjs                 端到端测试（122 项，起真实服务打接口）
+│   ├── selftest.mjs            框架自检（474 项）
+│   ├── e2e.mjs                 端到端测试（147 项，起真实服务打接口）
+│   └── qrlogin.mjs             扫码建机器人（10 项）
 ├── web/                        面板前端（原生 JS/CSS，无构建）
 └── docs/
 ```
@@ -458,9 +470,9 @@ openid 完全不同。共享 `roles.json` 等于所有权限记录全部对不
 ## 开发
 
 ```bash
-npm test              # 框架自检 345 项
-npm run test:e2e      # 端到端 150 项（起 mock 服务打全部接口，跑在临时目录）
-npm run test:all      # 两个都跑
+npm test              # 自检 484 项（selftest 474 + qrlogin 10）
+npm run test:e2e      # 端到端 147 项（起 mock 服务打全部接口，跑在临时目录）
+npm run test:all      # 全量约 631 项：自检 + 扫码 + e2e（真机驱动要真机，没配就跳过）
 npm run check:secrets # 扫硬编码凭据（CI 也跑这个，提交前建议过一遍）
 node src/main.js --mock          # 不连 QQ，命令行发假消息调插件
 node src/main.js --mock --serve  # 只开面板，调界面

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.3",
+  "version": "0.8.7",
   "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",
+    "test": "node test/selftest.mjs && node test/qrlogin.mjs",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/e2e.mjs && node test/live-driver.mjs",
+    "test:all": "node test/selftest.mjs && node test/qrlogin.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/markdown.js

@@ -71,6 +71,71 @@ export const md = {
   },
 };
 
+/**
+ * 把 markdown 消息降级成纯文本。
+ *
+ * 为什么需要：群机器人发 markdown 要平台放行，没权限 / 内容被判不合规时接口
+ * 直接返回 400，而 markdown 是**独立消息类型**、没有纯文本兜底——不发就等于
+ * 用户点了菜单什么也看不到。所有 `ctx.menu()` 出来的东西都走这条路，所以降级
+ * 不能只打日志。
+ *
+ * 降级顺序有讲究：交互标签里带 `=` 和引号，必须先换成它显示的文字，
+ * 否则后面剥标签的正则会把它啃成半截。
+ *
+ * @param {string|{content?:string}} src markdown 正文，或 `{ content }` 对象
+ * @returns {string} 尽量保留信息量的纯文本
+ */
+export function mdToPlain(src) {
+  let s = typeof src === 'string' ? src : String(src?.content ?? '');
+  if (!s) return '';
+
+  /** 从标签里取属性值并解码（官方要求 urlencode） */
+  const attr = (tag, name) => {
+    const m = new RegExp(`\\b${name}="([^"]*)"`, 'i').exec(tag);
+    if (!m) return '';
+    try {
+      return decodeURIComponent(m[1]);
+    } catch {
+      return m[1];
+    }
+  };
+
+  // 1) 交互标签 → 它显示的文字（群聊用 show，缺了退回 text）
+  s = s.replace(/<qqbot-cmd-input\b[^>]*>/gi, (tag) => attr(tag, 'show') || attr(tag, 'text'));
+  s = s.replace(/<qqbot-cmd-enter\b[^>]*>/gi, (tag) => attr(tag, 'text'));
+  // 2) @ 人：纯文本里没有 id 对应的昵称，留个 @ 比留一串 openid 强
+  s = s.replace(/<qqbot-at-user\b[^>]*>/gi, '@');
+  // 3) 其他标签一律剥掉
+  s = s.replace(/<[^>\n]{1,200}>/g, '');
+
+  // 4) 链接 [文字](地址) → 文字（地址）；文字和地址一样就只留一份
+  s = s.replace(/\[([^\]\n]*)\]\(([^)\s]+)\)/g, (m, text, url) =>
+    !text || text === url ? url : `${text}（${url}）`,
+  );
+
+  // 5) 分割线要在剥加粗之前处理，否则 *** 会被当成加粗
+  s = s.replace(/^[ \t]*(\*[ \t]*){3,}$/gm, '———');
+  s = s.replace(/^[ \t]*(-[ \t]*){3,}$/gm, '———');
+  s = s.replace(/^[ \t]*(_[ \t]*){3,}$/gm, '———');
+
+  // 6) 强调标记
+  s = s.replace(/\*\*([^*\n]+)\*\*/g, '$1');
+  s = s.replace(/__([^_\n]+)__/g, '$1');
+  s = s.replace(/(^|[^\w*])\*([^*\n]+)\*(?=[^\w*]|$)/g, '$1$2');
+  s = s.replace(/(^|[^\w_])_([^_\n]+)_(?=[^\w_]|$)/g, '$1$2');
+  s = s.replace(/~~([^~\n]+)~~/g, '$1');
+  s = s.replace(/`{1,3}([^`]*)`{1,3}/g, '$1');
+
+  // 7) 标题、引用符号
+  s = s.replace(/^[ \t]*#{1,6}[ \t]+/gm, '');
+  s = s.replace(/^[ \t]*>[ \t]?/gm, '');
+
+  // 8) 还原 escMd 的转义
+  s = s.replace(/\\([\\`*_~])/g, '$1');
+
+  return s.replace(/[ \t]+$/gm, '').replace(/\n{3,}/g, '\n\n').trim();
+}
+
 /**
  * 把「分组菜单」渲染成带可点击指令的 markdown。
  *

package/src/message.js

@@ -1,7 +1,7 @@
 import { createLogger } from './logger.js';
 import { FILE_TYPE } from './api.js';
 import { messageKindOf, EVENTS } from './events.js';
-import { renderMenuMd } from './markdown.js';
+import { renderMenuMd, mdToPlain } from './markdown.js';
 
 const log = createLogger('message');
 
@@ -543,10 +543,40 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   /** Markdown 消息（可带按钮 keyboard）。Markdown 是独立消息类型，先把攒的文本发掉 */
   msg.replyMarkdown = async (markdown, keyboard) => {
     await msg.flushReplies();
-    return send({ markdown, keyboard }, true).catch((e) => {
-      log.error('发送 Markdown 失败:', e.message);
-      return null;
-    });
+    try {
+      return await send({ markdown, keyboard }, true);
+    } catch (e) {
+      /**
+       * Markdown 是**独立消息类型**，没有纯文本兜底：平台不放行（没权限、
+       * 内容被判不合规）就整条发不出去。而所有 `ctx.menu()` 出来的菜单都是
+       * markdown——不降级的话，用户点菜单看到的是「什么都没发生」。
+       *
+       * 只在「服务端明确拒了」时降级（4xx）。理由：
+       *   · 5xx / 网络错误 有可能已经送达，重发会变成两条；
+       *   · 429 是限流，换纯文本一样被限，白烧一次；
+       *   · offline / expired / quota 换纯文本也发不出去，expired/quota 还会多扣额度。
+       */
+      const status = Number(e?.status) || 0;
+      const rejected = (status >= 400 && status < 500 && status !== 429) || e?.code === 'api';
+      if (!rejected) {
+        log.error('发送 Markdown 失败:', e.message);
+        return null;
+      }
+      const plain = mdToPlain(markdown);
+      if (!plain) {
+        log.error(`Markdown 被拒（${e.message}），且降不出纯文本`);
+        return null;
+      }
+      /**
+       * 不带 keyboard：按钮挂在纯文本上平台不认，带上会连累整条消息再被拒一次。
+       * 按钮里的指令本来也会出现在正文里（ctx.menu 渲染时带上），信息不丢。
+       */
+      log.warn(`Markdown 被拒（${e.message}），降级为纯文本重发`);
+      return send({ content: plain }, true).catch((e2) => {
+        log.error('降级纯文本也没发出去:', e2.message);
+        return null;
+      });
+    }
   };
 
   /**

package/src/plugin/context.js

@@ -4,9 +4,11 @@ import { createLogger } from '../logger.js';
 import { scopeOf, LEVEL, NO_PERM, levelName } from '../roles.js';
 import { md, renderMenuMd } from '../markdown.js';
 import { normalizeDashboard } from './dashboard.js';
+import { createToolCaller } from './tools.js';
+
 
 /**
- * 全局注册表：所有插件注册的命令和事件监听都放这里。
+ * 全局注册表：所有插件注册的命令、事件监听、AI 工具都放这里。
  * 重载插件时按 pluginId 精确清除，互不影响。
  */
 export class Registry {
@@ -15,6 +17,14 @@ export class Registry {
     this.listeners = new Map(); // eventName -> [{ pluginId, handler }]
     // pluginId -> { id, title, desc, sections: [{ title, items: [{ text, desc, isCommand }] }] }
     this.menus = new Map();
+    /**
+     * AI 可调用工具：name -> entry。
+     *
+     * 为什么按工具名而不是按插件索引：模型只认工具名，调用时也只给名字，
+     * 按名直查是 O(1)；重名必须当场报错，否则模型会调到一个「不知道谁的」
+     * 同名工具，出问题极难排查。
+     */
+    this.tools = new Map();
   }
 
   clearPlugin(id) {
@@ -27,6 +37,9 @@ export class Registry {
       else this.listeners.delete(event);
     }
     this.menus.delete(id);
+    for (const [name, entry] of this.tools) {
+      if (entry.pluginId === id) this.tools.delete(name);
+    }
   }
 
   /** 取（或建）某插件的菜单 */
@@ -104,6 +117,71 @@ export class Registry {
     if (!this.listeners.has(event)) this.listeners.set(event, []);
     this.listeners.get(event).push({ pluginId, handler });
   }
+
+  /**
+   * 注册一个 AI 可调用的工具。
+   *
+   * @param {string} pluginId
+   * @param {object} meta { name, description, parameters, ownerOnly, admin, timeoutMs, hidden }
+   * @param {(args:object, callCtx:object)=>any} handler
+   */
+  addTool(pluginId, meta, handler) {
+    const name = String(meta?.name ?? '').trim();
+    if (!name) throw new Error('工具缺少 name');
+    if (this.tools.has(name)) {
+      const owner = this.tools.get(name).pluginId;
+      throw new Error(
+        owner === pluginId
+          ? `工具 "${name}" 在本插件里重复注册`
+          : `工具 "${name}" 已被插件 ${owner} 注册`,
+      );
+    }
+    this.tools.set(name, {
+      pluginId,
+      pluginName: meta?.pluginName ?? pluginId,
+      name,
+      description: String(meta?.description ?? '').trim(),
+      parameters: meta?.parameters ?? { type: 'object', properties: {} },
+      handler,
+      ownerOnly: Boolean(meta?.ownerOnly),
+      admin: Boolean(meta?.admin),
+      timeoutMs: Number(meta?.timeoutMs) > 0 ? Number(meta.timeoutMs) : 0,
+      hidden: Boolean(meta?.hidden),
+    });
+    return this.tools.get(name);
+  }
+
+  removeTool(pluginId, name) {
+    const e = this.tools.get(name);
+    if (e && e.pluginId === pluginId) this.tools.delete(name);
+  }
+
+  getTool(name) {
+    return this.tools.get(String(name ?? '').trim()) ?? null;
+  }
+
+  /**
+   * 可对外暴露的工具描述（**不含 handler**）。
+   *
+   * 为什么不返回 entry 本体：这些描述会原样交给模型服务商，
+   * 带上函数引用既没法序列化，也等于把内部实现递出去。
+   */
+  listTools({ includeHidden = false } = {}) {
+    const out = [];
+    for (const e of this.tools.values()) {
+      if (e.hidden && !includeHidden) continue;
+      out.push({
+        name: e.name,
+        description: e.description,
+        parameters: e.parameters,
+        pluginId: e.pluginId,
+        pluginName: e.pluginName,
+        ownerOnly: e.ownerOnly,
+        admin: e.admin,
+      });
+    }
+    return out;
+  }
 }
 
 /** 每个插件一个简单的 JSON 键值存储，游戏存档之类可以直接用 */
@@ -236,6 +314,18 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
   // 面板「运行数据」：插件用 ctx.setDashboard() 推的最后一份
   let dashboardCache = null;
 
+  /**
+   * 工具调用器。`can` 依赖 ctx 自己（要按会话算权限等级），所以这里传的是
+   * 延迟求值的闭包——箭头函数体在真正调用时才碰 ctx，那时它早就建好了。
+   */
+  const callTool = createToolCaller({
+    registry,
+    isOwner,
+    can: (m, need) => ctx.can(m, need),
+    scopeOf,
+    log: (m) => logger.debug(m),
+  });
+
   const ctx = {
     id,
     name: meta.name ?? id,
@@ -442,6 +532,86 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
       registry.addListener(id, event, handler);
     },
 
+    /**
+     * 注册一个 **AI 可调用**的工具（跨插件）。
+     *
+     * 命令是给人打的，工具是给模型调的：模型只看到名字、说明和参数 schema，
+     * 自己决定什么时候调。别的插件（尤其 AI 插件）用 `ctx.tools()` 拿到清单、
+     * `ctx.callTool()` 执行，于是「AI 能查斗罗玩家数据」这种事不用 AI 插件
+     * 认识斗罗插件——两边只认这张表。
+     *
+     *   ctx.registerTool({
+     *     name: 'douluo_status',
+     *     description: '查一个斗罗玩家的等级、魂环、金币',
+     *     parameters: {
+     *       type: 'object',
+     *       properties: { uin: { type: 'string', description: '玩家 QQ 号' } },
+     *       required: ['uin'],
+     *     },
+     *     async execute({ uin }, call) {
+     *       const p = await load(uin);
+     *       return `${uin}：${p.level} 级，${p.gold} 金币`;
+     *     },
+     *   });
+     *
+     * `call` 里有 `{ msg, chatId, userId, userName, kind, scope, callTool }`，
+     * 需要按人区分的工具从 `call.userId` 取，别自己去翻全局。
+     *
+     * 名字**全局唯一**（跨插件也不能重）：模型只认名字，重名会调到一个
+     * 「不知道谁的」同名工具，出了问题极难查。
+     *
+     * @param {object} tool
+     * @param {string} tool.name         全局唯一，建议带插件前缀
+     * @param {string} [tool.description] 给模型看的说明，写「做什么」别写「怎么实现」
+     * @param {object} [tool.parameters]  JSON Schema（OpenAI function calling 同款）
+     * @param {boolean} [tool.ownerOnly]  只有机器人主人能调
+     * @param {boolean} [tool.admin]      需要当前会话管理员
+     * @param {number} [tool.timeoutMs]   超时，默认 15s
+     * @param {boolean} [tool.hidden]     不出现在 ctx.tools() 里，只能显式调用
+     * @param {(args:object, call:object)=>any} tool.execute
+     * @returns {() => void} 注销函数（插件卸载时会自动调用，不用手动收）
+     */
+    registerTool(tool) {
+      if (!tool || typeof tool.execute !== 'function') {
+        throw new Error('registerTool 需要 { name, execute }');
+      }
+      registry.addTool(
+        id,
+        { ...tool, pluginName: meta.name ?? id },
+        // 包一层：把 execute 抛出的同步异常也变成 rejection，
+        // 否则 callTool 里的 try/finally 接不住同步 throw
+        (args, call) => Promise.resolve().then(() => tool.execute(args, call)),
+      );
+      const off = () => registry.removeTool(id, tool.name);
+      disposers.push(off);
+      return off;
+    },
+
+    /**
+     * 列出所有插件暴露的 AI 工具（**不含执行函数**，可以直接序列化给模型）。
+     *
+     * 为什么不带 handler：这份清单会原样进请求体发给服务商，
+     * 带上函数引用既没法 JSON 化，也等于把内部实现递出去。
+     *
+     * @param {{includeHidden?:boolean}} [opts]
+     */
+    tools(opts) {
+      return registry.listTools(opts);
+    },
+
+    /**
+     * 执行一个工具。权限、超时、重入在这里统一兜住，调用方只管处理结果。
+     *
+     *   const list = ctx.tools();
+     *   const out = await ctx.callTool('douluo_status', { uin }, { msg });
+     *
+     * 失败一律 **throw**（不是返回空）：调用方多半是 AI 插件，它要把
+     * 「工具报错了」这句话回填给模型，让模型自己圆回来。
+     */
+    callTool(name, args, opts) {
+      return callTool(name, args, opts);
+    },
+
     /**
      * 定时任务。返回停止函数；插件卸载时会自动清理，不会残留。
      *   ctx.schedule('daily-reset', 60_000, () => { ... })

package/src/plugin/subprocess.js

@@ -275,6 +275,16 @@ export class SubprocessPlugin {
         this.commands = Array.isArray(o.commands) ? o.commands : [];
         this.menus = Array.isArray(o.menus) ? o.menus : [];
         this.levels = Array.isArray(o.levels) ? o.levels : [];
+        /**
+         * 外部插件还不能注册 AI 工具：工具的调用要走一次「核心 → 插件 → 核心」
+         * 的往返，协议里目前只有 msg 这一条请求/响应通道。与其默默忽略、
+         * 让作者以为自己注册成功了，不如当场说清楚。
+         */
+        if (Array.isArray(o.tools) && o.tools.length) {
+          this.log.warn(
+            `插件声明了 ${o.tools.length} 个 AI 工具，但外部插件暂不支持注册工具（需要内核插件，或等协议 v2）`,
+          );
+        }
         // listen 支持 true（= 全部消息）或字符串数组
         if (o.listen === true) this.listen = ['message'];
         else if (Array.isArray(o.listen)) this.listen = o.listen.map(String);

package/src/plugin/testkit.js

@@ -15,6 +15,8 @@
 
 import os from 'node:os';
 import path from 'node:path';
+import { Registry } from './context.js';
+import { createToolCaller } from './tools.js';
 
 /** 假的存储：全放内存，跑完就没了 */
 function memoryStorage() {
@@ -69,11 +71,32 @@ function fakeLogger(quiet) {
  * 造一个够用的 ctx。
  * @param {object} [opts]
  */
-export function makeCtx({ id = 'test', config = {}, quiet = true, dataDir = null } = {}) {
+export function makeCtx({
+  id = 'test',
+  config = {},
+  quiet = true,
+  dataDir = null,
+  registry = null,
+  isOwner: isOwnerFn = null,
+  can: canFn = null,
+} = {}) {
   const commands = new Map();
   const menus = [];
   const listeners = new Map();
   const scheduled = [];
+  /**
+   * 工具表。不传 registry 就自己造一个；要测「A 插件注册、B 插件调用」
+   * 时给两个 ctx 传**同一个** Registry 即可，和内核里的行为一致。
+   */
+  const toolRegistry = registry ?? new Registry();
+
+  /** 和内核同一份调用语义（权限/超时/重入），避免夹具与线上分叉 */
+  const toolCaller = createToolCaller({
+    registry: toolRegistry,
+    isOwner: (u) => ctx.isOwner(u),
+    can: (m, need) => ctx.can(m, need),
+    scopeOf: (m) => ctx.scopeOf(m),
+  });
 
   const ctx = {
     id,
@@ -131,9 +154,9 @@ export function makeCtx({ id = 'test', config = {}, quiet = true, dataDir = null
       for (const k of Object.keys(map)) out[k] = 10 + (map[k] ?? i++);
       return out;
     },
-    isOwner: () => false,
+    isOwner: isOwnerFn ?? (() => false),
     levelOf: async () => 9999,
-    can: async () => true,
+    can: canFn ?? (async () => true),
     scopeOf: (msg) => (msg?.groupId ? `group:${msg.groupId}` : `user:${msg?.userId ?? ''}`),
     isGroupAdmin: async () => false,
     getGroup: async () => null,
@@ -163,11 +186,31 @@ export function makeCtx({ id = 'test', config = {}, quiet = true, dataDir = null
     },
     dispose: () => {},
 
+    /* ---------------- 跨插件 AI 工具（和内核同一套语义） ---------------- */
+    registerTool(tool) {
+      if (!tool || typeof tool.execute !== 'function') {
+        throw new Error('registerTool 需要 { name, execute }');
+      }
+      toolRegistry.addTool(
+        id,
+        { ...tool, pluginName: ctx.name },
+        (args, call) => Promise.resolve().then(() => tool.execute(args, call)),
+      );
+      return () => toolRegistry.removeTool(id, tool.name);
+    },
+    tools(opts) {
+      return toolRegistry.listTools(opts);
+    },
+    callTool(name, args, opts) {
+      return toolCaller(name, args, opts);
+    },
+
     /* 夹具内部用 */
     __commands: commands,
     __menus: menus,
     __listeners: listeners,
     __scheduled: scheduled,
+    __tools: toolRegistry,
   };
 
   return ctx;

package/src/plugin/tools.js

@@ -0,0 +1,101 @@
+/**
+ * 跨插件 AI 工具的调用核心
+ * ========================
+ *
+ * 工具注册在 `Registry.tools`（按工具名索引，重载插件时按 pluginId 清），
+ * 这个文件只管**执行**：权限、超时、重入、调用上下文。
+ *
+ * 为什么单独拎出来：真 `ctx`（context.js）和插件测试夹具（testkit.js）都要
+ * 能调工具。语义写两份必然分叉——夹具里「有权限、没超时」，线上「要管理员、
+ * 15 秒超时」，插件作者在本地测通了上线却挂，是最难查的一类问题。
+ */
+
+/** 工具默认超时：AI 插件按轮推进，一个工具卡住等于整轮回复卡住 */
+export const DEFAULT_TOOL_TIMEOUT_MS = 15000;
+
+/**
+ * @param {object} deps
+ * @param {import('./context.js').Registry} deps.registry
+ * @param {(userId:string)=>boolean} deps.isOwner
+ * @param {(msg:object, need:string)=>Promise<boolean>} deps.can
+ * @param {(msg:object)=>string} deps.scopeOf
+ * @param {(msg:string)=>void} [deps.log]
+ */
+export function createToolCaller({ registry, isOwner, can, scopeOf, log = () => {} }) {
+  /**
+   * 执行一个工具。
+   *
+   * 失败一律 **throw**：调用方多半是 AI 插件，它要把「工具报错了」这句话
+   * 回填给模型让模型自己圆回来。返回 null / '' 表示「成功但没内容」，
+   * 这两种语义不能混。
+   *
+   * @param {string} name
+   * @param {object} [args]
+   * @param {{msg?:object, stack?:string[]}} [opts]
+   *        `stack` 是内部用的调用链，别自己传。
+   */
+  return async function callTool(name, args = {}, { msg = null, stack = [] } = {}) {
+    const key = String(name ?? '').trim();
+    const t = registry.getTool(key);
+    if (!t) throw new Error(`没有名为 "${key}" 的工具`);
+
+    /**
+     * 同一条调用链里不许重复出现同一个工具。
+     *
+     * 为什么用「链」而不是「全局正在执行集合」：全局集合会把**并发**误杀——
+     * 两个群同时问一句，第二个请求会因为「第一个还在跑」被拒，
+     * 而这两次调用本来毫无关系。用调用链则只挡真正的递归。
+     */
+    if (stack.includes(key)) {
+      throw new Error(`工具 "${key}" 不能在自己的调用链里重复调用（会无限递归）`);
+    }
+    const nextStack = [...stack, key];
+
+    const userId = msg?.userId ?? '';
+    if (t.ownerOnly && !isOwner(userId)) {
+      throw new Error(`工具 "${key}" 只有机器人主人能用`);
+    }
+    if (t.admin) {
+      if (!msg) throw new Error(`工具 "${key}" 需要管理员身份，但调用方没给会话上下文`);
+      if (!(await can(msg, 'admin'))) {
+        throw new Error(`工具 "${key}" 需要当前会话的管理员权限`);
+      }
+    }
+
+    const ms = t.timeoutMs || DEFAULT_TOOL_TIMEOUT_MS;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        () =>
+          reject(
+            new Error(
+              `工具 "${key}" 超过 ${ms >= 1000 ? `${Math.round(ms / 1000)}s` : `${ms}ms`} 没返回`,
+            ),
+          ),
+        ms,
+      );
+      // 别让一个 15s 的定时器把进程钉在事件循环里
+      timer.unref?.();
+    });
+
+    const call = {
+      msg,
+      chatId: msg?.chatId ?? '',
+      userId,
+      userName: msg?.userName ?? '',
+      kind: msg?.kind ?? '',
+      scope: msg ? scopeOf(msg) : 'global',
+      pluginId: t.pluginId,
+      toolName: key,
+      // 工具之间可以组合，但同样受重入与超时约束
+      callTool: (n, a) => callTool(n, a, { msg, stack: nextStack }),
+    };
+
+    log(`调用工具 ${key}（注册方：${t.pluginId}）`);
+    try {
+      return await Promise.race([t.handler(args ?? {}, call), timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}