koishi-plugin-memes/lib/provider.d.ts

MemeGenerator(RS)表情生成，全功能支持，可自由配置黑名单。

import { Context, h, Session } from 'koishi';
import { Config } from './index';
/**
 * @interface ParserFlags
 * @description 定义了命令行参数的解析标志。
 */
export interface ParserFlags {
    short?: boolean;
    long?: boolean;
    short_aliases?: string[];
    long_aliases?: string[];
}
/**
 * @interface MemeOption
 * @description 定义了表情模板的额外可配置选项。
 */
export interface MemeOption {
    name: string;
    type: string;
    default?: any;
    description?: string | null;
    parser_flags?: ParserFlags;
    choices?: (string | number)[] | null;
}
/**
 * @interface MemeShortcut
 * @description 定义了表情模板的快捷指令。
 */
export interface MemeShortcut {
    pattern: string;
    humanized?: string | null;
}
/**
 * @interface MemeInfo
 * @description 定义了单个表情模板的完整结构。
 */
export interface MemeInfo {
    key: string;
    keywords: string[];
    minImages: number;
    maxImages: number;
    minTexts: number;
    maxTexts: number;
    defaultTexts: string[];
    args: MemeOption[];
    tags?: string[];
    shortcuts?: MemeShortcut[];
    date_created?: string;
    date_modified?: string;
}
/**
 * @class MemeProvider
 * @description 负责与后端 API 交互，管理表情模板的获取、生成和处理。
 *              支持两种缓存策略：全量缓存和仅缓存 key。
 */
