koishi-plugin-best-cave 2.0.1 → 2.0.3

package/lib/DataManager.d.ts

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

package/lib/Utils.d.ts

@@ -0,0 +1,79 @@
+import { Context, h, Logger, Session } from 'koishi';
+import { CaveObject, Config, StoredElement } from './index';
+import { FileManager } from './FileManager';
+/**
+ * 将数据库中存储的 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>;
+/**
+ * 构建一条包含回声洞内容的完整消息，准备发送。
+ * 此函数会处理 S3 URL、文件映射路径或本地文件到 Base64 的转换。
+ * @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 实例。
+ */
+export declare function cleanupPendingDeletions(ctx: Context, fileManager: FileManager, logger: Logger): Promise<void>;
+/**
+ * 根据插件配置（是否分群）和当前会话，生成数据库查询所需的范围条件。
+ * @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 - 媒体类型 ('img', 'video', 'audio', 'file')。
+ * @param caveId - 新建回声洞的 ID。
+ * @param index - 媒体在消息中的索引。
+ * @param channelId - 频道 ID。
+ * @param userId - 用户 ID。
+ * @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。
+ */
+export declare function checkCooldown(session: Session, config: Config, lastUsed: Map<string, number>): string | null;
+/**
+ * 更新指定频道的指令使用时间戳。
+ * @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

@@ -41,13 +41,14 @@ declare module 'koishi' {
  * 插件的配置接口。
  */
 export interface Config {
-    cooldown: number;
+    coolDown: number;
     perChannel: boolean;
     adminUsers: string[];
     enableProfile: boolean;
-    enableDataIO: boolean;
+    enableIO: boolean;
     enableReview: boolean;
     caveFormat: string;
+    localPath?: string;
     enableS3: boolean;
     endpoint?: string;
     region?: string;

package/lib/index.js

@@ -298,23 +298,27 @@ async function mediaElementToBase64(element, fileManager, logger2) {
 __name(mediaElementToBase64, "mediaElementToBase64");
 async function buildCaveMessage(cave, config, fileManager, logger2) {
   const caveHElements = storedFormatToHElements(cave.elements);
-  const processedElements = await Promise.all(caveHElements.map(async (element) => {
+  const processedElements = await Promise.all(caveHElements.map((element) => {
     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 = config.publicUrl.endsWith("/") ? `${config.publicUrl}${fileName}` : `${config.publicUrl}/${fileName}`;
-      return (0, import_koishi.h)(element.type, { ...element.attrs, src: fullUrl });
+      return Promise.resolve((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 }));
     }
     return mediaElementToBase64(element, fileManager, logger2);
   }));
   const finalMessage = [];
   const formatString = config.caveFormat;
   const separatorIndex = formatString.indexOf("|");
-  let headerFormat;
-  let footerFormat;
+  let headerFormat, footerFormat;
   if (separatorIndex === -1) {
     headerFormat = formatString;
     footerFormat = "";
@@ -323,14 +327,10 @@ async function buildCaveMessage(cave, config, fileManager, logger2) {
     footerFormat = formatString.substring(separatorIndex + 1);
   }
   const headerText = headerFormat.replace("{id}", cave.id.toString()).replace("{name}", cave.userName);
-  if (headerText.trim()) {
-    finalMessage.push((0, import_koishi.h)("p", {}, headerText));
-  }
+  if (headerText.trim()) finalMessage.push((0, import_koishi.h)("p", {}, headerText));
   finalMessage.push(...processedElements);
   const footerText = footerFormat.replace("{id}", cave.id.toString()).replace("{name}", cave.userName);
-  if (footerText.trim()) {
-    finalMessage.push((0, import_koishi.h)("p", {}, footerText));
-  }
+  if (footerText.trim()) finalMessage.push((0, import_koishi.h)("p", {}, footerText));
   return finalMessage;
 }
 __name(buildCaveMessage, "buildCaveMessage");
@@ -376,20 +376,20 @@ async function downloadMedia(ctx, fileManager, url, originalName, type, caveId,
 }
 __name(downloadMedia, "downloadMedia");
 function checkCooldown(session, config, lastUsed) {
-  if (config.cooldown <= 0 || !session.channelId || config.adminUsers.includes(session.userId)) {
+  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) {
-    const waitTime = Math.ceil((config.cooldown * 1e3 - (now - lastTime)) / 1e3);
+  if (now - lastTime < config.coolDown * 1e3) {
+    const waitTime = Math.ceil((config.coolDown * 1e3 - (now - lastTime)) / 1e3);
     return `指令冷却中，请在 ${waitTime} 秒后重试`;
   }
   return null;
 }
 __name(checkCooldown, "checkCooldown");
 function updateCooldownTimestamp(session, config, lastUsed) {
-  if (config.cooldown > 0 && session.channelId) {
+  if (config.coolDown > 0 && session.channelId) {
     lastUsed.set(session.channelId, Date.now());
   }
 }
@@ -633,24 +633,25 @@ var usage = `
 var logger = new import_koishi3.Logger("best-cave");
 var Config = import_koishi3.Schema.intersect([
   import_koishi3.Schema.object({
-    cooldown: import_koishi3.Schema.number().default(10).description("冷却时间（秒）"),
+    coolDown: import_koishi3.Schema.number().default(10).description("冷却时间（秒）"),
     perChannel: import_koishi3.Schema.boolean().default(false).description("启用分群模式"),
     enableProfile: import_koishi3.Schema.boolean().default(false).description("启用自定义昵称"),
-    enableDataIO: import_koishi3.Schema.boolean().default(false).description("启用导入导出"),
-    adminUsers: import_koishi3.Schema.array(import_koishi3.Schema.string()).default([]).description("管理员 ID 列表"),
-    caveFormat: import_koishi3.Schema.string().default("回声洞 ——（{id}）|—— {name}").required().description("自定义文本(使用|分隔)")
+    enableIO: import_koishi3.Schema.boolean().default(false).description("启用导入导出"),
+    caveFormat: import_koishi3.Schema.string().default("回声洞 ——（{id}）|—— {name}").description("自定义文本"),
+    adminUsers: import_koishi3.Schema.array(import_koishi3.Schema.string()).default([]).description("管理员 ID 列表")
   }).description("基础配置"),
   import_koishi3.Schema.object({
     enableReview: import_koishi3.Schema.boolean().default(false).description("启用审核")
   }).description("审核配置"),
   import_koishi3.Schema.object({
+    localPath: import_koishi3.Schema.string().description("文件映射路径"),
     enableS3: import_koishi3.Schema.boolean().default(false).description("启用 S3 存储"),
-    endpoint: import_koishi3.Schema.string().required().description("端点 (Endpoint)"),
-    bucket: import_koishi3.Schema.string().required().description("存储桶 (Bucket)"),
-    region: import_koishi3.Schema.string().default("auto").description("区域 (Region)"),
     publicUrl: import_koishi3.Schema.string().description("公共访问 URL").role("link"),
-    accessKeyId: import_koishi3.Schema.string().required().description("Access Key ID").role("secret"),
-    secretAccessKey: import_koishi3.Schema.string().required().description("Secret Access Key").role("secret")
+    endpoint: import_koishi3.Schema.string().description("端点 (Endpoint)").role("link"),
+    bucket: import_koishi3.Schema.string().description("存储桶 (Bucket)"),
+    region: import_koishi3.Schema.string().default("auto").description("区域 (Region)"),
+    accessKeyId: import_koishi3.Schema.string().description("Access Key ID").role("secret"),
+    secretAccessKey: import_koishi3.Schema.string().description("Secret Access Key").role("secret")
   }).description("存储配置")
 ]);
 function apply(ctx, config) {
@@ -718,7 +719,7 @@ function apply(ctx, config) {
       const scopeQuery = getScopeQuery(session, config);
       const newId = await getNextCaveId(ctx, scopeQuery);
       const finalElementsForDb = [];
-      let mediaIndex = 1;
+      let mediaIndex = 0;
       async function traverseAndProcess(elements) {
         for (const el of elements) {
           const elementType = el.type === "image" ? "img" : el.type;
@@ -825,7 +826,7 @@ ${caveIds}`;
     profileManager = new ProfileManager(ctx);
     profileManager.registerCommands(cave);
   }
-  if (config.enableDataIO) {
+  if (config.enableIO) {
     dataManager = new DataManager(ctx, config, fileManager, logger);
     dataManager.registerCommands(cave);
   }

package/package.json

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