koishi-plugin-kkk 1.0.0

package/scripts/smoke-qqpanel.cjs

@@ -0,0 +1,205 @@
+/**
+ * 冒烟测试：QQ 平台的解析交互面板（Markdown + 原生按钮）。
+ *
+ * 覆盖：
+ *   1. QQ 平台发链接 → 只回面板（不回解析结果，也不会真的去下载视频）；
+ *   2. 面板里的画质按钮遵守体积上限（默认 200MB），超限档位不生成按钮；
+ *   3. 「视频＋弹幕」按钮 = 带 --panel=1 的同一条命令，点了重新渲染面板并高亮；
+ *   4. 参数覆盖真的生效：runWithParseOverride 里 Config.bilibili.videoQuality 变成按钮选的档位；
+ *   5. 抖音走的是同一套面板逻辑（用固定数据验证：4K 300MB 那一档必须被隐藏）；
+ *   6. 非 QQ 平台 / 关掉面板开关 → 行为不变。
+ *
+ * 用法：node scripts/smoke-qqpanel.cjs
+ */
+const path = require('node:path')
+const { Context } = require('koishi')
+
+const pluginRoot = path.resolve(__dirname, '..')
+const dataRoot = path.resolve(pluginRoot, 'data-smoke')
+const target = 'https://www.bilibili.com/video/BV1xx411c7mD'
+
+/* ------------------------------------------------------------------ *
+ * 抖音侧固定数据（没有 Cookie 时抖音接口必被风控，这里只验证展示与选档逻辑）
+ * ------------------------------------------------------------------ */
+const axios = require(path.join(pluginRoot, 'node_modules/axios'))
+const realAxiosGet = axios.get
+const LONG_URL = 'https://www.douyin.com/video/7123456789012345678'
+axios.get = async (url, options) => {
+  if (typeof url === 'string' && url.includes('douyin')) return { request: { res: { responseUrl: LONG_URL } }, data: '' }
+  return realAxiosGet(url, options)
+}
+
+const makeBitRate = (definition, sizeMB) => ({
+  gear_name: definition,
+  quality_type: 28,
+  bit_rate: 1000000,
+  FPS: 30,
+  format: 'mp4',
+  video_extra: JSON.stringify({ definition }),
+  play_addr: { uri: 'v', url_list: ['https://www.w3schools.com/html/mov_bbb.mp4'], data_size: Math.round(sizeMB * 1024 * 1024) }
+})
+const douyinDetail = {
+  aweme_id: '7123456789012345678',
+  aweme_type: 0,
+  is_slides: false,
+  desc: '【面板验证】抖音视频解析测试',
+  preview_title: '【面板验证】抖音视频解析测试',
+  create_time: Math.floor(Date.now() / 1000) - 3600,
+  share_url: LONG_URL,
+  author: { uid: '1', sec_uid: 'SEC', nickname: '测试作者', avatar_thumb: { url_list: ['https://www.w3schools.com/html/pic_trulli.jpg'] } },
+  statistics: { digg_count: 1, comment_count: 1, share_count: 1, collect_count: 1, play_count: 1 },
+  images: null,
+  music: null,
+  video: {
+    play_addr: { uri: 'v', url_list: ['https://www.w3schools.com/html/mov_bbb.mp4'], data_size: 20971520 },
+    cover: { url_list: ['https://www.w3schools.com/html/pic_trulli.jpg'] },
+    origin_cover: { url_list: ['https://www.w3schools.com/html/pic_trulli.jpg'] },
+    duration: 15000,
+    // 4K 那档 300MB，超过 QQ 的 200MB 硬限制，必须被面板隐藏
+    bit_rate: [makeBitRate('4k', 300), makeBitRate('1080p', 80), makeBitRate('720p', 20), makeBitRate('540p', 8)]
+  }
+}
+
+const amagi = require('@ikenxuan/amagi')
+const realFactory = amagi.default
+amagi.default = function (options) {
+  const client = realFactory(options)
+  client.douyin.fetcher.parseWork = async () => ({ success: true, code: 200, message: 'OK', data: { aweme_detail: douyinDetail } })
+  return client
+}
+
+const plugin = require(path.join(pluginRoot, 'lib/index.js'))
+const ctx = new Context()
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, qqPanel: true, qqFileLimitMB: 200 })
+
+/* ------------------------------------------------------------------ *
+ * 断言工具
+ * ------------------------------------------------------------------ */
+const results = []
+const check = (name, ok, detail) => {
+  results.push({ name, ok })
+  console.log((ok ? '  ✅ ' : '  ❌ ') + name + (detail ? '  —— ' + detail : ''))
+}
+
+/** 直接跑某个已注册命令（不经过中间件，避免无关命令干扰） */
+const runCommand = async (namePart, content, platform = 'qqguild') => {
+  const { commandQueue } = require(path.join(pluginRoot, 'lib/compat/runtime.js'))
+  const { Message } = require(path.join(pluginRoot, 'lib/compat/node-karin.js'))
+  const reg = commandQueue.find((item) => String(item.options?.name ?? '').includes(namePart))
+  if (!reg) throw new Error('没有注册命令: ' + namePart)
+
+  const sent = []
+  const bot = {
+    selfId: '10000', platform, status: 1, user: { id: '10000', name: 'smoke' }, ctx,
+    sendMessage: async (channel, payload) => { sent.push(payload); return ['msg-1'] },
+    getGuild: async () => ({ name: 'smoke-guild' })
+  }
+  const session = {
+    content, selfId: '10000', userId: '12345', guildId: '456', channelId: '456',
+    messageId: 'm1', bot, author: { nick: 'smoke' }, username: 'smoke', event: {},
+    send: async (payload) => { sent.push(payload); return ['msg-2'] }
+  }
+  await reg.handler(Message.fromSession(session), () => Symbol('next'))
+  return sent
+}
+
+/** 把发出的元素压成 markdown 文本 + 按钮清单 */
+const readPanel = (sent) => {
+  const flat = []
+  for (const item of sent) for (const el of (Array.isArray(item) ? item : [item])) flat.push(el)
+  const markdown = flat.filter((el) => el && el.type === 'markdown')
+    .map((el) => (el.children || []).map((child) => child.attrs && child.attrs.content).join('')).join('\n')
+  // 按钮现在是 markdown 内联的 <qqbot-cmd-input text="…" show="…" />（群聊唯一可用的指令标签）
+  const buttons = []
+  const pattern = /<qqbot-cmd-input\s+text="([^"]*)"\s+show="([^"]*)"\s+reference="[^"]*"\s*\/>/g
+  let matched
+  while ((matched = pattern.exec(markdown)) !== null) {
+    buttons.push({ data: decodeURIComponent(matched[1]), label: decodeURIComponent(matched[2]) })
+  }
+  return { flat, markdown, buttons }
+}
+
+setTimeout(async () => {
+  try {
+    const { getRuntime } = require(path.join(pluginRoot, 'lib/compat/runtime.js'))
+
+    console.log('\n[1] QQ 平台发 B站链接 → 只回面板（不解析、不下载）')
+    const sent = await runCommand('B站', target)
+    const panel = readPanel(sent)
+    check('只发了 1 条消息', sent.length === 1, '共 ' + sent.length + ' 条')
+    check('含 markdown 段', /解析设置/.test(panel.markdown))
+    check('用的是 markdown 指令标签 <qqbot-cmd-input>', panel.buttons.length > 0, panel.buttons.length + ' 个按钮')
+    check('不再发原生 keyboard 按钮', !panel.flat.some((el) => el && el.type === 'button-group'))
+    check('按钮文字是画质（不是整条指令）', panel.buttons.every((b) => b.label && !b.label.startsWith('#') && !/https?:/.test(b.label)), panel.buttons.map((b) => b.label).join(' / '))
+    check('按钮里不带链接（只放短令牌）', panel.buttons.every((b) => !/https?:/.test(b.data)), panel.buttons[0] && panel.buttons[0].data)
+    console.log('  —— markdown ——\n' + panel.markdown.split('\n').map((l) => '     ' + l).join('\n'))
+    console.log('  —— 按钮 ——')
+    for (const b of panel.buttons) console.log('     [' + b.label + '] → ' + b.data)
+
+    console.log('\n[2] 体积上限：上限压到 1MB 时只保留最小的一档')
+    const runtime = getRuntime()
+    const originalLimit = runtime.config.qqFileLimitMB
+    runtime.config.qqFileLimitMB = 1
+    const tiny = readPanel(await runCommand('B站', target))
+    runtime.config.qqFileLimitMB = originalLimit
+    const qualityButtons = tiny.buttons.filter((b) => /M/.test(b.label))
+    const distinct = [...new Set(qualityButtons.map((b) => b.label))]
+    check('最多保留 1 档画质（两行各一个按钮）', distinct.length <= 1, distinct.join(' / ') || '（无）')
+    check('markdown 给出「发送可能失败」的提示', /可能失败/.test(tiny.markdown), tiny.markdown.match(/⚠️.*/)?.[0] ?? '（无提示）')
+
+    console.log('\n[3] 每个按钮都直接解析（没有「切换面板」的按钮）')
+    const videoLine = panel.markdown.split('\n').find((line) => line.includes('**纯视频**')) || ''
+    const danmakuLine = panel.markdown.split('\n').find((line) => line.includes('视频 + 弹幕')) || ''
+    const videoButtons = panel.buttons.filter((b) => String(b.data).startsWith('解析 '))
+    const danmakuButtons = panel.buttons.filter((b) => String(b.data).startsWith('弹幕解析 '))
+    check('纯视频那一行的按钮发「解析」指令', videoLine.includes('qqbot-cmd-input') && videoButtons.length > 0, videoButtons.map((b) => b.data).join(' | '))
+    check('弹幕那一行的按钮发「弹幕解析」指令', danmakuLine.includes('qqbot-cmd-input') && danmakuButtons.length > 0, danmakuButtons.map((b) => b.data).join(' | '))
+    check('没有任何按钮带 --panel（点了不会再弹面板）', panel.buttons.every((b) => !String(b.data).includes('--panel')), panel.buttons.map((b) => b.data).join(' | '))
+
+    console.log('\n[4] 参数覆盖：按钮选的画质要真的作用到解析链路')
+    const { runWithParseOverride } = require(path.join(pluginRoot, 'lib/karin/module/utils/ParseOverride.js'))
+    const { Config } = require(path.join(pluginRoot, 'lib/karin/module/utils/Config.js'))
+    const configured = Config.bilibili.videoQuality
+    let inside = null
+    await runWithParseOverride({ bilibiliQuality: 116 }, async () => { inside = Config.bilibili.videoQuality })
+    check('作用域内取到覆盖值 116', inside === 116, 'inside=' + inside + ' / 配置=' + configured)
+    check('作用域外仍是配置值', Config.bilibili.videoQuality === configured, 'now=' + Config.bilibili.videoQuality)
+    let douyinInside = null
+    await runWithParseOverride({ douyinQuality: '720p' }, async () => { douyinInside = Config.douyin.videoQuality })
+    check('抖音画质同样可覆盖', douyinInside === '720p', 'inside=' + douyinInside)
+
+    console.log('\n[5] 抖音：同一套面板 + 200MB 硬限制过滤（固定数据）')
+    const dySent = await runCommand('抖音', 'https://v.douyin.com/iFakeTest/')
+    const dy = readPanel(dySent)
+    check('只发了 1 条消息（面板）', dySent.length === 1, '共 ' + dySent.length + ' 条')
+    check('面板标题是作品文案', /面板验证/.test(dy.markdown), dy.markdown.split('\n')[1])
+    const dyQuality = dy.buttons.filter((b) => /M/.test(b.label))
+    console.log('     画质按钮：' + dyQuality.map((b) => b.label).join(' / '))
+    check('300MB 的 4K 档被隐藏', !dyQuality.some((b) => b.label.includes('4K')), dyQuality.map((b) => b.label).join(' / '))
+    check('80MB 的 1080P 档保留', dyQuality.some((b) => b.label.includes('1080P')), dyQuality.map((b) => b.label).join(' / '))
+    check('画质参数用抖音的 --q=', dyQuality.some((b) => String(b.data).includes('--q=1080p')), dyQuality[0] && dyQuality[0].data)
+
+    console.log('\n[6] 非 QQ 平台 / 关掉开关 → 不发面板')
+    const { sendQqParsePanel } = require(path.join(pluginRoot, 'lib/karin/module/utils/QqPanel.js'))
+    const { Message } = require(path.join(pluginRoot, 'lib/compat/node-karin.js'))
+    const makeMessage = (platform) => Message.fromSession({
+      content: target, selfId: '10000', userId: '1', guildId: '456', channelId: '456', messageId: 'm',
+      bot: { selfId: '10000', platform, status: 1, ctx, sendMessage: async () => ['x'] },
+      author: { nick: 's' }, username: 's', event: {}, send: async () => ['y']
+    })
+    const onebot = await sendQqParsePanel(makeMessage('onebot'), { platform: 'bilibili', url: target, id: 'BV1xx411c7mD' }, { danmaku: false })
+    check('onebot 平台不发面板', onebot === false)
+    runtime.config.qqPanel = false
+    const disabled = await sendQqParsePanel(makeMessage('qqguild'), { platform: 'bilibili', url: target, id: 'BV1xx411c7mD' }, { danmaku: false })
+    runtime.config.qqPanel = true
+    check('qqPanel=false 时不发面板', disabled === false)
+
+    const failed = results.filter((item) => !item.ok)
+    console.log('\n=== ' + (results.length - failed.length) + '/' + results.length + ' 通过 ===')
+    process.exitCode = failed.length ? 1 : 0
+  } catch (error) {
+    console.error('冒烟测试失败:', error && error.stack ? error.stack : error)
+    process.exitCode = 1
+  }
+  process.exit(process.exitCode || 0)
+}, 5000)

