@forgetmelody/koishi-plugin-best-cave 0.0.0-stage → 1.0.0

package/lib/AIManager.d.ts

@@ -0,0 +1,99 @@
+import { Context, Logger } from 'koishi';
+import { Config, CaveObject } from './index';
+import { FileManager } from './FileManager';
+/**
+ * @description 定义了数据库 \`cave_meta\` 表的结构模型。
+ */
+export interface CaveMetaObject {
+    cave: number;
+    rating: number;
+    type: string;
+    keywords: string[];
+}
+declare module 'koishi' {
+    interface Tables {
+        cave_meta: CaveMetaObject;
+    }
+}
+/**
+ * @class AIManager
+ * @description AI 管理器，作为连接 AI 服务与回声洞功能的核心模块。
+ */
+export declare class AIManager {
+    private ctx;
+    private config;
+    private logger;
+    private fileManager;
+    private http;
+    private endpointIndex;
+    private retryTime;
+    /**
+     * @description 用于分析的 AI 系统提示词。
+     */
+    private readonly ANALYSIS_SYSTEM_PROMPT;
+    /**
+     * @description 用于查重的 AI 系统提示词。
+     */
+    private readonly DUPLICATE_SYSTEM_PROMPT;
+    /**
+     * @constructor
+     * @description AIManager 的构造函数。
+     * @param {Context} ctx - Koishi 的上下文对象。
+     * @param {Config} config - 插件的配置对象。
+     * @param {Logger} logger - 日志记录器实例。
+     * @param {FileManager} fileManager - 文件管理器实例。
+     */
+    constructor(ctx: Context, config: Config, logger: Logger, fileManager: FileManager);
+    /**
+     * @description 注册与 AI 功能相关的管理命令。
+     * @param {any} cave - \`cave\` 命令的实例，用于挂载子命令。
+     */
+    registerCommands(cave: any): void;
+    /**
+     * @description 检查新内容是否与数据库中已存在的回声洞重复。
+     * @param {CaveMetaObject} newAnalysis - 新内容经过 AI 分析后的元数据。
+     * @param {CaveObject} newCave - 待检查的新回声洞的完整对象。
+     * @returns {Promise<number[]>} - 一个 Promise，解析为重复的回声洞 ID 数组。如果不重复或检查失败，则为空数组。
+     */
+    checkForDuplicates(newAnalysis: CaveMetaObject, newCave: CaveObject): Promise<number[]>;
+    /**
+     * @description 对一个或多个回声洞内容进行 AI 分析。
+     * @param {CaveObject[]} caves - 需要分析的回声洞对象数组。
+     * @param {{ fileName: string; buffer: Buffer }[]} [mediaBuffers] - 可选的媒体文件缓存。
+     * @returns {Promise<CaveMetaObject[]>} - 一个 Promise，解析为分析结果（\`CaveMetaObject\`）的数组。
+     */
+    analyze(caves: CaveObject[], mediaBuffers?: {
+        fileName: string;
+        buffer: Buffer;
+    }[]): Promise<CaveMetaObject[]>;
+    /**
+     * @description 准备单个回声洞的内容（文本和图片）以供 AI 模型处理。
+     * @param {CaveObject} cave - 要处理的回声洞对象。
+     * @param {Map<string, Buffer>} [mediaMap] - 媒体文件的缓存 Map。
+     * @returns {Promise<any[] | null>} - 一个 Promise，解析为适合 AI 请求的 content 数组，如果回声洞为空则返回 null。
+     */
+    private prepareContent;
+    /**
+     * @description 使用 AI 批量判断一个主要回声洞是否与一组候选回声洞中的任何一个重复。
+     * @param {CaveObject} mainCave - 主要的回声洞。
+     * @param {CaveObject[]} candidateCaves - 用于比较的候选回声洞数组。
+     * @returns {Promise<number[]>} - 一个 Promise，解析为重复的回声洞 ID 数组。如果不重复或检查失败，则为空数组。
+     */
+    private IsDuplicate;
+    /**
+     * @description 计算两组关键词之间的相似度（Jaccard 相似系数）。
+     * @param {string[]} keywordsA - 第一组关键词。
+     * @param {string[]} keywordsB - 第二组关键词。
+     * @returns {number} - 返回 0 到 100 之间的相似度百分比。
+     */
+    private calculateSimilarity;
+    /**
+     * @description 向配置的 AI 服务端点发送请求的通用方法。
+     * @template T - 期望从 AI 响应中解析出的 JSON 对象的类型。
+     * @param {any[]} messages - 发送给 AI 的消息数组。
+     * @param {string} systemPrompt - 系统提示词。
+     * @returns {Promise<T>} - 一个 Promise，解析为从 AI 响应中解析出的 JSON 对象。
+     * @throws {Error} - 如果 AI 服务持续失败或响应无法解析，则抛出错误。
+     */
+    private requestAI;
+}

