music-link-vincentzyu-fork，网易和qq点歌，歌单支持纯文字、qq官机markdown、svg出图、puppeteer出图~歌曲信息除了常见图文格式，还可以发送onebot合并转发、音乐卡片、音乐语音、文件~

VincentZyu233 · 2026 年3 月 25 日 05:46

下一步是把js文件拆分一下，方便后续维护~

wc -l *.js

46e5dce43f023c051bb29d249608231d

VincentZyu233 · 2026 年3 月 25 日 13:25

哦对了，忘记提了，这个东西在win上面叫pagefile，原理都差不多，就是拿你disk上面的一块给你的memory做缓冲，

还有就是我自己是测过的，哪怕是2c2g的linux机器，你多配点swap，跑个puppeteer服务是没啥问题的

看这里：

debian ubuntu的机器可以直接用apt install chromium安装，因为chromium是开源软件，所以是直接收录在debian软件包里面的，然后安装好以后二进制的路径在这: /usr/bin/chromium 这个可以填入koishi的puppeteer插件的配置项里面~

哦还有，我突然发现私聊的 napcat音乐卡片还没做, 做一下

VincentZyu233 · 2026 年3 月 29 日 03:51

拆分js文件以后有点小bug，请更新到最新版本（比如忘记加 reusable 可重用，点歌数字解析有点问题等等）

如果还有bug 请及时反馈捏~ ：

~~💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入QQ群：259248174 🎉（这个群G了）~~

💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入新QQ群：1085190201 🎉

💡 在群里直接艾特我，回复的更快哦~ ✨

VincentZyu233 · 2026 年3 月 29 日 08:11

VincentZyu233 · 2026 年3 月 29 日 08:15

1.9.5-beta.1+20260329
- 功能优化
  - 歌单列表显示格式优化：歌曲编号从 1. 歌曲名 改为 (1) 歌曲名，更清晰易读
  - 尝试修复智能制表符对齐功能：然而并没有成功qwq
- 问题修复
  - 修复 command6 搜索结果缺少平台标识的问题，现在会正确显示 网易的红色的小圆角矩形tag~
- 文案优化
  - 将"出图模式"更名为"消息渲染模式"，描述更加准确
  - 更新部分后端 API 描述文案
    
    图片945×1217 291 KB
1.9.4-beta.1+20260329
- 代码重构
  - 拆分 index.js 为多个模块文件（middleware.js, command6.js, command9.js）
- 新增 notifier 通知
  - 插件启动时在 WebUI 显示配置信息
  - 显示资源文件（字体/图片）下载状态
- 界面优化
  - 添加字体使用声明和插件许可声明（MIT）
- Bug 修复
  - 修复重复插件检测问题
  - 修复序号输入错误 bug
  - 修复私聊音乐卡片发送失败
    
    图片883×509 26.8 KB

VincentZyu233 · 2026 年4 月 11 日 12:25

最近的一些更新捏：

1.9.9-beta.3+20260411
- 问题修复
  - 修复 Puppeteer 原始黑白样式(ORIGIN_BLACK_WHITE)中 version info 与歌单内容重叠的问题
    • body padding-top增至120px，为顶部元素预留充足空间
    • version-info移至页面真正左上角(top: 8px)，z-index: 1000
    • header-bar下移至top: 60px，避免与version info重叠
    • 调整DOM顺序：versionInfoHtml置于header-bar之前
  - 修复截图区域问题：改为截取整个body而非仅#song-list元素
1.9.9-beta.2+20260411
- 代码重构
  - 将测试相关文件从assets/迁移至test/目录
    • generate-test-data.py → test/
    • songlist-test.json → test/
  - 修正loadTestSongList函数中测试数据文件读取路径
- 文档更新
  - package.json新增test目录到files字段，确保发布时包含测试资源
  - 更新test/README.md使用说明，补充Python脚本执行命令
1.9.9-beta.1+20260411
- 新功能
  - command6/command9 新增 --test 测试模式，仅展示歌单不进入选择流程
  - SVG渲染支持自定义字体配置(svgEnableCustomFont/svgFontFiles/svgFontFamilies)
  - SVG/Puppeteer渲染器增加版本信息显示开关(svgShowVersionInfo/puppeteerShowVersionInfo)
