koishi-plugin-kkk 1.0.0

package/scripts/patch-webui.mjs

@@ -0,0 +1,112 @@
+/**
+ * 给原版 WebUI（assets/web 里的 SPA）加一个「QQ 适配器」分类。
+ *
+ * 原版面板只认 Karin 那份 config.json（接口库 / 通用 / 抖音 / 哔哩哔哩 / 快手 / 小红书 / 推送列表），
+ * 而 QQ 专属的那几项（面板、切片、番剧选集表格、卡片 OCR）是 Koishi 侧才有的，
+ * 于是这里往打包好的 SPA 里补一个 tab：
+ *
+ *   1. 分类列表里加 { key: 'qq', label: 'QQ 适配器' }；
+ *   2. 配置面板的分发 switch 里加 case 'qq'，渲染下面生成的组件；
+ *   3. 组件用 SPA 自带的字段渲染器，路径一律 ['qq', 字段名]，
+ *      读写的还是那份整包配置 —— 保存时 POST /kkk/v1/config，
+ *      服务端把 qq 拆出来写回 Koishi 的 koishi.yml（见 src/webui.ts）。
+ *
+ * 字段表来自 src/qqFields.json（和控制台表单同一份），所以两边永远一致。
+ * 脚本可反复执行：先删掉上次插入的片段，再按当前字段表重新插入。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pluginRoot = path.resolve(here, '..')
+const webAssets = path.join(pluginRoot, 'assets', 'web', 'assets')
+
+// 用字符码拼反引号，免得本文件自己被模板串语法绊倒
+const BT = String.fromCharCode(96)
+const START = '/*KKK-QQ-START*/'
+const END = '/*KKK-QQ-END*/'
+const COMPONENT = 'KKKQQConfig'
+
+const fields = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'src', 'qqFields.json'), 'utf-8'))
+
+const q = (value) => BT + String(value) + BT
+const arr = (items) => '[' + items.map(q).join(',') + ']'
+
+/** 一个字段 → 一行渲染器调用 */
+function renderField (field) {
+  const target = arr(['qq', field.key])
+  const args = [target, q(field.label), q(field.description)]
+  if (field.type === 'boolean') return 'i(' + args.join(',') + ')'
+  const options = ['type:' + q(field.secret ? 'password' : field.type === 'number' ? 'number' : 'text')]
+  if (field.type === 'number') {
+    options.push('fallback:' + Number(field.default))
+    if (field.min !== undefined) options.push('min:' + field.min)
+    if (field.max !== undefined) options.push('max:' + field.max)
+  } else if (field.secret) {
+    options.push('placeholder:' + q('留空则使用公共测试密钥'))
+  }
+  return 'a(' + args.concat('{' + options.join(',') + '}').join(',') + ')'
+}
+
+const groups = []
+for (const field of fields) {
+  let group = groups.find((item) => item.name === field.group)
+  if (!group) groups.push(group = { name: field.group, fields: [] })
+  group.fields.push(field)
+}
+
+const sections = groups.map((group) => 'r(' + q(group.name) + ',(0,U.jsx)(U.Fragment,{children:[' + group.fields.map(renderField).join(',') + ']}))').join(',')
+
+const componentCode = COMPONENT
+  + '=({config:e,renderers:t})=>{let{renderPageHeader:n,renderSubSection:r,renderSwitch:i,renderTextField:a}=t;return(0,U.jsxs)(U.Fragment,{children:[n('
+  + q('QQ 适配器') + ',' + q('这些设置只对 QQ 平台生效，其它平台不受影响。改完点右下角保存即可，不用重启。') + '),' + sections + ']})}'
+
+const CATEGORY = '{key:' + q('qq') + ',label:' + q('QQ 适配器') + ',description:' + q('QQ 平台专属') + '}'
+const SWITCH = ';case' + q('qq') + ':return(0,U.jsx)(' + COMPONENT + ',{...e})'
+const CATEGORY_ANCHOR = ',{key:' + q('pushlist') + ',label:' + q('推送列表') + ',description:' + q('订阅 JSON') + '}'
+const SWITCH_ANCHOR = 'case' + q('pushlist') + ':return(0,U.jsx)(MR,{...e})'
+const COMPONENT_ANCHOR = ',PR=e=>{switch(e.activeFile){'
+
+/** 去掉上次插入的组件（按标记切掉） */
+function stripComponent (text) {
+  let out = text
+  for (;;) {
+    const start = out.indexOf(START)
+    if (start < 0) return out
+    const end = out.indexOf(END, start)
+    if (end < 0) return out
+    out = out.slice(0, start) + out.slice(end + END.length)
+  }
+}
+
+const files = fs.readdirSync(webAssets).filter((name) => /^index-.*[.]js$/.test(name))
+if (!files.length) throw new Error('找不到 assets/web/assets/index-*.js（WebUI 前端包）')
+
+for (const name of files) {
+  const file = path.join(webAssets, name)
+  let text = fs.readFileSync(file, 'utf-8')
+  const before = text.length
+
+  // 可重复执行：先清掉上次插入的片段
+  text = stripComponent(text)
+  text = text.split(',' + CATEGORY).join('')
+  text = text.split(SWITCH).join('')
+
+  // 1. 分类列表
+  if (!text.includes(CATEGORY_ANCHOR)) throw new Error(name + '：找不到分类列表（前端包可能换版本了，需要重新适配）')
+  text = text.replace(CATEGORY_ANCHOR, ',' + CATEGORY + CATEGORY_ANCHOR)
+
+  // 2. 分发 switch
+  if (!text.includes(SWITCH_ANCHOR)) throw new Error(name + '：找不到配置面板的 switch')
+  text = text.replace(SWITCH_ANCHOR, SWITCH_ANCHOR + SWITCH)
+
+  // 3. 组件定义（塞在 PR 前面，同一个模块作用域，能用 U / Q 这些打包期变量）
+  if (!text.includes(COMPONENT_ANCHOR)) throw new Error(name + '：找不到配置面板组件')
+  text = text.replace(COMPONENT_ANCHOR, ',' + START + componentCode + END + COMPONENT_ANCHOR)
+
+  fs.writeFileSync(file, text)
+  console.log('[kkk] 已注入 QQ 适配器分类: ' + name + '（' + before + ' → ' + text.length + ' 字节）')
+}
+
+console.log('[kkk] 完成，共处理 ' + files.length + ' 个文件')