package/lib/DataManager.d.ts

@@ -0,0 +1,36 @@
+import { Context, Logger } from 'koishi';
+import { FileManager } from './FileManager';
+import { Config } from './index';
+/**
+ * @class DataManager
+ * @description 负责处理回声洞数据的导入和导出功能。
+ */
+export declare class DataManager {
+    private ctx;
+    private config;
+    private fileManager;
+    private logger;
+    /**
+     * @constructor
+     * @param ctx Koishi 上下文，用于数据库操作。
+     * @param config 插件配置。
+     * @param fileManager 文件管理器实例。
+     * @param logger 日志记录器实例。
+     */
+    constructor(ctx: Context, config: Config, fileManager: FileManager, logger: Logger);
+    /**
+     * @description 注册 `.export` 和 `.import` 子命令。
+     * @param cave - 主 `cave` 命令实例。
+     */
+    registerCommands(cave: any): void;
+    /**
+     * @description 导出所有 'active' 状态的回声洞数据到 `cave.json`。
+     * @returns 描述导出结果的消息字符串。
+     */
+    exportData(): Promise<string>;
+    /**
+     * @description 从 `cave.json` 文件导入回声洞数据。
+     * @returns 描述导入结果的消息字符串。
+     */
+    importData(): Promise<string>;
+}

package/lib/FileManager.d.ts

@@ -0,0 +1,48 @@
+import { Logger } from 'koishi';
+import { Config } from './index';
+/**
+ * @class FileManager
+ * @description 封装了对文件的存储、读取和删除操作。
+ * 能根据配置自动选择使用本地文件系统或 AWS S3 作为存储后端。
+ * 内置 Promise 文件锁，防止本地文件的并发写入冲突。
+ */
+export declare class FileManager {
+    private logger;
+    private resourceDir;
+    private locks;
+    private s3Client?;
+    private s3Bucket?;
+    /**
+     * @constructor
+     * @param baseDir Koishi 应用的基础数据目录 (ctx.baseDir)。
+     * @param config 插件的配置对象。
+     * @param logger 日志记录器实例。
+     */
+    constructor(baseDir: string, config: Config, logger: Logger);
+    /**
+     * @description 使用文件锁安全地执行异步文件操作，防止并发读写冲突。
+     * @template T 异步操作的返回类型。
+     * @param fullPath 需要加锁的文件的完整路径。
+     * @param operation 要执行的异步函数。
+     * @returns 异步操作的结果。
+     */
+    private withLock;
+    /**
+     * @description 保存文件，自动选择 S3 或本地存储。
+     * @param fileName 用作 S3 Key 或本地文件名。
+     * @param data 要写入的 Buffer 数据。
+     * @returns 保存时使用的文件名。
+     */
+    saveFile(fileName: string, data: Buffer): Promise<string>;
+    /**
+     * @description 读取文件，自动从 S3 或本地存储读取。
+     * @param fileName 要读取的文件名/标识符。
+     * @returns 文件的 Buffer 数据。
+     */
+    readFile(fileName: string): Promise<Buffer>;
+    /**
+     * @description 删除文件，自动从 S3 或本地删除。
+     * @param fileIdentifier 要删除的文件名/标识符。
+     */
+    deleteFile(fileIdentifier: string): Promise<void>;
+}

