koishi-plugin-best-cave 2.0.6 → 2.0.8

package/lib/DataManager.d.ts

@@ -2,9 +2,8 @@ import { Context, Logger } from 'koishi';
 import { FileManager } from './FileManager';
 import { Config } from './index';
 /**
- * 数据管理器 (DataManager)
- * @description
- * 负责处理回声洞数据的导入和导出功能。
+ * @class DataManager
+ * @description 负责处理回声洞数据的导入和导出功能。
  */
 export declare class DataManager {
     private ctx;
@@ -12,27 +11,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,10 @@
 import { Logger } from 'koishi';
 import { Config } from './index';
 /**
- * 文件管理器 (FileManager)
- * @description
- * 封装了对文件（资源）的存储、读取和删除操作。
- * 它能够根据插件配置自动选择使用本地文件系统或 AWS S3 作为存储后端。
- * 内置了基于 Promise 的文件锁，以防止对本地文件的并发写入冲突。
+ * @class FileManager
+ * @description 封装了对文件的存储、读取和删除操作。
+ * 能根据配置自动选择使用本地文件系统或 AWS S3 作为存储后端。
+ * 内置 Promise 文件锁，防止本地文件的并发写入冲突。
  */
 export declare class FileManager {
     private logger;
@@ -14,51 +13,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,36 @@ declare module 'koishi' {
     }
 }
 /**
- * 个人资料管理器 (ProfileManager)
- * @description
- * 负责管理用户在回声洞插件中的自定义昵称。
- * 提供设置、获取和清除昵称的数据库操作和相关命令。
- * 此类仅在插件配置中启用了 `enableProfile` 时才会被实例化。
+ * @class ProfileManager
+ * @description 负责管理用户在回声洞中的自定义昵称。
+ * 当插件配置 `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

@@ -1,12 +1,9 @@
-import { Context, h, Logger } from 'koishi';
+import { Context, Logger } from 'koishi';
 import { CaveObject, Config } from './index';
 import { FileManager } from './FileManager';
 /**
- * 审核管理器 (ReviewManager)
- * @description
- * 负责处理回声洞的审核流程。当 `enableReview` 配置项开启时，
- * 此管理器将被激活，用于处理新回声洞的提交、向管理员发送审核通知
- * 以及处理管理员的审核操作（通过/拒绝）。
+ * @class ReviewManager
+ * @description 负责处理回声洞的审核流程，处理新洞的提交、审核通知和审核操作。
  */
 export declare class ReviewManager {
     private ctx;
@@ -14,36 +11,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。
      * @returns 返回给操作者的确认消息。
      */
-    processReview(action: 'approve' | 'reject', caveId: number, adminUserName: string): Promise<string | (string | h)[]>;
+    processReview(action: 'approve' | 'reject', caveId: number): Promise<string>;
 }

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,13 +27,10 @@ declare module 'koishi' {
         cave: CaveObject;
     }
 }
-/**
- * 插件的配置接口。
- */
 export interface Config {
     coolDown: number;
     perChannel: boolean;
-    adminUsers: string[];
+    adminChannel: string;
     enableProfile: boolean;
     enableIO: boolean;
     enableReview: 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;