@xiaozhu2007/koishi-plugin-litematic-renderer 0.5.2 → 0.5.4

package/lib/index.d.ts

@@ -1,59 +1,113 @@
-import { Context, h, Schema, Session } from 'koishi';
+import { Context, h, Schema, Session } from "koishi";
+/** Koishi 插件名称 */
 export declare const name = "litematic-renderer";
+/** 插件可选注入的 Koishi 服务 */
 export declare const inject: {
     optional: string[];
 };
+/** Litematic 渲染插件的完整配置 */
 export interface Config {
+    /** QQ 机器人的接入方式 */
     qqBotType: QqBotType;
+    /** 独立渲染器使用的 Java 可执行文件；为空时自动查找 Java 21 或更高版本 */
     standaloneJavaCommand: string;
+    /** Minecraft 客户端 JAR 或基础资源包路径 */
     minecraftJarPath: string;
+    /** 自定义材质包路径，后面的材质包具有更高优先级 */
     resourcePackPaths: string[];
-    renderEngine: 'standalone' | 'java' | 'webgl' | 'cpu';
+    /** 用于生成投影图的渲染后端 */
+    renderEngine: "standalone" | "java" | "webgl" | "cpu";
+    /** 独立 Java 渲染器 JAR 的路径 */
     standaloneRendererJar: string;
+    /** 独立 Java 渲染任务的超时时间，单位为毫秒 */
     standaloneRenderTimeout: number;
+    /** 独立 Java 渲染器首次运行时的最大堆内存，单位为 MiB */
     standaloneJavaMaxHeapMb: number;
+    /** 内存不足后重试进程的最大堆内存，单位为 MiB */
     standaloneJavaRetryMaxHeapMb: number;
+    /** 检测到内存不足时允许重启 Java 进程的次数 */
     standaloneJavaMemoryRestartLimit: number;
+    /** 自动处理的最大文件大小，单位为 KiB */
     maxFileSize: number;
+    /** 投影声明方块数及所有区域总体积的上限 */
     maxBlocks: number;
+    /** 六面图和 CPU 渲染结果的最长边像素上限 */
     outputSize: number;
+    /** CPU 正二轴测渲染中方块菱形的半宽 */
     isometricCellSize: number;
+    /** PNG 背景颜色，格式为十六进制 RGB */
     background: string;
+    /** 是否将 PNG 背景输出为透明 */
     transparentBackground: boolean;
+    /** 是否默认使用 QQ 合并转发发送渲染结果 */
     sendAsForward: boolean;
+    /** 是否在每张渲染图前显示视图标题 */
     showViewTitles: boolean;
+    /** 是否在结果消息中引用并提及发送者 */
     replyAndMention: boolean;
+    /** 是否为支持的发送方式附加六面正交合成图 */
     sixFaceOverview: boolean;
+    /** 六面正交合成图的排列方向 */
     sixFaceLayout: SixFaceLayout;
+    /** 针对指定群聊覆盖的发送选项 */
     groupSendOptions: GroupSendOption[];
+    /** 文件下载及 WebGL 页面操作的超时时间，单位为毫秒 */
     renderTimeout: number;
+    /** 持久化渲染缓存的目录 */
     cacheDirectory: string;
+    /** 所有版本渲染缓存的总容量上限，单位为 GiB */
     cacheMaxSizeGb: number;
+    /** 聚合渲染诊断信息的 JSON 文件路径 */
     diagnosticsFilePath: string;
+    /** 用于上报渲染异常的 Sentry DSN */
+    sentryDsn: string;
+    /** 是否修复 OneBot 适配器对群文件上传事件的映射 */
     patchOneBotGroupUpload: boolean;
+    /** Fabric Java 渲染桥交换任务文件的目录 */
     javaBridgeDirectory: string;
+    /** 优先调用的外部 GPU 渲染器命令 */
     gpuRendererCommand: string;
+    /** 等待 Fabric Java 渲染桥返回结果的超时时间，单位为毫秒 */
     javaRenderTimeout: number;
+    /** Java 渲染器最终输出图像的边长 */
     javaResolution: number;
+    /** Java 渲染器的离屏超采样倍数 */
     javaSupersampling: number;
-    webglQuality: 'standard' | 'high' | 'ultra';
+    /** WebGL 渲染的质量预设 */
+    webglQuality: "standard" | "high" | "ultra";
+    /** WebGL 单张渲染图的宽度 */
     webglWidth: number;
+    /** WebGL 单张渲染图的高度 */
     webglHeight: number;
+    /** 是否将 WebGL 正二轴测结果裁成正方形 */
     isometricSquare: boolean;
+    /** 正二轴测主体在画布中的最大占比 */
     isometricFill: number;
+    /** 正二轴测视图绕竖直轴旋转的角度 */
     isometricRotation: number;
+    /** 正二轴测视图的俯仰角 */
     isometricSlant: number;
 }
