koishi-plugin-best-cave 2.0.5 → 2.0.6

package/lib/DataManager.d.ts

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

package/lib/FileManager.d.ts

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

package/lib/ProfileManager.d.ts

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

package/lib/ReviewManager.d.ts

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

package/lib/Utils.d.ts

@@ -2,72 +2,78 @@ import { Context, h, Logger, Session } from 'koishi';
 import { CaveObject, Config, StoredElement } from './index';
 import { FileManager } from './FileManager';
 /**
- * 将数据库存储格式的元素数组转换为 Koishi 消息元素 (h-element) 数组。
- * @param elements - StoredElement 对象数组。
- * @returns 可用于发送的 h-element 数组。
+ * 将数据库中存储的 StoredElement[] 数组转换为 Koishi h() 元素数组。
+ * @param elements - 从数据库读取的元素对象数组。
+ * @returns 转换后的 h() 元素数组，用于消息发送。
  */
 export declare function storedFormatToHElements(elements: StoredElement[]): h[];
 /**
- * 将指向本地媒体文件的 h-element 转换为内联 Base64 数据。
- * @param element - 包含本地文件路径的媒体 h-element。
+ * 将指向本地媒体文件的 h() 元素转换为内联 Base64 格式。
+ * @param element - 包含本地文件路径的 h() 媒体元素。
  * @param fileManager - FileManager 实例，用于读取文件。
- * @param logger - Logger 实例，用于记录日志。
- * @returns 转换后的 h-element，其 src 为 Base64 数据 URI，或在失败时返回一个文本提示。
+ * @param logger - Logger 实例，用于记录错误。
+ * @returns 转换后的 h() 元素，其 src 属性为 Base64 数据 URI。
  */
 export declare function mediaElementToBase64(element: h, fileManager: FileManager, logger: Logger): Promise<h>;
 /**
- * 根据配置构建一条包含回声洞内容的完整可发送消息。
+ * 构建一条包含回声洞内容的完整消息，准备发送。
+ * 此函数会处理 S3 URL、文件映射路径或本地文件到 Base64 的转换。
  * @param cave - 要展示的回声洞对象。
- * @param config - 插件配置对象。
+ * @param config - 插件配置。
  * @param fileManager - FileManager 实例。
  * @param logger - Logger 实例。
- * @returns 一个包含字符串和 h-element 的消息数组。
+ * @returns 一个包含 h() 元素和字符串的消息数组。
  */
 export declare function buildCaveMessage(cave: CaveObject, config: Config, fileManager: FileManager, logger: Logger): Promise<(string | h)[]>;
 /**
- * 遍历并转换消息元素为可存储格式，同时识别待下载的媒体文件。
- * @param sourceElements - 源消息中的 h-element 数组。
- * @param newId - 新回声洞的 ID。
- * @param channelId - 频道 ID。
- * @param userId - 用户 ID。
- * @returns 一个包含待存储元素和待下载媒体列表的对象。
- */
-export declare function prepareElementsForStorage(sourceElements: h[], newId: number, channelId: string, userId: string): {
-    finalElementsForDb: StoredElement[];
-    mediaToDownload: {
-        url: string;
-        fileName: string;
-    }[];
-};
-/**
- * 清理数据库中所有标记为 'delete' 状态的回声洞及其关联的文件。
+ * 清理数据库中所有被标记为 'delete' 状态的回声洞及其关联的文件。
  * @param ctx - Koishi 上下文。
  * @param fileManager - FileManager 实例，用于删除文件。
  * @param logger - Logger 实例。
  */
 export declare function cleanupPendingDeletions(ctx: Context, fileManager: FileManager, logger: Logger): Promise<void>;
 /**
- * 根据插件配置和会话上下文，生成数据库查询的作用域条件。
- * @param session - 当前 Koishi 会话对象。
- * @param config - 插件配置对象。
- * @returns 一个用于数据库查询的条件对象，其类型已精确定义。
+ * 根据插件配置（是否分群）和当前会话，生成数据库查询所需的范围条件。
+ * @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。
+ */
+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。
+ * @returns 保存后的文件名/标识符。
  */
-export declare function getScopeQuery(session: Session, config: Config): {
-    status: 'active';
-    channelId?: string;
-};
+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 - 当前 Koishi 会话对象。
- * @param config - 插件配置对象。
+ * 检查用户在当前频道是否处于指令冷却状态。
+ * @param session - 当前会话对象。
+ * @param config - 插件配置。
  * @param lastUsed - 存储各频道最后使用时间的 Map。
