koishi-plugin-kkk 3.12.0 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 更新日志
 
+## 3.12.1
+
+### 修：B站卡片的简介没了
+
+有一批 B 站视频解析出来的卡片，标题下面直接跳到播放数据，**视频简介整块不见了**。
+不是渲染糊了，是压根没画上去。
+
+原因是 B 站接口有时会把简介放在「分段简介」里、有时只放在普通简介字段里，
+之前的代码碰上第一种情况以外的数据会算出一份空简介，然后把「空的」当成「有内容」画出来，
+结果整块简介反而被吃掉了。
+
+现在两个字段都试，哪个真的有内容就用哪个 —— 单行简介、多行简介、带 @ 和链接的简介
+都能正常显示出来。
+
+顺手还修了一处：接口返回的简介字段是空的时候不会再让解析报错。
+
 ## 3.12.0
 
 ### 新：提取图片的按钮只能点一次

package/lib/build-metadata.json

@@ -1,10 +1,10 @@
 {
-  "version": "3.12.0",
-  "buildTime": "2026-10-01T15:04:46.055Z",
-  "buildTimestamp": 1790867086061,
+  "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/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.12.0",
+  "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/verify-changelog-range.cjs

@@ -14,8 +14,26 @@ 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(' , '))
-const cases = [['3.11.1', '3.12.0'], ['3.11.0', '3.12.0'], ['3.10.2', '3.12.0'], ['3.12.0', '3.12.0']]
+
+/** 当前版本号（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
@@ -23,4 +41,5 @@ for (const [startVersion, endVersion] of cases) {
     'range(' + startVersion + ' → ' + endVersion + ')：命中 [' + keys.join(', ') + ']  长度=' + out.length +
     (dumped ? '  ⚠ 返回了整份日志（没裁出来）' : '')
   )
+  if (dumped) process.exitCode = 1
 }

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),