package/lib/HashManager.d.ts

@@ -0,0 +1,73 @@
+import { Context, Logger } from 'koishi';
+import { Config } from './index';
+import { FileManager } from './FileManager';
+/**
+ * @description 数据库 `cave_hash` 表的完整对象模型。
+ */
+export interface CaveHashObject {
+    cave: number;
+    hash: string;
+    type: 'text' | 'image';
+}
+/**
+ * @class HashManager
+ * @description 负责生成、存储和比较文本与图片的哈希值。
+ * 实现了基于 Simhash 的文本查重和基于 DCT 感知哈希 (pHash) 的图片查重方案。
+ */
+export declare class HashManager {
+    private ctx;
+    private config;
+    private logger;
+    private fileManager;
+    /**
+     * @constructor
+     * @param ctx - Koishi 上下文，用于数据库操作。
+     * @param config - 插件配置，用于获取相似度阈值等。
+     * @param logger - 日志记录器实例。
+     * @param fileManager - 文件管理器实例，用于读取图片文件。
+     */
+    constructor(ctx: Context, config: Config, logger: Logger, fileManager: FileManager);
+    /**
+     * @description 注册与哈希功能相关的子命令。
+     * @param cave - 主 `cave` 命令实例。
+     */
+    registerCommands(cave: any): void;
+    /**
+     * @description 扫描并修复单个图片 Buffer，移除文件结束符之后的多余数据。
+     * @param imageBuffer - 原始的图片 Buffer。
+     * @returns 修复后的图片 Buffer。如果无需修复，则返回原始 Buffer。
+     */
+    sanitizeImageBuffer(imageBuffer: Buffer): Buffer;
+    /**
+     * @description 执行一维离散余弦变换 (DCT-II) 的方法。
+     * @param input - 输入的数字数组。
+     * @returns DCT 变换后的数组。
+     */
+    private dct1D;
+    /**
+     * @description 执行二维离散余弦变换 (DCT-II) 的方法。
+     * 通过对行和列分别应用一维 DCT 来实现。
+     * @param matrix - 输入的 N x N 像素亮度矩阵。
+     * @returns DCT 变换后的 N x N 系数矩阵。
+     */
+    private dct2D;
+    /**
+     * @description pHash 算法核心实现，使用 Jimp 和自定义 DCT。
+     * @param imageBuffer - 图片的 Buffer。
+     * @returns 64位十六进制 pHash 字符串。
+     */
+    generatePHash(imageBuffer: Buffer): Promise<string>;
+    /**
+     * @description 根据汉明距离计算相似度百分比。
+     * @param hex1 - 第一个哈希。
+     * @param hex2 - 第二个哈希。
+     * @returns 相似度 (0-100)。
+     */
+    calculateSimilarity(hex1: string, hex2: string): number;
+    /**
+     * @description 为文本生成 64 位 Simhash 字符串。
+     * @param text - 需要处理的文本。
+     * @returns 16位十六进制 Simhash 字符串。
+     */
+    generateTextSimhash(text: string): string;
+}

package/lib/NameManager.d.ts