package/scripts/smoke-render.cjs

@@ -0,0 +1,106 @@
+/**
+ * 渲染冒烟测试：用固定数据直接跑模板 SSR（不依赖 puppeteer，也不需要外网）。
+ *
+ * 验证点：
+ *   - 路由注册表能加载到上游模板（\`src/ktr/template/**\`）
+ *   - react-dom/server 能把模板渲染成 HTML，且关键内容出现在 HTML 里
+ *   - 模板样式（上游构建产物 style.css）被内联进 HTML
+ *   - 不支持的路由/坏数据会回退到内置通用卡片
+ *
+ * 用法：node scripts/smoke-render.cjs
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { Context } = require('koishi')
+
+const pluginRoot = path.resolve(__dirname, '..')
+const dataRoot = path.resolve(pluginRoot, 'data-smoke-render')
+fs.mkdirSync(path.join(dataRoot, 'koishi-plugin-kkk', 'config'), { recursive: true })
+
+const plugin = require(path.join(pluginRoot, 'lib/index.js'))
+const ctx = new Context()
+const fakeBot = {
+  selfId: '10000', platform: 'smoke', status: 1, user: { id: '10000', name: 'smoke' }, ctx,
+  sendMessage: async () => ['m'], getGuild: async () => ({ name: 'g' }), getFriendList: async () => []
+}
+Object.defineProperty(ctx, 'bots', { get: () => [fakeBot] })
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, masters: ['12345'] })
+
+// 用富文本包自带的构造函数拼文档，保证形状与模板一致
+const richtext = require(path.join(pluginRoot, 'lib/richtext/index.js'))
+const descDoc = richtext.createRichTextDocument([
+  richtext.createParagraphNode([richtext.createTextNode('这里是视频简介，用于验证富文本渲染链路。')])
+], { platform: 'bilibili' })
+
+/** B站视频信息模板的固定数据 */
+const videoInfoData = {
+  share_url: 'https://b23.tv/BV1xx411c7mD',
+  title: '【迁移验证】这是一条用于确认模板渲染的测试标题',
+  desc: descDoc,
+  stat: {
+    aid: 2, view: 1234567, danmaku: 4567, reply: 890, favorite: 2345, coin: 6789, share: 123,
+    now_rank: 0, his_rank: 8, like: 98765, dislike: 0, evaluation: '', argue_msg: ''
+  },
+  bvid: 'BV1xx411c7mD',
+  ctime: Math.floor(Date.now() / 1000) - 86400,
+  pic: 'https://i0.hdslb.com/bfs/archive/placeholder.jpg',
+  owner: { mid: 946974, name: '测试UP主', face: 'https://i0.hdslb.com/bfs/face/placeholder.jpg' },
+  hotDanmaku: [{ content: '测试弹幕', count: 12 }]
+}
+
+const outDir = path.join(dataRoot, 'html')
+fs.mkdirSync(outDir, { recursive: true })
+
+setTimeout(async () => {
+  let failures = 0
+  try {
+    const render = require(path.join(pluginRoot, 'lib/karin/module/utils/Render/index.js'))
+
+    const cases = [
+      { route: 'bilibili/videoInfo', data: videoInfoData, expect: '【迁移验证】' },
+      { route: 'other/changelog', data: { markdown: '## [2.42.5]\n- 迁移验证用的更新日志', Tip: false }, expect: '迁移验证用的更新日志' },
+      { route: '不存在的路由/xxx', data: videoInfoData, expect: '【迁移验证】', fallbackOnly: true }
+    ]
+
+    for (const item of cases) {
+      const html = await render.renderTemplateHtml(item.route, item.data, false)
+      const finalHtml = html ?? render.buildFallbackHtml(item.route, item.data, false, 1)
+      const usedTemplate = !!html
+      const ok = finalHtml.includes(item.expect) && (!item.fallbackOnly || !usedTemplate)
+      if (!ok) failures++
+      const file = path.join(outDir, item.route.replace(/[\\/]/g, '_') + '.html')
+      fs.writeFileSync(file, finalHtml)
+      console.log(
+        (ok ? '✅' : '❌') + ' ' + item.route +
+        ' | 模板 SSR: ' + (usedTemplate ? '是' : '否（回退卡片）') +
+        ' | HTML ' + finalHtml.length + ' 字节' +
+        ' | 含样式: ' + (finalHtml.includes('.flex') || finalHtml.includes('--tw') ? '是' : '否') +
+        ' | 含关键内容: ' + ok
+      )
+    }
+
+    // 注册表健康检查：所有路由的模板是否都能被加载（缺依赖会在这里暴露）
+    const registry = require(path.join(pluginRoot, 'lib/ktr/registry.js'))
+    const routes = Object.keys(registry.templateRegistry)
+    const broken = []
+    for (const route of routes) {
+      try {
+        const mod = await registry.loadTemplate(route)
+        if (!mod?.component) broken.push(route + '（无 component）')
+      } catch (error) {
+        broken.push(route + '（' + String(error && error.message).split('\n')[0] + '）')
+      }
+    }
+    console.log('\n模板注册表：共 ' + routes.length + ' 个路由，可加载 ' + (routes.length - broken.length) + ' 个')
+    if (broken.length) {
+      console.log('暂不可用（依赖缺失等，运行时会自动回退通用卡片）:')
+      for (const item of broken) console.log('  - ' + item)
+    }
+
+    console.log('\nHTML 样例输出目录: ' + outDir)
+  } catch (error) {
+    console.error('渲染冒烟测试失败:', error && error.stack ? error.stack : error)
+    failures++
+  }
+  process.exit(failures ? 1 : 0)
+}, 5000)