- 问题修复
  - 修复Puppeteer渲染器重复生成HTML的性能问题，优化为单次渲染
  - 修复SVG渲染器中config变量未定义的ReferenceError
- 代码质量
  - 统一代码缩进为4空格Tab，格式化所有源文件
1.9.7-beta.1+20260410
- 新增中间件白名单机制
  - 新增Onebot音乐卡片JSON解析的白名单过滤功能
  - 支持自定义白名单规则（viewType + enabled配置）
  - 默认启用music类型（单曲卡片），禁用news类型（歌单/一起听等）
  - 可通过配置项customWhitelist灵活控制哪些卡片类型需要解析
- 配置优化
  - 新增enableWhitelist配置项控制是否启用白名单过滤
  - 新增used_id配置项设置歌单里默认选择的序号（范围0-10）
- 问题修复
  - 重构渲染架构并全面优化代码结构
  - 新增lib/renderer-text.js文件，分离文本渲染逻辑
  - 重构并行/串行渲染模式，确保严格按照配置表顺序执行消息发送
  - 修复QQ平台无法连续发送多个markdown歌单的问题（增加msg_seq参数）
  - QQ Markdown模式新增renderInfo信息显示（版本、时间、仓库链接等）
- 日志系统增强
  - 资源下载流程：添加emoji标识和结构化日志
  - 缓存目录管理：增强路径验证，区分文件/目录类型
  - 文件下载监控：添加耗时统计、文件大小显示、超时提醒
  - 音乐卡片发送：优化日志输出格式，便于调试和问题追踪
- 代码质量提升
  - 优化整体代码格式和注释规范
  - 统一日志输出风格，使用emoji增强可读性
  - 增强类型定义文件(lib/index.d.ts)
  - 清理冗余代码和测试数据
- 论坛发布的markdown：查看1.9.7 OneBot音乐卡片白名单功能详解
1.9.6-beta.4+20260330
- QQ Markdown功能完善
  - 新增QQ平台Markdown渲染模式预览图片
  - 更新README.md文档，添加QQ Markdown模式说明
  - 优化render-qq-markdown.js渲染逻辑
  - 新增Koishi WebUI通知功能预览图片
1.9.6-beta.3+20260330
- 新增QQ平台Markdown发送能力
  - 适配command6和command9命令支持QQ Markdown发送
  - 优化相关命令和渲染逻辑
  - 为正式发版做准备
1.9.6-beta.2+20260329
- 问题修复
  - 修复QQ Markdown模式下歌手信息不显示的问题
- 配置优化
  - 新增markdownTableMaxDisplay配置（默认20首）
  - 新增markdownStyleMaxDisplay配置（默认10首）
  - 移除旧的markdownMaxDisplay配置项
1.9.5-beta.1+20260329
- 功能优化
  - 歌单列表显示格式优化：歌曲编号从 1. 歌曲名 改为 (1) 歌曲名，更清晰易读
  - 尝试修复智能制表符对齐功能：然而并没有成功qwq
- 问题修复
  - 修复 command6 搜索结果缺少平台标识的问题，现在会正确显示 网易的红色的小圆角矩形tag~
- 文案优化
  - 将"出图模式"更名为"消息渲染模式"，描述更加准确
  - 更新部分后端 API 描述文案

VincentZyu233 · 2026 年4 月 11 日 12:30

code is here:

https://gitee.com/vincent-zyu/koishi-plugin-music-link-vincentzyu-fork/blob/main/lib/renderer-qq-markdown.js

or

https://github.com/VincentZyuApps/koishi-plugin-music-link-vincentzyu-fork/blob/56a2923318626ed717b85b7f638b588f5d20dc69/lib/renderer-qq-markdown.js

如上所示， qq官bot平台支持markdown歌单

