qq-bot-roost 1.0.5 → 1.0.7

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-797%20passed-brightgreen" alt="测试 797 项">
+<img src="https://img.shields.io/badge/tests-813%20passed-brightgreen" alt="测试 813 项">
 <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-1.0.5-blueviolet" alt="版本 1.0.5">
+<img src="https://img.shields.io/badge/version-1.0.7-blueviolet" alt="版本 1.0.7">
 <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>
 
@@ -68,6 +68,7 @@
 - **多轮对话**：`ctx.prompt()` 问一句等回答，文字游戏的地基
 - **流式回复**：`msg.replyStream()` 做 AI 打字机效果，自动维护分片序号；群聊自动降级成普通消息
 - **模板消息**：`msg.replyCard()` 一次带上 markdown 正文 + 按钮 + ark 模板，不会拆成三条碎片
+- **图文卡片**：`msg.replyTuwen({title, description, url, picUrl})` 发官方 2026-10-28 新增的 `msg_type=8` 卡片，字段长度和 https 在发之前就校验
 - **素材缓存**：同一个图片 url 两天内只上传一次，省富媒体频控和流量
 - **中间件管道**：去重、白名单、限流、命令冷却都可插拔
 
@@ -275,7 +276,7 @@ docker compose up -d
 | 页签 | 能做什么 |
 |------|----------|
 | 概览 | 连接状态、运行时长、凭证有效期、内存、收发统计、活跃会话 Top20、重连 / 刷新凭证、调试发消息 |
-| 配置 | 凭证、intents 勾选、命令前缀、白名单、限流、去重窗口、消息日志、日志级别、面板端口 / 密钥 |
+| 配置 | 凭证、intents 勾选、命令前缀、白名单、限流、去重窗口、消息日志、日志级别、面板端口 / 密钥；底部**实例锁**：哪个 AppID 被哪个进程占着、残留记录一键清 |
 | 插件 | 列表、启用 / 禁用 / 重载、加载错误提示 |
 | 事件 | **47 个官方事件的订阅状态与接收计数**，一眼看出哪个事件没收到 |
 | 群组 | 全局主人增删、群档案（邀请人 / 群主 / 状态）、手动登记群 |
@@ -474,14 +475,9 @@ openid 完全不同。共享 `roles.json` 等于所有权限记录全部对不
 | [官方接口限制](docs/官方接口限制.md) | 官方限制清单、免@粘性原理、实现要点对照 |
 | [常见问题](docs/常见问题.md) | 收不到消息、发不出去、面板打不开、数据在哪 |
 | [真机联调](docs/真机联调.md) | 用小号（OneBot v11）在真群里跟机器人对话，测 intents / 被动回复 / msg_seq |
-| [对标 ElainaBot](docs/对标ElainaBot.md) | 与主流 Python 框架的逐项对比、差距与取舍 |
-| [事件与接口清单](docs/事件与接口清单.md) | 官方 47 个事件、47 个接口的覆盖审计（含频道生态缺口） |
-| [官方接口核查](docs/官方接口核查与AI工具化方案.md) | 逐页核对官方文档的结果：哪些接口真没有、官方能力怎么给 AI 用 |
-| [DSH-Aurabot 适配 v2](docs/DSH-Aurabot适配方案-v2.md) | 按 v0.7.2 的真实能力重写的接入方案：通道设计、模块去留、分期 |
 | [架构说明](docs/架构说明.md) | 进程模型、数据隔离、事件流、插件加载、面板多机器人实现 |
 | [DSH 接入指南](docs/DSH接入.md) | 装进 DeepSeek Harness，用 AI 管机器人：安装、配置、验证、排查 |
 | [AI 宿主接入](docs/AI宿主接入.md) | 外部 AI 驱动 Roost：SSE 消息下行、通用能力上行、能力清单 |
-| [同类项目调研](docs/GitHub同类项目调研.md) | 与 AstrBot / NoneBot2 / Koishi / ZeroBot 的对比 |
 
 ### 相关仓库
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -58,7 +58,7 @@ const PASSIVE_MAX_SEQ = 5;
  * 构造发送报文。抽成纯函数是为了能单测——`#payload` 是私有方法，测试摸不到。
  *
  * @param {object} opts 驼峰字段：content / msgType / msgId / msgSeq / eventId /
- *                      markdown / keyboard / media / ark / messageReference
+ *                      markdown / keyboard / media / card / ark / messageReference
  * @param {(msgId:string)=>number} nextSeq 取下一个 msg_seq
  * @returns {object} 官方要的 snake_case 报文
  */
