koishi-plugin-kkk 3.2.2 → 3.3.0-beta.2

package/lib/compat/node-karin.js

@@ -28,6 +28,8 @@ const node_url_1 = require("node:url");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const koishi_1 = require("koishi");
+// 版本比较复用注入器那边的实现（它处理了 -beta.1 这类预发布号的先后）
+const semver_1 = require("../karin/module/utils/semver");
 const logger_1 = require("./logger");
 Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
 const forward_collect_1 = require("./forward-collect");
@@ -954,11 +956,21 @@ const checkPkgUpdate = async (name, _options) => {
         if (!response.ok)
             return { status: 'error', error: new Error('HTTP ' + response.status) };
         const meta = await response.json();
-        const remote = meta?.['dist-tags']?.latest;
+        const tags = meta?.['dist-tags'] ?? {};
+        /**
+         * 预览版（3.3.0-beta.1 这种）**不能拿 latest 比**：本地跑 beta 时 latest 还在 3.2.2，
+         * 按老逻辑会报「有新版本 3.2.2」—— 那其实是**降级**。
+         * 所以带 - 的本地版本改看 beta 通道；beta 没有（说明预览已经并进正式版）才回退到 latest，
+         * 并且只在远端确实比本地新时才说「有更新」。
+         */
+        const isPreview = local.includes('-');
+        const remote = (isPreview ? (tags.beta || tags.latest) : tags.latest) || '';
         if (!remote)
             return { status: 'error', error: new Error('响应缺少 dist-tags.latest') };
         if (remote === local)
             return { status: 'no', local };
+        if (isPreview && !(0, semver_1.isSemverGreater)(remote, local))
+            return { status: 'no', local };
         return { status: 'yes', local, remote };
     }
     catch (error) {

package/lib/index.js

@@ -135,11 +135,31 @@ exports.inject = {
  */
 /** 摊平后由「Koishi 原生设置」分组提供的字段 */
 const NATIVE_KEYS = ['masters', 'dataPath', 'debug', 'autoParse', 'webUiAuth'];
+/**
+ * 控制台里**唯一可见**的一段文字：把用户指到 WebUI 面板去。
+ *
+ * 为什么把设置全藏了：同一份配置在控制台改一半、在面板改一半，两边都会把整份配置写回
+ * koishi.yml，很容易互相覆盖（用户实际遇到过「面板里关了、控制台一保存又回来了」）。
+ * 现在控制台不再提供编辑入口，只留这块说明。
+ *
+ * 注意：**隐藏不等于删除** —— 字段仍然在 schema 里声明着，所以在控制台里点保存
+ * 一样会把已有值带上，面板里的设置不会被清空。
+ */
+const WEBUI_GUIDE = [
+    '**所有设置都在 WebUI 配置面板里改**，地址：/kkk（打开 Koishi 控制台后，左侧边栏也有一个「**kkk 配置**」入口）。',
+    '',
+    '面板里包含：接口库 / 通用（含**错误上报**、在线播放器、合并转发）/ 抖音 / 哔哩哔哩 / 快手 / 小红书 / **QQ 适配器** / 推送列表。' +
+        '改完点右下角保存即可 —— 会写回 koishi.yml 并热重载，**不用重启**。',
+    '',
+    '**Koishi 控制台里的设置项已经全部隐藏**（值仍然保留，在这里点保存也不会把它们弄丢），免得两边各改一半、互相覆盖。',
+    '',
+    '面板里还有一组「**Koishi 设置**」（数据目录、调试日志、自动解析、面板是否要求先登录控制台）。' +
+        '只有 masters（主人账号）没有面板入口 —— 它属于 Koishi 的权限体系，而面板是免登录页面，' +
+        '需要直接改 koishi.yml 里本插件的配置段（改完重启 Koishi）。'
+].join('\n');
 exports.Config = koishi_1.Schema.intersect([
     koishi_1.Schema.object({
-        webuiGuide: koishi_1.Schema.const('').description('**本插件的配置都在配置面板里改**：Koishi 控制台左侧边栏 →「**kkk 配置**」。\n\n' +
-            '（原版配置面板：接口库 / 通用 / 抖音 / 哔哩哔哩 / 快手 / 小红书 / **QQ 适配器** / 推送列表，' +
-            '改完点右下角保存即可，写回 koishi.yml 并热重载，不用重启。）'),
+        webuiGuide: koishi_1.Schema.const('').description(WEBUI_GUIDE),
         // 全部隐藏：控制台表单里不显示，配置统一在控制台侧边栏的「kkk 配置」面板里改
         qq: (0, qqOptions_1.buildQqSchema)(koishi_1.Schema).hidden().description('QQ 适配器（只对 QQ 平台生效）'),
         advanced: koishi_1.Schema.object({
@@ -149,7 +169,7 @@ exports.Config = koishi_1.Schema.intersect([
             autoParse: koishi_1.Schema.boolean().default(true).description('群里有人发链接（或回复一条带链接的消息）就自动解析，不用打指令'),
             webUiAuth: koishi_1.Schema.boolean().default(true).description('配置面板 /kkk 是否要求先登录 Koishi 控制台（默认开）。装了 auth 插件的部署只有登录后才能打开面板；没装 auth 插件时本来就没有登录这一说，这里不生效'),
         }).collapse().hidden().description('Koishi 原生设置（一般不用改，已折叠）'),
-    }),
+    }).description('配置入口：请在 WebUI 面板（/kkk）里修改'),
     koishi_1.Schema.object({
         /**
          * 合并转发（两级开关）。
@@ -184,7 +204,7 @@ exports.Config = koishi_1.Schema.intersect([
             xiaohongshu: koishi_1.Schema.boolean().default(false).description('小红书：单独打开合并转发（全局关着时生效）'),
             xiaohongshuContent: koishi_1.Schema.array(koishi_1.Schema.union(['text', 'image', 'video', 'file'])).default([])
                 .description('小红书转发合并哪些内容（留空 = 用全局那份）')
-        }).description('合并转发（全局 + 各平台）'),
+        }).collapse().hidden().description('合并转发（全局 + 各平台）'),
         upstream: (0, schema_1.buildUpstreamSchema)(pluginRootDir).hidden().description('插件自身的配置（与 Karin 版 config.json 一致）。每项都带着上游默认值，枚举型字段是下拉框；' +
             '**与默认值不同**的项会在启动时写回 config.json，保持默认值的项不写（这样你直接改文件的内容不会被覆盖）')
     })

package/lib/karin/module/utils/CardParser.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveCardToUrl = exports.searchDouyinWorks = exports.searchBiliVideos = exports.extractUpNames = exports.extractUpName = exports.ocrImageText = exports.extractCardInfo = void 0;
+exports.resolveCardToUrl = exports.searchBiliVideos = exports.extractUpNames = exports.extractUpName = exports.ocrImageText = exports.extractCardInfo = void 0;
 /**
  * QQ 卡片消息解析（小程序卡片 / 分享卡片）。
  *
@@ -19,7 +19,6 @@ exports.resolveCardToUrl = exports.searchDouyinWorks = exports.searchBiliVideos
 const node_crypto_1 = require("node:crypto");
 const node_karin_1 = require("../../../compat/node-karin.js");
 const runtime_1 = require("../../../compat/runtime");
-const amagiClient_1 = require("./amagiClient");
 const Config_1 = require("./Config");
 /** Wbi 签名的置换表（B站前端固定的那一份） */
 const MIXIN_KEY_ENC_TAB = [
@@ -441,55 +440,6 @@ const searchBiliVideos = async (keyword, title = '', author = '', limit = 8) =>
     }
 };
 exports.searchBiliVideos = searchBiliVideos;
-/* ------------------------------------------------------------------ *
- * 抖音搜索（直接用 amagi 的 search 端点）
- * ------------------------------------------------------------------ */
-const searchDouyinWorks = async (keyword, limit = 8, authors = []) => {
-    try {
-        // 这版接口库的抖音 fetcher 不一定有 search（实测 6.6.0 上没有），没有就干脆跳过
-        const fetcher = amagiClient_1.douyinFetcher;
-        if (typeof fetcher?.search !== 'function') {
-            node_karin_1.logger.debug('[卡片解析] 当前接口库没有抖音搜索能力，跳过');
-            return [];
-        }
-        const res = await fetcher.search({ query: String(keyword ?? '').trim(), type: 'video', number: limit });
-        const list = res?.data?.data?.aweme_list ?? res?.data?.aweme_list ?? res?.aweme_list ?? [];
-        const titleKey = normalizeText(keyword);
-        const authorKeys = authors.map((item) => normalizeText(item)).filter((item) => item.length >= 2);
-        return list
-            .filter((item) => item?.aweme_id)
-            .map((item, index) => {
-            const desc = String(item.desc ?? '');
-            const sim = titleSimilarity(normalizeText(desc), titleKey);
-            // 作者对上一样加分：抖音搜索噪声大，光靠标题常常分不出是哪一条
-            const authorKey = normalizeText(String(item.author?.nickname ?? ''));
-            let authorScore = 0;
-            for (const key of authorKeys) {
-                if (!authorKey)
-                    break;
-                if (authorKey === key) {
-                    authorScore = 60;
-                    break;
-                }
-                if (authorKey.includes(key) || key.includes(authorKey))
-                    authorScore = Math.max(authorScore, 35);
-            }
-            return {
-                aweme_id: String(item.aweme_id),
-                desc,
-                author: String(item.author?.nickname ?? ''),
-                score: Math.round(sim * 100) + authorScore - index
-            };
-        })
-            .sort((left, right) => right.score - left.score)
-            .slice(0, Math.max(1, Math.min(20, limit)));
-    }
-    catch (error) {
-        node_karin_1.logger.warn('[卡片解析] 抖音搜索异常: ' + String(error?.message ?? error));
-        return [];
-    }
-};
-exports.searchDouyinWorks = searchDouyinWorks;
 const resolveCardToUrl = async (content) => {
     const card = (0, exports.extractCardInfo)(content);
     if (!card)
@@ -521,11 +471,7 @@ const resolveCardToUrl = async (content) => {
         node_karin_1.logger.mark('[卡片解析] OCR 没有给出可用关键词');
         return null;
     }
-    /** 卡片自带的 source 字段最准（实测 `source: 哔哩哔哩`），其次是 OCR 文本 */
-    const hint = String(card.source ?? '') + ' ' + card.title + ' ' + card.desc + ' ' + upName + ' ' + ocrText;
-    const looksDouyin = /抖音|douyin|快手|ks\./i.test(hint);
-    const looksBili = /bilibili|哔哩|B站|UP主/i.test(hint);
-    // ③ 先按最可能的平台搜，命中就返回
+    // ③ B站搜一把：标题 + 作者都对上才自动继续，否则把候选交给用户挑
     const tryBili = async () => {
         const hits = await (0, exports.searchBiliVideos)(keyword, card.title, upNames, 8);
         const candidates = hits.slice(0, 6).map((item) => ({
@@ -540,30 +486,17 @@ const resolveCardToUrl = async (content) => {
         }
         return { candidates };
     };
-    const tryDouyin = async () => {
-        const hits = await (0, exports.searchDouyinWorks)(keyword || card.title, 8, upNames);
-        const candidates = hits.slice(0, 6).map((item) => ({
-            platform: 'douyin', id: item.aweme_id, title: item.desc, author: item.author, score: item.score
-        }));
-        const best = hits[0];
-        // 抖音搜索噪声大，要求分数足够高才自动继续，否则交给用户挑
-        if (best && best.score > 40)
-            return { url: 'https://www.douyin.com/video/' + best.aweme_id, candidates };
-        return { candidates };
-    };
-    const order = looksDouyin && !looksBili ? [tryDouyin, tryBili] : [tryBili, tryDouyin];
-    const candidates = [];
-    for (const attempt of order) {
-        const hit = await attempt();
-        if (hit) {
-            candidates.push(...hit.candidates);
-            if (hit.url) {
-                node_karin_1.logger.mark('[卡片解析] 定位成功: ' + hit.url);
-                // 提示语里报「真正匹配上的那个 UP 名」，而不是卡片摘要里那个不准的
-                const matched = hit.matchedAuthor || upName;
-                return { url: hit.url, platform: hit.url.includes('bilibili') ? 'bilibili' : 'douyin', card, candidates, ocrText, upName: matched };
-            }
-        }
+    /**
+     * **只搜 B站**：抖音没有卡片消息这种玩法（那条「当前接口库没有抖音搜索能力」的日志就是
+     * 以前多此一举地搜抖音留下的）。卡片解析这条链路只处理 B站卡片（入口处已经按 source 过滤过），
+     * 少搜一个平台就少一次风控风险、也少几秒等待。
+     */
+    const hit = await tryBili();
+    const candidates = hit.candidates;
+    if (hit.url) {
+        node_karin_1.logger.mark('[卡片解析] 定位成功: ' + hit.url);
+        // 提示语里报「真正匹配上的那个 UP 名」，而不是卡片摘要里那个不准的
+        return { url: hit.url, platform: 'bilibili', card, candidates, ocrText, upName: hit.matchedAuthor || upName };
     }
     node_karin_1.logger.mark('[卡片解析] 没能唯一定位（标题: ' + card.title + '，UP: ' + upName + '），候选 ' + candidates.length + ' 条');
     if (candidates.length) {

package/lib/karin/module/utils/ErrorReport.js

@@ -301,11 +301,17 @@ const errorHelpSegments = (report, platform) => {
         ? '错误信息已上传，ID：' + report.id
         : '错误信息上传失败（不影响使用）';
     const ask = '可以前往 QQ 群内寻找帮助，在群内发送错误 ID 或该错误图片';
+    /**
+     * 两段之间必须**空一行**（\n\n）。
+     *
+     * markdown 里单个换行不算换行：两段会被拼成一整行，QQ 那边按一行显示时字号会被撑得很难看
+     * （用户原话「不换行大小会崩」）。纯文本那条也一样留空行，两种平台的观感才对得上。
+     */
     if (officialQq) {
         // QQ 官方机器人认 markdown：群号做成可点的加群链接
-        return [node_karin_1.segment.markdown(head + '\n' + '可以前往 [QQ 群 ' + group + '](' + link + ') 内寻找帮助，在群内发送错误 ID 或该错误图片')];
+        return [node_karin_1.segment.markdown(head + '\n\n' + '可以前往 [QQ 群 ' + group + '](' + link + ') 内寻找帮助，在群内发送错误 ID 或该错误图片')];
     }
     // 个人号（OneBot / NapCat）不渲染 markdown：裸链接 QQ 客户端自己会变蓝可点
-    return [node_karin_1.segment.text(head + '\nQQ 群 ' + group + '：' + ask + '\n' + link)];
+    return [node_karin_1.segment.text(head + '\n\nQQ 群 ' + group + '：' + ask + '\n' + link)];
 };
 exports.errorHelpSegments = errorHelpSegments;

package/lib/karin/platform/kuaishou/kuaishou.js

@@ -6,6 +6,8 @@ const module_1 = require("../../module");
 const ParseSteps_1 = require("../../module/utils/ParseSteps");
 // sendParseTip 单独导入：它在一个无依赖的叶子模块里，避免和平台模块形成循环 import
 const parseTip_1 = require("../../module/utils/parseTip");
+// 注意用相对写法：@/ 别名在仓库里指向 karin/，@/player 会被解析成不存在的 karin/player
+const player_1 = require("../../../player");
 const kuaishou_1 = require("../../platform/kuaishou");
 /**
  * 从作品详情里挑一条视频直链。
@@ -95,7 +97,7 @@ class Kuaishou extends module_1.Base {
         /** 发送任务组：评论区与视频各走一条线，谁先就绪谁先发 */
         /** 强制在线播放名单里的平台：本次一律走在线播放（见 player/index.ts） */
         // 适配器在「强制在线播放的适配器」名单里（例如 B站私聊机器人 platform === 'bilibili'）
-        applyForceOnlinePlayer(this.e);
+        (0, player_1.applyForceOnlinePlayer)(this.e);
         const sends = new ParseSteps_1.SendTasks(steps);
         await (0, parseTip_1.sendParseTip)(this.e, '快手');
         // 表情接口没换，还是 graphql 那条，`data.visionBaseEmoticons` 两层照旧

package/lib/karin/platform/xiaohongshu/xiaohongshu.js

@@ -12,6 +12,8 @@ const date_fns_1 = require("date-fns");
 const node_karin_1 = require("../../../compat/node-karin.js");
 const node_karin_2 = require("../../../compat/node-karin.js");
 const module_1 = require("../../module");
+// 注意用相对写法：@/ 别名在仓库里指向 karin/，@/player 会被解析成不存在的 karin/player
+const player_1 = require("../../../player");
 const ParseSteps_1 = require("../../module/utils/ParseSteps");
 const Config_1 = require("../../module/utils/Config");
 const comments_1 = require("./comments");
@@ -53,7 +55,7 @@ class Xiaohongshu extends module_1.Base {
         /** 发送任务组：内容（详情卡片 / 图片）与视频各走一条线，谁先就绪谁先发 */
         /** 强制在线播放名单里的平台：本次一律走在线播放（见 player/index.ts） */
         // 适配器在「强制在线播放的适配器」名单里（例如 B站私聊机器人 platform === 'bilibili'）
-        applyForceOnlinePlayer(this.e);
+        (0, player_1.applyForceOnlinePlayer)(this.e);
         const sends = new ParseSteps_1.SendTasks(steps);
         // 诊断：把入参和每一步的结果打出来，定位「只提示不解析」卡在哪
         node_karin_2.logger.mark('[小红书] 开始解析: note_id=' + String(data?.note_id ?? '（空）') + ' xsec_token=' + (data?.xsec_token ? '有' : '（空）') + ' type=' + String(this.type));

package/lib/webui.js

@@ -31,6 +31,29 @@ const configBridge_1 = require("./configBridge");
 const qqOptions_1 = require("./qqOptions");
 const COOKIE_NAME = 'kkk_config_token';
 const TOKEN_TTL = 7 * 24 * 60 * 60 * 1000;
+/**
+ * 面板「Koishi 设置」分类里能改的项 —— 也就是 Koishi 侧的原生选项（koishi.yml 里本插件的顶层键）。
+ *
+ * **masters 不在这里**：主人账号是 Koishi 的权限体系（谁能执行主人指令、谁收报错），
+ * 面板是免登录页面，不该给它开这个口子 —— 仍然只在 koishi.yml 里改。
+ * 控制台那边也已经全部隐藏，所以这 4 项是唯一还有图形入口的地方。
+ */
+const NATIVE_PANEL_KEYS = ['dataPath', 'debug', 'autoParse', 'webUiAuth'];
+/** 面板要显示的原生设置（只取白名单，缺的用默认值兜底） */
+const NATIVE_PANEL_DEFAULTS = {
+    dataPath: 'data',
+    debug: false,
+    autoParse: true,
+    webUiAuth: true
+};
+const readNativePanelOptions = (source) => {
+    const out = {};
+    for (const key of NATIVE_PANEL_KEYS) {
+        const value = source?.[key];
+        out[key] = value === undefined || value === null ? NATIVE_PANEL_DEFAULTS[key] : value;
+    }
+    return out;
+};
 function registerWebUi({ ctx, config, rawConfig, logger, pluginRoot }) {
     const server = ctx.server;
     if (!server || typeof server.get !== 'function') {
@@ -337,7 +360,8 @@ function registerWebUi({ ctx, config, rawConfig, logger, pluginRoot }) {
         // 在 Koishi 这边它就存在 `upstream` 里，启动时同步进 config.json。
         // 另外附一份 `qq`（「QQ 适配器」分类）：面板/切片/番剧选集/卡片识别这些是 Koishi 侧才有的开关，
         // 面板里作为独立分类显示，保存时由下面的 POST 拆出来写回 koishi.yml。
-        ok(response, { ...(config?.upstream ?? {}), qq: (0, qqOptions_1.readQqOptions)(config) }, '');
+        // koishi 这一组是「Koishi 设置」分类：Koishi 侧的原生选项（masters 不在里面，见 NATIVE_PANEL_KEYS）
+        ok(response, { ...(config?.upstream ?? {}), qq: (0, qqOptions_1.readQqOptions)(config), koishi: readNativePanelOptions(config) }, '');
     });
     server.post('/kkk/v1/config', async (response) => {
         if (!authed(response))
@@ -350,10 +374,21 @@ function registerWebUi({ ctx, config, rawConfig, logger, pluginRoot }) {
             //   - `qq`（面板里的「QQ 适配器」分类）→ 写回插件自己的配置（koishi.yml）
             //   - 其余整份 → upstream（Karin 版的 config.json 形状）
             // 保存都走 scope.update → 落盘 koishi.yml → 热重载 → 启动时同步回 config.json
-            const { qq, ...upstream } = normalizeLists(body);
+            const { qq, koishi: nativeGroup, ...upstream } = normalizeLists(body);
+            // 「Koishi 设置」分类：只认白名单里的键（前端传什么都写不进来别的东西）
+            const native = {};
+            if (nativeGroup && typeof nativeGroup === 'object') {
+                for (const key of NATIVE_PANEL_KEYS) {
+                    if (nativeGroup[key] === undefined)
+                        continue;
+                    native[key] = typeof NATIVE_PANEL_DEFAULTS[key] === 'boolean' ? !!nativeGroup[key] : String(nativeGroup[key]);
+                }
+            }
             await ctx.scope.update(normalize({
                 ...(rawConfig ?? config),
                 ...(qq && typeof qq === 'object' ? { qq: { ...(0, qqOptions_1.readQqOptions)(config), ...qq } } : {}),
+                // 注意：原生这几项是**顶层键**（dataPath / debug / autoParse / webUiAuth），不要塞进分组
+                ...native,
                 upstream
             }));
             /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-kkk",
-  "version": "3.2.2",
+  "version": "3.3.0-beta.2",
   "description": "抖音 / B站 / 快手 / 小红书 视频解析与动态推送，带 QQ 交互面板与弹幕烧录（karin-plugin-kkk 的 Koishi 移植版）",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

package/scripts/patch-webui.mjs

@@ -244,6 +244,73 @@ const CATEGORY_ANCHOR = ',{key:' + q('pushlist') + ',label:' + q('推送列表')
 const SWITCH_ANCHOR = 'case' + q('pushlist') + ':return(0,U.jsx)(MR,{...e})'
 const COMPONENT_ANCHOR = ',PR=e=>{switch(e.activeFile){'
 
+/* ------------------------------------------------------------------ *
+ * 「Koishi 设置」分类：插件在 Koishi 里的运行参数
+ * ------------------------------------------------------------------ */
+
+const KOISHI_START = '/*KKK-KOISHI-START*/'
+const KOISHI_END = '/*KKK-KOISHI-END*/'
+const KOISHI_COMPONENT = 'KKKNativeConfig'
+const KOISHI_CATEGORY = '{key:' + q('koishi') + ',label:' + q('Koishi 设置') + ',description:' + q('插件本体设置') + '}'
+const KOISHI_SWITCH = ';case' + q('koishi') + ':return(0,U.jsx)(' + KOISHI_COMPONENT + ',{...e})'
+
+/**
+ * 这一分类里的字段渲染器调用。
+ *
+ * 存的位置是 koishi.yml 里本插件的**顶层键**（dataPath / debug / autoParse / webUiAuth），
+ * 所以路径写 ['koishi', 字段名]，服务端（src/webui.ts 的 NATIVE_PANEL_KEYS）拆出来写回顶层。
+ *
+ * **masters 不在这里**：主人账号属于 Koishi 的权限体系，而面板是免登录页面，
+ * 不该给它开口子 —— 仍然只在 koishi.yml 里改（控制台那边也全部隐藏了）。
+ */
+const koishiFieldCode = [
+  'n(' + q('Koishi 设置') + ',' + q('插件在 Koishi 里的运行参数。改完点右下角保存即可 —— 会写回 koishi.yml 并热重载，不用重启。') + ')',
+  'r(' + q('基础') + ',(0,U.jsxs)(U.Fragment,{children:[' + [
+    'i(' + arr(['koishi', 'autoParse']) + ',' + q('自动解析') + ',' + q('群里有人发链接（或回复一条带链接的消息）就自动解析，不用打指令。') + ')',
+    'i(' + arr(['koishi', 'debug']) + ',' + q('调试日志') + ',' + q('在日志里输出调试信息，排查问题时才需要打开 —— 打开后日志会很吵。') + ')',
+    'a(' + arr(['koishi', 'dataPath']) + ',' + q('数据目录') + ',' + q('配置、数据库、临时文件都放在这里（一般是绝对路径，例如 D:/devkoishi/data）。改完需要重启 Koishi 才生效。') + ',{type:' + q('text') + '})',
+    'i(' + arr(['koishi', 'webUiAuth']) + ',' + q('面板需要登录控制台') + ',' + q('打开时 /kkk 面板要求先登录 Koishi 控制台（装了 auth 插件的部署）。没装 auth 插件时本来就没有登录这一说，这里不生效。') + ')'
+  ].join(',') + ']}))'
+].join(',')
+
+const koishiComponentCode = KOISHI_COMPONENT
+  + '=({config:e,renderers:t})=>{let{renderPageHeader:n,renderSubSection:r,renderSwitch:i,renderTextField:a}=t;return(0,U.jsxs)(U.Fragment,{children:[' + koishiFieldCode + ']})}'
+
+/** 去掉上次插入的 Koishi 分类片段（可反复执行） */
+function stripKoishiCategory (text) {
+  let out = text
+  for (;;) {
+    const start = out.indexOf(KOISHI_START)
+    if (start < 0) break
+    const end = out.indexOf(KOISHI_END, start)
+    if (end < 0) break
+    const from = out[start - 1] === ',' ? start - 1 : start
+    out = out.slice(0, from) + out.slice(end + KOISHI_END.length)
+  }
+  out = out.split(',' + KOISHI_CATEGORY).join('')
+  out = out.split(KOISHI_SWITCH).join('')
+  return out
+}
+
+function patchKoishiCategory (text, name) {
+  if (!text.includes(KOISHI_COMPONENT) && !text.includes(',' + CATEGORY)) return text
+  let out = stripKoishiCategory(text)
+  // 分类入口：插在「QQ 适配器」之后
+  const categoryAnchor = ',' + CATEGORY
+  if (out.includes(categoryAnchor)) {
+    out = out.replace(categoryAnchor, categoryAnchor + ',' + KOISHI_CATEGORY)
+  } else {
+    console.warn('[kkk] ' + name + '：没找到「QQ 适配器」分类入口，跳过 Koishi 分类')
+    return text
+  }
+  // 分发 switch：插在 QQ 的 case 之后
+  if (out.includes(SWITCH)) out = out.replace(SWITCH, SWITCH + KOISHI_SWITCH)
+  // 组件定义：和 QQ 组件一样塞在 PR 前面
+  if (out.includes(COMPONENT_ANCHOR)) out = out.replace(COMPONENT_ANCHOR, ',' + KOISHI_START + koishiComponentCode + KOISHI_END + COMPONENT_ANCHOR)
+  console.log('[kkk] 「Koishi 设置」分类已注入: ' + name)
+  return out
+}
+
 /** 去掉上次插入的组件（按标记切掉） */
 function stripComponent (text) {
   let out = text
@@ -802,6 +869,9 @@ for (const file of files) {
 
     // 3. 组件定义（塞在 PR 前面，同一个模块作用域，能用 U / Q 这些打包期变量）
     if (text.includes(COMPONENT_ANCHOR)) text = text.replace(COMPONENT_ANCHOR, ',' + START + componentCode + END + COMPONENT_ANCHOR)
+
+    // 4. 「Koishi 设置」分类（必须在 QQ 分类注入之后：它锚定的是 QQ 那一块）
+    text = patchKoishiCategory(text, name)
   }
 
   if (/DesktopLayout|MobileLayout/.test(name)) {

package/scripts/smoke-console-hidden.cjs

@@ -0,0 +1,70 @@
+/**
+ * 控制台（Koishi 插件配置页）可见性冒烟测试。
+ *
+ * 需求：**kkk 的配置界面里所有设置项都要隐藏**，只留一段「请到 WebUI 面板改」的说明。
+ * 理由：同一份配置在控制台改一半、在面板改一半，两边都会把整份配置写回 koishi.yml，
+ * 很容易互相覆盖（用户实际遇到过「面板里关了、控制台一保存又回来了」）。
+ *
+ * 隐藏用的是 Koishi 自带的 `Schema.*.hidden()`（控制台客户端认 `meta.hidden`：
+ * 不渲染、但字段仍在 schema 里，所以控制台保存不会把值弄丢）。
+ *
+ * 用法：node scripts/smoke-console-hidden.cjs
+ */
+const path = require('node:path')
+
+const pluginRoot = path.resolve(__dirname, '..')
+const libRoot = path.join(pluginRoot, 'lib')
+
+const runtime = require(path.join(libRoot, 'compat', 'runtime.js'))
+const noop = () => {}
+runtime.bindRuntime({
+  ctx: { get: () => undefined, logger: () => ({ info: noop, warn: noop, error: noop, debug: noop, mark: noop }), bots: [], registry: new Map() },
+  config: { app: {} },
+  dataRoot: path.join(pluginRoot, 'data-smoke-console'),
+  master: () => []
+})
+
+const { Config } = require(path.join(libRoot, 'index.js'))
+
+const results = []
+const check = (name, ok, detail) => {
+  results.push({ name, ok })
+  console.log((ok ? '  ✅ ' : '  ❌ ') + name + (detail ? '  —— ' + detail : ''))
+}
+
+/** 找出所有「可见」的叶子字段路径（hidden 的整棵子树都跳过） */
+const visibleLeaves = (node, prefix = '') => {
+  if (!node || node.meta?.hidden) return []
+  const out = []
+  if (node.type === 'object') {
+    for (const [key, child] of Object.entries(node.dict ?? {})) out.push(...visibleLeaves(child, prefix ? prefix + '.' + key : key))
+  } else if (node.type === 'intersect' || node.type === 'union' || node.type === 'tuple') {
+    for (const child of node.list ?? []) out.push(...visibleLeaves(child, prefix))
+  } else {
+    out.push(prefix || '(root)')
+  }
+  return out
+}
+
+const visible = visibleLeaves(Config)
+
+console.log('\n[1] 控制台里只剩一段指路文字')
+check('可见字段只有 webuiGuide', visible.length === 1 && visible[0] === 'webuiGuide', visible.join(', ') || '（没有任何可见字段）')
+
+console.log('\n[2] 那几组设置都还在 schema 里（隐藏 ≠ 删除，保存不会丢值）')
+const hiddenGroups = ['qq', 'advanced', 'forward', 'upstream']
+const branches = Config.type === 'intersect' ? Config.list : [Config]
+const dict = Object.assign({}, ...branches.map((branch) => branch.dict ?? {}))
+for (const key of hiddenGroups) {
+  check('隐藏组仍然声明着：' + key, !!dict[key] && dict[key].meta?.hidden === true, dict[key] ? ('hidden=' + String(dict[key].meta?.hidden)) : '字段不存在')
+}
+
+console.log('\n[3] 指路文字写的是 WebUI 面板')
+const guide = dict.webuiGuide
+check('webuiGuide 可见', !!guide && guide.meta?.hidden !== true)
+check('说明里提到 /kkk 面板', /\/kkk/.test(guide?.meta?.description ?? ''), String(guide?.meta?.description ?? '').slice(0, 40) + '…')
+check('说明里写了「隐藏」这件事', /隐藏/.test(guide?.meta?.description ?? ''))
+
+const failed = results.filter((item) => !item.ok)
+console.log('\n=== ' + (results.length - failed.length) + '/' + results.length + ' 通过 ===')
+process.exitCode = failed.length ? 1 : 0

package/scripts/smoke-imports.cjs

@@ -0,0 +1,93 @@
+/**
+ * 「用了没 import」检查（针对平台处理器里的在线播放器接口）。
+ *
+ * 背景：线上真实故障 —— `kuaishou.ts` / `xiaohongshu.ts` 里调了
+ * `applyForceOnlinePlayer(this.e)`，但这两个文件**从来没 import 过它**，
+ * 一发快手 / 小红书链接就是：
+ *
+ *     ReferenceError: applyForceOnlinePlayer is not defined
+ *
+ * 构建当时没拦住（用了未声明的名字，TypeScript 那条链路只做了转译）。
+ *
+ * 这里做的是**针对性**检查而不是通用 lint：把 `src/player` 导出的名字都收集起来，
+ * 再看平台处理器里有没有「调用了却没 import」的。通用 lint 在这个仓库里噪声太大
+ * （对象字面量、JSX 组件、同名局部函数都会误报），针对性检查零误报、直接锁住这个坑。
+ *
+ * 用法：node scripts/smoke-imports.cjs
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+
+const pluginRoot = path.resolve(__dirname, '..')
+const srcRoot = path.join(pluginRoot, 'src')
+
+const stripComments = (text) => text
+  .replace(/\/\*[\s\S]*?\*\//g, ' ')
+  .replace(/(^|[^:])\/\/[^\n]*/g, '$1 ')
+
+const walk = (dir, filter) => {
+  const out = []
+  for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, item.name)
+    if (item.isDirectory()) out.push(...walk(full, filter))
+    else if (filter(full)) out.push(full)
+  }
+  return out
+}
+
+/** src/player 导出的函数名 */
+const playerFile = path.join(srcRoot, 'player', 'index.ts')
+const playerText = fs.readFileSync(playerFile, 'utf8')
+const playerExports = new Set()
+for (const match of playerText.matchAll(/export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g)) playerExports.add(match[1])
+for (const match of playerText.matchAll(/export\s+const\s+([A-Za-z_$][\w$]*)/g)) playerExports.add(match[1])
+
+/** 这个文件有没有从 player 模块 import 这个名字 */
+const importsFromPlayer = (text, name) => {
+  // 注意用 [^{}]* 而不是 [\s\S]*?：后者会把前面好几条 import 一起吞进来，名字表就废了
+  // 也兼容 `import karin, { a, b } from '...'` 这种默认 + 具名混写
+  for (const match of text.matchAll(/import\s*(?:[A-Za-z_$][\w$]*\s*,)?\s*(?:type\s*)?\{([^{}]*)\}\s*from\s*'([^']*player[^']*)'/g)) {
+    const names = match[1].split(',').map((item) => item.trim().split(/\s+as\s+/).pop().trim())
+    if (names.includes(name)) return true
+  }
+  return false
+}
+
+const targets = walk(path.join(srcRoot, 'karin'), (file) => file.endsWith('.ts'))
+const problems = []
+let checked = 0
+for (const file of targets) {
+  const text = stripComments(fs.readFileSync(file, 'utf8'))
+  for (const name of playerExports) {
+    const used = new RegExp('(?<![\\w$.])' + name + '\\s*\\(').test(text)
+    if (!used) continue
+    checked++
+    if (importsFromPlayer(text, name)) continue
+    // 本文件自己定义了同名函数（重新导出等）就不算漏
+    if (new RegExp('function\\s+' + name + '\\s*\\(').test(text)) continue
+    problems.push({ file: path.relative(srcRoot, file), name })
+  }
+}
+
+console.log('检查了 ' + targets.length + ' 个源文件，player 导出 ' + playerExports.size + ' 个名字，命中调用 ' + checked + ' 处')
+
+// 自检：这个检查本身得真的能抓到（拿线上那次的形状验一下）
+const fakeBad = "export const x = async () => { applyForceOnlinePlayer(this.e) }"
+const fakeGood = "import { applyForceOnlinePlayer } from '../../../player'\nexport const x = async () => { applyForceOnlinePlayer(this.e) }"
+const selfCheck = [{
+  name: '自检：漏 import 的写法必须判为问题',
+  ok: !importsFromPlayer(fakeBad, 'applyForceOnlinePlayer')
+}, {
+  name: '自检：正常 import 的写法必须放行',
+  ok: importsFromPlayer(fakeGood, 'applyForceOnlinePlayer')
+}]
+for (const item of selfCheck) console.log((item.ok ? '  ✅ ' : '  ❌ ') + item.name)
+
+const failed = problems.length > 0 || selfCheck.some((item) => !item.ok)
+if (problems.length === 0) {
+  console.log('\n=== 通过：平台处理器里没有「调用了却没 import」的在线播放器接口 ===')
+} else {
+  for (const item of problems) console.log('  ❌ ' + item.file + ' 调用了 ' + item.name + ' 但没 import')
+  console.log('\n=== 失败：' + problems.length + ' 处 ===')
+}
+process.exitCode = failed ? 1 : 0