koishi-plugin-best-cave 2.7.15 → 2.7.16

package/lib/index.js

@@ -1144,23 +1144,17 @@ var AIManager = class {
    * @returns {Promise<number>} 一个 Promise，解析为成功分析和存储的条目数。
    */
   async analyzeAndStore(caves, mediaBuffers) {
-    try {
-      const mediaMap = mediaBuffers ? new Map(mediaBuffers.map((m) => [m.fileName, m.buffer])) : void 0;
-      const results = await this.getAnalyses(caves, mediaMap);
-      if (!results?.length) return 0;
-      const caveMetaObjects = results.map((res) => ({
-        cave: res.cave,
-        keywords: res.keywords || [],
-        description: res.description || "",
-        rating: Math.max(0, Math.min(100, res.rating || 0))
-      }));
-      await this.ctx.database.upsert("cave_meta", caveMetaObjects);
-      return caveMetaObjects.length;
-    } catch (error) {
-      const caveIds = caves.map((c) => c.id).join(", ");
-      this.logger.error(`分析回声洞 (${caveIds}) 出错:`, error);
-      throw error;
-    }
+    const mediaMap = mediaBuffers ? new Map(mediaBuffers.map((m) => [m.fileName, m.buffer])) : void 0;
+    const results = await this.getAnalyses(caves, mediaMap);
+    if (!results?.length) return 0;
+    const caveMetaObjects = results.map((res) => ({
+      cave: res.cave,
+      keywords: res.keywords || [],
+      description: res.description || "",
+      rating: Math.max(0, Math.min(100, res.rating || 0))
+    }));
+    await this.ctx.database.upsert("cave_meta", caveMetaObjects);
+    return caveMetaObjects.length;
   }
   /**
    * @description 调用 AI 判断两个回声洞内容是否重复或高度相似。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-best-cave",
   "description": "功能强大、高度可定制的回声洞。支持丰富的媒体类型、内容查重、人工审核、用户昵称、数据迁移以及本地/S3 双重文件存储后端。",
-  "version": "2.7.15",
+  "version": "2.7.16",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],

package/lib/AIManager.d.ts

@@ -1,92 +0,0 @@
-import { Context, Logger } from 'koishi';
-import { Config, CaveObject, StoredElement } from './index';
-import { FileManager } from './FileManager';
-/**
- * @description 定义了数据库 `cave_meta` 表的结构模型。
- * @property {number} cave - 关联的回声洞 `id`，作为外键和主键。
- * @property {string[]} keywords - AI 从回声洞内容中提取的核心关键词数组。
- * @property {string} description - AI 生成的对回声洞内容的简洁摘要或描述。
- * @property {number} rating - AI 对内容质量、趣味性或相关性的综合评分，范围为 0 到 100。
- */
-export interface CaveMetaObject {
-    cave: number;
-    keywords: string[];
-    description: string;
-    rating: number;
-}
-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 requestCount;
-    private rateLimitResetTime;
-    /**
-     * @constructor
-     * @param {Context} ctx - Koishi 的上下文对象，提供框架核心功能。
-     * @param {Config} config - 插件的配置对象。
-     * @param {Logger} logger - 日志记录器实例，用于输出日志。
-     * @param {FileManager} fileManager - 文件管理器实例，用于处理媒体文件。
-     */
-    constructor(ctx: Context, config: Config, logger: Logger, fileManager: FileManager);
-    /**
-     * @description 注册所有与 AIManager 功能相关的 Koishi 命令。
-     * @param {any} cave - Koishi 命令实例，用于挂载子命令。
-     */
-    registerCommands(cave: any): void;
-    /**
-     * @description 对新提交的内容执行 AI 驱动的查重检查。
-     * @param {StoredElement[]} newElements - 新提交的内容元素数组。
-     * @param {{ fileName: string; buffer: Buffer }[]} [mediaBuffers] - 可选的媒体文件缓冲区数组。
-     * @returns {Promise<{ duplicate: boolean; ids?: number[] }>} 一个 Promise，解析为一个对象，指示内容是否重复以及重复的回声洞 ID 数组（如果存在）。
-     */
-    checkForDuplicates(newElements: StoredElement[], mediaBuffers?: {
-        fileName: string;
-        buffer: Buffer;
-    }[]): Promise<{
-        duplicate: boolean;
-        ids?: number[];
-    }>;
-    /**
-     * @description 对单个或批量回声洞执行完整的分析和存储流程。
-     * @param {CaveObject[]} caves - 要分析的回声洞对象数组。
-     * @param {{ fileName: string; buffer: Buffer }[]} [mediaBuffers] - 可选的媒体文件缓冲区数组，仅在分析新内容时使用。
-     * @returns {Promise<number>} 一个 Promise，解析为成功分析和存储的条目数。
-     */
-    analyzeAndStore(caves: CaveObject[], mediaBuffers?: {
-        fileName: string;
-        buffer: Buffer;
-    }[]): Promise<number>;
-    /**
-     * @description 调用 AI 判断两个回声洞内容是否重复或高度相似。
-     * @param {CaveObject} caveA - 第一个回声洞对象。
-     * @param {CaveObject} caveB - 第二个回声洞对象。
-     * @returns {Promise<boolean>} 如果内容相似则返回 true，否则返回 false。
-     */
-    private isContentDuplicateAI;
-    /**
-     * @description 为一批回声洞准备内容，并向 AI 发送单个请求以获取所有分析结果。
-     * @param {CaveObject[]} caves - 要分析的回声洞对象数组。
-     * @param {Map<string, Buffer>} [mediaBufferMap] - 可选的媒体文件名到其缓冲区的映射。
-     * @returns {Promise<CaveMetaObject[]>} 一个 Promise，解析为 AI 返回的分析结果数组。
-     */
-    private getAnalyses;
-    /**
-     * @description 封装了向 OpenAI 兼容的 API 发送请求的底层逻辑，并稳健地解析 JSON 响应。
-     * @param {any[]} messages - 发送给 AI 的消息数组，遵循 OpenAI 格式。
-     * @param {string} systemPrompt - 系统提示词，用于指导 AI 的行为。
-     * @returns {Promise<T>} 一个 Promise，解析为从 AI 接收到的、解析后的 JSON 对象。
-     * @throws {Error} 当 AI 返回空或无效内容时抛出错误。
-     */
-    private requestAI;
-}

