koishi-plugin-best-cave 2.0.6 → 2.0.7

package/lib/DataManager.d.ts

@@ -2,7 +2,7 @@ import { Context, Logger } from 'koishi';
 import { FileManager } from './FileManager';
 import { Config } from './index';
 /**
- * 数据管理器 (DataManager)
+ * @class DataManager
  * @description
  * 负责处理回声洞数据的导入和导出功能。
  */
@@ -12,27 +12,26 @@ export declare class DataManager {
     private fileManager;
     private logger;
     /**
-     * 创建一个 DataManager 实例。
-     * @param ctx - Koishi 上下文，用于数据库操作。
-     * @param config - 插件配置。
-     * @param fileManager - 文件管理器实例，用于读写导入/导出文件。
-     * @param logger - 日志记录器实例。
+     * @constructor
+     * @param ctx Koishi 上下文，用于数据库操作。
+     * @param config 插件配置。
+     * @param fileManager 文件管理器实例。
+     * @param logger 日志记录器实例。
      */
     constructor(ctx: Context, config: Config, fileManager: FileManager, logger: Logger);
     /**
-     * 注册与数据导入导出相关的 `.export` 和 `.import` 子命令。
-     * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+     * @description 注册 `.export` 和 `.import` 子命令。
+     * @param cave - 主 `cave` 命令实例。
      */
     registerCommands(cave: any): void;
     /**
-     * 导出所有状态为 'active' 的回声洞数据。
-     * 数据将被序列化为 JSON 并保存到 `cave_export.json` 文件中。
-     * @returns 一个描述导出结果的字符串消息。
+     * @description 导出所有 'active' 状态的回声洞数据到 `cave_export.json`。
+     * @returns 描述导出结果的消息字符串。
      */
     exportData(): Promise<string>;
     /**
-     * 从 `cave_import.json` 文件导入回声洞数据。
-     * @returns 一个描述导入结果的字符串消息。
+     * @description 从 `cave_import.json` 文件导入回声洞数据。
+     * @returns 描述导入结果的消息字符串。
      */
     importData(): Promise<string>;
 }

package/lib/FileManager.d.ts