package/scripts/smoke-server.cjs

@@ -0,0 +1,94 @@
+/**
+ * Web 控制台冒烟测试：起一个真实的 Koishi HTTP 服务（koishi-plugin-server），
+ * 挂上插件后用 fetch 打控制台接口，验证：
+ *   1. GET /kkk                     控制台页面（零构建 HTML）
+ *   2. GET /kkk/v1/version          版本接口（无需鉴权）
+ *   3. GET /kkk/v1/config           无 token 且非本机 → 401
+ *   4. GET /kkk/v1/config           带 token → 模块列表
+ *   5. POST /kkk/v1/config          改一个配置项 → 再读确认已落盘
+ *   6. GET /kkk/v1/bots             机器人列表
+ *
+ * 用法：node scripts/smoke-server.cjs
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { Context } = require('koishi')
+
+const pluginRoot = path.resolve(__dirname, '..')
+const dataRoot = path.resolve(pluginRoot, 'data-smoke-server')
+const cfgDir = path.join(dataRoot, 'koishi-plugin-kkk', 'config')
+fs.mkdirSync(cfgDir, { recursive: true })
+
+const config = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'config/default_config/config.json'), 'utf8'))
+config.pushlist = { douyin: [], bilibili: [] }
+fs.writeFileSync(path.join(cfgDir, 'config.json'), JSON.stringify(config, null, 2))
+
+const PORT = Number(process.argv[2] || 5311)
+const TOKEN = 'kkk-smoke-token'
+const base = 'http://127.0.0.1:' + PORT
+
+const ctx = new Context()
+const serverModule = require('@koishijs/plugin-server')
+ctx.plugin(serverModule.default ?? serverModule, { port: PORT, host: '127.0.0.1' })
+ctx.plugin(require(path.join(pluginRoot, 'lib/index.js')), {
+  dataPath: dataRoot,
+  masters: ['12345'],
+  apiToken: TOKEN,
+  webui: true,
+  debug: false
+})
+
+const check = (name, ok, extra = '') => {
+  console.log((ok ? '✅' : '❌') + ' ' + name + (extra ? ' | ' + extra : ''))
+  if (!ok) failures++
+}
+let failures = 0
+
+const call = async (route, options = {}) => {
+  const headers = Object.assign({}, options.headers)
+  if (options.token) headers.Authorization = 'Bearer ' + options.token
+  if (options.body) headers['Content-Type'] = 'application/json'
+  const response = await fetch(base + route, Object.assign({}, options, { headers }))
+  const text = await response.text()
+  let json
+  try { json = JSON.parse(text) } catch {}
+  return { status: response.status, text, json }
+}
+
+// koishi 的 server 插件在 `ready` 事件里才开始监听端口，所以要显式 start 上下文
+void ctx.start().catch((error) => console.error('启动 Koishi 服务失败:', error))
+
+setTimeout(async () => {
+  try {
+    const page = await call('/kkk')
+    check('控制台页面 /kkk', page.status === 200 && page.text.includes('koishi-plugin-kkk 控制台'), 'HTTP ' + page.status + ' ' + page.text.length + ' 字节')
+
+    const version = await call('/kkk/v1/version')
+    check('版本接口 /kkk/v1/version', version.status === 200 && version.json?.data?.version, JSON.stringify(version.json?.data))
+
+    const noToken = await call('/kkk/v1/config')
+    check('未授权访问 /kkk/v1/config', noToken.status === 401, 'HTTP ' + noToken.status + ' ' + (noToken.json?.message || ''))
+
+    const withToken = await call('/kkk/v1/config', { token: TOKEN })
+    const modules = withToken.json?.data ? Object.keys(withToken.json.data) : []
+    check('读取配置 /kkk/v1/config', withToken.status === 200 && modules.length > 0, modules.length + ' 个模块: ' + modules.slice(0, 8).join(','))
+
+    const before = withToken.json?.data?.app?.parseTip
+    const save = await call('/kkk/v1/config', {
+      method: 'POST',
+      token: TOKEN,
+      body: JSON.stringify({ app: { ...withToken.json.data.app, parseTip: before === false } })
+    })
+    const after = await call('/kkk/v1/config', { token: TOKEN })
+    check('写入配置 POST /kkk/v1/config', save.json?.code === 200 && after.json?.data?.app?.parseTip === (before === false),
+      'parseTip: ' + before + ' → ' + after.json?.data?.app?.parseTip +
+      ' | results: ' + JSON.stringify(save.json?.data?.results ?? save.json).slice(0, 200))
+
+    const bots = await call('/kkk/v1/bots', { token: TOKEN })
+    check('机器人列表 /kkk/v1/bots', bots.status === 200 && Array.isArray(bots.json?.data), 'HTTP ' + bots.status)
+  } catch (error) {
+    console.error('控制台冒烟测试失败:', error && error.stack ? error.stack : error)
+    failures++
+  }
+  process.exit(failures ? 1 : 0)
+}, 7000)

package/src/compat/axios.ts

@@ -0,0 +1,5 @@
+/** `node-karin/axios` 的兼容实现：直接复用 axios */
+import axios from 'axios'
+
+export * from 'axios'
+export default axios