package/lib/DataManager.d.ts

@@ -1,36 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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 注册与哈希功能相关的 `.hash` 和 `.check` 子命令。
-     * @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 汉明距离。
-     */
-    calculateHammingDistance(hex1: string, hex2: string): number;
-    /**
-     * @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

@@ -1,45 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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;
-    private reusableIds;
-    /**
-     * @param ctx Koishi 上下文。
-     * @param config 插件配置。
-     * @param fileManager 文件管理器实例。
-     * @param logger 日志记录器实例。
-     * @param reusableIds 可复用 ID 的内存缓存。
-     */
-    constructor(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, reusableIds: Set<number>);
-    /**
-     * @description 注册与审核相关的子命令。
-     * @param cave - 主 `cave` 命令实例。
-     */
-    registerCommands(cave: any): void;
-    /**
-     * @description 将新回声洞提交到管理群组以供审核。
-     * @param cave 新创建的、状态为 'pending' 的回声洞对象。
-     */
-    sendForPend(cave: CaveObject): Promise<void>;
-}

package/lib/Utils.d.ts

@@ -1,91 +0,0 @@
-import { Context, h, Logger, Session } from 'koishi';
-import { CaveObject, Config, StoredElement } from './index';
-import { FileManager } from './FileManager';
-import { HashManager, CaveHashObject } from './HashManager';
-/**
- * @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 清理数据库中标记为 'delete' 状态的回声洞及其关联文件和哈希。
- * @param ctx Koishi 上下文。
- * @param fileManager 文件管理器实例。
- * @param logger 日志记录器实例。
- * @param reusableIds 可复用 ID 的内存缓存。
- */
-export declare function cleanupPendingDeletions(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, reusableIds: Set<number>): Promise<void>;
-/**
- * @description 根据配置和会话，生成数据库查询的范围条件。
- * @param session 当前会话。
- * @param config 插件配置。
- * @param includeStatus 是否包含 status: 'active' 条件，默认为 true。
- * @returns 数据库查询条件对象。
- */
-export declare function getScopeQuery(session: Session, config: Config, includeStatus?: boolean): object;
-/**
- * @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 执行文本 (Simhash) 和图片 (pHash) 相似度查重。
- * @returns 一个对象，指示是否发现重复项；如果未发现，则返回生成的哈希。
- */
-export declare function performSimilarityChecks(ctx: Context, config: Config, hashManager: HashManager, logger: Logger, finalElementsForDb: StoredElement[], downloadedMedia: {
-    fileName: string;
-    buffer: Buffer;
-}[]): Promise<{
-    duplicate: boolean;
-    message?: string;
-    textHashesToStore?: Omit<CaveHashObject, 'cave'>[];
-    imageHashesToStore?: Omit<CaveHashObject, 'cave'>[];
-}>;
-/**
- * @description 异步处理文件上传，并在成功后更新回声洞状态。
- * @param ctx - Koishi 上下文。
- * @param config - 插件配置。
- * @param fileManager - FileManager 实例，用于保存文件。
- * @param logger - 日志记录器实例。
- * @param cave - 刚刚在数据库中创建的 `preload` 状态的回声洞对象。
- * @param downloadedMedia - 需要保存的媒体文件及其 Buffer。
- * @param reusableIds - 可复用 ID 的内存缓存。
- * @param session - 触发此操作的用户会话。
- * @returns 成功则返回最终状态 ('pending' or 'active')，失败则返回 'delete'。
- */
-export declare function handleFileUploads(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, cave: CaveObject, downloadedMedia: {
-    fileName: string;
-    buffer: Buffer;
-}[], reusableIds: Set<number>, needsReview: boolean): Promise<'pending' | 'active'>;
-/**
- * @description 校验会话是否来自指定的管理群组。
- * @param session 当前会话。
- * @param config 插件配置。
- * @returns 如果校验不通过，返回错误信息字符串；如果通过，返回 null。
- */
-export declare function requireAdmin(session: Session, config: Config): string | null;

package/lib/index.d.ts

@@ -1,67 +0,0 @@
-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;
-    aiEndpoint?: string;
-    aiApiKey?: string;
-    aiModel?: string;
-    aiRPM?: number;
-}
-export declare const Config: Schema<Config>;
-export declare function apply(ctx: Context, config: Config): void;