@yunzai-ng/core 0.1.0

package/dist/plugin/tar.js

@@ -0,0 +1,277 @@
+/**
+ * 模块职责：tar.gz 解包 —— 把内存中的归档解到目标目录，并在解包阶段执行路径与体积校验
+ * 依赖方向：仅依赖 node 标准库与 `util/fs` 的越界校验；不认识插件市场，也不发起网络请求
+ * 生命周期：纯函数，无状态
+ * 注意事项：该实现不引入第三方解包库。插件市场需要在 Windows 与 Termux 上以相同方式
+ *          解包 GitHub 归档，而现有的 tar 实现均带原生模块或较大的依赖树；
+ *          归档格式本身只有 512 字节定长头部一种结构，自行解析的成本低于引入依赖。
+ *
+ *          解包被视为处理不可信输入。三项校验在写盘之前完成：
+ *          1) 每个条目的目标路径经 `safeJoin` 求值，越出目标目录即丢弃该条目；
+ *          2) 符号链接与硬链接条目一律丢弃 —— 归档可借链接把后续写入导向目录之外，
+ *             而插件分发不需要链接；
+ *          3) 解包后总字节数与条目数均设上限，避免高压缩比归档耗尽磁盘。
+ */
+import { gunzipSync, gzipSync } from "node:zlib";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { safeJoin } from "../util/fs.js";
+/** tar 块大小 */
+const BLOCK = 512;
+/** 头部各字段的偏移与长度 */
+const FIELD = {
+    name: [0, 100],
+    size: [124, 12],
+    typeflag: [156, 1],
+    prefix: [345, 155]
+};
+/** 解包后总字节数的缺省上限 */
+const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+/** 条目数的缺省上限 */
+const DEFAULT_MAX_ENTRIES = 20_000;
+/**
+ * 按 NUL 截断并去除首尾空白
+ * @param buf 归档缓冲
+ * @param offset 起始偏移
+ * @param length 字段长度
+ * @returns 字段文本
+ */
+function textAt(buf, offset, length) {
+    const slice = buf.subarray(offset, offset + length);
+    const end = slice.indexOf(0);
+    return Buffer.from(end === -1 ? slice : slice.subarray(0, end))
+        .toString("utf8")
+        .trim();
+}
+/**
+ * 读取一个八进制数值字段
+ *
+ * 体积字段在超过 8GiB 时会改用 base-256 编码（首字节最高位置 1）。插件归档不会
+ * 触及该量级，因此这里遇到 base-256 直接判为非法，而不是实现一段无从验证的分支。
+ * @param buf 归档缓冲
+ * @param offset 起始偏移
+ * @param length 字段长度
+ * @returns 数值
+ * @throws 字段为 base-256 编码或不是合法八进制时
+ */
+function octalAt(buf, offset, length) {
+    const first = buf[offset] ?? 0;
+    if ((first & 0x80) !== 0)
+        throw new Error("归档使用了 base-256 数值字段，超出支持范围");
+    const text = textAt(buf, offset, length);
+    if (text === "")
+        return 0;
+    const value = Number.parseInt(text, 8);
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`归档头部的数值字段非法：${text}`);
+    return value;
+}
+/**
+ * 判断一个块是否全为零字节
+ * @param buf 归档缓冲
+ * @param offset 块起始偏移
+ * @returns 是否为结束块
+ */
+function isZeroBlock(buf, offset) {
+    for (let i = offset; i < offset + BLOCK; i++)
+        if (buf[i] !== 0)
+            return false;
+    return true;
+}
+/**
+ * 解析一个头部块
+ * @param buf 归档缓冲
+ * @param offset 块起始偏移
+ * @returns 头部信息
+ */
+function readHeader(buf, offset) {
+    const name = textAt(buf, offset + FIELD.name[0], FIELD.name[1]);
+    const prefix = textAt(buf, offset + FIELD.prefix[0], FIELD.prefix[1]);
+    return {
+        path: prefix === "" ? name : `${prefix}/${name}`,
+        size: octalAt(buf, offset + FIELD.size[0], FIELD.size[1]),
+        type: textAt(buf, offset + FIELD.typeflag[0], FIELD.typeflag[1]) || "0"
+    };
+}
+/**
+ * 从 pax 扩展头部中取出 `path` 记录
+ *
+ * 记录格式为 `长度 键=值\n`，长度含自身。仅取 `path`，其余记录（权限、时间）
+ * 与插件分发无关。
+ * @param block 扩展头部的内容
+ * @returns 路径；未声明时 undefined
+ */
+function paxPath(block) {
+    const text = Buffer.from(block).toString("utf8");
+    const match = /\d+ path=([^\n]*)\n/.exec(text);
+    return match?.[1];
+}
+/**
+ * 剥离路径的前若干层
+ * @param path 归档内路径
+ * @param strip 剥离层数
+ * @returns 剥离后的相对路径；剥空时为空串
+ */
+function stripPath(path, strip) {
+    if (strip <= 0)
+        return path;
+    const parts = path.split("/").filter(part => part !== "");
+    return parts.slice(strip).join("/");
+}
+/**
+ * 把归档条目写入目标目录
+ *
+ * 目标目录会被按需创建。返回值为实际写入的相对路径列表，供调用方在日志中说明
+ * 安装内容，也便于单元测试断言。
+ * @param archive gzip 压缩后的 tar 归档
+ * @param dest 目标目录绝对路径
+ * @param opts 解包选项
+ * @returns 实际写入的相对路径列表
+ * @throws 归档结构非法、超出体积或条目上限时
+ */
+export async function extractTarGz(archive, dest, opts = {}) {
+    const buf = gunzipSync(archive);
+    const strip = opts.strip ?? 0;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const written = [];
+    let total = 0;
+    let entries = 0;
+    /** 由 pax 或 GNU 长名头部预告的下一条目路径 */
+    let pendingPath;
+    let offset = 0;
+    while (offset + BLOCK <= buf.length) {
+        if (isZeroBlock(buf, offset))
+            break;
+        const header = readHeader(buf, offset);
+        offset += BLOCK;
+        const contentBlocks = Math.ceil(header.size / BLOCK);
+        const content = buf.subarray(offset, offset + header.size);
+        offset += contentBlocks * BLOCK;
+        // 扩展头部本身不落盘，只影响下一个条目的路径
+        if (header.type === "x" || header.type === "X") {
+            pendingPath = paxPath(content);
+            continue;
+        }
+        if (header.type === "L") {
+            pendingPath = Buffer.from(content).toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        // 全局头部与链接条目一律丢弃，理由见文件头
+        if (header.type === "g" || header.type === "1" || header.type === "2") {
+            pendingPath = undefined;
+            continue;
+        }
+        const rawPath = pendingPath ?? header.path;
+        pendingPath = undefined;
+        const rel = stripPath(rawPath, strip);
+        if (rel === "")
+            continue;
+        if (++entries > maxEntries)
+            throw new Error(`归档条目数超过上限 ${maxEntries}`);
+        total += header.size;
+        if (total > maxBytes)
+            throw new Error(`归档解包后体积超过上限 ${maxBytes} 字节`);
+        let target;
+        try {
+            target = safeJoin(dest, rel);
+        }
+        catch {
+            // 越界条目直接跳过：归档由第三方提供，不应因其内容异常而中断整次安装，
+            // 但也绝不能按其要求写到目标目录之外
+            continue;
+        }
+        if (header.type === "5") {
+            await mkdir(target, { recursive: true });
+            continue;
+        }
+        if (header.type !== "0")
+            continue;
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        written.push(rel);
+    }
+    return written;
+}
+/**
+ * 判断目录内是否只有一个顶层目录
+ *
+ * GitHub 的归档统一带一层 `仓库名-提交号/` 包装，而用户自建的归档可能没有。
+ * 调用方据此决定 `strip` 取 0 还是 1。
+ * @param paths 归档内的相对路径列表
+ * @returns 唯一的顶层目录名；不唯一或存在顶层文件时 undefined
+ */
+export function singleRoot(paths) {
+    const roots = new Set();
+    for (const path of paths) {
+        const first = path.split("/")[0] ?? "";
+        if (first === path)
+            return undefined;
+        roots.add(first);
+    }
+    return roots.size === 1 ? [...roots][0] : undefined;
+}
+/**
+ * 拼一个位于目标目录内的路径，越界时抛错
+ *
+ * 供插件市场在删除前复核目标路径，语义与解包阶段一致。
+ * @param base 基准目录
+ * @param name 名称
+ * @returns 绝对路径
+ * @throws 越界时
+ */
+export function joinWithin(base, name) {
+    return safeJoin(base, name);
+}
+/** 供测试与调用方复用的块大小 */
+export const TAR_BLOCK_SIZE = BLOCK;
+/**
+ * 构造一个 tar 头部块
+ *
+ * 该函数只在测试与自建归档时使用；生产路径只解包不打包。之所以放在本文件而不是
+ * 测试文件里，是为了让头部字段的偏移只有一份定义 —— 打包与解包共用 `FIELD`，
+ * 偏移写错时两侧同时失败，不会出现"测试自己造的归档能解、真实归档不能解"。
+ * @param path 条目路径
+ * @param size 内容字节数
+ * @param type 类型标记
+ * @returns 512 字节头部
+ */
+export function buildTarHeader(path, size, type) {
+    const block = Buffer.alloc(BLOCK);
+    block.write(path.slice(0, FIELD.name[1]), FIELD.name[0], "utf8");
+    block.write(`${size.toString(8).padStart(11, "0")}\0`, FIELD.size[0], "ascii");
+    block.write("0000644\0", 100, "ascii");
+    block.write("0000000\0", 108, "ascii");
+    block.write("0000000\0", 116, "ascii");
+    block.write(`${Math.floor(Date.now() / 1000).toString(8).padStart(11, "0")}\0`, 136, "ascii");
+    block.write(type, FIELD.typeflag[0], "ascii");
+    block.write("ustar\0" + "00", 257, "ascii");
+    // 校验和字段先填空格再求和，这是格式规定的计算方式
+    block.write("        ", 148, "ascii");
+    let sum = 0;
+    for (const byte of block)
+        sum += byte;
+    block.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+    return block;
+}
+/**
+ * 把若干文件打成 gzip 压缩的 tar 归档
+ * @param files 条目列表，路径使用正斜杠
+ * @returns 压缩后的归档
+ */
+export function buildTarGz(files) {
+    const parts = [];
+    for (const file of files) {
+        const content = typeof file.content === "string" ? Buffer.from(file.content, "utf8") : Buffer.from(file.content);
+        const type = file.type ?? "0";
+        parts.push(buildTarHeader(file.path, type === "5" ? 0 : content.length, type));
+        if (type !== "5" && content.length > 0) {
+            const padded = Buffer.alloc(Math.ceil(content.length / BLOCK) * BLOCK);
+            content.copy(padded);
+            parts.push(padded);
+        }
+    }
+    parts.push(Buffer.alloc(BLOCK * 2));
+    return gzipSync(Buffer.concat(parts));
+}
+//# sourceMappingURL=tar.js.map

package/dist/plugin/tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.js","sourceRoot":"","sources":["../../src/plugin/tar.ts"],"names":[],"mappings":"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"}

package/dist/render/registry.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 模块职责：渲染注册表 —— 实现 `RenderSink`，管理渲染器插件并择一执行渲染
+ * 依赖方向：依赖类型包、plugin/hooks 的接缝定义、util/*；**不认识 puppeteer**
+ * 生命周期：随内核创建；每个渲染器随提供方插件卸载而摘除；`stop()` 关闭全部渲染器
+ * 注意事项：内核对「怎么把 HTML 变成图片」零认知，只做三件事：择一可用者、补齐全局默认值、
+ *          失败时指明失败方。四项刻意的选择：
+ *
+ *          **`available()` 的结果要缓存。** 它的实现可能是探测 Chromium 是否存在这类几十毫秒的
+ *          磁盘操作，每渲染一张图探一次会计进每条消息的响应时间。故按 TTL 缓存，且**探测本身
+ *          单例化** —— 十条消息同时请求渲染不该产生十次并发探测。
+ *
+ *          **失败后立即让可用性缓存作废。** 浏览器崩溃这件事必须在下一次渲染时被发现。不可用
+ *          状态的 TTL 更短：使用者刚装好 Chromium，不该再等一分钟。
+ *
+ *          **只在「该渲染器整体不可用」时切换**，此前先重试同一个。`render.retry` 的语义是本次
+ *          渲染重试几次（浏览器繁忙、页面偶发超时）。全部失败时把每个渲染器的原因**逐条**汇总
+ *          抛出 —— 只报最后一个的话，真实原因常在第一个里。
+ *
+ *          **此处不限并发。** 同时渲染多张图会不会耗尽内存，取决于渲染器自己页面池的大小，
+ *          只有渲染器插件知道那个数。内核再加一层信号量只会与插件内部的池互相干扰。
+ */
+import type { Disposer, Logger, RenderDoneInfo, RenderRequest, RenderResult, RendererProvider } from "@yunzai-ng/types";
+import type { RenderSink } from "../plugin/hooks.js";
+/** 渲染相关的配置视图（对应配置项 `render.*`） */
+export interface RenderPolicy {
+    /** 首选渲染器 id，对应 `render.default` */
+    readonly default: string;
+    /** 单次渲染超时（毫秒） */
+    readonly timeout: number;
+    /** 渲染失败重试次数 */
+    readonly retry: number;
+    /** 图片质量 0-100 */
+    readonly quality: number;
+    /** 缩放倍率 */
+    readonly scale: number;
+}
+/** 渲染器的对外描述（WebUI "渲染" 页面的数据来源） */
+export interface RendererInfo {
+    /** 渲染器 id */
+    readonly id: string;
+    /** 展示名 */
+    readonly name: string;
+    /** 提供方插件名 */
+    readonly owner: string;
+    /** 是否为当前首选 */
+    readonly preferred: boolean;
+    /** 最近判定的可用性；从未判定过时 undefined */
+    readonly available: boolean | undefined;
+    /** 最近失败原因 */
+    readonly lastError: string | undefined;
+    /** 累计成功次数 */
+    readonly succeeded: number;
+    /** 累计失败次数 */
+    readonly failed: number;
+}
+/** 渲染注册表构造参数 */
+export interface RenderRegistryOptions {
+    /** 基础日志器 */
+    readonly logger: Logger;
+    /**
+     * 取当前渲染配置
+     *
+     * 取函数而非直接传值：`render.*` 在 WebUI 里随时可改，配置存储会就地更新，
+     * 缓存一份快照就意味着"改了配置要重启才生效"。
+     */
+    readonly policy: () => RenderPolicy;
+    /**
+     * 一次渲染结束后的通知（成功或全部渲染器失败）
+     *
+     * 取回调而非直接传 `CoreEventBus`：本文件对渲染实现零认知，认识事件总线
+     * 就等于认识插件系统。回调由 `installRuntime` 传入 —— 它本来就持有总线。
+     *
+     * 省略即不通知，现有调用方（含测试）因此无须改动。
+     */
+    readonly onDone?: (info: RenderDoneInfo) => void;
+}
+/**
+ * 渲染注册表
+ *
+ * 既是 `ctx.registerRenderer()` 的落点，也是 `ctx.render()` / `e.render()` 的执行处。
+ */
+export declare class RenderRegistry implements RenderSink {
+    #private;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts: RenderRegistryOptions);
+    /** 已注册的渲染器数量 */
+    get size(): number;
+    /**
+     * 注册一个渲染器
+     * @param provider 渲染器实现
+     * @param owner 提供方插件名
+     * @returns 注销句柄
+     * @throws 该 id 已被别的插件占用时
+     */
+    register(provider: RendererProvider, owner: string): Disposer;
+    /**
+     * 执行一次渲染
+     * @param req 渲染请求（模板根等已由插件上下文补全）
+     * @returns 渲染结果
+     * @throws 没有任何渲染器、没有可用渲染器、或全部渲染器都失败时
+     */
+    render(req: RenderRequest): Promise<RenderResult>;
+    /**
+     * 列出已注册的渲染器
+     * @returns 渲染器描述数组，首选排在最前
+     */
+    list(): RendererInfo[];
+    /**
+     * 摘除某插件注册的全部渲染器
+     *
+     * 兜底路径：插件上下文正常会逐条调用 Disposer，但插件 setup 中途抛错时
+     * 可能存在未经 ctx 的登记。
+     * @param owner 插件名
+     * @returns 摘除的条数
+     */
+    removePlugin(owner: string): number;
+    /**
+     * 关闭全部渲染器（停机时调用）
+     *
+     * 会等待插件卸载时那些"发出去就不管"的 `dispose()` 收尾 —— 否则进程退出时
+     * 可能留下没杀掉的 Chromium 子进程。
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/render/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/render/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAcpD,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,iBAAiB;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,eAAe;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iBAAiB;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,WAAW;IACX,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAsBD,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,aAAa;IACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,UAAU;IACV,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,aAAa;IACb,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,cAAc;IACd,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,aAAa;IACb,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,aAAa;IACb,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,aAAa;IACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,YAAY;IACZ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,YAAY,CAAA;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACjD;AAWD;;;;GAIG;AACH,qBAAa,cAAe,YAAW,UAAU;;IAY/C;;OAEG;gBACS,IAAI,EAAE,qBAAqB;IAMvC,gBAAgB;IAChB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IA0B7D;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAqFvD;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IActB;;;;;;;OAOG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAWnC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAgH5B"}