koishi-plugin-kkk 1.0.0

package/lib/compat/node-karin.js

@@ -0,0 +1,1053 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncUpstreamToKoishi = exports.segment = exports.logger = exports.karin = exports.app = exports.isFfmpegAvailable = exports.ffprobe = exports.ffmpeg = exports.createServerErrorResponse = exports.createNotFoundResponse = exports.createBadRequestResponse = exports.createSuccessResponse = exports.authMiddleware = exports.defineConfig = exports.checkPort = exports.isDocker = exports.mkdirSync = exports.updatePkg = exports.checkPkgUpdate = exports.restart = exports.watch = exports.hooks = exports.config = exports.common = exports.render = exports.db = exports.contactFriend = exports.contactGroup = exports.ForwardPayload = exports.Message = exports.KkkBot = exports.NEXT = exports.BOT_READY = exports.BOT_DISCONNECT = exports.BOT_CONNECT = exports.getKoishiContext = void 0;
+exports.makeForward = makeForward;
+exports.logs = logs;
+exports.parseChangelog = parseChangelog;
+exports.range = range;
+/**
+ * `node-karin` 的 Koishi 兼容实现（迁移核心）。
+ *
+ * 目标：让 packages/core/src 里的业务代码几乎原样运行 —— 只把框架 API 换成 Koishi 的实现。
+ * 覆盖范围按原插件的真实调用面收敛：
+ *   karin.command / task / getBot / getAllBot(ID|List) / contactGroup / sendMsg / sendMaster / on / ctx
+ *   logger（见 ./logger）、segment（见 ./segment）、common.makeForward、config.master、db(KV)、render、sqlite3、root
+ */
+const node_child_process_1 = require("node:child_process");
+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");
+const logger_1 = require("./logger");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
+const runtime_1 = require("./runtime");
+const segment_1 = require("./segment");
+Object.defineProperty(exports, "segment", { enumerable: true, get: function () { return segment_1.segment; } });
+const syncConfig_1 = require("./syncConfig");
+Object.defineProperty(exports, "syncUpstreamToKoishi", { enumerable: true, get: function () { return syncConfig_1.syncUpstreamToKoishi; } });
+const text_1 = require("./text");
+/** 取当前 Koishi 上下文（移植代码访问 Koishi 服务用） */
+const getKoishiContext = () => (0, runtime_1.getRuntime)().ctx;
+exports.getKoishiContext = getKoishiContext;
+exports.BOT_CONNECT = 'bot-connect';
+exports.BOT_DISCONNECT = 'bot-disconnect';
+exports.BOT_READY = 'bot-ready';
+/** 命令处理器调用 next() 时返回的哨兵，表示继续走后续中间件 */
+exports.NEXT = Symbol('kkk.next');
+/* ------------------------------------------------------------------ *
+ * Bot 适配
+ * ------------------------------------------------------------------ */
+const MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.mp4': 'video/mp4',
+    '.mp3': 'audio/mpeg',
+    '.amr': 'audio/amr',
+    '.silk': 'audio/silk',
+    '.bin': 'application/octet-stream'
+};
+function guessMime(filePath) {
+    const ext = node_path_1.default.extname(filePath).toLowerCase();
+    return MIME_BY_EXT[ext] ?? 'application/octet-stream';
+}
+/** 仿 karin 的 AdapterType（机器人实例） */
+class KkkBot {
+    bot;
+    constructor(bot) {
+        this.bot = bot;
+    }
+    get selfId() {
+        return this.bot.selfId;
+    }
+    get account() {
+        return {
+            selfId: this.bot.selfId,
+            uid: this.bot.user?.id ?? this.bot.selfId,
+            uin: this.bot.selfId,
+            name: this.bot.user?.name ?? this.bot.selfId,
+            avatar: this.bot.user?.avatar
+        };
+    }
+    get adapter() {
+        const platform = String(this.bot.platform ?? '');
+        const raw = this.bot.adapter || {};
+        const cfg = raw.config ?? {};
+        return {
+            name: platform,
+            protocol: platform,
+            standard: platform,
+            // 错误卡片模板还会读这三项，之前没给 → 卡片上显示 undefined 和一个空的「v」
+            platform: String(raw.platform ?? cfg.platform ?? (platform || '未知')),
+            communication: String(raw.communication ?? cfg.communication ?? cfg.protocol ?? '未知'),
+            version: String(raw.version ?? cfg.version ?? ''),
+            raw: this.bot.adapter
+        };
+    }
+    get ctx() {
+        return this.bot.ctx;
+    }
+    /** 好友列表 */
+    /**
+     * 好友列表。
+     *
+     * Koishi 的 Bot 没有统一的 getFriendList，拿不到就返回空数组 ——
+     * 上游用它来「找能给主人发消息的 bot」，空数组会自然走到后面的兜底逻辑（getAllBotID），
+     * 所以这里**不能抛错**，否则整条推送链路会断在第一步。
+     */
+    async getFriendList() {
+        try {
+            return await this.bot.getFriendList();
+        }
+        catch (error) {
+            logger_1.logger.debug('getFriendList 失败: ' + String(error));
+            return [];
+        }
+    }
+    /** 群信息，karin 侧字段为 groupName */
+    async getGroupInfo(groupId) {
+        try {
+            const guild = await this.bot.getGuild(groupId);
+            return { ...guild, groupId, groupName: guild?.name ?? '' };
+        }
+        catch (error) {
+            logger_1.logger.debug('getGroupInfo 失败: ' + String(error));
+            return undefined;
+        }
+    }
+    async getGroupAvatarUrl(groupId) {
+        try {
+            return await this.bot.getGroupAvatarUrl?.(groupId) ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    async getAvatarUrl(userId) {
+        try {
+            return await this.bot.getAvatarUrl?.(userId) ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * 合并转发。
+     *
+     * 上游是把内容装进「合并转发」发出去；但**部分适配器根本没有合并转发能力**
+     * （例如 QQ 官方适配器 koishi-plugin-adapter-qq-crack，platform=\`qqguild\`，
+     * 整个包里没有一处 forward），硬发 \`<message>\` 元素只会失败或变成一条空消息。
+     * 所以这里先问适配器支不支持，不支持就**退化成直接发送这些元素**（视觉上是普通消息）。
+     */
+    async sendForwardMsg(contact, elements, _options) {
+        const channelId = typeof contact === 'string' ? contact : contact.peer;
+        const payload = elements instanceof ForwardPayload ? elements : new ForwardPayload(normalizeContent(elements));
+        if (supportsForward(this.bot)) {
+            try {
+                const ids = await this.bot.sendMessage(channelId, [(0, koishi_1.h)('message', ...payload.elements)]);
+                return { messageId: ids[ids.length - 1] ?? '' };
+            }
+            catch (error) {
+                logger_1.logger.warn('合并转发发送失败，改为直接发送内容: ' + String(error?.message ?? error));
+            }
+        }
+        else {
+            logger_1.logger.debug('当前适配器（' + this.bot.platform + '）不支持合并转发，改为直接发送内容');
+        }
+        // 退化路径：整条发一次；失败再逐个元素发，尽量把内容送出去
+        try {
+            const ids = await this.bot.sendMessage(channelId, payload.elements);
+            return { messageId: ids[ids.length - 1] ?? '' };
+        }
+        catch (error) {
+            logger_1.logger.warn('整条发送失败，改为逐个元素发送: ' + String(error?.message ?? error));
+            let lastId = '';
+            for (const item of payload.elements) {
+                const ids = await this.bot.sendMessage(channelId, [item]);
+                lastId = ids[ids.length - 1] ?? lastId;
+            }
+            return { messageId: lastId };
+        }
+    }
+    /**
+     * 上传群文件。
+     *
+     * 上游会把「文件」写成各种形式：本地路径、`file://`、`base64://xxx`（Base.ts 生成视频文件时就是这种）。
+     * 之前这里只认路径，base64 串会直接抛「上传文件不存在」或者被当成 URL 交给适配器去 fetch
+     * （日志表现：`QQ 消息发送失败 fetch base64://AAAAHGZ0eXBpc29t…`）。
+     * 现在统一交给 `segment.file` 处理：它能吃路径 / file:// / base64:// / Buffer。
+     */
+    async uploadFile(contact, file, name) {
+        const channelId = typeof contact === 'string' ? contact : contact.peer;
+        let element;
+        if (Buffer.isBuffer(file)) {
+            element = segment_1.segment.file(file, name);
+        }
+        else if (typeof file === 'string' && (file.startsWith('base64://') || file.startsWith('data:'))) {
+            element = segment_1.segment.file(file, name);
+        }
+        else {
+            const filePath = String(file).startsWith('file://') ? String(file).slice('file://'.length) : String(file);
+            if (!node_fs_1.default.existsSync(filePath))
+                throw new Error('上传文件不存在: ' + filePath);
+            element = segment_1.segment.file(node_fs_1.default.readFileSync(filePath), name ?? node_path_1.default.basename(filePath));
+        }
+        return this.bot.sendMessage(channelId, [element]);
+    }
+    /** 群成员信息，karin 侧字段：userId/nick/card/role */
+    async getGroupMemberInfo(groupId, userId) {
+        const bot = this.bot;
+        try {
+            const member = await bot.getGuildMember?.(groupId, userId);
+            if (!member)
+                return undefined;
+            return { ...member, userId: member.user?.id ?? userId, nick: member.user?.name ?? member.nick ?? '', card: member.nick ?? '' };
+        }
+        catch (error) {
+            logger_1.logger.debug('getGroupMemberInfo 失败: ' + String(error));
+            return undefined;
+        }
+    }
+    /** 群列表，karin 侧字段：group_id/group_name */
+    async getGroupList() {
+        const bot = this.bot;
+        try {
+            const list = await bot.getGuildList?.();
+            return (list ?? []).map((item) => ({ ...item, group_id: item.id, group_name: item.name }));
+        }
+        catch (error) {
+            logger_1.logger.debug('getGroupList 失败: ' + String(error));
+            return [];
+        }
+    }
+    /** 取消息（karin 的 bot.getMsg），结果按 karin 的 elements 形状返回 */
+    async getMsg(contact, messageId) {
+        const channelId = typeof contact === 'string' ? contact : contact.peer;
+        try {
+            const message = await this.bot.getMessage(channelId, messageId);
+            if (!message)
+                return { message_id: messageId, elements: [], raw_message: '' };
+            const elements = (message.elements ?? []).map((el) => {
+                switch (el.type) {
+                    case 'text': return { type: 'text', text: el.attrs?.content ?? '' };
+                    case 'image': return { type: 'image', file: el.attrs?.src ?? '' };
+                    case 'at': return { type: 'at', qq: el.attrs?.id ?? '' };
+                    case 'quote': return { type: 'reply', id: el.attrs?.id ?? '' };
+                    default: return { type: el.type, data: JSON.stringify(el.attrs ?? {}) };
+                }
+            });
+            return { message_id: message.id ?? messageId, raw_message: message.content ?? '', elements };
+        }
+        catch (error) {
+            logger_1.logger.debug('getMsg 失败: ' + String(error));
+            return { message_id: messageId, elements: [], raw_message: '' };
+        }
+    }
+    /** 发送消息（karin 的 bot.sendMsg） */
+    async sendMsg(contact, content, _options) {
+        const channelId = typeof contact === 'string' ? contact : contact.peer;
+        const ids = await this.bot.sendMessage(channelId, normalizeContent(content));
+        return { messageId: ids[ids.length - 1] ?? '' };
+    }
+    /**
+     * 消息表情回应（karin 的 bot.setMsgReaction）。
+     * Satori 机器人没有统一接口，能调则调，不能调就静默返回 false —— 原插件只用它做「处理中/成功」提示。
+     */
+    async setMsgReaction(_contact, messageId, emojiId, isAdd = true) {
+        const bot = this.bot;
+        const fn = bot.setMessageReaction ?? bot.setMsgReaction;
+        if (typeof fn !== 'function')
+            return false;
+        try {
+            await fn.call(bot, messageId, String(emojiId), isAdd);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 撤回消息。
+     *
+     * 必须带上频道号：QQ 适配器的 `deleteMessage(channelId, messageId)` 会在内部对
+     * channelId 调 `.startsWith`，传 undefined 直接抛
+     * `TypeError: Cannot read properties of undefined (reading 'startsWith')`（撤回全部失败）。
+     * @param messageId 要撤回的消息 id
+     * @param channelId 频道/群 id（karin 侧调用一般不带，这时用最近一次事件的频道）
+     */
+    async recallMsg(messageId, channelId) {
+        try {
+            const channel = channelId || this.lastChannelId || '';
+            return await this.bot.deleteMessage(channel, messageId);
+        }
+        catch (error) {
+            logger_1.logger.debug('recallMsg 失败: ' + String(error));
+            return undefined;
+        }
+    }
+}
+exports.KkkBot = KkkBot;
+/* ------------------------------------------------------------------ *
+ * Message 适配
+ * ------------------------------------------------------------------ */
+/** 仿 karin 的 Message（事件对象） */
+class Message {
+    /** 消息文本（原插件会直接改写这个字段） */
+    msg;
+    selfId;
+    userId;
+    groupId;
+    isGroup;
+    sender;
+    contact;
+    bot;
+    messageId;
+    /** 引用的消息 ID（karin 的 e.replyId） */
+    replyId;
+    session;
+    /** 原始 satori 事件载荷 */
+    raw;
+    constructor(init) {
+        this.msg = init.msg ?? '';
+        this.selfId = init.selfId ?? '';
+        this.userId = init.userId ?? '';
+        this.groupId = init.groupId ?? '';
+        this.isGroup = init.isGroup ?? false;
+        this.sender = init.sender ?? { userId: this.userId, nick: '' };
+        this.contact = init.contact ?? { peer: this.groupId || ('private:' + this.userId), isGroup: this.isGroup };
+        this.bot = init.bot instanceof KkkBot ? init.bot : new KkkBot(init.bot);
+        this.messageId = init.messageId ?? '';
+        this.replyId = init.replyId ?? '';
+        this.session = init.session;
+        this.raw = init.raw;
+    }
+    /**
+     * 由 Koishi 会话构造。
+     * @param session Koishi 会话
+     * @param msg 已经归一化过的消息文本（QQ 卡片链路会在匹配前先做异步还原，见 karin/module/utils/QqCardResolve.ts）；
+     *            不传时退回同步归一化（还原 JSON 转义 + 提取已有链接）
+     */
+    static fromSession(session, msg) {
+        const isGroup = !!session.guildId;
+        const userId = session.userId ?? '';
+        return new Message({
+            // QQ 分享卡片在适配器里是「带 JSON 转义的一整段文本」，这里还原转义并补上挖出来的链接，
+            // 否则各平台的链接正则匹配不到（详见 compat/text.ts）
+            msg: msg ?? (0, text_1.normalizeMessageText)(session.content ?? ''),
+            selfId: session.selfId,
+            userId,
+            groupId: session.guildId ?? session.channelId ?? '',
+            isGroup,
+            sender: { userId, nick: session.author?.nick ?? session.username ?? '' },
+            contact: {
+                peer: session.channelId ?? (isGroup ? session.guildId : 'private:' + userId),
+                guildId: session.guildId ?? undefined,
+                userId,
+                isGroup
+            },
+            bot: session.bot,
+            messageId: session.messageId ?? '',
+            replyId: session.quote?.id ?? session.event?.message?.quote?.id ?? '',
+            session,
+            raw: session.event
+        });
+    }
+    /**
+     * 回复消息。
+     *
+     * **被动回复兜底**：QQ 官方 bot 的「被动回复」有硬限制（一条消息只能回几次、还有时间窗），
+     * 而弹幕烧录这种操作动辄几分钟 —— 回来再 reply 就会撞
+     * `[40034128] 回复消息失败，被动回复时间或者次数超过限制`，视频明明下好了却发不出去。
+     * 这时自动改用**主动消息**（不带引用，直接往频道里发），失败才把原错误抛出去。
+     */
+    async reply(content, _options) {
+        const elements = normalizeContent(content);
+        /**
+         * 主动消息兜底（重点）。
+         *
+         * QQ 适配器在「被动回复超限」时**不一定抛异常**：它只是发不出去、返回空数组，
+         * 于是 await send() 看起来是成功的 —— 视频就静默丢了。所以这里除了 catch，
+         * 还要看**有没有拿到消息 ID**：没拿到就换主动消息（不带引用）重发一次。
+         */
+        const sendActive = async () => {
+            const activeIds = await this.bot.bot.sendMessage(this.contact.peer, elements);
+            return { messageId: activeIds?.[activeIds.length - 1] ?? '' };
+        };
+        try {
+            if (this.session) {
+                const ids = await this.session.send(elements);
+                const id = ids?.[ids.length - 1] ?? '';
+                if (!id) {
+                    logger_1.logger.mark('[compat] 回复没有返回消息 ID（多为被动回复超限），改用主动消息重发');
+                    return await sendActive();
+                }
+                return { messageId: id };
+            }
+            const ids = await this.bot.bot.sendMessage(this.contact.peer, elements);
+            return { messageId: ids?.[ids.length - 1] ?? '' };
+        }
+        catch (error) {
+            const text = String(error?.message ?? error);
+            // 被动回复额度/时间窗超了：换成主动消息再试一次
+            if (!/被动回复|40034128|timeout|次数超过/.test(text))
+                throw error;
+            // 用 mark 级别：这是「视频明明下好了却发不出去」的关键兜底，日志里要看得见
+            logger_1.logger.mark('[compat] 被动回复受限，改用主动消息发送: ' + text);
+            return await sendActive();
+        }
+    }
+    /** karin 的 e.bot 直接就是发送者 */
+    async sendMsg(content) {
+        return this.reply(content);
+    }
+}
+exports.Message = Message;
+function normalizeContent(content) {
+    if (content === undefined || content === null)
+        return [];
+    return Array.isArray(content) ? content : [content];
+}
+/**
+ * 合并转发的载荷。
+ *
+ * 上游 \`common.makeForward(elements, botId, botName)\` 的返回值只被 \`bot.sendForwardMsg()\` 消费，
+ * 所以这里用一个带类型的对象承载「哪些元素要转发」，由 sendForwardMsg 决定真转发还是退化成直发。
+ */
+class ForwardPayload {
+    elements;
+    botId;
+    botName;
+    constructor(elements, botId, botName) {
+        this.elements = elements;
+        this.botId = botId;
+        this.botName = botName;
+    }
+}
+exports.ForwardPayload = ForwardPayload;
+/** karin 的 common.makeForward */
+function makeForward(elements, botId, botName) {
+    return new ForwardPayload(normalizeContent(elements), botId, botName);
+}
+/**
+ * 适配器是否支持「合并转发」。
+ *
+ * OneBot 系（platform 为 onebot / red / chronocat…）支持 Satori 的 \`<message>\` 元素；
+ * QQ 官方 API（qqguild / qq / qqbot）没有这个能力，必须退化。
+ */
+function supportsForward(bot) {
+    const platform = String(bot?.platform ?? '');
+    if (!platform)
+        return false;
+    return !/qqguild|qqbot|^qq$|official/i.test(platform);
+}
+/* ------------------------------------------------------------------ *
+ * karin 门面
+ * ------------------------------------------------------------------ */
+let commandOrder = 0;
+const contactGroup = (groupId) => ({ peer: groupId, guildId: groupId, isGroup: true });
+exports.contactGroup = contactGroup;
+const contactFriend = (userId) => ({ peer: 'private:' + userId, userId, isGroup: false });
+exports.contactFriend = contactFriend;
+function resolveBot(selfId) {
+    const runtime = (0, runtime_1.tryGetRuntime)();
+    if (!runtime)
+        return undefined;
+    const bots = runtime.ctx.bots;
+    if (!bots?.length)
+        return undefined;
+    const matched = selfId ? bots.find((bot) => bot.selfId === selfId || bot.user?.id === selfId) : undefined;
+    return new KkkBot(matched ?? bots[0]);
+}
+function command(reg, handler, options) {
+    const registration = { reg, handler, options, order: commandOrder++ };
+    runtime_1.commandQueue.push(registration);
+    return registration;
+}
+function task(name, cron, handler, options) {
+    const registration = { name, cron, handler, options };
+    runtime_1.taskQueue.push(registration);
+    return registration;
+}
+function on(event, handler) {
+    runtime_1.eventQueue.push({ event, handler });
+    return () => {
+        const index = runtime_1.eventQueue.findIndex((item) => item.handler === handler);
+        if (index >= 0)
+            runtime_1.eventQueue.splice(index, 1);
+    };
+}
+async function sendMsg(selfId, contact, content, _options) {
+    const bot = resolveBot(selfId);
+    if (!bot)
+        throw new Error('[kkk] 没有可用的机器人实例，无法发送消息');
+    const channelId = typeof contact === 'string' ? contact : contact.peer;
+    const ids = await bot.bot.sendMessage(channelId, normalizeContent(content));
+    return { messageId: ids[ids.length - 1] ?? '', rawData: ids };
+}
+async function sendMaster(botId, master, content, _options) {
+    const bot = resolveBot(botId);
+    if (!bot)
+        throw new Error('[kkk] 没有可用的机器人实例，无法发送消息');
+    const elements = normalizeContent(content);
+    const target = bot.bot;
+    // Satori 的 Bot 有 sendPrivateMessage；个别适配器没有，退化成私聊频道 id
+    const ids = typeof target.sendPrivateMessage === 'function'
+        ? await target.sendPrivateMessage(master, elements)
+        : await target.sendMessage('private:' + master, elements);
+    return { messageId: ids?.[ids.length - 1] ?? '', rawData: ids };
+}
+/**
+ * 等待同一会话中的下一条消息（karin 的 karin.ctx）。
+ */
+function waitContext(event, options = {}) {
+    const runtime = (0, runtime_1.getRuntime)();
+    const timeout = options.time ?? 60 * 1000;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const dispose = runtime.ctx.on('message', (session) => {
+            if (settled)
+                return;
+            if (session.channelId !== event.contact.peer)
+                return;
+            if (event.userId && session.userId !== event.userId)
+                return;
+            settled = true;
+            dispose();
+            clearTimeout(timer);
+            resolve(Message.fromSession(session));
+        });
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            dispose();
+            if (options.throwOnTimeout)
+                reject(new Error('等待用户输入超时'));
+            else
+                resolve(undefined);
+        }, timeout);
+    });
+}
+/* ------------------------------------------------------------------ *
+ * KV 存储（karin 的 db.get/set/del）
+ * ------------------------------------------------------------------ */
+const kvCache = new Map();
+let kvLoaded = false;
+function kvFile() {
+    return node_path_1.default.resolve((0, runtime_1.getRuntime)().dataRoot, 'koishi-plugin-kkk', 'data', 'kv.json');
+}
+function loadKv() {
+    if (kvLoaded)
+        return;
+    kvLoaded = true;
+    try {
+        const file = kvFile();
+        if (node_fs_1.default.existsSync(file)) {
+            const data = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+            for (const [key, value] of Object.entries(data))
+                kvCache.set(key, value);
+        }
+    }
+    catch (error) {
+        logger_1.logger.warn('读取 KV 存储失败: ' + String(error));
+    }
+}
+function saveKv() {
+    try {
+        const file = kvFile();
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+        node_fs_1.default.writeFileSync(file, JSON.stringify(Object.fromEntries(kvCache), null, 2));
+    }
+    catch (error) {
+        logger_1.logger.warn('写入 KV 存储失败: ' + String(error));
+    }
+}
+exports.db = {
+    async get(key) {
+        loadKv();
+        return kvCache.get(key);
+    },
+    async set(key, value) {
+        loadKv();
+        kvCache.set(key, value);
+        saveKv();
+    },
+    async del(key) {
+        loadKv();
+        kvCache.delete(key);
+        saveKv();
+    },
+    async all() {
+        loadKv();
+        return Object.fromEntries(kvCache);
+    },
+    async clear() {
+        kvCache.clear();
+        saveKv();
+    }
+};
+/* ------------------------------------------------------------------ *
+ * render / app / 其它零散 API
+ * ------------------------------------------------------------------ */
+exports.render = {
+    /**
+     * karin 的 render.render：给 HTML 文件截图。
+     * 这里走 koishi-plugin-puppeteer（可选依赖）。
+     */
+    async render(options) {
+        const runtime = (0, runtime_1.getRuntime)();
+        const puppeteer = runtime.ctx.puppeteer;
+        if (!puppeteer)
+            throw new Error('[kkk] 渲染失败：未安装 koishi-plugin-puppeteer');
+        const screenshotOptions = {
+            file: options.file,
+            selector: options.selector ?? '#container',
+            fullPage: options.fullPage ?? false,
+            omitBackground: options.omitBackground ?? true,
+            type: options.type ?? 'png',
+            pageGotoParams: options.pageGotoParams
+        };
+        /**
+         * 自己开页面对 HTML 文件截图。
+         *
+         * 不能走 `puppeteer.render(html, options)` —— 那个 API 的第二个参数是**回调函数**，
+         * 传截图配置进去会直接报 `callback is not a function`
+         * （抖音弹幕条渲染就是这么挂的，日志里一堆「弹幕条渲染失败，将按纯文字处理」）。
+         */
+        const target = options.selector ?? '#container';
+        const newPage = async () => {
+            if (typeof puppeteer.page === 'function')
+                return await puppeteer.page();
+            if (puppeteer.browser && typeof puppeteer.browser.newPage === 'function')
+                return await puppeteer.browser.newPage();
+            return null;
+        };
+        const page = await newPage();
+        if (!page)
+            throw new Error('[kkk] 渲染失败：puppeteer 服务没有可用的页面');
+        try {
+            if (page.setViewport)
+                await page.setViewport({ width: 1200, height: 900, deviceScaleFactor: 2 });
+            await page.goto((0, node_url_1.pathToFileURL)(options.file).href, {
+                waitUntil: options.pageGotoParams?.waitUntil ?? 'load',
+                timeout: options.pageGotoParams?.timeout ?? 15000
+            });
+            const handle = (await page.$(target)) ?? (await page.$('body'));
+            const box = handle ? await handle.boundingBox() : null;
+            if (box && box.height > 900 && page.setViewport) {
+                await page.setViewport({ width: Math.ceil(box.width) + 4, height: Math.ceil(box.height) + 4, deviceScaleFactor: 2 });
+            }
+            const buffer = await page.screenshot({
+                clip: box ?? undefined,
+                omitBackground: options.omitBackground ?? true,
+                type: options.type ?? 'png'
+            });
+            return buffer.toString('base64');
+        }
+        finally {
+            try {
+                await page.close();
+            }
+            catch { /* 忽略 */ }
+        }
+        if (Buffer.isBuffer(result))
+            return result.toString('base64');
+        if (typeof result === 'string')
+            return result.replace(/^data:image\/\w+;base64,/, '');
+        if (result?.data)
+            return String(result.data).replace(/^data:image\/\w+;base64,/, '');
+        throw new Error('[kkk] 渲染失败：截图结果为空');
+    }
+};
+exports.common = {
+    makeForward,
+    async sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    },
+    get karinVersion() {
+        return exports.karin.version;
+    }
+};
+exports.config = {
+    /** 主人账号列表 */
+    master() {
+        return (0, runtime_1.getRuntime)().config.masters;
+    },
+    /** 读取任意目录下的配置文件（兼容占位） */
+    json(dir) {
+        const runtime = (0, runtime_1.getRuntime)();
+        const file = dir ? node_path_1.default.resolve(runtime.dataRoot, dir) : node_path_1.default.resolve(runtime.dataRoot, 'config.json');
+        try {
+            return JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+};
+/**
+ * karin 的 hooks 是内置插件（更新检测等）暴露的钩子集合。
+ * Koishi 侧没有对应实现，这里做成深度空实现：任何属性都是可调用的 no-op，
+ * 避免移植代码在 import 阶段直接崩掉。
+ */
+const noopProxy = new Proxy(function () { }, {
+    get: (_target, prop) => (prop === 'then' ? undefined : noopProxy),
+    apply: () => noopProxy
+});
+exports.hooks = new Proxy({}, {
+    get: (_target, prop) => (prop === 'on' || prop === 'once'
+        ? (event, handler) => on(event, handler)
+        : noopProxy)
+});
+const watch = (_paths, _options, _handler) => () => { };
+exports.watch = watch;
+const restart = async () => {
+    logger_1.logger.warn('[kkk] Koishi 环境下不支持插件重启，请手动重启进程');
+};
+exports.restart = restart;
+/**
+ * 检查 npm 上的最新版本（对应 karin 的 checkPkgUpdate）。
+ * 返回 karin 约定的三种形状：yes(有更新) / no(无更新) / error。
+ * 未发布到 npm 的包（例如本地开发时的 koishi-plugin-kkk）会走到 error 分支，调用方按「无更新」处理。
+ */
+const checkPkgUpdate = async (name, _options) => {
+    const local = readLocalVersion();
+    try {
+        const response = await fetch('https://registry.npmmirror.com/' + name, { signal: AbortSignal.timeout(10000) });
+        if (!response.ok)
+            return { status: 'error', error: new Error('HTTP ' + response.status) };
+        const meta = await response.json();
+        const remote = meta?.['dist-tags']?.latest;
+        if (!remote)
+            return { status: 'error', error: new Error('响应缺少 dist-tags.latest') };
+        if (remote === local)
+            return { status: 'no', local };
+        return { status: 'yes', local, remote };
+    }
+    catch (error) {
+        return { status: 'error', error: error };
+    }
+};
+exports.checkPkgUpdate = checkPkgUpdate;
+/** 读取插件自身 package.json 的版本号 */
+function readLocalVersion() {
+    try {
+        const file = node_path_1.default.resolve((0, runtime_1.getRuntime)().pluginRoot, 'package.json');
+        return JSON.parse(node_fs_1.default.readFileSync(file, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const updatePkg = async (_name) => {
+    logger_1.logger.warn('[kkk] Koishi 环境下请使用包管理器更新插件');
+    return false;
+};
+exports.updatePkg = updatePkg;
+exports.mkdirSync = node_fs_1.default.mkdirSync;
+const isDocker = () => false;
+exports.isDocker = isDocker;
+/**
+ * 提取 CHANGELOG 中指定数量的版本记录（karin 的 \`logs\`）。
+ * 上游用法：\`logs({ version, data, length })\` → 返回最近 \`length\` 个版本的 markdown 片段。
+ */
+function logs(options) {
+    const { data, length, version } = options ?? {};
+    if (typeof data !== 'string' || !data)
+        return '';
+    const versions = parseChangelog(data);
+    const keys = Object.keys(versions);
+    if (!keys.length)
+        return '';
+    let start = 0;
+    if (version) {
+        const index = keys.findIndex((key) => compareVersion(key, version) === 0);
+        if (index >= 0)
+            start = index;
+    }
+    const take = Math.max(1, Number(length) || 1);
+    return keys.slice(start, start + take).map((key) => '## [' + key + ']\n' + versions[key]).join('\n\n');
+}
+/** 版本号比较（仅用于 changelog 过滤，够用即可） */
+function compareVersion(a, b) {
+    const pa = String(a).replace(/^v/i, '').split('-')[0].split('.').map((item) => Number(item) || 0);
+    const pb = String(b).replace(/^v/i, '').split('-')[0].split('.').map((item) => Number(item) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    }
+    return 0;
+}
+/**
+ * 解析 CHANGELOG.md：\`{ '1.2.3': '该版本的正文' }\`（karin 的 parseChangelog）。
+ * 标题形如 \`## [1.2.3](...) (2024-01-01)\` 或 \`## 1.2.3\`。
+ */
+function parseChangelog(text) {
+    const result = {};
+    if (typeof text !== 'string' || !text)
+        return result;
+    const lines = text.split(/\r?\n/);
+    let current = null;
+    let buffer = [];
+    const flush = () => {
+        if (current)
+            result[current] = buffer.join('\n').trim();
+        buffer = [];
+    };
+    for (const line of lines) {
+        const matched = line.match(/^#{1,4}\s*\[?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\]?/);
+        if (matched) {
+            flush();
+            current = matched[1];
+            continue;
+        }
+        if (current)
+            buffer.push(line);
+    }
+    flush();
+    return result;
+}
+/**
+ * 按版本区间裁剪 changelog（karin 的 range）。
+ * 上游用法：\`range({ data, startVersion, endVersion, compare: 'semver' })\`，返回裁剪后的 markdown 文本。
+ * 区间语义：\`startVersion < v <= endVersion\`；解析不出任何版本时原样返回。
+ */
+function range(options) {
+    const { data, startVersion, endVersion } = options ?? {};
+    if (typeof data !== 'string')
+        return data;
+    const parsed = parseChangelog(data);
+    const versions = Object.keys(parsed);
+    if (!versions.length)
+        return data;
+    const selected = versions.filter((version) => {
+        if (startVersion && compareVersion(version, startVersion) <= 0)
+            return false;
+        if (endVersion && compareVersion(version, endVersion) > 0)
+            return false;
+        return true;
+    });
+    if (!selected.length)
+        return data;
+    return selected.map((version) => '## [' + version + ']\n' + parsed[version]).join('\n\n');
+}
+const checkPort = async (port) => port;
+exports.checkPort = checkPort;
+const defineConfig = (config) => config;
+exports.defineConfig = defineConfig;
+/**
+ * 控制台 API 的鉴权（替代 karin 的 WebUI 会话鉴权）。
+ *
+ * - 插件配置里设了 \`apiToken\`：要求 \`Authorization: Bearer <token>\`（或 \`?token=\`）；
+ * - 没设 token：只放行本机请求，避免把配置接口裸奔到公网。
+ */
+const authMiddleware = (req, res, next) => {
+    const expected = String((0, runtime_1.getRuntime)().config.apiToken ?? '');
+    const provided = String(req?.headers?.authorization ?? '').replace(/^Bearer\s+/i, '')
+        || String(req?.query?.token ?? '');
+    if (expected) {
+        if (provided === expected)
+            return next();
+        return respond(401, res, { code: 401, message: '未授权：apiToken 不正确' });
+    }
+    const address = String(req?.socket?.remoteAddress ?? req?.ip ?? '');
+    if (/^(::1|::ffff:127\.0\.0\.1|127\.0\.0\.1)$/.test(address))
+        return next();
+    return respond(401, res, { code: 401, message: '未授权：请在插件配置中设置 apiToken' });
+};
+exports.authMiddleware = authMiddleware;
+/**
+ * karin 的响应助手：**第一个参数是 express 的 res**，会直接把响应写出去。
+ * 例如 `createSuccessResponse(res, data, 'ok')` / `createBadRequestResponse(res, '参数错误')`。
+ * 移植过来的 controllers 就是这么用的，签名必须对齐（否则请求会一直挂着不返回）。
+ */
+const respond = (status, res, payload) => {
+    try {
+        if (res && typeof res.status === 'function' && typeof res.json === 'function') {
+            res.status(status).json(payload);
+        }
+        else if (res && typeof res.send === 'function') {
+            res.status?.(status).send?.(payload);
+        }
+    }
+    catch (error) {
+        logger_1.logger.debug('[kkk] 写响应失败: ' + String(error));
+    }
+    return payload;
+};
+const createSuccessResponse = (res, data, message = 'success') => respond(200, res, { code: 200, message, data });
+exports.createSuccessResponse = createSuccessResponse;
+const createBadRequestResponse = (res, message = '请求参数错误') => respond(400, res, { code: 400, message });
+exports.createBadRequestResponse = createBadRequestResponse;
+const createNotFoundResponse = (res, message = '资源不存在') => respond(404, res, { code: 404, message });
+exports.createNotFoundResponse = createNotFoundResponse;
+const createServerErrorResponse = (res, message = '服务器内部错误') => respond(500, res, { code: 500, message });
+exports.createServerErrorResponse = createServerErrorResponse;
+/* ------------------------------------------------------------------ *
+ * FFmpeg / ffprobe
+ *
+ * 上游 karin 直接调它的 ffmpeg 封装；Koishi 兼容层原先是个**抛错的占位实现**，
+ * 结果所有要拼流/改封装的解析（登录态 B站 视频要先把 m4s 修成 mp4 再和音频合成）
+ * 都在第一步就炸/哑掉 —— 用户看到的就是「提示开始解析，然后没下文」。
+ *
+ * 这里给它一个真实现：子进程直接跑 ffmpeg / ffprobe，返回值形状保持 karin 的
+ * `{ status, stdout, stderr }`（`status` 为真表示成功，kkk 里到处这么判断）。
+ * 可执行文件来源优先级：karin 传入的 options.ffmpegPath → koishi-plugin-ffmpeg-path 服务
+ * → 环境变量 FFMPEG_PATH/FFPROBE_PATH → PATH 里的 ffmpeg/ffprobe。
+ * ------------------------------------------------------------------ */
+function ffmpegRuntimeCtx() {
+    try {
+        return (0, runtime_1.tryGetRuntime)()?.ctx;
+    }
+    catch {
+        return null;
+    }
+}
+/** 由 ffmpeg 路径推出同目录的 ffprobe（找不到就交给 PATH） */
+function siblingFfprobe(ffmpegPath) {
+    try {
+        if (!ffmpegPath || ffmpegPath === 'ffmpeg')
+            return 'ffprobe';
+        const dir = node_path_1.default.dirname(ffmpegPath);
+        const name = process.platform === 'win32' ? 'ffprobe.exe' : 'ffprobe';
+        const candidate = node_path_1.default.join(dir, name);
+        return node_fs_1.default.existsSync(candidate) ? candidate : 'ffprobe';
+    }
+    catch {
+        return 'ffprobe';
+    }
+}
+function resolveFfmpegBin(options = {}) {
+    if (typeof options?.ffmpegPath === 'string' && options.ffmpegPath)
+        return options.ffmpegPath;
+    const ctx = ffmpegRuntimeCtx();
+    const servicePath = ctx?.ffmpeg?.executable ?? ctx?.ffmpeg?.path;
+    if (typeof servicePath === 'string' && servicePath)
+        return servicePath;
+    return process.env.FFMPEG_PATH || process.env.FFMPEG_BIN || 'ffmpeg';
+}
+/** 把 karin 那种「一整条参数串」拆成 argv（引号内的空格要保留） */
+function splitCommandArgs(input) {
+    const args = [];
+    const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let match;
+    while ((match = pattern.exec(String(input ?? '')))) {
+        args.push(match[1] ?? match[2] ?? match[3]);
+    }
+    return args;
+}
+function runFfmpegBinary(bin, args, options = {}) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(bin, args, { windowsHide: true });
+        }
+        catch (error) {
+            resolve({ status: false, stdout: '', stderr: String(error?.message ?? error), code: null });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        // 默认 10 分钟兜底，避免遇到损坏文件 / 网络流时永远挂着（kkk 里都是 await 调用）
+        const timeout = Number(options?.timeout ?? 600000);
+        const timer = timeout > 0 ? setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* 忽略 */ }
+        }, timeout) : null;
+        const done = (result) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        child.stdout?.on('data', (chunk) => {
+            const text = String(chunk);
+            stdout += text;
+            options?.onStdout?.(text);
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = String(chunk);
+            stderr += text;
+            options?.onStderr?.(text);
+        });
+        child.on('error', (error) => {
+            done({ status: false, stdout, stderr: stderr + String(error?.message ?? error), code: null });
+        });
+        child.on('close', (code) => {
+            done({ status: code === 0, stdout, stderr, code });
+        });
+    });
+}
+const ffmpeg = (input, options = {}) => runFfmpegBinary(resolveFfmpegBin(options), splitCommandArgs(input), options);
+exports.ffmpeg = ffmpeg;
+const ffprobe = (input, options = {}) => {
+    const bin = typeof options?.ffprobePath === 'string' && options.ffprobePath
+        ? options.ffprobePath
+        : (process.env.FFPROBE_PATH || siblingFfprobe(resolveFfmpegBin(options)));
+    return runFfmpegBinary(bin, splitCommandArgs(input), options);
+};
+exports.ffprobe = ffprobe;
+/** 是否真的能用 ffmpeg（弹幕烧录 / 转码相关功能用它决定要不要提示「未接入」） */
+const isFfmpegAvailable = () => {
+    try {
+        const bin = resolveFfmpegBin();
+        if (bin === 'ffmpeg') {
+            // PATH 里的 ffmpeg：查一下常见位置即可，不为了探测去启动进程
+            return true;
+        }
+        return node_fs_1.default.existsSync(bin);
+    }
+    catch {
+        return false;
+    }
+};
+exports.isFfmpegAvailable = isFfmpegAvailable;
+/** express 应用实例（模块级懒加载，供 module/server 使用） */
+let expressApp;
+exports.app = new Proxy({}, {
+    get(_target, prop) {
+        if (!expressApp) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const express = require('express');
+            expressApp = express();
+        }
+        return expressApp[prop];
+    }
+});
+exports.karin = {
+    version: '1.16.3-koishi-compat',
+    command,
+    task,
+    on,
+    getBot: (selfId) => resolveBot(selfId),
+    /**
+     * 取所有在线 bot 的 id。
+     *
+     * 不能只读 `bot.selfId` —— 实测 `ctx.bots` 里混着 console / sandbox 这类
+     * selfId 为 null 的实例，过滤前会得到 `[null, null]`，推送任务就永远"找不到可用 bot"。
+     * 这里把几种可能的来源都兜上，并且丢掉空值。
+     */
+    getAllBotID: () => {
+        const bots = (0, runtime_1.tryGetRuntime)()?.ctx.bots ?? [];
+        const ids = bots.map((bot) => bot?.selfId ?? bot?.user?.id ?? bot?.internal?.selfId ?? '');
+        return [...new Set(ids.map((id) => String(id ?? '')).filter((id) => id && id !== 'undefined'))];
+    },
+    getAllBotList: () => ((0, runtime_1.tryGetRuntime)()?.ctx.bots ?? []).map((bot) => ({ bot: new KkkBot(bot), status: 1 })),
+    contactGroup: exports.contactGroup,
+    contactFriend: exports.contactFriend,
+    sendMsg,
+    sendMaster,
+    ctx: waitContext,
+    /** karin.template 在 Koishi 侧无对应实现 */
+    template: (_name) => undefined,
+    logger: logger_1.logger,
+    segment: segment_1.segment,
+    root: {}
+};
+exports.default = exports.karin;