@@ -0,0 +1,45 @@
+import { Context } from 'koishi';
+/** 数据库 `cave_user` 表的结构。 */
+export interface UserName {
+    userId: string;
+    nickname: string;
+}
+declare module 'koishi' {
+    interface Tables {
+        cave_user: UserName;
+    }
+}
+/**
+ * @class NameManager
+ * @description 负责管理用户在回声洞中的自定义昵称。
+ */
+export declare class NameManager {
+    private ctx;
+    /**
+     * @constructor
+     * @param ctx - Koishi 上下文，用于初始化数据库模型。
+     */
+    constructor(ctx: Context);
+    /**
+     * @description 注册 `.name` 子命令，用于管理用户昵称。
+     * @param cave - 主 `cave` 命令实例。
+     */
+    registerCommands(cave: any): void;
+    /**
+     * @description 设置或更新指定用户的昵称。
+     * @param userId - 目标用户的 ID。
+     * @param nickname - 要设置的新昵称。
+     */
+    setNickname(userId: string, nickname: string): Promise<void>;
+    /**
+     * @description 获取指定用户的昵称。
+     * @param userId - 目标用户的 ID。
+     * @returns 用户的昵称字符串或 null。
+     */
+    getNickname(userId: string): Promise<string | null>;
+    /**
+     * @description 清除指定用户的昵称设置。
+     * @param userId - 目标用户的 ID。
+     */
+    clearNickname(userId: string): Promise<void>;
+}

package/lib/PendManager.d.ts

@@ -0,0 +1,31 @@
+import { Context, Logger } from 'koishi';
+import { CaveObject, Config } from './index';
+import { FileManager } from './FileManager';
+/**
+ * @class PendManager
+ * @description 负责处理回声洞的审核流程，处理新洞的提交、审核通知和审核操作。
+ */
+export declare class PendManager {
+    private ctx;
+    private config;
+    private fileManager;
+    private logger;
+    /**
+     * @param ctx Koishi 上下文。
+     * @param config 插件配置。
+     * @param fileManager 文件管理器实例。
+     * @param logger 日志记录器实例。
+     * @param reusableIds 可复用 ID 的内存缓存。
+     */
+    constructor(ctx: Context, config: Config, fileManager: FileManager, logger: Logger);
+    /**
+     * @description 注册与审核相关的子命令。
+     * @param cave - 主 `cave` 命令实例。
+     */
+    registerCommands(cave: any): void;
+    /**
+     * @description 将新回声洞提交到管理群组以供审核。
+     * @param cave 新创建的、状态为 'pending' 的回声洞对象。
+     */
+    sendForPend(cave: CaveObject): Promise<void>;
+}

package/lib/Utils.d.ts

