koishi-plugin-best-cave 2.2.9 → 2.3.0

package/lib/index.js

@@ -442,7 +442,7 @@ async function handleFileUploads(ctx, config, fileManager, logger2, reviewManage
         for (const existing of existingGlobalHashes) {
           const similarity = hashManager.calculateSimilarity(globalHash, existing.hash);
           if (similarity >= config.imageWholeThreshold) {
-            await session.send(`图片与回声洞（${existing.cave}）的相似度为 ${similarity.toFixed(2)}%，超过阈值`);
+            await session.send(`图片与回声洞（${existing.cave}）的相似度（${similarity.toFixed(2)}%）超过阈值`);
             await ctx.database.upsert("cave", [{ id: cave.id, status: "delete" }]);
             cleanupPendingDeletions(ctx, fileManager, logger2, reusableIds);
             return;
@@ -453,7 +453,7 @@ async function handleFileUploads(ctx, config, fileManager, logger2, reviewManage
           for (const existing of existingQuadrantHashes) {
             if (notifiedPartialCaves.has(existing.cave)) continue;
             if (newSubHash === existing.hash) {
-              await session.send(`图片局部与回声洞（${existing.cave}）存在完全相同的区块`);
+              await session.send(`图片与回声洞（${existing.cave}）局部相同`);
               notifiedPartialCaves.add(existing.cave);
             }
           }
@@ -1035,7 +1035,7 @@ function apply(ctx, config) {
             for (const existing of existingTextHashes) {
               const similarity = hashManager.calculateSimilarity(newSimhash, existing.hash);
               if (similarity >= config.textThreshold) {
-                return `文本与回声洞（${existing.cave}）的相似度为 ${similarity.toFixed(2)}%，超过阈值`;
+                return `文本与回声洞（${existing.cave}）的相似度（${similarity.toFixed(2)}%）超过阈值`;
               }
             }
             textHashesToStore.push({ hash: newSimhash, type: "simhash" });

package/package.json

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

package/readme.md

@@ -8,13 +8,14 @@
 
 - **丰富的内容形式**：不止于文本，轻松发布包含图片、视频、音频甚至文件的混合内容。插件能自动解析回复或引用的消息，并将其完整存入回声洞。
 - **灵活的存储后端**：媒体文件可存储在 **本地服务器** (`data/cave` 目录)，或配置使用 **AWS S3** 兼容的云端对象存储。支持通过公共URL、本地文件路径或Base64三种方式发送媒体。
-- **内容相似度检查**：(可选) 启用后，插件会在添加时自动计算文本（Simhash）和图片（pHash）的哈希值，拒绝与现有内容相似度过高的投稿，有效防止重复。
+- **高级内容查重**：(可选) 启用后，插件会在添加时自动计算文本（Simhash）和图片（pHash，包括整体及分块哈希）的哈希值，拒绝与现有内容相似度过高的投稿，并能对局部相似的图片进行提示，有效防止重复。
 - **完善的审核机制**：(可选) 启用后，所有新投稿都将进入待审核状态，并通知管理群组。只有管理员审核通过后，内容才会对用户可见，确保内容质量。
 - **精细的作用域**：通过 `perChannel` 配置，可设定回声洞是在所有群聊中共享（全局模式），还是在每个群聊中独立（分群模式）。
 - **专属用户昵称**：(可选) 用户可以为自己在回声洞中的发言设置一个专属昵称，增加趣味性。
 - **便捷的数据管理**：(可选) 管理员可通过指令轻松地将所有回声洞数据导出为 `JSON` 文件备份，或从文件中恢复数据，迁移无忧。
-- **强大的维护工具**：管理员可以通过 `cave.hash` 指令为历史数据批量生成哈希值，并获取一份所有内容的相似度报告。
+- **强大的维护工具**：管理员可以通过 `cave.hash` 指令为历史数据批量生成哈希值，并通过 `cave.check` 获取一份所有内容的相似度报告。
 - **权限分离**：普通用户可删除自己的投稿。审核、数据管理等高级操作则仅限在指定的 **管理群组** 内由管理员执行。
+- **智能ID管理**：采用ID回收和空缺扫描机制，确保回声洞序号紧凑，并能高效处理大量删除和添加操作。
 
 ## 📖 指令说明
 
@@ -23,7 +24,7 @@
 | 指令 | 别名/选项 | 说明 |
 | :--- | :--- | :--- |
 | `cave` | | 随机查看一条回声洞。 |
-| `cave.add [内容]` | `cave -a [内容]` | 添加一条新的回声洞。可直接跟内容，也可回复/引用消息，或等待机器人提示后发送。 |
+| `cave.add [内容]` | `cave -a [内容]` | 添加一条新的回声洞。可直接跟内容，也可回复/引用消息，或等待机器人提示后在一分钟内发送。 |
 | `cave.view <序号>` | `cave -g <序号>` | 查看指定序号的回声洞。 |
 | `cave.del <序号>` | `cave -r <序号>` | 删除指定序号的回声洞。仅投稿人或在管理群组内的管理员可操作。 |
 | `cave.list` | `cave -l` | 查询并列出自己投稿过的所有回声洞序号及总数。 |
@@ -41,7 +42,8 @@
 | `cave.review.N [序号]` | `enableReview: true` | **(仅限管理群组)** 拒绝审核。若不提供序号，则拒绝所有待审核内容。 |
 | `cave.export` | `enableIO: true` | **(仅限管理群组)** 将所有`active`状态的回声洞导出到 `cave_export.json`。 |
 | `cave.import` | `enableIO: true` | **(仅限管理群组)** 从 `cave_import.json` 文件中导入数据。 |
-| `cave.hash` | `enableSimilarity: true` | **(仅限管理群组)** 校验所有历史数据，补全哈希并检查内容相似度。 |
+| `cave.hash` | `enableSimilarity: true` | **(仅限管理群组)** 校验所有历史数据，为缺失哈希的回声洞补全记录。 |
+| `cave.check` | `enableSimilarity: true` | **(仅限管理群组)** 检查所有回声洞的哈希，生成一份关于文本和图片相似度的报告。 |
 
 ## ⚙️ 配置说明
 
@@ -60,10 +62,10 @@
 
 | 配置项 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
-| `enableReview` | `boolean` | `false` | 是否启用审核机制。 |
+| `enableReview` | `boolean` | `false` | 是否启用审核机制。启用后，新投稿将进入`pending`状态。 |
 | `enableSimilarity` | `boolean` | `false` | 是否启用内容相似度检查（查重）。 |
-| `textThreshold` | `number` | `0.9` | 文本相似度阈值 (0-1)。超过此值将被拒绝。 |
-| `imageThreshold` | `number` | `0.9` | 图片相似度阈值 (0-1)。超过此值将被拒绝。 |
+| `textThreshold` | `number` | `95` | **文本**相似度阈值 (0-100)。基于Simhash汉明距离计算，超过此值将被拒绝。 |
+| `imageWholeThreshold` | `number` | `95` | **图片整体**相似度阈值 (0-100)。基于pHash汉明距离计算，超过此值将被拒绝。 |
 
 ### 存储配置
 
@@ -83,7 +85,8 @@
 1. **媒体发送方式**：插件会按以下优先级决定如何发送图片、视频等媒体文件：
     1. **S3 公共URL**：如果 `enableS3` 和 `publicUrl` 已配置。
     2. **本地文件路径**：如果 `localPath` 已配置。
-    3. **Base64 编码**：如果以上两项均未配置，将文件转为 Base64 发送（可能受平台大小限制）。
-2. **文件存储权限**：若使用本地存储，请确保 Koishi 拥有对 `data/cave` 目录的读写权限。若使用 S3，请确保 Access Key 权限和存储桶策略配置正确。
+    3. **Base64 编码**：如果以上两项均未配置，将文件转为 Base64 发送（可能受平台大小限制或支持问题）。
+2. **文件存储权限**：若使用本地存储，请确保 Koishi 拥有对 `data/cave` 目录的读写权限。若使用 S3，请确保 Access Key 权限和存储桶策略（如ACL设为`public-read`）配置正确。
 3. **异步删除**：删除操作（`cave.del` 或审核拒绝）会将内容状态标记为 `delete`，然后由后台任务异步清理关联的文件和数据库条目，以避免阻塞当前指令。
-4. **数据迁移**：导入功能会读取插件数据目录下的 `cave_import.json`。导出功能则会生成 `cave_export.json`。请在操作前放置或备份好相应文件。
+4. **数据迁移**：导入功能会读取插件数据目录下的 `cave_import.json`。导出功能则会生成 `cave_export.json`。请在操作前放置或备份好相应文件。导入时，ID会从现有最大ID开始自增，不会覆盖或修改老数据。
+5. **查重机制**：图片查重不仅比较整图，还会比较图片的四个象限。如果象限完全一致，会发送提示但不会直接拒绝，为识别拼接图、裁剪图等提供了依据。

package/lib/HashManager.d.ts

@@ -1,98 +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 对数据库中所有哈希进行两两比较，找出相似度过高的内容。
-     * @returns 一个包含检查结果的报告字符串。
-     */
-    checkForSimilarCaves(): 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/Utils.d.ts

@@ -1,71 +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 { ReviewManager } from './ReviewManager';
-/**
- * @description 将数据库存储的 StoredElement[] 转换为 Koishi 的 h() 元素数组。
- * @param elements 从数据库读取的元素数组。
- * @returns 转换后的 h() 元素数组。
- */
-export declare function storedFormatToHElements(elements: StoredElement[]): h[];
-/**
- * @description 构建一条用于发送的完整回声洞消息，处理不同存储后端的资源链接。
- * @param cave 回声洞对象。
- * @param config 插件配置。
- * @param fileManager 文件管理器实例。
- * @param logger 日志记录器实例。
- * @returns 包含 h() 元素和字符串的消息数组。
- */
-export declare function buildCaveMessage(cave: CaveObject, config: Config, fileManager: FileManager, logger: Logger): 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 触发操作的会话。
- * @returns 包含数据库元素和待保存媒体列表的对象。
- */
-export declare function processMessageElements(sourceElements: h[], newId: number, session: Session): Promise<{
-    finalElementsForDb: StoredElement[];
-    mediaToSave: {
-        sourceUrl: string;
-        fileName: string;
-    }[];
-}>;
-export declare function handleFileUploads(ctx: Context, config: Config, fileManager: FileManager, logger: Logger, reviewManager: ReviewManager, cave: CaveObject, mediaToToSave: {
-    sourceUrl: string;
-    fileName: string;
-}[], reusableIds: Set<number>, session: Session, hashManager: HashManager, textHashesToStore: Omit<CaveHashObject, 'cave'>[]): Promise<void>;

package/lib/index.d.ts

@@ -1,53 +0,0 @@
-import { Context, Schema } from 'koishi';
-import { CaveHashObject } from './HashManager';
-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 StoredElement {
-    type: 'text' | 'image' | 'video' | 'audio' | 'file';
-    content?: string;
-    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;
-    }
-}
-export interface Config {
-    coolDown: number;
-    perChannel: boolean;
-    adminChannel: string;
-    enableProfile: boolean;
-    enableIO: boolean;
-    enableReview: boolean;
-    caveFormat: string;
-    enableSimilarity: boolean;
-    textThreshold: number;
-    imageWholeThreshold: number;
-    localPath?: string;
-    enableS3: boolean;
-    endpoint?: string;
-    region?: string;
-    accessKeyId?: string;
-    secretAccessKey?: string;
-    bucket?: string;
-    publicUrl?: string;
-}
-export declare const Config: Schema<Config>;
-export declare function apply(ctx: Context, config: Config): void;