package/src/compat/cron.ts

@@ -0,0 +1,86 @@
+/**
+ * 最小 cron 调度器（5 段：分 时 日 月 周）。
+ *
+ * 原插件通过 karin.task 注册定时任务，Koishi 侧没有等价 API，
+ * 这里自己实现匹配，用 ctx.setInterval 每 30 秒检查一次。
+ */
+import type { Context } from 'koishi'
+
+function parseField (field: string, min: number, max: number): (value: number) => boolean {
+  if (field === '*' || field === '?') return () => true
+  const matchers: Array<(value: number) => boolean> = []
+  for (const part of field.split(',')) {
+    const stepMatch = part.match(/^(\*|\d+(?:-\d+)?)\/(\d+)$/)
+    if (stepMatch) {
+      const step = Number(stepMatch[2])
+      const [start, end] = stepMatch[1] === '*' ? [min, max] : stepMatch[1].split('-').map(Number)
+      matchers.push((value) => value >= start && value <= (end ?? start) && (value - start) % step === 0)
+      continue
+    }
+    const rangeMatch = part.match(/^(\d+)-(\d+)$/)
+    if (rangeMatch) {
+      const start = Number(rangeMatch[1])
+      const end = Number(rangeMatch[2])
+      matchers.push((value) => value >= start && value <= end)
+      continue
+    }
+    const num = Number(part)
+    if (!Number.isNaN(num)) matchers.push((value) => value === num)
+  }
+  if (!matchers.length) return () => true
+  return (value: number) => matchers.some((matcher) => matcher(value))
+}
+
+export function cronMatcher (expression: string) {
+  const fields = expression.trim().split(/\s+/)
+  if (fields.length < 5) return () => false
+  const [minute, hour, day, month, week] = fields
+  const matchMinute = parseField(minute, 0, 59)
+  const matchHour = parseField(hour, 0, 23)
+  const matchDay = parseField(day, 1, 31)
+  const matchMonth = parseField(month, 1, 12)
+  const matchWeek = parseField(week, 0, 6)
+  return (date: Date) => matchMinute(date.getMinutes())
+    && matchHour(date.getHours())
+    && matchDay(date.getDate())
+    && matchMonth(date.getMonth() + 1)
+    && matchWeek(date.getDay())
+}
+
+export interface ScheduledTask {
+  name: string
+  cron: string
+  handler: (...args: any[]) => any
+  options?: Record<string, any>
+}
+
+export function startScheduler (ctx: Context, logger: any, tasks: ScheduledTask[]) {
+  if (!tasks.length) return
+  const entries = tasks.map((task) => ({ task, match: cronMatcher(task.cron), running: false, lastKey: '' }))
+
+  for (const entry of entries) {
+    logger.info('注册定时任务 %s（%s）', entry.task.name, entry.task.cron)
+  }
+
+  const tick = async () => {
+    const now = new Date()
+    const key = now.toISOString().slice(0, 16)
+    for (const entry of entries) {
+      if (entry.lastKey === key) continue
+      if (!entry.match(now)) continue
+      entry.lastKey = key
+      if (entry.running) {
+        logger.warn('任务 %s 上一轮尚未结束，跳过本次触发', entry.task.name)
+        continue
+      }
+      entry.running = true
+      Promise.resolve()
+        .then(() => entry.task.handler())
+        .catch((error) => logger.error('任务 %s 执行失败: %s', entry.task.name, error?.stack ?? error))
+        .finally(() => { entry.running = false })
+    }
+  }
+
+  ctx.setInterval(tick, 30 * 1000)
+  void tick()
+}