@@ -0,0 +1,100 @@
+import { Context, h, Logger, Session } from 'koishi';
+import { CaveObject, Config, StoredElement } from './index';
+import { FileManager } from './FileManager';
+import { HashManager } from './HashManager';
+import { AIManager } from './AIManager';
+import { PendManager } from './PendManager';
+/**
+ * @description 构建一条用于发送的完整回声洞消息，处理不同存储后端的资源链接。
+ * @param cave 回声洞对象。
+ * @param config 插件配置。
+ * @param fileManager 文件管理器实例。
+ * @param logger 日志记录器实例。
+ * @param platform 目标平台名称 (e.g., 'onebot')。
+ * @param prefix 可选的消息前缀 (e.g., '已删除', '待审核')。
+ * @returns 包含多条消息的数组，每条消息是一个 (string | h)[] 数组。
+ */
+export declare function buildCaveMessage(cave: CaveObject, config: Config, fileManager: FileManager, logger: Logger, platform?: string, prefix?: string): Promise<(string | h)[][]>;
+/**
+ * @description 直接调用 QQ 官方机器人 API 发送带自定义键盘的 Markdown 消息。
+ * @param session 当前会话。
+ * @param content Markdown 文本内容。
+ */
+export declare function sendQQCaveMarkdown(session: Session, content: string): Promise<void>;
+/**
+ * @description 发送一条回声洞。QQ 平台使用单条 Markdown + 自定义键盘消息，其余平台保持原有逻辑。
+ * @param session 当前会话。
+ * @param cave 回声洞对象。
+ * @param config 插件配置。
+ * @param fileManager 文件管理器实例。
+ * @param logger 日志记录器实例。
+ * @param prefix 可选的消息前缀。
+ */
+export declare function sendCave(session: Session, cave: CaveObject, config: Config, fileManager: FileManager, logger: Logger, prefix?: string): Promise<void>;
+/**
+ * @description 解析指令中的回声洞序号，兼容空格、| 与逗号等多种分隔写法。
+ * @param inputs 指令参数的原始值。
+ * @returns ids 为去重后的合法序号，invalid 为无法解析的原始片段。
+ */
+export declare function parseCaveIds(inputs: unknown[]): {
+    ids: number[];
+    invalid: string[];
+};
+/**
+ * @description 获取下一个可用的回声洞 ID，采用“回收ID > 扫描空缺 > 最大ID+1”策略。
+ * @param ctx Koishi 上下文。
+ * @param reusableIds 可复用 ID 的内存缓存。
+ * @returns 可用的新 ID。
+ */
+export declare function getNextCaveId(ctx: Context, reusableIds: Set<number>): Promise<number>;
+/**
+ * @description 解析消息元素，分离出文本和待下载的媒体文件。
+ * @param sourceElements 原始的 Koishi 消息元素数组。
+ * @param newId 这条回声洞的新 ID。
+ * @param session 触发操作的会话。
+ * @param config 插件配置。
+ * @param logger 日志实例。
+ * @param creationTime 统一的创建时间戳，用于生成文件名。
+ * @returns 包含数据库元素和待保存媒体列表的对象。
+ */
+export declare function processMessageElements(sourceElements: h[], newId: number, session: Session, creationTime: Date): Promise<{
+    finalElementsForDb: StoredElement[];
+    mediaToSave: {
+        sourceUrl: string;
+        fileName: string;
+    }[];
+}>;
+/**
+ * @description 根据提供的配对关系，将项目 ID 进行聚类。
+ * @param pairs 一个由 [number, number] 组成的数组，代表需要合并的项目 ID 配对。
+ * @returns 返回一个二维数组，每个子数组代表一个大小大于1的聚类。
+ */
+export declare function clusterItemsFromPairs(pairs: [number, number][]): number[][];
+/**
+ * @description 通用的 LSH (局部敏感哈希) 候选对生成器。
+ * @param items 要处理的项目数组。
+ * @param getBucketInfo 一个函数，接收单个项目，并返回其唯一 ID 和一个桶键数组。
+ * @returns 一个 Set，包含所有候选对的字符串键 (e.g., "123-456")。
+ */
+export declare function generateFromLSH<T>(items: T[], getBucketInfo: (item: T) => {
+    id: number;
+    keys: string[];
+}): Set<string>;
+/**
+ * @description 处理新回声洞创建后的后续逻辑，包括媒体下载、查重、AI分析、哈希存储和状态更新。
+ * @param ctx Koishi 上下文。
+ * @param config 插件配置。
+ * @param fileManager 文件管理器实例。
+ * @param logger 日志记录器实例。
+ * @param reusableIds 可复用 ID 的内存缓存。
+ * @param newCave 已初步创建（status: 'preload'）的回声洞对象。
+ * @param mediaToSave 待保存的媒体文件列表。
+ * @param session 触发操作的会话。
+ * @param hashManager 哈希管理器实例（如果启用）。
+ * @param aiManager AI管理器实例（如果启用）。
+ * @param reviewManager 审核管理器实例（如果启用）。
+ */
+export declare function processNewCave(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, reusableIds: Set<number>, newCave: CaveObject, session: Session, mediaToSave: {
+    sourceUrl: string;
+    fileName: string;
+}[], hashManager: HashManager | null, aiManager: AIManager | null, reviewManager: PendManager | null): Promise<void>;

package/lib/index.d.ts

