koishi-plugin-best-cave 2.7.19 → 2.7.21

package/lib/HashManager.d.ts

@@ -0,0 +1,80 @@
+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 汉明距离。
+     */
+    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

@@ -0,0 +1,105 @@
+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 session 当前会话。
+ * @param config 插件配置。
+ * @returns 如果校验不通过，返回错误信息字符串；如果通过，返回 null。
+ */
+export declare function requireAdmin(session: Session, config: Config): string | null;
+/**
+ * @class DSU
+ * @description 一个通用的并查集（Disjoint Set Union）数据结构，用于高效地处理集合的合并与查找。
+ * 非常适合用于将相似或重复的项进行聚类。
+ */
+export declare class DSU {
+    private parent;
+    /**
+     * 查找元素的根节点，并进行路径压缩优化。
+     * @param i - 要查找的元素 ID。
+     * @returns 元素的根节点 ID。
+     */
+    find(i: number): number;
+    /**
+     * 合并两个元素所在的集合。
+     * @param i - 第一个元素。
+     * @param j - 第二个元素。
+     */
+    union(i: number, j: number): void;
+}
+/**
+ * @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>;

package/lib/index.js

@@ -487,25 +487,67 @@ async function performSimilarityChecks(ctx, config, hashManager, logger2, finalE
   }
 }
 __name(performSimilarityChecks, "performSimilarityChecks");
-async function handleFileUploads(ctx, config, fileManager, logger2, cave, downloadedMedia, reusableIds, needsReview) {
-  try {
-    await Promise.all(downloadedMedia.map((item) => fileManager.saveFile(item.fileName, item.buffer)));
-    const finalStatus = needsReview ? "pending" : "active";
-    await ctx.database.upsert("cave", [{ id: cave.id, status: finalStatus }]);
-    return finalStatus;
-  } catch (fileProcessingError) {
-    logger2.error(`回声洞（${cave.id}）文件处理失败:`, fileProcessingError);
-    await ctx.database.upsert("cave", [{ id: cave.id, status: "delete" }]);
-    cleanupPendingDeletions(ctx, config, fileManager, logger2, reusableIds);
-    throw fileProcessingError;
-  }
-}
-__name(handleFileUploads, "handleFileUploads");
 function requireAdmin(session, config) {
   if (session.cid !== config.adminChannel) return "此指令仅限在管理群组中使用";
   return null;
 }
 __name(requireAdmin, "requireAdmin");
+var DSU = class {
+  static {
+    __name(this, "DSU");
+  }
+  parent = /* @__PURE__ */ new Map();
+  /**
+   * 查找元素的根节点，并进行路径压缩优化。
+   * @param i - 要查找的元素 ID。
+   * @returns 元素的根节点 ID。
+   */
+  find(i) {
+    if (!this.parent.has(i)) {
+      this.parent.set(i, i);
+      return i;
+    }
+    if (this.parent.get(i) === i) return i;
+    const root = this.find(this.parent.get(i));
+    this.parent.set(i, root);
+    return root;
+  }
+  /**
+   * 合并两个元素所在的集合。
+   * @param i - 第一个元素。
+   * @param j - 第二个元素。
+   */
+  union(i, j) {
+    const rootI = this.find(i);
+    const rootJ = this.find(j);
+    if (rootI !== rootJ) this.parent.set(rootI, rootJ);
+  }
+};
+function generateFromLSH(items, getBucketInfo) {
+  const buckets = /* @__PURE__ */ new Map();
+  items.forEach((item) => {
+    const { id, keys } = getBucketInfo(item);
+    if (!id || !keys || keys.length === 0) return;
+    keys.forEach((key) => {
+      if (!buckets.has(key)) buckets.set(key, []);
+      buckets.get(key).push(id);
+    });
+  });
+  const candidatePairs = /* @__PURE__ */ new Set();
+  for (const ids of buckets.values()) {
+    if (ids.length < 2) continue;
+    const uniqueIds = [...new Set(ids)].sort((a, b) => a - b);
+    if (uniqueIds.length < 2) continue;
+    for (let i = 0; i < uniqueIds.length; i++) {
+      for (let j = i + 1; j < uniqueIds.length; j++) {
+        const pairKey = `${uniqueIds[i]}-${uniqueIds[j]}`;
+        candidatePairs.add(pairKey);
+      }
+    }
+  }
+  return candidatePairs;
+}
+__name(generateFromLSH, "generateFromLSH");
 
 // src/DataManager.ts
 var DataManager = class {
@@ -718,7 +760,7 @@ var HashManager = class {
     __name(this, "HashManager");
   }
   /**
-   * @description 注册与哈希功能相关的 `.hash` 和 `.check` 子命令。
+   * @description 注册与哈希功能相关的子命令。
    * @param cave - 主 `cave` 命令实例。
    */
   registerCommands(cave) {
@@ -788,48 +830,78 @@ var HashManager = class {
         const imageThreshold = options.imageThreshold ?? this.config.imageThreshold;
         const allHashes = await this.ctx.database.get("cave_hash", {});
         if (allHashes.length < 2) return "无可比较哈希";
-        const buckets = /* @__PURE__ */ new Map();
-        const hashLookup = /* @__PURE__ */ new Map();
-        for (const hashObj of allHashes) {
-          if (!hashLookup.has(hashObj.cave)) hashLookup.set(hashObj.cave, {});
-          hashLookup.get(hashObj.cave)[hashObj.type] = hashObj.hash;
+        const candidatePairs = generateFromLSH(allHashes, (hashObj) => {
           const binHash = BigInt("0x" + hashObj.hash).toString(2).padStart(64, "0");
+          const keys = [];
           for (let i = 0; i < 4; i++) {
             const band = binHash.substring(i * 16, (i + 1) * 16);
-            const bucketKey = `${hashObj.type}:${i}:${band}`;
-            if (!buckets.has(bucketKey)) buckets.set(bucketKey, []);
-            buckets.get(bucketKey).push(hashObj.cave);
+            keys.push(`${hashObj.type}:${i}:${band}`);
           }
-        }
-        const candidatePairs = /* @__PURE__ */ new Set();
-        const similarPairs = { text: /* @__PURE__ */ new Set(), image: /* @__PURE__ */ new Set() };
-        for (const ids of buckets.values()) {
-          if (ids.length < 2) continue;
-          for (let i = 0; i < ids.length; i++) {
-            for (let j = i + 1; j < ids.length; j++) {
-              const id1 = ids[i];
-              const id2 = ids[j];
-              const pairKey = [id1, id2].sort((a, b) => a - b).join("-");
-              if (candidatePairs.has(pairKey)) continue;
-              candidatePairs.add(pairKey);
-              const cave1Hashes = hashLookup.get(id1);
-              const cave2Hashes = hashLookup.get(id2);
-              if (cave1Hashes?.text && cave2Hashes?.text) {
-                const similarity = this.calculateSimilarity(cave1Hashes.text, cave2Hashes.text);
-                if (similarity >= textThreshold) similarPairs.text.add(`${id1} & ${id2} = ${similarity.toFixed(2)}%`);
-              }
-              if (cave1Hashes?.image && cave2Hashes?.image) {
-                const similarity = this.calculateSimilarity(cave1Hashes.image, cave2Hashes.image);
-                if (similarity >= imageThreshold) similarPairs.image.add(`${id1} & ${id2} = ${similarity.toFixed(2)}%`);
-              }
-            }
+          return { id: hashObj.cave, keys };
+        });
+        const hashLookup = /* @__PURE__ */ new Map();
+        allHashes.forEach((h4) => {
+          if (!hashLookup.has(h4.cave)) hashLookup.set(h4.cave, {});
+          hashLookup.get(h4.cave)[h4.type] = h4.hash;
+        });
+        const textPairs = [];
+        const imagePairs = [];
+        for (const pairKey of candidatePairs) {
+          const [id1, id2] = pairKey.split("-").map(Number);
+          const cave1Hashes = hashLookup.get(id1);
+          const cave2Hashes = hashLookup.get(id2);
+          if (cave1Hashes?.text && cave2Hashes?.text) {
+            const similarity = this.calculateSimilarity(cave1Hashes.text, cave2Hashes.text);
+            if (similarity >= textThreshold) textPairs.push({ id1, id2, similarity });
           }
+          if (cave1Hashes?.image && cave2Hashes?.image) {
+            const similarity = this.calculateSimilarity(cave1Hashes.image, cave2Hashes.image);
+            if (similarity >= imageThreshold) imagePairs.push({ id1, id2, similarity });
+          }
+        }
+        if (textPairs.length === 0 && imagePairs.length === 0) return "未发现高相似度的内容";
+        const generateReportForType = /* @__PURE__ */ __name((pairs) => {
+          if (pairs.length === 0) return { reportLines: [], clusters: [] };
+          const dsu = new DSU();
+          const allIds = /* @__PURE__ */ new Set();
+          pairs.forEach((p) => {
+            dsu.union(p.id1, p.id2);
+            allIds.add(p.id1);
+            allIds.add(p.id2);
+          });
+          const clusterMap = /* @__PURE__ */ new Map();
+          allIds.forEach((id) => {
+            const root = dsu.find(id);
+            if (!clusterMap.has(root)) clusterMap.set(root, []);
+            clusterMap.get(root).push(id);
+          });
+          const validClusters = Array.from(clusterMap.values()).filter((c) => c.length > 1);
+          const reportLines = [];
+          validClusters.forEach((cluster) => {
+            const sortedCluster = cluster.sort((a, b) => a - b);
+            const clusterPairs = pairs.filter((p) => cluster.includes(p.id1) && cluster.includes(p.id2)).sort((a, b) => b.similarity - a.similarity);
+            const scores = clusterPairs.map((p) => `${p.similarity.toFixed(2)}%`).join("/");
+            reportLines.push(`- ${sortedCluster.join("|")} = ${scores}`);
+          });
+          return { reportLines, clusters: validClusters };
+        }, "generateReportForType");
+        const textResult = generateReportForType(textPairs);
+        const imageResult = generateReportForType(imagePairs);
+        const totalClusters = textResult.clusters.length + imageResult.clusters.length;
+        if (totalClusters === 0) return "未发现高相似度的内容";
+        let report = `共发现 ${totalClusters} 组高相似度的内容:`;
+        if (textResult.reportLines.length > 0) {
+          report += `
+[文本相似]`;
+          report += `
+${textResult.reportLines.join("\n")}`;
+        }
+        if (imageResult.reportLines.length > 0) {
+          report += `
+[图片相似]`;
+          report += `
+${imageResult.reportLines.join("\n")}`;
         }
-        const totalFindings = similarPairs.text.size + similarPairs.image.size;
-        if (totalFindings === 0) return "未发现高相似度的内容";
-        let report = `已发现 ${totalFindings} 组高相似度的内容:`;
-        if (similarPairs.text.size > 0) report += "\n文本内容相似:\n" + [...similarPairs.text].join("\n");
-        if (similarPairs.image.size > 0) report += "\n图片内容相似:\n" + [...similarPairs.image].join("\n");
         return report.trim();
       } catch (error) {
         this.logger.error("检查相似度失败:", error);
@@ -1082,7 +1154,7 @@ var AIManager = class {
         if (cavesToAnalyze.length === 0) return "无需分析回声洞";
         await session.send(`开始分析 ${cavesToAnalyze.length} 个回声洞...`);
         let successCount = 0;
-        const batchSize = 10;
+        const batchSize = 25;
         for (let i = 0; i < cavesToAnalyze.length; i += batchSize) {
           const batch = cavesToAnalyze.slice(i, i + batchSize);
           this.logger.info(`[${i + 1}/${cavesToAnalyze.length}] 正在分析 ${batch.length} 条回声洞...`);
@@ -1104,27 +1176,42 @@ var AIManager = class {
       try {
         const allMeta = await this.ctx.database.get("cave_meta", {});
         if (allMeta.length < 2) return "无可比较数据";
+        const candidatePairs = generateFromLSH(allMeta, (meta) => ({ id: meta.cave, keys: meta.keywords }));
+        if (candidatePairs.size === 0) return "未发现相似内容";
         const allCaves = new Map((await this.ctx.database.get("cave", { status: "active" })).map((c) => [c.id, c]));
-        const foundPairs = /* @__PURE__ */ new Set();
-        const checkedPairs = /* @__PURE__ */ new Set();
-        for (let i = 0; i < allMeta.length; i++) {
-          for (let j = i + 1; j < allMeta.length; j++) {
-            const meta1 = allMeta[i];
-            const meta2 = allMeta[j];
-            const pairKey = [meta1.cave, meta2.cave].sort((a, b) => a - b).join("-");
-            if (checkedPairs.has(pairKey)) continue;
-            const similarity = this.calculateKeywordSimilarity(meta1.keywords, meta2.keywords);
-            if (similarity >= 80) {
-              const cave1 = allCaves.get(meta1.cave);
-              const cave2 = allCaves.get(meta2.cave);
-              if (cave1 && cave2 && await this.isContentDuplicateAI(cave1, cave2)) foundPairs.add(`${cave1.id} & ${cave2.id}`);
-              checkedPairs.add(pairKey);
-            }
-          }
-        }
-        if (foundPairs.size === 0) return "检查完成，未发现高重复性的内容。";
-        return `检查完成，共发现 ${foundPairs.size} 组可能重复的内容:
-${[...foundPairs].join("\n")}`;
+        const duplicatePairs = [];
+        const comparisonPromises = Array.from(candidatePairs).map(async (pairKey) => {
+          const [id1, id2] = pairKey.split("-").map(Number);
+          const cave1 = allCaves.get(id1);
+          const cave2 = allCaves.get(id2);
+          if (cave1 && cave2 && await this.isContentDuplicateAI(cave1, cave2)) return { id1, id2 };
+          return null;
+        });
+        const results = await Promise.all(comparisonPromises);
+        duplicatePairs.push(...results.filter(Boolean));
+        if (duplicatePairs.length === 0) return "未发现高重复性的内容";
+        const dsu = new DSU();
+        const allIds = /* @__PURE__ */ new Set();
+        duplicatePairs.forEach((p) => {
+          dsu.union(p.id1, p.id2);
+          allIds.add(p.id1);
+          allIds.add(p.id2);
+        });
+        const clusters = /* @__PURE__ */ new Map();
+        allIds.forEach((id) => {
+          const root = dsu.find(id);
+          if (!clusters.has(root)) clusters.set(root, []);
+          clusters.get(root).push(id);
+        });
+        const validClusters = Array.from(clusters.values()).filter((c) => c.length > 1);
+        if (validClusters.length === 0) return "未发现高重复性的内容";
+        let report = `共发现 ${validClusters.length} 组高重复性的内容:`;
+        validClusters.forEach((cluster) => {
+          const sortedCluster = cluster.sort((a, b) => a - b);
+          report += `
+- ${sortedCluster.join("|")}`;
+        });
+        return report;
       } catch (error) {
         this.logger.error("检查重复性失败:", error);
         return `检查失败: ${error.message}`;
@@ -1258,7 +1345,7 @@ ${combinedText}` }, ...images];
       "Content-Type": "application/json",
       "Authorization": `Bearer ${this.config.aiApiKey}`
     };
-    const response = await this.http.post(fullUrl, payload, { headers, timeout: 6e4 });
+    const response = await this.http.post(fullUrl, payload, { headers, timeout: 18e4 });
     const content = response?.choices?.[0]?.message?.content;
     if (typeof content !== "string" || !content.trim()) throw new Error();
     try {
@@ -1371,58 +1458,68 @@ function apply(ctx, config) {
     }
   });
   cave.subcommand(".add [content:text]", "添加回声洞").usage("添加一条回声洞。可直接发送内容，也可回复或引用消息。").action(async ({ session }, content) => {
-    try {
-      let sourceElements;
-      if (session.quote?.elements) {
-        sourceElements = session.quote.elements;
-      } else if (content?.trim()) {
-        sourceElements = import_koishi3.h.parse(content);
-      } else {
-        await session.send("请在一分钟内发送你要添加的内容");
-        const reply = await session.prompt(6e4);
-        if (!reply) return "等待操作超时";
-        sourceElements = import_koishi3.h.parse(reply);
-      }
-      const newId = await getNextCaveId(ctx, reusableIds);
-      const creationTime = /* @__PURE__ */ new Date();
-      const { finalElementsForDb, mediaToSave } = await processMessageElements(sourceElements, newId, session, creationTime);
-      if (finalElementsForDb.length === 0) return "无可添加内容";
-      const hasMedia = mediaToSave.length > 0;
-      const downloadedMedia = [];
-      if (hasMedia) {
-        for (const media of mediaToSave) {
-          const buffer = Buffer.from(await ctx.http.get(media.sourceUrl, { responseType: "arraybuffer", timeout: 3e4 }));
-          downloadedMedia.push({ fileName: media.fileName, buffer });
+    let sourceElements;
+    if (session.quote?.elements) {
+      sourceElements = session.quote.elements;
+    } else if (content?.trim()) {
+      sourceElements = import_koishi3.h.parse(content);
+    } else {
+      await session.send("请在一分钟内发送你要添加的内容");
+      const reply = await session.prompt(6e4);
+      if (!reply) return "等待操作超时";
+      sourceElements = import_koishi3.h.parse(reply);
+    }
+    const newId = await getNextCaveId(ctx, reusableIds);
+    const creationTime = /* @__PURE__ */ new Date();
+    const { finalElementsForDb, mediaToSave } = await processMessageElements(sourceElements, newId, session, creationTime);
+    if (finalElementsForDb.length === 0) return "无可添加内容";
+    const userName = (config.enableName ? await profileManager.getNickname(session.userId) : null) || session.username;
+    const needsReview = config.enablePend && session.cid !== config.adminChannel;
+    const finalStatus = needsReview ? "pending" : "active";
+    const newCave = await ctx.database.create("cave", {
+      id: newId,
+      elements: finalElementsForDb,
+      channelId: session.channelId,
+      userId: session.userId,
+      userName,
+      status: finalStatus,
+      time: creationTime
+    });
+    session.send(needsReview ? `提交成功，序号为（${newCave.id}）` : `添加成功，序号为（${newCave.id}）`);
+    (async () => {
+      try {
+        const hasMedia = mediaToSave.length > 0;
+        const downloadedMedia = [];
+        if (hasMedia) {
+          for (const media of mediaToSave) {
+            const buffer = Buffer.from(await ctx.http.get(media.sourceUrl, { responseType: "arraybuffer", timeout: 3e4 }));
+            downloadedMedia.push({ fileName: media.fileName, buffer });
+          }
+        }
+        let textHashesToStore = [];
+        let imageHashesToStore = [];
+        if (hashManager) {
+          for (const media of downloadedMedia) media.buffer = hashManager.sanitizeImageBuffer(media.buffer);
+          const checkResult = await performSimilarityChecks(ctx, config, hashManager, logger, finalElementsForDb, downloadedMedia);
+          if (checkResult.duplicate) {
+            await session.send(`回声洞（${newId}）添加失败：${checkResult.message}`);
+            await ctx.database.upsert("cave", [{ id: newId, status: "delete" }]);
+            await cleanupPendingDeletions(ctx, config, fileManager, logger, reusableIds);
+            return;
+          }
+          textHashesToStore = checkResult.textHashesToStore;
+          imageHashesToStore = checkResult.imageHashesToStore;
         }
-      }
-      let textHashesToStore = [];
-      let imageHashesToStore = [];
-      if (hashManager) {
-        for (const media of downloadedMedia) media.buffer = hashManager.sanitizeImageBuffer(media.buffer);
-        const checkResult = await performSimilarityChecks(ctx, config, hashManager, logger, finalElementsForDb, downloadedMedia);
-        if (checkResult.duplicate) return checkResult.message;
-        textHashesToStore = checkResult.textHashesToStore;
-        imageHashesToStore = checkResult.imageHashesToStore;
-      }
-      if (aiManager) {
-        const duplicateResult = await aiManager.checkForDuplicates(finalElementsForDb, downloadedMedia);
-        if (duplicateResult?.duplicate && duplicateResult.ids?.length > 0) return `内容与回声洞（${duplicateResult.ids.join("|")}）重复`;
-      }
-      const userName = (config.enableName ? await profileManager.getNickname(session.userId) : null) || session.username;
-      const needsReview = config.enablePend && session.cid !== config.adminChannel;
-      let finalStatus = hasMedia ? "preload" : needsReview ? "pending" : "active";
-      const newCave = await ctx.database.create("cave", {
-        id: newId,
-        elements: finalElementsForDb,
-        channelId: session.channelId,
-        userId: session.userId,
-        userName,
-        status: finalStatus,
-        time: creationTime
-      });
-      if (hasMedia) finalStatus = await handleFileUploads(ctx, config, fileManager, logger, newCave, downloadedMedia, reusableIds, needsReview);
-      if (finalStatus !== "preload") {
-        newCave.status = finalStatus;
+        if (aiManager) {
+          const duplicateResult = await aiManager.checkForDuplicates(finalElementsForDb, downloadedMedia);
+          if (duplicateResult?.duplicate && duplicateResult.ids?.length > 0) {
+            await session.send(`回声洞（${newId}）添加失败：内容与回声洞（${duplicateResult.ids.join("|")}）重复`);
+            await ctx.database.upsert("cave", [{ id: newId, status: "delete" }]);
+            await cleanupPendingDeletions(ctx, config, fileManager, logger, reusableIds);
+            return;
+          }
+        }
+        if (hasMedia) await Promise.all(downloadedMedia.map((item) => fileManager.saveFile(item.fileName, item.buffer)));
         if (aiManager) {
           const analyses = await aiManager.analyze([newCave], downloadedMedia);
           if (analyses.length > 0) await ctx.database.upsert("cave_meta", analyses);
@@ -1432,12 +1529,13 @@ function apply(ctx, config) {
           if (allHashesToInsert.length > 0) await ctx.database.upsert("cave_hash", allHashesToInsert);
         }
         if (finalStatus === "pending" && reviewManager) reviewManager.sendForPend(newCave);
+      } catch (error) {
+        logger.error(`回声洞（${newId}）处理失败:`, error);
+        await ctx.database.upsert("cave", [{ id: newId, status: "delete" }]);
+        await cleanupPendingDeletions(ctx, config, fileManager, logger, reusableIds);
+        await session.send(`回声洞（${newId}）处理失败: ${error.message}`);
       }
-      return needsReview ? `提交成功，序号为（${newCave.id}）` : `添加成功，序号为（${newCave.id}）`;
-    } catch (error) {
-      logger.error("添加回声洞失败:", error);
-      return "添加失败，请稍后再试";
-    }
+    })();
   });
   cave.subcommand(".view <id:posint>", "查看指定回声洞").action(async ({ session }, id) => {
     if (!id) return "请输入要查看的回声洞序号";

package/package.json

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

package/readme.md

@@ -2,24 +2,27 @@
 
 [![npm](https://img.shields.io/npm/v/koishi-plugin-best-cave?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-best-cave)
 
-功能强大、高度可定制的回声洞插件。支持丰富的媒体类型、内容查重、人工审核、用户昵称、数据迁移以及本地/S3 双重文件存储后端。
+功能强大、高度可定制的回声洞插件。支持丰富的媒体类型、内容查重、AI分析、人工审核、用户昵称、数据迁移以及本地/S3 双重文件存储后端。
 
 ## 🧩 前置依赖
 
 - **数据库 (`koishi-plugin-database`)**: 本插件强依赖数据库来存储数据，请确保您已至少配置了一个数据库插件（如 `koishi-plugin-database-sqlite` 或 `koishi-plugin-database-mysql`）。
 - **图片处理 (`sharp`)**: 如果您启用了 `enableSimilarity` (内容查重) 功能，插件需要使用 `sharp` 库来处理图片。通常情况下它会自动安装，如遇安装问题，请参考 `sharp` 的官方文档解决。
+- **AI 服务**: 如果您启用了 `enableAI` (AI 功能)，则需要一个兼容 OpenAI API 的服务提供商，并获取相应的 **Endpoint** 和 **API Key**。
 
 ## ✨ 功能亮点
 
-- **丰富的内容形式**：不止于文本，轻松发布包含图片、视频、音频甚至文件的混合内容。插件能自动解析回复或引用的消息，并将其完整存入回声洞。
+- **丰富的内容形式**：不止于文本，轻松发布包含图片、视频、音频、文件、合并转发的混合内容。插件能自动解析回复或引用的消息，并将其完整存入回声洞。
 - **灵活的存储后端**：媒体文件可存储在 **本地服务器** (`data/cave` 目录)，或配置使用任何 **S3 兼容** 的云端对象存储（如 AWS S3, MinIO, 阿里云 OSS, 腾讯云 COS 等）。支持通过公共URL、本地文件路径或Base64三种方式发送媒体。
-- **高级内容查重**：(可选) 启用后，插件会在添加时自动计算文本 (Simhash) 和图片 (pHash) 的哈希值。对于相似度过高的投稿将直接拒绝，有效防止重复。管理员还可通过维护工具找出局部相似或拼接的图片。
+- **AI 智能分析**：(可选) 启用后，插件能调用大语言模型对投稿内容进行智能分析，自动提取**关键词**、生成**一句话描述**并进行**趣味性评分**，为未来的内容检索和管理提供支持。
+- **高级内容查重**：(可选) 插件提供两种查重模式：
+  - **哈希查重**：在添加时自动计算文本 (Simhash) 和图片 (pHash) 的哈希值。对于相似度过高的投稿将直接拒绝，有效防止重复。
+  - **AI 语义查重**：在添加时利用 AI 模型判断新内容与现有内容在**语义或“梗”的本质上**是否重复，能识别各类变体和转述。
 - **完善的审核机制**：(可选) 启用后，所有新投稿都将进入待审核状态，并通知管理群组。只有管理员审核通过后，内容才会对用户可见，确保内容质量。
 - **精细的作用域**：通过 `perChannel` 配置，可设定回声洞是在所有群聊中共享（全局模式），还是在每个群聊中独立（分群模式）。
 - **专属用户昵称**：(可选) 用户可以为自己在回声洞中的发言设置一个专属昵称，增加趣味性。
 - **便捷的数据管理**：(可选) 管理员可通过指令轻松地将所有回声洞数据导出为 `JSON` 文件备份，或从文件中恢复数据，迁移无忧。
-- **强大的维护工具**：管理员可以通过 `cave.hash` 指令为历史数据批量生成哈希值，并通过 `cave.check` 获取一份所有内容的相似度报告。
-- **权限分离**：普通用户可删除自己的投稿。审核、数据管理等高级操作则仅限在指定的 **管理群组** 内由管理员执行。
+- **强大的维护工具**：管理员可以通过一系列指令为历史数据批量生成哈希值 (`cave.hash`)、补全 AI 分析 (`cave.ai`)、获取相似度报告 (`cave.check`) 或 AI 重复性报告 (`cave.compare`)。
 - **高效的ID管理**：优先复用已删除的ID，并在无可用ID时采用高效的“最大ID+1”策略，确保回声洞序号紧凑，并能高效处理大量数据。
 
 ## 📖 指令说明
@@ -29,28 +32,31 @@
 | 指令 | 别名/选项 | 说明 |
 | :--- | :--- | :--- |
 | `cave` | | 随机查看一条回声洞。 |
-| `cave.add [内容]` | `cave -a [内容]` | 添加新的回声洞。可以直接跟文字，也可以**回复一条带图片/视频的消息后发送 `cave.add`**，或等待机器人提示后发送。 |
+| `cave.add [内容]` | `cave -a [内容]` | 添加新的回声洞。可以直接跟文字，也可以**回复一条消息后发送 `cave.add`**，或等待机器人提示后发送。 |
 | `cave.view <序号>` | `cave -g <序号>` | 查看指定序号的回声洞。 |
 | `cave.del <序号>` | `cave -r <序号>` | 删除指定序号的回声洞。仅投稿人或在管理群组内的管理员可操作。 |
 | `cave.list` | `cave -l` | 查询并列出自己投稿过的所有回声洞序号及总数。 |
 | | `-u <用户>` | 查询指定用户（需@或使用ID）投稿的所有回声洞。 |
 | | `-a` | **(仅限管理群组)** 查看所有用户的投稿数量排行榜。 |
 
-### 模块化指令
+### 模块化管理指令
 
-这些指令只有在配置中启用了相应功能后才可用。
+这些指令只有在配置中启用了相应功能后才可用，且大部分仅限在**管理群组**中使用。
 
 | 指令 | 所需配置 | 说明 |
 | :--- | :--- | :--- |
-| `cave.name [昵称]` | `enableName: true` | 设置你在回声洞中显示的昵称。若不提供昵称，则清除现有设置。 |
-| `cave.pend` | `enablePend: true` | **(仅限管理群组)** 列出所有待审核的回声洞ID。 |
-| `cave.pend <序号>` | `enablePend: true` | **(仅限管理群组)** 查看指定待审核内容的详情。 |
-| `cave.pend.Y [...序号]` | `enablePend: true` | **(仅限管理群组)** 通过审核。若不提供序号，则通过所有待审核内容。 |
-| `cave.pend.N [...序号]` | `enablePend: true` | **(仅限管理群组)** 拒绝审核。若不提供序号，则拒绝所有待审核内容。 |
-| `cave.export` | `enableIO: true` | **(仅限管理群组)** 将所有`active`状态的回声洞导出到 `data/cave/cave_export.json`。 |
-| `cave.import` | `enableIO: true` | **(仅限管理群组)** 从 `data/cave/cave_import.json` 文件中导入数据。 |
-| `cave.hash` | `enableSimilarity: true` | **(仅限管理群组)** 校验所有历史数据，为缺失哈希的回声洞补全记录。 |
-| `cave.check` | `enableSimilarity: true` | **(仅限管理群组)** 检查所有回声洞的哈希，生成一份关于文本和图片相似度的报告。 |
+| `cave.name [昵称]` | `enableName: true` | **(用户指令)** 设置你在回声洞中显示的昵称。若不提供昵称，则清除现有设置。 |
+| `cave.pend` | `enablePend: true` | **(管理)** 列出所有待审核的回声洞ID。 |
+| `cave.pend <序号>` | `enablePend: true` | **(管理)** 查看指定待审核内容的详情。 |
+| `cave.pend.Y [...序号]` | `enablePend: true` | **(管理)** 通过审核。若不提供序号，则通过所有待审核内容。 |
+| `cave.pend.N [...序号]` | `enablePend: true` | **(管理)** 拒绝审核。若不提供序号，则拒绝所有待审核内容。 |
+| `cave.export` | `enableIO: true` | **(管理)** 将所有`active`状态的回声洞导出到 `data/cave/cave.json`。 |
+| `cave.import` | `enableIO: true` | **(管理)** 从 `data/cave/cave.json` 文件中导入数据。 |
+| `cave.hash` | `enableSimilarity: true` | **(管理)** 校验所有历史数据，为缺失哈希的回声洞补全记录。 |
+| `cave.check` | `enableSimilarity: true` | **(管理)** 检查所有回声洞的哈希，生成一份关于文本和图片相似度的报告。 |
+| `cave.fix [...序号]` | `enableSimilarity: true`| **(管理)** 扫描并修复回声洞中的图片（移除多余数据）。可指定ID或扫描全部。 |
+| `cave.ai` | `enableAI: true` | **(管理)** 分析所有历史数据，为缺失AI元数据的回声洞补全记录。 |
+| `cave.compare` | `enableAI: true` | **(管理)** 检查所有回声洞的AI关键词，生成一份关于内容重复性的报告。 |
 
 ## ⚙️ 配置说明
 
@@ -62,16 +68,25 @@
 | `enableName` | `boolean` | `false` | 是否启用自定义昵称功能 (`cave.name` 指令)。 |
 | `enableIO` | `boolean` | `false` | 是否启用数据导入/导出功能 (`cave.export` / `.import` 指令)。 |
 | `adminChannel` | `string` | `'onebot:'` | **管理群组ID**。格式为 `平台名:群号`，如 `onebot:12345678`。管理指令仅在此群组生效。若配置无效，审核将自动通过。 |
-| `caveFormat` | `string` | `'回声洞 ——（{id}）\|—— {*name}'` | 回声洞消息的显示格式。`\|`为页眉页脚分隔符。支持强大的占位符语法：• **基本**: `{id}`, `{name}`, `{time}`, `{user}`, `{channel}`• **自动打码**: `{*user}` (在占位符前加\*)• **审核可见**: `{/channel}` (在占位符前加/)• **组合**: `{*user/user}` (常规打码/审核时完整) |
+| `caveFormat` | `string` | `'回声洞 ——（{id}）\|—— {name}'` | 回声洞消息的显示格式。`\|`为页眉页脚分隔符。支持强大的占位符语法：• **基本**: `{id}`, `{name}`, `{time}`, `{user}`, `{channel}`• **自动打码**: `{*user}` (在占位符前加 `*`)• **审核可见**: `{name/}` (在 `/` 后留空，表示常规模式下不显示)• **审核替换**: `{user/name}` (常规模式显示 `user`，审核模式显示 `name`)• **组合**: `{*user/user}` (常规模式下打码显示 `user`，审核时完整显示 `user`) |
 
 ### 复核配置 (审核与查重)
 
 | 配置项 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
 | `enablePend` | `boolean` | `false` | 是否启用审核机制。启用后，新投稿将进入`pending`状态。 |
-| `enableSimilarity` | `boolean` | `false` | 是否启用内容相似度检查（查重）。 |
-| `textThreshold` | `number` | `90` | **文本**相似度阈值 (0-100)。基于Simhash汉明距离计算，超过此值将被拒绝。 |
-| `imageThreshold` | `number` | `90` | **图片整体**相似度阈值 (0-100)。基于pHash汉明距离计算，超过此值将被拒绝。 |
+| `enableSimilarity` | `boolean` | `false` | 是否启用基于哈希的内容相似度检查（查重）。 |
+| `textThreshold` | `number` | `95` | **文本**相似度阈值 (0-100)。基于Simhash汉明距离计算，超过此值将被拒绝。 |
+| `imageThreshold` | `number` | `95` | **图片**相似度阈值 (0-100)。基于pHash汉明距离计算，超过此值将被拒绝。 |
+
+### 模型配置 (AI)
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `enableAI` | `boolean` | `false` | 是否启用 AI 分析与查重功能。 |
+| `aiEndpoint` | `string` | `'https://api.siliconflow.cn/v1'` | **(AI 必填)** 兼容 OpenAI 的 API 端点 (Endpoint)。 |
+| `aiApiKey` | `string` | | **(AI 必填)** API 密钥 (Key)。 |
+| `aiModel` | `string` | `'THUDM/GLM-4.1V-9B-Thinking'` | **(AI 可选)** 使用的语言模型名称 (Model)。需为支持图片理解的多模态模型。 |
 
 ### 存储配置
 
@@ -93,6 +108,6 @@
     2. **本地文件路径**：如果 `localPath` 已配置。
     3. **Base64 编码**：如果以上两项均未配置，将文件转为 Base64 发送（可能受平台大小限制或支持问题）。
 2. **文件存储权限**：若使用本地存储，请确保 Koishi 拥有对 `data/cave` 目录的读写权限。若使用 S3，请确保 Access Key 权限和存储桶策略（如ACL设为`public-read`）配置正确。
-3. **异步删除**：删除操作（`cave.del` 或审核拒绝）会将内容状态标记为 `delete`，然后由后台任务异步清理关联的文件和数据库条目，以避免阻塞当前指令。
-4. **数据迁移**：导入功能会读取插件数据目录下的 `cave_import.json`。导出功能则会生成 `cave_export.json`。请在操作前放置或备份好相应文件。导入时，ID会从现有最大ID开始自增，不会覆盖或修改老数据。
-5. **查重机制**：图片查重在投稿时，仅基于**整图**的相似度进行判断和拒绝。插件还会为图片的四个象限生成哈希，但这些局部哈希仅用于 `cave.check` 指令生成相似度报告，供管理员识别拼接图、裁剪图等情况，**并不会在投稿时直接导致拒绝**。
+3. **异步处理**：投稿、删除等操作涉及文件下载、哈希计算、AI 分析和文件清理，这些耗时操作均在后台异步执行，以避免阻塞当前指令。您可能会先收到“添加成功”的消息，稍后才会收到查重失败或处理失败的提示。
+4. **数据迁移**：导入/导出功能均使用插件数据目录下的 `cave.json` 文件。导入时，若遇到与数据库中现有 ID 冲突的条目，该条目会被分配一个新的、当前最大的 ID 加一的序号，不会覆盖或修改老数据。
+5. **查重机制**：投稿时的查重是实时进行的，若相似度超过阈值会直接拒绝。而 `.check` 和 `.compare` 指令则用于对整个数据库进行批量扫描，生成全面的相似度/重复性报告，帮助管理员发现更复杂或历史遗留的重复内容。