-export type SendMode = 'forward' | 'combined';
-export type ReplyAndMentionOverride = 'inherit' | 'enabled' | 'disabled';
-export type SixFaceLayout = 'horizontal' | 'vertical';
-export type QqBotType = 'official' | 'selfHosted';
+/** 自建 QQ 中发送多张渲染图的方式 */
+export type SendMode = "forward" | "combined";
+/** 群聊是否覆盖全局的引用及提及设置 */
+export type ReplyAndMentionOverride = "inherit" | "enabled" | "disabled";
+/** 六面正交合成图的排列方向 */
+export type SixFaceLayout = "horizontal" | "vertical";
+/** QQ 机器人的接入方式 */
+export type QqBotType = "official" | "selfHosted";
+/** 指定群聊的消息发送覆盖项 */
 export interface GroupSendOption {
+    /** 要应用覆盖设置的 QQ 群号 */
     groupId: string;
+    /** 多张渲染图的发送方式 */
     sendMode: SendMode;
+    /** 引用及提及行为相对于全局配置的覆盖方式 */
     replyAndMention: ReplyAndMentionOverride;
 }
+/** Koishi 控制台使用的插件配置模式 */
 export declare const Config: Schema<Config>;
+/** 来自 Koishi 或 OneBot 事件的兼容文件元素 */
 interface FileElement {
     name?: string;
     filename?: string;
@@ -68,70 +122,259 @@ interface FileElement {
     fileId?: string;
     busid?: string | number;
 }
+/** 投影中的非空气方块及其世界坐标 */
 interface Block {
     x: number;
     y: number;
     z: number;
     name: string;
 }
+/** 已写入磁盘、可发送给会话的渲染图 */
 interface ImageResult {
     title: string;
     path: string;
 }
+/** 从 Litematic 根标签中提取的展示元数据 */
 export interface LitematicMetadata {
+    /** 创建投影的游戏 ID，缺失时为“未知” */
     author: string;
+    /** 格式化后的创建时间，使用中国标准时间 */
     createdAt: string;
+    /** 文件声明的非空气方块总数 */
     totalBlocks?: number;
+    /** 文件声明的区域总体积 */
     totalVolume?: number;
+    /** 投影包围盒在 X、Y、Z 轴上的尺寸 */
     size?: [number, number, number];
+    /** Litematic 文件格式版本 */
     litematicVersion?: number;
+    /** Minecraft 数据版本号 */
     minecraftDataVersion?: number;
+    /** 由数据版本号推断出的 Minecraft 版本 */
     minecraftVersion?: string;
 }
+/**
+ * 注册 Litematic 文件监听、中间件、命令、缓存和诊断端点
+ *
+ * @param ctx - 当前 Koishi 上下文
+ * @param config - 插件配置
+ * @returns 无返回值
+ */
 export declare function apply(ctx: Context, config: Config): void;
+/**
+ * 为影响渲染结果的配置生成稳定的短哈希
+ *
+ * @param configuration - 可被 JSON 序列化的渲染配置
+ * @returns SHA-256 摘要的前 16 个十六进制字符
+ */
 export declare function hashRenderConfiguration(configuration: unknown): string;
+/** OneBot 适配器源码兼容补丁的处理结果 */
 interface SourcePatchResult {
+    /** 处理后的适配器源码 */
     source: string;
+    /** 本次处理是否修改了源码 */
     changed: boolean;
+    /** 原始源码是否已经支持群文件上传事件 */
     alreadyCompatible: boolean;
 }
+/**
+ * 恢复特定 OneBot 适配器版本中被注释的群文件上传事件映射
+ *
+ * @remarks
+ * 如果源码已经兼容或无法识别预期代码块，函数会原样返回源码
+ *
+ * @param source - OneBot 适配器编译后的 JavaScript 源码
+ * @returns 补丁后的源码以及是否修改、是否已兼容的状态
+ */
 export declare function patchOneBotAdapterSource(source: string): SourcePatchResult;
+/**
+ * 从投影文件名生成跨平台安全的缓存名称片段
+ *
+ * @param filename - 原始投影文件名或路径
+ * @returns 移除扩展名和非法字符后、最长 80 个字符的名称
+ */
 export declare function cacheNameSegment(filename: string): string;
+/**
+ * 按最近最少使用顺序删除缓存条目，直至容量不超过限制
+ *
+ * @param cacheDirectory - 包含版本子目录的缓存根目录
+ * @param maxBytes - 允许保留的最大总字节数
+ * @param protectedDirectory - 本轮清理中不得删除的缓存条目
+ * @returns 清理后的总字节数、删除字节数和删除条目数
+ * @throws 无法读取或删除缓存内容时抛出文件系统错误
+ */
 export declare function enforceCacheLimit(cacheDirectory: string, maxBytes: number, protectedDirectory?: string): Promise<{
     totalBytes: number;
     removedBytes: number;
     removedEntries: number;
 }>;
-type FileSession = Pick<Session, 'elements' | 'content'> & {
+/** 查找上传文件所需的最小会话数据 */
+type FileSession = Pick<Session, "elements" | "content"> & {
     event?: unknown;
     _data?: unknown;
     data?: unknown;
     message?: unknown;
 };
+/**
+ * 在 Koishi 会话元素及常见适配器原始事件字段中查找 Litematic 文件
+ *
+ * @param session - 包含消息元素或适配器原始数据的会话
+ * @returns 首个识别出的 `.litematic` 文件；未找到时返回 `undefined`
+ */
 export declare function findLitematicFile(session: FileSession): FileElement | undefined;
+/**
+ * 判断 Java 主版本是否满足独立渲染器的最低要求
+ *
+ * @param version - Java 主版本号；检测失败时为 `undefined`
+ * @returns 版本为 21 或更高时返回 `true`
+ */
 export declare function supportsStandaloneJavaVersion(version: number | undefined): boolean;
+/**
+ * 生成独立 Java 渲染进程使用的 JVM 内存和垃圾回收参数
+ *
+ * @param maxHeapMb - 请求的最大堆内存，单位为 MiB
+ * @returns 最大堆被限制在 128 到 32768 MiB 范围内的 JVM 参数
+ */
 export declare function standaloneJvmOptions(maxHeapMb: number): string[];
+/**
+ * 根据退出码和标准错误判断 Java 进程是否因内存不足而失败
+ *
+ * @param output - Java 进程的标准错误输出
+ * @param exitCode - Java 进程退出码
+ * @returns 输出包含常见内存错误或退出码为 137 时返回 `true`
+ */
 export declare function isJavaMemoryFailure(output: string, exitCode?: number | null): boolean;
-export declare function formatRenderError(error: unknown, config: Pick<Config, 'maxFileSize'>): string;
+/**
+ * 将单次独立渲染诊断合并到插件级诊断文件
+ *
+ * @remarks
+ * 相同方块问题会累加计数并最多保留 20 个样本，相同渲染错误也会累加计数
+ *
+ * @param output - 包含 `render-diagnostics.json` 的渲染输出目录
+ * @param destination - 插件级诊断 JSON 文件路径
+ * @param logger - 用于报告新增诊断类别的 Koishi 日志器
+ * @returns 无诊断内容时直接解决，否则在合并文件写入后解决
+ * @throws 无法读取或写入诊断文件时抛出文件系统错误
+ */
+export declare function mergeRenderDiagnostics(output: string, destination: string, logger: ReturnType<Context["logger"]>): Promise<void>;
+/**
+ * 将内部渲染错误转换为不泄露本地路径的用户提示
+ *
+ * @param error - 捕获到的任意错误值
+ * @param config - 格式化文件大小提示所需的配置
+ * @returns 可直接发送给用户的中文错误消息
+ */
+export declare function formatRenderError(error: unknown, config: Pick<Config, "maxFileSize">): string;
+/** 已结合全局配置和群聊覆盖项的最终发送选项 */
 export interface ResolvedSendOptions {
+    /** 当前 QQ 机器人的接入方式 */
     qqBotType: QqBotType;
+    /** 多张图片的发送方式 */
     sendMode: SendMode;
+    /** 是否引用并按平台能力提及发送者 */
     replyAndMention: boolean;
+    /** 是否在图片前显示视图标题 */
     showViewTitles: boolean;
+    /** 是否生成并发送六面正交合成图 */
     sixFaceOverview: boolean;
 }
-type SendConfig = Pick<Config, 'sendAsForward' | 'replyAndMention' | 'groupSendOptions'> & Partial<Pick<Config, 'qqBotType' | 'showViewTitles' | 'sixFaceOverview'>>;
+/** 解析消息发送选项所需的配置子集 */
+type SendConfig = Pick<Config, "sendAsForward" | "replyAndMention" | "groupSendOptions"> & Partial<Pick<Config, "qqBotType" | "showViewTitles" | "sixFaceOverview">>;
+/**
+ * 合并全局发送配置与指定群聊最后一条匹配的覆盖项
+ *
+ * @param config - 全局发送配置及群聊覆盖项
+ * @param groupId - 当前 QQ 群号
+ * @returns 适用于当前会话的最终发送选项
+ */
 export declare function resolveSendOptions(config: SendConfig, groupId?: string): ResolvedSendOptions;
+/**
+ * 根据 QQ 接入类型和发送模式发送渲染图及投影元数据
+ *
+ * @remarks
+ * 官方 QQ 会先将所有图片合成为一张总览图，自建 QQ 支持合并转发或联合消息
+ *
+ * @param session - 接收渲染结果的 Koishi 会话
+ * @param images - 已写入磁盘的渲染图片
+ * @param metadata - 格式化后的投影元数据
+ * @param options - 已解析的发送选项
+ * @param projectionName - 在成功消息中展示的投影名称
+ * @returns 所有图片和元数据发送完成后解决的 Promise
+ * @throws 图片读取、合成或消息发送失败时抛出错误
+ */
 export declare function sendImages(session: Session, images: ImageResult[], metadata: string, options: ResolvedSendOptions, projectionName?: string): Promise<void>;
+/**
+ * 将轴测图和可选六面图排版为官方 QQ 使用的单张总览 PNG
+ *
+ * @param images - 要合成的磁盘 PNG 图片
+ * @returns 写入首张图片所在目录的总览图绝对路径
+ * @throws 图片列表为空、图片无效或文件系统操作失败时抛出错误
+ */
 export declare function composeQqOverview(images: ImageResult[]): Promise<string>;
+/**
+ * 创建适合当前 QQ 接入方式的引用和提及消息元素
+ *
+ * @param session - 要回复的 Koishi 会话
+ * @param qqBotType - QQ 机器人接入方式
+ * @returns 官方 QQ 最多包含引用，自建 QQ 还会包含发送者提及
+ */
 export declare function replyElements(session: Session, qqBotType?: QqBotType): h[];
+/**
+ * 从 Litematic 文件读取展示和限制校验所需的元数据
+ *
+ * @param data - Gzip 压缩或未压缩的 Litematic NBT 数据
+ * @returns 规范化的作者、时间、尺寸和版本信息
+ * @throws 数据不是有效 NBT 或包含不支持的标签类型时抛出错误
+ */
 export declare function parseLitematicMetadata(data: Buffer): LitematicMetadata;
+/**
+ * 校验文件声明值及每个区域的实际总体积是否超过资源限制
+ *
+ * @remarks
+ * 无效的自定义限制会回退为 5000000，区域体积使用绝对尺寸计算
+ *
+ * @param data - 原始 Litematic NBT 数据
+ * @param metadata - 预先解析的 Litematic 元数据
+ * @param configuredLimit - 允许的方块数和总体积上限
+ * @returns 校验通过时无返回值
+ * @throws 声明值、区域总体积或计算结果超过限制时抛出错误
+ */
 export declare function validateProjectionLimits(data: Buffer, metadata: LitematicMetadata, configuredLimit?: number): void;
+/**
+ * 将 Litematic 元数据格式化为适合聊天消息展示的多行文本
+ *
+ * @param metadata - 已解析的 Litematic 元数据
+ * @param filename - 可选的源文件名，用于显示投影名称
+ * @returns 包含作者、时间、数量、尺寸及版本的中文文本
+ */
 export declare function formatLitematicMetadata(metadata: LitematicMetadata, filename?: string): string;
+/**
+ * 解析 Litematic 所有区域中的非空气方块
+ *
+ * @param data - Gzip 压缩或未压缩的 Litematic NBT 数据
+ * @returns 带世界坐标和方块名称的非空气方块列表
+ * @throws 文件缺少区域数据或不包含非空气方块时抛出错误
+ */
 export declare function parseLitematic(data: Buffer): Block[];
+/**
+ * 使用内置 CPU 栅格器生成正向和反向轴测 PNG
+ *
+ * @param blocks - 要渲染的非空气方块
+ * @param config - 控制尺寸、背景和方块比例的插件配置
+ * @returns 两张带固定文件名的内存 PNG
+ */
 export declare function renderSchematic(blocks: Block[], config: Config): {
     title: string;
     png: Buffer<ArrayBuffer>;
 }[];
+/**
+ * 将投影的上下东西南北视图合成为一张正交总览 PNG
+ *
+ * @param blocks - 要投影的非空气方块
+ * @param config - 控制输出尺寸和背景的插件配置
+ * @param layout - 六张视图采用横向 3×2 或纵向 2×3 排列
+ * @returns 包含六个方向标签的 PNG 数据
+ * @throws 方块列表为空时抛出错误
+ */
 export declare function renderSixFaceOverview(blocks: Block[], config: Config, layout?: SixFaceLayout): Buffer<ArrayBuffer>;
 export {};