新增配置项：

    // 🖼️ 歌单渲染格式设置
    Schema.object({
        showGeneratingTip: Schema.boolean().default(true).description('💬 是否在开始生成歌单时发送"🔄正在生成歌单，请稍候..."的提示消息<br>✅ 开启（默认）：发送提示并在完成后撤回<br>❌ 关闭：不发送提示消息，直接等待渲染完成'),
        renderMode: Schema
            .array(Schema.object({
                mode: Schema.union([
                    Schema.const('text').description('📝 文字模式'),
                    Schema.const('puppeteer').description('🎨 Puppeteer (传统方式)'),
                    Schema.const('svg').description('✨ SVG (resvg 渲染，推荐)'),
                    Schema.const('markdown_table').description('📊 QQ Markdown 表格模式'),
                    Schema.const('markdown_style').description('💫 QQ Markdown 格式风格'),
                ]).role('radio').description('渲染模式'),
                enabled: Schema.boolean().default(true).description('是否启用'),
            }))
            .role('table')
            .default([
                { mode: 'text', enabled: true },
                { mode: 'puppeteer', enabled: true },
                { mode: 'svg', enabled: true },
                { mode: 'markdown_table', enabled: false },
                { mode: 'markdown_style', enabled: false },
            ])
            .description('🖼️ 消息渲染模式设置（可添加多个，按顺序执行）<br>✨ (非qq官机平台)配合"严格顺序模式"可实现：文字 → SVG → Puppeteer 的发送顺序<br>⚠️ 如果启用了多个相同模式，只有第一个会生效'),
        strictOrderMode: Schema.boolean().default(true).description('📋 是否严格按照上表顺序串行执行（默认 true 为串行渲染）<br>⚠️ <b>强烈建议开启</b>：由于 Node.js单线程特性，并行渲染会导致 CPU争抢，使所有模式都变慢<br>✅ 串行模式：各渲染器独占CPU，互不干扰，总耗时更短<br>🐢 并行模式：多个渲染器同时竞争单线程CPU，互相阻塞，性能会有下降'),
    }).description('🖼️ 歌单渲染格式设置'),

VincentZyu233 · 2026 年4 月 11 日 12:35

↓ markdown file is also here

https://gitee.com/vincent-zyu/koishi-plugin-music-link-vincentzyu-fork/blob/main/doc/koishi%E8%AE%BA%E5%9D%9B%E7%9A%84%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97%E6%8D%8F/1.9.7%E6%9B%B4%E6%96%B0%E4%BA%86%E8%A7%A3%E6%9E%90onebot%E9%9F%B3%E4%B9%90%E5%8D%A1%E7%89%87%E7%9A%84%E7%99%BD%E5%90%8D%E5%8D%95.md

or:

https://github.com/VincentZyuApps/koishi-plugin-music-link-vincentzyu-fork/blob/01aed5ad314bb01f774d5b07e6064da02900eb9b/doc/koishi%E8%AE%BA%E5%9D%9B%E7%9A%84%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97%E6%8D%8F/1.9.7%E6%9B%B4%E6%96%B0%E4%BA%86%E8%A7%A3%E6%9E%90onebot%E9%9F%B3%E4%B9%90%E5%8D%A1%E7%89%87%E7%9A%84%E7%99%BD%E5%90%8D%E5%8D%95.md

以下是正文：

v1.9.7-beta.1 更新日志 - OneBot音乐卡片白名单过滤功能

新增功能概述

本次更新为 OneBot平台 的音乐卡片自动解析功能新增了 白名单过滤机制，让你可以更精细地控制哪些类型的音乐卡片会被插件自动识别和处理。

效果预览

上图说明：发送了6个音乐卡片（3个news类型 + 3个music类型）

只有3个music类型的单曲卡片触发了中间件解析 (网易云 Deco 火花、QQ音乐 Mimi 科学、酷狗音乐神秘毛子歌手神秘俄语歌)

剩下3个news类型的歌单/一起听卡片被成功过滤跳过 (网易云一起听 by蓝蚀白瑜、网易云歌单 Phigros、MIUI音乐 Mimi 拥抱)。

核心特性摘要

智能过滤：自动区分单曲、歌单、一起听等不同类型卡片
灵活配置：支持启用/禁用白名单，自定义允许的卡片类型
精准匹配：基于卡片的json view 字段进行精确匹配
可视化配置：通过表格形式管理白名单规则

使用quote-debug-msg-json-image这个插件把onebot音乐卡片的json数据dump出来，观察发现: 一般单曲卡片json的键值对中 view这个key对应的值是music,而其他的卡片(比如歌单、一起听等等)的这个键对应的值一般是news

