koishi-plugin-best-cave 1.3.0 → 1.3.1

package/lib/index.d.ts

@@ -24,4 +24,5 @@ export interface Config {
     enablePagination: boolean;
     itemsPerPage: number;
     duplicateThreshold: number;
+    enableDuplicate: boolean;
 }

package/lib/index.js

@@ -33,14 +33,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/locales/zh-CN.yml
 var require_zh_CN = __commonJS({
   "src/locales/zh-CN.yml"(exports2, module2) {
-    module2.exports = { _config: { manager: "管理员", number: "冷却时间（秒）", enableAudit: "启用审核", imageMaxSize: "图片最大大小（MB）", duplicateThreshold: "图片相似度阈值（0-1）", allowVideo: "允许视频上传", videoMaxSize: "视频最大大小（MB）", enablePagination: "启用统计分页", itemsPerPage: "每页显示数目", blacklist: "黑名单（用户）", whitelist: "审核白名单（用户/群组/频道）" }, commands: { cave: { description: "回声洞", usage: "支持添加、抽取、查看、管理回声洞", examples: "使用 cave 随机抽取回声洞\n使用 -a 直接添加或引用添加\n使用 -g 查看指定回声洞\n使用 -r 删除指定回声洞", options: { a: "添加回声洞", g: "查看回声洞", r: "删除回声洞", p: "通过审核（批量）", d: "拒绝审核（批量）", l: "查询投稿统计" }, add: { noContent: "请在一分钟内发送内容", operationTimeout: "操作超时，添加取消", videoDisabled: "不允许上传视频", submitPending: "提交成功，序号为（{0}）", addSuccess: "添加成功，序号为（{0}）", mediaSizeExceeded: "{0}文件大小超过限制", localFileNotAllowed: "检测到本地文件路径，无法保存" }, remove: { noPermission: "你无权删除他人添加的回声洞", deletePending: "删除（待审核）", deleted: "已删除" }, list: { pageInfo: "第 {0} / {1} 页", header: "当前共有 {0} 项回声洞：", totalItems: "用户 {0} 共计投稿 {1} 项：", idsLine: "{0}" }, audit: { noPending: "暂无待审核回声洞", pendingNotFound: "未找到待审核回声洞", pendingResult: "{0}，剩余 {1} 个待审核回声洞：[{2}]", auditPassed: "已通过", auditRejected: "已拒绝", batchAuditResult: "已{0} {1}/{2} 项回声洞", title: "待审核回声洞：", from: "投稿人：", sendFailed: "发送审核消息失败，无法联系管理员 {0}" }, error: { noContent: "回声洞内容为空", getCave: "获取回声洞失败", noCave: "没有回声洞", invalidId: "请输入有效的回声洞ID", notFound: "未找到该回声洞", duplicateFound: "发现相似度为 {0}% 的" }, message: { blacklisted: "你已被列入黑名单", managerOnly: "此操作仅限管理员可用", cooldown: "群聊冷却中...请在 {0} 秒后重试", caveTitle: "回声洞 —— （{0}）", contributorSuffix: "—— {0}", mediaSizeExceeded: "{0}文件大小超过限制" } } } };
+    module2.exports = { _config: { manager: "管理员", number: "冷却时间（秒）", enableAudit: "启用审核", imageMaxSize: "图片最大大小（MB）", enableDuplicate: "启用图片查重", duplicateThreshold: "图片相似度阈值（0-1）", allowVideo: "允许视频上传", videoMaxSize: "视频最大大小（MB）", enablePagination: "启用统计分页", itemsPerPage: "每页显示数目", blacklist: "黑名单（用户）", whitelist: "审核白名单（用户/群组/频道）" }, commands: { cave: { description: "回声洞", usage: "支持添加、抽取、查看、管理回声洞", examples: "使用 cave 随机抽取回声洞\n使用 -a 直接添加或引用添加\n使用 -g 查看指定回声洞\n使用 -r 删除指定回声洞", options: { a: "添加回声洞", g: "查看回声洞", r: "删除回声洞", p: "通过审核（批量）", d: "拒绝审核（批量）", l: "查询投稿统计" }, add: { noContent: "请在一分钟内发送内容", operationTimeout: "操作超时，添加取消", videoDisabled: "不允许上传视频", submitPending: "提交成功，序号为（{0}）", addSuccess: "添加成功，序号为（{0}）", mediaSizeExceeded: "{0}文件大小超过限制", localFileNotAllowed: "检测到本地文件路径，无法保存" }, remove: { noPermission: "你无权删除他人添加的回声洞", deletePending: "删除（待审核）", deleted: "已删除" }, list: { pageInfo: "第 {0} / {1} 页", header: "当前共有 {0} 项回声洞：", totalItems: "用户 {0} 共计投稿 {1} 项：", idsLine: "{0}" }, audit: { noPending: "暂无待审核回声洞", pendingNotFound: "未找到待审核回声洞", pendingResult: "{0}，剩余 {1} 个待审核回声洞：[{2}]", auditPassed: "已通过", auditRejected: "已拒绝", batchAuditResult: "已{0} {1}/{2} 项回声洞", title: "待审核回声洞：", from: "投稿人：", sendFailed: "发送审核消息失败，无法联系管理员 {0}" }, error: { noContent: "回声洞内容为空", getCave: "获取回声洞失败", noCave: "没有回声洞", invalidId: "请输入有效的回声洞ID", notFound: "未找到该回声洞", exactDuplicateFound: "发现完全相同的", similarDuplicateFound: "发现相似度为 {0}% 的" }, message: { blacklisted: "你已被列入黑名单", managerOnly: "此操作仅限管理员可用", cooldown: "群聊冷却中...请在 {0} 秒后重试", caveTitle: "回声洞 —— （{0}）", contributorSuffix: "—— {0}", mediaSizeExceeded: "{0}文件大小超过限制" } } } };
   }
 });
 
 // src/locales/en-US.yml
 var require_en_US = __commonJS({
   "src/locales/en-US.yml"(exports2, module2) {
-    module2.exports = { _config: { manager: "Administrator", number: "Cooldown time (seconds)", enableAudit: "Enable moderation", imageMaxSize: "Maximum image size (MB)", duplicateThreshold: "Image similarity threshold (0-1)", allowVideo: "Allow video uploads", videoMaxSize: "Maximum video size (MB)", enablePagination: "Enable statistics pagination", itemsPerPage: "Items per page", blacklist: "Blacklist (users)", whitelist: "Moderation whitelist (users/groups/channels)" }, commands: { cave: { description: "Echo Cave", usage: "Support adding, drawing, viewing, and managing echo cave entries", examples: "Use cave to randomly draw an entry\nUse -a to add directly or by reference\nUse -g to view specific entry\nUse -r to delete specific entry", options: { a: "Add entry", g: "View entry", r: "Delete entry", p: "Approve submission (batch)", d: "Reject submission (batch)", l: "Check submission statistics" }, add: { noContent: "Please send content within one minute", operationTimeout: "Operation timeout, addition cancelled", videoDisabled: "Video uploads are not allowed", submitPending: "Submission successful, ID is ({0})", addSuccess: "Added successfully, ID is ({0})", mediaSizeExceeded: "{0} file size exceeds limit", localFileNotAllowed: "Local file path detected, cannot save" }, remove: { noPermission: "You don't have permission to delete others' entries", deletePending: "Delete (pending)", deleted: "Deleted" }, list: { pageInfo: "Page {0} / {1}", header: "Currently there are {0} entries:", totalItems: "User {0} has submitted {1} entries:", idsLine: "{0}" }, audit: { noPending: "No pending entries", pendingNotFound: "Pending entry not found", pendingResult: "{0}, {1} pending entries remaining: [{2}]", auditPassed: "Approved", auditRejected: "Rejected", batchAuditResult: "{0} {1}/{2} entries", title: "Pending entries:", from: "Submitted by:", sendFailed: "Failed to send moderation message, cannot contact administrator {0}" }, error: { noContent: "Entry content is empty", getCave: "Failed to get entry", noCave: "No entries available", invalidId: "Please enter a valid entry ID", notFound: "Entry not found", duplicateFound: "Found duplicate image with similarity of {0}%" }, message: { blacklisted: "You have been blacklisted", managerOnly: "This operation is for administrators only", cooldown: "Group chat cooldown... Please try again in {0} seconds", caveTitle: "Echo Cave —— ({0})", contributorSuffix: "—— {0}", mediaSizeExceeded: "{0} file size exceeds limit" } } } };
+    module2.exports = { _config: { manager: "Administrator", number: "Cooldown time (seconds)", enableAudit: "Enable moderation", imageMaxSize: "Maximum image size (MB)", enableDuplicate: "Enable image duplicate check", duplicateThreshold: "Image similarity threshold (0-1)", allowVideo: "Allow video upload", videoMaxSize: "Maximum video size (MB)", enablePagination: "Enable statistics pagination", itemsPerPage: "Items per page", blacklist: "Blacklist (users)", whitelist: "Moderation whitelist (users/groups/channels)" }, commands: { cave: { description: "Echo Cave", usage: "Support adding, drawing, viewing, and managing echo caves", examples: "Use cave to randomly draw an echo\nUse -a to add directly or add by reference\nUse -g to view specific echo\nUse -r to delete specific echo", options: { a: "Add echo", g: "View echo", r: "Delete echo", p: "Approve moderation (batch)", d: "Reject moderation (batch)", l: "Query submission statistics" }, add: { noContent: "Please send content within one minute", operationTimeout: "Operation timeout, addition cancelled", videoDisabled: "Video upload not allowed", submitPending: "Submission successful, ID is ({0})", addSuccess: "Added successfully, ID is ({0})", mediaSizeExceeded: "{0} file size exceeds limit", localFileNotAllowed: "Local file path detected, cannot save" }, remove: { noPermission: "You don't have permission to delete others' echos", deletePending: "Delete (pending review)", deleted: "Deleted" }, list: { pageInfo: "Page {0} / {1}", header: "Currently there are {0} echos:", totalItems: "User {0} has submitted {1} items:", idsLine: "{0}" }, audit: { noPending: "No pending echos for review", pendingNotFound: "Pending echo not found", pendingResult: "{0}, {1} pending echos remaining: [{2}]", auditPassed: "Approved", auditRejected: "Rejected", batchAuditResult: "{0} {1}/{2} echos", title: "Pending echos:", from: "Submitted by:", sendFailed: "Failed to send moderation message, cannot contact administrator {0}" }, error: { noContent: "Echo content is empty", getCave: "Failed to get echo", noCave: "No echos available", invalidId: "Please enter a valid echo ID", notFound: "Echo not found", exactDuplicateFound: "Found exactly identical", similarDuplicateFound: "Found {0}% similar" }, message: { blacklisted: "You have been blacklisted", managerOnly: "This operation is limited to administrators only", cooldown: "Group chat cooling down... Please try again in {0} seconds", caveTitle: "Echo Cave —— ({0})", contributorSuffix: "—— {0}", mediaSizeExceeded: "{0} file size exceeds limit" } } } };
   }
 });
 
