koishi-plugin-best-cave 2.4.1 → 2.4.3

package/lib/DataManager.d.ts

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

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

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

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

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

@@ -37,15 +37,6 @@ export declare function getScopeQuery(session: Session, config: Config, includeS
  * @returns 可用的新 ID。
  */
 export declare function getNextCaveId(ctx: Context, 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 消息元素数组。

package/lib/index.d.ts

@@ -38,7 +38,6 @@ declare module 'koishi' {
     }
 }
 export interface Config {
-    coolDown: number;
     perChannel: boolean;
     adminChannel: string;
     enableName: boolean;

package/lib/index.js

@@ -239,8 +239,8 @@ var DataManager = class {
         return `操作失败: ${error.message}`;
       }
     }, "requireAdmin");
-    cave.subcommand(".export", "导出回声洞数据").action(requireAdmin(() => this.exportData()));
-    cave.subcommand(".import", "导入回声洞数据").action(requireAdmin(() => this.importData()));
+    cave.subcommand(".export", "导出回声洞数据").usage("将所有回声洞数据导出到 cave_export.json 中。").action(requireAdmin(() => this.exportData()));
+    cave.subcommand(".import", "导入回声洞数据").usage("从 cave_import.json 中导入回声洞数据。").action(requireAdmin(() => this.importData()));
   }
   /**
    * @description 导出所有 'active' 状态的回声洞数据到 `cave_export.json`。
@@ -399,20 +399,6 @@ async function getNextCaveId(ctx, reusableIds) {
   return newId;
 }
 __name(getNextCaveId, "getNextCaveId");
-function checkCooldown(session, config, lastUsed) {
-  const adminChannelId = config.adminChannel?.split(":")[1];
-  if (adminChannelId && session.channelId === adminChannelId) return null;
-  if (config.coolDown <= 0 || !session.channelId) return null;
-  const lastTime = lastUsed.get(session.channelId) || 0;
-  const remainingTime = lastTime + config.coolDown * 1e3 - Date.now();
-  if (remainingTime > 0) return `指令冷却中，请在 ${Math.ceil(remainingTime / 1e3)} 秒后重试`;
-  return null;
-}
-__name(checkCooldown, "checkCooldown");
-function updateCooldownTimestamp(session, config, lastUsed) {
-  if (config.coolDown > 0 && session.channelId) lastUsed.set(session.channelId, Date.now());
-}
-__name(updateCooldownTimestamp, "updateCooldownTimestamp");
 async function processMessageElements(sourceElements, newId, session, config, logger2) {
   const mediaToSave = [];
   let mediaIndex = 0;
@@ -506,7 +492,8 @@ async function handleFileUploads(ctx, config, fileManager, logger2, reviewManage
       }
     }
     await Promise.all(downloadedMedia.map((item) => fileManager.saveFile(item.fileName, item.buffer)));
-    const finalStatus = config.enablePend ? "pending" : "active";
+    const needsReview = config.enablePend && session.channelId !== config.adminChannel?.split(":")[1];
+    const finalStatus = needsReview ? "pending" : "active";
     await ctx.database.upsert("cave", [{ id: cave.id, status: finalStatus }]);
     if (hashManager) {
       const allHashesToInsert = [...textHashesToStore, ...imageHashesToStore].map((h4) => ({ ...h4, cave: cave.id }));
@@ -552,7 +539,7 @@ var PendManager = class {
       if (session.channelId !== this.config.adminChannel?.split(":")[1]) return "此指令仅限在管理群组中使用";
       return null;
     }, "requireAdmin");
-    const pend = cave.subcommand(".pend [id:posint]", "审核回声洞").action(async ({ session }, id) => {
+    const pend = cave.subcommand(".pend [id:posint]", "审核回声洞").usage("查询待审核的回声洞列表，或指定 ID 查看对应待审核的回声洞。").action(async ({ session }, id) => {
       const adminError = requireAdmin(session);
       if (adminError) return adminError;
       if (id) {
@@ -568,31 +555,29 @@ var PendManager = class {
       return `当前共有 ${pendingCaves.length} 条待审核回声洞，序号为：
 ${pendingCaves.map((c) => c.id).join("|")}`;
     });
-    const createPendAction = /* @__PURE__ */ __name((actionType) => async ({ session }, id) => {
+    const createPendAction = /* @__PURE__ */ __name((actionType) => async ({ session }, ...ids) => {
       const adminError = requireAdmin(session);
       if (adminError) return adminError;
+      if (ids.length === 0) return "请指定回声洞 ID";
       try {
         const targetStatus = actionType === "approve" ? "active" : "delete";
         const actionText = actionType === "approve" ? "通过" : "拒绝";
-        if (!id) {
-          const pendingCaves = await this.ctx.database.get("cave", { status: "pending" });
-          if (!pendingCaves.length) return `当前没有需要${actionText}的回声洞`;
-          await this.ctx.database.upsert("cave", pendingCaves.map((c) => ({ id: c.id, status: targetStatus })));
-          if (targetStatus === "delete") cleanupPendingDeletions(this.ctx, this.fileManager, this.logger, this.reusableIds);
-          return `已批量${actionText} ${pendingCaves.length} 条回声洞`;
-        }
-        const [cave2] = await this.ctx.database.get("cave", { id, status: "pending" });
-        if (!cave2) return `回声洞（${id}）无需审核`;
-        await this.ctx.database.upsert("cave", [{ id, status: targetStatus }]);
+        const cavesToProcess = await this.ctx.database.get("cave", {
+          id: { $in: ids },
+          status: "pending"
+        });
+        if (cavesToProcess.length === 0) return `回声洞（${ids.join("|")}）无需审核或不存在`;
+        const processedIds = cavesToProcess.map((cave2) => cave2.id);
+        await this.ctx.database.upsert("cave", processedIds.map((id) => ({ id, status: targetStatus })));
         if (targetStatus === "delete") cleanupPendingDeletions(this.ctx, this.fileManager, this.logger, this.reusableIds);
-        return `回声洞（${id}）已${actionText}`;
+        return `已${actionText}回声洞（${processedIds.join("|")}）`;
       } catch (error) {
         this.logger.error(`审核操作失败:`, error);
         return `操作失败: ${error.message}`;
       }
     }, "createPendAction");
-    pend.subcommand(".Y [id:posint]", "通过审核").action(createPendAction("approve"));
-    pend.subcommand(".N [id:posint]", "拒绝审核").action(createPendAction("reject"));
+    pend.subcommand(".Y [...ids:posint]", "通过审核").usage("通过一个或多个指定 ID 的回声洞审核。").action(createPendAction("approve"));
+    pend.subcommand(".N [...ids:posint]", "拒绝审核").usage("拒绝一个或多个指定 ID 的回声洞审核。").action(createPendAction("reject"));
   }
   /**
    * @description 将新回声洞提交到管理群组以供审核。
@@ -979,7 +964,6 @@ var usage = `
 var logger = new import_koishi3.Logger("best-cave");
 var Config = import_koishi3.Schema.intersect([
   import_koishi3.Schema.object({
-    coolDown: import_koishi3.Schema.number().default(10).description("冷却时间（秒）"),
     perChannel: import_koishi3.Schema.boolean().default(false).description("启用分群模式"),
     enableName: import_koishi3.Schema.boolean().default(false).description("启用自定义昵称"),
     enableIO: import_koishi3.Schema.boolean().default(false).description("启用导入导出"),
@@ -1014,7 +998,6 @@ function apply(ctx, config) {
     time: "timestamp"
   }, { primary: "id" });
   const fileManager = new FileManager(ctx.baseDir, config, logger);
-  const lastUsed = /* @__PURE__ */ new Map();
   const reusableIds = /* @__PURE__ */ new Set();
   const profileManager = config.enableName ? new NameManager(ctx) : null;
   const reviewManager = config.enablePend ? new PendManager(ctx, config, fileManager, logger, reusableIds) : null;
@@ -1025,15 +1008,12 @@ function apply(ctx, config) {
     if (options.view) return session.execute(`cave.view ${options.view}`);
     if (options.delete) return session.execute(`cave.del ${options.delete}`);
     if (options.list) return session.execute("cave.list");
-    const cdMessage = checkCooldown(session, config, lastUsed);
-    if (cdMessage) return cdMessage;
     try {
       const query = getScopeQuery(session, config);
       const candidates = await ctx.database.get("cave", query, { fields: ["id"] });
       if (!candidates.length) return `当前${config.perChannel && session.channelId ? "本群" : ""}还没有任何回声洞`;
       const randomId = candidates[Math.floor(Math.random() * candidates.length)].id;
       const [randomCave] = await ctx.database.get("cave", { ...query, id: randomId });
-      updateCooldownTimestamp(session, config, lastUsed);
       const messages = await buildCaveMessage(randomCave, config, fileManager, logger, session.platform);
       for (const message of messages) if (message.length > 0) await session.send(import_koishi3.h.normalize(message));
     } catch (error) {
@@ -1074,7 +1054,8 @@ function apply(ctx, config) {
       }
       const userName = (config.enableName ? await profileManager.getNickname(session.userId) : null) || session.username;
       const hasMedia = mediaToSave.length > 0;
-      const initialStatus = hasMedia ? "preload" : config.enablePend ? "pending" : "active";
+      const needsReview = config.enablePend && session.channelId !== config.adminChannel?.split(":")[1];
+      const initialStatus = hasMedia ? "preload" : needsReview ? "pending" : "active";
       const newCave = await ctx.database.create("cave", {
         id: newId,
         elements: finalElementsForDb,
@@ -1098,12 +1079,9 @@ function apply(ctx, config) {
   });
   cave.subcommand(".view <id:posint>", "查看指定回声洞").action(async ({ session }, id) => {
     if (!id) return "请输入要查看的回声洞序号";
-    const cdMessage = checkCooldown(session, config, lastUsed);
-    if (cdMessage) return cdMessage;
     try {
       const [targetCave] = await ctx.database.get("cave", { ...getScopeQuery(session, config), id });
       if (!targetCave) return `回声洞（${id}）不存在`;
-      updateCooldownTimestamp(session, config, lastUsed);
       const messages = await buildCaveMessage(targetCave, config, fileManager, logger, session.platform);
       for (const message of messages) if (message.length > 0) await session.send(import_koishi3.h.normalize(message));
     } catch (error) {

package/package.json

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

package/readme.md

@@ -40,8 +40,8 @@
 | `cave.name [昵称]` | `enableName: true` | 设置你在回声洞中显示的昵称。若不提供昵称，则清除现有设置。 |
 | `cave.pend` | `enablePend: true` | **(仅限管理群组)** 列出所有待审核的回声洞ID。 |
 | `cave.pend <序号>` | `enablePend: true` | **(仅限管理群组)** 查看指定待审核内容的详情。 |
-| `cave.pend.Y [序号]` | `enablePend: true` | **(仅限管理群组)** 通过审核。若不提供序号，则通过所有待审核内容。 |
-| `cave.pend.N [序号]` | `enablePend: true` | **(仅限管理群组)** 拒绝审核。若不提供序号，则拒绝所有待审核内容。 |
+| `cave.pend.Y [...序号]` | `enablePend: true` | **(仅限管理群组)** 通过审核。若不提供序号，则通过所有待审核内容。 |
+| `cave.pend.N [...序号]` | `enablePend: true` | **(仅限管理群组)** 拒绝审核。若不提供序号，则拒绝所有待审核内容。 |
 | `cave.export` | `enableIO: true` | **(仅限管理群组)** 将所有`active`状态的回声洞导出到 `cave_export.json`。 |
 | `cave.import` | `enableIO: true` | **(仅限管理群组)** 从 `cave_import.json` 文件中导入数据。 |
 | `cave.hash` | `enableSimilarity: true` | **(仅限管理群组)** 校验所有历史数据，为缺失哈希的回声洞补全记录。 |
@@ -53,7 +53,6 @@
 
 | 配置项 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
-| `coolDown` | `number` | `10` | `cave` 和 `cave.view` 指令的冷却时间（秒）。在管理群组中无冷却。 |
 | `perChannel` | `boolean` | `false` | 是否启用分群模式。`true` 表示各群的回声洞独立。 |
 | `enableName` | `boolean` | `false` | 是否启用自定义昵称功能 (`cave.name` 指令)。 |
 | `enableIO` | `boolean` | `false` | 是否启用数据导入/导出功能 (`cave.export` / `.import` 指令)。 |