- * @returns 若处于冷却中，返回提示信息字符串；否则返回 null。
+ * @returns 如果处于冷却中，返回提示信息字符串；否则返回 null。
  */
 export declare function checkCooldown(session: Session, config: Config, lastUsed: Map<string, number>): string | null;
 /**
  * 更新指定频道的指令使用时间戳。
- * @param session - 当前 Koishi 会话对象。
- * @param config - 插件配置对象。
+ * @param session - 当前会话对象。
+ * @param config - 插件配置。
  * @param lastUsed - 存储各频道最后使用时间的 Map。
  */
 export declare function updateCooldownTimestamp(session: Session, config: Config, lastUsed: Map<string, number>): void;

package/lib/index.d.ts

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

package/lib/index.js

@@ -45,8 +45,9 @@ var fs = __toESM(require("fs/promises"));
 var path = __toESM(require("path"));
 var FileManager = class {
   /**
+   * 创建一个 FileManager 实例。
    * @param baseDir - Koishi 应用的基础数据目录 (ctx.baseDir)。
-   * @param config - 插件的配置对象。
+   * @param config - 插件的完整配置对象。
    * @param logger - 日志记录器实例。
    */
   constructor(baseDir, config, logger2) {
@@ -67,19 +68,24 @@ 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(`Failed to create resource directory ${this.resourceDir}:`, error);
+      this.logger.error(`创建资源目录失败 ${this.resourceDir}:`, error);
       throw error;
     }
   }
@@ -93,7 +99,8 @@ var FileManager = class {
     return path.join(this.resourceDir, fileName);
   }
   /**
-   * 使用文件锁安全地执行一个异步文件操作，防止对同一文件的并发访问。
+   * 使用文件锁来安全地执行一个异步文件操作。
+   * 这可以防止对同一文件的并发读写造成数据损坏。
    * @template T - 异步操作的返回类型。
    * @param fileName - 需要加锁的文件名。
    * @param operation - 要执行的异步函数。
@@ -103,24 +110,19 @@ var FileManager = class {
   async withLock(fileName, operation) {
     const fullPath = this.getFullPath(fileName);
     while (this.locks.has(fullPath)) {
-      await this.locks.get(fullPath).catch(() => {
-      });
+      await this.locks.get(fullPath);
     }
-    const promise = operation();
+    const promise = operation().finally(() => {
+      this.locks.delete(fullPath);
+    });
     this.locks.set(fullPath, promise);
-    try {
-      return await promise;
-    } finally {
-      if (this.locks.get(fullPath) === promise) {
-        this.locks.delete(fullPath);
-      }
-    }
+    return promise;
   }
   /**
-   * 保存文件，自动路由到 S3 或本地存储。
-   * @param fileName - 文件名，将用作 S3 Key 或本地文件名。
+   * 保存文件，自动选择 S3 或本地存储。
+   * @param fileName - 文件名，将用作 S3 中的 Key 或本地文件名。
    * @param data - 要写入的 Buffer 数据。
-   * @returns 返回保存时使用的文件名。
+   * @returns 返回保存时使用的文件名/标识符。
    */
   async saveFile(fileName, data) {
     if (this.s3Client) {
@@ -129,18 +131,20 @@ 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;
     }
-    return fileName;
   }
   /**
-   * 读取文件，自动从 S3 或本地存储获取。
-   * @param fileName - 要读取的文件名。
+   * 读取文件，自动从 S3 或本地存储读取。
+   * @param fileName - 要读取的文件名/标识符。
    * @returns 文件的 Buffer 数据。
    */
   async readFile(fileName) {
@@ -158,26 +162,26 @@ var FileManager = class {
     }
   }
   /**
-   * 删除文件，自动从 S3 或本地存储删除。
-   * @param fileName - 要删除的文件名。
+   * 删除文件，自动从 S3 或本地删除。
+   * @param fileIdentifier - 要删除的文件名/标识符。
    */