@@ -70,14 +70,24 @@ var FileHandler = class {
   static RETRY_COUNT = 3;
   static RETRY_DELAY = 1e3;
   static CONCURRENCY_LIMIT = 5;
-  // 并发控制
+  /**
+   * 并发控制
+   * @param operation 要执行的操作
+   * @param limit 并发限制
+   * @returns 操作结果
+   */
   static async withConcurrencyLimit(operation, limit = this.CONCURRENCY_LIMIT) {
     while (this.locks.size >= limit) {
       await Promise.race(this.locks.values());
     }
     return operation();
   }
-  // 文件操作包装器
+  /**
+   * 文件操作包装器
+   * @param filePath 文件路径
+   * @param operation 要执行的操作
+   * @returns 操作结果
+   */
   static async withFileOp(filePath, operation) {
     const key = filePath;
     while (this.locks.has(key)) {
@@ -101,7 +111,11 @@ var FileHandler = class {
       this.locks.delete(key);
     }
   }
-  // 事务处理
+  /**
+   * 事务处理
+   * @param operations 要执行的操作数组
+   * @returns 操作结果数组
+   */
   static async withTransaction(operations) {
     const results = [];
     const completed = /* @__PURE__ */ new Set();
@@ -125,7 +139,11 @@ var FileHandler = class {
       throw error;
     }
   }
-  // JSON读写
+  /**
+   * 读取 JSON 数据
+   * @param filePath 文件路径
+   * @returns JSON 数据
+   */
   static async readJsonData(filePath) {
     return this.withFileOp(filePath, async () => {
       try {
@@ -136,6 +154,11 @@ var FileHandler = class {
       }
     });
   }
+  /**
+   * 写入 JSON 数据
+   * @param filePath 文件路径
+   * @param data 要写入的数据
+   */
   static async writeJsonData(filePath, data) {
     const tmpPath = `${filePath}.tmp`;
     await this.withFileOp(filePath, async () => {
@@ -143,7 +166,10 @@ var FileHandler = class {
       await fs.promises.rename(tmpPath, filePath);
     });
   }
-  // 目录和文件操作
+  /**
+   * 确保目录存在
+   * @param dir 目录路径
+   */
   static async ensureDirectory(dir) {
     await this.withConcurrencyLimit(async () => {
       if (!fs.existsSync(dir)) {
@@ -151,6 +177,10 @@ var FileHandler = class {
       }
     });
   }
+  /**
+   * 确保 JSON 文件存在
+   * @param filePath 文件路径
+   */
   static async ensureJsonFile(filePath) {
     await this.withFileOp(filePath, async () => {
       if (!fs.existsSync(filePath)) {
@@ -158,7 +188,11 @@ var FileHandler = class {
       }
     });
   }
-  // 媒体文件操作
+  /**
+   * 保存媒体文件
+   * @param filePath 文件路径
+   * @param data 文件数据
+   */
   static async saveMediaFile(filePath, data) {
     await this.withConcurrencyLimit(async () => {
       const dir = path.dirname(filePath);
@@ -169,6 +203,10 @@ var FileHandler = class {
       );
     });
   }
+  /**
+   * 删除媒体文件
+   * @param filePath 文件路径
+   */
   static async deleteMediaFile(filePath) {
     await this.withFileOp(filePath, async () => {
       if (fs.existsSync(filePath)) {
@@ -193,10 +231,20 @@ var IdManager = class {
   statusFilePath;
   stats = {};
   usedIds = /* @__PURE__ */ new Set();
+  /**
+   * 初始化ID管理器
+   * @param baseDir - 基础目录路径
+   */
   constructor(baseDir) {
     const caveDir = path2.join(baseDir, "data", "cave");
     this.statusFilePath = path2.join(caveDir, "status.json");
   }
+  /**
+   * 初始化ID管理系统
+   * @param caveFilePath - 正式回声洞数据文件路径
+   * @param pendingFilePath - 待处理回声洞数据文件路径
+   * @throws 当初始化失败时抛出错误
+   */
   async initialize(caveFilePath, pendingFilePath) {
     if (this.initialized) return;
     try {
@@ -252,6 +300,15 @@ var IdManager = class {
       throw error;
     }
   }
+  /**
+   * 处理ID冲突
+   * @param conflicts - ID冲突映射表
+   * @param caveFilePath - 正式回声洞数据文件路径
+   * @param pendingFilePath - 待处理回声洞数据文件路径
+   * @param caveData - 正式回声洞数据
+   * @param pendingData - 待处理回声洞数据
+   * @private
+   */
   async handleConflicts(conflicts, caveFilePath, pendingFilePath, caveData, pendingData) {
     logger2.warn(`Found ${conflicts.size} ID conflicts`);
     let modified = false;
@@ -276,6 +333,11 @@ var IdManager = class {
       logger2.success("ID conflicts resolved");
     }
   }
+  /**
+   * 获取下一个可用的ID
+   * @returns 下一个可用的ID
+   * @throws 当ID管理器未初始化时抛出错误
+   */
   getNextId() {
     if (!this.initialized) {
       throw new Error("IdManager not initialized");
@@ -296,6 +358,11 @@ var IdManager = class {
     );
     return nextId;
   }
+  /**
+   * 标记ID为已删除状态
+   * @param id - 要标记为删除的ID
+   * @throws 当ID管理器未初始化时抛出错误
+   */
   async markDeleted(id) {
     if (!this.initialized) {
       throw new Error("IdManager not initialized");
@@ -307,6 +374,11 @@ var IdManager = class {
     this.maxId = Math.max(maxUsedId, maxDeletedId);
     await this.saveStatus();
   }
+  /**
+   * 添加贡献统计
+   * @param contributorNumber - 贡献者编号
+   * @param caveId - 回声洞ID
+   */
   async addStat(contributorNumber, caveId) {
     if (contributorNumber === "10000") return;
     if (!this.stats[contributorNumber]) {
@@ -315,6 +387,11 @@ var IdManager = class {
     this.stats[contributorNumber].push(caveId);
     await this.saveStatus();
   }
+  /**
+   * 移除贡献统计
+   * @param contributorNumber - 贡献者编号
+   * @param caveId - 回声洞ID
+   */
   async removeStat(contributorNumber, caveId) {
     if (this.stats[contributorNumber]) {
       this.stats[contributorNumber] = this.stats[contributorNumber].filter((id) => id !== caveId);
@@ -324,9 +401,18 @@ var IdManager = class {
       await this.saveStatus();
     }
   }
+  /**
+   * 获取所有贡献统计信息
+   * @returns 贡献者编号到回声洞ID列表的映射
+   */
   getStats() {
     return this.stats;
   }
+  /**
+   * 保存当前状态到文件
+   * @private
+   * @throws 当保存失败时抛出错误
+   */
   async saveStatus() {
     try {
       const status = {
@@ -357,16 +443,25 @@ var ImageHasher = class {
     __name(this, "ImageHasher");
   }
   /**
-   * 计算图片哈希值
+   * 计算图片的感知哈希值
+   * @param imageBuffer - 图片的二进制数据
+   * @returns 返回64位的十六进制哈希字符串
+   * @throws 当图片处理失败时可能抛出错误
    */
   static async calculateHash(imageBuffer) {
     const { data } = await (0, import_sharp.default)(imageBuffer).grayscale().resize(32, 32, { fit: "fill" }).raw().toBuffer({ resolveWithObject: true });
-    const waveletMatrix = this.haarWaveletTransform(data, 32);
-    const features = this.extractFeatures(waveletMatrix, 32);
-    const mean = features.reduce((sum, val) => sum + val, 0) / features.length;
-    const binaryHash = features.map((val) => val > mean ? "1" : "0").join("");
+    const dctMatrix = this.computeDCT(data, 32);
+    const features = this.extractFeatures(dctMatrix, 32);
+    const median = this.calculateMedian(features);
+    const binaryHash = features.map((val) => val > median ? "1" : "0").join("");
     return this.binaryToHex(binaryHash);
   }
+  /**
+   * 将二进制字符串转换为十六进制
+   * @param binary - 二进制字符串
+   * @returns 十六进制字符串
+   * @private
+   */
   static binaryToHex(binary) {
     const hex = [];
     for (let i = 0; i < binary.length; i += 4) {
@@ -375,6 +470,12 @@ var ImageHasher = class {
     }
     return hex.join("");
   }
+  /**
+   * 将十六进制字符串转换为二进制
+   * @param hex - 十六进制字符串
+   * @returns 二进制字符串
+   * @private
+   */
   static hexToBinary(hex) {
     let binary = "";
     for (const char of hex) {
@@ -383,40 +484,64 @@ var ImageHasher = class {
     }
     return binary;
   }
-  static haarWaveletTransform(data, size) {
+  /**
+   * 计算图像的DCT(离散余弦变换)
+   * @param data - 图像数据
+   * @param size - 图像尺寸
+   * @returns DCT变换后的矩阵
+   * @private
+   */
+  static computeDCT(data, size) {
     const matrix = Array(size).fill(0).map(() => Array(size).fill(0));
+    const output = Array(size).fill(0).map(() => Array(size).fill(0));
     for (let i = 0; i < size; i++) {
       for (let j = 0; j < size; j++) {
         matrix[i][j] = data[i * size + j];
       }
     }
-    for (let i = 0; i < size; i++) {
-      this.haarTransform1D(matrix[i]);
-    }
-    for (let j = 0; j < size; j++) {
-      const col = matrix.map((row) => row[j]);
-      this.haarTransform1D(col);
-      for (let i = 0; i < size; i++) {
-        matrix[i][j] = col[i];
+    for (let u = 0; u < size; u++) {
+      for (let v = 0; v < size; v++) {
+        let sum = 0;
+        for (let x = 0; x < size; x++) {
+          for (let y = 0; y < size; y++) {
+            const cx = Math.cos((2 * x + 1) * u * Math.PI / (2 * size));
+            const cy = Math.cos((2 * y + 1) * v * Math.PI / (2 * size));
+            sum += matrix[x][y] * cx * cy;
+          }
+        }
+        output[u][v] = sum * this.getDCTCoefficient(u, size) * this.getDCTCoefficient(v, size);
       }
     }
-    return matrix;
+    return output;
   }
-  static haarTransform1D(arr) {
-    const len = arr.length;
-    const temp = new Array(len).fill(0);
-    for (let i = 0; i < len; i += 2) {
-      if (i + 1 < len) {
-        temp[i / 2] = (arr[i] + arr[i + 1]) / 2;
-        temp[len / 2 + i / 2] = (arr[i] - arr[i + 1]) / 2;
-      } else {
-        temp[i / 2] = arr[i];
-      }
-    }
-    for (let i = 0; i < len; i++) {
-      arr[i] = temp[i];
-    }
+  /**
+   * 获取DCT系数
+   * @param index - 索引值
+   * @param size - 矩阵大小
+   * @returns DCT系数
+   * @private
+   */
+  static getDCTCoefficient(index, size) {
+    return index === 0 ? Math.sqrt(1 / size) : Math.sqrt(2 / size);
   }
+  /**
+   * 计算数组的中位数
+   * @param arr - 输入数组
+   * @returns 中位数
+   * @private
+   */
+  static calculateMedian(arr) {
+    const sorted = [...arr].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+  }
+  /**
+   * 从DCT矩阵中提取特征值
+   * @param matrix - DCT矩阵
+   * @param size - 矩阵大小
+   * @returns 特征值数组
+   * @private
+   */
   static extractFeatures(matrix, size) {
     const features = [];
     const featureSize = 8;
@@ -428,7 +553,11 @@ var ImageHasher = class {
     return features;
   }
   /**
-   * 计算两个hash值的汉明距离
+   * 计算两个哈希值之间的汉明距离
+   * @param hash1 - 第一个哈希值
+   * @param hash2 - 第二个哈希值
+   * @returns 汉明距离
+   * @throws 当两个哈希值长度不等时抛出错误
    */
   static calculateDistance(hash1, hash2) {
     if (hash1.length !== hash2.length) {
@@ -443,14 +572,20 @@ var ImageHasher = class {
     return distance;
   }
   /**
-   * 计算图片相似度(0-1)
+   * 计算两个图片哈希值的相似度
+   * @param hash1 - 第一个哈希值
+   * @param hash2 - 第二个哈希值
+   * @returns 返回0-1之间的相似度值，1表示完全相同，0表示完全不同
    */
   static calculateSimilarity(hash1, hash2) {
     const distance = this.calculateDistance(hash1, hash2);
     return (64 - distance) / 64;
   }
   /**
-   * 批量比较图片相似度
+   * 批量比较一个新哈希值与多个已存在哈希值的相似度
+   * @param newHash - 新的哈希值
+   * @param existingHashes - 已存在的哈希值数组
+   * @returns 相似度数组，每个元素对应一个已存在哈希值的相似度
    */
   static batchCompareSimilarity(newHash, existingHashes) {
     return existingHashes.map((hash) => this.calculateSimilarity(newHash, hash));
@@ -462,6 +597,10 @@ var import_util = require("util");
 var logger3 = new import_koishi3.Logger("HashStorage");
 var readFileAsync = (0, import_util.promisify)(fs3.readFile);
 var HashStorage = class _HashStorage {
+  /**
+   * 初始化HashStorage实例
+   * @param caveDir 回声洞数据目录路径
+   */
   constructor(caveDir) {
     this.caveDir = caveDir;
   }
@@ -470,11 +609,11 @@ var HashStorage = class _HashStorage {
   }
   // 哈希数据文件名
   static HASH_FILE = "hash.json";
-  // 洞穴数据文件名
+  // 回声洞数据文件名
   static CAVE_FILE = "cave.json";
   // 批处理大小
   static BATCH_SIZE = 50;
-  // 存储洞穴ID到图片哈希值的映射
+  // 存储回声洞ID到图片哈希值的映射
   hashes = /* @__PURE__ */ new Map();
   // 初始化状态标志
   initialized = false;
@@ -487,6 +626,11 @@ var HashStorage = class _HashStorage {
   get caveFilePath() {
     return path3.join(this.caveDir, _HashStorage.CAVE_FILE);
   }
+  /**
+   * 初始化哈希存储
+   * 读取现有哈希数据或重新构建哈希值
+   * @throws 初始化失败时抛出错误
+   */
   async initialize() {
     if (this.initialized) return;
     try {
@@ -507,6 +651,10 @@ var HashStorage = class _HashStorage {
       throw error;
     }
   }
+  /**
+   * 获取当前哈希存储状态
+   * @returns 包含最后更新时间和所有条目的状态对象
+   */
   async getStatus() {
     if (!this.initialized) await this.initialize();
     return {
@@ -517,6 +665,11 @@ var HashStorage = class _HashStorage {
       }))
     };
   }
+  /**
+   * 更新指定回声洞的图片哈希值
+   * @param caveId 回声洞ID
+   * @param imgBuffers 图片buffer数组
+   */
   async updateCaveHash(caveId, imgBuffers) {
     if (!this.initialized) await this.initialize();
     try {
@@ -533,6 +686,10 @@ var HashStorage = class _HashStorage {
       logger3.error(`Failed to update hash (cave ${caveId}): ${error.message}`);
     }
   }
+  /**
+   * 更新所有回声洞的哈希值
+   * @param isInitialBuild 是否为初始构建
+   */
   async updateAllCaves(isInitialBuild = false) {
     if (!this.initialized && !isInitialBuild) {
       await this.initialize();
@@ -582,6 +739,12 @@ var HashStorage = class _HashStorage {
       throw error;
     }
   }
+  /**
+   * 查找重复的图片
+   * @param imgBuffers 待查找的图片buffer数组
+   * @param threshold 相似度阈值
+   * @returns 匹配结果数组，包含索引、回声洞ID和相似度
+   */
   async findDuplicates(imgBuffers, threshold) {
     if (!this.initialized) await this.initialize();
     const inputHashes = await Promise.all(
@@ -616,10 +779,19 @@ var HashStorage = class _HashStorage {
       })
     );
   }
+  /**
+   * 加载回声洞数据
+   * @returns 回声洞数据数组
+   * @private
+   */
   async loadCaveData() {
     const data = await FileHandler.readJsonData(this.caveFilePath);
     return Array.isArray(data) ? data.flat() : [];
   }
+  /**
+   * 保存哈希数据到文件
+   * @private
+   */
   async saveHashes() {
     const data = {
       hashes: Object.fromEntries(this.hashes),
@@ -627,6 +799,10 @@ var HashStorage = class _HashStorage {
     };
     await FileHandler.writeJsonData(this.filePath, [data]);
   }
+  /**
+   * 构建初始哈希数据
+   * @private
+   */
   async buildInitialHashes() {
     const caveData = await this.loadCaveData();
     let processedImageCount = 0;
@@ -663,6 +839,10 @@ var HashStorage = class _HashStorage {
     await this.saveHashes();
     logger3.success(`Build completed. Processed ${processedImageCount}/${totalImages} images`);
   }
+  /**
+   * 更新缺失的哈希值
+   * @private
+   */
   async updateMissingHashes() {
     const caveData = await this.loadCaveData();
     let updatedCount = 0;
@@ -695,6 +875,13 @@ var HashStorage = class _HashStorage {
       logger3.info(`Updated ${updatedCount} new hashes`);
     }
   }
+  /**
+   * 批量处理数组项
+   * @param items 待处理项数组
+   * @param processor 处理函数
+   * @param batchSize 批处理大小
+   * @private
+   */
   async processBatch(items, processor, batchSize = _HashStorage.BATCH_SIZE) {
     for (let i = 0; i < items.length; i += batchSize) {
       const batch = items.slice(i, i + batchSize);
@@ -723,6 +910,8 @@ var Config = import_koishi4.Schema.object({
   // 启用审核
   imageMaxSize: import_koishi4.Schema.number().default(4),
   // 图片大小限制(MB)
+  enableDuplicate: import_koishi4.Schema.boolean().default(true),
+  // 开启查重
   duplicateThreshold: import_koishi4.Schema.number().default(0.8),
   // 查重阈值(0-1)
   allowVideo: import_koishi4.Schema.boolean().default(true),
@@ -918,7 +1107,6 @@ async function apply(ctx, config) {
           type: "video",
           file: savedVideos[0],
           index: Number.MAX_SAFE_INTEGER
-          // 确保视频总是在最后
         });
       }
       const hashStorage2 = new HashStorage(path4.join(ctx2.baseDir, "data", "cave"));
@@ -1280,9 +1468,6 @@ async function saveMedia(urls, fileNames, resourceDir, caveId, mediaType, config
   const downloadTasks = urls.map(async (url, i) => {
     const fileName = fileNames[i];
     const ext = path4.extname(fileName || url) || (mediaType === "img" ? ".png" : ".mp4");
-    const baseName = path4.basename(fileName || "media", ext).replace(/[^\u4e00-\u9fa5a-zA-Z0-9]/g, "");
-    const finalFileName = `${caveId}_${baseName}${ext}`;
-    const filePath = path4.join(resourceDir, finalFileName);
     try {
       const response = await ctx.http(decodeURIComponent(url).replace(/&amp;/g, "&"), {
         method: "GET",
@@ -1295,31 +1480,55 @@ async function saveMedia(urls, fileNames, resourceDir, caveId, mediaType, config
         }
       });
       if (!response.data) throw new Error("empty_response");
+      const buffer = Buffer.from(response.data);
       if (mediaType === "img") {
-        const buffer = Buffer.from(response.data);
-        const result = await hashStorage.findDuplicates([buffer], config.duplicateThreshold);
-        if (result.length > 0 && result[0] !== null) {
-          const duplicate = result[0];
-          const similarity = duplicate.similarity;
-          if (similarity >= config.duplicateThreshold) {
+        const baseName = path4.basename(fileName || "md5", ext).replace(/[^\u4e00-\u9fa5a-zA-Z0-9]/g, "");
+        const files = await fs4.promises.readdir(resourceDir);
+        const duplicateFile = files.find((file) => file.startsWith(baseName + "_"));
+        if (duplicateFile) {
+          const duplicateCaveId = parseInt(duplicateFile.split("_")[1]);
+          if (!isNaN(duplicateCaveId)) {
             const caveFilePath = path4.join(ctx.baseDir, "data", "cave", "cave.json");
             const data = await FileHandler.readJsonData(caveFilePath);
-            const originalCave = data.find((item) => item.cave_id === duplicate.caveId);
+            const originalCave = data.find((item) => item.cave_id === duplicateCaveId);
             if (originalCave) {
-              const message = session.text(
-                "commands.cave.error.duplicateFound",
-                [(similarity * 100).toFixed(1)]
-              );
+              const message = session.text("commands.cave.error.exactDuplicateFound");
               await session.send(message + await buildMessage(originalCave, resourceDir, session));
               throw new Error("duplicate_found");
             }
           }
         }
+        if (config.enableDuplicate) {
+          const result = await hashStorage.findDuplicates([buffer], config.duplicateThreshold);
+          if (result.length > 0 && result[0] !== null) {
+            const duplicate = result[0];
+            const similarity = duplicate.similarity;
+            if (similarity >= config.duplicateThreshold) {
+              const caveFilePath = path4.join(ctx.baseDir, "data", "cave", "cave.json");
+              const data = await FileHandler.readJsonData(caveFilePath);
+              const originalCave = data.find((item) => item.cave_id === duplicate.caveId);
+              if (originalCave) {
+                const message = session.text(
+                  "commands.cave.error.similarDuplicateFound",
+                  [(similarity * 100).toFixed(1)]
+                );
+                await session.send(message + await buildMessage(originalCave, resourceDir, session));
+                throw new Error("duplicate_found");
+              }
+            }
+          }
+        }
+        const finalFileName = `${caveId}_${baseName}${ext}`;
+        const filePath = path4.join(resourceDir, finalFileName);
         await FileHandler.saveMediaFile(filePath, buffer);
+        return finalFileName;
       } else {
-        await FileHandler.saveMediaFile(filePath, Buffer.from(response.data));
+        const baseName = path4.basename(fileName || "video", ext).replace(/[^\u4e00-\u9fa5a-zA-Z0-9]/g, "");
+        const finalFileName = `${caveId}_${baseName}${ext}`;
+        const filePath = path4.join(resourceDir, finalFileName);
+        await FileHandler.saveMediaFile(filePath, buffer);
+        return finalFileName;
       }
-      return finalFileName;
     } catch (error) {
       if (error.message === "duplicate_found") {
         throw error;

package/lib/utils/HashStorage.d.ts

@@ -1,10 +1,19 @@
+/**
+ * 哈希存储状态信息
+ */
 interface HashStatus {
+    /** 最后更新时间戳 */
     lastUpdated: string;
+    /** 所有回声洞的哈希值条目 */
     entries: Array<{
         caveId: number;
         hashes: string[];
     }>;
 }
+/**
+ * 图片哈希值存储管理类
+ * 负责管理和维护回声洞图片的哈希值
+ */
 export declare class HashStorage {
     private readonly caveDir;
     private static readonly HASH_FILE;
@@ -12,23 +21,75 @@ export declare class HashStorage {
     private static readonly BATCH_SIZE;
     private hashes;
     private initialized;
+    /**
+     * 初始化HashStorage实例
+     * @param caveDir 回声洞数据目录路径
+     */
     constructor(caveDir: string);
     private get filePath();
     private get resourceDir();
     private get caveFilePath();
+    /**
+     * 初始化哈希存储
+     * 读取现有哈希数据或重新构建哈希值
+     * @throws 初始化失败时抛出错误
+     */
     initialize(): Promise<void>;
+    /**
+     * 获取当前哈希存储状态
+     * @returns 包含最后更新时间和所有条目的状态对象
+     */
     getStatus(): Promise<HashStatus>;
+    /**
+     * 更新指定回声洞的图片哈希值
+     * @param caveId 回声洞ID
+     * @param imgBuffers 图片buffer数组
+     */
     updateCaveHash(caveId: number, imgBuffers?: Buffer[]): Promise<void>;
+    /**
+     * 更新所有回声洞的哈希值
+     * @param isInitialBuild 是否为初始构建
+     */
     updateAllCaves(isInitialBuild?: boolean): Promise<void>;
+    /**
+     * 查找重复的图片
+     * @param imgBuffers 待查找的图片buffer数组
+     * @param threshold 相似度阈值
+     * @returns 匹配结果数组，包含索引、回声洞ID和相似度
+     */
     findDuplicates(imgBuffers: Buffer[], threshold: number): Promise<Array<{
         index: number;
         caveId: number;
         similarity: number;
     } | null>>;
+    /**
+     * 加载回声洞数据
+     * @returns 回声洞数据数组
+     * @private
+     */
     private loadCaveData;
+    /**
+     * 保存哈希数据到文件
+     * @private
+     */
     private saveHashes;
+    /**
+     * 构建初始哈希数据
+     * @private
+     */
     private buildInitialHashes;
+    /**
+     * 更新缺失的哈希值
+     * @private
+     */
     private updateMissingHashes;
+    /**
+     * 批量处理数组项
+     * @param items 待处理项数组
+     * @param processor 处理函数
+     * @param batchSize 批处理大小
+     * @private
+     */
     private processBatch;
 }
 export {};

package/lib/utils/ImageHasher.d.ts

@@ -1,27 +1,81 @@
 import { Buffer } from 'buffer';
 /**
- * 图片哈希计算
+ * 图片哈希计算工具类
+ * 使用 DCT(离散余弦变换)方法计算图片的感知哈希值，可用于图片相似度比较
  */
 export declare class ImageHasher {
     /**
-     * 计算图片哈希值
+     * 计算图片的感知哈希值
+     * @param imageBuffer - 图片的二进制数据
+     * @returns 返回64位的十六进制哈希字符串
+     * @throws 当图片处理失败时可能抛出错误
      */
     static calculateHash(imageBuffer: Buffer): Promise<string>;
+    /**
+     * 将二进制字符串转换为十六进制
+     * @param binary - 二进制字符串
+     * @returns 十六进制字符串
+     * @private
+     */
     private static binaryToHex;
+    /**
+     * 将十六进制字符串转换为二进制
+     * @param hex - 十六进制字符串
+     * @returns 二进制字符串
+     * @private
+     */
     private static hexToBinary;
-    private static haarWaveletTransform;
-    private static haarTransform1D;
+    /**
+     * 计算图像的DCT(离散余弦变换)
+     * @param data - 图像数据
+     * @param size - 图像尺寸
+     * @returns DCT变换后的矩阵
+     * @private
+     */
+    private static computeDCT;
+    /**
+     * 获取DCT系数
+     * @param index - 索引值
+     * @param size - 矩阵大小
+     * @returns DCT系数
+     * @private
+     */
+    private static getDCTCoefficient;
+    /**
+     * 计算数组的中位数
+     * @param arr - 输入数组
+     * @returns 中位数
+     * @private
+     */
+    private static calculateMedian;
+    /**
+     * 从DCT矩阵中提取特征值
+     * @param matrix - DCT矩阵
+     * @param size - 矩阵大小
+     * @returns 特征值数组
+     * @private
+     */
     private static extractFeatures;
     /**
-     * 计算两个hash值的汉明距离
+     * 计算两个哈希值之间的汉明距离
+     * @param hash1 - 第一个哈希值
+     * @param hash2 - 第二个哈希值
+     * @returns 汉明距离
+     * @throws 当两个哈希值长度不等时抛出错误
      */
     static calculateDistance(hash1: string, hash2: string): number;
     /**
-     * 计算图片相似度(0-1)
+     * 计算两个图片哈希值的相似度
+     * @param hash1 - 第一个哈希值
+     * @param hash2 - 第二个哈希值
+     * @returns 返回0-1之间的相似度值，1表示完全相同，0表示完全不同
      */
     static calculateSimilarity(hash1: string, hash2: string): number;
     /**
-     * 批量比较图片相似度
+     * 批量比较一个新哈希值与多个已存在哈希值的相似度
+     * @param newHash - 新的哈希值
+     * @param existingHashes - 已存在的哈希值数组
+     * @returns 相似度数组，每个元素对应一个已存在哈希值的相似度
      */
     static batchCompareSimilarity(newHash: string, existingHashes: string[]): number[];
 }

package/lib/utils/fileHandler.d.ts

@@ -3,17 +3,61 @@ export declare class FileHandler {
     private static readonly RETRY_COUNT;
     private static readonly RETRY_DELAY;
     private static readonly CONCURRENCY_LIMIT;
+    /**
+     * 并发控制
+     * @param operation 要执行的操作
+     * @param limit 并发限制
+     * @returns 操作结果
+     */
     private static withConcurrencyLimit;
+    /**
+     * 文件操作包装器
+     * @param filePath 文件路径
+     * @param operation 要执行的操作
+     * @returns 操作结果
+     */
     private static withFileOp;
+    /**
+     * 事务处理
+     * @param operations 要执行的操作数组
+     * @returns 操作结果数组
+     */
     static withTransaction<T>(operations: Array<{
         filePath: string;
         operation: () => Promise<T>;
         rollback?: () => Promise<void>;
     }>): Promise<T[]>;
+    /**
+     * 读取 JSON 数据
+     * @param filePath 文件路径
+     * @returns JSON 数据
+     */
     static readJsonData<T>(filePath: string): Promise<T[]>;
+    /**
+     * 写入 JSON 数据
+     * @param filePath 文件路径
+     * @param data 要写入的数据
+     */
     static writeJsonData<T>(filePath: string, data: T[]): Promise<void>;
+    /**
+     * 确保目录存在
+     * @param dir 目录路径
+     */
     static ensureDirectory(dir: string): Promise<void>;
+    /**
+     * 确保 JSON 文件存在
+     * @param filePath 文件路径
+     */
     static ensureJsonFile(filePath: string): Promise<void>;
+    /**
+     * 保存媒体文件
+     * @param filePath 文件路径
+     * @param data 文件数据
+     */
     static saveMediaFile(filePath: string, data: Buffer | string): Promise<void>;
+    /**
+     * 删除媒体文件
+     * @param filePath 文件路径
+     */
     static deleteMediaFile(filePath: string): Promise<void>;
 }

package/lib/utils/idManager.d.ts

@@ -1,3 +1,7 @@
+/**
+ * ID管理器类
+ * 负责管理回声洞ID的分配、删除和统计信息
+ */
 export declare class IdManager {
     private deletedIds;
     private maxId;
@@ -5,13 +9,61 @@ export declare class IdManager {
     private readonly statusFilePath;
     private stats;
     private usedIds;
+    /**
+     * 初始化ID管理器
+     * @param baseDir - 基础目录路径
+     */
     constructor(baseDir: string);
+    /**
+     * 初始化ID管理系统
+     * @param caveFilePath - 正式回声洞数据文件路径
+     * @param pendingFilePath - 待处理回声洞数据文件路径
+     * @throws 当初始化失败时抛出错误
+     */
     initialize(caveFilePath: string, pendingFilePath: string): Promise<void>;
+    /**
+     * 处理ID冲突
+     * @param conflicts - ID冲突映射表
+     * @param caveFilePath - 正式回声洞数据文件路径
+     * @param pendingFilePath - 待处理回声洞数据文件路径
+     * @param caveData - 正式回声洞数据
+     * @param pendingData - 待处理回声洞数据
+     * @private
+     */
     private handleConflicts;
+    /**
+     * 获取下一个可用的ID
+     * @returns 下一个可用的ID
+     * @throws 当ID管理器未初始化时抛出错误
+     */
     getNextId(): number;
+    /**
+     * 标记ID为已删除状态
+     * @param id - 要标记为删除的ID
+     * @throws 当ID管理器未初始化时抛出错误
+     */
     markDeleted(id: number): Promise<void>;
+    /**
+     * 添加贡献统计
+     * @param contributorNumber - 贡献者编号
+     * @param caveId - 回声洞ID
+     */
     addStat(contributorNumber: string, caveId: number): Promise<void>;
+    /**
+     * 移除贡献统计
+     * @param contributorNumber - 贡献者编号
+     * @param caveId - 回声洞ID
+     */
     removeStat(contributorNumber: string, caveId: number): Promise<void>;
+    /**
+     * 获取所有贡献统计信息
+     * @returns 贡献者编号到回声洞ID列表的映射
+     */
     getStats(): Record<string, number[]>;
+    /**
+     * 保存当前状态到文件
+     * @private
+     * @throws 当保存失败时抛出错误
+     */
     private saveStatus;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-best-cave",
   "description": "最好的 cave 插件，可开关的审核系统，可引用添加，支持图文混合内容，可查阅投稿列表，完美复刻你的 .cave 体验！",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],