koishi-plugin-kkk 3.11.1 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 更新日志
 
+## 3.12.0
+
+### 新：提取图片的按钮只能点一次
+
+卡片下面「提取封面图 / 提取评论区图片」这两个按钮以前可以一直点。有人一直点，
+群里就被同一张图刷屏，而且看不出是谁在点。
+
+现在**同一张卡片上的同一个按钮只放行一次**：
+
+- 再点不会往群里发任何东西（不再刷屏），但日志里会记下「这次是谁点的、之前是谁点过」，
+  真被人刷了能查出来；
+- 封面和评论区是两个按钮，各点各的，互不影响；换一个作品也照常能点；
+- 想再要一次，**重新发一遍链接**就行，新卡片下面的按钮又是可点的（不会被永久锁死）；
+- 自己手敲 `kkk封面` / `kkk评论` 不受这个限制，随时都能用。
+
+还有一处顺手修的：万一这次没发出去（图过期了、或者发送报错），这次点击**不算数**，
+再点一次还是能发 —— 以前那种「点一次就永久作废」的情况不会出现。
+
 ## 3.11.1
 
 这一版修的主要是两类事：**东西发不出去**，和**按钮点了没反应**。

package/lib/build-metadata.json

@@ -1,7 +1,7 @@
 {
-  "version": "3.11.1",
-  "buildTime": "2026-10-01T13:05:54.560Z",
-  "buildTimestamp": 1790859954564,
+  "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",

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