koishi-plugin-kkk 1.0.0

package/src/compat/phosphor-icons.tsx

@@ -0,0 +1,25 @@
+/**
+ * `@phosphor-icons/react` 的替代实现。
+ *
+ * 为什么要替：这个包 **本身有 bug** —— 它的 package.json 是 `"type": "module"`，
+ * 但 `exports.require` 指向 `./dist/index.cjs.js`（`.js` 在 ESM 包里会被当成 ESM ✗），
+ * 于是模板一旦 `require` 它就抛：
+ *   `exports is not defined in ES module scope ... @phosphor-icons/react/package.json contains "type": "module"`
+ * 结果是**所有卡片模板都加载失败、退化成通用兜底卡**（用户看到的就是「模板怎么崩了」）。
+ *
+ * 这里接一层：用已经在依赖里的 `lucide-react`（CJS 正常 ✓）逐个映射成同名导出，
+ * 调用方（模板）不用改任何代码，图标风格略有差异但卡片能正常渲染。
+ */
+export {
+  Clock as ClockIcon,
+  Image as ImageIcon,
+  MapPin as MapPinIcon,
+  Music as MusicNoteIcon,
+  Play as PlayIcon,
+  Play,
+  CircleHelp as Question,
+  UserPlus as UserPlusIcon,
+  Users as UsersIcon,
+  UsersRound as UsersThreeIcon,
+  Video as VideoCameraIcon
+} from 'lucide-react'

package/src/compat/qqcard.ts