@@ -0,0 +1,72 @@
+import { Context, Schema } from 'koishi';
+import { CaveHashObject } from './HashManager';
+import { CaveMetaObject } from './AIManager';
+export declare const name = "best-cave";
+export declare const inject: string[];
+export declare const usage = "\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #4a6ee0;\">\uD83D\uDCCC \u63D2\u4EF6\u8BF4\u660E</h2>\n  <p>\uD83D\uDCD6 <strong>\u4F7F\u7528\u6587\u6863</strong>\uFF1A\u8BF7\u70B9\u51FB\u5DE6\u4E0A\u89D2\u7684 <strong>\u63D2\u4EF6\u4E3B\u9875</strong> \u67E5\u770B\u63D2\u4EF6\u4F7F\u7528\u6587\u6863</p>\n  <p>\uD83D\uDD0D <strong>\u66F4\u591A\u63D2\u4EF6</strong>\uFF1A\u53EF\u8BBF\u95EE <a href=\"https://github.com/YisRime\" style=\"color:#4a6ee0;text-decoration:none;\">\u82E1\u6DDE\u7684 GitHub</a> \u67E5\u770B\u672C\u4EBA\u7684\u6240\u6709\u63D2\u4EF6</p>\n</div>\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #e0574a;\">\u2764\uFE0F \u652F\u6301\u4E0E\u53CD\u9988</h2>\n  <p>\uD83C\uDF1F \u559C\u6B22\u8FD9\u4E2A\u63D2\u4EF6\uFF1F\u8BF7\u5728 <a href=\"https://github.com/YisRime\" style=\"color:#e0574a;text-decoration:none;\">GitHub</a> \u4E0A\u7ED9\u6211\u4E00\u4E2A Star\uFF01</p>\n  <p>\uD83D\uDC1B \u9047\u5230\u95EE\u9898\uFF1F\u8BF7\u901A\u8FC7 <strong>Issues</strong> \u63D0\u4EA4\u53CD\u9988\uFF0C\u6216\u52A0\u5165 QQ \u7FA4 <a href=\"https://qm.qq.com/q/PdLMx9Jowq\" style=\"color:#e0574a;text-decoration:none;\"><strong>855571375</strong></a> \u8FDB\u884C\u4EA4\u6D41</p>\n</div>\n";
+/**
+ * @description 存储在合并转发中的单个节点的数据结构。
+ */
+export interface ForwardNode {
+    userId: string;
+    userName: string;
+    elements: StoredElement[];
+}
+/**
+ * @description 存储在数据库中的单个消息元素。
+ */
+export interface StoredElement {
+    type: 'text' | 'image' | 'video' | 'audio' | 'file' | 'at' | 'forward' | 'reply' | 'face';
+    content?: string | ForwardNode[];
+    file?: string;
+}
+/**
+ * @description 数据库 \`cave\` 表的完整对象模型。
+ */
+export interface CaveObject {
+    id: number;
+    elements: StoredElement[];
+    channelId: string;
+    userId: string;
+    userName: string;
+    status: 'active' | 'delete' | 'pending' | 'preload';
+    time: Date;
+}
+declare module 'koishi' {
+    interface Tables {
+        cave: CaveObject;
+        cave_hash: CaveHashObject;
+        cave_meta: CaveMetaObject;
+    }
+}
+export interface Config {
+    perChannel: boolean;
+    adminChannel: string;
+    enableName: boolean;
+    enableIO: boolean;
+    enablePend: boolean;
+    caveFormat: string;
+    enableSimilarity: boolean;
+    textThreshold: number;
+    imageThreshold: number;
+    localPath?: string;
+    enableS3: boolean;
+    endpoint?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    bucket?: string;
+    publicUrl?: string;
+    enableAI: boolean;
+    endpoints?: {
+        url: string;
+        key: string;
+        model: string;
+    }[];
+    enableApprove: boolean;
+    approveThreshold: number;
+    onAIReviewFail: boolean;
+    systemPrompt: string;
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;