koishi-plugin-kkk 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,263 +1,75 @@
 # 更新日志
 
-## 3.11.0
-
-### 修「发送视频」失败：QQ 群文件名不能直接用作品标题
-
-用户贴的日志：
-
-```
-[视频发送] 平台=qq 体积=40.6MB QQ阈值=30MB 走群文件=true
-被动消息: 视频大小: 40.6MB 正在通过e.bot.uploadFile回复...
-视频文件上传错误,Error
-[ErrorHandler] 原始错误: 解析过程中有 1 个步骤失败（发送视频）：
-Error
-    at _QQMessageEncoder.send (…/@satorijs/core/lib/index.cjs:756:13)
-```
-
-查了原始日志（`data/logs/2026-10-01-*.log`），事实是：**40.62MB、走群文件、1.8 秒就失败**，
-而且**今天同一个快手视频连失败三次**；历史上走群文件成功的三次是 B站 / 抖音 / onebot。
-
-根因：**群文件名**。
-
-- 快手的 `originTitle` 就是**作品标题原文**（`kuaishou.ts` 里 `originTitle: \`${work.photo.caption}.mp4\``），
-  这条视频的标题是一段**带换行、224 个字符**的多行文案
-  （`《打电话赢 1 万！…爽到爆》\n\n三大现金挑战…`）；
-- 群文件那条分支以前把 `originTitle` **原样**拼上 `.mp4` 当 `file_name` 发给 QQ 的
-  `upload_prepare` —— 名字里带 `\n`，QQ 直接判参数错误，**视频一个字节都没发出去**；
-- 标题本身已经带 `.mp4` 时还会拼成 `xxx.mp4.mp4`；
-- 同一条链路在 B站 上是好的，因为 `bilibili.ts` 早就做过
-  `substring(0, 50).replace(/[\\/:*?"<>|\r\n\s]/g, ' ')` —— 快手 / 抖音 / 番剧那几处漏了。
-  磁盘上的文件名有 `processFilename` 兜着，所以这个问题**只在「发到 QQ」时**暴露，本地看不出异常。
-
-改法：
-
-- 新增 `Base.groupFileName(file)`：去掉调用方自带的 `.mp4` → 把
-  `\ / : * ? " < > |`、换行、制表符、控制字符换成空格 → 去掉开头的点 → 截到 60 字符 →
-  标题为空时退回 `filepath` 的文件名，都没有才用 `kkk_<时间戳>.mp4`。
-  一处收口，四个平台（含定时推送里 `useGroupFile: true` 那条）一起好。
-- 群文件发送**失败换名字重试一次**：先用清洗后的标题名，被 QQ 打回就换
-  `kkk_<时间戳>.mp4` 再来一遍。群文件名是这条链路上唯一「因文件而异」的入参，
-  换个名字往往就通了，代价只有一次调用。
-- **错误信息不再只说「Error」**：适配器抛的是 `@satorijs/core` 的 `AggregateError`，
-  它 `super('')` —— message 是空的，真正的原因在 `errors: Error[]` 里
-  （`QQ 消息发送失败 [400xxxxx] xxx`）。以前的日志把它整个丢掉，只剩
-  `视频文件上传错误,Error` 和一句「解析过程中有 1 个步骤失败（发送视频）：」。
-  新增 `ParseSteps.describeError`，把 `errors[]` / `cause` 逐层剥开，
-  日志里、错误卡片上、`throwIfFailed` 合成的错误里都带上了真正的原因。
-- 顺带修 `临时预览地址：http://localhost:undefined/kkk/ssr/video/…`：
-  `process.env.HTTP_PORT` 是上游 karin 的环境变量，Koishi 侧没有 ——
-  改成读 `ctx.config.port`，拿不到再退回环境变量 / 7777。
-- 顺带修 `scripts/build.mjs` 里唯一一处**同步起子进程**
-  （`execFileSync('git', ['rev-parse', 'HEAD'])` 取 commit hash）：这台开发机上同步
-  `spawn` 会被直接掐掉，表现是**构建一行输出都没有就退出**。改成直接读 `.git/HEAD`
-  （含 `packed-refs` / worktree 两种形态），`GITHUB_SHA` 仍作兜底。
-- 新增 `scripts/probe-group-file-name.cjs`（38 项，全程离线）：用**这条视频的真实标题**
-  断言文件名的合法性；端到端真调 `uploadFile`，断言交给适配器的名字里没有换行；
-  断言失败后会换临时名重试、且只重试一次；断言 `describeError` 能挖出 `AggregateError`
-  里的错误码；外加源码守卫。
-
-### 「是否收集评论区的图片」不再是摆设；评论区没图就不挂按钮
-
-用户两句话，一个主题：**按钮和开关都得名副其实**。
-
-1. 「评论区没有图片就不要显示按钮了」—— 一条评论都没贴图时，「提取评论区图片」
-   点下去什么也发不出来（缓存里没有那张图），是个**点了没反应的摆设**。
-2. 「是否收集评论区的图片……这个开不开都没有用啊」—— 那个开关**确实一直是个摆设**：
-   B站视频那条链路上的实现被写死成 `if (false && …)` 整段短路了，点开点关都一样。
-
-现在：
-
-- 新增 `QqPanel.hasCardImage(key, 'cover' | 'comment')`：**缓存里没有那张图就不挂对应按钮**。
-  「提取评论区图片」要的是**评论里用户自己贴的图**（`commentPics`），不是渲染出来的那张评论长图
-  —— 长图卡片本身已经发过一遍了，再挂个按钮去重发它没有意义。
-  四个平台（B站 / 抖音 / 快手 / 小红书）统一走这个口径，原生按钮和 markdown 文字链两条路都走。
-  抖音以前连 `commentPics` 都不记，按钮只能退回去重发长图 —— 现在补上了。
-- 「是否收集评论区的图片」**真的接上了**：打开时解析完直接把评论区里用户贴的图**发一条**
-  （优先合并成一条 markdown：官方 QQ bot 上合并转发经常发不出去，会退化成一张图一条消息；
-  不支持 markdown 的适配器才退回 `makeForward`），
-  **并且不再挂「提取评论区图片」按钮** —— 图已经在群里了，再挂一个只是重复发一遍。
-  关着（默认）就照旧：不直接发，按钮挂上。
-- 新增 `src/karin/module/utils/CommentPics.ts`：把「评论区图片直接发」收成**一个**函数，
-  返回「**到底发出去了没有**」，调用方拿这个结果决定按钮挂不挂。
-  三个调用点（B站视频 / B站动态 / 抖音）原本各抄一份，而这次的规则要横跨「发送」和「挂按钮」两处，
-  抄三份必然会漏改一处，出现「发了图还挂按钮」或「没发图也没按钮」这种半截状态。
-  - 发失败（没图 / 图全部落地失败 / 适配器报错）**不算发过**，按钮照挂 —— 别让用户没路走。
-  - 图**直接发过之后仍然记进缓存**：按钮不挂只是「别再点重发」，手敲 `kkk评论` 还要读这份缓存。
-- 面板上那个开关的说明也跟着改了（`scripts/patch-webui.mjs` 里加了一条描述改写）：
-  「打开后：…卡片下面就不再挂『提取评论区图片』按钮了；关闭（默认）：…想单独存图再点一下。」
-  免得用户再对着文案猜它到底管什么。
-- `scripts/probe-extract-buttons.cjs` 重写：覆盖「只有封面 / 有评论图 / 只有评论长图 / 没有作品 id」
-  四种缓存状态下四个平台按钮的挂与不挂、开关打开后的按钮抑制，
-  以及 `sendCommentPicsDirectly` 的四条出口（没图 / 落地失败 / 正常两张 / 发送抛错），
-  外加一条**源码守卫**（产物里不许再出现 `if (false && Config.…)` 这种短路，且开关真的被读到）。
-  全程离线（探针自己起 `127.0.0.1` 服务供图），28 项全过。
-
-### 所有指令收进 `kkk` 分组（控制台里不再铺一地）
-
-- 以前 40 条指令全是**顶层**的（`解析`、`kkk帮助`、`b站登录`、`设置抖音推送`、
-  `抖音全部强制推送`…），控制台的「指令」页从头翻到尾。
-- 现在统一挂在 **`kkk` 分组**下：`kkk.解析`、`kkk.帮助`、`kkk.版本`、`kkk.B站登录`、
-  `kkk.设置抖音推送`、`kkk.下载进度`…… 共 34 条子指令 + 1 个分组节点。
-  - Koishi 的指令树是**靠名字里的 `.` 分词**的（`ctx.command('kkk.帮助')` 会顺手建出父指令 `kkk`），
-    而控制台只把**名字里带 `.`** 的子指令收进 `children` ——
-    所以「只把 `parent` 指过去、名字还叫 `kkk帮助`」是没用的，名字必须真的写成 `kkk.xxx`。
-  - 显示名会**去掉前导的 `kkk`**（`kkk帮助` → `帮助`、`kkkB站登录` → `B站登录`），
-    免得控制台里出现 `kkk/kkk帮助` 这种套娃。
-- **老名字一个都没少，而且不能少**：用户习惯、QQ 按钮里的指令文本（`解析 … --qn=16`）、
-  面板上的 📊 按钮（`下载进度`）用的都是裸名字，所以全部原样挂成**别名**。
-  `解析` / `kkk解析` / `弹幕解析` 这类本来就指向同一个 handler 的名字会**合并成一条指令**
-  （`解析` 与 `kkk解析` 现在是同一条），控制台里不再重复出现。
-- 四种写法都能用：`解析 <链接>`、`/解析 <链接>`、`kkk.解析 <链接>`、`kkk 解析 <链接>`。
-  后两种是分组带来的新写法，`action` 里会把 `kkk` + 分隔符（空格 / 点 / 全角空格）
-  还原成 karin 注册表认的那个名字再往下传（移植过来的业务代码按
-  `e.msg.replace(/^#kkk帮助/, '')` 这种裸名字写的，不能改一行）。
-- 只敲 `kkk` 会列出所有子指令（父指令上挂了个 action），子指令照常优先。
-- **顺手修**：面板上那个 📊「查询下载进度」按钮走的是**回调按钮**（`interaction/button`），
-  回调文本进的是文本兜底（`runTextCommand`），而 `下载进度` 从来就不是 karin 注册表里的指令 ——
-  也就是说**点了没反应**。现在文本兜底里单独认一下 `#?(kkk)?下载进度`。
-- `alias()` 撞名会抛异常、把整个 `apply` 拖死（apply 一挂，指令和控制台路由全都上不去）。
-  正常升级路径上旧指令会先被 dispose 掉、撞不上，但热重载时序偶尔会让上一个实例的指令还在表里，
-  所以挂别名包了一层 try/catch：撞名只警告（重启即恢复），绝不让 apply 抛出去。
-
-### md 图片的尺寸改成「真量」；量不到就不发 markdown（修「图片被强制拉伸」）
-
-用户先后反馈过两件事，根因是同一个：**尺寸是猜出来的**。
-
-1. 「发送的所有 md 图片都要 `#宽px #高px`，不然根本看不见」——
-   QQ 的 markdown 图片必须写死尺寸，`![](url)` 在手机端是**一片空白**。
-2. 「自适应发送的图片长宽高有些被强制拉伸了」——
-   读不出尺寸时以前会**猜**一个 `宽度 × 宽度×1.3` 的框填进去，
-   而 QQ 是**按声明的框渲染**的：框的比例和原图对不上就被硬拉变形。
-
-现在统一成一句话：**尺寸必须来自真实测量，量不到就返回 `null`、退回普通图片段发**
-（普通图片会被客户端压得糊一点，但比例是对的、也看得见，比一张拉变形的图强）。
-
-- 新增 `src/compat/imageSize.ts`：一个**无依赖**的叶子模块，从二进制头读 PNG / JPEG / GIF / WebP
-  的真实像素尺寸（含 WebP 的 `VP8X` / `VP8L` / `VP8 ` 三种头）。
-  以前「读尺寸」在插件里有**四个消费方各写各的**，能力还不一样 —— 同一张 WebP
-  在一条链路上能读出来、在另一条上读不出来，读不出来的那条只能猜。
-  现在四条链路共用它，格式覆盖一次就全都覆盖。
-- `Render.getImageMetadata` 从「只认 PNG / JPEG」换成它；
-  `compat/imageMarkdown.ts` 里那份重复的读取实现删掉；
-  `QqPanel` 的面板卡片尺寸也走它。
-- **删掉所有「读不出就猜」的兜底**：
-  - `QqPanel.toMarkdownImage` 原来有**四处**「读不出尺寸就按 `maxWidth × maxWidth×1.3` 估一个」
-    （这就是拉伸的来源）。现在：读不出 → 先补一次 ffprobe → 还是不行就 `null`；
-    宿主的 `assets` 服务没给出公网地址、图片下载失败，同样 `null`。
-  - `QqPanel.panelCardInfo` 新增：面板卡片的 `#宽px #高px` 只用真实值，
-    读不出就**不发这张卡**（不再 `|| 1440` / `|| 1080` 兜一个）。
-- 发送出口的兜底（`compat/imageMarkdown`）也跟着改：
-  - `ensureMarkdownImageSize` 保留为**估算版**，只在「连图都读不到」时当最后一道兜底；
-  - 新增 `sizeMarkdownImages`：**先把图下下来量真实尺寸**，量到就用真实比例，
-    量不到才退到估算。走的是它，不是估算那版。
-  - 这层兜底要**放在「有没有图片段」的判断之前**：长图切片那种消息整条只有
-    markdown、一个图片段都没有，放后面会整条漏掉。
-    markdown 段的正文在 `children[].attrs.content`（`segment.markdown` 走 satori 的 `h()`），
-    不在 `attrs.content` 上，两种形状都认（改写函数因此变成 async）。
-- `scripts/probe-md-image-size.cjs`：探针重写成**离线可重复**的
-  （自己起一个 `127.0.0.1` 的服务提供确定尺寸的图），
-  覆盖「800×600 要缩成 420×315 而不是 420×546」「读不出尺寸 / 404 / base64 / data:
-  一律返回 null」「量不到才用估算」等 39 项。
-
-### 封面解析也要去重
-
-- 出面板（B站 / 抖音那条「封面 + 画质表格」）原来是在作品级去重**之前**就 return 的，
-  于是短时间内重复发同一条链接会一遍遍重新出面板；
-  反倒**点清晰度按钮是有去重的**（按钮命令带 `--qn` / `--q`，绕过面板走到作品级去重）。
-- 现在首发链接也按「平台 + 会话 + 用户 + 作品 id」挡一次，**画质不在键里**
-  （选了画质走下面那道作品级去重，两者互不干扰）。
-- 面板按钮点出来的（带 `--p` / `--qn` / `--panel` / `--bgp`）一律放行，
-  否则「重发面板」「上一页 / 下一页」会被它自己上一次的点击挡住。
-
-### 卡片下面加「提取封面图 / 提取评论区图片」
-
-- 卡片在 QQ 上是一整条 markdown 图片，几张图叠在一起，想单独存封面或只看评论区长图很不方便。
-  现在卡片下面多一行两个按钮，点一下把那张图**单独发一遍**（md 格式，不重新渲染卡片）。
-- 按钮挂在**评论区那条长图**下面（详情卡片下面也有）：QQ 上的解析基本都是
-  「发链接 → 出面板 → 点清晰度」，这种走法详情卡片是不发的（面板已经发过那张卡），
-  评论区才是每次都能看到的那条。
-- **按钮和图片在同一条消息里**：不再单独发一条按钮消息，而是直接拼在图片下面一起发
-  （详情卡片、评论区卡片都是 `[...图片, ...按钮]` 一次 reply；
-  评论长图要走切片，切片发送加了「附加元素」参数，按钮只挂在**最后一组**切片后面）。
-- **按钮不在画质面板里**：点清晰度后面板会被撤回（`replyReplacing`），挂在面板上的按钮
-  跟着一起没了，点了没反应。面板只在**内部**把封面记进缓存，不显示按钮。
-- **改成 QQ 原生回调按钮**（`keyboard`，`action.type = 1`），不再是 markdown 里的
-  `<qqbot-cmd-input>` —— 那个在 QQ 上渲染成**蓝色文字链**，不是按钮。
-  原生按钮点一下直接把指令回调给机器人（走 `interaction/button` 事件，插件里已有监听），
-  **不用再往输入框塞文本、不用再点一次发送**。
-  适配器不支持原生按钮时（官方 `@koishijs/plugin-adapter-qq` 没实现 keyboard）自动退回原来的文字链。
-- **两张卡各带各的按钮**，不再堆在最后一条下面：
-  封面 / 详情卡片 → 「提取封面图」；评论区 → 「提取评论区图片」。
-  动态卡片同样按内容给（有封面才给「提取封面图」），动态评论区给「提取评论区图片」。
-- **面板那张封面卡上也带「提取封面图」**：发链接后第一条是面板，封面是**单独一条消息**
-  发的、选清晰度时只撤下面那张表格、卡片留在群里，所以按钮挂在这里点得到
-  （挂在画质表格上不行 —— 一选清晰度整条就被撤了）。面板上**不给**「提取评论区图片」，
-  那会儿评论图还没渲染。
-- **修：点「提取评论区图片」却变成重新解析一遍视频**。
-  按钮回调的文本是 `kkk评论 bilibili:BV1JSan6GEFW`，而 B站链接指令的正则是靠 BV 号认链接的
-  —— **它也能匹配这串字**。`runTextCommand` 按注册顺序取第一条命中，而各平台链接指令
-  的优先级是 800、提取指令原来没设（0），于是被抢走、当成「解析这条链接」跑了一遍。
-  现在提取指令优先级提到 **900**（正则锚在 `^#?`，抢在最前面也不会误伤别的消息）。
-- **「提取评论区图片」改发评论里用户贴的图**。
-  之前发的是插件**渲染出来的那张评论长图**，而那张卡片本身已经发过了 —— 等于原样重发。
-  现在缓存里分开记两类图：渲染卡片（`comment`）和评论里用户自己贴的图（`commentPics`，
-  取自 `bilibiliComments` 的 `image_urls`），按钮优先发后者，
-  点击时过一遍 `processImageUrls` 落地成能发的地址；一条评论都没贴图时才退回渲染卡片。
-  视频评论 / 动态评论两处都记了，与「评论区图片收集」那个开关无关（关着也能提取）。
-
-### QQ 适配器设置：图片超过指定高度就自动切片
-
-- 新增 **`sliceImageAutoHeight`**（「图片发送」组，默认 **6000** 像素，填 `0` = 关）。
-- 原来的「超大图片自动切片」是**先整张发一次、被 QQ 拒收了才补切**：QQ 收得下的超高图
-  就这么整张出去了。而太高的图 QQ 会整体缩小显示，卡片下面挂了提取按钮时，
-  缩图留下的空白会被按钮撑开 —— 一大片空白很难看。
-- 设了阈值就**直接切开**不再试发，每片都在正常尺寸内，没有这块空白。
-
-- **按钮带作品参数**：指令形如 `kkk封面 bilibili:BV1JSan6GEFW`。
-  之前按「会话最近一次解析」取图，群里**又有人发了别的链接**之后缓存就被覆盖，
-  回头点老卡片下面的按钮会发出来**另一个作品**的图。现在缓存按「平台 + 作品 id」存，
-  按钮把键当参数带上，点哪张卡就取哪个作品（手敲不带参数时才回退到本会话最近一条）。
-- **动态也有这两个按钮**：B站动态卡片（图文 / 纯文 / 转发 / 视频 / 专栏）和动态评论区
-  下面都挂了；动态的作品键是**里面的 BV**（视频动态）或动态 id，
-  封面取视频封面 / 第一张图 / 被转发的那条；没有封面的（纯文字）只给「提取评论区图片」。
-- **只有 QQ / QQ 频道有按钮**；其它平台显示一句提示，照着「引用这条消息发送 `kkk封面 …` /
-  `kkk评论 …`」操作即可。
-
-### 小红书 / 快手也补上了这两个提取按钮
-
-- **小红书**：上一版只做了 B站 / 抖音，小红书整条链路一次都没调用过按钮，
-  所以发小红书链接时卡片下面什么都没有。现在笔记信息卡（封面 + 字体正文 + 数据的详情卡）
-  下面挂「提取封面图」，评论卡片下面挂「提取评论区图片」。
-  封面取 `image_list[0]`，视频笔记的 `image_list` 常为空数组，按
-  `video.image.first_frame` → `video.cover` 兜底（和详情卡片显示的是同一个值）。
-- **快手**：这条链路**只有评论区一张卡** —— 作品信息本身就画在评论卡顶部，没有单独的封面卡，
-  所以封面与评论区**两个按钮都挂在评论卡下面**。封面取 `photo.coverUrls[0].url`。
-- **「提取评论区图片」发的是评论里用户贴的图**，两个平台各自的取法：
-  小红书取每条评论的 `pictures`（根评论 + 子评论都收，按出现顺序去重 ——
-  卡片里每条只渲染了第一张，按钮要发的是全部）；
-  快手取 `rootComments[i].attachments[].content.smallUrl`（多 CDN 取第一条）。
-- 两处都按「平台 + 作品 id」记缓存，按钮回调带着 `xiaohongshu:<note_id>` / `kuaishou:<photoId>`，
-  和 B站 / 抖音同一套口径（15 分钟过期、过期提示重发链接）。
-
-### 推送消息下面的「解析」按钮
-
-- 定时推送出来的动态 / 作品卡片自带链接，但没开自动解析时没人会去解析它。
-  现在卡片下面多一个「解析」按钮，点一下即按这条链接解析。
-- 以前这里用的是旧式回调按钮 `segment.button`，且只认 `adapter.name === 'QQ Official Bot'`，
-  很多部署上根本不出按钮。现在和「提取图」按钮同一套写法：QQ / QQ 频道给 markdown 按钮，
-  其它平台给文字提示。B站、抖音推送都改了。
-- **解析的是动态里面的作品，不是动态本身**：推送卡片已经把这条动态整个渲染出来了，
-  再点「解析」去解析同一条动态等于把刚才那张卡片原样再发一遍，没有意义。现在按钮取的是
-  **动态里带的那个作品** —— 视频动态取里面的 BV；转发动态取**被转发的**那一条（转发本身只是个壳）；
-  图文 / 纯文字动态翻正文富文本和网页卡片里的跳转链接，取第一条**能解析的作品链接**
-  （话题页、`t.bilibili.com` 动态页、个人主页、专栏、直播间这类会被跳过）。
-  一条动态里什么作品都没带的（纯文字、纯图文、转发了条纯文字）→ **不显示按钮**。
-- 按钮前面加了换行：原来按钮元素是拼在卡片内容末尾的，不加换行会粘在图片那一行后面。
-- **只有 QQ / QQ 频道有按钮**；其它平台显示一句提示，照着「引用这条消息发送 `kkk封面` /
-  `kkk评论`」操作即可。两个平台都能用的指令：`kkk封面`、`kkk评论`。
-- 点按钮**不重新解析、不重新渲染**：图源取自上次解析（按会话缓存 15 分钟，
-  换了作品就整条作废；评论长图是临时文件，会被定时清理，过期就提示先发条链接）。
+## 3.12.0
+
+### 新：提取图片的按钮只能点一次
+
+卡片下面「提取封面图 / 提取评论区图片」这两个按钮以前可以一直点。有人一直点，
+群里就被同一张图刷屏，而且看不出是谁在点。
+
+现在**同一张卡片上的同一个按钮只放行一次**：
+
+- 再点不会往群里发任何东西（不再刷屏），但日志里会记下「这次是谁点的、之前是谁点过」，
+  真被人刷了能查出来；
+- 封面和评论区是两个按钮，各点各的，互不影响；换一个作品也照常能点；
+- 想再要一次，**重新发一遍链接**就行，新卡片下面的按钮又是可点的（不会被永久锁死）；
+- 自己手敲 `kkk封面` / `kkk评论` 不受这个限制，随时都能用。
+
+还有一处顺手修的：万一这次没发出去（图过期了、或者发送报错），这次点击**不算数**，
+再点一次还是能发 —— 以前那种「点一次就永久作废」的情况不会出现。
+
+## 3.11.1
+
+这一版修的主要是两类事：**东西发不出去**，和**按钮点了没反应**。
+
+### 修：视频发不出来（快手的长标题）
+
+快手有些作品的标题是好几行的长文案。QQ 收群文件时会先看文件名，
+标题里带换行就直接把整个上传退回来了 —— 视频明明已经下好，
+却一个都没发出去，只在群里留一张报错卡（同一个视频连着失败了三次）。
+
+现在发之前会把名字收拾干净（去掉换行和非法字符、太长就截断）；
+万一还是被 QQ 退回，会自动换个临时名字再发一次。
+
+顺带把报错信息也修好了：以前只写一句「失败」，现在会带上 QQ 给的原因，
+真出问题一眼就能看出是什么。
+
+### 新：卡片下面可以单独提取封面图 / 评论区的图
+
+解析出来的卡片是一整条长图，想单独存封面、或者只看评论里别人贴的图，以前只能自己截图。
+现在卡片下面多了一行按钮：
+
+- **提取封面图** —— 把封面单独发一遍；
+- **提取评论区图片** —— 发的是**评论里用户自己贴的图**（不是插件渲染的那张评论长图）。
+
+B站、抖音、小红书、快手都做了。只有 QQ / QQ 频道会有按钮，
+其它平台会提示你引用那条消息、手敲 `kkk封面` / `kkk评论`。
+
+### 修：「是否收集评论区的图片」打开没反应
+
+打开这个开关，解析完就会**直接把评论区里的图发一条**，卡片下面不再重复挂按钮；
+关着（默认）保持原样，想单独存图自己点一下。
+
+另外，评论区一条图都没有的时候，那个按钮不会再显示了 —— 反正点了也没东西可发。
+
+### 改：指令在控制台里收进「kkk」分组
+
+控制台的指令页面以前有 40 条指令铺一地，现在统一收在 `kkk` 下面。
+**几种写法照旧都能用**：`解析 <链接>`、`/解析 <链接>`、`kkk.解析 <链接>`、`kkk 解析 <链接>`。
+
+### 修：图片被强制拉伸
+
+QQ 的 markdown 图片必须写死尺寸。以前尺寸读不出来时会随便猜一个，
+比例和原图对不上就被硬拉变形。现在尺寸一律实测，实在量不到就退回普通图片发送
+（会糊一点，但比例是对的、也看得见）。
+
+### 其它
+
+- 图片超过 6000 像素就自动切开再发（这个高度可以在设置里改），不再先整张发一遍、被退回来才补切。
+- 短时间内重复发同一条链接，不会一遍一遍重新出面板了。
+- 推送消息下面多了「解析」按钮，点的是动态里带的那个作品（不是动态本身）。
+- 修：点「提取评论区图片」以前会变成把视频重新解析一遍。
+- 修：日志里的视频预览地址端口是空的、打不开。
 
 ## 3.10.2
 