JSON示例文件目录

doc/dev/20260410_1736_1.9.7_新增中间件解析onebot音乐卡片白名单的规划捏/
├── 单曲卡片
│ ├── MIUI音乐单曲实际上就是QQ音乐的音乐卡片捏_20260410_151110.json
│ ├── QQ音乐单曲的音乐卡片捏_20260410_173524.json
│ ├── 网易云单曲的音乐卡片捏_20260410_144917.json
│ └── 酷狗音乐单曲的音乐卡片捏_20260410_150015.json
└── 非单曲卡片
├── 网易云一起听的音乐卡片捏_20260410_144218.json
└── 网易云歌单的音乐卡片捏_20260410_144736.json

所以目前的做法其实很简单，有个table配置项，默认配置是 music卡片解析，news卡片不解析

想要了解细节的可以往下看

功能详解

什么是音乐卡片？

在QQ/TIM等客户端中，分享音乐时会发送一种特殊的 JSON格式卡片消息。这些卡片包含了歌曲信息、封面、播放链接等元数据。

例如，当你从网易云音乐或QQ音乐分享到群聊时，看到的不是普通文本，而是一个带有封面图和播放按钮的精美卡片。

为什么要白名单过滤？

不同类型的音乐卡片结构差异很大：

卡片类型	适用场景	是否需要解析
单曲卡片	分享单首歌曲	推荐解析
歌单卡片	分享整个歌单	通常不需要
一起听卡片	多人在线听歌	通常不需要

问题场景：

用户分享了"每日推荐"歌单 → 插件误认为是单曲 → 尝试搜索失败
好友发起"一起听"邀请 → 插件无法正确提取歌曲ID → 报错

解决方案：
通过白名单过滤，只让插件处理你真正需要的卡片类型（通常是单曲），忽略其他无关卡片。

配置项说明

`enableWhitelist` - 是否启用白名单过滤

默认值：true（启用）
作用：控制是否开启白名单过滤功能

# 启用白名单（推荐）
enableWhitelist: true

# 关闭白名单（解析所有卡片）
enableWhitelist: false

`customWhitelist` - 自定义白名单规则表

这是一个表格形式的配置项，每行代表一条规则：

列名	类型	说明	示例
`viewType`	字符串	卡片的视图类型	`music`, `news`
`enabled`	布尔值	是否启用此规则	`true`, `false`

配置项的代码：

    Schema.object({
        enablemiddleware: Schema.boolean().description("🔍 是否自动解析Onebot音乐卡片json <br> <i> ⚠️仅对Onebot平台生效</i>").default(false),
        enablePrependMiddleware: Schema.boolean().description("⚡ 是否使用前置中间件监听<br>`中间件无法接受到消息可以考虑开启`").default(false),
        enableWhitelist: Schema.boolean().default(true).description('🎯 是否启用白名单过滤<br>✅ 开启（默认）：只解析白名单中允许的卡片类型<br>❌ 关闭：解析所有音乐卡片'),
        customWhitelist: Schema.array(Schema.object({
            viewType: Schema.string().default('music').description('视图类型'),
            enabled: Schema.boolean().default(true).description('启用此规则'),
        })).role('table').description('⚙️ 自定义白名单规则<br>只有匹配白名单规则的卡片才会被解析<br>💡 留空表示拒绝所有卡片<br><b>常见类型说明：</b><br>• <code>music</code> - 大概率为单曲卡片（推荐启用）<br>• <code>news</code> - 大概率为歌单、一起听等（通常禁用）<br>• <code>其他</code> - 如果以后有新的type你也可以自己填入喵').default([
            { viewType: 'music', enabled: true },
            { viewType: 'news', enabled: false },
        ]),
        // <br>• <code>music</code> - 单曲卡片（最常见）<br>• <code>news</code> - 歌单/一起听等其他卡片<br>• 其他 - 自定义类型
        used_id: Schema.number().default(1).min(0).max(10).description("🔢 在歌单里默认选择的序号<br>范围`0-10`，无需考虑11-20，会自动根据Onebot音乐卡片卡片的平台选择。若音乐平台不匹配 则在搜索项前十个进行选择。"),
    }).description('🎴 中间件解析Onebot音乐卡片Json的相关设置'),