@@ -0,0 +1,251 @@
+/**
+ * QQ 分享卡片解析 + 「无链接卡片」还原。
+ *
+ * ## 背景
+ * QQ 官方适配器（koishi-plugin-adapter-qq-crack，platform=\`qqguild\`）把卡片消息**整段塞进文本**，
+ * 不同来源的卡片长的也不一样，常见三种：
+ *
+ * \`\`\`text
+ * // 1. 小程序卡片（B站/抖音），meta.detail_1 里带 qqdocurl
+ * {"app":"com.tencent.structmsg","meta":{"detail_1":{"qqdocurl":"https:\\/\\/b23.tv\\/xxxx"}}}
+ * // 2. 新版分享卡片，链接在 meta.news.jumpUrl
+ * {"app":"com.tencent.structmsg","view":"news","meta":{"news":{"tag":"哔哩哔哩","title":"...","jumpUrl":"..."}}}
+ * // 3. 只有标题和封面，**一个链接都没有**（QQ 端把跳转吞了）
+ * {"app":"com.tencent.miniapp_01","desc":"哔哩哔哩","meta":{"detail_1":{"appid":"1109937557","title":"..."}}}
+ * \`\`\`
+ *
+ * 第 3 种是纯解析链路救不回来的：插件拿到的文本里没有 URL，各平台的链接正则必然匹配不到。
+ * koishi-plugin-qq-chat 的做法是「标题 + 封面 OCR 出的 UP 主」去 B 站搜索匹配；
+ * 这里做得更直接 —— 卡片封面往往就是 B 站图床的稿件封面，
+ * 直接用**封面哈希**和搜索结果里的 \`pic\` 对齐（见 platform/bilibili/search.ts），
+ * 哈希认不出来再退化成标题/作者打分。
+ *
+ * 因此本模块只做两件事：
+ *   1. {@link parseQqCards}：把消息文本里的卡片 JSON 挖出来，归一化成 {@link QqCard}；
+ *   2. {@link resolveCardsInText}：对「没有链接的 B 站卡片」做搜索还原，把规范链接追加到文本末尾，
+ *      让下游的解析命令照常命中（命令本身仍按前缀匹配，不受影响）。
+ */
+
+/** 平台标识 */
+export type QqCardPlatform = 'bilibili' | 'douyin' | 'kuaishou' | 'xiaohongshu' | 'unknown'
+
+/** 归一化后的 QQ 卡片 */
+export interface QqCard {
+  /** ark 的 app 字段，例如 com.tencent.structmsg */
+  app: string
+  /** ark 的 view 字段，例如 news */
+  view: string
+  /** 归一化出的平台 */
+  platform: QqCardPlatform
+  /** 标题（优先 meta 里的 title，其次 desc / prompt） */
+  title: string
+  /** 描述文本 */
+  desc: string
+  /** UP 主 / 作者（卡片里有就取，没有留空） */
+  author: string
+  /** 封面图地址 */
+  cover: string
+  /** 卡片里能挖到的所有 http(s) 链接 */
+  urls: string[]
+  /** 原始 JSON 对象 */
+  raw: any
+}
+
+/** 小程序 appid → 平台 */
+const APPID_PLATFORM: Record<string, QqCardPlatform> = {
+  // 哔哩哔哩小程序
+  '1109937557': 'bilibili',
+  // 抖音小程序
+  '1109937556': 'douyin',
+  '1110083189': 'douyin',
+  // 快手小程序
+  '1109937559': 'kuaishou'
+}
+
+/** 文本特征 → 平台 */
+const TEXT_PLATFORM: Array<{ platform: QqCardPlatform; pattern: RegExp }> = [
+  { platform: 'bilibili', pattern: /哔哩哔哩|bilibili|b23\.tv|bili2233|\bBV[0-9A-Za-z]{10}\b/i },
+  { platform: 'douyin', pattern: /抖音|douyin|iesdouyin/i },
+  { platform: 'kuaishou', pattern: /快手|kuaishou/i },
+  { platform: 'xiaohongshu', pattern: /小红书|xiaohongshu|xhslink/i }
+]
+
+/** 取字段用的键名表 */
+const TITLE_KEYS = /^(title|desc|description|summary|subtitle|prompt|tag|source|from|appname)$/i
+/**
+ * 「真标题」键名。
+ *
+ * 必须和 {@link TITLE_KEYS} 区分开：ark 里 `desc`/`tag` 是「哔哩哔哩」这种来源名，
+ * 而它们**排在 title 前面**，混在一起取第一个字段会把来源名当成视频标题
+ * （后果是拿「哔哩哔哩」去搜索，匹配到完全无关的视频）。
+ */
+const REAL_TITLE_KEY = /^title$/i
+const COVER_KEYS = /^(preview|icon|image|imageurl|picurl|pic|cover|coverurl|thumb|thumbnail|img|imgurl|headimg)$/i
+const URL_KEYS = /^(jumpurl|qqdocurl|url|contenturl|shareurl|link|targeturl|weburl|h5url|pageurl|sourceurl)$/i
+const AUTHOR_KEYS = /^(author|nickname|nick|upname|up_name|username|name|uploader)$/i
+
+/** JSON 转义还原（与 compat/text.ts 保持同一套规则，但这里要能解析回对象） */
+function unescapeJson (input: string): string {
+  return input
+    .replace(/\\u002[fF]/g, '/')
+    .replace(/\\\//g, '/')
+    .replace(/\\"/g, '"')
+    .replace(/\\u0026/gi, '&')
+}
+
+/**
+ * 从一段文本里挖出所有「括号配平」的 JSON 对象字面量。
+ *
+ * 不能用 \`/\{[^{}]*\}/\` 这类正则：ark 是嵌套结构，正则只能匹配到最内层；
+ * 也不能按 \`{"app"\` 切分：一张卡片里可能同时出现多个对象（实测有 \`meta\` 和 \`config\`）。
+ * 所以老老实实扫一遍括号，并且**跳过字符串内部的括号**（卡片里就有标题带花括号的）。
+ * @param text 原始文本
+ * @returns JSON 子串数组
+ */
+export function extractJsonObjects (text: string): string[] {
+  const result: string[] = []
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') { inString = true; continue }
+    if (char === '{') {
+      if (depth === 0) start = i
+      depth += 1
+      continue
+    }
+    if (char === '}') {
+      if (depth > 0) {
+        depth -= 1
+        if (depth === 0 && start >= 0) result.push(text.slice(start, i + 1))
+      }
+      continue
+    }
+  }
+  return result
+}
+
+/** 递归收集卡片里的文本 / 封面 / 链接 / 作者字段（保持出现顺序，去重） */
+function collectFields (node: any, bucket: { titles: string[]; texts: string[]; covers: string[]; urls: string[]; authors: string[]; appids: string[] }, depth = 0): void {
+  if (!node || typeof node !== 'object' || depth > 8) return
+  if (Array.isArray(node)) {
+    for (const item of node) collectFields(item, bucket, depth + 1)
+    return
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (typeof value === 'string') {
+      const text = value.trim()
+      if (!text) continue
+      if (key === 'appid') { bucket.appids.push(text); continue }
+      const isUrlLike = /^https?:\/\//i.test(text) || text.startsWith('//')
+
+      // 判定顺序很关键：按「键名」判断必须早于「值长得像 URL」。
+      // 卡片封面（preview/icon）的值本身就是 http 链接，先按值判会把封面当跳转链接收进 urls，
+      // 结果就是 cover 永远是空 —— 封面哈希这条最硬的匹配路径直接失效。
+      if (URL_KEYS.test(key) && !COVER_KEYS.test(key)) { bucket.urls.push(text); continue }
+      if (COVER_KEYS.test(key)) {
+        if (isUrlLike) bucket.covers.push(text)
+        continue
+      }
+      if (REAL_TITLE_KEY.test(key)) { bucket.titles.push(text); continue }
+      if (TITLE_KEYS.test(key)) { bucket.texts.push(text); continue }
+      if (AUTHOR_KEYS.test(key)) { bucket.authors.push(text); continue }
+      if (isUrlLike) { bucket.urls.push(text); continue }
+      // 兜底：任何字符串里的 URL 也收进来（有的卡片把链接塞在 desc 里）
+      const matched = text.match(/https?:\/\/[^\s"'<>\\]+/gi)
+      if (matched) for (const url of matched) bucket.urls.push(url)
+      continue
+    }
+    if (value && typeof value === 'object') collectFields(value, bucket, depth + 1)
+  }
+}
+
+/** 判定平台：appid 优先，其次看所有文本里的平台特征 */
+function detectPlatform (bucket: { titles: string[]; texts: string[]; covers: string[]; urls: string[]; appids: string[] }, app: string, view: string): QqCardPlatform {
+  for (const appid of bucket.appids) {
+    const platform = APPID_PLATFORM[appid]
+    if (platform) return platform
+  }
+  const haystack = [...bucket.titles, ...bucket.texts, ...bucket.covers, ...bucket.urls, app, view].join(' ')
+  for (const { platform, pattern } of TEXT_PLATFORM) {
+    if (pattern.test(haystack)) return platform
+  }
+  return 'unknown'
+}
+
+/** 从已经 JSON.parse 好的对象里归一化出一张卡片 */
+export function toQqCard (raw: any): QqCard | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  if (typeof raw.app !== 'string' && !raw.meta && !raw.prompt) return null
+
+  const bucket = { titles: [] as string[], texts: [] as string[], covers: [] as string[], urls: [] as string[], authors: [] as string[], appids: [] as string[] }
+  if (typeof raw.appid === 'string') bucket.appids.push(raw.appid)
+  collectFields(raw, bucket)
+
+  const app = typeof raw.app === 'string' ? raw.app : ''
+  const view = typeof raw.view === 'string' ? raw.view : ''
+  const prompt = typeof raw.prompt === 'string' ? raw.prompt.replace(/^\[[^\]]*\]\s*/, '') : ''
+
+  const unique = (list: string[]) => [...new Set(list.filter(Boolean))]
+  const texts = unique(bucket.texts)
+  const title = unique(bucket.titles)[0] ?? texts[0] ?? prompt
+  const desc = texts.find((text) => text !== title) ?? ''
+
+  return {
+    app,
+    view,
+    platform: detectPlatform(bucket, app, view),
+    title,
+    desc,
+    author: unique(bucket.authors)[0] ?? '',
+    cover: unique(bucket.covers)[0] ?? '',
+    urls: unique(bucket.urls),
+    raw
+  }
+}
+
+/**
+ * 解析一段消息文本里的所有 QQ 卡片。
+ * 普通聊天文本（没有 JSON 对象）返回空数组，代价只有一次括号扫描。
+ * @param input 消息原文（可以是 JSON 转义过的）
+ */
+export function parseQqCards (input: string): QqCard[] {
+  const text = String(input ?? '')
+  if (!text.includes('{')) return []
+  const cards: QqCard[] = []
+  const seen = new Set<string>()
+
+  for (const snippet of extractJsonObjects(text)) {
+    for (const candidate of [snippet, unescapeJson(snippet)]) {
+      try {
+        const card = toQqCard(JSON.parse(candidate))
+        if (!card) continue
+        const key = card.app + '|' + card.title + '|' + card.urls.join(',')
+        if (seen.has(key)) continue
+        seen.add(key)
+        cards.push(card)
+        break
+      } catch {
+        // 不是合法 JSON 就换下一种写法
+      }
+    }
+  }
+  return cards
+}
+
+/** 从卡片封面里取出 B 站图床的稿件哈希（\`.../bfs/archive/<hash>.jpg\`） */
+export function coverArchiveHash (url: unknown): string {
+  const matched = String(url ?? '').match(/\/bfs\/archive\/([0-9a-f]+)(?:\.\w+)?/i)
+  return matched ? matched[1].toLowerCase() : ''
+}
+
+export default parseQqCards

package/src/compat/root.ts

@@ -0,0 +1,44 @@
+/**
+ * `node-karin/root` 的兼容实现。
+ *
+ * 注意：karin 里 `karinPathBase` / `karinPathHtml` 是**字符串常量**（不是函数），
+ * 移植代码直接写 \`\${karinPathBase}/\${Root.pluginName}/config\`，所以这里按值导出。
+ * 值在模块首次 require 时确定，因此兼容层运行时必须在加载移植代码之前完成绑定。
+ */
+import path from 'node:path'
+
+import { PLUGIN_DIR_NAME, tryGetRuntime } from './runtime'
+
+/** Karin 的数据根目录 */
+export const karinPathBase: string = (() => {
+  const runtime = tryGetRuntime()
+  if (runtime) return runtime.dataRoot
+  // 兜底：允许在未绑定运行时时读取（例如工具脚本里）
+  return path.resolve(process.cwd(), 'data')
+})()
+
+/** 插件私有数据目录 */
+export const karinPathData: string = path.resolve(karinPathBase, PLUGIN_DIR_NAME, 'data')
+
+/**
+ * 渲染产物目录。
+ * 与 Karin 一致：这里只给根目录，具体子目录由调用方拼 \`\${karinPathHtml}/\${pluginName}\`。
+ */
+export const karinPathHtml: string = path.resolve(karinPathBase, 'html')
+
+/** 临时文件目录（同样只给根目录，Common.tempDri 会再拼一层插件名） */
+export const karinPathTemp: string = path.resolve(karinPathBase, 'temp')
+
+/** Karin 根目录（Koishi 下即插件根目录） */
+export const karinPathRoot: string = tryGetRuntime()?.pluginRoot ?? process.cwd()
+
+export const isDocker = () => false
+
+export default {
+  karinPathBase,
+  karinPathData,
+  karinPathHtml,
+  karinPathTemp,
+  karinPathRoot,
+  isDocker
+}

package/src/compat/runtime.ts

@@ -0,0 +1,120 @@
+/**
+ * 兼容层运行时状态。
+ *
+ * 原 koishi-plugin-kkk 的代码在模块顶层就会调用 `karin.command(...)` / `karin.task(...)`，
+ * 这些调用发生在 Koishi 插件 apply 之前，因此先进入队列，等 apply 时绑定 ctx 再统一落地。
+ */
+import path from 'node:path'
+
+import type { Context } from 'koishi'
+
+export interface KkkRuntimeConfig {
+  /** 主人账号（对应 karin 的 config.master()） */
+  masters: string[]
+  /** 调试日志 */
+  debug: boolean
+  /** 数据目录，默认 <baseDir>/data */
+  dataPath?: string
+  /** 控制台 API 令牌；留空时只允许本机访问 */
+  apiToken?: string
+  /** QQ 平台解析前先发交互面板（Markdown + 按钮）让用户选解析内容和画质 */
+  qqPanel?: boolean
+  /** QQ 面板里隐藏超过该体积（MB）的画质按钮；QQ 富媒体视频硬限制为 200MB */
+  qqFileLimitMB?: number
+}
+
+export interface KkkRuntime {
+  ctx: Context
+  config: KkkRuntimeConfig
+  /** 插件根目录（含 lib/、resources/） */
+  pluginRoot: string
+  /** 数据根目录 */
+  dataRoot: string
+}
+
+let runtime: KkkRuntime | null = null
+
+export function bindRuntime (value: KkkRuntime) {
+  runtime = value
+}
+
+export function tryGetRuntime (): KkkRuntime | null {
+  return runtime
+}
+
+export function getRuntime (): KkkRuntime {
+  if (!runtime) throw new Error('[kkk] Karin 兼容层尚未初始化，请通过 koishi-plugin-kkk 插件加载')
+  return runtime
+}
+
+/**
+ * Koishi 当前配置的命令前缀。
+ *
+ * 用户在 koishi.yml 里可以配多个，例如 \`['/', '']\`：\`''\` 表示「不带前缀直接敲指令」。
+ * 面板按钮要按这个来决定发出去的命令文本长什么样。
+ * @returns 前缀列表（可能是空串）
+ */
+export function commandPrefixes (): string[] {
+  const value = (tryGetRuntime()?.ctx as any)?.config?.prefix
+  if (Array.isArray(value)) {
+    const list = value.filter((item): item is string => typeof item === 'string')
+    if (list.length) return list
+  }
+  if (typeof value === 'string') return [value]
+  return ['']
+}
+
+/**
+ * 拼一条「用户视角」的指令文本（用于 QQ 面板按钮）。
+ * @param name 指令名，例如 \`解析\`
+ * @returns 带前缀的指令（配置了空前缀时就是指令名本身）
+ */
+export function commandInvocation (name: string): string {
+  const prefixes = commandPrefixes()
+  if (prefixes.includes('')) return name
+  return (prefixes.find((item) => item) ?? '') + name
+}
+
+/** 插件在数据目录下的子目录名（对应 karin 的 Root.pluginName） */
+export const PLUGIN_DIR_NAME = 'koishi-plugin-kkk'
+
+/** Karin 的数据根目录（等价 karinPathBase），移植代码按 \`\${karinPathBase}/\${pluginName}\` 组织文件 */
+export function karinPathBase (): string {
+  return getRuntime().dataRoot
+}
+
+/** 插件私有数据目录 */
+export function pluginDataDir (): string {
+  return path.resolve(karinPathBase(), PLUGIN_DIR_NAME)
+}
+
+/** 渲染产物目录 */
+export function karinPathHtml (): string {
+  return path.resolve(pluginDataDir(), 'html')
+}
+
+/** 临时文件目录 */
+export function karinPathTemp (): string {
+  return path.resolve(pluginDataDir(), 'temp')
+}
+
+export interface CommandRegistration {
+  reg: RegExp | string
+  handler: (...args: any[]) => any
+  options?: Record<string, any>
+  order: number
+}
+
+export interface TaskRegistration {
+  name: string
+  cron: string
+  handler: (...args: any[]) => any
+  options?: Record<string, any>
+}
+
+/** 模块顶层注册、等待 apply 落地的命令 */
+export const commandQueue: CommandRegistration[] = []
+/** 模块顶层注册、等待 apply 落地的定时任务 */
+export const taskQueue: TaskRegistration[] = []
+/** 模块顶层注册的事件监听 */
+export const eventQueue: Array<{ event: string; handler: (...args: any[]) => any }> = []

package/src/compat/segment.ts

@@ -0,0 +1,161 @@
+/**
+ * karin `segment` 的 Koishi 兼容实现。
+ *
+ * karin 的 segment 与 Koishi 的 `h`（Satori element）语义接近，
+ * 这里主要补两件事：把 `base64://` / `file://` / 本地路径统一成适配器能发的资源，以及补上残留的 QQ 专有段。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { h } from 'koishi'
+
+const MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.svg': 'image/svg+xml',
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.m4a': 'audio/mp4',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.silk': 'audio/silk',
+  '.amr': 'audio/amr'
+}
+
+const guessMime = (filePath: string, kind: 'image' | 'video' | 'audio' | 'file') => {
+  const ext = path.extname(filePath).toLowerCase()
+  if (MIME[ext]) return MIME[ext]
+  if (kind === 'image') return 'image/png'
+  if (kind === 'video') return 'video/mp4'
+  if (kind === 'audio') return 'audio/mpeg'
+  return 'application/octet-stream'
+}
+
+const asBuffer = (src: string, kind: 'image' | 'video' | 'audio' | 'file') => {
+  if (src.startsWith('base64://')) {
+    const raw = Buffer.from(src.slice('base64://'.length), 'base64')
+    return { data: raw, type: guessMime('.' + (kind === 'image' ? 'png' : kind === 'video' ? 'mp4' : 'mp3'), kind) }
+  }
+  if (src.startsWith('data:')) return null
+  if (/^[a-z]+:\/\//i.test(src) && !src.startsWith('file://')) return null
+  const filePath = src.startsWith('file://') ? fileURLToPath(src) : src
+  if (!fs.existsSync(filePath)) return null
+  return { data: fs.readFileSync(filePath), type: guessMime(filePath, kind) }
+}
+
+/** 把 karin 支持的资源写法统一成 Satori 元素可用的资源 */
+function resource (src: any, kind: 'image' | 'video' | 'audio' | 'file'): any {
+  if (Buffer.isBuffer(src) || src instanceof ArrayBuffer) return src
+  if (typeof src !== 'string') return String(src ?? '')
+  const buf = asBuffer(src, kind)
+  if (buf) return buf.data
+  if (src.startsWith('base64://')) return 'data:' + guessMime('', kind) + ';base64,' + src.slice(9)
+  return src
+}
+
+/**
+ * karin 的媒体段是 `{ type, file }`，而 Koishi 的元素把内容放在 `attrs.src`。
+ * 上游 karin 代码经常直接读 `segment.file`（例如登录二维码：`qrimg[0].file` →
+ * 落盘 + 发送），在 Koishi 下这个属性根本不存在，于是「生成二维码图片失败」。
+ *
+ * 这里给元素补一个**只读的 `file` 兼容属性**（不可枚举，不会进 JSON / 不会影响发送）：
+ *   - data URL → 还原成 karin 习惯的 `base64://xxx`
+ *   - 其它（http 链接 / 路径）原样返回
+ */
+function withKarinFile<T extends Record<string, any>> (element: T): T {
+  if (!element || typeof element !== 'object' || 'file' in element) return element
+  Object.defineProperty(element, 'file', {
+    enumerable: false,
+    configurable: true,
+    get () {
+      const src = element.attrs?.src ?? element.attrs?.url
+      if (typeof src === 'string' && src.startsWith('data:')) {
+        const comma = src.indexOf(',')
+        return comma >= 0 ? 'base64://' + src.slice(comma + 1) : src
+      }
+      return src
+    }
+  })
+  return element
+}
+
+function resElement (type: 'image' | 'video' | 'audio', src: any, ...rest: any[]) {
+  if (Buffer.isBuffer(src) || src instanceof ArrayBuffer) {
+    return withKarinFile(h[type](src as any, rest[0] ?? guessMime('', type === 'audio' ? 'audio' : type)))
+  }
+  const buf = typeof src === 'string' ? asBuffer(src, type) : null
+  if (buf) return withKarinFile(h[type](buf.data as any, buf.type))
+  if (typeof src === 'string' && src.startsWith('base64://')) {
+    return withKarinFile(h[type](('data:' + guessMime('', type === 'audio' ? 'audio' : type) + ';base64,' + src.slice(9)) as any))
+  }
+  return withKarinFile(h[type](src as any))
+}
+
+/**
+ * QQ 原生按钮的属性名修复。
+ *
+ * Koishi 的 `h()` 会把**顶层属性名** camelize（`render_data` → `renderData`），
+ * 而 koishi-plugin-adapter-qq-crack 是按 snake_case 读的（`attrs.render_data`）。
+ * 不改回来的话按钮渲染数据整个丢失，适配器会退化成「按钮文字 = action.data」——
+ * 也就是按钮上直接糊一整条 `#解析 https://… --qn=80`。
+ * 嵌套对象不会被 camelize，所以只需要补顶层这一层。
+ * @param element 按钮元素
+ */
+function restoreButtonAttrs<T extends { attrs: Record<string, any> }> (element: T): T {
+  const attrs = element.attrs
+  if (attrs.renderData && !attrs.render_data) attrs.render_data = attrs.renderData
+  if (attrs.visitedLabel && !attrs.visited_label) attrs.visited_label = attrs.visitedLabel
+  return element
+}
+
+export const segment = {
+  text: (value: any) => h.text(String(value ?? '')),
+  image: (src: any, ..._rest: any[]) => resElement('image', src),
+  video: (src: any, ..._rest: any[]) => resElement('video', src),
+  audio: (src: any, ..._rest: any[]) => resElement('audio', src),
+  record: (src: any, ..._rest: any[]) => resElement('audio', src),
+  reply: (id: any) => h.quote(String(id)),
+  at: (id: any) => h.at(String(id)),
+  face: (id: any) => h('face', { id: String(id) }),
+  file: (src: any, name?: string) => {
+    // base64:// 与本地路径都要转成真正的资源再交给适配器：
+    // 直接把 `base64://xxx` 字符串塞进 h.file()，适配器会去 fetch 这个地址而失败
+    // （日志里就是「QQ 消息发送失败 fetch base64://AAAAHGZ0eXBpc29t…」——那是 mp4 的头）
+    if (typeof src === 'string' && src.startsWith('base64://')) {
+      return withKarinFile(h.file(
+        Buffer.from(src.slice('base64://'.length), 'base64') as any,
+        guessMime(name ?? '', 'file'),
+        name ? { title: name } : undefined
+      ))
+    }
+    if (typeof src === 'string' && fs.existsSync(src.startsWith('file://') ? fileURLToPath(src) : src)) {
+      const filePath = src.startsWith('file://') ? fileURLToPath(src) : src
+      return withKarinFile(h.file(fs.readFileSync(filePath) as any, guessMime(filePath, 'file'), { title: name ?? path.basename(filePath) }))
+    }
+    if (Buffer.isBuffer(src) || src instanceof ArrayBuffer) {
+      return withKarinFile(h.file(src as any, guessMime(name ?? '', 'file'), name ? { title: name } : undefined))
+    }
+    return withKarinFile(h.file(src, name ? { title: name } : undefined))
+  },
+  /** markdown：传字符串等价于 `h('markdown', text)`；传对象则作为 attrs（如 `{ content, stream }`） */
+  markdown: (content: any, ...rest: any[]) =>
+    h('markdown', ...(rest.length ? rest : [content && typeof content === 'object' ? content : String(content ?? '')])),
+  button: (...args: any[]) => restoreButtonAttrs(h('button', ...args) as any),
+  /** QQ 原生按钮换行分组：一行最多 5 个按钮 */
+  buttonGroup: (children: any[]) => h('button-group', {}, Array.isArray(children) ? children : [children]),
+  count: (value: any) => h.text(String(value ?? '')),
+  raw: (type: string, data: Record<string, any>) => h(type, data),
+  /** 兼容 karin 的 segment 常量表 */
+  Image: 'image',
+  Video: 'video',
+  Text: 'text',
+  Reply: 'reply'
+}
+
+export default segment