koishi-plugin-kkk 1.0.0

package/src/karin/module/utils/Network/constants.ts

@@ -0,0 +1,135 @@
+import type { AxiosRequestConfig } from 'node-karin/axios'
+import axios from 'node-karin/axios'
+
+/**
+ * 错误代码到中文描述的映射
+ */
+export const ERROR_CODE_MAP: Record<string, string> = {
+  // 网络连接错误
+  ECONNRESET: '连接被重置',
+  ECONNREFUSED: '连接被拒绝',
+  ECONNABORTED: '连接中止',
+  ETIMEDOUT: '连接超时',
+  ENETUNREACH: '网络不可达',
+  EHOSTUNREACH: '主机不可达',
+  ENOTFOUND: 'DNS解析失败',
+  EPIPE: '管道破裂',
+  EAI_AGAIN: 'DNS临时失败',
+
+  // Axios 特定错误代码
+  ERR_BAD_OPTION_VALUE: '无效的配置选项值',
+  ERR_BAD_OPTION: '无效的配置选项',
+  ERR_NETWORK: '网络错误',
+  ERR_DEPRECATED: '使用了已弃用的功能',
+  ERR_BAD_RESPONSE: '无效的响应',
+  ERR_BAD_REQUEST: '无效的请求',
+  ERR_CANCELED: '请求被取消',
+  ERR_NOT_SUPPORT: '不支持的功能',
+  ERR_INVALID_URL: '无效的URL',
+
+  // HTTP 状态码相关
+  EHTTP: 'HTTP错误',
+
+  // 其他常见错误
+  EACCES: '权限不足',
+  ENOENT: '文件或目录不存在',
+  EMFILE: '打开的文件过多',
+  ENOSPC: '磁盘空间不足'
+}
+
+/**
+ * 可恢复的错误代码列表
+ */
+export const RECOVERABLE_ERROR_CODES = [
+  'ECONNRESET', // 连接被重置（代理切换、网络切换、服务器断流）
+  'ETIMEDOUT', // 连接超时
+  'ECONNREFUSED', // 连接被拒绝
+  'ENOTFOUND', // DNS解析失败
+  'ENETUNREACH', // 网络不可达
+  'EHOSTUNREACH', // 主机不可达
+  'EPIPE', // 管道破裂
+  'EAI_AGAIN', // DNS临时失败
+  'ECONNABORTED' // 连接中止
+]
+
+/**
+ * 可恢复错误的关键词
+ */
+export const RECOVERABLE_KEYWORDS = ['aborted', 'timeout', 'network', 'ECONNRESET', 'socket hang up', 'connection reset']
+
+/**
+ * Chrome 版本数据地址
+ * @remarks
+ * 访问失败时将自动尝试代理站
+ */
+const CHROME_VERSIONS_URL = 'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions.json'
+/**
+ * 代理前缀
+ * @remarks
+ * 直接将目标地址拼接在此域名后面即可
+ */
+const PROXY_PREFIX = 'https://jiashu.1win.eu.org/'
+
+/**
+ * 构建浏览器 UA 字符串
+ * @param version - Chrome 版本号，例如 `146.0.7680.76`
+ * @returns UA 字符串
+ */
+const buildUserAgent = (version: string): string =>
+  `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${version} Safari/537.36 Edg/${version}`
+
+/**
+ * 获取最新稳定版 Chrome 版本号
+ * @param url - 版本源地址
+ * @param proxyPrefix - 代理前缀地址，当直连失败时使用
+ * @returns 成功返回版本号，失败返回 null
+ */
+const fetchLatestChromeVersion = async (url: string, proxyPrefix: string): Promise<string | null> => {
+  try {
+    const resp = await axios.get(url, { timeout: 15000 })
+    const version: unknown = resp.data?.channels?.Stable?.version
+    return typeof version === 'string' && version.length > 0 ? version : null
+  } catch {
+    try {
+      const resp = await axios.get(`${proxyPrefix}${url}`, { timeout: 15000 })
+      const version: unknown = resp.data?.channels?.Stable?.version
+      return typeof version === 'string' && version.length > 0 ? version : null
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * 默认 UA 字符串（降级兜底）
+ */
+const DEFAULT_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36 Edg/137.0.0.0'
+
+/**
+ * 动态解析得到的 UA
+ * @remarks
+ * 优先使用「最新稳定版」Chrome 版本；失败时回退到内置 UA
+ */
+// Koishi 移植：原实现用顶层 await 拉取最新 Chrome 版本（CJS 构建不支持顶层 await），
+// 改为先用内置 UA，随后在后台异步刷新。
+const RESOLVED_UA: string = DEFAULT_UA
+
+/**
+ * 默认请求头
+ */
+export const BASE_HEADERS: AxiosRequestConfig['headers'] = {
+  Accept: '*/*',
+  'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6',
+  'User-Agent': RESOLVED_UA
+}
+
+// 后台刷新 UA（失败保持内置兜底，不影响请求）
+void (async () => {
+  try {
+    const latest = await fetchLatestChromeVersion(CHROME_VERSIONS_URL, PROXY_PREFIX)
+    if (latest) BASE_HEADERS['User-Agent'] = buildUserAgent(latest)
+  } catch {
+    // 忽略：保持 DEFAULT_UA
+  }
+})()

package/src/karin/module/utils/Network/helpers.ts

@@ -0,0 +1,183 @@
+import type { AxiosRequestConfig } from 'node-karin/axios'
+import { AxiosError } from 'node-karin/axios'
+
+import { ERROR_CODE_MAP, RECOVERABLE_ERROR_CODES, RECOVERABLE_KEYWORDS } from './constants'
+
+/**
+ * 获取错误的中英文描述
+ * @param error 错误对象
+ * @returns 格式化的错误描述
+ */
+export const getErrorDescription = (error: any): string => {
+  const code = error?.code || (error instanceof AxiosError ? error.code : null)
+  const message = error?.message || String(error)
+
+  if (code && ERROR_CODE_MAP[code]) {
+    return `${ERROR_CODE_MAP[code]} (${code}): ${message}`
+  } else if (code) {
+    return `错误代码 ${code}: ${message}`
+  } else {
+    return message
+  }
+}
+
+/**
+ * 脱敏处理IP地址
+ * @param text 包含IP的文本
+ * @returns 脱敏后的文本
+ */
+export const sanitizeIP = (text: string): string => {
+  if (!text) return text
+
+  // IPv4 脱敏: 192.168.1.1 -> 192.168.*.*
+  text = text.replace(/\b(\d{1,3}\.\d{1,3})\.\d{1,3}\.\d{1,3}\b/g, '$1.*.*')
+
+  // IPv6 脱敏: 2001:0db8:85a3::8a2e:0370:7334 -> 2001:0db8:****
+  text = text.replace(/\b([0-9a-fA-F]{1,4}:[0-9a-fA-F]{1,4}):[0-9a-fA-F:]+\b/g, '$1:****')
+
+  return text
+}
+
+/**
+ * 脱敏处理敏感请求头信息
+ * @param headers 原始请求头
+ * @returns 脱敏后的请求头（敏感字段直接删除）
+ */
+export const sanitizeHeaders = (headers: Record<string, string> | AxiosRequestConfig['headers']): Record<string, string> => {
+  if (!headers) return {}
+
+  const sanitized: Record<string, string> = {}
+  const sensitiveKeys = ['cookie', 'cookies', 'authorization', 'x-api-key', 'api-key', 'token']
+  const ipSensitiveKeys = ['x-forwarded-for', 'x-real-ip', 'x-client-ip', 'x-originating-ip']
+
+  for (const [key, value] of Object.entries(headers)) {
+    const lowerKey = key.toLowerCase()
+
+    // 敏感字段直接跳过，不添加到结果中
+    if (sensitiveKeys.some((sk) => lowerKey.includes(sk))) {
+      continue
+    }
+    // IP 相关字段也直接跳过
+    if (ipSensitiveKeys.some((sk) => lowerKey.includes(sk))) {
+      continue
+    }
+    // 其他字段保留
+    sanitized[key] = String(value)
+  }
+
+  return sanitized
+}
+
+/**
+ * 判断错误是否为可恢复的网络错误
+ * @param error 错误对象
+ * @returns 是否为可恢复错误
+ */
+export const isRecoverableNetworkError = (error: any): boolean => {
+  // 检查错误代码
+  if (error?.code && RECOVERABLE_ERROR_CODES.includes(error.code)) {
+    return true
+  }
+
+  // 检查 AxiosError
+  if (error instanceof AxiosError) {
+    if (error.code && RECOVERABLE_ERROR_CODES.includes(error.code)) {
+      return true
+    }
+
+    const errorMessage = error.message?.toLowerCase() || ''
+    if (RECOVERABLE_KEYWORDS.some((keyword) => errorMessage.includes(keyword.toLowerCase()))) {
+      return true
+    }
+  }
+
+  // 检查普通 Error
+  if (error instanceof Error) {
+    const errorMessage = error.message?.toLowerCase() || ''
+    if (RECOVERABLE_KEYWORDS.some((keyword) => errorMessage.includes(keyword.toLowerCase()))) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * 判断是否为服务器断流（风控）导致的错误
+ * @param error 错误对象
+ * @returns 是否为断流错误
+ */
+export const isThrottlingError = (error: any): boolean => {
+  const code = error?.code || (error instanceof AxiosError ? error.code : null)
+
+  // ECONNRESET 是最常见的断流错误
+  if (code === 'ECONNRESET') {
+    return true
+  }
+
+  // 检查错误消息
+  const message = error?.message?.toLowerCase() || ''
+  const throttlingKeywords = ['connection reset', 'socket hang up', 'econnreset']
+
+  return throttlingKeywords.some((keyword) => message.includes(keyword))
+}
+
+/**
+ * 计算指数退避延迟
+ * @param retryCount 当前重试次数
+ * @param baseDelay 基础延迟（毫秒）
+ * @param maxDelay 最大延迟（毫秒）
+ * @returns 延迟时间（毫秒）
+ */
+export const calculateBackoffDelay = (retryCount: number, baseDelay = 1000, maxDelay = 8000): number => {
+  return Math.min(2 ** retryCount * baseDelay, maxDelay)
+}
+
+/**
+ * 格式化字节数为可读字符串
+ * @param bytes 字节数
+ * @returns 格式化后的字符串
+ */
+export const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(2)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`
+}
+
+/**
+ * 从响应头中提取文件总字节数
+ * @param headers 响应头
+ * @returns 文件总大小，无法提取时返回 0
+ */
+export const extractTotalBytesFromHeaders = (headers?: Record<string, unknown> | null): number => {
+  if (!headers) return 0
+
+  const contentRange = headers['content-range']
+  const contentRangeText = Array.isArray(contentRange) ? contentRange[0] : String(contentRange ?? '')
+  const rangeMatch = contentRangeText.match(/\/(\d+)(?:\s*$)/)
+  if (rangeMatch) {
+    return Number.parseInt(rangeMatch[1], 10)
+  }
+
+  const contentLength = headers['content-length']
+  const contentLengthText = Array.isArray(contentLength) ? contentLength[0] : String(contentLength ?? '')
+  const parsedLength = Number.parseInt(contentLengthText, 10)
+
+  return Number.isFinite(parsedLength) ? parsedLength : 0
+}
+
+/**
+ * 清理文件名，移除不安全字符
+ * @param filename 原始文件名
+ * @returns 安全的文件名
+ */
+export const sanitizeFilename = (filename: string): string => {
+  // 替换非法符号 + 控制字符
+  return filename
+    .replace(/[<>:"/\\|?*\p{Cc}]/gu, '_')
+    .replace(/^\.+/, '')
+    .replace(/\.+$/, '')
+    .replace(/\s+/g, '_')
+    .substring(0, 200)
+}

package/src/karin/module/utils/Network/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Network 模块
+ * 提供网络请求、文件下载（支持限速和断点续传）等功能
+ */
+
+export { BASE_HEADERS } from './constants'
+export { Downloader } from './Downloader'
+export {
+  calculateBackoffDelay,
+  extractTotalBytesFromHeaders,
+  formatBytes,
+  getErrorDescription,
+  isRecoverableNetworkError,
+  isThrottlingError,
+  sanitizeFilename,
+  sanitizeHeaders
+} from './helpers'
+export type { ImageDownloadResult } from './ImageDownloader'
+export { ImageDownloader } from './ImageDownloader'
+export { Network } from './Network'
+// 为了向后兼容，同时导出 Networks 别名
+export { Network as Networks } from './Network'
+export { ThrottleStream } from './ThrottleStream'
+export type { CustomAxiosRequestConfig, DownloadResult, ProgressCallback, ThrottleConfig } from './types'
+export { DEFAULT_THROTTLE_CONFIG } from './types'
+
+// 为了向后兼容，导出 baseHeaders 别名
+export { BASE_HEADERS as baseHeaders } from './constants'

package/src/karin/module/utils/Network/types.ts

@@ -0,0 +1,46 @@
+import type { AxiosRequestConfig } from 'node-karin/axios'
+
+/**
+ * 扩展 AxiosRequestConfig 以支持内部重试计数和跳过重试
+ */
+export interface CustomAxiosRequestConfig extends AxiosRequestConfig {
+  __retryCount?: number
+  skipRetry?: boolean
+}
+
+/**
+ * 下载进度回调函数类型
+ */
+export type ProgressCallback = (downloadedBytes: number, totalBytes: number) => void
+
+/**
+ * 下载结果类型
+ */
+export interface DownloadResult {
+  filepath: string
+  totalBytes: number
+}
+
+/**
+ * 限速配置
+ */
+export interface ThrottleConfig {
+  /** 是否启用限速，默认 true */
+  enabled: boolean
+  /** 最大下载速度 (bytes/s)，默认 10MB/s */
+  maxSpeed: number
+  /** 检测到断流后自动降速的比例，默认 0.7 (降到 70%) */
+  autoReduceRatio: number
+  /** 最小速度限制 (bytes/s)，默认 1MB/s */
+  minSpeed: number
+}
+
+/**
+ * 默认限速配置
+ */
+export const DEFAULT_THROTTLE_CONFIG: ThrottleConfig = {
+  enabled: true,
+  maxSpeed: 10 * 1024 * 1024, // 10 MB/s
+  autoReduceRatio: 0.7,
+  minSpeed: 1 * 1024 * 1024 // 1 MB/s
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @deprecated 请使用 './Network' 模块
+ * 此文件保留用于向后兼容
+ */
+export type { CustomAxiosRequestConfig, DownloadResult, ProgressCallback, ThrottleConfig } from './Network'
+export {
+  BASE_HEADERS,
+  baseHeaders,
+  DEFAULT_THROTTLE_CONFIG,
+  Downloader,
+  extractTotalBytesFromHeaders,
+  formatBytes,
+  getErrorDescription,
+  isRecoverableNetworkError,
+  isThrottlingError,
+  Network,
+  Networks,
+  sanitizeHeaders,
+  ThrottleStream
+} from './Network'

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

@@ -0,0 +1,33 @@
+/**
+ * 解析去重锁。
+ *
+ * 同一次点击可能被 QQ 投递两遍（指令按钮既发消息又发交互事件、用户连点、客户端重发），
+ * 而解析本身是重活（取流 + 下载 + 发送），跑两遍的后果是：
+ * 用户看到两次「检测到链接，开始解析」，第二次还会因为缓存已被清理而失败。
+ *
+ * 这里按「会话 + 作品 + 画质 + 弹幕开关」在短时间内只放行一次；
+ * 换画质/换解析内容属于不同的键，不会被误伤。
+ */
+
+/** 去重窗口（毫秒） */
+const WINDOW = 20 * 1000
+
+const recent = new Map<string, number>()
+
+/**
+ * 尝试取得一次解析许可。
+ * @param key 去重键（建议包含会话、作品 ID、画质与弹幕开关）
+ * @returns true = 可以解析；false = 刚刚已经跑过一次，忽略
+ */
+export function acquireParseLock (key: string): boolean {
+  const now = Date.now()
+  for (const [item, at] of recent) {
+    if (now - at > WINDOW) recent.delete(item)
+  }
+  const last = recent.get(key)
+  if (last !== undefined && now - last < WINDOW) return false
+  recent.set(key, now)
+  return true
+}
+
+export default acquireParseLock

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

@@ -0,0 +1,128 @@
+/**
+ * 单条消息的解析参数覆盖（画质 / 弹幕）。
+ *
+ * ## 为什么需要它
+ * QQ 平台的交互面板（见 module/utils/QqPanel.ts）让用户点按钮选画质，
+ * 但画质是**深埋在**业务代码里的全局配置读取：\`Config.bilibili.videoQuality\` 在
+ * 取流、选流、下载各写了一次，把参数一层层传下去要改十几个函数签名。
+ *
+ * 这里用 AsyncLocalStorage 把「本次解析的选择」挂在异步上下文上，
+ * Config 的 Proxy 读取时优先取覆盖值 —— 业务代码一行都不用改，
+ * 定时推送、其它会话也不会被串味（上下文只在本条消息的处理链里生效）。
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/** 一次解析的参数覆盖 */
+export interface ParseOverride {
+  /** B站画质 qn（见 bilibili.yaml 的 videoQuality） */
+  bilibiliQuality?: number
+  /** 抖音画质档位（4k / 2k / 1080p / 720p / 540p / adapt） */
+  douyinQuality?: string
+  /** 小红书画质档位 */
+  xiaohongshuQuality?: string
+  /** 强制烧录弹幕（等价于用「#弹幕解析」触发） */
+  burnDanmaku?: boolean
+  /**
+   * 本次解析是**从 QQ 面板按钮点进来的**。
+   *
+   * 面板已经把卡片图发过了，所以解析时不再重复发提示语和预览卡片，
+   * 只回一句「收到请求，开始下载」，再直接给下载结果。
+   */
+  fromPanel?: boolean
+  /** 面板里这一档画质的预估体积（MB），用于提示「超过 30MB 会以文件发送」 */
+  estimatedSizeMB?: number
+  /** 番剧分集表格要出第几页（面板上的「上一页 / 下一页」） */
+  bangumiPage?: number
+}
+
+const storage = new AsyncLocalStorage<ParseOverride>()
+
+/**
+ * 在参数覆盖的上下文里执行解析。
+ * @param override 覆盖项（空对象则直接执行）
+ * @param fn 解析逻辑
+ */
+export function runWithParseOverride<T> (override: ParseOverride, fn: () => Promise<T>): Promise<T> {
+  if (!override || !Object.keys(override).length) return fn()
+  return storage.run(override, fn)
+}
+
+/** 当前上下文里的覆盖项（不在解析链路里时返回 undefined） */
+export function getParseOverride (): ParseOverride | undefined {
+  return storage.getStore()
+}
+
+/** 从消息文本里解析出来的参数 */
+export interface ParseFlags {
+  /** 面板按钮的短令牌（\`--p=xxx\`），调用方用它换回真实链接 */
+  panelToken?: string
+  /** 覆盖项 */
+  override: ParseOverride
+  /** 去掉参数后的消息文本 */
+  cleaned: string
+  /** 是否出现了任何参数（用于判断这条消息是不是面板点出来的） */
+  hasAny: boolean
+  /** 面板重新渲染请求：0 纯视频 / 1 带弹幕；undefined 表示不是面板切换 */
+  panel?: 0 | 1
+  /** 番剧分集表格翻页：页码（配合 --p=<番剧令牌> 使用） */
+  bangumiPage?: number
+}
+
+/**
+ * 解析消息里的 \`--xxx\` 参数。
+ *
+ * 约定（按钮 action.data 与手工输入通用，所以刻意做得短、好敲）：
+ *   - \`--qn=80\`    B站画质
+ *   - \`--q=1080p\`  抖音/小红书画质
+ *   - \`--dm=1\`     烧录弹幕
+ *   - \`--panel=1\`  只重发面板（1 = 带弹幕，0 = 纯视频）
+ *   - \`--p=abc123\` 面板按钮的短令牌（真实链接存在插件内存里，见 QqPanel）
+ * @param msg 消息文本
+ * @returns 解析结果
+ */
+export function parseParseFlags (msg: string): ParseFlags {
+  const text = String(msg ?? '')
+  const override: ParseOverride = {}
+  let hasAny = false
+  let panel: 0 | 1 | undefined
+  let panelToken: string | undefined
+  let bangumiPage: number | undefined
+
+  const cleaned = text
+    .replace(/\s*--p=([0-9a-z]+)/i, (_all, value: string) => {
+      panelToken = value
+      hasAny = true
+      return ''
+    })
+    .replace(/\s*--qn=(\d+)/gi, (_all, value: string) => {
+      override.bilibiliQuality = Number(value)
+      hasAny = true
+      return ''
+    })
+    .replace(/\s*--q=([0-9a-z]+)/gi, (_all, value: string) => {
+      override.douyinQuality = value
+      override.xiaohongshuQuality = value
+      hasAny = true
+      return ''
+    })
+    .replace(/\s*--dm=1/gi, () => {
+      override.burnDanmaku = true
+      hasAny = true
+      return ''
+    })
+    .replace(/\s*--panel=([01])/gi, (_all, value: string) => {
+      panel = value === '1' ? 1 : 0
+      hasAny = true
+      return ''
+    })
+    .replace(/\s*--bgp=(\d+)/gi, (_all, value: string) => {
+      bangumiPage = Number(value)
+      hasAny = true
+      return ''
+    })
+    .trim()
+
+  return { override, cleaned, hasAny, panel, panelToken, bangumiPage }
+}
+
+export default parseParseFlags

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

@@ -0,0 +1,116 @@
+/**
+ * QQ 卡片「无链接」还原。
+ *
+ * QQ 官方适配器把分享卡片整段当文本丢进来，而新版卡片**连跳转链接都没有**，
+ * 于是各平台的链接正则一条都匹配不上 —— 用户侧的表现就是「卡片发出来没反应」。
+ * 这里把卡片（详见 compat/qqcard.ts）还原成一条规范链接，追加到消息文本末尾，
+ * 让原有的解析命令照常命中：命令本身仍按前缀匹配，普通消息完全不受影响。
+ *
+ * 匹配策略（强 → 弱）：
+ *   1. 卡片自带 B 站链接（b23.tv / bilibili.com）→ 直接规范化；
+ *   2. 卡片封面哈希 == 搜索结果的 \`pic\` 哈希 → 同一张稿件封面，直接认定；
+ *   3. 标题包含/相等（打分 ≥ 60）→ 认定。
+ * 认不出来就**不还原**，宁可让下游提示「未找到链接」，也不要猜错视频解析出别人的内容。
+ */
+import { logger } from 'node-karin'
+
+import { parseQqCards, type QqCard } from '../../../compat/qqcard'
+import { extractUrls, normalizeMessageText } from '../../../compat/text'
+import { resolveBiliCanonicalUrl, searchBilibiliVideos } from '@/platform/bilibili/search'
+
+/** B 站链接特征（消息里已经有链接就不用还原了） */
+const BILI_URL = /bilibili\.com|b23\.tv|bili2233|\bBV[0-9A-Za-z]{10}\b/i
+
+/** 还原结果缓存：同一条卡片消息会被匹配、命令、统计等多处读取，没必要重复搜索 */
+const cache = new Map<string, string>()
+const CACHE_LIMIT = 64
+
+/** 认不认这条搜索结果 */
+const isConfident = (item: { coverMatch: boolean; score: number }): boolean => item.coverMatch || item.score >= 60
+
+/** 纯平台名/占位词，拿去搜索只会搜到无关视频 */
+const GENERIC_TITLE = /^(哔哩哔哩|bilibili|视频|弹幕|分享|网页链接|抖音|快手|小红书)+$/i
+
+/**
+ * 标题是否值得拿去搜索。
+ * 卡片字段缺失时标题可能是「哔哩哔哩」这类来源名，与其拿它赌一个视频，不如放弃还原。
+ * @param title 卡片标题
+ */
+const isSearchableTitle = (title: string): boolean => {
+  const key = String(title ?? '').replace(/\s+/g, '')
+  return key.length >= 4 && !GENERIC_TITLE.test(key)
+}
+
+/**
+ * 把一张 B 站卡片还原成规范视频链接。
+ * @param card 卡片
+ * @returns 规范链接；无法确定时返回空串
+ */
+export async function resolveBiliCard (card: QqCard): Promise<string> {
+  const inline = card.urls.find((url) => BILI_URL.test(url) || /\bBV[0-9A-Za-z]{10}\b/.test(url))
+  if (inline) return await resolveBiliCanonicalUrl(inline)
+  if (!isSearchableTitle(card.title)) {
+    logger.debug('[QQ卡片] 标题「' + card.title + '」过于宽泛，放弃搜索还原')
+    return ''
+  }
+
+  const items = await searchBilibiliVideos({
+    keyword: card.title,
+    title: card.title,
+    author: card.author,
+    cover: card.cover,
+    limit: 8
+  })
+  const best = items.find(isConfident)
+  if (!best) {
+    logger.debug('[QQ卡片] 标题「' + card.title + '」没有找到足够可信的B站视频，放弃还原' + (items[0] ? '（最高分 ' + items[0].score + '：' + items[0].title + '）' : ''))
+    return ''
+  }
+  logger.debug('[QQ卡片] 还原B站视频: ' + best.title + ' → ' + best.bvid + '（分数 ' + best.score + (best.coverMatch ? '，封面命中' : '') + '）')
+  return 'https://www.bilibili.com/video/' + best.bvid
+}
+
+/**
+ * 归一化一条消息文本：JSON 转义还原 + 已有链接提取 + 无链接卡片搜索还原。
+ *
+ * 普通消息走同步快路径（一次 \`includes('{')\` 就返回），只有疑似卡片的文本才会触发网络搜索。
+ * @param content 原始消息文本
+ * @returns 可交给解析命令的文本
+ */
+export async function resolveQqCardContent (content: string): Promise<string> {
+  const raw = String(content ?? '')
+  const base = normalizeMessageText(raw)
+  if (!raw || !raw.includes('{')) return base
+
+  const cached = cache.get(raw)
+  if (cached !== undefined) return cached
+
+  const result = await resolveCards(raw, base)
+  if (cache.size >= CACHE_LIMIT) cache.delete(cache.keys().next().value as string)
+  cache.set(raw, result)
+  return result
+}
+
+/** 实际的还原逻辑（与缓存分开，便于阅读） */
+async function resolveCards (raw: string, base: string): Promise<string> {
+  const cards = parseQqCards(raw)
+  if (!cards.length) return base
+  // 已经有 B 站链接的消息不用还原：解析命令自己就能处理短链
+  if (extractUrls(base).some((url) => BILI_URL.test(url))) return base
+
+  const targets = cards.filter((card) => card.platform === 'bilibili' && isSearchableTitle(card.title)).slice(0, 2)
+  if (!targets.length) return base
+
+  const extra: string[] = []
+  for (const card of targets) {
+    try {
+      const url = await resolveBiliCard(card)
+      if (url && !base.includes(url) && !extra.includes(url)) extra.push(url)
+    } catch (error) {
+      logger.debug('[QQ卡片] 还原失败: ' + String(error))
+    }
+  }
+  return extra.length ? base + ' ' + extra.join(' ') : base
+}
+
+export default resolveQqCardContent