-  async deleteFile(fileName) {
+  async deleteFile(fileIdentifier) {
     if (this.s3Client) {
       const command = new import_client_s3.DeleteObjectCommand({
         Bucket: this.s3Bucket,
-        Key: fileName
+        Key: fileIdentifier
       });
       await this.s3Client.send(command).catch((err) => {
-        this.logger.warn(`删除文件 ${fileName} 失败:`, err);
+        this.logger.warn(`删除文件 ${fileIdentifier} 失败:`, err);
       });
     } else {
-      const filePath = this.getFullPath(fileName);
-      await this.withLock(fileName, async () => {
+      const filePath = this.getFullPath(fileIdentifier);
+      await this.withLock(fileIdentifier, async () => {
         try {
           await fs.unlink(filePath);
         } catch (error) {
           if (error.code !== "ENOENT") {
-            this.logger.warn(`删除文件 ${fileName} 失败:`, error);
+            this.logger.warn(`删除文件 ${filePath} 失败:`, error);
           }
         }
       });
@@ -188,15 +192,19 @@ var FileManager = class {
 // src/ProfileManager.ts
 var ProfileManager = class {
   /**
-   * @param ctx - Koishi 上下文，用于数据库交互。
+   * 创建一个 ProfileManager 实例。
+   * @param ctx - Koishi 上下文，用于初始化数据库模型。
    */
   constructor(ctx) {
     this.ctx = ctx;
     this.ctx.model.extend("cave_user", {
       userId: "string",
+      // 用户 ID
       nickname: "string"
+      // 用户自定义昵称
     }, {
       primary: "userId"
+      // 使用 userId 作为主键，确保每个用户只有一条昵称记录。
     });
   }
   static {
@@ -204,7 +212,7 @@ var ProfileManager = class {
   }
   /**
    * 注册与用户昵称相关的 `.profile` 子命令。
-   * @param cave - 主 `cave` 命令实例，用于挂载子命令。
+   * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
    */
   registerCommands(cave) {
     cave.subcommand(".profile [nickname:text]", "设置显示昵称").usage("设置你在回声洞中显示的昵称。不提供昵称则清除记录。").action(async ({ session }, nickname) => {
@@ -223,16 +231,19 @@ var ProfileManager = class {
    * @param nickname - 要设置的新昵称。
    */
   async setNickname(userId, nickname) {
-    await this.ctx.database.upsert("cave_user", [{ userId, nickname }]);
+    await this.ctx.database.upsert("cave_user", [{
+      userId,
+      nickname
+    }]);
   }
   /**
    * 获取指定用户的昵称。
    * @param userId - 目标用户的 ID。
-   * @returns 返回用户的昵称字符串，如果用户未设置则返回 null。
+   * @returns 返回用户的昵称字符串。如果用户未设置昵称，则返回 null。
    */
   async getNickname(userId) {
-    const [profile] = await this.ctx.database.get("cave_user", { userId });
-    return profile?.nickname || null;
+    const profiles = await this.ctx.database.get("cave_user", { userId });
+    return profiles[0]?.nickname || null;
   }
   /**
    * 清除指定用户的昵称设置。
@@ -243,102 +254,6 @@ var ProfileManager = class {
   }
 };
 
-// src/DataManager.ts
-var DataManager = class {
-  /**
-   * @param ctx - Koishi 上下文，用于数据库操作。
-   * @param config - 插件配置对象。
-   * @param fileManager - 文件管理器实例，用于读写导入/导出文件。
-   * @param logger - 日志记录器实例。
-   */
-  constructor(ctx, config, fileManager, logger2) {
-    this.ctx = ctx;
-    this.config = config;
-    this.fileManager = fileManager;
-    this.logger = logger2;
-  }
-  static {
-    __name(this, "DataManager");
-  }
-  /**
-   * 注册与数据导入导出相关的 `.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("正在导出数据，请稍候...");
-        return await this.exportData();
-      } catch (error) {
-        this.logger.error("导出数据时发生错误:", error);
-        return `导出失败: ${error.message}`;
-      }
-    });
-    cave.subcommand(".import", "导入回声洞数据").usage("从 cave_import.json 中导入回声洞数据。").action(async ({ session }) => {
-      if (!this.config.adminUsers.includes(session.userId)) return "抱歉，你没有权限导入数据";
-      try {
-        await session.send("正在导入数据，请稍候...");
-        return await this.importData();
-      } catch (error) {
-        this.logger.error("导入数据时发生错误:", error);
-        return `导入失败: ${error.message}`;
-      }
-    });
-  }
-  /**
-   * 导出所有状态为 'active' 的回声洞数据到 `cave_export.json` 文件。
-   * @returns 一个描述导出结果的字符串消息。
-   */
-  async exportData() {
-    const fileName = "cave_export.json";
-    const cavesToExport = await this.ctx.database.get("cave", { status: "active" });
-    const portableCaves = cavesToExport.map(({ id, ...rest }) => rest);
-    const data = JSON.stringify(portableCaves, null, 2);
-    await this.fileManager.saveFile(fileName, Buffer.from(data));
-    return `成功导出 ${portableCaves.length} 条数据`;
-  }
-  /**
-   * 从 `cave_import.json` 文件导入回声洞数据。
-   * @returns 一个描述导入结果的字符串消息。
-   */
-  async importData() {
-    const fileName = "cave_import.json";
-    let importedData;
-    try {
-      const fileContent = await this.fileManager.readFile(fileName);
-      importedData = JSON.parse(fileContent.toString("utf-8"));
-      if (!Array.isArray(importedData)) {
-        throw new Error("导入文件格式非 JSON 数组");
-      }
-    } catch (error) {
-      return `读取导入文件失败: ${error.message}`;
-    }
-    const allCaves = await this.ctx.database.get("cave", {}, { fields: ["id"] });
-    const existingIds = new Set(allCaves.map((c) => c.id));
-    let nextId = 1;
-    const cavesToCreate = [];
-    for (const caveData of importedData) {
-      while (existingIds.has(nextId)) {
-        nextId++;
-      }
-      const newId = nextId;
-      const newCave = {
-        ...caveData,
-        id: newId,
-        channelId: caveData.channelId,
-        status: "active"
-      };
-      cavesToCreate.push(newCave);
-      existingIds.add(newId);
-    }
-    if (cavesToCreate.length > 0) {
-      await this.ctx.database.upsert("cave", cavesToCreate);
-    }
-    return `成功导入 ${cavesToCreate.length} 条回声洞数据`;
-  }
-};
-
 // src/Utils.ts
 var import_koishi = require("koishi");
 var path2 = __toESM(require("path"));
@@ -376,7 +291,7 @@ async function mediaElementToBase64(element, fileManager, logger2) {
     return (0, import_koishi.h)(element.type, { ...element.attrs, src: `data:${mimeType};base64,${data.toString("base64")}` });
   } catch (error) {
     logger2.warn(`转换本地文件 ${fileName} 为 Base64 失败:`, error);
-    return import_koishi.h.text(`[${element.type}]`);
+    return (0, import_koishi.h)("p", {}, `[${element.type}]`);
   }
 }
 __name(mediaElementToBase64, "mediaElementToBase64");
@@ -386,68 +301,47 @@ async function buildCaveMessage(cave, config, fileManager, logger2) {
     const isMedia = ["image", "video", "audio", "file"].includes(element.type);
     const fileName = element.attrs.src;
     if (!isMedia || !fileName) {
-      return element;
+      return Promise.resolve(element);
     }
     if (config.enableS3 && config.publicUrl) {
-      const fullUrl = new URL(fileName, config.publicUrl.endsWith("/") ? config.publicUrl : `${config.publicUrl}/`).href;
-      return (0, import_koishi.h)(element.type, { ...element.attrs, src: fullUrl });
+      const fullUrl = config.publicUrl.endsWith("/") ? `${config.publicUrl}${fileName}` : `${config.publicUrl}/${fileName}`;
+      return Promise.resolve((0, import_koishi.h)(element.type, { ...element.attrs, src: fullUrl }));
     }
     if (config.localPath) {
-      const fileUri = `file://${path2.join(config.localPath, fileName)}`;
-      return (0, import_koishi.h)(element.type, { ...element.attrs, src: fileUri });
+      const mappedPath = path2.join(config.localPath, fileName);
+      const fileUri = `file://${mappedPath}`;
+      return Promise.resolve((0, import_koishi.h)(element.type, { ...element.attrs, src: fileUri }));
     }
     return mediaElementToBase64(element, fileManager, logger2);
   }));
   const finalMessage = [];
-  const [headerFormat, footerFormat] = config.caveFormat.split("|");
-  const replacer = /* @__PURE__ */ __name((str) => str.replace("{id}", cave.id.toString()).replace("{name}", cave.userName), "replacer");
-  if (headerFormat?.trim()) finalMessage.push(replacer(headerFormat));
+  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);
+  if (headerText.trim()) finalMessage.push(headerText);
   finalMessage.push(...processedElements);
-  if (footerFormat?.trim()) finalMessage.push(replacer(footerFormat));
+  const footerText = footerFormat.replace("{id}", cave.id.toString()).replace("{name}", cave.userName);
+  if (footerText.trim()) finalMessage.push(footerText);
   return finalMessage;
 }
 __name(buildCaveMessage, "buildCaveMessage");
-function prepareElementsForStorage(sourceElements, newId, channelId, userId) {
-  const finalElementsForDb = [];
-  const mediaToDownload = [];
-  let mediaIndex = 0;
-  const processElement = /* @__PURE__ */ __name((el) => {
-    const elementType = el.type;
-    if (["image", "video", "audio", "file"].includes(elementType) && el.attrs.src) {
-      const fileIdentifier = el.attrs.src;
-      if (fileIdentifier.startsWith("http")) {
-        mediaIndex++;
-        const originalName = el.attrs.file;
-        const defaultExtMap = { "image": ".jpg", "video": ".mp4", "audio": ".mp3", "file": ".dat" };
-        const ext = originalName ? path2.extname(originalName) : "";
-        const finalExt = ext || defaultExtMap[elementType] || ".dat";
-        const generatedFileName = `${newId}_${mediaIndex}_${channelId}_${userId}${finalExt}`;
-        finalElementsForDb.push({ type: elementType, file: generatedFileName });
-        mediaToDownload.push({ url: fileIdentifier, fileName: generatedFileName });
-      } else {
-        finalElementsForDb.push({ type: elementType, file: fileIdentifier });
-      }
-    } else if (elementType === "text" && el.attrs.content?.trim()) {
-      finalElementsForDb.push({ type: "text", content: el.attrs.content.trim() });
-    }
-    if (el.children) {
-      el.children.forEach(processElement);
-    }
-  }, "processElement");
-  sourceElements.forEach(processElement);
-  return { finalElementsForDb, mediaToDownload };
-}
-__name(prepareElementsForStorage, "prepareElementsForStorage");
 async function cleanupPendingDeletions(ctx, fileManager, logger2) {
   try {
     const cavesToDelete = await ctx.database.get("cave", { status: "delete" });
     if (cavesToDelete.length === 0) return;
-    const filesToDelete = cavesToDelete.flatMap(
-      (cave) => cave.elements.filter((el) => el.file).map((el) => el.file)
-    );
-    await Promise.all(filesToDelete.map((file) => fileManager.deleteFile(file)));
-    const idsToRemove = cavesToDelete.map((cave) => cave.id);
-    await ctx.database.remove("cave", { id: { $in: idsToRemove } });
+    for (const cave of cavesToDelete) {
+      const deletePromises = cave.elements.filter((el) => el.file).map((el) => fileManager.deleteFile(el.file));
+      await Promise.all(deletePromises);
+      await ctx.database.remove("cave", { id: cave.id });
+    }
   } catch (error) {
     logger2.error("清理回声洞时发生错误:", error);
   }
@@ -461,6 +355,25 @@ function getScopeQuery(session, config) {
   return 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));
+  let newId = 1;
+  while (existingIds.has(newId)) {
+    newId++;
+  }
+  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;
@@ -481,13 +394,106 @@ function updateCooldownTimestamp(session, config, lastUsed) {
 }
 __name(updateCooldownTimestamp, "updateCooldownTimestamp");
 
+// src/DataManager.ts
+var DataManager = class {
+  /**
+   * 创建一个 DataManager 实例。
+   * @param ctx - Koishi 上下文，用于数据库操作。
+   * @param config - 插件配置。
+   * @param fileManager - 文件管理器实例，用于读写导入/导出文件。
+   * @param logger - 日志记录器实例。
+   */
+  constructor(ctx, config, fileManager, logger2) {
+    this.ctx = ctx;
+    this.config = config;
+    this.fileManager = fileManager;
+    this.logger = logger2;
+  }
+  static {
+    __name(this, "DataManager");
+  }
+  /**
+   * 注册与数据导入导出相关的 `.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;
+      } catch (error) {
+        this.logger.error("导出数据时发生错误:", error);
+        return `导出失败: ${error.message}`;
+      }
+    });
+    cave.subcommand(".import", "导入回声洞数据").usage("从 cave_import.json 中导入回声洞数据。").action(async ({ session }) => {
+      if (!this.config.adminUsers.includes(session.userId)) return "抱歉，你没有权限导入数据";
+      try {
+        await session.send("正在导入数据，请稍候...");
+        const resultMessage = await this.importData();
+        return resultMessage;
+      } catch (error) {
+        this.logger.error("导入数据时发生错误:", error);
+        return `导入失败: ${error.message}`;
+      }
+    });
+  }
+  /**
+   * 导出所有状态为 'active' 的回声洞数据。
+   * 数据将被序列化为 JSON 并保存到 `cave_export.json` 文件中。
+   * @returns 一个描述导出结果的字符串消息。
+   */
+  async exportData() {
+    const fileName = "cave_export.json";
+    const cavesToExport = await this.ctx.database.get("cave", { status: "active" });
+    const portableCaves = cavesToExport.map(({ id, ...rest }) => rest);
+    const data = JSON.stringify(portableCaves, null, 2);
+    await this.fileManager.saveFile(fileName, Buffer.from(data));
+    return `成功导出 ${portableCaves.length} 条数据`;
+  }
+  /**
+   * 从 `cave_import.json` 文件导入回声洞数据。
+   * @returns 一个描述导入结果的字符串消息。
+   */
+  async importData() {
+    const fileName = "cave_import.json";
+    let importedCaves;
+    try {
+      const fileContent = await this.fileManager.readFile(fileName);
+      importedCaves = JSON.parse(fileContent.toString("utf-8"));
+      if (!Array.isArray(importedCaves)) {
+        throw new Error("导入文件格式无效");
+      }
+    } catch (error) {
+      this.logger.error(`读取导入文件失败:`, error);
+      return `读取导入文件失败: ${error.message || "未知错误"}`;
+    }
+    let successCount = 0;
+    for (const cave of importedCaves) {
+      const newId = await getNextCaveId(this.ctx, {});
+      const newCave = {
+        ...cave,
+        id: newId,
+        channelId: cave.channelId || null,
+        // 确保 channelId 存在，若无则为 null。
+        status: "active"
+        // 导入的数据直接设为 active 状态。
+      };
+      await this.ctx.database.create("cave", newCave);
+      successCount++;
+    }
+    return `成功导入 ${successCount} 条回声洞数据`;
+  }
+};
+
 // src/ReviewManager.ts
-var APPROVE_ACTIONS = /* @__PURE__ */ new Set(["y", "yes", "pass", "approve"]);
-var REJECT_ACTIONS = /* @__PURE__ */ new Set(["n", "no", "deny", "reject"]);
 var ReviewManager = class {
   /**
+   * 创建一个 ReviewManager 实例。
    * @param ctx - Koishi 上下文。
-   * @param config - 插件配置对象。
+   * @param config - 插件配置。
    * @param fileManager - 文件管理器实例。
    * @param logger - 日志记录器实例。
    */
@@ -502,7 +508,7 @@ var ReviewManager = class {
   }
   /**
    * 注册与审核相关的 `.review` 子命令。
-   * @param cave - 主 `cave` 命令实例，用于挂载子命令。
+   * @param cave - 主 `cave` 命令的实例，用于挂载子命令。
    */
   registerCommands(cave) {
     cave.subcommand(".review [id:posint] [action:string]", "审核回声洞").usage("查看或审核回声洞，使用 <Y/N> 进行审核。").action(async ({ session }, id, action) => {
@@ -510,46 +516,44 @@ var ReviewManager = class {
         return "抱歉，你没有权限执行审核";
       }
       if (!id) {
-        return this.listPendingCaves();
+        const pendingCaves = await this.ctx.database.get("cave", { status: "pending" });
+        if (pendingCaves.length === 0) {
+          return "当前没有需要审核的回声洞";
+        }
+        const pendingIds = pendingCaves.map((c) => c.id).join(", ");
+        return `当前共有 ${pendingCaves.length} 条待审核回声洞，序号为：
+${pendingIds}`;
       }
       const [targetCave] = await this.ctx.database.get("cave", { id });
-      if (!targetCave) return `回声洞（${id}）不存在`;
-      if (targetCave.status !== "pending") return `回声洞（${id}）无需审核`;
-      if (!action) {
-        return this.buildReviewMessage(targetCave);
+      if (!targetCave) {
+        return `回声洞（${id}）不存在`;
       }
-      const normalizedAction = action.toLowerCase();
-      if (APPROVE_ACTIONS.has(normalizedAction)) {
-        return this.processReview("approve", targetCave, session.username);
+      if (targetCave.status !== "pending") {
+        return `回声洞（${id}）无需审核`;
       }
-      if (REJECT_ACTIONS.has(normalizedAction)) {
-        return this.processReview("reject", targetCave, session.username);
+      if (id && !action) {
+        return this.buildReviewMessage(targetCave);
       }
-      return `无效操作: "${action}"
+      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}"
 请使用 "Y" (通过) 或 "N" (拒绝)`;
+      }
+      return this.processReview(reviewAction, id, session.username);
     });
   }
   /**
-   * 列出所有待审核的回声洞。
-   * @private
-   */
-  async listPendingCaves() {
-    const pendingCaves = await this.ctx.database.get("cave", { status: "pending" });
-    if (pendingCaves.length === 0) {
-      return "当前没有需要审核的回声洞";
-    }
-    const pendingIds = pendingCaves.map((c) => c.id).join(", ");
-    return `当前共有 ${pendingCaves.length} 条待审核回声洞，序号为：
-${pendingIds}`;
-  }
-  /**
-   * 将一条新回声洞提交给管理员进行审核。
-   * 如果没有配置管理员，将自动通过审核。
+   * 将一条新的回声洞提交给所有管理员进行审核。
    * @param cave - 新创建的、状态为 'pending' 的回声洞对象。
    */
   async sendForReview(cave) {
     if (!this.config.adminUsers?.length) {
-      this.logger.warn(`No admin users configured. Cave ${cave.id} has been auto-approved.`);
+      this.logger.warn(`未配置管理员，回声洞（${cave.id}）已自动通过审核`);
       await this.ctx.database.upsert("cave", [{ id: cave.id, status: "active" }]);
       return;
     }
@@ -557,45 +561,55 @@ ${pendingIds}`;
     try {
       await this.ctx.broadcast(this.config.adminUsers, reviewMessage);
     } catch (error) {
-      this.logger.error(`Failed to broadcast review request for cave ${cave.id}:`, error);
+      this.logger.error(`广播回声洞（${cave.id}）审核请求失败:`, error);
     }
   }
   /**
-   * 构建用于发送给管理员的审核消息。
+   * 构建一条用于发送给管理员的、包含审核信息的消息。
    * @param cave - 待审核的回声洞对象。
    * @returns 一个可直接发送的消息数组。
    * @private
    */
   async buildReviewMessage(cave) {
     const caveContent = await buildCaveMessage(cave, this.config, this.fileManager, this.logger);
-    return [`待审核`, ...caveContent];
+    return [
+      `以下内容待审核：`,
+      ...caveContent
+    ];
   }
   /**
    * 处理管理员的审核决定（通过或拒绝）。
    * @param action - 'approve' (通过) 或 'reject' (拒绝)。
-   * @param cave - 被审核的回声洞对象。
-   * @param adminUserName - 执行操作的管理员昵称。
+   * @param caveId - 被审核的回声洞 ID。
+   * @param adminUserName - 执行操作的管理员的昵称。
    * @returns 返回给操作者的确认消息。
    */
-  async processReview(action, cave, adminUserName) {
+  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}）无需审核`;
     let resultMessage;
     let broadcastMessage;
     if (action === "approve") {
-      await this.ctx.database.upsert("cave", [{ id: cave.id, status: "active" }]);
-      resultMessage = `回声洞（${cave.id}）已通过`;
-      broadcastMessage = `回声洞（${cave.id}）已由管理员 "${adminUserName}" 通过`;
+      await this.ctx.database.upsert("cave", [{ id: caveId, status: "active" }]);
+      resultMessage = `回声洞（${caveId}）已通过`;
+      broadcastMessage = `回声洞（${caveId}）已由管理员 "${adminUserName}" 通过`;
     } else {
-      await this.ctx.database.upsert("cave", [{ id: cave.id, status: "delete" }]);
-      resultMessage = `回声洞（${cave.id}）已拒绝`;
+      await this.ctx.database.upsert("cave", [{ id: caveId, status: "delete" }]);
       const caveContent = await buildCaveMessage(cave, this.config, this.fileManager, this.logger);
-      broadcastMessage = [`回声洞（${cave.id}）已由管理员 "${adminUserName}" 拒绝`, ...caveContent];
-      cleanupPendingDeletions(this.ctx, this.fileManager, this.logger).catch((err) => {
-        this.logger.error(`Background cleanup failed for rejected cave ${cave.id}:`, err);
-      });
+      resultMessage = [
+        `回声洞（${caveId}）已拒绝`,
+        ...caveContent
+      ];
+      broadcastMessage = [
+        `回声洞（${caveId}）已由管理员 "${adminUserName}" 拒绝`,
+        ...caveContent
+      ];
+      cleanupPendingDeletions(this.ctx, this.fileManager, this.logger);
     }
-    if (this.config.adminUsers?.length) {
-      this.ctx.broadcast(this.config.adminUsers, broadcastMessage).catch((err) => {
-        this.logger.error(`Failed to broadcast review result for cave ${cave.id}:`, err);
+    if (broadcastMessage && this.config.adminUsers?.length) {
+      await this.ctx.broadcast(this.config.adminUsers, broadcastMessage).catch((err) => {
+        this.logger.error(`广播回声洞（${cave.id}）审核结果失败:`, err);
       });
     }
     return resultMessage;
@@ -645,14 +659,22 @@ 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' 字段设置为主键。
   });
   const fileManager = new FileManager(ctx.baseDir, config, logger);
   const lastUsed = /* @__PURE__ */ new Map();
@@ -674,40 +696,55 @@ function apply(ctx, config) {
       }
       const randomId = candidates[Math.floor(Math.random() * candidates.length)].id;
       const [randomCave] = await ctx.database.get("cave", { ...query, id: randomId });
-      if (randomCave) {
-        updateCooldownTimestamp(session, config, lastUsed);
-        return buildCaveMessage(randomCave, config, fileManager, logger);
-      }
-      return "未能获取到回声洞";
+      updateCooldownTimestamp(session, config, lastUsed);
+      return buildCaveMessage(randomCave, config, fileManager, logger);
     } catch (error) {
       logger.error("随机获取回声洞失败:", error);
+      return "随机获取回声洞失败";
     }
   });
   cave.subcommand(".add [content:text]", "添加回声洞").usage("添加一条回声洞。可以直接发送内容，也可以回复或引用一条消息。").action(async ({ session }, content) => {
+    const savedFileIdentifiers = [];
     try {
-      let sourceElements = session.quote?.elements;
-      if (!sourceElements) {
-        const sourceText = content?.trim();
-        if (sourceText) {
-          sourceElements = import_koishi2.h.parse(sourceText);
-        } else {
-          await session.send("请在一分钟内发送你要添加的内容");
-          const reply = await session.prompt(6e4);
-          if (!reply) return "操作超时，已取消添加";
-          sourceElements = import_koishi2.h.parse(reply);
-        }
+      let sourceElements;
+      if (session.quote?.elements) {
+        sourceElements = session.quote.elements;
+      } else if (content?.trim()) {
+        sourceElements = import_koishi2.h.parse(content);
+      } else {
+        await session.send("请在一分钟内发送你要添加的内容");
+        const reply = await session.prompt(6e4);
+        if (!reply) return "操作超时，已取消添加";
+        sourceElements = import_koishi2.h.parse(reply);
       }
       const scopeQuery = getScopeQuery(session, config);
-      const allCaves = await ctx.database.get("cave", scopeQuery, { fields: ["id"] });
-      const existingIds = new Set(allCaves.map((c) => c.id));
-      let newId = 1;
-      while (existingIds.has(newId)) {
-        newId++;
+      const newId = await getNextCaveId(ctx, scopeQuery);
+      const finalElementsForDb = [];
+      let mediaIndex = 0;
+      async function traverseAndProcess(elements) {
+        for (const el of elements) {
+          const elementType = el.type;
+          if (["image", "video", "audio", "file"].includes(elementType) && 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;
+            }
+            finalElementsForDb.push({ type: elementType, file: fileIdentifier });
+          } else if (elementType === "text" && el.attrs.content?.trim()) {
+            finalElementsForDb.push({ type: "text", content: el.attrs.content.trim() });
+          }
+          if (el.children) await traverseAndProcess(el.children);
+        }
       }
-      const { finalElementsForDb, mediaToDownload } = prepareElementsForStorage(sourceElements, newId, session.channelId, session.userId);
+      __name(traverseAndProcess, "traverseAndProcess");
+      await traverseAndProcess(sourceElements);
       if (finalElementsForDb.length === 0) return "内容为空，已取消添加";
       let userName = session.username;
-      if (config.enableProfile && profileManager) {
+      if (config.enableProfile) {
         userName = await profileManager.getNickname(session.userId) || userName;
       }
       const newCave = {
@@ -720,24 +757,17 @@ function apply(ctx, config) {
         time: /* @__PURE__ */ new Date()
       };
       await ctx.database.create("cave", newCave);
-      try {
-        const downloadPromises = mediaToDownload.map(async (media) => {
-          const response = await ctx.http.get(media.url, { responseType: "arraybuffer", timeout: 3e4 });
-          await fileManager.saveFile(media.fileName, Buffer.from(response));
-        });
-        await Promise.all(downloadPromises);
-      } catch (fileError) {
-        await ctx.database.remove("cave", { id: newId });
-        logger.error("媒体文件存储失败:", fileError);
-        return "添加失败：媒体文件存储失败";
-      }
-      if (newCave.status === "pending" && reviewManager) {
+      if (newCave.status === "pending") {
         reviewManager.sendForReview(newCave);
         return `提交成功，序号为（${newCave.id}）`;
       }
       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 "添加失败，请稍后再试";
     }
   });
@@ -748,7 +778,9 @@ 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) {
@@ -766,14 +798,15 @@ function apply(ctx, config) {
       if (!isOwner && !isAdmin) {
         return "抱歉，你没有权限删除这条回声洞";
       }
-      const caveMessage = await buildCaveMessage(targetCave, config, fileManager, logger);
       await ctx.database.upsert("cave", [{ id, status: "delete" }]);
-      session.send([`已删除`, ...caveMessage]);
-      cleanupPendingDeletions(ctx, fileManager, logger).catch((err) => {
-        logger.error(`删除回声洞（${id}）失败:`, err);
-      });
+      const caveMessage = await buildCaveMessage(targetCave, config, fileManager, logger);
+      cleanupPendingDeletions(ctx, fileManager, logger);
+      return [
+        `以下内容已删除`,
+        ...caveMessage
+      ];
     } catch (error) {
-      logger.error(`标记删除回声洞（${id}）失败:`, error);
+      logger.error(`标记回声洞（${id}）失败:`, error);
       return "删除失败，请稍后再试";
     }
   });

package/package.json

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