package/lib/build-metadata.json

@@ -1,10 +1,10 @@
 {
-  "version": "3.11.0",
-  "buildTime": "2026-10-01T11:38:31.580Z",
-  "buildTimestamp": 1790854711588,
+  "version": "3.12.0",
+  "buildTime": "2026-10-01T15:04:46.055Z",
+  "buildTimestamp": 1790867086061,
   "name": "koishi-plugin-kkk",
   "description": "抖音 / B站 / 快手 / 小红书 视频解析与动态推送，带 QQ 交互面板与弹幕烧录（karin-plugin-kkk 的 Koishi 移植版）",
   "homepage": "https://github.com/maimai993/koishi-plugin-kkk#readme",
-  "commitHash": "71a4bb6c80dde7452a58b88d135bcc6a02c537f7",
-  "shortCommitHash": "71a4bb6"
+  "commitHash": "676659fbbdf78244670d22aee37bb7668ef73b42",
+  "shortCommitHash": "676659f"
 }

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/package.json

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

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,26 @@
+/** 离线自验：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(' , '))
+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']]
+for (const [startVersion, endVersion] of cases) {
+  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 ? '  ⚠ 返回了整份日志（没裁出来）' : '')
+  )
+}

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封面`（不带参数）时用它兜底 —— 按钮自己是带参数的，不走这条路。