export declare class MemeProvider {
    private ctx;
    url: string;
    isRsApi: boolean;
    private cache;
    private keys;
    private logger;
    private config;
    /**
     * MemeProvider 构造函数。
     * @param ctx - Koishi 的上下文对象。
     * @param url - 后端 API 的地址。
     * @param config - 插件的配置项。
     */
    constructor(ctx: Context, url: string, config: Config);
    /**
     * 启动并初始化 Provider。
     * 它会检查 API 版本并根据配置拉取数据。
     * @returns 返回一个包含版本号和模板总数的对象。
     */
    start(): Promise<{
        version: string;
        count: number;
    }>;
    /**
     * 将非 rs API 返回的原始模板信息解析为标准 MemeInfo 格式。
     * @param data - 从 API 获取的原始数据对象。
     * @returns 标准化的 MemeInfo 对象。
     */
    private parseNonRsInfo;
    /**
     * 根据配置从后端 API 拉取数据。
     * 如果 `cacheAllInfo` 为 true，则缓存所有模板的详细信息；
     * 否则，仅缓存模板的 key 列表。
     * @returns 返回获取到的模板总数。
     */
    fetch(): Promise<number>;
    /**
     * @description 根据会话的上下文（群组ID）和全局配置，计算并返回一个包含所有被禁用表情 key 的集合。
     * @param {string} [guildId] - (可选) 当前会话的群组 ID。如果提供，将用于匹配特定群组的禁用规则。
     * @returns {Set<string>} 一个包含所有在当前上下文中被禁用的表情 key 的集合，可用于快速过滤。
     */
    private getExclusionSet;
    /**
     * 快速判断一个词是否可以触发表情制作。
     * 此方法仅操作本地缓存，不产生网络请求。
     * @param word - 要检查的单词 (key 或 keyword)。
     * @returns 如果可以触发则返回 true。
     */
    isTriggerable(word: string): boolean;
    /**
     * 根据关键词查找对应的快捷指令。
     * 仅在 `cacheAllInfo` 模式下有效。
     * @param word - 要查找的快捷指令关键词。
     * @param session - 当前 Koishi 会话，用于检查黑名单。
     * @returns 如果找到，则返回包含模板信息和快捷指令参数的对象，否则返回 null。
     */
    findShortcut(word: string, session?: Session): {
        meme: MemeInfo;
        shortcutArgs: string[];
    } | null;
    /**
     * 根据 key 或关键词获取单个模板信息。
     * - 缓存模式下：从内存中直接查找。
     * - 非缓存模式下：通过网络请求获取。
     * @param keyOrKeyword - 模板的 key 或关键词。
     * @param session - 当前 Koishi 会话，用于检查黑名单。
     * @returns 返回找到的 MemeInfo 对象，如果找不到或被禁用则返回 null。
     */
    getInfo(keyOrKeyword: string, session?: Session): Promise<MemeInfo | null>;
    /**
     * 根据查询字符串搜索模板。
     * - 缓存模式下：在本地进行带权重的模糊搜索。
     * - 非缓存模式下：依赖服务端的搜索接口或进行简单的 key 匹配。
     * @param query - 搜索关键词。
     * @param session - 当前 Koishi 会话，用于过滤黑名单。
     * @returns 返回匹配的 key 数组或 MemeInfo 数组。
     */
    search(query: string, session?: Session): Promise<string[] | MemeInfo[]>;
    /**
     * 随机获取一个模板信息。
     * @param session - 当前 Koishi 会话。
     * @param inputImages - 输入的有效图片数量（可选）。
     * @param inputTexts - 输入的有效文本数量（可选）。
     * @returns 返回找到的 MemeInfo 对象，如果找不到则返回 null。
     */
    getRandom(session?: Session, imgCnt?: number, txtCnt?: number): Promise<MemeInfo | null>;
    /**
     * 获取指定模板的预览图。
     * @param key - 模板的 key。
     * @returns 返回包含图片 Buffer 的 Promise，或在失败时返回错误信息的字符串。
     */
    getPreview(key: string): Promise<Buffer | string>;
    /**
     * 根据输入创建表情图片。
     * @param key - 模板的 key。
     * @param input - Koishi 的 h 元素数组，包含图片和文本。
     * @param session - 当前 Koishi 会话对象。
     * @returns 返回一个包含生成图片的 h 元素，或在失败时返回错误信息的字符串。
     * @throws {Error} 当参数不足时，抛出名为 'MissError' 的错误。
     */
    create(key: string, input: h[], session: Session): Promise<h | string>;
    /**
     * 调用后端 API 渲染模板列表图片。
     * @param session - 当前 Koishi 会话，用于过滤黑名单。
     * @returns 返回包含图片的 Buffer 或错误信息字符串。
     */
    renderList(session?: Session): Promise<Buffer | string>;
    /**
     * 调用后端 API 渲染统计图片。
     * @param title - 统计图标题。
     * @param type - 统计类型 ('meme_count' 或 'time_count')。
     * @param data - 统计数据，格式为 `[key, value]` 对的数组。
     * @returns 返回包含图片的 Buffer 或错误信息字符串。
     */
    renderStatistics(title: string, type: string, data: [string, number][]): Promise<Buffer | string>;
    /**
     * 调用后端 API 对单张图片进行处理。
     * @param endpoint - API 的端点名称。
     * @param imageUrl - 要处理的图片的 URL。
     * @param payload - (可选) 附加的请求体数据。
     * @returns 返回处理结果，可能是包含图片的 h 元素或文本信息。
     */
    processImage(endpoint: string, imageUrl: string, payload?: any): Promise<h | string>;
    /**
     * 调用后端 API 对多张图片进行处理。
     * @param endpoint - API 的端点名称。
     * @param sources - 包含多个图片 URL 的数组。
     * @param payload - (可选) 附加的请求体数据。
     * @returns 返回处理后的图片 h 元素，或错误信息。
     */
    processImages(endpoint: string, sources: string[], payload?: any): Promise<h | string>;
    /**
     * 封装图片合并端点的请求逻辑。
     * @param image_ids - 已上传的图片 ID 列表。
     * @param endpoint - API 的端点名称。
     * @param payload - 附加的请求体数据。
     * @returns 返回包含合并后图片的 Buffer。
     */
    private performMerge;
    /**
     * 将图片 Buffer 上传到后端 API。
     * @param buf - 包含图片数据的 Buffer。
     * @returns 返回上传后得到的 image_id。
     */
    private upload;
}