@@ -1,11 +1,11 @@
 import { Logger } from 'koishi';
 import { Config } from './index';
 /**
- * 文件管理器 (FileManager)
+ * @class FileManager
  * @description
- * 封装了对文件（资源）的存储、读取和删除操作。
- * 它能够根据插件配置自动选择使用本地文件系统或 AWS S3 作为存储后端。
- * 内置了基于 Promise 的文件锁，以防止对本地文件的并发写入冲突。
+ * 封装了对文件的存储、读取和删除操作。
+ * 能根据配置自动选择使用本地文件系统或 AWS S3 作为存储后端。
+ * 内置 Promise 文件锁，防止本地文件的并发写入冲突。
  */
 export declare class FileManager {
     private logger;
@@ -14,51 +14,36 @@ export declare class FileManager {
     private s3Client?;
     private s3Bucket?;
     /**
-     * 创建一个 FileManager 实例。
-     * @param baseDir - Koishi 应用的基础数据目录 (ctx.baseDir)。
-     * @param config - 插件的完整配置对象。
-     * @param logger - 日志记录器实例。
+     * @constructor
+     * @param baseDir Koishi 应用的基础数据目录 (ctx.baseDir)。
+     * @param config 插件的配置对象。
+     * @param logger 日志记录器实例。
      */
     constructor(baseDir: string, config: Config, logger: Logger);
     /**
-     * 确保本地资源目录存在。如果目录不存在，则会递归创建。
-     * 这是一个幂等操作。
-     * @private
-     */
-    private ensureDirectory;
-    /**
-     * 获取给定文件名的完整本地路径。
-     * @param fileName - 文件名。
-     * @returns 文件的绝对路径。
-     * @private
-     */
-    private getFullPath;
-    /**
-     * 使用文件锁来安全地执行一个异步文件操作。
-     * 这可以防止对同一文件的并发读写造成数据损坏。
-     * @template T - 异步操作的返回类型。
-     * @param fileName - 需要加锁的文件名。
-     * @param operation - 要执行的异步函数。
+     * @description 使用文件锁安全地执行异步文件操作，防止并发读写冲突。
+     * @template T 异步操作的返回类型。
+     * @param fullPath 需要加锁的文件的完整路径。
+     * @param operation 要执行的异步函数。
      * @returns 返回异步操作的结果。
-     * @private
      */
     private withLock;
     /**
-     * 保存文件，自动选择 S3 或本地存储。
-     * @param fileName - 文件名，将用作 S3 中的 Key 或本地文件名。
-     * @param data - 要写入的 Buffer 数据。
+     * @description 保存文件，自动选择 S3 或本地存储。
+     * @param fileName 用作 S3 Key 或本地文件名。
+     * @param data 要写入的 Buffer 数据。
      * @returns 返回保存时使用的文件名/标识符。
      */
     saveFile(fileName: string, data: Buffer): Promise<string>;
     /**
-     * 读取文件，自动从 S3 或本地存储读取。
-     * @param fileName - 要读取的文件名/标识符。
+     * @description 读取文件，自动从 S3 或本地存储读取。
+     * @param fileName 要读取的文件名/标识符。
      * @returns 文件的 Buffer 数据。
      */
     readFile(fileName: string): Promise<Buffer>;
     /**
-     * 删除文件，自动从 S3 或本地删除。
-     * @param fileIdentifier - 要删除的文件名/标识符。
+     * @description 删除文件，自动从 S3 或本地删除。
+     * @param fileIdentifier 要删除的文件名/标识符。
      */
     deleteFile(fileIdentifier: string): Promise<void>;
 }

package/lib/ProfileManager.d.ts

@@ -1,8 +1,8 @@
 import { Context } from 'koishi';
 /**
- * 数据库中 `cave_user` 表的记录结构。
- * @property userId - 用户的唯一 ID，作为主键。
- * @property nickname - 用户设置的自定义昵称。
+ * @description 数据库 `cave_user` 表的结构定义。
+ * @property userId 用户唯一ID，作为主键。
+ * @property nickname 用户自定义的昵称。
  */
 export interface UserProfile {
     userId: string;
@@ -14,38 +14,37 @@ declare module 'koishi' {
     }
 }
 /**
- * 个人资料管理器 (ProfileManager)
+ * @class ProfileManager
  * @description
- * 负责管理用户在回声洞插件中的自定义昵称。
- * 提供设置、获取和清除昵称的数据库操作和相关命令。
- * 此类仅在插件配置中启用了 `enableProfile` 时才会被实例化。
+ * 负责管理用户在回声洞中的自定义昵称。
+ * 当插件配置 `enableProfile` 为 true 时实例化。
  */
 export declare class ProfileManager {
     private ctx;
     /**
-     * 创建一个 ProfileManager 实例。
+     * @constructor
      * @param ctx - Koishi 上下文，用于初始化数据库模型。
      */
     constructor(ctx: Context);
     /**
-     * 注册与用户昵称相关的 `.profile` 子命令。
-     * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+     * @description 注册 `.profile` 子命令，用于管理用户昵称。
+     * @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。
+     * @returns 返回用户的昵称字符串，如果未设置则返回 null。
      */
     getNickname(userId: string): Promise<string | null>;
     /**
-     * 清除指定用户的昵称设置。
+     * @description 清除指定用户的昵称设置。
      * @param userId - 目标用户的 ID。
      */
     clearNickname(userId: string): Promise<void>;

package/lib/ReviewManager.d.ts

@@ -2,11 +2,10 @@ import { Context, h, Logger } from 'koishi';
 import { CaveObject, Config } from './index';
 import { FileManager } from './FileManager';
 /**
- * 审核管理器 (ReviewManager)
+ * @class ReviewManager
  * @description
- * 负责处理回声洞的审核流程。当 `enableReview` 配置项开启时，
- * 此管理器将被激活，用于处理新回声洞的提交、向管理员发送审核通知
- * 以及处理管理员的审核操作（通过/拒绝）。
+ * 负责处理回声洞的审核流程。当 `enableReview` 配置开启时，
+ * 此管理器将被激活，处理新洞的提交、审核通知和审核操作。
  */
 export declare class ReviewManager {
     private ctx;
@@ -14,35 +13,28 @@ export declare class ReviewManager {
     private fileManager;
     private logger;
     /**
-     * 创建一个 ReviewManager 实例。
-     * @param ctx - Koishi 上下文。
-     * @param config - 插件配置。
-     * @param fileManager - 文件管理器实例。
-     * @param logger - 日志记录器实例。
+     * @constructor
+     * @param ctx Koishi 上下文。
+     * @param config 插件配置。
+     * @param fileManager 文件管理器实例。
+     * @param logger 日志记录器实例。
      */
     constructor(ctx: Context, config: Config, fileManager: FileManager, logger: Logger);
     /**
-     * 注册与审核相关的 `.review` 子命令。
-     * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+     * @description 注册与审核相关的 `.review` 子命令。
+     * @param cave - 主 `cave` 命令实例。
      */
     registerCommands(cave: any): void;
     /**
-     * 将一条新的回声洞提交给所有管理员进行审核。
-     * @param cave - 新创建的、状态为 'pending' 的回声洞对象。
+     * @description 将新回声洞提交给管理员审核。
+     * @param cave 新创建的、状态为 'pending' 的回声洞对象。
      */
     sendForReview(cave: CaveObject): Promise<void>;
     /**
-     * 构建一条用于发送给管理员的、包含审核信息的消息。
-     * @param cave - 待审核的回声洞对象。
-     * @returns 一个可直接发送的消息数组。
-     * @private
-     */
-    private buildReviewMessage;
-    /**
-     * 处理管理员的审核决定（通过或拒绝）。
-     * @param action - 'approve' (通过) 或 'reject' (拒绝)。
-     * @param caveId - 被审核的回声洞 ID。
-     * @param adminUserName - 执行操作的管理员的昵称。
+     * @description 处理管理员的审核决定（通过或拒绝）。
+     * @param action 'approve' (通过) 或 'reject' (拒绝)。
+     * @param caveId 被审核的回声洞 ID。
+     * @param adminUserName 操作管理员的昵称。
      * @returns 返回给操作者的确认消息。
      */
     processReview(action: 'approve' | 'reject', caveId: number, adminUserName: string): Promise<string | (string | h)[]>;

package/lib/Utils.d.ts

@@ -2,78 +2,54 @@ import { Context, h, Logger, Session } from 'koishi';
 import { CaveObject, Config, StoredElement } from './index';
 import { FileManager } from './FileManager';
 /**
- * 将数据库中存储的 StoredElement[] 数组转换为 Koishi h() 元素数组。
- * @param elements - 从数据库读取的元素对象数组。
- * @returns 转换后的 h() 元素数组，用于消息发送。
+ * @description 将数据库存储的 StoredElement[] 转换为 Koishi 的 h() 元素数组。
+ * @param elements 从数据库读取的元素数组。
+ * @returns 转换后的 h() 元素数组。
  */
 export declare function storedFormatToHElements(elements: StoredElement[]): h[];
 /**
- * 将指向本地媒体文件的 h() 元素转换为内联 Base64 格式。
- * @param element - 包含本地文件路径的 h() 媒体元素。
- * @param fileManager - FileManager 实例，用于读取文件。
- * @param logger - Logger 实例，用于记录错误。
- * @returns 转换后的 h() 元素，其 src 属性为 Base64 数据 URI。
- */
-export declare function mediaElementToBase64(element: h, fileManager: FileManager, logger: Logger): Promise<h>;
-/**
- * 构建一条包含回声洞内容的完整消息，准备发送。
+ * @description 构建一条用于发送的完整回声洞消息。
  * 此函数会处理 S3 URL、文件映射路径或本地文件到 Base64 的转换。
- * @param cave - 要展示的回声洞对象。
- * @param config - 插件配置。
- * @param fileManager - FileManager 实例。
- * @param logger - Logger 实例。
- * @returns 一个包含 h() 元素和字符串的消息数组。
+ * @param cave 要展示的回声洞对象。
+ * @param config 插件配置。
+ * @param fileManager FileManager 实例。
+ * @param logger Logger 实例。
+ * @returns 包含 h() 元素和字符串的消息数组。
  */
 export declare function buildCaveMessage(cave: CaveObject, config: Config, fileManager: FileManager, logger: Logger): Promise<(string | h)[]>;
 /**
- * 清理数据库中所有被标记为 'delete' 状态的回声洞及其关联的文件。
- * @param ctx - Koishi 上下文。
- * @param fileManager - FileManager 实例，用于删除文件。
- * @param logger - Logger 实例。
+ * @description 清理数据库中所有被标记为 'delete' 状态的回声洞及其关联文件。
+ * @param ctx Koishi 上下文。
+ * @param fileManager FileManager 实例。
+ * @param logger Logger 实例。
  */
 export declare function cleanupPendingDeletions(ctx: Context, fileManager: FileManager, logger: Logger): Promise<void>;
 /**
- * 根据插件配置（是否分群）和当前会话，生成数据库查询所需的范围条件。
- * @param session - 当前会话对象。
- * @param config - 插件配置。
- * @returns 一个用于数据库查询的条件对象。
+ * @description 根据配置（是否分群）和当前会话，生成数据库查询的范围条件。
+ * @param session 当前会话对象。
+ * @param config 插件配置。
+ * @returns 用于数据库查询的条件对象。
  */
 export declare function getScopeQuery(session: Session, config: Config): object;
 /**
- * 获取下一个可用的回声洞 ID。
- * 策略是找到当前已存在的 ID 中最小的未使用正整数。
- * @param ctx - Koishi 上下文。
- * @param query - 查询回声洞的范围条件，用于分群模式。
- * @returns 一个可用的新 ID。
- * @performance 对于非常大的数据集，此函数可能会有性能瓶颈，因为它需要获取所有现有 ID。
+ * @description 获取下一个可用的回声洞 ID（最小的未使用正整数）。
+ * @param ctx Koishi 上下文。
+ * @param query 查询范围条件，用于分群模式。
+ * @returns 可用的新 ID。
+ * @performance 在大数据集下，此函数可能存在性能瓶颈，因为它需要获取所有现有ID。
  */
 export declare function getNextCaveId(ctx: Context, query?: object): Promise<number>;
 /**
- * 下载网络媒体资源并保存到文件存储中（本地或 S3）。
- * @param ctx - Koishi 上下文。
- * @param fileManager - FileManager 实例。
- * @param url - 媒体资源的 URL。
- * @param originalName - 原始文件名，用于获取扩展名。
- * @param type - 媒体类型 ('image', 'video', 'audio', 'file')。
- * @param caveId - 新建回声洞的 ID。
- * @param index - 媒体在消息中的索引。
- * @param channelId - 频道 ID。
- * @param userId - 用户 ID。
+ * @description 下载网络媒体资源并保存到文件存储中。
  * @returns 保存后的文件名/标识符。
  */
 export declare function downloadMedia(ctx: Context, fileManager: FileManager, url: string, originalName: string, type: string, caveId: number, index: number, channelId: string, userId: string): Promise<string>;
 /**
- * 检查用户在当前频道是否处于指令冷却状态。
- * @param session - 当前会话对象。
- * @param config - 插件配置。
- * @param lastUsed - 存储各频道最后使用时间的 Map。
- * @returns 如果处于冷却中，返回提示信息字符串；否则返回 null。
+ * @description 检查用户是否处于指令冷却中。
+ * @returns 若在冷却中则返回提示字符串，否则返回 null。
  */
 export declare function checkCooldown(session: Session, config: Config, lastUsed: Map<string, number>): string | null;
 /**
- * 更新指定频道的指令使用时间戳。
- * @param session - 当前会话对象。
- * @param config - 插件配置。
- * @param lastUsed - 存储各频道最后使用时间的 Map。
+ * @description 更新指定频道的指令使用时间戳。
  */
 export declare function updateCooldownTimestamp(session: Session, config: Config, lastUsed: Map<string, number>): void;

package/lib/index.d.ts

@@ -1,12 +1,9 @@
 import { Context, Schema } from 'koishi';
 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\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";
+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";
 /**
- * 存储在数据库中的单个消息元素。
- * @property type - 元素类型。
- * @property content - 文本内容，仅用于 'text' 类型。
- * @property file - 文件标识符（本地文件名或 S3 Key），用于媒体类型。
+ * @description 存储在数据库中的单个消息元素。
  */
 export interface StoredElement {
     type: 'text' | 'image' | 'video' | 'audio' | 'file';
@@ -14,14 +11,7 @@ export interface StoredElement {
     file?: string;
 }
 /**
- * 数据库中 `cave` 表的完整对象模型。
- * @property id - 回声洞的唯一数字 ID。
- * @property elements - 构成回声洞内容的元素数组。
- * @property channelId - 提交回声洞的频道 ID，若为私聊则为 null。
- * @property userId - 提交用户的 ID。
- * @property userName - 提交用户的昵称。
- * @property status - 回声洞状态: 'active' (活跃), 'delete' (待删除), 'pending' (待审核)。
- * @property time - 提交时间。
+ * @description 数据库 `cave` 表的完整对象模型。
  */
 export interface CaveObject {
     id: number;
@@ -37,9 +27,6 @@ declare module 'koishi' {
         cave: CaveObject;
     }
 }
-/**
- * 插件的配置接口。
- */
 export interface Config {
     coolDown: number;
     perChannel: boolean;
@@ -57,13 +44,5 @@ export interface Config {
     bucket?: string;
     publicUrl?: string;
 }
-/**
- * 使用 Koishi Schema 定义插件的配置项，用于生成配置界面。
- */
 export declare const Config: Schema<Config>;
-/**
- * 插件的入口函数。
- * @param ctx - Koishi 上下文。
- * @param config - 用户提供的插件配置。
- */
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_koishi2 = require("koishi");
+var path3 = __toESM(require("path"));
 
 // src/FileManager.ts
 var import_client_s3 = require("@aws-sdk/client-s3");
@@ -45,10 +46,10 @@ var fs = __toESM(require("fs/promises"));
 var path = __toESM(require("path"));
 var FileManager = class {
   /**
-   * 创建一个 FileManager 实例。
-   * @param baseDir - Koishi 应用的基础数据目录 (ctx.baseDir)。
-   * @param config - 插件的完整配置对象。
-   * @param logger - 日志记录器实例。
+   * @constructor
+   * @param baseDir Koishi 应用的基础数据目录 (ctx.baseDir)。
+   * @param config 插件的配置对象。
+   * @param logger 日志记录器实例。
    */
   constructor(baseDir, config, logger2) {
     this.logger = logger2;
@@ -68,47 +69,18 @@ var FileManager = class {
   static {
     __name(this, "FileManager");
   }
-  // 本地资源存储目录的绝对路径。
   resourceDir;
-  // 本地文件锁，键为文件绝对路径，值为一个 Promise，用于防止对同一文件的并发访问。
   locks = /* @__PURE__ */ new Map();
-  // S3 客户端实例，仅在启用 S3 时初始化。
   s3Client;
-  // S3 存储桶名称。
   s3Bucket;
   /**
-   * 确保本地资源目录存在。如果目录不存在，则会递归创建。
-   * 这是一个幂等操作。
-   * @private
-   */
-  async ensureDirectory() {
-    try {
-      await fs.mkdir(this.resourceDir, { recursive: true });
-    } catch (error) {
-      this.logger.error(`创建资源目录失败 ${this.resourceDir}:`, error);
-      throw error;
-    }
-  }
-  /**
-   * 获取给定文件名的完整本地路径。
-   * @param fileName - 文件名。
-   * @returns 文件的绝对路径。
-   * @private
-   */
-  getFullPath(fileName) {
-    return path.join(this.resourceDir, fileName);
-  }
-  /**
-   * 使用文件锁来安全地执行一个异步文件操作。
-   * 这可以防止对同一文件的并发读写造成数据损坏。
-   * @template T - 异步操作的返回类型。
-   * @param fileName - 需要加锁的文件名。
-   * @param operation - 要执行的异步函数。
+   * @description 使用文件锁安全地执行异步文件操作，防止并发读写冲突。
+   * @template T 异步操作的返回类型。
+   * @param fullPath 需要加锁的文件的完整路径。
+   * @param operation 要执行的异步函数。
    * @returns 返回异步操作的结果。
-   * @private
    */
-  async withLock(fileName, operation) {
-    const fullPath = this.getFullPath(fileName);
+  async withLock(fullPath, operation) {
     while (this.locks.has(fullPath)) {
       await this.locks.get(fullPath);
     }
@@ -119,9 +91,9 @@ var FileManager = class {
     return promise;
   }
   /**
-   * 保存文件，自动选择 S3 或本地存储。
-   * @param fileName - 文件名，将用作 S3 中的 Key 或本地文件名。
-   * @param data - 要写入的 Buffer 数据。
+   * @description 保存文件，自动选择 S3 或本地存储。
+   * @param fileName 用作 S3 Key 或本地文件名。
+   * @param data 要写入的 Buffer 数据。
    * @returns 返回保存时使用的文件名/标识符。
    */
   async saveFile(fileName, data) {
@@ -131,57 +103,52 @@ var FileManager = class {
         Key: fileName,
         Body: data,
         ACL: "public-read"
-        // 默认将文件权限设置为公开可读，方便通过 URL 访问。
+        // 默认为公开可读
       });
       await this.s3Client.send(command);
-      return fileName;
     } else {
-      await this.ensureDirectory();
-      const filePath = this.getFullPath(fileName);
-      await this.withLock(fileName, () => fs.writeFile(filePath, data));
-      return fileName;
+      await fs.mkdir(this.resourceDir, { recursive: true }).catch((error) => {
+        this.logger.error(`创建资源目录失败 ${this.resourceDir}:`, error);
+        throw error;
+      });
+      const filePath = path.join(this.resourceDir, fileName);
+      await this.withLock(filePath, () => fs.writeFile(filePath, data));
     }
+    return fileName;
   }
   /**
-   * 读取文件，自动从 S3 或本地存储读取。
-   * @param fileName - 要读取的文件名/标识符。
+   * @description 读取文件，自动从 S3 或本地存储读取。
+   * @param fileName 要读取的文件名/标识符。
    * @returns 文件的 Buffer 数据。
    */
   async readFile(fileName) {
     if (this.s3Client) {
-      const command = new import_client_s3.GetObjectCommand({
-        Bucket: this.s3Bucket,
-        Key: fileName
-      });
+      const command = new import_client_s3.GetObjectCommand({ Bucket: this.s3Bucket, Key: fileName });
       const response = await this.s3Client.send(command);
-      const byteArray = await response.Body.transformToByteArray();
-      return Buffer.from(byteArray);
+      return Buffer.from(await response.Body.transformToByteArray());
     } else {
-      const filePath = this.getFullPath(fileName);
-      return this.withLock(fileName, () => fs.readFile(filePath));
+      const filePath = path.join(this.resourceDir, fileName);
+      return this.withLock(filePath, () => fs.readFile(filePath));
     }
   }
   /**
-   * 删除文件，自动从 S3 或本地删除。
-   * @param fileIdentifier - 要删除的文件名/标识符。
+   * @description 删除文件，自动从 S3 或本地删除。
+   * @param fileIdentifier 要删除的文件名/标识符。
    */
   async deleteFile(fileIdentifier) {
     if (this.s3Client) {
-      const command = new import_client_s3.DeleteObjectCommand({
-        Bucket: this.s3Bucket,
-        Key: fileIdentifier
-      });
+      const command = new import_client_s3.DeleteObjectCommand({ Bucket: this.s3Bucket, Key: fileIdentifier });
       await this.s3Client.send(command).catch((err) => {
-        this.logger.warn(`删除文件 ${fileIdentifier} 失败:`, err);
+        this.logger.warn(`删除 S3 文件 ${fileIdentifier} 失败:`, err);
       });
     } else {
-      const filePath = this.getFullPath(fileIdentifier);
-      await this.withLock(fileIdentifier, async () => {
+      const filePath = path.join(this.resourceDir, fileIdentifier);
+      await this.withLock(filePath, async () => {
         try {
           await fs.unlink(filePath);
         } catch (error) {
           if (error.code !== "ENOENT") {
-            this.logger.warn(`删除文件 ${filePath} 失败:`, error);
+            this.logger.warn(`删除本地文件 ${filePath} 失败:`, error);
           }
         }
       });
@@ -192,7 +159,7 @@ var FileManager = class {
 // src/ProfileManager.ts
 var ProfileManager = class {
   /**
-   * 创建一个 ProfileManager 实例。
+   * @constructor
    * @param ctx - Koishi 上下文，用于初始化数据库模型。
    */
   constructor(ctx) {
@@ -204,49 +171,47 @@ var ProfileManager = class {
       // 用户自定义昵称
     }, {
       primary: "userId"
-      // 使用 userId 作为主键，确保每个用户只有一条昵称记录。
+      // 保证每个用户只有一条昵称记录。
     });
   }
   static {
     __name(this, "ProfileManager");
   }
   /**
-   * 注册与用户昵称相关的 `.profile` 子命令。
-   * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+   * @description 注册 `.profile` 子命令，用于管理用户昵称。
+   * @param cave - 主 `cave` 命令实例。
    */
   registerCommands(cave) {
-    cave.subcommand(".profile [nickname:text]", "设置显示昵称").usage("设置你在回声洞中显示的昵称。不提供昵称则清除记录。").action(async ({ session }, nickname) => {
+    cave.subcommand(".profile [nickname:text]", "设置显示昵称").usage("设置你在回声洞中显示的昵称。若不提供昵称，则清除现有昵称。").action(async ({ session }, nickname) => {
       const trimmedNickname = nickname?.trim();
-      if (!trimmedNickname) {
+      if (trimmedNickname) {
+        await this.setNickname(session.userId, trimmedNickname);
+        return `昵称已更新为：${trimmedNickname}`;
+      } else {
         await this.clearNickname(session.userId);
         return "昵称已清除";
       }
-      await this.setNickname(session.userId, trimmedNickname);
-      return `昵称已更新为：${trimmedNickname}`;
     });
   }
   /**
-   * 设置或更新指定用户的昵称。
+   * @description 设置或更新指定用户的昵称。
    * @param userId - 目标用户的 ID。
    * @param nickname - 要设置的新昵称。
    */
   async setNickname(userId, nickname) {
-    await this.ctx.database.upsert("cave_user", [{
-      userId,
-      nickname
-    }]);
+    await this.ctx.database.upsert("cave_user", [{ userId, nickname }]);
   }
   /**
-   * 获取指定用户的昵称。
+   * @description 获取指定用户的昵称。
    * @param userId - 目标用户的 ID。
-   * @returns 返回用户的昵称字符串。如果用户未设置昵称，则返回 null。
+   * @returns 返回用户的昵称字符串，如果未设置则返回 null。
    */
   async getNickname(userId) {
-    const profiles = await this.ctx.database.get("cave_user", { userId });
-    return profiles[0]?.nickname || null;
+    const profile = await this.ctx.database.get("cave_user", { userId });
+    return profile[0]?.nickname ?? null;
   }
   /**
-   * 清除指定用户的昵称设置。
+   * @description 清除指定用户的昵称设置。
    * @param userId - 目标用户的 ID。
    */
   async clearNickname(userId) {
@@ -257,78 +222,46 @@ var ProfileManager = class {
 // src/Utils.ts
 var import_koishi = require("koishi");
 var path2 = __toESM(require("path"));
-var mimeTypeMap = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".mp4": "video/mp4",
-  ".mp3": "audio/mpeg",
-  ".webp": "image/webp"
-};
+var mimeTypeMap = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".mp4": "video/mp4", ".mp3": "audio/mpeg", ".webp": "image/webp" };
 function storedFormatToHElements(elements) {
   return elements.map((el) => {
-    switch (el.type) {
-      case "text":
-        return import_koishi.h.text(el.content);
-      case "image":
-      case "video":
-      case "audio":
-      case "file":
-        return (0, import_koishi.h)(el.type, { src: el.file });
-      default:
-        return null;
-    }
+    if (el.type === "text") return import_koishi.h.text(el.content);
+    if (["image", "video", "audio", "file"].includes(el.type)) return (0, import_koishi.h)(el.type, { src: el.file });
+    return null;
   }).filter(Boolean);
 }
 __name(storedFormatToHElements, "storedFormatToHElements");
-async function mediaElementToBase64(element, fileManager, logger2) {
-  const fileName = element.attrs.src;
-  try {
-    const data = await fileManager.readFile(fileName);
-    const ext = path2.extname(fileName).toLowerCase();
-    const mimeType = mimeTypeMap[ext] || "application/octet-stream";
-    return (0, import_koishi.h)(element.type, { ...element.attrs, src: `data:${mimeType};base64,${data.toString("base64")}` });
-  } catch (error) {
-    logger2.warn(`转换本地文件 ${fileName} 为 Base64 失败:`, error);
-    return (0, import_koishi.h)("p", {}, `[${element.type}]`);
-  }
-}
-__name(mediaElementToBase64, "mediaElementToBase64");
 async function buildCaveMessage(cave, config, fileManager, logger2) {
   const caveHElements = storedFormatToHElements(cave.elements);
-  const processedElements = await Promise.all(caveHElements.map((element) => {
+  const processedElements = await Promise.all(caveHElements.map(async (element) => {
     const isMedia = ["image", "video", "audio", "file"].includes(element.type);
     const fileName = element.attrs.src;
-    if (!isMedia || !fileName) {
-      return Promise.resolve(element);
-    }
+    if (!isMedia || !fileName) return element;
     if (config.enableS3 && config.publicUrl) {
       const fullUrl = config.publicUrl.endsWith("/") ? `${config.publicUrl}${fileName}` : `${config.publicUrl}/${fileName}`;
-      return Promise.resolve((0, import_koishi.h)(element.type, { ...element.attrs, src: fullUrl }));
+      return (0, import_koishi.h)(element.type, { ...element.attrs, src: fullUrl });
     }
     if (config.localPath) {
-      const mappedPath = path2.join(config.localPath, fileName);
-      const fileUri = `file://${mappedPath}`;
-      return Promise.resolve((0, import_koishi.h)(element.type, { ...element.attrs, src: fileUri }));
+      const fileUri = `file://${path2.join(config.localPath, fileName)}`;
+      return (0, import_koishi.h)(element.type, { ...element.attrs, src: fileUri });
+    }
+    try {
+      const data = await fileManager.readFile(fileName);
+      const ext = path2.extname(fileName).toLowerCase();
+      const mimeType = mimeTypeMap[ext] || "application/octet-stream";
+      return (0, import_koishi.h)(element.type, { ...element.attrs, src: `data:${mimeType};base64,${data.toString("base64")}` });
+    } catch (error) {
+      logger2.warn(`转换文件 ${fileName} 为 Base64 失败:`, error);
+      return (0, import_koishi.h)("p", {}, `[${element.type}]`);
     }
-    return mediaElementToBase64(element, fileManager, logger2);
   }));
   const finalMessage = [];
-  const formatString = config.caveFormat;
-  const separatorIndex = formatString.indexOf("|");
-  let headerFormat, footerFormat;
-  if (separatorIndex === -1) {
-    headerFormat = formatString;
-    footerFormat = "";
-  } else {
-    headerFormat = formatString.substring(0, separatorIndex);
-    footerFormat = formatString.substring(separatorIndex + 1);
-  }
-  const headerText = headerFormat.replace("{id}", cave.id.toString()).replace("{name}", cave.userName);
+  const [headerFormat, footerFormat = ""] = config.caveFormat.split("|");
+  const replacements = { id: cave.id.toString(), name: cave.userName };
+  const headerText = headerFormat.replace(/\{id\}|\{name\}/g, (match) => replacements[match.slice(1, -1)]);
   if (headerText.trim()) finalMessage.push(headerText);
   finalMessage.push(...processedElements);
-  const footerText = footerFormat.replace("{id}", cave.id.toString()).replace("{name}", cave.userName);
+  const footerText = footerFormat.replace(/\{id\}|\{name\}/g, (match) => replacements[match.slice(1, -1)]);
   if (footerText.trim()) finalMessage.push(footerText);
   return finalMessage;
 }
@@ -336,7 +269,7 @@ __name(buildCaveMessage, "buildCaveMessage");
 async function cleanupPendingDeletions(ctx, fileManager, logger2) {
   try {
     const cavesToDelete = await ctx.database.get("cave", { status: "delete" });
-    if (cavesToDelete.length === 0) return;
+    if (!cavesToDelete.length) return;
     for (const cave of cavesToDelete) {
       const deletePromises = cave.elements.filter((el) => el.file).map((el) => fileManager.deleteFile(el.file));
       await Promise.all(deletePromises);
@@ -349,15 +282,12 @@ async function cleanupPendingDeletions(ctx, fileManager, logger2) {
 __name(cleanupPendingDeletions, "cleanupPendingDeletions");
 function getScopeQuery(session, config) {
   const baseQuery = { status: "active" };
-  if (config.perChannel && session.channelId) {
-    return { ...baseQuery, channelId: session.channelId };
-  }
-  return baseQuery;
+  return config.perChannel && session.channelId ? { ...baseQuery, channelId: session.channelId } : baseQuery;
 }
 __name(getScopeQuery, "getScopeQuery");
 async function getNextCaveId(ctx, query = {}) {
-  const allCaves = await ctx.database.get("cave", query, { fields: ["id"] });
-  const existingIds = new Set(allCaves.map((c) => c.id));
+  const allCaveIds = (await ctx.database.get("cave", query, { fields: ["id"] })).map((c) => c.id);
+  const existingIds = new Set(allCaveIds);
   let newId = 1;
   while (existingIds.has(newId)) {
     newId++;
@@ -365,19 +295,8 @@ async function getNextCaveId(ctx, query = {}) {
   return newId;
 }
 __name(getNextCaveId, "getNextCaveId");
-async function downloadMedia(ctx, fileManager, url, originalName, type, caveId, index, channelId, userId) {
-  const defaultExtMap = { "image": ".jpg", "video": ".mp4", "audio": ".mp3", "file": ".dat" };
-  const ext = originalName ? path2.extname(originalName) : "";
-  const finalExt = ext || defaultExtMap[type] || ".dat";
-  const fileName = `${caveId}_${index}_${channelId}_${userId}${finalExt}`;
-  const response = await ctx.http.get(url, { responseType: "arraybuffer", timeout: 3e4 });
-  return fileManager.saveFile(fileName, Buffer.from(response));
-}
-__name(downloadMedia, "downloadMedia");
 function checkCooldown(session, config, lastUsed) {
-  if (config.coolDown <= 0 || !session.channelId || config.adminUsers.includes(session.userId)) {
-    return null;
-  }
+  if (config.coolDown <= 0 || !session.channelId || config.adminUsers.includes(session.userId)) return null;
   const now = Date.now();
   const lastTime = lastUsed.get(session.channelId) || 0;
   if (now - lastTime < config.coolDown * 1e3) {
@@ -397,11 +316,11 @@ __name(updateCooldownTimestamp, "updateCooldownTimestamp");
 // src/DataManager.ts
 var DataManager = class {
   /**
-   * 创建一个 DataManager 实例。
-   * @param ctx - Koishi 上下文，用于数据库操作。
-   * @param config - 插件配置。
-   * @param fileManager - 文件管理器实例，用于读写导入/导出文件。
-   * @param logger - 日志记录器实例。
+   * @constructor
+   * @param ctx Koishi 上下文，用于数据库操作。
+   * @param config 插件配置。
+   * @param fileManager 文件管理器实例。
+   * @param logger 日志记录器实例。
    */
   constructor(ctx, config, fileManager, logger2) {
     this.ctx = ctx;
@@ -413,16 +332,15 @@ var DataManager = class {
     __name(this, "DataManager");
   }
   /**
-   * 注册与数据导入导出相关的 `.export` 和 `.import` 子命令。
-   * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+   * @description 注册 `.export` 和 `.import` 子命令。
+   * @param cave - 主 `cave` 命令实例。
    */
   registerCommands(cave) {
     cave.subcommand(".export", "导出回声洞数据").usage("将所有回声洞数据导出到 cave_export.json。").action(async ({ session }) => {
       if (!this.config.adminUsers.includes(session.userId)) return "抱歉，你没有权限导出数据";
       try {
         await session.send("正在导出数据，请稍候...");
-        const resultMessage = await this.exportData();
-        return resultMessage;
+        return await this.exportData();
       } catch (error) {
         this.logger.error("导出数据时发生错误:", error);
         return `导出失败: ${error.message}`;
@@ -432,8 +350,7 @@ var DataManager = class {
       if (!this.config.adminUsers.includes(session.userId)) return "抱歉，你没有权限导入数据";
       try {
         await session.send("正在导入数据，请稍候...");
-        const resultMessage = await this.importData();
-        return resultMessage;
+        return await this.importData();
       } catch (error) {
         this.logger.error("导入数据时发生错误:", error);
         return `导入失败: ${error.message}`;
@@ -441,9 +358,8 @@ var DataManager = class {
     });
   }
   /**
-   * 导出所有状态为 'active' 的回声洞数据。
-   * 数据将被序列化为 JSON 并保存到 `cave_export.json` 文件中。
-   * @returns 一个描述导出结果的字符串消息。
+   * @description 导出所有 'active' 状态的回声洞数据到 `cave_export.json`。
+   * @returns 描述导出结果的消息字符串。
    */
   async exportData() {
     const fileName = "cave_export.json";
@@ -454,8 +370,8 @@ var DataManager = class {
     return `成功导出 ${portableCaves.length} 条数据`;
   }
   /**
-   * 从 `cave_import.json` 文件导入回声洞数据。
-   * @returns 一个描述导入结果的字符串消息。
+   * @description 从 `cave_import.json` 文件导入回声洞数据。
+   * @returns 描述导入结果的消息字符串。
    */
   async importData() {
     const fileName = "cave_import.json";
@@ -463,9 +379,7 @@ var DataManager = class {
     try {
       const fileContent = await this.fileManager.readFile(fileName);
       importedCaves = JSON.parse(fileContent.toString("utf-8"));
-      if (!Array.isArray(importedCaves)) {
-        throw new Error("导入文件格式无效");
-      }
+      if (!Array.isArray(importedCaves)) throw new Error("导入文件格式无效");
     } catch (error) {
       this.logger.error(`读取导入文件失败:`, error);
       return `读取导入文件失败: ${error.message || "未知错误"}`;
@@ -477,9 +391,9 @@ var DataManager = class {
         ...cave,
         id: newId,
         channelId: cave.channelId || null,
-        // 确保 channelId 存在，若无则为 null。
+        // 保证 channelId 存在
         status: "active"
-        // 导入的数据直接设为 active 状态。
+        // 导入的数据直接设为活跃状态
       };
       await this.ctx.database.create("cave", newCave);
       successCount++;
@@ -491,11 +405,11 @@ var DataManager = class {
 // src/ReviewManager.ts
 var ReviewManager = class {
   /**
-   * 创建一个 ReviewManager 实例。
-   * @param ctx - Koishi 上下文。
-   * @param config - 插件配置。
-   * @param fileManager - 文件管理器实例。
-   * @param logger - 日志记录器实例。
+   * @constructor
+   * @param ctx Koishi 上下文。
+   * @param config 插件配置。
+   * @param fileManager 文件管理器实例。
+   * @param logger 日志记录器实例。
    */
   constructor(ctx, config, fileManager, logger2) {
     this.ctx = ctx;
@@ -507,49 +421,36 @@ var ReviewManager = class {
     __name(this, "ReviewManager");
   }
   /**
-   * 注册与审核相关的 `.review` 子命令。
-   * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
+   * @description 注册与审核相关的 `.review` 子命令。
+   * @param cave - 主 `cave` 命令实例。
    */
   registerCommands(cave) {
     cave.subcommand(".review [id:posint] [action:string]", "审核回声洞").usage("查看或审核回声洞，使用 <Y/N> 进行审核。").action(async ({ session }, id, action) => {
-      if (!this.config.adminUsers.includes(session.userId)) {
-        return "抱歉，你没有权限执行审核";
-      }
+      if (!this.config.adminUsers.includes(session.userId)) return "抱歉，你没有权限执行审核";
       if (!id) {
         const pendingCaves = await this.ctx.database.get("cave", { status: "pending" });
-        if (pendingCaves.length === 0) {
-          return "当前没有需要审核的回声洞";
-        }
-        const pendingIds = pendingCaves.map((c) => c.id).join(", ");
+        if (pendingCaves.length === 0) return "当前没有需要审核的回声洞";
         return `当前共有 ${pendingCaves.length} 条待审核回声洞，序号为：
-${pendingIds}`;
+${pendingCaves.map((c) => c.id).join(", ")}`;
       }
       const [targetCave] = await this.ctx.database.get("cave", { id });
-      if (!targetCave) {
-        return `回声洞（${id}）不存在`;
-      }
-      if (targetCave.status !== "pending") {
-        return `回声洞（${id}）无需审核`;
-      }
+      if (!targetCave) return `回声洞（${id}）不存在`;
+      if (targetCave.status !== "pending") return `回声洞（${id}）无需审核`;
       if (id && !action) {
-        return this.buildReviewMessage(targetCave);
+        return [`待审核：`, ...await buildCaveMessage(targetCave, this.config, this.fileManager, this.logger)];
       }
       const normalizedAction = action.toLowerCase();
       let reviewAction;
-      if (["y", "yes", "ok", "pass", "approve"].includes(normalizedAction)) {
-        reviewAction = "approve";
-      } else if (["n", "no", "deny", "reject"].includes(normalizedAction)) {
-        reviewAction = "reject";
-      } else {
-        return `无效操作: "${action}"
+      if (["y", "yes", "ok", "pass", "approve"].includes(normalizedAction)) reviewAction = "approve";
+      else if (["n", "no", "deny", "reject"].includes(normalizedAction)) reviewAction = "reject";
+      else return `无效操作: "${action}"
 请使用 "Y" (通过) 或 "N" (拒绝)`;
-      }
       return this.processReview(reviewAction, id, session.username);
     });
   }
   /**
-   * 将一条新的回声洞提交给所有管理员进行审核。
-   * @param cave - 新创建的、状态为 'pending' 的回声洞对象。
+   * @description 将新回声洞提交给管理员审核。
+   * @param cave 新创建的、状态为 'pending' 的回声洞对象。
    */
   async sendForReview(cave) {
     if (!this.config.adminUsers?.length) {
@@ -557,7 +458,7 @@ ${pendingIds}`;
       await this.ctx.database.upsert("cave", [{ id: cave.id, status: "active" }]);
       return;
     }
-    const reviewMessage = await this.buildReviewMessage(cave);
+    const reviewMessage = [`待审核：`, ...await buildCaveMessage(cave, this.config, this.fileManager, this.logger)];
     try {
       await this.ctx.broadcast(this.config.adminUsers, reviewMessage);
     } catch (error) {
@@ -565,29 +466,15 @@ ${pendingIds}`;
     }
   }
   /**
-   * 构建一条用于发送给管理员的、包含审核信息的消息。
-   * @param cave - 待审核的回声洞对象。
-   * @returns 一个可直接发送的消息数组。
-   * @private
-   */
-  async buildReviewMessage(cave) {
-    const caveContent = await buildCaveMessage(cave, this.config, this.fileManager, this.logger);
-    return [
-      `以下内容待审核：`,
-      ...caveContent
-    ];
-  }
-  /**
-   * 处理管理员的审核决定（通过或拒绝）。
-   * @param action - 'approve' (通过) 或 'reject' (拒绝)。
-   * @param caveId - 被审核的回声洞 ID。
-   * @param adminUserName - 执行操作的管理员的昵称。
+   * @description 处理管理员的审核决定（通过或拒绝）。
+   * @param action 'approve' (通过) 或 'reject' (拒绝)。
+   * @param caveId 被审核的回声洞 ID。
+   * @param adminUserName 操作管理员的昵称。
    * @returns 返回给操作者的确认消息。
    */
   async processReview(action, caveId, adminUserName) {
-    const [cave] = await this.ctx.database.get("cave", { id: caveId });
-    if (!cave) return `回声洞（${caveId}）不存在`;
-    if (cave.status !== "pending") return `回声洞（${caveId}）无需审核`;
+    const [cave] = await this.ctx.database.get("cave", { id: caveId, status: "pending" });
+    if (!cave) return `回声洞（${caveId}）不存在或无需审核`;
     let resultMessage;
     let broadcastMessage;
     if (action === "approve") {
@@ -596,19 +483,12 @@ ${pendingIds}`;
       broadcastMessage = `回声洞（${caveId}）已由管理员 "${adminUserName}" 通过`;
     } else {
       await this.ctx.database.upsert("cave", [{ id: caveId, status: "delete" }]);
-      const caveContent = await buildCaveMessage(cave, this.config, this.fileManager, this.logger);
-      resultMessage = [
-        `回声洞（${caveId}）已拒绝`,
-        ...caveContent
-      ];
-      broadcastMessage = [
-        `回声洞（${caveId}）已由管理员 "${adminUserName}" 拒绝`,
-        ...caveContent
-      ];
+      resultMessage = `回声洞（${caveId}）已拒绝`;
+      broadcastMessage = `回声洞（${caveId}）已由管理员 "${adminUserName}" 拒绝`;
       cleanupPendingDeletions(this.ctx, this.fileManager, this.logger);
     }
-    if (broadcastMessage && this.config.adminUsers?.length) {
-      await this.ctx.broadcast(this.config.adminUsers, broadcastMessage).catch((err) => {
+    if (this.config.adminUsers?.length) {
+      this.ctx.broadcast(this.config.adminUsers, broadcastMessage).catch((err) => {
         this.logger.error(`广播回声洞（${cave.id}）审核结果失败:`, err);
       });
     }
@@ -625,7 +505,6 @@ var usage = `
   <p>📖 <strong>使用文档</strong>：请点击左上角的 <strong>插件主页</strong> 查看插件使用文档</p>
   <p>🔍 <strong>更多插件</strong>：可访问 <a href="https://github.com/YisRime" style="color:#4a6ee0;text-decoration:none;">苡淞的 GitHub</a> 查看本人的所有插件</p>
 </div>
-
 <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);">
   <h2 style="margin-top: 0; color: #e0574a;">❤️ 支持与反馈</h2>
   <p>🌟 喜欢这个插件？请在 <a href="https://github.com/YisRime" style="color:#e0574a;text-decoration:none;">GitHub</a> 上给我一个 Star！</p>
@@ -659,23 +538,13 @@ var Config = import_koishi2.Schema.intersect([
 function apply(ctx, config) {
   ctx.model.extend("cave", {
     id: "unsigned",
-    // 无符号整数，作为主键。
     elements: "json",
-    // 存储为 JSON 字符串的元素数组。
     channelId: "string",
-    // 频道 ID。
     userId: "string",
-    // 用户 ID。
     userName: "string",
-    // 用户昵称。
     status: "string",
-    // 回声洞状态。
     time: "timestamp"
-    // 提交时间。
-  }, {
-    primary: "id"
-    // 将 'id' 字段设置为主键。
-  });
+  }, { primary: "id" });
   const fileManager = new FileManager(ctx.baseDir, config, logger);
   const lastUsed = /* @__PURE__ */ new Map();
   let profileManager;
@@ -704,7 +573,6 @@ function apply(ctx, config) {
     }
   });
   cave.subcommand(".add [content:text]", "添加回声洞").usage("添加一条回声洞。可以直接发送内容，也可以回复或引用一条消息。").action(async ({ session }, content) => {
-    const savedFileIdentifiers = [];
     try {
       let sourceElements;
       if (session.quote?.elements) {
@@ -717,46 +585,73 @@ function apply(ctx, config) {
         if (!reply) return "操作超时，已取消添加";
         sourceElements = import_koishi2.h.parse(reply);
       }
-      const scopeQuery = getScopeQuery(session, config);
-      const newId = await getNextCaveId(ctx, scopeQuery);
+      const idScopeQuery = {};
+      if (config.perChannel && session.channelId) {
+        idScopeQuery["channelId"] = session.channelId;
+      }
+      const newId = await getNextCaveId(ctx, idScopeQuery);
       const finalElementsForDb = [];
+      const mediaToSave = [];
       let mediaIndex = 0;
+      const typeMap = {
+        "img": "image",
+        "image": "image",
+        "video": "video",
+        "audio": "audio",
+        "file": "file",
+        "text": "text"
+      };
       async function traverseAndProcess(elements) {
         for (const el of elements) {
-          const elementType = el.type;
-          if (["image", "video", "audio", "file"].includes(elementType) && el.attrs.src) {
+          const normalizedType = typeMap[el.type];
+          if (!normalizedType) {
+            if (el.children) await traverseAndProcess(el.children);
+            continue;
+          }
+          if (["image", "video", "audio", "file"].includes(normalizedType) && el.attrs.src) {
             let fileIdentifier = el.attrs.src;
             if (fileIdentifier.startsWith("http")) {
               mediaIndex++;
-              const originalName = el.attrs.file;
-              const savedId = await downloadMedia(ctx, fileManager, fileIdentifier, originalName, elementType, newId, mediaIndex, session.channelId, session.userId);
-              savedFileIdentifiers.push(savedId);
-              fileIdentifier = savedId;
+              const defaultExtMap = { "image": ".jpg", "video": ".mp4", "audio": ".mp3", "file": ".dat" };
+              const ext = el.attrs.file && path3.extname(el.attrs.file) ? path3.extname(el.attrs.file) : defaultExtMap[normalizedType] || ".dat";
+              const channelIdentifier = session.channelId || "private";
+              const fileName = `${newId}_${mediaIndex}_${channelIdentifier}_${session.userId}${ext}`;
+              mediaToSave.push({ sourceUrl: fileIdentifier, fileName });
+              fileIdentifier = fileName;
             }
-            finalElementsForDb.push({ type: elementType, file: fileIdentifier });
-          } else if (elementType === "text" && el.attrs.content?.trim()) {
+            finalElementsForDb.push({ type: normalizedType, file: fileIdentifier });
+          } else if (normalizedType === "text" && el.attrs.content?.trim()) {
             finalElementsForDb.push({ type: "text", content: el.attrs.content.trim() });
           }
-          if (el.children) await traverseAndProcess(el.children);
+          if (el.children) {
+            await traverseAndProcess(el.children);
+          }
         }
       }
       __name(traverseAndProcess, "traverseAndProcess");
       await traverseAndProcess(sourceElements);
       if (finalElementsForDb.length === 0) return "内容为空，已取消添加";
-      let userName = session.username;
-      if (config.enableProfile) {
-        userName = await profileManager.getNickname(session.userId) || userName;
-      }
+      const customNickname = config.enableProfile ? await profileManager.getNickname(session.userId) : null;
       const newCave = {
         id: newId,
         elements: finalElementsForDb,
         channelId: session.channelId,
         userId: session.userId,
-        userName,
+        userName: customNickname || session.username,
         status: config.enableReview ? "pending" : "active",
         time: /* @__PURE__ */ new Date()
       };
       await ctx.database.create("cave", newCave);
+      try {
+        await Promise.all(mediaToSave.map(async (media) => {
+          const response = await ctx.http.get(media.sourceUrl, { responseType: "arraybuffer", timeout: 3e4 });
+          await fileManager.saveFile(media.fileName, Buffer.from(response));
+        }));
+      } catch (fileSaveError) {
+        logger.error(`文件保存失败:`, fileSaveError);
+        await ctx.database.remove("cave", { id: newId });
+        throw fileSaveError;
+      }
       if (newCave.status === "pending") {
         reviewManager.sendForReview(newCave);
         return `提交成功，序号为（${newCave.id}）`;
@@ -764,10 +659,6 @@ function apply(ctx, config) {
       return `添加成功，序号为（${newId}）`;
     } catch (error) {
       logger.error("添加回声洞失败:", error);
-      if (savedFileIdentifiers.length > 0) {
-        logger.info(`添加失败，回滚并删除 ${savedFileIdentifiers.length} 个文件...`);
-        await Promise.all(savedFileIdentifiers.map((fileId) => fileManager.deleteFile(fileId)));
-      }
       return "添加失败，请稍后再试";
     }
   });
@@ -778,9 +669,7 @@ function apply(ctx, config) {
     try {
       const query = { ...getScopeQuery(session, config), id };
       const [targetCave] = await ctx.database.get("cave", query);
-      if (!targetCave) {
-        return `回声洞（${id}）不存在`;
-      }
+      if (!targetCave) return `回声洞（${id}）不存在`;
       updateCooldownTimestamp(session, config, lastUsed);
       return buildCaveMessage(targetCave, config, fileManager, logger);
     } catch (error) {
@@ -793,18 +682,13 @@ function apply(ctx, config) {
     try {
       const [targetCave] = await ctx.database.get("cave", { id, status: "active" });
       if (!targetCave) return `回声洞（${id}）不存在`;
-      const isOwner = targetCave.userId === session.userId;
-      const isAdmin = config.adminUsers.includes(session.userId);
-      if (!isOwner && !isAdmin) {
+      if (targetCave.userId !== session.userId && !config.adminUsers.includes(session.userId)) {
         return "抱歉，你没有权限删除这条回声洞";
       }
       await ctx.database.upsert("cave", [{ id, status: "delete" }]);
       const caveMessage = await buildCaveMessage(targetCave, config, fileManager, logger);
       cleanupPendingDeletions(ctx, fileManager, logger);
-      return [
-        `以下内容已删除`,
-        ...caveMessage
-      ];
+      return [`已删除`, ...caveMessage];
     } catch (error) {
       logger.error(`标记回声洞（${id}）失败:`, error);
       return "删除失败，请稍后再试";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-best-cave",
   "description": "最强大的回声洞现已重构完成啦！注意数据格式需要使用脚本转换哦~",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],