默认规则：

customWhitelist:
  - viewType: music    # 单曲卡片
    enabled: true      # ✅ 允许解析
  
  - viewType: news     # 歌单/一起听卡片
    enabled: false     # ❌ 拒绝解析

如何添加新规则：

点击"添加行"按钮
在 viewType 列输入卡片类型（如 music、news 或其他）
勾选 enabled 列的复选框以启用该规则
保存配置即可生效

配置界面截图

上图展示了白名单配置的表格界面，可以清晰地看到 viewType 和 enabled 两列

康康json长啥样

本git仓库的 doc/dev/20260410_1736_1.9.7_新增中间件解析onebot音乐卡片白名单的规划捏 这个文件夹存了一些json示例捏

root@bawuyinguo:/home/bawuyinguo/SSoftwareFiles/koishi/koishi-dev-4/external/music-link-vincentzyu-fork/doc/dev/20260410_1736_1.9.7_新增中间件解析onebot音乐卡片白名单的规划捏# ls -la | grep json
-rw-r--r-- 1 root root    2637  4月 10 17:46 MIUI音乐单曲实际上就是QQ音乐的音乐卡片捏_20260410_151110.json
-rw-r--r-- 1 root root    3083  4月 10 17:46 QQ音乐单曲的音乐卡片捏_20260410_173524.json
-rw-r--r-- 1 root root    2902  4月 10 17:46 网易云一起听的音乐卡片捏_20260410_144218.json
-rw-r--r-- 1 root root    2823  4月 10 17:46 网易云单曲的音乐卡片捏_20260410_144917.json
-rw-r--r-- 1 root root    2747  4月 10 17:46 网易云歌单的音乐卡片捏_20260410_144736.json
-rw-r--r-- 1 root root    3412  4月 10 17:46 酷狗音乐单曲的音乐卡片捏_20260410_150015.json
root@bawuyinguo:/home/bawuyinguo/SSoftwareFiles/koishi/koishi-dev-4/external/music-link-vincentzyu-fork/doc/dev/20260410_1736_1.9.7_新增中间件解析onebot音乐卡片白名单的规划捏#

卡片结构分析

OneBot音乐卡片本质上是JSON格式的数据，关键字段如下：

{
  "app": "com.tencent.music.lua",    // SDK标识（固定）
  "view": "music",                    // 视图类型（关键！）
  "meta": {
    "music": {                        // 单曲元数据
      "title": "歌曲名称",
      "desc": "歌手",
      "jumpUrl": "https://..."
    }
  }
}

关键发现：

所有腾讯SDK生成的单曲卡片都使用 view: "music"
歌单/一起听卡片使用 view: "news"
app 字段对于同一类卡片是固定的，因此只需关注 view 字段

过滤逻辑

// 伪代码示意
if (!config.enableWhitelist) {
  return true;  // 未启用白名单，允许所有卡片
}

// 检查卡片的 view 字段是否在白名单中
return config.customWhitelist.some(rule => 
  rule.enabled && (rule.viewType === '*' || rule.viewType === jsonData.view)
);

实际案例参考

以下是从真实环境中捕获的各种音乐卡片JSON样本，你可以点击查看完整内容：

提示： 如果你想自己捕获音乐卡片的JSON数据，可以使用这个插件捏： quote-debug-msg-json-image
该插件可以将收到的消息（包括OneBot音乐卡片）导出为JSON文件，方便调试和分析。

GitHub: https://github.com/VincentZyuApps/koishi-plugin-quote-debug-msg-json-image

Gitee: https://gitee.com/vincent-zyu/koishi-plugin-quote-debug-msg-json-image

单曲卡片示例

QQ音乐单曲

QQ音乐单曲的音乐卡片捏_20260410_173524.json

关键特征：

{
  "app": "com.tencent.music.lua",
  "view": "music",
  "meta": {
    "music": {
      "title": "歌曲名称",
      "desc": "歌手",
      "tag": "QQ音乐"
    }
  }
}

酷狗音乐单曲

酷狗音乐单曲的音乐卡片捏_20260410_150015.json

网易云音乐单曲

网易云单曲的音乐卡片捏_20260410_144917.json

