koishi-plugin-best-cave 2.3.18 → 2.4.0

package/lib/index.d.ts

@@ -56,7 +56,6 @@ export interface Config {
     secretAccessKey?: string;
     bucket?: string;
     publicUrl?: string;
-    debug: boolean;
 }
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -1001,10 +1001,7 @@ var Config = import_koishi3.Schema.intersect([
     region: import_koishi3.Schema.string().default("auto").description("区域 (Region)"),
     accessKeyId: import_koishi3.Schema.string().description("Access Key ID").role("secret"),
     secretAccessKey: import_koishi3.Schema.string().description("Secret Access Key").role("secret")
-  }).description("存储配置"),
-  import_koishi3.Schema.object({
-    debug: import_koishi3.Schema.boolean().default(false).description("启用调试模式，将在控制台输出详细的操作日志。")
-  }).description("开发配置")
+  }).description("存储配置")
 ]);
 function apply(ctx, config) {
   ctx.model.extend("cave", {
@@ -1057,16 +1054,8 @@ function apply(ctx, config) {
         if (!reply) return "等待操作超时";
         sourceElements = import_koishi3.h.parse(reply);
       }
-      if (config.debug) {
-        logger.info(`消息内容: 
-${JSON.stringify(sourceElements, null, 2)}`);
-        logger.info(`完整会话: 
-${JSON.stringify(session, null, 2)}`);
-      }
       const newId = await getNextCaveId(ctx, getScopeQuery(session, config, false), reusableIds);
       const { finalElementsForDb, mediaToSave } = await processMessageElements(sourceElements, newId, session, config, logger);
-      if (config.debug) logger.info(`数据库元素: 
-${JSON.stringify(finalElementsForDb, null, 2)}`);
       if (finalElementsForDb.length === 0) return "无可添加内容";
       const textHashesToStore = [];
       if (hashManager) {

package/package.json

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

package/readme.md

@@ -8,7 +8,7 @@
 
 - **丰富的内容形式**：不止于文本，轻松发布包含图片、视频、音频甚至文件的混合内容。插件能自动解析回复或引用的消息，并将其完整存入回声洞。
 - **灵活的存储后端**：媒体文件可存储在 **本地服务器** (`data/cave` 目录)，或配置使用 **AWS S3** 兼容的云端对象存储。支持通过公共URL、本地文件路径或Base64三种方式发送媒体。
-- **高级内容查重**：(可选) 启用后，插件会在添加时自动计算文本（Simhash）和图片（pHash，包括整体及分块哈希）的哈希值，拒绝与现有内容相似度过高的投稿，并能对局部相似的图片进行提示，有效防止重复。
+- **高级内容查重**：(可选) 启用后，插件会在添加时自动计算文本 (Simhash) 和图片 (pHash) 的哈希值。对于相似度过高的投稿将直接拒绝，有效防止重复。此外，还会对图片的四个象限进行哈希，管理员可通过维护工具找出局部相同的图片。
 - **完善的审核机制**：(可选) 启用后，所有新投稿都将进入待审核状态，并通知管理群组。只有管理员审核通过后，内容才会对用户可见，确保内容质量。
 - **精细的作用域**：通过 `perChannel` 配置，可设定回声洞是在所有群聊中共享（全局模式），还是在每个群聊中独立（分群模式）。
 - **专属用户昵称**：(可选) 用户可以为自己在回声洞中的发言设置一个专属昵称，增加趣味性。
@@ -66,8 +66,8 @@
 | :--- | :--- | :--- | :--- |
 | `enablePend` | `boolean` | `false` | 是否启用审核机制。启用后，新投稿将进入`pending`状态。 |
 | `enableSimilarity` | `boolean` | `false` | 是否启用内容相似度检查（查重）。 |
-| `textThreshold` | `number` | `95` | **文本**相似度阈值 (0-100)。基于Simhash汉明距离计算，超过此值将被拒绝。 |
-| `imageThreshold` | `number` | `95` | **图片整体**相似度阈值 (0-100)。基于pHash汉明距离计算，超过此值将被拒绝。 |
+| `textThreshold` | `number` | `90` | **文本**相似度阈值 (0-100)。基于Simhash汉明距离计算，超过此值将被拒绝。 |
+| `imageThreshold` | `number` | `90` | **图片整体**相似度阈值 (0-100)。基于pHash汉明距离计算，超过此值将被拒绝。 |
 
 ### 存储配置
 
@@ -91,4 +91,4 @@
 2. **文件存储权限**：若使用本地存储，请确保 Koishi 拥有对 `data/cave` 目录的读写权限。若使用 S3，请确保 Access Key 权限和存储桶策略（如ACL设为`public-read`）配置正确。
 3. **异步删除**：删除操作（`cave.del` 或审核拒绝）会将内容状态标记为 `delete`，然后由后台任务异步清理关联的文件和数据库条目，以避免阻塞当前指令。
 4. **数据迁移**：导入功能会读取插件数据目录下的 `cave_import.json`。导出功能则会生成 `cave_export.json`。请在操作前放置或备份好相应文件。导入时，ID会从现有最大ID开始自增，不会覆盖或修改老数据。
-5. **查重机制**：图片查重不仅比较整图，还会比较图片的四个象限。如果象限完全一致，会发送提示但不会直接拒绝，为识别拼接图、裁剪图等提供了依据。
+5. **查重机制**：图片查重在投稿时，仅基于**整图**的相似度进行判断和拒绝。插件还会为图片的四个象限生成哈希，但这些局部哈希仅用于 `cave.check` 指令生成相似度报告，以供管理员识别拼接图、裁剪图等情况，并不会在投稿时直接导致拒绝。

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_export.json`。
-     * @returns 描述导出结果的消息字符串。
-     */
-    exportData(): Promise<string>;
-    /**
-     * @description 从 `cave_import.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,102 +0,0 @@
-import { Context, Logger } from 'koishi';
-import { Config, CaveObject } from './index';
-import { FileManager } from './FileManager';
-/**
- * @description 数据库 `cave_hash` 表的完整对象模型。
- */
-export interface CaveHashObject {
-    cave: number;
-    hash: string;
-    type: 'simhash' | 'phash_g' | 'phash_q1' | 'phash_q2' | 'phash_q3' | 'phash_q4';
-}
-/**
- * @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 检查数据库中所有回声洞，为没有哈希记录的历史数据生成哈希。
-     * @returns 一个包含操作结果的报告字符串。
-     */
-    generateHashesForHistoricalCaves(): Promise<string>;
-    /**
-     * @description 为单个回声洞对象生成所有类型的哈希（文本+图片）。
-     * @param cave - 回声洞对象。
-     * @returns 生成的哈希对象数组。
-     */
-    generateAllHashesForCave(cave: Pick<CaveObject, 'id' | 'elements'>): Promise<CaveHashObject[]>;
-    /**
-     * @description 对数据库中所有哈希进行两两比较，找出相似度过高的内容。
-     * @param options 包含临时阈值的可选对象。
-     * @returns 一个包含检查结果的报告字符串。
-     */
-    checkForSimilarCaves(options?: {
-        textThreshold?: number;
-        imageThreshold?: number;
-    }): Promise<string>;
-    /**
-     * @description 为单个图片Buffer生成全局pHash和四个象限的局部pHash。
-     * @param imageBuffer - 图片的Buffer数据。
-     * @returns 包含全局哈希和四象限哈希的对象。
-     */
-    generateAllImageHashes(imageBuffer: Buffer): Promise<{
-        globalHash: string;
-        quadrantHashes: {
-            q1: string;
-            q2: string;
-            q3: string;
-            q4: string;
-        };
-    }>;
-    /**
-     * @description 执行二维离散余弦变换 (DCT-II)。
-     * @param matrix - 输入的 N x N 像素亮度矩阵。
-     * @returns DCT变换后的 N x N 系数矩阵。
-     */
-    private _dct2D;
-    /**
-     * @description pHash 算法核心实现。
-     * @param imageBuffer - 图片的Buffer。
-     * @param size - 期望的哈希位数 (必须是完全平方数, 如 64 或 256)。
-     * @returns 十六进制pHash字符串。
-     */
-    private _generatePHash;
-    /**
-     * @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,83 +0,0 @@
-import { Context, h, Logger, Session } from 'koishi';
-import { CaveObject, Config, StoredElement } from './index';
-import { FileManager } from './FileManager';
-import { HashManager, CaveHashObject } from './HashManager';
-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 清理数据库中标记为 'delete' 状态的回声洞及其关联文件和哈希。
- * @param ctx Koishi 上下文。
- * @param fileManager 文件管理器实例。
- * @param logger 日志记录器实例。
- * @param reusableIds 可复用 ID 的内存缓存。
- */
-export declare function cleanupPendingDeletions(ctx: Context, 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 query 查询范围条件。
- * @param reusableIds 可复用 ID 的内存缓存。
- * @returns 可用的新 ID。
- */
-export declare function getNextCaveId(ctx: Context, query: object, reusableIds: Set<number>): Promise<number>;
-/**
- * @description 检查用户是否处于指令冷却中。
- * @returns 若在冷却中则提示字符串，否则 null。
- */
-export declare function checkCooldown(session: Session, config: Config, lastUsed: Map<string, number>): string | null;
-/**
- * @description 更新指定频道的指令使用时间戳。
- */
-export declare function updateCooldownTimestamp(session: Session, config: Config, lastUsed: Map<string, number>): void;
-/**
- * @description 解析消息元素，分离出文本和待下载的媒体文件。
- * @param sourceElements 原始的 Koishi 消息元素数组。
- * @param newId 这条回声洞的新 ID。
- * @param session 触发操作的会话。
- * @param config 插件配置。
- * @param logger 日志实例。
- * @returns 包含数据库元素和待保存媒体列表的对象。
- */
-export declare function processMessageElements(sourceElements: h[], newId: number, session: Session, config: Config, logger: Logger): Promise<{
-    finalElementsForDb: StoredElement[];
-    mediaToSave: {
-        sourceUrl: string;
-        fileName: string;
-    }[];
-}>;
-/**
- * @description 异步处理文件上传、查重和状态更新的后台任务。
- * @param ctx - Koishi 上下文。
- * @param config - 插件配置。
- * @param fileManager - FileManager 实例，用于保存文件。
- * @param logger - 日志记录器实例。
- * @param reviewManager - ReviewManager 实例，用于提交审核。
- * @param cave - 刚刚在数据库中创建的 `preload` 状态的回声洞对象。
- * @param mediaToSave - 需要下载和处理的媒体文件列表。
- * @param reusableIds - 可复用 ID 的内存缓存。
- * @param session - 触发此操作的用户会话，用于发送反馈。
- * @param hashManager - HashManager 实例，如果启用则用于哈希计算和比较。
- * @param textHashesToStore - 已预先计算好的、待存入数据库的文本哈希对象数组。
- */
-export declare function handleFileUploads(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, reviewManager: PendManager, cave: CaveObject, mediaToToSave: {
-    sourceUrl: string;
-    fileName: string;
-}[], reusableIds: Set<number>, session: Session, hashManager: HashManager, textHashesToStore: Omit<CaveHashObject, 'cave'>[]): Promise<void>;