package/src/compat/esm.ts

@@ -0,0 +1,13 @@
+/**
+ * 真实动态 import 的逃生舱。
+ *
+ * tsc 在 `module: commonjs` 下会把 `await import('x')` 降级成 `Promise.resolve().then(() => require('x'))`，
+ * 于是 ESM-only 的依赖（例如 `@ikenxuan/qrcode` 的 exports 没有 require 条件）依旧加载不了。
+ * 这里用 `new Function` 包一层，绕开编译期改写，运行时由 Node 走真正的 ESM 加载。
+ */
+export function importEsm<T = any> (specifier: string): Promise<T> {
+  const importer = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<T>
+  return importer(specifier)
+}
+
+export default importEsm

package/src/compat/express.ts

@@ -0,0 +1,5 @@
+/** `node-karin/express` 的兼容实现：复用 express */
+import express from 'express'
+
+export * from 'express'
+export default express

package/src/compat/heroui.tsx

@@ -0,0 +1,53 @@
+/**
+ * \`@heroui/react\` 的最小兼容实现（Koishi 迁移补充）。
+ *
+ * 上游只有 4 个模板用到 HeroUI，且只用到 \`Chip\` 与 \`Button\` 两个展示型组件。
+ * 而 @heroui/react v3 是 **ESM-only**（package.json 里 exports 只有 import 条件，没有 CJS 产物），
+ * 我们的 CJS 产物（tsc 直出、无打包器）没法 require 它。
+ *
+ * 这里用同语义的普通元素实现：调用方本来就通过 \`className\` / \`style\` 传入了绝大多数样式，
+ * 海报又是静态 HTML（没有交互），因此渲染结果与 HeroUI 基本一致。
+ */
+import React from 'react'
+
+interface CompatProps {
+  size?: 'sm' | 'md' | 'lg'
+  color?: string
+  variant?: string
+  className?: string
+  style?: React.CSSProperties
+  children?: React.ReactNode
+  [key: string]: unknown
+}
+
+const join = (...parts: Array<string | undefined | false>) => parts.filter(Boolean).join(' ')
+
+/** 对应 HeroUI 的 Chip（标签/徽章） */
+export const Chip = ({ size = 'md', color, variant, className, style, children, ...rest }: CompatProps) => (
+  <span
+    className={join('inline-flex items-center justify-center rounded-full leading-none', className)}
+    style={style}
+    data-color={color}
+    data-variant={variant}
+    data-size={size}
+    {...(rest as any)}
+  >
+    {children}
+  </span>
+)
+
+/** 对应 HeroUI 的 Button（静态海报里就是一块按钮样式的容器） */
+export const Button = ({ size = 'md', color, variant, className, style, children, ...rest }: CompatProps) => (
+  <span
+    className={join('inline-flex items-center justify-center gap-2 rounded-xl font-medium', className)}
+    style={style}
+    data-color={color}
+    data-variant={variant}
+    data-size={size}
+    {...(rest as any)}
+  >
+    {children}
+  </span>
+)
+
+export default { Chip, Button }

package/src/compat/lodash.ts

@@ -0,0 +1,32 @@
+/**
+ * \`node-karin/lodash\` 的兼容实现。
+ *
+ * 上游只有一个模板用到它，且只用了 \`camelCase\` / \`upperFirst\` 两个纯函数，
+ * 因此这里不引入 lodash 全量依赖，直接实现同语义的小函数（并保留 lodash 的默认导出形态）。
+ */
+
+/** lodash 的 camelCase：\`'QQ Bot' -> 'qqBot'\` */
+export function camelCase (input: string): string {
+  const words = String(input ?? '')
+    .replace(/['\u2019]/g, '')
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+  return words
+    .map((word, index) => {
+      const lower = word.toLowerCase()
+      return index === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1)
+    })
+    .join('')
+}
+
+/** lodash 的 upperFirst：只把首字母大写 */
+export function upperFirst (input: string): string {
+  const text = String(input ?? '')
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+const lodash = { camelCase, upperFirst }
+export default lodash