非单曲卡片示例

网易云歌单

网易云歌单的音乐卡片捏_20260410_144736.json

关键特征：

{
  "app": "com.tencent.tuwen.lua",
  "view": "news",
  "meta": {
    "news": {
      "title": "歌单名称",
      "desc": "包含XX首歌曲",
      "tag": "网易云音乐"
    }
  }
}

网易云一起听

网易云一起听的音乐卡片捏_20260410_144218.json

MIUI音乐单曲

MIUI音乐单曲实际上就是QQ音乐的音乐卡片捏_20260410_151110.json

（MIUI据说实际上貌似就是QQ音乐套壳？但是好像似乎MIUI分享出来的卡片的view字段是news而不是music。如果有人需要保留miui音乐的检测同时排除其他非单曲卡片可以找我联系捏。因为懒不想做了鹅鹅鹅）

使用建议

场景1：只想解析单曲（推荐大多数用户）

保持默认配置即可：

enableWhitelist: true
customWhitelist:
  - viewType: music
    enabled: true
  - viewType: news
    enabled: false

效果：

自动解析所有单曲卡片
忽略歌单、一起听等非单曲卡片

场景2：需要解析所有类型卡片

关闭白名单过滤：

enableWhitelist: false

注意： 这可能导致插件尝试解析不兼容的卡片类型而产生错误。

场景3：自定义特殊需求

如果你发现了新的卡片类型并希望支持它：

打开插件配置的"中间件解析OneBot音乐卡片Json的相关设置"部分
确保 enableWhitelist 为 true
在 customWhitelist 表格中添加新行：
- viewType: 输入新发现的视图类型（可通过日志查看）
- enabled: 勾选以启用
保存并重启插件

如何查看卡片的 view 类型？

开启 loggerinfo: true 配置项，观察日志输出中的 view= 字段
或者用我上面说的quote-debug-msg-json-image插件，使用dump-json指令捏

常见问题

Q1: 为什么我的音乐卡片没有被解析？

可能原因：

卡片类型不在白名单中（检查 view 字段）
enableWhitelist 为 true 但白名单为空
对应规则未被启用（enabled: false）

解决方法：

开启 loggerinfo: true 查看日志
检查日志中的 [卡片过滤] 提示信息
根据需要调整白名单规则

Q2: 如何知道某个卡片的 view 类型是什么？

方法1：查看日志

# 开启详细日志后，会看到类似输出：
⏭️ [卡片过滤] 跳过非匹配卡片 | 🔍 view=news | ️ 白名单=已启用

here is code:

root@bawuyinguo:/home/.../music-link-vincentzyu-fork# rg 卡片过滤
lib/middleware.js
57:                            logInfo(`⏭️ [卡片过滤] 跳过非匹配卡片 | 🔍 view=${jsonData.view} | ️ 白名单=${config.enableWhitelist ? '已启用' : '未启用'}`);

方法2：查看JSON文件

插件 quote-debug-msg-json-image dump卡片JSON（推荐）
在导出的JSON文件中查找 "view": "xxx" 字段
也可以参考本文档" 实际案例参考"章节中的示例JSON文件

方法3：参考本文档的示例

单曲通常是 view: "music"
歌单/一起听通常是 view: "news"

Q3: 可以通配符匹配吗？

目前支持 * 作为通配符：

customWhitelist:
  - viewType: "*"    # 匹配所有类型
    enabled: true

但这等同于关闭白名单，不如直接设置 enableWhitelist: false 更清晰。

Q4: 这个功能对其他平台有效吗？

无效。 白名单过滤仅对 OneBot平台 生效，因为：

只有OneBot平台才有这种JSON格式的卡片消息呀

更新历史

v1.9.7 (2026-04-10)

新增 OneBot音乐卡片白名单过滤功能
新增 enableWhitelist 配置项
新增 customWhitelist 表格配置
优化所有日志输出，增加emoji标识
完善文档和示例

v1.9.6 及以前

无白名单功能，解析所有检测到的音乐卡片

获取帮助

如果遇到任何问题或有改进建议：

QQ 交流群：259248174（这个群G了
QQ 交流群：1085190201
Issue提交：GitHub仓库
完整文档：Gitee README