package/scripts/smoke-commands.cjs

@@ -0,0 +1,39 @@
+/**
+ * 信息类命令冒烟测试：`#kkk帮助` / `#kkk版本` / `#kkk更新日志`。
+ * 覆盖 Render 兜底、CHANGELOG 解析（兼容层 logs/parseChangelog/range）、运行环境快照。
+ *
+ * 用法：node scripts/smoke-commands.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-cmd');
+fs.mkdirSync(path.join(dataRoot, 'koishi-plugin-kkk', 'config'), { recursive: true });
+const config = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'config/default_config/config.json'), 'utf8'));
+config.app.parseTip = false;
+fs.writeFileSync(path.join(dataRoot, 'koishi-plugin-kkk', 'config', 'config.json'), JSON.stringify(config, null, 2));
+const plugin = require(path.join(pluginRoot, 'lib/index.js'));
+const ctx = new Context();
+const sent = [];
+const fakeBot = { selfId: '10000', platform: 'smoke', status: 1, user: { id: '10000', name: 's' }, ctx,
+  sendMessage: async (ch, c) => { sent.push(c); return ['m'] }, getGuild: async () => ({ name: 'g' }), getFriendList: async () => [] };
+Object.defineProperty(ctx, 'bots', { get: () => [fakeBot] });
+const middlewares = [];
+const orig = ctx.middleware.bind(ctx);
+ctx.middleware = (fn, ...rest) => { middlewares.push(fn); return orig(fn, ...rest) };
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, masters: ['12345'] });
+const makeSession = (content) => ({ content, selfId: '10000', userId: '12345', guildId: '456', channelId: '456', messageId: 'm1', bot: fakeBot, author: { nick: 's' }, username: 's', event: {}, send: async (c) => { sent.push(c); return ['m2'] } });
+async function dispatch (content) {
+  const session = makeSession(content); let i = 0;
+  const run = async () => { while (i < middlewares.length) { const mw = middlewares[i++]; let cont = false; await mw(session, () => { cont = true; return run() }); if (!cont) return } };
+  await run();
+}
+setTimeout(async () => {
+  const { commandQueue } = require(path.join(pluginRoot, 'lib/compat/runtime.js'));
+  console.log('middlewares=' + middlewares.length + ' commands=' + commandQueue.length);
+  for (const cmd of ['#kkk帮助', '#kkk版本', '#kkk更新日志']) {
+    try { console.log('--- ' + cmd + ' ---'); await dispatch(cmd); } catch (e) { console.log('FAIL', e.message); }
+  }
+  console.log('\n共发出 ' + sent.length + ' 条消息');
+  for (const c of sent) { const list = Array.isArray(c) ? c : [c]; console.log(list.map((el) => typeof el === 'string' ? el.slice(0, 160) : '[' + (el && el.type) + ']').join(' | ').slice(0, 300)); }
+  process.exit(0);
+}, 5000);

package/scripts/smoke-config.cjs

@@ -0,0 +1,122 @@
+/**
+ * 冒烟测试：控制台配置表单（Schema）与「表单 → config.json」的落地规则。
+ *
+ * 覆盖：
+ *   1. 每个叶子字段都带默认值（控制台里不再是一片空白）；
+ *   2. 枚举字段都渲染成下拉（union of const），选项里包含默认值，且没有假选项；
+ *   3. 默认值能通过 Schema 校验，非法值会被拒绝；
+ *   4. **与上游默认值相同的项不写回 config.json** —— 用户直接改文件的内容不会被表单默认值盖掉；
+ *   5. 真的改过的项会写回；空数组/空对象仍然算「没填」。
+ *
+ * 用法：node scripts/smoke-config.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-config')
+const cfgDir = path.join(dataRoot, 'koishi-plugin-kkk', 'config')
+const cfgFile = path.join(cfgDir, 'config.json')
+
+const defaults = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'config/default_config/config.json'), 'utf8'))
+
+/** 模拟「用户之前直接在 config.json 里手改过两处」 */
+fs.mkdirSync(cfgDir, { recursive: true })
+const direct = JSON.parse(JSON.stringify(defaults))
+direct.douyin.videoQuality = '1080p'
+direct.app.renderScale = 150
+fs.writeFileSync(cfgFile, JSON.stringify(direct, null, 2))
+
+const results = []
+const check = (name, ok, detail) => {
+  results.push({ name, ok })
+  console.log((ok ? '  ✅ ' : '  ❌ ') + name + (detail ? '  —— ' + detail : ''))
+}
+
+const plugin = require(path.join(pluginRoot, 'lib/index.js'))
+const ctx = new Context()
+// 控制台保存后 koishi.yml 里就是「默认值 + 用户改动」这个样子，这里直接把它整份塞进 upstream
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, upstream: defaults })
+
+setTimeout(async () => {
+  try {
+    const { buildUpstreamSchema } = require(path.join(pluginRoot, 'lib/schema.js'))
+    const { applyUpstreamOverrides } = require(path.join(pluginRoot, 'lib/configBridge.js'))
+    const schema = buildUpstreamSchema(pluginRoot)
+
+    console.log('\n[1] 叶子字段都要有默认值')
+    let leaf = 0
+    let missing = []
+    // Koishi 的 Schema 实例本身是**函数**（schema(value) 就是校验），typeof 判断别写成 !== 'object'
+    const isSchema = (node) => !!node && (typeof node === 'object' || typeof node === 'function')
+    const walkLeaf = (node, fieldPath) => {
+      if (!isSchema(node)) return
+      if (node.type === 'object') {
+        for (const [key, child] of Object.entries(node.dict || {})) walkLeaf(child, fieldPath + '.' + key)
+        return
+      }
+      leaf += 1
+      if (!node.type || node.type === 'any') return
+      if (!node.meta || node.meta.default === undefined) missing.push(fieldPath)
+    }
+    for (const [key, child] of Object.entries(schema.dict)) walkLeaf(child, key)
+    check('所有叶子字段都有默认值', missing.length === 0, missing.length ? '缺失：' + missing.slice(0, 8).join(', ') : '共 ' + leaf + ' 个叶子字段')
+
+    console.log('\n[2] 枚举字段渲染成下拉，且选项里含默认值')
+    const unions = []
+    const walkUnion = (node, fieldPath) => {
+      if (!isSchema(node)) return
+      if (node.type === 'union') { unions.push({ fieldPath, node }); return }
+      if (node.type === 'object') {
+        for (const [key, child] of Object.entries(node.dict || {})) walkUnion(child, fieldPath + '.' + key)
+        return
+      }
+      if (node.type === 'array' && node.inner) walkUnion(node.inner, fieldPath + '[]')
+    }
+    for (const [key, child] of Object.entries(schema.dict)) walkUnion(child, key)
+    const noDefaultInOptions = unions.filter((item) => {
+      const values = item.node.list.map((option) => option.value)
+      const fallback = item.node.meta.default
+      if (Array.isArray(fallback)) return fallback.some((value) => !values.includes(value))
+      return !values.includes(fallback)
+    })
+    check('枚举字段数量合理（≥ 25）', unions.length >= 25, unions.length + ' 个下拉字段')
+    check('每个下拉都包含自己的默认值', noDefaultInOptions.length === 0, noDefaultInOptions.map((item) => item.fieldPath).join(', '))
+    console.log('     权限类字段：' + JSON.stringify(schema.dict.douyin.dict.loginPerm.list.map((option) => option.value)))
+    console.log('     B站画质：' + JSON.stringify(schema.dict.bilibili.dict.videoQuality.list.map((option) => option.value)))
+    console.log('     抖音发送内容：' + JSON.stringify(schema.dict.douyin.dict.sendContent.inner.list.map((option) => option.value)))
+    const perms = schema.dict.app.dict.errorLogSendTo.inner.list.map((option) => option.value)
+    check('errorLogSendTo 没有混进 console 这种假选项', !perms.includes('console'), perms.join(','))
+
+    console.log('\n[3] Schema 校验')
+    let defaultsOk = true
+    try { schema(defaults) } catch (error) { defaultsOk = false; console.log('     ' + error.message) }
+    check('默认配置能通过校验', defaultsOk)
+    let rejected = false
+    try { schema({ douyin: { videoQuality: '999p' } }) } catch { rejected = true }
+    check('非法枚举值被拒绝', rejected)
+
+    console.log('\n[4] 与默认值相同的项不写回 config.json')
+    const untouched = applyUpstreamOverrides(defaults)
+    const afterUntouched = JSON.parse(fs.readFileSync(cfgFile, 'utf8'))
+    check('写回字段数为 0', untouched.changed.length === 0, untouched.changed.slice(0, 5).join(', '))
+    check('手改的 douyin.videoQuality 没被覆盖', afterUntouched.douyin.videoQuality === '1080p', afterUntouched.douyin.videoQuality)
+    check('手改的 app.renderScale 没被覆盖', afterUntouched.app.renderScale === 150, String(afterUntouched.app.renderScale))
+
+    console.log('\n[5] 真的改过的项要写回，空容器仍算没填')
+    const changedResult = applyUpstreamOverrides({ douyin: { videoQuality: '720p' }, app: { renderScale: 120 }, pushlist: { douyin: [] } })
+    const afterChanged = JSON.parse(fs.readFileSync(cfgFile, 'utf8'))
+    check('改过的两项都写回了', changedResult.changed.includes('douyin.videoQuality') && changedResult.changed.includes('app.renderScale'), changedResult.changed.join(', '))
+    check('config.json 里是新值', afterChanged.douyin.videoQuality === '720p' && afterChanged.app.renderScale === 120, afterChanged.douyin.videoQuality + ' / ' + afterChanged.app.renderScale)
+    check('空数组不写回（不算改动）', !changedResult.changed.some((item) => item.startsWith('pushlist')), changedResult.changed.join(', '))
+
+    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)
+}, 4000)

