koishi-plugin-kkk 3.11.1 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # 更新日志
 
+## 3.12.1
+
+### 修：B站卡片的简介没了
+
+有一批 B 站视频解析出来的卡片，标题下面直接跳到播放数据，**视频简介整块不见了**。
+不是渲染糊了，是压根没画上去。
+
+原因是 B 站接口有时会把简介放在「分段简介」里、有时只放在普通简介字段里，
+之前的代码碰上第一种情况以外的数据会算出一份空简介，然后把「空的」当成「有内容」画出来，
+结果整块简介反而被吃掉了。
+
+现在两个字段都试，哪个真的有内容就用哪个 —— 单行简介、多行简介、带 @ 和链接的简介
+都能正常显示出来。
+
+顺手还修了一处：接口返回的简介字段是空的时候不会再让解析报错。
+
+## 3.12.0
+
+### 新：提取图片的按钮只能点一次
+
+卡片下面「提取封面图 / 提取评论区图片」这两个按钮以前可以一直点。有人一直点，
+群里就被同一张图刷屏，而且看不出是谁在点。
+
+现在**同一张卡片上的同一个按钮只放行一次**：
+
+- 再点不会往群里发任何东西（不再刷屏），但日志里会记下「这次是谁点的、之前是谁点过」，
+  真被人刷了能查出来；
+- 封面和评论区是两个按钮，各点各的，互不影响；换一个作品也照常能点；
+- 想再要一次，**重新发一遍链接**就行，新卡片下面的按钮又是可点的（不会被永久锁死）；
+- 自己手敲 `kkk封面` / `kkk评论` 不受这个限制，随时都能用。
+
+还有一处顺手修的：万一这次没发出去（图过期了、或者发送报错），这次点击**不算数**，
+再点一次还是能发 —— 以前那种「点一次就永久作废」的情况不会出现。
+
 ## 3.11.1
 
 这一版修的主要是两类事：**东西发不出去**，和**按钮点了没反应**。

package/lib/build-metadata.json

@@ -1,10 +1,10 @@
 {
-  "version": "3.11.1",
-  "buildTime": "2026-10-01T13:05:54.560Z",
-  "buildTimestamp": 1790859954564,
+  "version": "3.12.1",
+  "buildTime": "2026-10-03T17:20:37.408Z",
+  "buildTimestamp": 1791048037420,
   "name": "koishi-plugin-kkk",
   "description": "抖音 / B站 / 快手 / 小红书 视频解析与动态推送，带 QQ 交互面板与弹幕烧录（karin-plugin-kkk 的 Koishi 移植版）",
   "homepage": "https://github.com/maimai993/koishi-plugin-kkk#readme",
-  "commitHash": "676659fbbdf78244670d22aee37bb7668ef73b42",
-  "shortCommitHash": "676659f"
+  "commitHash": "c3384b0563f126fff043bf0fed433cc406fd08a9",
+  "shortCommitHash": "c3384b0"
 }

package/lib/karin/apps/tools.js