@@ -72,6 +72,7 @@ export function buildSendPayload(opts = {}, nextSeq = () => 1) {
     markdown,
     keyboard,
     media,
+    card,
     ark,
     messageReference,
   } = opts;
@@ -100,6 +101,21 @@ export function buildSendPayload(opts = {}, nextSeq = () => 1) {
     payload.ark = ark;
     payload.msg_type = 3;
   }
+  /**
+   * 图文卡片（`msg_type=8`，官方 2026-10-28 新增，群聊/单聊都支持）。
+   *
+   * 放在 ark 之后是有意的：`msg_type` 是**单值**，一条消息只能有一种富文本。
+   * 同时给 markdown 和 card 时以 card 为准（最后写的赢），调用方本该只给一个。
+   *
+   * `content` 置空照抄 markdown 那条路的做法——官方示例里 `msg_type=8`
+   * 根本没有 content 字段，而 `#payload` 总会带一个 `content: ''`，
+   * 留着空串跟「类型与内容不匹配」（22006）只差一步。
+   */
+  if (card) {
+    payload.card = card;
+    payload.msg_type = 8;
+    payload.content = '';
+  }
   /**
    * 引用回复。官方是独立字段，不是 msg_id 那套被动回复：
    *   message_id 取 `REFIDX_xxx`——别人发的消息从事件的
@@ -234,7 +250,7 @@ export class QQApi {
   /**
    * 发送群消息
    * @param {string} groupOpenid
-   * @param {object} opts content / msgType / msgId / eventId / markdown / keyboard / media / ark / messageReference
+   * @param {object} opts content / msgType / msgId / eventId / markdown / keyboard / media / card / ark / messageReference
    */
   async sendGroup(groupOpenid, opts = {}) {
     const r = await this.#request('POST', `/v2/groups/${enc(groupOpenid)}/messages`, this.#payload(opts));
@@ -547,9 +563,15 @@ export class QQApi {
   async sendMedia(scene, target, { fileType, url, fileData, msgId, messageReference }) {
     const up = await this.uploadMedia(scene, target, { fileType, url, fileData });
     if (!up?.file_info) throw new Error('上传成功但未返回 file_info');
+    /**
+     * **不要 content。**
+     *
+     * 官方字段表：`msg_type=7` 时生效的是 `media`，`content` 只在
+     * `msg_type=0` 时是全文。以前这里填了一个空格占位，客户端会把
+     * 它当成正文，渲染出一块空的文字区（图被挤到一侧）。
+     */
     const opts = {
       msgType: 7,
-      content: ' ',
       media: { file_info: up.file_info },
       msgId,
       messageReference,

package/src/bot.js

@@ -379,7 +379,19 @@ export class BotRuntime {
     const claimed = await claimInstance({ appId: cfg.appId });
     if (!claimed.ok) {
       this.state = 'error';
-      this.lastError = `AppID ${cfg.appId} 已有实例在运行（PID ${claimed.conflict.pid}）`;
+      /**
+       * 文案得能指导下一步。
+       *
+       * 以前只有「AppID xxx 已有实例在运行（PID 2816）」——用户既不知道 2816
+       * 是谁，也没有任何地方能查。而他遇到的往往是「那个进程早就不在了，
+       * 只是记录没删掉」，这时候要做的事跟「真的有另一个进程在跑」完全不同。
+       */
+      const cpid = Number(claimed.conflict?.pid) || 0;
+      const who = cpid === process.pid ? '本进程里的另一个机器人配置' : `PID ${cpid}`;
+      this.lastError =
+        `AppID ${cfg.appId} 已被${who}占用。` +
+        '如果那个进程已经关了，去「设置 → 实例锁」清掉这条记录再上线；' +
+        '如果它确实还在跑，先把另一个停掉';
       this.log.error(this.lastError);
       return this.state;
     }
@@ -401,6 +413,13 @@ export class BotRuntime {
       this.state = 'error';
       this.lastError = e.message;
       this.log.error(`连接失败: ${e.message}`);
+      /**
+       * 连接失败就把认领还回去。
+       *
+       * 不还的话会留下一条「我这个 pid 还占着这个 AppID」的记录——而实际上
+       * 我根本没连上网关。那个 pid 之后被系统复用，就变成一条永远清不掉的脏记录。
+       */
+      if (!this.mock) await releaseInstance(cfg.appId).catch(() => {});
     }
     return this.state;
   }

package/src/instance.js

@@ -92,6 +92,91 @@ function isAlive(pid) {
   return pidLooksLikeNode(pid);
 }
 
+/**
+ * 这个进程的命令行。
+ *
+ * 拿不到（工具不在、没权限、进程刚好退出）返回 null —— 调用方要区分
+ * 「问不到」和「问到了但不匹配」，这两种的处理方向完全相反。
+ */
+function commandLineOf(pid) {
+  if (process.platform === 'win32') {
+    /**
+     * 先用 wmic：开一个进程约 40ms，比 PowerShell 快一个数量级。
+     * Win11 24H2 起 wmic 已被移除（本机实测 ENOENT），所以要留后路。
+     */
+    try {
+      const out = execFileSync(
+        'wmic',
+        ['process', 'where', `ProcessId=${pid}`, 'get', 'CommandLine', '/value'],
+        { encoding: 'utf8', timeout: 3000, windowsHide: true },
+      );
+      const m = /CommandLine=(.+)/.exec(out);
+      if (m) return m[1].trim() || null;
+    } catch {}
+    /**
+     * 退回 PowerShell。慢（起一个进程 300–600ms），所以**只在冲突路径上调用**：
+     * 正常启动、正常注销、面板刷新都不会走到这里。
+     */
+    try {
+      const out = execFileSync(
+        'powershell',
+        [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine`,
+        ],
+        { encoding: 'utf8', timeout: 8000, windowsHide: true },
+      );
+      return out.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    if (process.platform === 'linux') {
+      // 内核直接给，不用 fork；参数之间是 \0
+      return readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim() || null;
+    }
+    return (
+      execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8', timeout: 3000 }).trim() ||
+      null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** 本框架进程的特征。安装目录各不相同，所以只认「包名」和「入口文件名」 */
+const ROOST_HINT = /(qq-bot-roost|src[\\/]main\.js)/i;
+
+/**
+ * pid 是否还活着（且确实是本框架的进程）。
+ *
+ * 三层，一层比一层贵：
+ *   ① `isAlive` —— pid 存在 + 进程名是 node（便宜，正常路径都走这个）
+ *   ② 命令行里有没有本框架的特征（慢，**只在冲突时**才查）
+ *
+ * 第 ② 层是为 PID 复用准备的：Windows 会把回收的 PID 分给别的程序。
+ * 踩过的坑——被强杀的机器人留下 pid=15008，后来 15008 被
+ * SearchProtocolHost.exe 占用（进程名不是 node，① 就挡住了）。但如果占用者
+ * 是**另一个 node 程序**（你的构建脚本、别的 bot），① 看不出来，于是
+ * 「机器人还在跑」——启动被拒、记录删不掉、界面上显示一个你从没见过的 PID。
+ *
+ * 方向仍然是「拿不准就往活着倒」：误判成死 → 同 AppID 双开 → 4902 互踢，
+ * 比「多让用户点一次清理」严重得多。
+ *
+ * @returns {Promise<boolean>}
+ */
+async function isOurRoost(pid) {
+  if (!isAlive(pid)) return false;
+  const cmd = commandLineOf(pid);
+  if (cmd === null) return true; // 问不到 → 当成我们的
+  if (ROOST_HINT.test(cmd)) return true;
+  // 命令行里跑着某个 .js，却不含本框架特征 → 是别的 node 程序，占的是复用的 pid
+  return !/\.[cm]?js\b/i.test(cmd);
+}
+
 async function readAll() {
   try {
     const raw = JSON.parse(await fs.readFile(FILE, 'utf8'));
@@ -156,7 +241,18 @@ export async function claimInstance({ appId, force = false }) {
 
   const existing = data[key];
   if (existing && existing.pid !== process.pid && !force) {
-    return { ok: false, conflict: { pid: existing.pid, at: existing.at } };
+    /**
+     * 冲突时**再核一次**：那个 pid 现在还是不是本框架。
+     *
+     * `prune()` 走的是便宜的判断（pid 在 + 进程名是 node），挡不住
+     * 「pid 被复用给另一个 node 程序」——那种情况用户会看到一个从没见过的
+     * PID 拦着自己，而记录删不掉。这里多花一次命令行查询，
+     * **只在这条冲突路径上花**，正常启动一次都不会走到。
+     */
+    if (await isOurRoost(Number(existing.pid))) {
+      return { ok: false, conflict: { pid: existing.pid, at: existing.at } };
+    }
+    // 命令行显示是别的程序占了复用的 pid → 当死记录，继续往下认领
   }
 
   inProcessClaims.add(key);
@@ -179,7 +275,60 @@ export async function listInstances() {
   return prune(await readAll());
 }
 
+/**
+ * 面板用：把文件里的记录**原样**列出来，并标出每条还活着没。
+ *
+ * 和 `listInstances()` 的区别：那个是互斥判定用的，只返回活的；这个连死记录
+ * 一起返回——用户要清的恰恰是死记录，看不到就没法清。
+ */
+export async function listInstancesAll() {
+  const data = await readAll();
+  return Object.entries(data)
+    .filter(([, rec]) => rec && typeof rec === 'object')
+    .map(([appId, rec]) => {
+      const pid = Number(rec.pid) || 0;
+      return {
+        appId,
+        pid,
+        at: Number(rec.at) || 0,
+        mock: Boolean(rec.mock),
+        alive: isAlive(pid),
+        /** 是不是当前这个面板进程自己在用的（那条不能清） */
+        self: pid === process.pid,
+      };
+    })
+    .sort((a, b) => b.at - a.at);
+}
+
+/**
+ * 强制清掉一条实例记录（面板「实例锁」里手动清理用）。
+ *
+ * 不检查 pid 还活着没——用户点它，本来就是冲着「进程明明没了却还拦着我」来的。
+ * 但**本进程自己那条不许清**：那是正在生效的互斥，删掉等于放开同进程双开，
+ * 两个机器人用同一个 AppID 连网关会 4902 互踢。
+ *
+ * @returns {Promise<{ok:boolean, message?:string, pid?:number}>}
+ */
+export async function clearInstance(appId) {
+  const key = String(appId ?? '').trim();
+  if (!key) return { ok: false, message: '要指定 AppID' };
+  const data = await readAll();
+  const rec = data[key];
+  if (!rec) return { ok: false, message: `没有 ${key} 的记录` };
+  if (Number(rec.pid) === process.pid) {
+    return { ok: false, message: '这条是本进程自己在用的，不能清——先把那个机器人下线' };
+  }
+  delete data[key];
+  await writeAll(data);
+  return { ok: true, pid: Number(rec.pid) || 0 };
+}
+
 /** 测试用：直接看文件内容（不剪枝） */
 export async function _rawRead() {
   return readAll();
 }
+
+/** 测试用：看某个 pid 的命令行拿不拿得到（拿不到返回 null） */
+export function _commandLineOf(pid) {
+  return commandLineOf(pid);
+}

package/src/message.js

@@ -42,6 +42,34 @@ function stripMention(content) {
     .trim();
 }
 
+/**
+ * 图文卡片（`msg_type=8`）的官方硬约束，发之前先查一遍。
+ *
+ * 为什么要自己查：官方对参数不合规只回一个 `304061 消息内容无效`，
+ * **不说是哪个字段**。四个字段里有一个超长或写成了 http，日志里就只有
+ * 这么一句话，排查全靠逐个试。在这里提前拦下，日志能直接写
+ * 「description 要 1–200 字（当前 231）」。
+ *
+ * 长度按字符算（`.length`）：中文一个字算一位，跟官方「1–50 字符」对齐。
+ * emoji 会占 2 位——这只会让判断偏严，不会放过超长的内容。
+ *
+ * @returns {string} 不合格的原因；空串表示通过
+ */
+function tuwenProblem({ title, description, url, picUrl } = {}) {
+  const len = (v) => String(v ?? '').length;
+  if (!len(title)) return 'title 不能为空';
+  if (len(title) > 50) return `title 要 1–50 字（当前 ${len(title)}）`;
+  if (!len(description)) return 'description 不能为空';
+  if (len(description) > 200) return `description 要 1–200 字（当前 ${len(description)}）`;
+  for (const [name, v] of [['url', url], ['picUrl', picUrl]]) {
+    if (!len(v)) return `${name} 不能为空`;
+    /** 官方：必须是 https；http 会被拒，而且报的同样是 304061 */
+    if (!/^https:\/\//i.test(String(v))) return `${name} 必须是 https 开头`;
+    if (len(v) > 1024) return `${name} 超过 1024 字符（当前 ${len(v)}）`;
+  }
+  return '';
+}
+
 /**
  * 从正文里捞 @ 的 openid。
  *
@@ -726,6 +754,12 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
    *
    * ark 和 markdown 同时给时以 markdown 为准（官方不支持一条消息两种富文本）。
    *
+   * **ark 这条路现在基本用不上**：官方「消息类型」页把结构化卡片在单聊和
+   * 群聊都标成「发 ❌ / 收 ✅」，也就是只能收不能发（频道曾是唯一支持发送的
+   * 场景）。真实插件里也没有人调它——ark 在本项目主要是**接收侧**在用
+   * （解析别人发来的卡片）。参数保留是为了老代码不报错，新代码要发卡片
+   * 请用 `replyTuwen()`（`msg_type=8`，2026-10-28 官方新出的图文卡片）。
+   *
    * @param {{markdown?:object, keyboard?:object, ark?:object}} card
    */
   msg.replyCard = async (card = {}) => {
@@ -748,13 +782,71 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
     });
   };
 
+  /**
+   * 发**图文卡片**（`msg_type=8`，官方 2026-10-28 新增，群聊 / 单聊都支持）。
+   *
+   * 一张可点的卡片：标题 + 一句描述 + 跳转链接 + 封面图。四个字段都是必填。
+   *
+   *   await msg.replyTuwen({
+   *     title: 'iPhone 17 Pro 正式发布',
+   *     description: '全新 A20 芯片 / 钛金属机身 / 支持卫星通信',
+   *     url: 'https://news.qq.com/rain/a/20261014A05XYZ00',
+   *     picUrl: 'https://inews.gtimg.com/newsapp_bt/0/xxx/1000.jpg',
+   *   });
+   *
+   * **和 `replyCard()` 不是一回事**，虽然名字都带 card：那个发的是
+   * markdown + 按钮 + ark 的组合，ark 属于旧版结构化模板，官方现在
+   * 群聊 / 单聊都标「发 ❌」；这个发的是卡片消息类型本身，是新东西。
+   * 另起一个方法而不是塞进 `replyCard`，是因为两者的「同时给了怎么办」
+   * 逻辑不一样——那边要丢一个，这边没有并列的字段。
+   *
+   * 没有任何降级：卡片渲染不出来就是失败，不像 markdown 能退成纯文本
+   * （退成纯文本等于把图和链接都丢掉，发出去反而更奇怪）。
+   *
+   * @param {{title:string, description:string, url:string, picUrl:string}} card
+   * @returns {Promise<object|null>} 发送结果；参数不合格时是 null
+   */
+  msg.replyTuwen = async (card = {}) => {
+    const bad = tuwenProblem(card);
+    if (bad) {
+      log.error(`图文卡片没发：${bad}`);
+      return null;
+    }
+    await msg.flushReplies();
+    return send({
+      /**
+       * `msgType` 显式带上，和 `replyImage` 传 7 是同一个理由：真正决定
+       * `msg_type` 的是 `buildSendPayload` 里 `card` 那一支，但中间还有
+       * 出站记账要读这个字段，不传它账本里这条消息就是「未知类型」。
+       */
+      msgType: 8,
+      card: {
+        type: 'tuwen',
+        content: {
+          title: String(card.title),
+          description: String(card.description),
+          url: String(card.url),
+          pic_url: String(card.picUrl),
+        },
+      },
+    }, true).catch((e) => {
+      log.error('发送图文卡片失败:', e.message);
+      return null;
+    });
+  };
+
   /**
    * 发富媒体：上传后以 msg_type=7 发送。
    *
    * 富媒体在官方接口里只能是独立消息（msg_type=7），但这条消息自带
    * `content` 文本字段：传了 `text` 就和图走**同一条**，不用先发一句话
-   * 再发一张图（那是两条消息，群里看着是两截）。不传 text 时保持老
-   * 行为——content 给一个空格（官方不接受空 content）。
+   * 再发一张图（那是两条消息，群里看着是两截）。
+   *
+   * 不传 text 时**不带 content 字段**。官方对 `msg_type=7` 的 content
+   * 没有语义要求（只有 `msg_type=0` 时它才是全文），客户端拿到
+   * 「富媒体 + 空正文」就是一张干净的图。以前这里塞了个空格占位，
+   * 理由是「官方不接受空 content」——那说的是传 `''`，跟不传不是一回事，
+   * 结果客户端按图文混排渲染，图外面多出一圈文字区（v1.0.6 修掉）。
    *
    * 发送前会先把攒着的文本 flush 掉，免得「缓冲中的回复」被这条
    * 富媒体消息挤成顺序错乱的两条。
@@ -821,9 +913,18 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
       }
       if (!up?.file_info) throw new Error('未返回 file_info');
 
-      const content = text ? String(text) : ' ';
+      /**
+       * **没话要说就别带 content。**
+       *
+       * 官方字段表里 `msg_type=7` 是「富媒体(media)」，`content` 只在
+       * `msg_type=0` 时才是全文，在 7 里没有语义。以前这里塞一个空格占位，
+       * 客户端收到「富媒体 + 非空 content」就按图文排版——图被挤进卡片一侧，
+       * 群里看到的是「一张图 + 一块空文字框」，而不是一张干净的图。
+       */
       return await send({
-        msgType: 7, content, media: { file_info: up.file_info },
+        msgType: 7,
+        ...(text ? { content: String(text) } : {}),
+        media: { file_info: up.file_info },
         /** 有效类型（可能因超过软限被降级成 FILE），账本占位按它来 */
         fileType: effectiveType,
       }, true);
@@ -865,8 +966,9 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
         reuse: false, // base64 本来就不进缓存
       });
       if (!up?.file_info) throw new Error('未返回 file_info');
+      /** 同上：不带 content。buffer 分支没有「附一句话」的入口，所以永远不该有 */
       return await send({
-        msgType: 7, content: ' ', media: { file_info: up.file_info }, fileType,
+        msgType: 7, media: { file_info: up.file_info }, fileType,
       }, true);
     } catch (e) {
       log.error('发送图片 Buffer 失败:', e.message);

package/src/outbound.js

@@ -219,7 +219,9 @@ class QuotaLedger {
  *   · 纯文本   `{ content }`
  *   · markdown `{ markdown: { content } }` ← ai-chat 默认就走这条
  *   · 卡片     `{ markdown, keyboard, ark }`
- *   · 富媒体   `{ msgType: 7, media }`，正文只有一个占位空格
+ *   · 图文卡片 `{ msgType: 8, card: { type:'tuwen', content:{ title … } } }`
+ *   · 富媒体   `{ msgType: 7, media }`，**不带 content**（7 里 content 没有语义，
+ *              填了客户端会当正文，渲染出一块空文字区）
  *
  * 漏掉的后果不是发不出去（账本的状态机不看摘要），而是摘要列全变成
  * `…(0)#da39a3ee`——所有记录长得一模一样，「人工核对」这条路等于堵死，
@@ -246,6 +248,12 @@ export function digestTextOf(payload) {
   if (p.media) return mediaName ?? '[媒体]';
   if (mediaName) return mediaName;
   if (p.ark) return '[卡片]';
+  /**
+   * 图文卡片（`msg_type=8`）带上标题。只写 `[卡片]` 的话，一天发十条卡片
+   * 就是十条一模一样的记录，账本里根本分不出哪条是哪条。
+   */
+  const cardTitle = p.card?.content?.title;
+  if (p.card) return cardTitle ? `[图文卡片] ${cardTitle}` : '[图文卡片]';
   return '';
 }
 

package/src/plugin/testkit.js

@@ -241,6 +241,8 @@ export function makeMsg({
   const replies = [];
   /** markdown 消息单独记一份，好断言「走的是富文本还是纯文本」 */
   const markdowns = [];
+  /** 图文卡片同理：结构化留一份，插件测试能断言 title/url 有没有传对 */
+  const tuwens = [];
   const prefix = '/';
   const isCommand = content.startsWith(prefix);
   const body = isCommand ? content.slice(prefix.length).trim() : content;
@@ -268,6 +270,7 @@ export function makeMsg({
     replied: false,
     replies,
     markdowns,
+    tuwens,
 
     async reply(text) {
       msg.replied = true;
@@ -300,6 +303,15 @@ export function makeMsg({
       replies.push(card?.markdown?.content ?? '[card]');
       return { id: 'x' };
     },
+    async replyTuwen(card) {
+      msg.replied = true;
+      // 和真身一样先校验：插件测试里传错字段也该像线上那样「发不出去」
+      const bad = !card?.title || !card?.description || !card?.url || !card?.picUrl;
+      if (bad) return null;
+      tuwens.push({ ...card });
+      replies.push(`[tuwen] ${card.title} :: ${card.url}`);
+      return { id: 'x' };
+    },
     async replyImage(src, opts = {}) {
       msg.replied = true;
       // opts.text 走的是 msg_type=7 的 content（图文同一条消息）。

package/src/web/server.js

@@ -26,6 +26,8 @@ import {
 // 面板改插件启停时要同步机器人配置里的过滤器，两边不能各说各的
 import { pluginFilterOf, pluginAllowedIn } from '../bot.js';
 import { CONFLICT, INVALID } from '../identity.js';
+// 实例锁：面板要能看见「哪个 AppID 被谁占着」并清掉残留记录
+import { listInstancesAll, clearInstance, releaseInstance } from '../instance.js';
 import { SMTP_DEFAULTS } from '../mail/defaults.js';
 import { extractAddress } from '../mail/smtp.js';
 import { userFacingSendError } from '../outbound.js';
@@ -1352,6 +1354,28 @@ export async function startWebServer({
           if ((await listBotIds()).includes(id)) {
             return json(res, 409, { error: `机器人 ${id} 已存在` });
           }
+          /**
+           * AppID 也必须唯一。
+           *
+           * 以前只查 id：面板里能建出两只鸟填同一个 AppID，第二只点上线必报
+           * 「AppID xxx 已有实例在运行（PID yyy）」——而那个 yyy 就是面板自己。
+           * 用户看到这句话完全想不到问题出在「有两个配置填了同一个 AppID」上。
+           */
+          const appIdWanted = String(body.appId ?? '').trim();
+          if (appIdWanted) {
+            for (const other of await listBotIds()) {
+              if (other === id) continue;
+              let oc = null;
+              try {
+                oc = JSON.parse(await fs.readFile(botPaths(other).config, 'utf8'));
+              } catch {}
+              if (String(oc?.appId ?? '').trim() === appIdWanted) {
+                return json(res, 409, {
+                  error: `AppID ${appIdWanted} 已经被机器人 ${other} 用了。一个 AppID 只能配一只鸟——先改掉那边，或者用另一个 AppID`,
+                });
+              }
+            }
+          }
           try {
             const created = await onBotAdd(id, {
               name: String(body.name ?? '').trim() || id,
@@ -1458,6 +1482,8 @@ export async function startWebServer({
         if (pathname === '/api/config' && req.method === 'PUT') {
           const body = await readBody(req);
           const before = JSON.stringify({ appId: cfg.appId, intents: cfg.intents });
+          /** 改 AppID 之后要释放旧记录、认领新记录，所以先把旧值存下来 */
+          const oldAppId = String(cfg.appId ?? '');
           const oldSecret = cfg.appSecret;
 
           if (typeof body.appId === 'string') cfg.appId = body.appId.trim();
@@ -1598,8 +1624,27 @@ export async function startWebServer({
               tokens.token = '';
               tokens.expiresAt = 0;
             }
-            log.info('连接参数变化，正在重连网关...');
-            rt.gateway?.restart?.().catch(() => {});
+            /**
+             * 换 AppID 不能只 `gateway.restart()`。
+             *
+             * 那条路径只重连 WebSocket，**不经过 goOnline，也就永远不会 claim
+             * 新 AppID** —— 于是换完之后互斥对新值完全失效：两个进程用同一个新
+             * AppID 双开也不会被拦，直接 4902 互踢。反过来旧 AppID 的记录还挂着
+             * 自己的 pid，想换回去又会被它拦住。
+             *
+             * 所以走「下线 → 上线」：`goOffline` 释放（此时 cfg.appId 已经是新值，
+             * 老 key 要单独清），`goOnline` 认领新的。
+             */
+            if (oldAppId && oldAppId !== cfg.appId) {
+              await releaseInstance(oldAppId).catch(() => {});
+              if (rt.state === 'online') {
+                await rt.goOffline?.().catch(() => {});
+                await rt.goOnline?.().catch(() => {});
+              }
+            } else {
+              log.info('连接参数变化，正在重连网关...');
+              rt.gateway?.restart?.().catch(() => {});
+            }
           }
 
           // 填完 AppID / AppSecret 顺手把「默认机器人」换成官方昵称
@@ -2909,6 +2954,36 @@ export async function startWebServer({
           return json(res, 200, { ok: true });
         }
 
+        /**
+         * 实例锁：谁占着哪个 AppID。
+         *
+         * 这张表以前**只写不读**——`listInstances()` 定义了但全仓零引用。
+         * 于是用户看到「AppID xxx 已有实例在运行（PID 2816）」时，既不知道 2816
+         * 是谁，也没有任何地方能清掉它，唯一出路是自己去删 `data/instances.json`，
+         * 而大多数人根本不知道有这个文件。
+         */
+        if (pathname === '/api/instances' && req.method === 'GET') {
+          return json(res, 200, {
+            instances: await listInstancesAll(),
+            /** 当前面板进程的 pid：前端用它标出「这条是你正在用的」 */
+            pid: process.pid,
+            /** 文件路径：接口也清不掉时，至少告诉用户手动去哪删 */
+            file: path.join(DIRS.data, 'instances.json'),
+          });
+        }
+
+        /**
+         * 清掉一条残留记录。
+         *
+         * 只删「不是本进程在用」的那条——本进程的记录是正在生效的互斥，
+         * 删了就等于放开同进程双开（两个机器人同一 AppID → 4902 互踢）。
+         */
+        if (pathname === '/api/instances/clear' && req.method === 'POST') {
+          const body = await readBody(req);
+          const r = await clearInstance(String(body?.appId ?? ''));
+          return json(res, r.ok ? 200 : 400, r);
+        }
+
         // 日志
         if (pathname === '/api/logs' && req.method === 'GET') {
           const limit = Math.min(500, Number(url.searchParams.get('limit')) || 200);

package/web/app.js

@@ -1326,8 +1326,85 @@ async function loadConfig() {
   } catch (e) {
     $('#cfgMsg').textContent = '读取配置失败: ' + e.message;
   }
+  refreshInstances();
 }
 
+/* ---------------- 实例锁 ---------------- */
+
+/**
+ * 拉实例表并渲染。
+ *
+ * 为什么要有这块 UI：以前 `listInstances()` 定义了但**全仓零引用**。用户看到
+ * 「AppID xxx 已有实例在运行（PID 2816）」时，既不知道 2816 是谁、也不知道
+ * 上哪查，唯一出路是自己去删 `data/instances.json`——而大多数人不知道有这个文件。
+ */
+async function refreshInstances() {
+  const body = $('#instancesBody');
+  if (!body) return;
+  let data;
+  try {
+    data = await api('/api/instances');
+  } catch (e) {
+    body.innerHTML = `<tr><td colspan="5" class="empty">读不到实例表：${escapeHtml(e.message)}</td></tr>`;
+    return;
+  }
+  const list = Array.isArray(data?.instances) ? data.instances : [];
+  if (!list.length) {
+    body.innerHTML = '<tr><td colspan="5" class="empty">没有实例记录</td></tr>';
+  } else {
+    body.innerHTML = list
+      .map((it) => {
+        // 用内联色值：面板没有现成的状态类，硬造新 class 还得改 style.css
+        const state = it.alive
+          ? '<span style="color:var(--ok)">在跑</span>'
+          : '<span style="color:var(--err)">已退出</span>';
+        const self = it.self ? ' <span class="hint">本进程</span>' : '';
+        const when = it.at ? new Date(it.at).toLocaleString('zh-CN') : '-';
+        // 本进程那条是正在生效的互斥，清掉等于放开同进程双开
+        const action = it.self
+          ? '<span class="hint">—</span>'
+          : `<button class="btn small" data-clear="${escapeHtml(it.appId)}">清理</button>`;
+        return `<tr>
+          <td class="mono">${escapeHtml(it.appId)}</td>
+          <td class="mono">${it.pid || '-'}</td>
+          <td>${state}${self}</td>
+          <td>${escapeHtml(when)}</td>
+          <td>${action}</td>
+        </tr>`;
+      })
+      .join('');
+  }
+  const foot = $('#instancesFoot');
+  if (foot) {
+    foot.textContent = data?.file
+      ? `记录文件：${data.file}${list.some((x) => !x.alive) ? '（「已退出」的记录可以直接清）' : ''}`
+      : '';
+  }
+}
+
+$('#btnRefreshInstances')?.addEventListener('click', () => refreshInstances());
+
+// 清理按钮走事件委托：行是 innerHTML 拼的，逐行绑事件会在每次刷新后失效
+document.addEventListener('click', async (e) => {
+  const btn = e.target?.closest?.('[data-clear]');
+  if (!btn) return;
+  const appId = btn.dataset.clear;
+  const ok = await confirmDialog({
+    title: '清掉这条实例记录？',
+    message: `AppID <b>${escapeHtml(appId)}</b> 的占用记录会被删除。<br><br>
+      只有确认那个进程<b>已经不在跑了</b>才能清。如果它其实还活着，清掉之后两个进程会用同一个 AppID 连网关，互相踢下线。`,
+    okText: '清掉',
+    danger: true,
+  });
+  if (!ok) return;
+  try {
+    await api('/api/instances/clear', { method: 'POST', body: JSON.stringify({ appId }) });
+    refreshInstances();
+  } catch (err) {
+    alert('清理失败：' + err.message);
+  }
+});
+
 $('#cfgForm').addEventListener('submit', async (e) => {
   e.preventDefault();
   const f = e.target;

package/web/index.html

@@ -573,6 +573,31 @@
         <button type="submit" class="btn primary">保存配置</button>
       </div>
     </form>
+
+    <!--
+      实例锁：同一个 AppID 只允许一个进程连网关。
+      平时不用看，出现「已有实例在运行」时才来这里。
+      放在 form 外面：这里的按钮不能触发「保存配置」。
+    -->
+    <div class="box">
+      <div class="box-hd">
+        <h3>实例锁</h3>
+        <div class="plugin-tools">
+          <button class="btn small" type="button" id="btnRefreshInstances">刷新</button>
+        </div>
+      </div>
+      <div class="hint">
+        每个机器人被哪个进程（PID）占着。机器人已经退出了却还提示「已有实例在运行」时，
+        把那条「已退出」的记录清掉就行——不需要自己去翻文件。
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead><tr><th>AppID</th><th>PID</th><th>状态</th><th>登记时间</th><th></th></tr></thead>
+          <tbody id="instancesBody"><tr><td colspan="5" class="empty">读取中…</td></tr></tbody>
+        </table>
+      </div>
+      <div class="hint" id="instancesFoot"></div>
+    </div>
   </section>
 
   <!-- 统计 -->