package/scripts/smoke-douyin.cjs

@@ -0,0 +1,170 @@
+/**
+ * 抖音解析链路冒烟测试：把 amagi 的抖音接口替换成固定数据，
+ * 验证「链接识别 → 作品详情 → 清晰度选档 → 下载 → 发送」在 Koishi 侧是否跑得通。
+ * 用途：本机没有抖音 Cookie（接口必被风控）时，仍能验证抖音解析这条最长的业务链路。
+ *
+ * 用法：node scripts/smoke-douyin.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-douyin')
+const cfgDir = path.join(dataRoot, 'koishi-plugin-kkk', 'config')
+fs.mkdirSync(cfgDir, { recursive: true })
+
+const VIDEO_URL = 'https://www.w3schools.com/html/mov_bbb.mp4'
+const COVER_URL = 'https://www.w3schools.com/html/pic_trulli.jpg'
+
+const config = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'config/default_config/config.json'), 'utf8'))
+config.app.parseTip = false
+config.app.removeCache = true
+config.douyin.videoQuality = '720p'
+config.douyin.sendContent = ['info', 'video']
+config.douyin.switch = true
+config.pushlist = { douyin: [], bilibili: [] }
+fs.writeFileSync(path.join(cfgDir, 'config.json'), JSON.stringify(config, null, 2))
+
+// 1) 让 getDouyinID 的短链解析不依赖外网（伪造重定向后的长链）
+const axios = require(path.join(pluginRoot, 'node_modules/axios'))
+const LONG_URL = 'https://www.douyin.com/video/7123456789012345678'
+axios.get = async () => ({ request: { res: { responseUrl: LONG_URL } }, data: '' })
+
+// 2) 替换 amagi 的客户端工厂（每个 Base 实例都会新建 client，必须包住工厂）
+const amagi = require('@ikenxuan/amagi')
+const realFactory = amagi.default
+
+function makeBitRate (definition, width, height) {
+  return {
+    gear_name: definition,
+    quality_type: 28,
+    bit_rate: 1000000,
+    FPS: 30,
+    // 抖音 Web 端与下载都只认 mp4 封装，选档会按 format === 'mp4' 过滤
+    format: 'mp4',
+    video_extra: JSON.stringify({ definition }),
+    play_addr: { uri: 'v', url_list: [VIDEO_URL], data_size: 700000, width, height }
+  }
+}
+
+function makeDetail () {
+  return {
+    aweme_id: '7123456789012345678',
+    aweme_type: 0,
+    is_slides: false,
+    desc: '【迁移验证】抖音视频解析测试',
+    preview_title: '【迁移验证】抖音视频解析测试',
+    create_time: Math.floor(Date.now() / 1000) - 3600,
+    share_url: LONG_URL,
+    share_info: { share_url: LONG_URL },
+    author: {
+      uid: '1234567890',
+      sec_uid: 'SEC_UID_TEST',
+      nickname: '测试作者',
+      unique_id: 'test_author',
+      signature: '这里是签名',
+      avatar_thumb: { url_list: [COVER_URL] },
+      avatar_larger: { url_list: [COVER_URL] },
+      follower_count: 12345
+    },
+    statistics: { digg_count: 1234, comment_count: 56, share_count: 78, collect_count: 910, play_count: 111213 },
+    images: null,
+    music: null,
+    video: {
+      play_addr: { uri: 'v', url_list: [VIDEO_URL], data_size: 700000, width: 1280, height: 720 },
+      play_addr_h264: { uri: 'v', url_list: [VIDEO_URL], data_size: 700000, width: 1280, height: 720 },
+      cover: { url_list: [COVER_URL] },
+      origin_cover: { url_list: [COVER_URL] },
+      dynamic_cover: { url_list: [COVER_URL] },
+      duration: 15000,
+      ratio: '720p',
+      bit_rate: [makeBitRate('1080p', 1920, 1080), makeBitRate('720p', 1280, 720), makeBitRate('540p', 960, 540)]
+    }
+  }
+}
+
+amagi.default = function (options) {
+  const client = realFactory(options)
+  client.douyin.fetcher.parseWork = async () => ({ success: true, code: 200, message: 'OK', data: { aweme_detail: makeDetail() } })
+  client.douyin.fetcher.fetchWorkComments = async () => ({ success: true, code: 200, message: 'OK', data: { comments: [], cursor: 0, has_more: 0, total: 0 } })
+  client.douyin.fetcher.fetchEmojiList = async () => ({ success: true, code: 200, message: 'OK', data: { emoji_list: [] } })
+  client.douyin.fetcher.fetchUserProfile = async () => ({
+    success: true, code: 200, message: 'OK',
+    data: {
+      user: {
+        uid: '1234567890',
+        sec_uid: 'SEC_UID_TEST',
+        nickname: '测试作者',
+        unique_id: 'test_author',
+        signature: '这里是签名',
+        avatar_thumb: { url_list: [COVER_URL] },
+        avatar_larger: { url_list: [COVER_URL] },
+        follower_count: 12345,
+        following_count: 66,
+        total_favorited: 7890,
+        aweme_count: 42,
+        ip_location: '浙江'
+      }
+    }
+  })
+  return client
+}
+
+const plugin = require(path.join(pluginRoot, 'lib/index.js'))
+const ctx = new Context()
+const sent = []
+const fakeBot = {
+  selfId: '10000', platform: 'smoke', status: 1, user: { id: '10000', name: 'smoke' }, ctx,
+  sendMessage: async (channel, content) => { sent.push({ channel, content }); return ['msg-1'] },
+  getGuild: async () => ({ name: 'smoke-guild' }),
+  getFriendList: async () => []
+}
+Object.defineProperty(ctx, 'bots', { get: () => [fakeBot] })
+
+const middlewares = []
+const originalMiddleware = ctx.middleware.bind(ctx)
+ctx.middleware = (fn, ...rest) => { middlewares.push(fn); return originalMiddleware(fn, ...rest) }
+
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, masters: ['12345'], webui: false })
+
+const makeSession = (content) => ({
+  content, selfId: '10000', userId: '12345', guildId: '456', channelId: '456',
+  messageId: 'm1', bot: fakeBot, author: { nick: 'smoke' }, username: 'smoke', event: {},
+  send: async (c) => { sent.push({ channel: '456', content: c }); return ['msg-2'] }
+})
+
+async function dispatch (content) {
+  const session = makeSession(content)
+  let index = 0
+  const run = async () => {
+    while (index < middlewares.length) {
+      const middleware = middlewares[index++]
+      let continued = false
+      await middleware(session, () => { continued = true; return run() })
+      if (!continued) return
+    }
+  }
+  await run()
+}
+
+setTimeout(async () => {
+  try {
+    console.log('=== 抖音链接解析（固定数据） ===')
+    await dispatch('https://www.douyin.com/video/7123456789012345678')
+    console.log('\n=== 共发出 ' + sent.length + ' 条消息 ===')
+    for (const item of sent) {
+      const list = Array.isArray(item.content) ? item.content : [item.content]
+      console.log('→ ' + list.map((el) => {
+        if (typeof el === 'string') return el.slice(0, 160)
+        const type = el && el.type ? el.type : typeof el
+        const attrs = el && el.attrs ? JSON.stringify(el.attrs).slice(0, 120) : ''
+        return '[' + type + '] ' + attrs
+      }).join(' | ').slice(0, 400))
+    }
+  } catch (error) {
+    console.error('抖音冒烟测试失败:', error && error.stack ? error.stack : error)
+    process.exitCode = 1
+  }
+  process.exit(process.exitCode || 0)
+}, 5000)

package/scripts/smoke-koishi-commands.cjs

@@ -0,0 +1,210 @@
+/**
+ * 冒烟测试：指令注册与分发（去掉 # 前缀，注册成真正的 Koishi 指令）。
+ *
+ * 覆盖：
+ *   1. 33 个 karin 命令注册成了 Koishi 指令（在 \$commander 的指令表里、带说明和选项）；
+ *   2. 指令的 action 走通：裸写 \`解析 <链接>\` 与带前缀 \`/解析 <链接>\` 都能触发解析面板；
+ *   3. 旧的 \`#解析 <链接>\` 仍可用（兜底中间件）；
+ *   4. 消息里的链接自动解析（链接识别那条路）依旧工作，且遇到指令消息要让路；
+ *   5. 面板按钮发出去的就是「不带 # 的指令」，并随平台切换 解析 / 弹幕解析；
+ *   6. autoParse=false 时裸链接不再解析。
+ *
+ * 用法：node scripts/smoke-koishi-commands.cjs
+ * 说明：测试用 QQ 平台（platform=qqguild），解析会先出「交互面板」，
+ *       既验证了指令链路，又不会真的去下载视频。
+ */
+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-kcmd')
+fs.mkdirSync(path.join(dataRoot, 'koishi-plugin-kkk', 'config'), { recursive: true })
+const config = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'config/default_config/config.json'), 'utf8'))
+config.app.parseTip = false
+fs.writeFileSync(path.join(dataRoot, 'koishi-plugin-kkk', 'config', 'config.json'), JSON.stringify(config, null, 2))
+
+const plugin = require(path.join(pluginRoot, 'lib/index.js'))
+const ctx = new Context()
+let sent = []
+const fakeBot = {
+  selfId: '10000', platform: 'qqguild', status: 1, user: { id: '10000', name: 's' }, ctx,
+  sendMessage: async (ch, c) => { sent.push(c); return ['m'] },
+  getGuild: async () => ({ name: 'g' }), getFriendList: async () => []
+}
+Object.defineProperty(ctx, 'bots', { get: () => [fakeBot] })
+
+// 抓住所有中间件（含 Koishi 指令分发自己的那条），手动串成链
+const middlewares = []
+const original = ctx.middleware.bind(ctx)
+ctx.middleware = (fn, ...rest) => { middlewares.push(fn); return original(fn, ...rest) }
+
+ctx.plugin(plugin, { dataPath: dataRoot, debug: true, masters: ['12345'], qqPanel: true })
+
+const results = []
+const check = (name, ok, detail) => {
+  results.push({ name, ok })
+  console.log((ok ? '  ✅ ' : '  ❌ ') + name + (detail ? '  —— ' + detail : ''))
+}
+
+const URL = 'https://www.bilibili.com/video/BV1xx411c7mD'
+
+const makeSession = (content) => ({
+  content, selfId: '10000', userId: '12345', guildId: '456', channelId: '456', messageId: 'm1',
+  bot: fakeBot, author: { nick: 's' }, username: 's', event: {}, user: { id: '12345' },
+  send: async (c) => { sent.push(c); return ['m2'] }
+})
+
+/** 读这一次 dispatch 发出的面板内容 */
+const readSent = () => {
+  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 { sent: sent.length, markdown, buttons }
+}
+
+/** 走中间件链（验证「链接自动解析」和旧的 # 写法） */
+const dispatchMiddleware = async (content) => {
+  sent = []
+  const session = makeSession(content)
+  let index = 0
+  const run = async () => {
+    while (index < middlewares.length) {
+      const middleware = middlewares[index++]
+      let continued = false
+      await middleware(session, () => { continued = true; return run() })
+      if (!continued) return
+    }
+  }
+  await run()
+  return readSent()
+}
+
+/** 走 Koishi 指令的 action（就是指令匹配成功后 Koishi 会调用的那个函数） */
+const runCommand = async (name, content) => {
+  const command = ctx.$commander._commandList.find((item) => item.name === name)
+  if (!command) throw new Error('没有注册指令: ' + name)
+  sent = []
+  const session = makeSession(content)
+  await command._actions[command._actions.length - 1]({ session, options: {}, args: [] })
+  return readSent()
+}
+
+setTimeout(async () => {
+  try {
+    console.log('\n[1] 注册成真正的 Koishi 指令')
+    const list = ctx.$commander._commandList
+    const names = list.map((item) => item.name)
+    const i18n = ctx.i18n._data[''] || {}
+    const desc = (name) => i18n['commands.' + name + '.description'] || ''
+    check('指令表里有 解析 / 弹幕解析 / kkk帮助', ['解析', '弹幕解析', 'kkk帮助'].every((name) => names.includes(name)), '共 ' + names.length + ' 个')
+    check('指令不再是 # 开头', names.every((name) => !name.startsWith('#')))
+    check('指令带说明（控制台可见）', desc('解析').length > 0 && desc('弹幕解析').length > 0, '解析: ' + desc('解析') + ' / 弹幕解析: ' + desc('弹幕解析'))
+    check('权限类指令也在表里', names.includes('b站登录') && names.includes('设置抖音推送'), names.filter((name) => /登录|推送/.test(name)).length + ' 个')
+    const parseCmd = list.find((item) => item.name === '解析')
+    check('解析 指令声明了面板用到的选项', ['qn', 'q', 'dm', 'panel'].every((key) => key in (parseCmd._options || {})), Object.keys(parseCmd._options || {}).join(','))
+
+    console.log('\n[2] 指令 action 走通（裸写与带前缀）')
+    const bare = await runCommand('解析', '解析 ' + URL)
+    check('「解析 <链接>」触发解析面板', /解析设置/.test(bare.markdown), bare.markdown.split('\n')[0] || '（无输出）')
+    const slash = await runCommand('解析', '/解析 ' + URL)
+    check('「/解析 <链接>」同样触发', /解析设置/.test(slash.markdown))
+
+    console.log('\n[3] 面板按钮发的是不带 # 的指令')
+    console.log('     按钮：' + bare.buttons.map((button) => '[' + button.label + ']').join(' '))
+    check('按钮里没有 # 前缀', bare.buttons.length > 0 && bare.buttons.every((button) => !String(button.data).startsWith('#')), bare.buttons[0] && bare.buttons[0].data)
+    check('按钮文本是 解析/弹幕解析 指令预览', bare.buttons.every((button) => /^(解析|弹幕解析) /.test(String(button.data))), bare.buttons.map((button) => button.data).slice(0, 2).join(' | '))
+    check('按钮里不带链接（只放短令牌）', bare.buttons.every((button) => !/https?:\/\//.test(String(button.data))), bare.buttons.map((button) => button.data).join(' | '))
+    check('按钮长度可控（≤ 40 字符）', bare.buttons.every((button) => String(button.data).length <= 40), '最长 ' + Math.max(...bare.buttons.map((button) => String(button.data).length)) + ' 字符')
+    const danmakuButton = bare.buttons.find((button) => String(button.data).startsWith('弹幕解析 '))
+    check('存在「弹幕解析」按钮', !!danmakuButton, danmakuButton && danmakuButton.data)
+    check('没有任何按钮带 --panel（点了不会再弹面板）', bare.buttons.every((button) => !String(button.data).includes('--panel')), bare.buttons.map((button) => button.data).join(' | '))
+    const { resolvePanelToken } = require(path.join(pluginRoot, 'lib/karin/module/utils/QqPanel.js'))
+    const token = (String(bare.buttons[0].data).match(/--p=([0-9a-z]+)/) || [])[1]
+    check('短令牌能换回真实链接', resolvePanelToken(token) === URL, token + ' → ' + resolvePanelToken(token))
+
+    console.log('\n[4] 旧的 # 写法与链接自动解析仍然可用')
+    const legacy = await dispatchMiddleware('#解析 ' + URL)
+    check('旧的 #解析 仍可用（兜底中间件）', /解析设置/.test(legacy.markdown))
+    const link = await dispatchMiddleware(URL)
+    check('裸链接触发解析面板', /解析设置/.test(link.markdown))
+    check('只发一条（没有重复解析）', link.sent === 1, '共 ' + link.sent + ' 条')
+
+    console.log('\n[5] 按钮文本能被解析成参数（点下去就是一次带参数的解析）')
+    const { parseParseFlags } = require(path.join(pluginRoot, 'lib/karin/module/utils/ParseOverride.js'))
+    if (danmakuButton) {
+      const flags = parseParseFlags(String(danmakuButton.data))
+      check('带上了画质与令牌', flags.override.bilibiliQuality === 16 && !!flags.panelToken, JSON.stringify(flags.override) + ' token=' + flags.panelToken)
+      check('指令名决定要不要弹幕（不再用 --dm=1）', String(danmakuButton.data).startsWith('弹幕解析 ') && flags.override.burnDanmaku === undefined)
+    }
+
+    console.log('\n[6] 按钮点击的另一种落地方式：interaction/button 事件')
+    {
+      sent = []
+      const interactionSession = {
+        content: '', selfId: '10000', userId: '12345', guildId: '456', channelId: '456', messageId: 'm1',
+        bot: fakeBot, author: { nick: 's' }, username: 's', user: { id: '12345' },
+        event: { button: { id: 'b1', data: 'kkk版本' } },
+        send: async (c) => { sent.push(c); return ['m3'] }
+      }
+      ctx.emit('interaction/button', interactionSession)
+      await new Promise((resolve) => setTimeout(resolve, 1500))
+      check('回调按钮事件里的指令被执行了', sent.length > 0, '发出 ' + sent.length + ' 条')
+    }
+
+    console.log('\n[7] 其它指令也走通了同一条 action 包装')
+    const version = await runCommand('kkk版本', 'kkk版本')
+    check('「kkk版本」有回复', version.sent > 0, '发出 ' + version.sent + ' 条')
+    const help = await runCommand('kkk帮助', 'kkk帮助')
+    check('「kkk帮助」有回复', help.sent > 0, '发出 ' + help.sent + ' 条')
+
+    console.log('\n[8] Koishi 没认领时，文本兜底也能跑（宿主 prefix 没配空串的情况）')
+    // 假会话没有 argv（等于 Koishi 没把这条当指令），此时必须靠插件自己的文本兜底
+    const fallback = await dispatchMiddleware('kkk版本')
+    check('无前缀指令文本仍能被执行', fallback.sent > 0, '发出 ' + fallback.sent + ' 条')
+    const legacyLink = await dispatchMiddleware(URL)
+    check('裸链接走链接识别那条路（照常出面板）', /解析设置/.test(legacyLink.markdown))
+
+    console.log('\n[9] autoParse=false 时裸链接不再解析')
+    const ctx2 = new Context()
+    const middlewares2 = []
+    const original2 = ctx2.middleware.bind(ctx2)
+    ctx2.middleware = (fn, ...rest) => { middlewares2.push(fn); return original2(fn, ...rest) }
+    ctx2.plugin(plugin, { dataPath: dataRoot, debug: true, masters: ['12345'], autoParse: false })
+    await new Promise((resolve) => setTimeout(resolve, 1500))
+    let sent2 = []
+    const session2 = {
+      content: URL, selfId: '10000', userId: '12345', guildId: '456', channelId: '456', messageId: 'm1',
+      bot: { ...fakeBot, sendMessage: async (ch, c) => { sent2.push(c); return ['m'] } },
+      author: { nick: 's' }, username: 's', event: {}, user: { id: '12345' },
+      send: async (c) => { sent2.push(c); return ['m2'] }
+    }
+    let index = 0
+    const run = async () => {
+      while (index < middlewares2.length) {
+        const middleware = middlewares2[index++]
+        let continued = false
+        await middleware(session2, () => { continued = true; return run() })
+        if (!continued) return
+      }
+    }
+    await run()
+    check('autoParse=false 时裸链接不解析', sent2.length === 0, '发出 ' + sent2.length + ' 条')
+
+    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)