koishi-plugin-ets2-tools-tmp 3.4.5 → 3.5.0

package/lib/util/localImageHost.js

@@ -0,0 +1,219 @@
+/**
+ * 本地图片托管：把截图写成文件，并注册 HTTP 路由对外提供公网 URL。
+ *
+ * 为什么需要它：
+ * - QQ 官方机器人的 qqbot-media 方案有「单机器人 100 张」上限，且手机端不渲染；
+ * - markdown 里用**公网 https URL** 是最稳妥的（所有客户端都支持）。
+ *
+ * 用法：配置 publicBaseUrl（如 https://bd.114512.xyz:5155）后，
+ * 本模块会把图片存到 <data>/tmp-images/<hash>.png，
+ * 并提供 <publicBaseUrl>/tmp-images/<hash>.png 的访问地址。
+ *
+ * 依赖：Koishi 的 server 服务（koishi.yml 里已有 server 插件）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/** 路由前缀 */
+const ROUTE_PREFIX = '/tmp-images';
+
+/** 已注册过路由的 ctx（避免重复注册） */
+const registered = new WeakSet();
+
+/** 图片保留时长（毫秒）：超过自动清理，避免磁盘无限增长 */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 计算图片存储目录。
+ * 优先用 Koishi 的 baseDir/data，取不到就退到当前工作目录下的 data。
+ */
+function resolveImageDir(ctx) {
+    const base = (ctx && ctx.baseDir) ||
+        (ctx && ctx.app && ctx.app.baseDir) ||
+        process.cwd();
+    return path.join(base, 'data', 'tmp-images');
+}
+
+/**
+ * 从公网地址里取 URL 路径前缀（子路径部署时用）。
+ * 例如 https://bot.114512.xyz/koishi → '/koishi'
+ *      https://bot.114512.xyz        → ''
+ */
+function getPathPrefix(cfg) {
+    const base = getPublicBaseUrl(cfg);
+    if (!base) return '';
+    try {
+        const u = new URL(base);
+        const p = String(u.pathname || '').replace(/\/+$/, '');
+        return p === '/' ? '' : p;
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * 注册静态路由（幂等）。
+ *
+ * 路由会带上公网地址里的子路径前缀，保证「生成的 URL」和「实际挂载路径」一致。
+ * 例如配置 https://bot.114512.xyz/koishi 时，路由为 /koishi/tmp-images/:name。
+ *
+ * @param {object} ctx koishi context
+ * @param {object} cfg 插件配置
+ * @returns {string|null} 图片目录；server 服务不可用时返回 null
+ */
+function registerStaticRoute(ctx, cfg) {
+    if (!ctx.server || typeof ctx.server.get !== 'function') {
+        return null;
+    }
+    if (registered.has(ctx)) {
+        return resolveImageDir(ctx);
+    }
+
+    const dir = resolveImageDir(ctx);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    } catch (error) {
+        ctx.logger.warn(`[本地图片] 创建目录失败: ${error.message}`);
+        return null;
+    }
+
+    const prefix = getPathPrefix(cfg);
+    const routePath = `${prefix}${ROUTE_PREFIX}/:name`;
+
+    ctx.server.get(routePath, (koaCtx) => {
+        const raw = String(koaCtx.params && koaCtx.params.name || '');
+        // 防目录穿越：只允许安全文件名
+        const name = path.basename(raw);
+        if (!/^[A-Za-z0-9_-]+\.(png|jpg|jpeg|gif|webp)$/i.test(name)) {
+            koaCtx.status = 404;
+            return;
+        }
+        const file = path.join(dir, name);
+        if (!fs.existsSync(file)) {
+            koaCtx.status = 404;
+            return;
+        }
+        const ext = path.extname(name).toLowerCase();
+        const mime = ext === '.png' ? 'image/png'
+            : ext === '.gif' ? 'image/gif'
+                : ext === '.webp' ? 'image/webp'
+                    : 'image/jpeg';
+        koaCtx.type = mime;
+        // 图片内容不变（按 hash 命名），可长缓存
+        koaCtx.set('Cache-Control', 'public, max-age=86400');
+        koaCtx.body = fs.createReadStream(file);
+    });
+
+    registered.add(ctx);
+    return dir;
+}
+
+/**
+ * 清理过期图片（按 mtime）。
+ * @returns {number} 删除的文件数
+ */
+function cleanupExpired(ctx, dir) {
+    let removed = 0;
+    try {
+        const now = Date.now();
+        for (const name of fs.readdirSync(dir)) {
+            const file = path.join(dir, name);
+            try {
+                const stat = fs.statSync(file);
+                if (stat.isFile() && now - stat.mtimeMs > MAX_AGE_MS) {
+                    fs.unlinkSync(file);
+                    removed++;
+                }
+            } catch { }
+        }
+    } catch { }
+    if (removed > 0 && ctx.logger) {
+        ctx.logger.debug(`[本地图片] 已清理 ${removed} 个过期文件`);
+    }
+    return removed;
+}
+
+/**
+ * 把图片元素存成本地文件，返回可公网访问的 URL。
+ *
+ * @param {object} ctx koishi context
+ * @param {object} cfg 插件配置（需要 qqOfficial.publicBaseUrl）
+ * @param {object} imageSegment 图片元素
+ * @returns {Promise<string|null>} 公网 URL；未配置或失败返回 null
+ */
+async function saveImageForPublicUrl(ctx, cfg, imageSegment) {
+    const baseUrl = getPublicBaseUrl(cfg);
+    if (!baseUrl) return null;
+
+    const dir = registerStaticRoute(ctx, cfg);
+    if (!dir) return null;
+
+    const src = imageSegment && imageSegment.attrs && (imageSegment.attrs.src || imageSegment.attrs.url);
+    if (!src) return null;
+
+    // 已是公网 URL：直接返回
+    if (/^https?:\/\//i.test(src)) return src;
+
+    const m = /^data:([^;]+);base64,(.*)$/s.exec(src);
+    if (!m) return null;
+
+    const mime = String(m[1] || '').toLowerCase();
+    const ext = mime === 'image/png' ? 'png'
+        : mime === 'image/gif' ? 'gif'
+            : mime === 'image/webp' ? 'webp'
+                : 'jpg';
+
+    let buffer;
+    try {
+        buffer = Buffer.from(m[2], 'base64');
+    } catch {
+        return null;
+    }
+    if (!buffer.length) return null;
+
+    // 按内容 hash 命名：同一张图不重复写盘
+    const hash = crypto.createHash('sha1').update(buffer).digest('hex').slice(0, 20);
+    const fileName = `${hash}.${ext}`;
+    const filePath = path.join(dir, fileName);
+
+    try {
+        if (!fs.existsSync(filePath)) {
+            fs.writeFileSync(filePath, buffer);
+            // 顺手清理过期文件
+            cleanupExpired(ctx, dir);
+        } else {
+            // 命中已有文件：刷新 mtime，延长保留期
+            try { fs.utimesSync(filePath, new Date(), new Date()); } catch { }
+        }
+    } catch (error) {
+        ctx.logger.warn(`[本地图片] 写入失败: ${error.message}`);
+        return null;
+    }
+
+    return `${baseUrl}${ROUTE_PREFIX}/${fileName}`;
+}
+
+/**
+ * 读取配置里的公网地址（去掉末尾斜杠）。
+ */
+function getPublicBaseUrl(cfg) {
+    const raw = cfg && cfg.qqOfficial && cfg.qqOfficial.publicBaseUrl;
+    if (!raw) return null;
+    const text = String(raw).trim();
+    if (!text) return null;
+    if (!/^https?:\/\//i.test(text)) return null;
+    return text.replace(/\/+$/, '');
+}
+
+module.exports = {
+    ROUTE_PREFIX,
+    MAX_AGE_MS,
+    getPublicBaseUrl,
+    getPathPrefix,
+    registerStaticRoute,
+    saveImageForPublicUrl,
+    cleanupExpired,
+    resolveImageDir,
+};

package/lib/util/messageRender.js

@@ -0,0 +1,234 @@
+/**
+ * 消息输出层：统一处理「文本 / 图片」两种呈现方式，并区分 onebot 与 QQ 官方机器人。
+ *
+ * 设计要点：
+ * - 业务代码只关心「内容」和「要不要图片」，不用处理平台差异；
+ * - onebot：图片就发图片，文本就发文本（原有行为完全不变）；
+ * - QQ 官方：走「原生 markdown + keyboard」直接发送，
+ *   因为走元素层无法控制按钮分行（br 无效、多个 button-group 会产生空行）。
+ *
+ * 所有函数都返回可交给 session.send 的内容；
+ * 官方机器人下若已由本模块直接发送，则返回 SENT 标记由调用方忽略。
+ */
+
+const qqOfficial = require('./qqOfficial');
+const qqMediaUpload = require('./qqMediaUpload');
+const qqMarkdown = require('./qqMarkdown');
+const localImageHost = require('./localImageHost');
+
+/** 表示「消息已由本模块直接发送完毕」，调用方无需再返回内容 */
+const SENT = Symbol('qq-message-sent');
+
+/**
+ * 是否应使用图片形式。
+ * @param {number|string} type 1=文本，2=图片（沿用插件现有 type 约定）
+ */
+function wantImage(type) {
+    return Number(type) === 2;
+}
+
+/**
+ * 把纯文本转成一个适合 markdown 的正文。
+ * 官方适配器在 <qq:markdown> 内不转义，外面的文本会被转义，
+ * 所以业务文本要放进来才能保留 `**`、`#` 等语法。
+ */
+function markdownText(text) {
+    return qqOfficial.markdownBlock(text);
+}
+
+/**
+ * 文本输出。
+ *
+ * @param {object} session koishi session
+ * @param {string} text 文本内容
+ * @param {object} [opts]
+ * @param {boolean} [opts.markdown] 官方机器人是否用 markdown 包裹（默认 true）
+ * @param {Array<Array<object>>} [opts.buttons] 按钮行（仅官方机器人有效）
+ * @returns {string|Array<object>|Promise<Symbol>}
+ */
+async function renderText(session, text, opts) {
+    const options = opts || {};
+    const body = String(text == null ? '' : text);
+
+    // onebot 及未启用官方适配器：保持原样，绝不加任何元素
+    if (!qqOfficial.isQQOfficial(session)) {
+        return body;
+    }
+
+    const useMarkdown = options.markdown !== false;
+    const buttons = Array.isArray(options.buttons) ? options.buttons : [];
+
+    if (!useMarkdown && buttons.length === 0) {
+        return body;
+    }
+
+    // 官方机器人：优先走原生发送（可精确控制按钮分行）
+    if (typeof qqMarkdown.sendMarkdownWithButtons === 'function' && typeof session?.bot?.internal?.sendMessage === 'function') {
+        const sent = await qqMarkdown.sendMarkdownWithButtons(session, {
+            markdown: useMarkdown ? body : '',
+            buttons,
+        });
+        if (sent) return SENT;
+    }
+
+    // 回退：元素层（按钮可能挤在一行，但至少能发出去）
+    const children = [];
+    if (useMarkdown) {
+        children.push(markdownText(body));
+    } else {
+        children.push(require('koishi').h.text(body));
+    }
+    if (buttons.length > 0) {
+        children.push(qqOfficial.buttonGroup(buttons));
+    }
+    return children;
+}
+
+/**
+ * 图片 + 可选按钮的输出。
+ *
+ * @param {object} session
+ * @param {object} imageSegment segment.image(...) 产出的图片元素
+ * @param {object} [opts]
+ * @param {Array<Array<object>>} [opts.buttons] 按钮行（仅官方机器人有效）
+ * @param {string} [opts.caption] 图片上方的说明文本（官方机器人可选）
+ * @param {function(object): Promise<string|null>} [opts.uploader]
+ *        官方机器人下，用于把本地图片转成 markdown 可用 URL 的函数
+ * @returns {object|Array<object>|Promise<Symbol>}
+ */
+async function renderImage(session, imageSegment, opts) {
+    const options = opts || {};
+
+    // onebot：原样返回图片元素，行为不变
+    if (!qqOfficial.isQQOfficial(session)) {
+        return imageSegment;
+    }
+
+    const buttons = Array.isArray(options.buttons) ? options.buttons : [];
+    const uploader = options.uploader || options.defaultUploader;
+
+    // 优先：上传图片 → 写进 markdown → 原生发送（图片与按钮同一条消息）
+    if (typeof uploader === 'function' && options.inline !== false) {
+        const inline = await renderInlineImage(session, imageSegment, buttons, { ...options, uploader });
+        if (inline) return inline;
+    }
+
+    // 退化：图片一条 + 按钮一条（保持可用）
+    if (buttons.length === 0) {
+        return imageSegment;
+    }
+    const children = [imageSegment];
+    if (options.caption) {
+        children.push(markdownText(options.caption));
+    }
+    children.push(qqOfficial.buttonGroup(buttons));
+    return children;
+}
+
+/**
+ * 把图片塞进 markdown 正文，与按钮共用一条消息。
+ * @returns {Promise<Symbol|Array<object>|null>} 成功返回 SENT；退化时返回元素数组；失败返回 null
+ */
+async function renderInlineImage(session, imageSegment, buttons, options) {
+    let imageUrl = null;
+    try {
+        imageUrl = await options.uploader(imageSegment);
+    } catch (error) {
+        imageUrl = null;
+    }
+
+    if (!imageUrl) {
+        // 上传失败：交给调用方退化处理
+        if (buttons.length === 0) return null;
+        const children = [imageSegment];
+        if (options.caption) children.push(markdownText(options.caption));
+        children.push(qqOfficial.buttonGroup(buttons));
+        return children;
+    }
+
+    // markdown：说明文字 + 图片
+    const lines = [];
+    if (options.caption) lines.push(options.caption);
+    lines.push(`![${options.alt || 'image'}](${imageUrl})`);
+    const markdown = lines.join('\n');
+
+    // 原生发送（一条消息：图片 + 按钮）
+    if (typeof session?.bot?.internal?.sendMessage === 'function') {
+        const sent = await qqMarkdown.sendMarkdownWithButtons(session, { markdown, buttons });
+        if (sent) return SENT;
+    }
+
+    // 回退元素层
+    return qqOfficial.markdownWithButtons(markdown, buttons);
+}
+
+/**
+ * 按配置的 type 选择输出形式。
+ *
+ * @param {object} session
+ * @param {object} cfg 插件配置
+ * @param {string} typePath 取 type 的路径，如 'tmpMileageRanking.type'
+ * @param {object} content
+ * @param {string} content.text 文本内容
+ * @param {function(): Promise<object>} [content.image] 生成图片的异步函数
+ * @param {Array<Array<object>>} [content.buttons] 按钮行
+ * @returns {Promise<object|string|Symbol>}
+ */
+async function renderByType(ctx, session, cfg, typePath, content) {
+    const type = readType(cfg, typePath);
+    const buttons = content.buttons || [];
+
+    if (wantImage(type) && typeof content.image === 'function') {
+        const image = await content.image();
+        if (image) {
+            // 官方机器人：把图片转成 markdown 可引用的地址，和按钮合成一条消息
+            return renderImage(session, image, {
+                buttons,
+                caption: content.caption,
+                alt: content.alt,
+                uploader: qqOfficial.isQQOfficial(session)
+                    ? await buildUploader(ctx, cfg, session)
+                    : null,
+            });
+        }
+        // 图片生成失败 → 回退文本，保证有回应
+    }
+
+    return renderText(session, content.text, { buttons });
+}
+
+/**
+ * 构造图片上传器：
+ * 1. 配置了 qqOfficial.publicBaseUrl → 存本地文件，用公网 URL（无数量限制，手机端也可显示）
+ * 2. 否则退回 QQ 官方 media-images 上传（有限制，但可用）
+ */
+async function buildUploader(ctx, cfg, session) {
+    // 有公网域名：走本地文件 + 静态路由
+    if (ctx && localImageHost.getPublicBaseUrl(cfg)) {
+        return (seg) => localImageHost.saveImageForPublicUrl(ctx, cfg, seg);
+    }
+    // 回退：QQ 官方素材上传
+    return (seg) => qqMediaUpload.uploadImageForMarkdown(session, seg);
+}
+
+/** 读取形如 'a.b.c' 的配置路径 */
+function readType(cfg, path) {
+    if (!path) return 1;
+    let cur = cfg;
+    for (const key of String(path).split('.')) {
+        if (cur == null) return 1;
+        cur = cur[key];
+    }
+    return cur == null ? 1 : cur;
+}
+
+module.exports = {
+    SENT,
+    wantImage,
+    markdownText,
+    renderText,
+    renderImage,
+    renderByType,
+    buildUploader,
+    readType,
+};

package/lib/util/qqMarkdown.js

@@ -0,0 +1,171 @@
+/**
+ * QQ 官方机器人：直接构造原生的 markdown + keyboard 消息。
+ *
+ * 为什么不用 Koishi 元素层：
+ * - `<button-group>` 里用 `<br>` 分隔行**无效**（适配器不处理 br，所有按钮挤一行）；
+ * - 每个按钮一个 `<button-group>` 会产生**空行**（适配器 flush 时多 push 了空数组）；
+ * - 结果就是按钮被压缩成「再...」「我...」这种省略号。
+ *
+ * 所以这里绕过元素层，直接拼 QQ 官方的 payload：
+ *   { msg_type: 2, markdown: { content }, keyboard: { content: { rows } } }
+ * 这样每一行放几个按钮完全可控。
+ */
+
+const qqOfficial = require('./qqOfficial');
+
+const MSG_TIMEOUT = 5 * 60 * 1000 - 2000;
+
+/**
+ * 构造单个按钮的原生结构（与适配器 decodeButton 保持一致）。
+ *
+ * 支持两种入参写法：
+ * - 原生风格：{ label, type: 'input'|'link'|'callback', text|href|id, primary }
+ * - 便捷风格：{ label, text }        → 自动视为 input 按钮
+ * - 便捷风格：{ label, href }        → 自动视为 link 按钮
+ * - 也可直接传 qqOfficial.inputButton() 产出的元素，自动转换
+ *
+ * @returns {object} QQ 官方按钮结构
+ */
+function nativeButton(opts) {
+    const o = opts || {};
+
+    // 已经是原生结构（有 render_data + action）→ 幂等返回，避免二次转换把 label 清空
+    if (o.render_data && o.action) {
+        return {
+            render_data: {
+                label: String(o.render_data.label == null ? '' : o.render_data.label),
+                visited_label: String(o.render_data.visited_label == null ? o.render_data.label || '' : o.render_data.visited_label),
+                style: o.render_data.style === 1 ? 1 : 0,
+            },
+            action: {
+                type: o.action.type === 2 ? 2 : o.action.type === 0 ? 0 : 1,
+                permission: { type: 2 },
+                data: String(o.action.data == null ? '' : o.action.data),
+            },
+        };
+    }
+
+    // 已经是 Koishi 元素（inputButton 等的产出）：从 attrs 里取
+    let label, type, text, href, id, primary;
+    if (o.type && o.attrs) {
+        const a = o.attrs || {};
+        label = String(Array.isArray(o.children) ? o.children.join('') : '');
+        type = a.type || 'input';
+        text = a.text;
+        href = a.href;
+        id = a.id;
+        primary = a.class === 'primary';
+    } else {
+        label = String(o.label == null ? '' : o.label);
+        type = o.type || (o.href ? 'link' : 'input');
+        text = o.text;
+        href = o.href;
+        id = o.id;
+        primary = !!o.primary;
+    }
+
+    const actionType = type === 'input' ? 2 : type === 'link' ? 0 : 1;
+    let data = '';
+    if (actionType === 2) data = String(text == null ? '' : text);
+    else if (actionType === 0) data = String(href == null ? '' : href);
+    else data = String(id == null ? '' : id);
+
+    return {
+        render_data: {
+            label,
+            visited_label: label,
+            style: primary ? 1 : 0,
+        },
+        action: {
+            type: actionType,
+            permission: { type: 2 },
+            data,
+        },
+    };
+}
+
+/**
+ * 把「按钮行」转成原生 keyboard 结构。
+ * @param {Array<Array<object>>} rows 行数组；每行是若干按钮
+ * @returns {object|null} keyboard；无按钮返回 null
+ */
+function buildKeyboard(rows) {
+    if (!Array.isArray(rows)) return null;
+    const out = [];
+    for (const row of rows) {
+        if (!Array.isArray(row) || row.length === 0) continue;
+        out.push({ buttons: row.map(nativeButton) });
+    }
+    // QQ 键盘最多 5 行，每行最多 5 个按钮
+    const limited = out.slice(0, 5).map(r => ({ buttons: r.buttons.slice(0, 5) }));
+    return limited.length ? { content: { rows: limited } } : null;
+}
+
+/**
+ * 发送一条「markdown 正文 + 按钮」的官方消息（一条消息，不是多条）。
+ *
+ * @param {object} session koishi session
+ * @param {object} content
+ * @param {string} content.markdown markdown 正文
+ * @param {Array<Array<object>>} [content.buttons] 按钮行
+ * @returns {Promise<object|null>} 发送结果；不支持时返回 null（调用方回退到元素层）
+ */
+async function sendMarkdownWithButtons(session, content) {
+    const c = content || {};
+    const markdown = String(c.markdown == null ? '' : c.markdown);
+
+    const bot = session && session.bot;
+    if (!bot || !bot.internal) return null;
+
+    const keyboard = buildKeyboard(c.buttons);
+
+    // 被动回复：群聊用 msg_id（同一消息内可多次回复，msg_seq 递增）
+    const data = {
+        msg_type: 2,
+        markdown: { content: markdown || ' ' },
+        msg_id: undefined,
+        msg_seq: undefined,
+        event_id: undefined,
+    };
+    if (keyboard) data.keyboard = keyboard;
+
+    // 复用被动回复窗口（5 分钟内可以 msg_id 连续回复）
+    const now = Date.now();
+    if (session.messageId && session.timestamp && now - session.timestamp < MSG_TIMEOUT) {
+        session['seq'] = (session['seq'] || 0) + 1;
+        data.msg_id = session.messageId;
+        data.msg_seq = session['seq'];
+    } else if (session.qq && session.qq.id && session.timestamp && now - session.timestamp < MSG_TIMEOUT) {
+        data.event_id = session.qq.id;
+    } else if (session.messageId) {
+        data.msg_id = session.messageId;
+        data.msg_seq = 1;
+    }
+
+    const send = async () => {
+        if (session.isDirect) {
+            return await bot.internal.sendPrivateMessage(session.channelId, data);
+        }
+        return await bot.internal.sendMessage(session.channelId, data);
+    };
+
+    try {
+        return await send();
+    } catch (error) {
+        // 被动回复窗口过期：不带头重发一次
+        const noPassive = !data.msg_id && !data.event_id;
+        if (!noPassive) {
+            delete data.msg_id;
+            delete data.msg_seq;
+            delete data.event_id;
+            try { return await send(); } catch { return null; }
+        }
+        return null;
+    }
+}
+
+module.exports = {
+    nativeButton,
+    buildKeyboard,
+    sendMarkdownWithButtons,
+};