@@ -627,6 +627,20 @@ const handleCardParse = (0, ErrorHandler_1.wrapWithErrorHandler)(async (e, next)
  * `卡片消息` 是可推导的中文名，放最前面。
  */
 exports.cardAPP = node_karin_1.default.command(/卡片消息/, handleCardParse, { name: 'kkk-卡片解析' });
+/**
+ * 这条指令是不是**QQ 回调按钮**点出来的。
+ *
+ * 判据是会话类型：回调按钮（`action.type = 1`）在适配器里被标成
+ * `session.type = 'interaction/button'`（见 `koishi-plugin-adapter-qq-crack` 的 `utils.ts`），
+ * 而手敲指令、以及不支持原生按钮时给的蓝字文字链（`<qqbot-cmd-input>`），
+ * 都会变成**普通消息**（`session.type = 'message'`）。
+ *
+ * 这个区别正是「限一次」的适用范围：**只有按钮才限一次**。
+ * 按钮用户看不见指令、也没法确认自己点没点过，所以由插件兜着；
+ * 手敲指令是用户主动发的，随时都能用，留一条明确的路（图发不出来时还能重试）。
+ * @param e 消息事件
+ */
+const isButtonClick = (e) => String(e?.session?.type ?? '') === 'interaction/button';
 /**
  * 单独把卡片图发一遍（`kkk封面` / `kkk评论`）。
  *
@@ -636,6 +650,11 @@ exports.cardAPP = node_karin_1.default.command(/卡片消息/, handleCardParse,
  *
  * **不重新解析、不重新渲染**：图源是上次解析记下来的（见 CardImageCache），
  * 15 分钟过期（评论图是临时文件，会被定时清理），过期了就提示先发条链接。
+ *
+ * **按钮只放行一次**（用户要求：有人一直点，群里被同一张图刷屏、还查不出是谁）：
+ * `interaction/button` 这条路上按「作品 + 按钮种类」先占后发，重复点击**静默忽略**、
+ * 只在日志里记下是谁在点。手敲指令不受此限；重新发一次链接（新卡片）
+ * 会 `rememberCardImages` 重新武装按钮。
  */
 const handleExtractCard = (0, ErrorHandler_1.wrapWithErrorHandler)(async (e, next) => {
     const msg = String(e.msg ?? '');
@@ -648,7 +667,20 @@ const handleExtractCard = (0, ErrorHandler_1.wrapWithErrorHandler)(async (e, nex
      */
     const arg = msg.replace(/^#?(?:kkk封面|kkk评论|提取封面图|提取评论区图片)/, '').trim();
     const wantComment = /评论/.test(msg);
-    const cached = (0, CardImageCache_1.recallCardImages)((0, CardImageCache_1.resolveCardImageKey)(e, arg));
+    const cardKey = (0, CardImageCache_1.resolveCardImageKey)(e, arg);
+    const kind = wantComment ? 'comment' : 'cover';
+    const label = wantComment ? '提取评论区图片' : '提取封面图';
+    /**
+     * **拦截重复点击。**「先占后发」而不是「发成功再记」：
+     * 反过来写的话，快速连点会有好几次同时通过检查，照样能刷出好几条。
+     */
+    const fromButton = isButtonClick(e);
+    if (fromButton && !(0, CardImageCache_1.claimCardImageExtract)(cardKey, kind, String(e.userId ?? ''))) {
+        const prev = (0, CardImageCache_1.recallCardImageExtract)(cardKey, kind);
+        node_karin_1.logger.mark('[提取卡片图] 忽略一次重复点击：%s 点的「%s」，这张卡片上 %s 已经点过了（同一张卡片只放行一次，想再要一次就重新发链接）', String(e.userId ?? '（未知用户）'), label, prev?.by ? String(prev.by) : '（未知用户）');
+        return;
+    }
+    const cached = (0, CardImageCache_1.recallCardImages)(cardKey);
     let urls;
     if (wantComment) {
         /**
@@ -676,14 +708,25 @@ const handleExtractCard = (0, ErrorHandler_1.wrapWithErrorHandler)(async (e, nex
         urls = cached?.cover ? [cached.cover] : undefined;
     }
     if (!urls?.length) {
+        /** 这次没发出去，不该算「点过了」——否则图一过期按钮就彻底废了 */
+        if (fromButton)
+            (0, CardImageCache_1.releaseCardImageExtract)(cardKey, kind);
         await e.reply(wantComment
             ? '没拿到这条内容的评论区图片 —— 评论里没有用户贴图，或者已经过期（15 分钟）／临时文件被清理了，重新发一下链接再点 ~'
             : '没找到这个作品的封面 —— 可能已经过期（15 分钟），重新发一下链接再点 ~');
         return;
     }
     /** 图片统一走 markdown：QQ 上不会被二次压缩，小字才看得清（见 compat/imageMarkdown） */
-    const md = await (0, QqPanel_1.buildMarkdownImageMessage)(urls, 420, (0, ImageSlice_1.platformOf)(e));
-    await e.reply(md ?? urls.map((url) => node_karin_1.segment.image(url)));
+    try {
+        const md = await (0, QqPanel_1.buildMarkdownImageMessage)(urls, 420, (0, ImageSlice_1.platformOf)(e));
+        await e.reply(md ?? urls.map((url) => node_karin_1.segment.image(url)));
+    }
+    catch (error) {
+        /** 发送失败同样不当「点过了」：用户再点一次还能拿到图 */
+        if (fromButton)
+            (0, CardImageCache_1.releaseCardImageExtract)(cardKey, kind);
+        throw error;
+    }
     node_karin_1.logger.debug('[提取卡片图] 已发送 %s 张（%s）', urls.length, wantComment ? '评论区' : '封面');
 }, { businessName: '提取卡片图' });
 /**

package/lib/karin/module/utils/CardImageCache.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cardImageKeyOf = cardImageKeyOf;
 exports.rememberCardImages = rememberCardImages;
+exports.claimCardImageExtract = claimCardImageExtract;
+exports.releaseCardImageExtract = releaseCardImageExtract;
+exports.recallCardImageExtract = recallCardImageExtract;
 exports.rememberLastCardKey = rememberLastCardKey;
 exports.resolveCardImageKey = resolveCardImageKey;
 exports.recallCardImages = recallCardImages;
@@ -12,6 +15,27 @@ const TTL_MS = 15 * 60 * 1000;
 const store = new Map();
 /** 会话 → 最近一次解析的作品键（不带参数手敲指令时的兜底） */
 const lastBySession = new Map();
+/**
+ * 回调按钮的「已经点过了」记录：`${作品键}|${种类}` → 谁点的、什么时候。
+ *
+ * ## 为什么需要它（用户要求）
+ *
+ * 「提取封面图 / 提取评论区图片」是 **QQ 原生回调按钮**：点一下就把载荷回调给机器人，
+ * QQ 那边不会记住「已经点过」，**按钮一直可以点**。于是有人会一直点，
+ * 群里就被同一张图刷屏（用户原话：「最多只能触发一次，不然点一直点，不知道谁在刷屏」）。
+ *
+ * 所以这里记一笔：**同一张卡片上的同一个按钮只放行一次**，后面的点击静默忽略、只记日志。
+ *   - 作用域是「作品 + 种类」，不是「人」：封面和评论区是两个按钮，互不影响；
+ *   - **重新解析会重新武装**：新卡片发出去时会 {@link rememberCardImages}（顺便清掉旧记录），
+ *     所以「想再要一次」只要重发链接，不会被永久锁死；
+ *   - 手敲指令（`kkk封面 bilibili:BV…`）**不走这里**，随时都能用，留一条明确的路；
+ *   - 跟着 {@link TTL_MS} 一起过期：图都过期了，记录留着也没意义。
+ */
+const extracted = new Map();
+/** 记录键 */
+function extractedKeyOf(key, kind) {
+    return String(key ?? '') + '|' + kind;
+}
 /** 会话键 */
 function sessionKeyOf(e) {
     return String(e?.contact?.peer ?? e?.channelId ?? '');
@@ -34,12 +58,19 @@ function sweep() {
         if (now - item.at > TTL_MS)
             store.delete(key);
     }
+    for (const [key, item] of extracted) {
+        if (now - item.at > TTL_MS)
+            extracted.delete(key);
+    }
 }
 /**
  * 记下本次解析的图。
  *
  * **只补传进来的那几项**：详情页发完先记封面，评论渲染完再补评论区，
  * 后一次调用不会把前一次记的封面抹掉。
+ *
+ * 顺带**重新武装**这次记的那几种图对应的按钮：新卡片要发出去了，
+ * 它下面的按钮应该可以再点一次（旧卡片上的那次点击不作数）。
  * @param key {@link cardImageKeyOf}
  * @param patch 要记录的内容
  */
@@ -50,14 +81,56 @@ function rememberCardImages(key, patch) {
     const prev = store.get(key);
     const next = prev ?? { key, at: Date.now() };
     next.at = Date.now();
-    if (patch.cover)
+    if (patch.cover) {
         next.cover = patch.cover;
-    if (patch.comment?.length)
+        extracted.delete(extractedKeyOf(key, 'cover'));
+    }
+    if (patch.comment?.length) {
         next.comment = patch.comment;
-    if (patch.commentPics?.length)
+        extracted.delete(extractedKeyOf(key, 'comment'));
+    }
+    if (patch.commentPics?.length) {
         next.commentPics = patch.commentPics;
+        extracted.delete(extractedKeyOf(key, 'comment'));
+    }
     store.set(key, next);
 }
+/**
+ * 占一次「卡片按钮已经点过了」。**只有 QQ 回调按钮走这里**（手敲指令不调）。
+ *
+ * 先占后发、发失败再 {@link releaseCardImageExtract}：
+ * 反过来「先发成功再记」的话，快速连点会有几次同时通过检查，照样能刷出好几条。
+ * @param key 作品键（{@link cardImageKeyOf}）
+ * @param kind 封面还是评论区
+ * @param by 点击者（用于日志里认出「谁在刷屏」）
+ * @returns 第一次点返回 `true`（放行）；之前已经点过返回 `false`
+ */
+function claimCardImageExtract(key, kind, by) {
+    if (!key)
+        return true;
+    sweep();
+    const id = extractedKeyOf(key, kind);
+    if (extracted.has(id))
+        return false;
+    extracted.set(id, { at: Date.now(), by: String(by ?? '') });
+    return true;
+}
+/** 撤销一次占用（这次没发出去 —— 过期、没图、发送报错 —— 不该算「点过了」） */
+function releaseCardImageExtract(key, kind) {
+    if (!key)
+        return;
+    extracted.delete(extractedKeyOf(key, kind));
+}
+/**
+ * 这个按钮是不是已经点过了（日志用：带上是谁点的）。
+ * @param key 作品键
+ * @param kind 封面还是评论区
+ */
+function recallCardImageExtract(key, kind) {
+    if (!key)
+        return undefined;
+    return extracted.get(extractedKeyOf(key, kind));
+}
 /**
  * 记下「这个会话最近解析的是哪个作品」。
  * 用户手敲 `kkk封面`（不带参数）时用它兜底 —— 按钮自己是带参数的，不走这条路。

package/lib/karin/platform/bilibili/bilibili.js

@@ -344,9 +344,7 @@ class Bilibili extends utils_1.Base {
                         const img = await (0, utils_1.Render)(this.e, 'bilibili/videoInfo', {
                             share_url: 'https://b23.tv/' + infoData.data.data.bvid,
                             title: infoData.data.data.title,
-                            desc: infoData.data.data.desc_v2?.length
-                                ? (0, dynamic_text_1.buildBilibiliVideoDescRichText)(infoData.data.data.desc_v2)
-                                : (0, dynamic_text_1.buildBilibiliDynamicRichText)(infoData.data.data.desc || '', []),
+                            desc: (0, dynamic_text_1.buildVideoDescRichText)(infoData.data.data.desc_v2, infoData.data.data.desc),
                             stat: infoData.data.data.stat,
                             bvid: infoData.data.data.bvid,
                             ctime: infoData.data.data.ctime,
@@ -1187,9 +1185,7 @@ class Bilibili extends utils_1.Base {
                             img = await (0, utils_1.Render)(this.e, 'bilibili/dynamic/DYNAMIC_TYPE_AV', {
                                 image_url: INFODATA.data.data.pic,
                                 text: (0, dynamic_text_1.buildBilibiliDynamicRichText)(INFODATA.data.data.title, []),
-                                desc: INFODATA.data.data.desc_v2?.length
-                                    ? (0, dynamic_text_1.buildBilibiliVideoDescRichText)(INFODATA.data.data.desc_v2)
-                                    : (0, dynamic_text_1.buildBilibiliDynamicRichText)(INFODATA.data.data.desc || '', []),
+                                desc: (0, dynamic_text_1.buildVideoDescRichText)(INFODATA.data.data.desc_v2, INFODATA.data.data.desc),
                                 dynamic_text: dynamicText,
                                 dianzan: (0, utils_1.Count)(INFODATA.data.data.stat.like),
                                 pinglun: (0, utils_1.Count)(INFODATA.data.data.stat.reply),

package/lib/karin/platform/bilibili/dynamic-text.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildBilibiliRichTextForwardMessage = exports.buildBilibiliArticleRichText = exports.buildBilibiliVideoDescRichText = exports.buildBilibiliDynamicRichText = exports.buildUsernameRichText = exports.getUsernameMetadata = void 0;
+exports.buildBilibiliRichTextForwardMessage = exports.buildBilibiliArticleRichText = exports.buildVideoDescRichText = exports.buildBilibiliVideoDescRichText = exports.buildBilibiliDynamicRichText = exports.buildUsernameRichText = exports.getUsernameMetadata = void 0;
 const richtext_1 = require("../../../richtext");
 const node_karin_1 = require("../../../compat/node-karin.js");
 /**
@@ -201,9 +201,17 @@ exports.buildBilibiliDynamicRichText = buildBilibiliDynamicRichText;
  * desc_v2 结构：
  * - type: 1 → 纯文本（含换行、链接）
  * - type: 2 → @提及（biz_id 为用户ID）
+ *
+ * **入参可能是 `null`/`undefined`**（接口在某些情况下就是这么给的，amagi 自己的类型里
+ * 也写着 `desc_v2: null`），这里必须容错 —— 直接 `for…of` 会抛 `descV2 is not iterable`。
+ * 一般不要直接调它，用 {@link buildVideoDescRichText}，它会把 `desc` 兜底也算进去。
+ *
+ * @param descV2 接口给的 desc_v2（可为空）
  */
 const buildBilibiliVideoDescRichText = (descV2) => {
     const nodes = [];
+    if (!descV2)
+        return (0, richtext_1.createRichTextDocument)(nodes, { platform: 'bilibili' });
     for (const item of descV2) {
         const rawText = item.raw_text || '';
         if (!rawText)
@@ -232,6 +240,46 @@ const buildBilibiliVideoDescRichText = (descV2) => {
     return (0, richtext_1.createRichTextDocument)(nodes, { platform: 'bilibili' });
 };
 exports.buildBilibiliVideoDescRichText = buildBilibiliVideoDescRichText;
+/**
+ * 视频详情的简介 → 富文本（**卡片该用这个，不要自己在调用处写三元**）。
+ *
+ * ## 为什么要有它
+ *
+ * 各调用点以前是这么写的：
+ *
+ * ```ts
+ * desc: data.desc_v2?.length
+ *   ? buildBilibiliVideoDescRichText(data.desc_v2)
+ *   : buildBilibiliDynamicRichText(data.desc || '', [])
+ * ```
+ *
+ * 看着没问题，但 `desc_v2` **不保证是「非空数组」** —— 接口至少有两种给不出内容的形态：
+ *
+ * - **`null`**：amagi 自己的类型里就有一支专职写着 `desc_v2: null`；
+ * - **`[{ raw_text: '', type: 1 }]`**：数组长度是 1，但里面一个字都没有。
+ *
+ * 前者 `?.length` 是 `undefined`、后者 `?.length` 是 1，判断结果不同，
+ * 但**都不能产生可显示的简介** —— 于是交给模板的都是空文档，
+ * 而卡片模板里写的是 `props.data.desc &&`，空文档为假 ⇒ **整块简介不渲染**，
+ * 而 `desc` 纯文本里明明有内容。用户反馈的「封面卡片没有简介」就是这个。
+ *
+ * 这个函数把口径收在一处，按**能不能产出内容**判断，而不是按长度：
+ *   - `desc_v2` 能产出非空文档 → 用它（带 @ 提及、富文本样式）；
+ *   - 否则 → 用 `desc` 纯文本兜底（**关键：desc_v2 为空时不能把 desc 也一起丢掉**）；
+ *   - 两个都没有 → 返回**合法的空文档**（`nodes: []`），模板判假后自然不显示，
+ *     不会抛错、也不会渲染出 `undefined` 字样。
+ *
+ * @param descV2 接口给的 desc_v2（数组 / null / undefined / 空内容数组都可能）
+ * @param desc 接口给的 desc 纯文本（兜底用）
+ */
+const buildVideoDescRichText = (descV2, desc) => {
+    const fromV2 = (0, exports.buildBilibiliVideoDescRichText)(descV2);
+    /** 真的产出了内容才用它：空数组、全空串、null 都会走到 desc 兜底 */
+    if (fromV2.nodes.length > 0)
+        return fromV2;
+    return (0, exports.buildBilibiliDynamicRichText)(desc || '', []);
+};
+exports.buildVideoDescRichText = buildVideoDescRichText;
 /** 修复图片 URL 协议。 */
 const fixImageUrl = (url) => {
     if (url.startsWith('//')) {

package/lib/karin/platform/bilibili/push.js

@@ -420,9 +420,7 @@ class Bilibilipush extends module_1.Base {
                             img = await (0, module_1.Render)(this.e, 'bilibili/dynamic/DYNAMIC_TYPE_AV', {
                                 image_url: INFODATA.data.data.pic,
                                 text: (0, dynamic_text_1.buildBilibiliDynamicRichText)(INFODATA.data.data.title, []),
-                                desc: INFODATA.data.data.desc_v2?.length
-                                    ? (0, dynamic_text_1.buildBilibiliVideoDescRichText)(INFODATA.data.data.desc_v2)
-                                    : (0, dynamic_text_1.buildBilibiliDynamicRichText)(INFODATA.data.data.desc || '', []),
+                                desc: (0, dynamic_text_1.buildVideoDescRichText)(INFODATA.data.data.desc_v2, INFODATA.data.data.desc),
                                 dynamic_text: dynamicText,
                                 dianzan: (0, module_1.Count)(INFODATA.data.data.stat.like),
                                 pinglun: (0, module_1.Count)(INFODATA.data.data.stat.reply),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-kkk",
-  "version": "3.11.1",
+  "version": "3.12.1",
   "description": "抖音 / B站 / 快手 / 小红书 视频解析与动态推送，带 QQ 交互面板与弹幕烧录（karin-plugin-kkk 的 Koishi 移植版）",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

package/scripts/probe-bili-desc.cjs

@@ -0,0 +1,218 @@
+/**
+ * 探针：B站视频卡片里**简介到底有没有渲染出来**。
+ *
+ * 用户反馈：「b站的视频解析封面卡片渲染的内容没有简介」。
+ *
+ * 这一版不用截图（截图要浏览器渲染器，只有宿主里才有），直接用 **SSR 产物 HTML**：
+ * `renderTemplateHtml` 是「模板组件 → HTML 字符串」那一步，不需要浏览器。
+ * 于是可以精确问三个问题：
+ *   ① 数据里 `desc` 是空的时候，HTML 长什么样（基线）；
+ *   ② `desc` 是正常富文本时，简介的原文**有没有出现在 HTML 里**；
+ *   ③ 两次 HTML 的长度差有多大 —— 简介整段文字 + 换行都进去的话，差值是**几千字符级**，
+ *      只差几十字符就说明「有内容但没渲染」。
+ *
+ * 用法：node scripts/probe-bili-desc.cjs
+ */
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const root = path.join(__dirname, '..')
+const lib = path.join(root, 'lib')
+
+const runtime = require(path.join(lib, 'compat/runtime.js'))
+runtime.bindRuntime({
+  ctx: { config: { port: 5200 } },
+  config: { app: {} },
+  dataRoot: fs.mkdtempSync(path.join(os.tmpdir(), 'kkk-probe-bili-desc-'))
+})
+
+require(path.join(lib, 'compat/logger.js')).setLogger({
+  debug () {}, info () {}, mark () {},
+  warn: (m) => console.log('  [warn] ' + m),
+  error: (m) => console.log('  [error] ' + m)
+})
+
+const Config = require(path.join(lib, 'karin/module/utils/Config.js'))
+Config.Config = {
+  app: { EmojiReply: false, RenderWaitTime: 10, renderScale: 2, noiseOverlay: 'off' },
+  amagi: { cookies: {} },
+  bilibili: {},
+  douyin: {}
+}
+
+const render = require(path.join(lib, 'karin/module/utils/Render/index.js'))
+const rich = require(path.join(lib, 'richtext/parse/index.js'))
+const dynamicText = require(path.join(lib, 'karin/platform/bilibili/dynamic-text.js'))
+
+let failed = 0
+const check = (name, ok, detail) => {
+  console.log((ok ? '  ✔ ' : '  ✘ ') + name + (detail ? '  → ' + detail : ''))
+  if (!ok) failed++
+}
+
+/** 一段「像真的」的 B 站简介：多行 + 时间轴 + 链接，跟真实投稿一个形状 */
+const DESC_LINES = [
+  '本期视频带大家看一下这个方案的完整实现，代码已经开源，链接放在下面。',
+  '',
+  '00:00 开场',
+  '01:20 环境准备',
+  '05:40 核心逻辑',
+  '12:00 踩坑记录',
+  '',
+  '参考资料：https://www.bilibili.com/read/cv12345678',
+  '',
+  '感谢大家的支持，记得三连 ~'
+]
+const DESC_TEXT = DESC_LINES.join('\n')
+/** 只取一段不含 URL、不含 @ 的普通文字当「海报标记」，避免被链接/表情的处理干扰 */
+const MARKER = '本期视频带大家看一下这个方案的完整实现'
+
+const descDoc = dynamicText.buildBilibiliVideoDescRichText([{ raw_text: DESC_TEXT, type: 1 }])
+
+const baseData = (desc) => ({
+  share_url: 'https://b23.tv/BV1JSan6GEFW',
+  title: '【实拍】这个方案到底能不能跑起来？完整实现 + 踩坑记录',
+  desc,
+  stat: { view: 1234567, danmaku: 8901, reply: 2345, like: 98765, coin: 12345, share: 678, favorite: 23456 },
+  bvid: 'BV1JSan6GEFW',
+  ctime: 1735689600,
+  pic: 'https://i0.hdslb.com/bfs/archive/0000000000000000000000000000000000000000.jpg',
+  owner: { mid: 123456, name: '测试UP主', face: 'https://i0.hdslb.com/bfs/face/0000000000000000000000000000000000000000.jpg' }
+})
+
+/** html 里出现 desc 区域才算「渲染了简介」：找渲染后的可见文本片段 */
+const countOccurrences = (haystack, needle) => haystack.split(needle).length - 1
+
+;(async () => {
+  try {
+    console.log('\n=== 1. desc 构建链路（纯函数，先确认数据没问题） ===')
+    {
+      const plain = rich.extractRichTextPlainText(descDoc)
+      console.log('  富文本节点数 = ' + descDoc.nodes.length + ' | 纯文本长度 = ' + plain.length)
+      check('简介文本完整进了富文本文档', plain.includes(MARKER), JSON.stringify(plain.slice(0, 30)))
+      check('换行被转成 lineBreak 节点（多行简介要靠它）', descDoc.nodes.some((n) => n.type === 'lineBreak'),
+        '节点类型：' + [...new Set(descDoc.nodes.map((n) => n.type))].join(','))
+    }
+
+    console.log('\n=== 2. SSR 对照：带简介 vs 不带简介 ===')
+    const htmlWith = await render.renderTemplateHtml('bilibili/videoInfo', baseData(descDoc), false)
+    const htmlWithout = await render.renderTemplateHtml(
+      'bilibili/videoInfo',
+      baseData(rich.createRichTextDocument([], { platform: 'bilibili' })),
+      false
+    )
+
+    check('两侧 SSR 都成功（模板与校验通过）', !!htmlWith && !!htmlWithout,
+      'with=' + (htmlWith ? htmlWith.length : 'null') + ' without=' + (htmlWithout ? htmlWithout.length : 'null'))
+
+    if (htmlWith && htmlWithout) {
+      const inWith = countOccurrences(htmlWith, MARKER)
+      const inWithout = countOccurrences(htmlWithout, MARKER)
+      console.log('  简介首句在 HTML 里出现次数：带简介 = ' + inWith + ' / 不带简介 = ' + inWithout)
+      check('带简介 → 简介原文出现在卡片 HTML 里', inWith > 0, '出现 ' + inWith + ' 次')
+      check('不带简介 → 简介原文不出现（对照成立）', inWithout === 0, '出现 ' + inWithout + ' 次')
+
+      /** 时间轴、链接这些也验一下：它们走的是另外的分支（split 换行 / URL 识别） */
+      check('时间轴行渲染进去了', htmlWith.includes('05:40 核心逻辑'))
+      check('简介里的链接被渲染成可点的 a 标签', /<a[^>]*href="https:\/\/www\.bilibili\.com\/read\/cv12345678"/.test(htmlWith))
+
+      const delta = htmlWith.length - htmlWithout.length
+      console.log('  两次 HTML 长度：' + htmlWith.length + ' vs ' + htmlWithout.length + '（差 ' + delta + ' 字符）')
+      check('长度差是「整段简介」的量级（不是几十字符）', delta > DESC_TEXT.length, '差 ' + delta + ' 字符，简介本体 ' + DESC_TEXT.length + ' 字符')
+
+      /** 存一份给人工看（了解实际排版） */
+      const out = path.join(root, 'bili-desc-probe.html')
+      fs.writeFileSync(out, htmlWith, 'utf8')
+      console.log('  已写出 SSR HTML：' + path.relative(root, out) + '（可直接用浏览器打开看排版）')
+    }
+
+    console.log('\n=== 3. ✅ 回归：desc_v2 为 null 时简介不能凭空消失 ===')
+    {
+      /**
+       * **本次的真凶**：`data.desc_v2?.length` 只在 desc_v2 是**数组**时才对，
+       * 而接口在某些情况下给的是 `desc_v2: null`（amagi 自己的类型里就有这一支：
+       * `type Arc = { desc: string; desc_v2: null }`）。
+       * 于是判断为假 → 走 desc 兜底那一支……实际并没有：三元的两个分支都指望
+       * `desc_v2` 是数组，最后交给模板的是一个**空文档**，
+       * 卡片模板里 `props.data.desc &&` 直接为假 ⇒ **整块简介都不渲染**，
+       * 而 `desc`（纯文本）明明有内容 —— 用户看到的就是「封面卡片没有简介」。
+       *
+       * 这里**直接测产物里的 `buildVideoDescRichText`**（新的统一口径），
+       * 而不是在探针里重写一遍逻辑 —— 重写的话实现改坏了它也测不出来。
+       */
+      const buildDesc = dynamicText.buildVideoDescRichText
+      check('产物里有 buildVideoDescRichText（三处调用点都用它）', typeof buildDesc === 'function',
+        typeof buildDesc)
+
+      const plainDesc = '掉宝时间：北京时间 2026年9月29日15:00 -10月15日14:59'
+
+      /** ① 正常：desc_v2 有内容 */
+      const normal = rich.extractRichTextPlainText(buildDesc([{ raw_text: plainDesc, type: 1 }], plainDesc))
+      check('desc_v2 正常 → 用 desc_v2', normal.includes('掉宝时间'), JSON.stringify(normal.slice(0, 24)))
+
+      /** ② 真凶场景：desc_v2 是 null，desc 有内容 */
+      const nullPlain = rich.extractRichTextPlainText(buildDesc(null, plainDesc))
+      check('desc_v2 = null → 用 desc 兜底（不再丢简介）', nullPlain.includes('掉宝时间'),
+        nullPlain ? JSON.stringify(nullPlain.slice(0, 24)) : '(空 —— 简介丢了)')
+
+      /** ③ desc_v2 缺失（undefined）也一样 */
+      check('desc_v2 缺失 → 同样用 desc 兜底',
+        rich.extractRichTextPlainText(buildDesc(undefined, plainDesc)).includes('掉宝时间'))
+
+      /** ④ desc_v2 空数组（接口偶尔给空数组） */
+      check('desc_v2 空数组 → 还是用 desc 兜底',
+        rich.extractRichTextPlainText(buildDesc([], plainDesc)).includes('掉宝时间'))
+
+      /** ⑤ desc_v2 是「有元素但元素都是空文本」：没有可用内容，也该退回 desc */
+      check('desc_v2 全是空串 → 退回 desc 兜底',
+        rich.extractRichTextPlainText(buildDesc([{ raw_text: '', type: 1 }], plainDesc)).includes('掉宝时间'))
+
+      /** ⑥ 两个都空：不能抛错，且必须是合法的空文档（模板要能吃） */
+      let bothEmpty
+      try {
+        bothEmpty = buildDesc(null, '')
+        check('两处都空 → 得到合法的空富文本文档', bothEmpty?.nodes?.length === 0,
+          'nodes=' + (bothEmpty?.nodes?.length ?? 'undefined'))
+      } catch (error) {
+        check('两处都空 → 不抛错', false, error.message)
+      }
+      /** ⑦ 老函数直接吃 null 也不能崩（别处还有人在调它） */
+      let oldCrash = false
+      try {
+        dynamicText.buildBilibiliVideoDescRichText(null)
+      } catch (error) {
+        oldCrash = true
+      }
+      check('buildBilibiliVideoDescRichText(null) 不再抛 descV2 is not iterable', !oldCrash)
+
+      /** ⑧ **端到端**：拿真凶数据走一遍 SSR，简介必须出现在 HTML 里 */
+      if (bothEmpty) {
+        const nullV2Html = await render.renderTemplateHtml('bilibili/videoInfo', baseData(buildDesc(null, plainDesc)), false)
+        check('desc_v2=null 的数据 → SSR 出来的卡片里真的有简介',
+          !!nullV2Html && nullV2Html.includes('掉宝时间'),
+          nullV2Html ? ('HTML ' + nullV2Html.length + ' 字符，含简介=' + nullV2Html.includes('掉宝时间')) : 'SSR 失败')
+      }
+    }
+
+    console.log('\n=== 4. 真实的 desc_v2 形状（从接口拿到的就是它） ===')
+    {
+      /** 接口里 desc_v2 的常见形状：多段，每段 type=1 纯文本 / type=2 @某人 */
+      const mixed = dynamicText.buildBilibiliVideoDescRichText([
+        { raw_text: '第一段简介\n', type: 1 },
+        { raw_text: '@某某UP', type: 2, biz_id: 999 },
+        { raw_text: '\n尾段 https://b23.tv/abc', type: 1 }
+      ])
+      const plain = rich.extractRichTextPlainText(mixed)
+      console.log('  混合 desc_v2 → ' + JSON.stringify(plain))
+      check('多段拼接后 @ 与链接都在', plain.includes('@某某UP') && plain.includes('https://b23.tv/abc'))
+    }
+
+    console.log('\n' + (failed ? '✘ 有 ' + failed + ' 项没通过' : '✔ 全部通过'))
+  } catch (error) {
+    console.error('探针自身出错:', error)
+    failed++
+  } finally {
+    process.exit(failed ? 1 : 0)
+  }
+})()

package/scripts/probe-extract-once.cjs

@@ -0,0 +1,317 @@
+/**
+ * 探针：「提取封面图 / 提取评论区图片」这两个**回调按钮最多只触发一次**。
+ *
+ * 用户原话：「提取图片的回调按钮最多只能触发一次，不然点一直点，不知道谁在刷屏」。
+ *
+ * QQ 的原生回调按钮（`action.type = 1`）是**发出去就收不回**的东西：QQ 那边不会记住
+ * 「这个按钮点过了」，所以只能由插件自己拦 —— 这里就把拦的那段（真 `handleExtractCard`）
+ * 跑起来，逐条验证：
+ *   ① 第一次点：正常出图；
+ *   ② 再点（同一个人 / 换个人）：**静默忽略**，群里不再多一条，日志里记下是谁在点；
+ *   ③ 封面按钮和评论按钮是两件事，互不影响；
+ *   ④ 换作品互不影响；
+ *   ⑤ **重新解析会重新武装**（新卡片发出来，按钮又能点一次）—— 不然就永久锁死了；
+ *   ⑥ **手敲指令不受限**（留一条明确的路，图发不出来时还能重试）；
+ *   ⑦ 这次没发出去（图过期 / 发送失败）**不算「点过了」**，再点还能成；
+ *   ⑧ 记录跟着缓存一起 15 分钟过期。
+ *
+ * 走的是**真产物**（`lib/karin/apps/tools.js` 里 `extractCardAPP` 的 handler），
+ * 只把「量图片尺寸」「把图片地址落地」这两步打桩 —— 那是网络活，与本次要验的逻辑无关。
+ * 不联网、不连 QQ、不碰用户配置、不写任何文件（dataRoot 用临时目录）。
+ *
+ * 用法：node scripts/probe-extract-once.cjs
+ */
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const lib = path.join(__dirname, '..', 'lib')
+
+/**
+ * **先把运行环境打桩，再 require 业务模块。**
+ *
+ * `Config` / `runtime` / `logger` 都是在业务模块 **import 期**就被读到的
+ * （比如 `tools.ts` 里 `priority: Config.app.videoTool ? …` 就是模块级表达式），
+ * 所以顺序不能反，否则整个 require 直接抛。
+ */
+const runtime = require(path.join(lib, 'compat/runtime.js'))
+runtime.bindRuntime({
+  ctx: { config: { port: 5200 } },
+  /**
+   * `errorNoCard: true` —— 出错只发文字、不渲染错误卡片。
+   * 第 7b 段会故意让发送失败，那时异常会流进错误处理器；不关掉卡片渲染的话
+   * 探针要凭空渲染一张几 MB 的大图（还要切片、发到几个账号），与本次要验的东西无关。
+   */
+  config: { app: {}, errorNoCard: true },
+  dataRoot: fs.mkdtempSync(path.join(os.tmpdir(), 'kkk-probe-extract-once-'))
+})
+
+/** 接住日志：要断言「谁在刷屏」真的被记下来了 */
+const marks = []
+const warns = []
+require(path.join(lib, 'compat/logger.js')).setLogger({
+  debug () {},
+  info: (message) => marks.push(String(message)),
+  warn: (message) => warns.push(String(message)),
+  error () {}
+})
+
+const Config = require(path.join(lib, 'karin/module/utils/Config.js'))
+Config.Config = {
+  /** EmojiReply 关掉：不然每次调用都会去尝试给消息加表情（探针里没有真 bot） */
+  app: { EmojiReply: false, videoTool: false, videoSendMode: 'url' },
+  amagi: { cookies: {} },
+  bilibili: {},
+  douyin: {},
+  kuaishou: {},
+  xiaohongshu: {}
+}
+
+const ImageHelper = require(path.join(lib, 'karin/module/utils/ImageHelper.js'))
+const QqPanel = require(path.join(lib, 'karin/module/utils/QqPanel.js'))
+const CardImageCache = require(path.join(lib, 'karin/module/utils/CardImageCache.js'))
+const tools = require(path.join(lib, 'karin/apps/tools.js'))
+
+/** 量尺寸那一步（会去下载图片）：换成固定串，断言里只关心「发了几次」 */
+QqPanel.buildMarkdownImageMessage = async (urls) =>
+  urls?.length ? { type: 'markdown', attrs: { content: urls.map((url) => '![cover](' + url + ')').join('\n') } } : undefined
+/** 把图片地址落地那一步（会去下载 / 转 base64）：原样返回 */
+ImageHelper.processImageUrls = async (urls) => urls
+
+/**
+ * 错误处理器也打桩。
+ *
+ * 第 7b 段要验「发送失败时不该占用额度」，那就必须真的让 `e.reply` 抛一次 ——
+ * 异常会流进 `wrapWithErrorHandler` 的错误分支。真实的错误处理会上报（联网）、
+ * 给主人 / 管理员发通知，探针里既没网也没账号，全打掉即可。
+ * （上面 `errorNoCard` 已经省掉了渲染那一步。）
+ */
+const errorReport = require(path.join(lib, 'karin/module/utils/ErrorReport.js'))
+errorReport.uploadErrorReport = async () => null
+const errorSender = require(path.join(lib, 'karin/module/utils/ErrorHandler/sender.js'))
+for (const name of ['sendErrorToTrigger', 'sendErrorToMaster', 'sendErrorToAllMasters', 'sendErrorToAdmins', 'sendErrorToConfiguredIds']) {
+  errorSender[name] = async () => {}
+}
+
+let failed = 0
+const check = (name, ok, detail) => {
+  console.log((ok ? '  ✔ ' : '  ✘ ') + name + (detail ? '  → ' + detail : ''))
+  if (!ok) failed++
+}
+/** 章节标题 */
+const section = (title) => console.log('\n=== ' + title + ' ===')
+
+/**
+ * 造一条假消息。
+ * @param opts.msg 指令原文（按钮回调的 data 拼上 `#` 后就是它）
+ * @param opts.button 是不是 QQ 回调按钮点出来的（决定 `session.type`）
+ * @param opts.userId 谁点的
+ * @param opts.peer 会话
+ */
+const makeMessage = (opts) => {
+  const replies = []
+  const e = {
+    msg: opts.msg,
+    userId: opts.userId ?? 'user-1',
+    selfId: 'self-1',
+    groupId: 'group-1',
+    isGroup: true,
+    isPrivate: false,
+    channelId: opts.peer ?? 'group-1',
+    contact: { peer: opts.peer ?? 'group-1', guildId: 'group-1', isGroup: true, userId: opts.userId ?? 'user-1' },
+    sender: { userId: opts.userId ?? 'user-1', nick: '触发者' },
+    messageId: 'msg-1',
+    /** 关键判据：回调按钮 = `interaction/button`，手敲 / 蓝字链 = `message` */
+    session: { type: opts.button ? 'interaction/button' : 'message' },
+    bot: { adapter: { name: 'adapter-qq-crack' } },
+    reply: async (content) => {
+      replies.push(content)
+      return [{ id: 'r' + replies.length }]
+    }
+  }
+  return { e, replies }
+}
+
+/** 发出去的东西是不是「图」（markdown 段里带了图片） */
+const hasImage = (content) => /!\[[^\]]*\]\([^)\s]+\)/.test(JSON.stringify(content ?? ''))
+
+/** 跑一次 handler（真产物里那个被 wrapWithErrorHandler 包过的） */
+const click = async (opts) => {
+  const { e, replies } = makeMessage(opts)
+  await tools.extractCardAPP.handler(e, () => undefined)
+  return replies
+}
+
+const COVER_KEY = CardImageCache.cardImageKeyOf('bilibili', 'BV1JSan6GEFW')
+const COMMENT_KEY = CardImageCache.cardImageKeyOf('douyin', '7123456789')
+const OTHER_KEY = CardImageCache.cardImageKeyOf('kuaishou', 'photo-9')
+
+const armCover = (key) => CardImageCache.rememberCardImages(key, { cover: 'https://cdn/' + key + '/cover.jpg' })
+const armComment = (key) => CardImageCache.rememberCardImages(key, { commentPics: ['https://cdn/' + key + '/c1.jpg'] })
+
+;(async () => {
+  try {
+    section('1. 第一次点：正常出图')
+    {
+      armCover(COVER_KEY)
+      const replies = await click({ msg: '#kkk封面 ' + COVER_KEY, button: true, userId: 'user-A' })
+      check('点一次 → 出图一条', replies.length === 1 && hasImage(replies[0]), '发送 ' + replies.length + ' 次')
+    }
+
+    section('2. 再点：静默忽略，不再刷屏')
+    {
+      /** 同一个人连点 */
+      const again = await click({ msg: '#kkk封面 ' + COVER_KEY, button: true, userId: 'user-A' })
+      check('同一个人再点 → 一条都不发', again.length === 0, '发送 ' + again.length + ' 次')
+      /** 换个人点，同样拦掉（拦的是「这张卡片这个按钮」，不是「这个人」） */
+      const other = await click({ msg: '#kkk封面 ' + COVER_KEY, button: true, userId: 'user-B' })
+      check('换个人点 → 也拦掉（群里就是同一张图，谁点都不再发）', other.length === 0, '发送 ' + other.length + ' 次')
+      const spam = marks.filter((line) => line.includes('重复点击'))
+      /** 前两次点击各产生一条：第一条说「user-A 又点了一次」，第二条说「user-B 也在点，但 user-A 已经点过了」 */
+      check(
+        '日志里记下了「谁在点」（这次点的 + 第一次点的都要有）',
+        spam.length === 2 && spam[1].includes('user-B') && spam[1].includes('user-A'),
+        spam[1] ?? '(没有这条日志)'
+      )
+    }
+
+    section('3. 封面 / 评论是两个按钮，互不影响')
+    {
+      armComment(COMMENT_KEY)
+      const comment = await click({ msg: '#kkk评论 ' + COMMENT_KEY, button: true, userId: 'user-B' })
+      check('评论区按钮照常能用（没被封面那次点击带累）', comment.length === 1 && hasImage(comment[0]), '发送 ' + comment.length + ' 次')
+      const commentAgain = await click({ msg: '#kkk评论 ' + COMMENT_KEY, button: true, userId: 'user-C' })
+      check('评论按钮自己也只能点一次', commentAgain.length === 0, '发送 ' + commentAgain.length + ' 次')
+    }
+
+    section('4. 换作品互不影响')
+    {
+      armCover(OTHER_KEY)
+      const card2 = await click({ msg: '#kkk封面 ' + OTHER_KEY, button: true, userId: 'user-A' })
+      check('另一个作品的封面按钮可以点', card2.length === 1 && hasImage(card2[0]), '发送 ' + card2.length + ' 次')
+      const u1 = await click({ msg: '#kkk评论 ' + COMMENT_KEY, button: true, userId: 'user-A' }) // 评论那条还是 user-B 点过
+      check('缓存里两件作品各记各的，不会串', u1.length === 0, '发送 ' + u1.length + ' 次')
+    }
+
+    section('5. 重新发一次链接（新卡片）→ 按钮重新可用')
+    {
+      /** 同一个作品又解析了一遍：`rememberCardImages` 会顺手清掉「点过了」记录 */
+      armCover(COVER_KEY)
+      const reArmed = await click({ msg: '#kkk封面 ' + COVER_KEY, button: true, userId: 'user-C' })
+      check('新卡片下面的按钮又能点一次（不会被永久锁死）', reArmed.length === 1 && hasImage(reArmed[0]), '发送 ' + reArmed.length + ' 次')
+      const third = await click({ msg: '#kkk封面 ' + COVER_KEY, button: true, userId: 'user-C' })
+      check('新卡片上也只放行一次', third.length === 0, '发送 ' + third.length + ' 次')
+    }
+
+    section('6. 手敲指令不受限（留一条明确的路）')
+    {
+      /** 上一步刚被 user-C 点过，这里手敲两次都该出图 */
+      /** 先记下水线：只检查「手敲这一段」有没有新写日志（上面按钮那几段的日志不能算进来） */
+      const before = marks.length
+      const typed1 = await click({ msg: 'kkk封面 ' + COVER_KEY, button: false, userId: 'user-D' })
+      const typed2 = await click({ msg: 'kkk封面 ' + COVER_KEY, button: false, userId: 'user-D' })
+      check('手敲（不是按钮）→ 两次都出图', typed1.length === 1 && typed2.length === 1 && hasImage(typed2[0]), typed1.length + ' / ' + typed2.length)
+      check('手敲不会往「谁在刷屏」日志里写东西', !marks.slice(before).some((line) => line.includes('重复点击')), marks.slice(before).join(' | ') || '(没有新日志)')
+      /** 旧 `#` 写法同样是「手敲」口径 */
+      const hashTyped = await click({ msg: '#kkk封面 ' + COVER_KEY, button: false, userId: 'user-D' })
+      check('旧 `#kkk封面` 写法也照常', hashTyped.length === 1, '发送 ' + hashTyped.length + ' 次')
+    }
+
+    section('7. 这次没发出去，不算「点过了」')
+    {
+      const emptyKey = CardImageCache.cardImageKeyOf('xiaohongshu', 'note-empty')
+      /** 缓存里什么都没有：按钮点了只会得到一句提示 */
+      const miss = await click({ msg: '#kkk封面 ' + emptyKey, button: true, userId: 'user-E' })
+      check('没图 → 回一句提示（不是图）', miss.length === 1 && !hasImage(miss[0]), '发送 ' + miss.length + ' 次')
+      /** 关键：这次不该占用掉额度 —— 等图有了再点必须能成 */
+      CardImageCache.rememberCardImages(emptyKey, { cover: 'https://cdn/k/cover.jpg' })
+      const retry = await click({ msg: '#kkk封面 ' + emptyKey, button: true, userId: 'user-E' })
+      check('图补上后再点 → 能出图（失败没占额度）', retry.length === 1 && hasImage(retry[0]), '发送 ' + retry.length + ' 次')
+    }
+    {
+      /** 过期的那条路：作品键在缓存里根本不存在（= 按钮没带参数、也没解析记录） */
+      const { e } = makeMessage({ msg: '#kkk封面', button: true, userId: 'user-F' })
+      e.contact.peer = 'group-elsewhere'
+      e.channelId = 'group-elsewhere'
+      const replies = []
+      e.reply = async (content) => { replies.push(content); return [{ id: 'x' }] }
+      await tools.extractCardAPP.handler(e, () => undefined)
+      check('作品键都拿不到 → 也是提示，不抛错', replies.length === 1 && !hasImage(replies[0]), '发送 ' + replies.length + ' 次')
+    }
+
+    {
+      /**
+       * **发送那一步报错时也不该占用额度。**
+       *
+       * 这条是真跑的：把 `e.reply` 换成抛错，异常会一路走到 `wrapWithErrorHandler`
+       * 的错误分支（错误上报 / 发通知已在上面的打桩里换成空实现）。
+       * 如果实现里漏了 `release`，下面那次重试就会被自己的「已点过」记录挡住 ——
+       * 群里表现成「这张卡片再也发不出图了」。
+       */
+      const failKey = CardImageCache.cardImageKeyOf('bilibili', 'BVfail')
+      armCover(failKey)
+      const { e } = makeMessage({ msg: '#kkk封面 ' + failKey, button: true, userId: 'user-Z' })
+      e.reply = async () => { throw new Error('模拟发送失败') }
+      let threw = false
+      try {
+        await tools.extractCardAPP.handler(e, () => undefined)
+      } catch {
+        threw = true
+      }
+      console.log('  · 发送抛错后 handler ' + (threw ? '把错误抛了出来（错误处理器没接住）' : '由错误处理器接住并返回'))
+      const retry = await click({ msg: '#kkk封面 ' + failKey, button: true, userId: 'user-Z' })
+      check('发送失败 → 不算「点过了」，再点一次还能出图', retry.length === 1 && hasImage(retry[0]), '发送 ' + retry.length + ' 次')
+      const afterRetry = await click({ msg: '#kkk封面 ' + failKey, button: true, userId: 'user-Z' })
+      check('重试成功之后才真正占用（第三次点被拦）', afterRetry.length === 0, '发送 ' + afterRetry.length + ' 次')
+    }
+
+    section('8. 记录跟着缓存一起过期（15 分钟）')
+    {
+      const ttlKey = CardImageCache.cardImageKeyOf('bilibili', 'BVttl')
+      armCover(ttlKey)
+      check('先占一次 → true', CardImageCache.claimCardImageExtract(ttlKey, 'cover', 'user-G') === true)
+      check('紧接着再占 → false（拦住了）', CardImageCache.claimCardImageExtract(ttlKey, 'cover', 'user-G') === false)
+      /** 把时间拨过 TTL：记录和缓存一起被 sweep 清掉 */
+      const realNow = Date.now
+      Date.now = () => realNow() + 16 * 60 * 1000
+      try {
+        check('过了 15 分钟 → 记录跟着过期，又能占了', CardImageCache.claimCardImageExtract(ttlKey, 'cover', 'user-H') === true)
+        check('同一时刻缓存也过期了', CardImageCache.recallCardImages(ttlKey) === undefined)
+      } finally {
+        Date.now = realNow
+      }
+    }
+
+    section('9. release / 隔离的最小口径')
+    {
+      const k = CardImageCache.cardImageKeyOf('bilibili', 'BVdirect')
+      CardImageCache.claimCardImageExtract(k, 'cover', 'u')
+      CardImageCache.releaseCardImageExtract(k, 'cover')
+      check('release 之后又能占（发送失败重试靠它）', CardImageCache.claimCardImageExtract(k, 'cover', 'u') === true)
+      check('release 只撤销自己那一种，不碰另一种', CardImageCache.claimCardImageExtract(k, 'comment', 'u') === true)
+      CardImageCache.releaseCardImageExtract(k, 'cover')
+      check('撤销封面后，评论那条记录还在', CardImageCache.recallCardImageExtract(k, 'comment')?.by === 'u')
+      check('空作品键不参与拦截（拿不到键时不该把所有点击都堵死）', CardImageCache.claimCardImageExtract('', 'cover', 'u') === true)
+    }
+
+    section('10. 源码守卫：只在「按钮」那条路上判一次')
+    {
+      /** 先剥注释再匹配 —— 注释里写到的函数名会把断言带偏（这个坑踩过两次） */
+      const stripComments = (source) => source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1')
+      const src = stripComments(fs.readFileSync(path.join(lib, 'karin/apps/tools.js'), 'utf8'))
+      check('判据是会话类型 `interaction/button`', /e\?\.session\?\.type[\s\S]{0,40}===\s*'interaction\/button'/.test(src))
+      check('只在 fromButton 为真时才占用', /if\s*\(\s*fromButton\s*&&\s*!\s*\(0,\s*CardImageCache_1\.claimCardImageExtract\)/.test(src))
+      check('claim 全文只出现一次（别处不许再判一遍）', (src.match(/claimCardImageExtract\)\(/g) ?? []).length === 1, String((src.match(/claimCardImageExtract\)\(/g) ?? []).length))
+      check('两条失败路都 release 了（没图 / 发送报错）', (src.match(/releaseCardImageExtract\)\(/g) ?? []).length === 2, String((src.match(/releaseCardImageExtract\)\(/g) ?? []).length))
+      const cacheSrc = stripComments(fs.readFileSync(path.join(lib, 'karin/module/utils/CardImageCache.js'), 'utf8'))
+      check('重新记图时会清掉旧记录（重新武装）', /extracted\.delete\(/.test(cacheSrc))
+    }
+
+    console.log('\n' + (failed ? '✘ 有 ' + failed + ' 项没通过' : '✔ 全部通过' + (warns.length ? '（warn ' + warns.length + ' 条）' : '')))
+  } catch (error) {
+    console.error('探针自身出错:', error)
+    failed++
+  } finally {
+    process.exit(failed ? 1 : 0)
+  }
+})()

package/scripts/verify-changelog-range.cjs

@@ -0,0 +1,45 @@
+/** 离线自验：CHANGELOG 的 `## x.y.z` 标题必须能被 range() 裁出来 */
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const root = 'E:/devkoishi/plugins/koishi-plugin-kkk'
+const lib = path.join(root, 'lib')
+
+const runtime = require(path.join(lib, 'compat/runtime.js'))
+runtime.bindRuntime({ ctx: { config: { port: 5200 } }, config: { app: {} }, dataRoot: os.tmpdir() })
+require(path.join(lib, 'compat/logger.js')).setLogger({ debug () {}, info () {}, warn () {}, error () {} })
+
+const karin = require(path.join(lib, 'compat/node-karin.js'))
+const md = fs.readFileSync(path.join(root, 'CHANGELOG.md'), 'utf8')
+
+console.log('解析出的版本：' + Object.keys(karin.parseChangelog(md)).join(' , '))
+
+/** 当前版本号（package.json）；CHANGELOG 顶部的 `## x.y.z` 必须是它，否则卡片会整份发出去 */
+const version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version
+const all = Object.keys(karin.parseChangelog(md))
+if (!all.includes(version)) {
+  console.log('❌ CHANGELOG 里没有 `## ' + version + '` 这一段（package.json 的版本号对不上）')
+  process.exitCode = 1
+} else {
+  console.log('✅ package.json 版本 ' + version + ' 在 CHANGELOG 里有对应段落')
+}
+
+/** 取当前版本以及它下面 3 个历史版本，逐个验证「上一版 → 这一版」能裁出东西 */
+const cases = []
+for (let i = 0; i < all.length; i++) {
+  cases.push([all[i + 1] ?? all[i], all[i]])
+}
+for (const [startVersion, endVersion] of cases) {
+  // 最老那一版的下界只能等于它自己（没有更老的版本可当哨兵），range() 此时必然返回整份，
+  // 属于工具本身的预期行为，不算失败。
+  if (startVersion === endVersion && endVersion === all[all.length - 1]) continue
+  const out = karin.range({ data: md, startVersion, endVersion, compare: 'semver' })
+  const keys = Object.keys(karin.parseChangelog(out))
+  const dumped = out.length >= md.length
+  console.log(
+    'range(' + startVersion + ' → ' + endVersion + ')：命中 [' + keys.join(', ') + ']  长度=' + out.length +
+    (dumped ? '  ⚠ 返回了整份日志（没裁出来）' : '')
+  )
+  if (dumped) process.exitCode = 1
+}

package/src/karin/apps/tools.ts

@@ -7,7 +7,14 @@ import {
 } from '@/module/utils/QqPanel'
 import { replyReplacing } from '@/module/utils/QqPanel'
 import { resolveCardToUrl } from '@/module/utils/CardParser'
-import { recallCardImages, resolveCardImageKey } from '@/module/utils/CardImageCache'
+import {
+  claimCardImageExtract,
+  recallCardImageExtract,
+  recallCardImages,
+  releaseCardImageExtract,
+  resolveCardImageKey,
+  type CardImageKind
+} from '@/module/utils/CardImageCache'
 import { processImageUrls } from '@/module/utils/ImageHelper'
 
 import { Common, downloadVideo } from '@/module'
@@ -658,6 +665,21 @@ const handleCardParse = wrapWithErrorHandler(
  */
 export const cardAPP = karin.command(/卡片消息/, handleCardParse, { name: 'kkk-卡片解析' })
 
+/**
+ * 这条指令是不是**QQ 回调按钮**点出来的。
+ *
+ * 判据是会话类型：回调按钮（`action.type = 1`）在适配器里被标成
+ * `session.type = 'interaction/button'`（见 `koishi-plugin-adapter-qq-crack` 的 `utils.ts`），
+ * 而手敲指令、以及不支持原生按钮时给的蓝字文字链（`<qqbot-cmd-input>`），
+ * 都会变成**普通消息**（`session.type = 'message'`）。
+ *
+ * 这个区别正是「限一次」的适用范围：**只有按钮才限一次**。
+ * 按钮用户看不见指令、也没法确认自己点没点过，所以由插件兜着；
+ * 手敲指令是用户主动发的，随时都能用，留一条明确的路（图发不出来时还能重试）。
+ * @param e 消息事件
+ */
+const isButtonClick = (e: any): boolean => String(e?.session?.type ?? '') === 'interaction/button'
+
 /**
  * 单独把卡片图发一遍（`kkk封面` / `kkk评论`）。
  *
@@ -667,6 +689,11 @@ export const cardAPP = karin.command(/卡片消息/, handleCardParse, { name: 'k
  *
  * **不重新解析、不重新渲染**：图源是上次解析记下来的（见 CardImageCache），
  * 15 分钟过期（评论图是临时文件，会被定时清理），过期了就提示先发条链接。
+ *
+ * **按钮只放行一次**（用户要求：有人一直点，群里被同一张图刷屏、还查不出是谁）：
+ * `interaction/button` 这条路上按「作品 + 按钮种类」先占后发，重复点击**静默忽略**、
+ * 只在日志里记下是谁在点。手敲指令不受此限；重新发一次链接（新卡片）
+ * 会 `rememberCardImages` 重新武装按钮。
  */
 const handleExtractCard = wrapWithErrorHandler(
   async (e, next) => {
@@ -680,7 +707,25 @@ const handleExtractCard = wrapWithErrorHandler(
      */
     const arg = msg.replace(/^#?(?:kkk封面|kkk评论|提取封面图|提取评论区图片)/, '').trim()
     const wantComment = /评论/.test(msg)
-    const cached = recallCardImages(resolveCardImageKey(e, arg))
+    const cardKey = resolveCardImageKey(e, arg)
+    const kind: CardImageKind = wantComment ? 'comment' : 'cover'
+    const label = wantComment ? '提取评论区图片' : '提取封面图'
+    /**
+     * **拦截重复点击。**「先占后发」而不是「发成功再记」：
+     * 反过来写的话，快速连点会有好几次同时通过检查，照样能刷出好几条。
+     */
+    const fromButton = isButtonClick(e)
+    if (fromButton && !claimCardImageExtract(cardKey, kind, String(e.userId ?? ''))) {
+      const prev = recallCardImageExtract(cardKey, kind)
+      logger.mark(
+        '[提取卡片图] 忽略一次重复点击：%s 点的「%s」，这张卡片上 %s 已经点过了（同一张卡片只放行一次，想再要一次就重新发链接）',
+        String(e.userId ?? '（未知用户）'),
+        label,
+        prev?.by ? String(prev.by) : '（未知用户）'
+      )
+      return
+    }
+    const cached = recallCardImages(cardKey)
     let urls: string[] | undefined
     if (wantComment) {
       /**
@@ -705,14 +750,22 @@ const handleExtractCard = wrapWithErrorHandler(
       urls = cached?.cover ? [cached.cover] : undefined
     }
     if (!urls?.length) {
+      /** 这次没发出去，不该算「点过了」——否则图一过期按钮就彻底废了 */
+      if (fromButton) releaseCardImageExtract(cardKey, kind)
       await e.reply(wantComment
         ? '没拿到这条内容的评论区图片 —— 评论里没有用户贴图，或者已经过期（15 分钟）／临时文件被清理了，重新发一下链接再点 ~'
         : '没找到这个作品的封面 —— 可能已经过期（15 分钟），重新发一下链接再点 ~')
       return
     }
     /** 图片统一走 markdown：QQ 上不会被二次压缩，小字才看得清（见 compat/imageMarkdown） */
-    const md = await buildMarkdownImageMessage(urls, 420, platformOf(e))
-    await e.reply(md ?? urls.map((url) => segment.image(url)))
+    try {
+      const md = await buildMarkdownImageMessage(urls, 420, platformOf(e))
+      await e.reply(md ?? urls.map((url) => segment.image(url)))
+    } catch (error) {
+      /** 发送失败同样不当「点过了」：用户再点一次还能拿到图 */
+      if (fromButton) releaseCardImageExtract(cardKey, kind)
+      throw error
+    }
     logger.debug('[提取卡片图] 已发送 %s 张（%s）', urls.length, wantComment ? '评论区' : '封面')
   },
   { businessName: '提取卡片图' }

package/src/karin/module/utils/CardImageCache.ts

@@ -45,11 +45,37 @@ export interface CardImages {
 /** 缓存有效期：评论图是临时文件，别放太久 */
 const TTL_MS = 15 * 60 * 1000
 
+/** 按钮种类：封面 / 评论区 */
+export type CardImageKind = 'cover' | 'comment'
+
 /** 作品 → 图 */
 const store = new Map<string, CardImages>()
 /** 会话 → 最近一次解析的作品键（不带参数手敲指令时的兜底） */
 const lastBySession = new Map<string, string>()
 
+/**
+ * 回调按钮的「已经点过了」记录：`${作品键}|${种类}` → 谁点的、什么时候。
+ *
+ * ## 为什么需要它（用户要求）
+ *
+ * 「提取封面图 / 提取评论区图片」是 **QQ 原生回调按钮**：点一下就把载荷回调给机器人，
+ * QQ 那边不会记住「已经点过」，**按钮一直可以点**。于是有人会一直点，
+ * 群里就被同一张图刷屏（用户原话：「最多只能触发一次，不然点一直点，不知道谁在刷屏」）。
+ *
+ * 所以这里记一笔：**同一张卡片上的同一个按钮只放行一次**，后面的点击静默忽略、只记日志。
+ *   - 作用域是「作品 + 种类」，不是「人」：封面和评论区是两个按钮，互不影响；
+ *   - **重新解析会重新武装**：新卡片发出去时会 {@link rememberCardImages}（顺便清掉旧记录），
+ *     所以「想再要一次」只要重发链接，不会被永久锁死；
+ *   - 手敲指令（`kkk封面 bilibili:BV…`）**不走这里**，随时都能用，留一条明确的路；
+ *   - 跟着 {@link TTL_MS} 一起过期：图都过期了，记录留着也没意义。
+ */
+const extracted = new Map<string, { at: number, by: string }>()
+
+/** 记录键 */
+function extractedKeyOf (key: string, kind: CardImageKind): string {
+  return String(key ?? '') + '|' + kind
+}
+
 /** 会话键 */
 function sessionKeyOf (e: any): string {
   return String(e?.contact?.peer ?? e?.channelId ?? '')
@@ -72,6 +98,9 @@ function sweep (): void {
   for (const [key, item] of store) {
     if (now - item.at > TTL_MS) store.delete(key)
   }
+  for (const [key, item] of extracted) {
+    if (now - item.at > TTL_MS) extracted.delete(key)
+  }
 }
 
 /**
@@ -79,6 +108,9 @@ function sweep (): void {
  *
  * **只补传进来的那几项**：详情页发完先记封面，评论渲染完再补评论区，
  * 后一次调用不会把前一次记的封面抹掉。
+ *
+ * 顺带**重新武装**这次记的那几种图对应的按钮：新卡片要发出去了，
+ * 它下面的按钮应该可以再点一次（旧卡片上的那次点击不作数）。
  * @param key {@link cardImageKeyOf}
  * @param patch 要记录的内容
  */
@@ -88,12 +120,56 @@ export function rememberCardImages (key: string, patch: { cover?: string, commen
   const prev = store.get(key)
   const next: CardImages = prev ?? { key, at: Date.now() }
   next.at = Date.now()
-  if (patch.cover) next.cover = patch.cover
-  if (patch.comment?.length) next.comment = patch.comment
-  if (patch.commentPics?.length) next.commentPics = patch.commentPics
+  if (patch.cover) {
+    next.cover = patch.cover
+    extracted.delete(extractedKeyOf(key, 'cover'))
+  }
+  if (patch.comment?.length) {
+    next.comment = patch.comment
+    extracted.delete(extractedKeyOf(key, 'comment'))
+  }
+  if (patch.commentPics?.length) {
+    next.commentPics = patch.commentPics
+    extracted.delete(extractedKeyOf(key, 'comment'))
+  }
   store.set(key, next)
 }
 
+/**
+ * 占一次「卡片按钮已经点过了」。**只有 QQ 回调按钮走这里**（手敲指令不调）。
+ *
+ * 先占后发、发失败再 {@link releaseCardImageExtract}：
+ * 反过来「先发成功再记」的话，快速连点会有几次同时通过检查，照样能刷出好几条。
+ * @param key 作品键（{@link cardImageKeyOf}）
+ * @param kind 封面还是评论区
+ * @param by 点击者（用于日志里认出「谁在刷屏」）
+ * @returns 第一次点返回 `true`（放行）；之前已经点过返回 `false`
+ */
+export function claimCardImageExtract (key: string, kind: CardImageKind, by: string): boolean {
+  if (!key) return true
+  sweep()
+  const id = extractedKeyOf(key, kind)
+  if (extracted.has(id)) return false
+  extracted.set(id, { at: Date.now(), by: String(by ?? '') })
+  return true
+}
+
+/** 撤销一次占用（这次没发出去 —— 过期、没图、发送报错 —— 不该算「点过了」） */
+export function releaseCardImageExtract (key: string, kind: CardImageKind): void {
+  if (!key) return
+  extracted.delete(extractedKeyOf(key, kind))
+}
+
+/**
+ * 这个按钮是不是已经点过了（日志用：带上是谁点的）。
+ * @param key 作品键
+ * @param kind 封面还是评论区
+ */
+export function recallCardImageExtract (key: string, kind: CardImageKind): { at: number, by: string } | undefined {
+  if (!key) return undefined
+  return extracted.get(extractedKeyOf(key, kind))
+}
+
 /**
  * 记下「这个会话最近解析的是哪个作品」。
  * 用户手敲 `kkk封面`（不带参数）时用它兜底 —— 按钮自己是带参数的，不走这条路。

package/src/karin/platform/bilibili/bilibili.ts

@@ -83,7 +83,7 @@ import {
   buildBilibiliArticleRichText,
   buildBilibiliDynamicRichText,
   buildBilibiliRichTextForwardMessage,
-  buildBilibiliVideoDescRichText,
+  buildVideoDescRichText,
   getUsernameMetadata
 } from '@/platform/bilibili/dynamic-text'
 import {
@@ -390,9 +390,7 @@ export class Bilibili extends Base {
             const img = await Render(this.e, 'bilibili/videoInfo', {
               share_url: 'https://b23.tv/' + infoData.data.data.bvid,
               title: infoData.data.data.title,
-              desc: infoData.data.data.desc_v2?.length
-                ? buildBilibiliVideoDescRichText(infoData.data.data.desc_v2)
-                : buildBilibiliDynamicRichText(infoData.data.data.desc || '', []),
+              desc: buildVideoDescRichText(infoData.data.data.desc_v2, infoData.data.data.desc),
               stat: infoData.data.data.stat,
               bvid: infoData.data.data.bvid,
               ctime: infoData.data.data.ctime,
@@ -1319,9 +1317,7 @@ export class Bilibili extends Base {
               img = await Render(this.e, 'bilibili/dynamic/DYNAMIC_TYPE_AV', {
                 image_url: INFODATA.data.data.pic,
                 text: buildBilibiliDynamicRichText(INFODATA.data.data.title, []),
-                desc: INFODATA.data.data.desc_v2?.length
-                  ? buildBilibiliVideoDescRichText(INFODATA.data.data.desc_v2)
-                  : buildBilibiliDynamicRichText(INFODATA.data.data.desc || '', []),
+                desc: buildVideoDescRichText(INFODATA.data.data.desc_v2, INFODATA.data.data.desc),
                 dynamic_text: dynamicText,
                 dianzan: Count(INFODATA.data.data.stat.like),
                 pinglun: Count(INFODATA.data.data.stat.reply),

package/src/karin/platform/bilibili/dynamic-text.ts

@@ -272,9 +272,16 @@ export const buildBilibiliDynamicRichText = (
  * desc_v2 结构：
  * - type: 1 → 纯文本（含换行、链接）
  * - type: 2 → @提及（biz_id 为用户ID）
+ *
+ * **入参可能是 `null`/`undefined`**（接口在某些情况下就是这么给的，amagi 自己的类型里
+ * 也写着 `desc_v2: null`），这里必须容错 —— 直接 `for…of` 会抛 `descV2 is not iterable`。
+ * 一般不要直接调它，用 {@link buildVideoDescRichText}，它会把 `desc` 兜底也算进去。
+ *
+ * @param descV2 接口给的 desc_v2（可为空）
  */
-export const buildBilibiliVideoDescRichText = (descV2: Array<{ raw_text?: string; type?: number; biz_id?: number }>): RichTextDocument => {
+export const buildBilibiliVideoDescRichText = (descV2: Array<{ raw_text?: string; type?: number; biz_id?: number }> | null | undefined): RichTextDocument => {
   const nodes: RichTextNode[] = []
+  if (!descV2) return createRichTextDocument(nodes, { platform: 'bilibili' })
   for (const item of descV2) {
     const rawText = item.raw_text || ''
     if (!rawText) continue
@@ -301,6 +308,48 @@ export const buildBilibiliVideoDescRichText = (descV2: Array<{ raw_text?: string
   return createRichTextDocument(nodes, { platform: 'bilibili' })
 }
 
+/**
+ * 视频详情的简介 → 富文本（**卡片该用这个，不要自己在调用处写三元**）。
+ *
+ * ## 为什么要有它
+ *
+ * 各调用点以前是这么写的：
+ *
+ * ```ts
+ * desc: data.desc_v2?.length
+ *   ? buildBilibiliVideoDescRichText(data.desc_v2)
+ *   : buildBilibiliDynamicRichText(data.desc || '', [])
+ * ```
+ *
+ * 看着没问题，但 `desc_v2` **不保证是「非空数组」** —— 接口至少有两种给不出内容的形态：
+ *
+ * - **`null`**：amagi 自己的类型里就有一支专职写着 `desc_v2: null`；
+ * - **`[{ raw_text: '', type: 1 }]`**：数组长度是 1，但里面一个字都没有。
+ *
+ * 前者 `?.length` 是 `undefined`、后者 `?.length` 是 1，判断结果不同，
+ * 但**都不能产生可显示的简介** —— 于是交给模板的都是空文档，
+ * 而卡片模板里写的是 `props.data.desc &&`，空文档为假 ⇒ **整块简介不渲染**，
+ * 而 `desc` 纯文本里明明有内容。用户反馈的「封面卡片没有简介」就是这个。
+ *
+ * 这个函数把口径收在一处，按**能不能产出内容**判断，而不是按长度：
+ *   - `desc_v2` 能产出非空文档 → 用它（带 @ 提及、富文本样式）；
+ *   - 否则 → 用 `desc` 纯文本兜底（**关键：desc_v2 为空时不能把 desc 也一起丢掉**）；
+ *   - 两个都没有 → 返回**合法的空文档**（`nodes: []`），模板判假后自然不显示，
+ *     不会抛错、也不会渲染出 `undefined` 字样。
+ *
+ * @param descV2 接口给的 desc_v2（数组 / null / undefined / 空内容数组都可能）
+ * @param desc 接口给的 desc 纯文本（兜底用）
+ */
+export const buildVideoDescRichText = (
+  descV2: Array<{ raw_text?: string; type?: number; biz_id?: number }> | null | undefined,
+  desc: string | null | undefined
+): RichTextDocument => {
+  const fromV2 = buildBilibiliVideoDescRichText(descV2)
+  /** 真的产出了内容才用它：空数组、全空串、null 都会走到 desc 兜底 */
+  if (fromV2.nodes.length > 0) return fromV2
+  return buildBilibiliDynamicRichText(desc || '', [])
+}
+
 /** 修复图片 URL 协议。 */
 const fixImageUrl = (url: string): string => {
   if (url.startsWith('//')) {

package/src/karin/platform/bilibili/push.ts

@@ -40,7 +40,7 @@ import {
   buildBilibiliArticleRichText,
   buildBilibiliDynamicRichText,
   buildBilibiliRichTextForwardMessage,
-  buildBilibiliVideoDescRichText,
+  buildVideoDescRichText,
   getUsernameMetadata
 } from '@/platform/bilibili/dynamic-text'
 import { buildBilibiliLiveSessionId, parseBilibiliLiveStartedAt } from '@/platform/bilibili/live-status'
@@ -516,9 +516,7 @@ export class Bilibilipush extends Base {
               img = await Render(this.e, 'bilibili/dynamic/DYNAMIC_TYPE_AV', {
                 image_url: INFODATA.data.data.pic,
                 text: buildBilibiliDynamicRichText(INFODATA.data.data.title, []),
-                desc: INFODATA.data.data.desc_v2?.length
-                  ? buildBilibiliVideoDescRichText(INFODATA.data.data.desc_v2)
-                  : buildBilibiliDynamicRichText(INFODATA.data.data.desc || '', []),
+                desc: buildVideoDescRichText(INFODATA.data.data.desc_v2, INFODATA.data.data.desc),
                 dynamic_text: dynamicText,
                 dianzan: Count(INFODATA.data.data.stat.like),
                 pinglun: Count(INFODATA.data.data.stat.reply),