@yunzai-ng/core 0.1.0

package/dist/platform/system.js

@@ -0,0 +1,242 @@
+/**
+ * 模块职责：探测本机的磁盘与 GPU —— 概览页两个进度组件的数据来源
+ * 依赖方向：仅依赖 node 内置模块与本目录的 detect；不认识 HTTP，也不认识面板
+ * 生命周期：无状态函数 + 一份短命缓存；缓存生存期见 `CACHE_MS`
+ * 注意事项：**CPU 与内存不在本模块。** 那两项已在 `sampleUsage()` 里并随 `GET /api/overview`
+ *          发给面板；此处再供一份就是同一事实的第二个来源，采样时刻还不同 —— 面板上会出现
+ *          「CPU 卡片和 CPU 环不是一个数」。四个不显而易见的决定：
+ *
+ *          **磁盘走 `fs.statfs`，不调外部命令。** Windows 上 `Get-CimInstance` 实测约 813ms，
+ *          而 `statfs` 逐盘合计 3ms、字节数一致 —— 差两个数量级是因为起一个 PowerShell 进程就要
+ *          半秒，而这个端点被 5 秒一次地轮询。
+ *
+ *          **「有几个分区」按平台分别回答。** Windows 探盘符；Linux 与安卓读 `/proc/mounts` 只留
+ *          真实块设备；macOS 与未知系统只报 `/` —— 为一个进度条搬 `getmntinfo` 不值得。
+ *
+ *          **GPU 只认 nvidia-smi，取不到就当没有这件事。** 测不到时**不返回 `gpus` 字段**而非
+ *          返回空数组：空数组会被前端读成「确实有 0 块显卡」，而 0% 会被读成「GPU 空闲」。
+ *
+ *          **`nvidia-smi` 不存在这件事只查一次。** 没有 N 卡的机器上每 5 秒 spawn 一个必然
+ *          ENOENT 的进程，一天是一万七千次。
+ */
+import { constants as fsConstants } from "node:fs";
+import { access, readFile, statfs } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { detectPlatform } from "./detect.js";
+/**
+ * 快照缓存生存期
+ *
+ * 取 4 秒而非 5 秒：面板按 5 秒轮询，缓存若与轮询同为 5 秒，两个周期的相位差会让
+ * 每隔几次出现一次「这次读的是上一次的数」。比轮询间隔短一点，则每次轮询必然重新采。
+ */
+const CACHE_MS = 4000;
+/** 探测盘符的范围，理由同 server/browse.ts：A、B 是软驱字母 */
+const DRIVE_LETTERS = "CDEFGHIJKLMNOPQRSTUVWXYZ";
+/** 最多报告几个分区 */
+const MAX_DISKS = 12;
+/** nvidia-smi 的超时毫秒 */
+const GPU_TIMEOUT_MS = 3000;
+/**
+ * `/proc/mounts` 里不当作「分区」的文件系统类型
+ *
+ * squashfs 是 snap 包的只读镜像，一台装了十几个 snap 的 Ubuntu 上会有十几条，
+ * 且每条都「100% 已用」—— 那是只读镜像的常态，不是磁盘快满了。
+ */
+const PSEUDO_FS = new Set(["squashfs", "iso9660", "ramfs", "tmpfs", "devtmpfs", "overlay", "aufs"]);
+/** 上一次快照与其采样时刻 */
+let cache;
+/** 是否已确认本机没有 nvidia-smi，见文件头第 4 条 */
+let noNvidiaSmi = false;
+/**
+ * 列举现有的盘符
+ *
+ * Node 没有列举盘符的 API，只能逐个字母试。`access` 而非 `statfs`：后者在未插盘的
+ * 读卡器上会等到超时，前者只问「能不能访问」。
+ * @returns 形如 `C:\` 的盘根数组，按字母升序
+ */
+export async function listDriveRoots() {
+    const probes = [...DRIVE_LETTERS].map(async (letter) => {
+        const root = `${letter}:\\`;
+        try {
+            await access(root, fsConstants.R_OK);
+            return root;
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const found = await Promise.all(probes);
+    return found.filter((root) => root !== undefined);
+}
+/**
+ * 从 `/proc/mounts` 里挑出真实分区的挂载点
+ *
+ * 只留设备名以 `/` 开头的行：那是真实块设备，从而一举排除 proc、sysfs、cgroup、
+ * devpts 等一切伪文件系统 —— 逐个列举它们的名字迟早会漏。再按类型排掉只读镜像
+ * （见 `PSEUDO_FS`），并按挂载点去重（bind mount 会让同一处出现两次）。
+ * @returns 挂载点数组；读不到该文件时为空
+ */
+async function readMountPoints() {
+    let text;
+    try {
+        text = await readFile("/proc/mounts", "utf8");
+    }
+    catch {
+        return [];
+    }
+    const seen = new Set();
+    for (const line of text.split("\n")) {
+        const [device, rawMount, fstype] = line.split(/\s+/);
+        if (device === undefined || rawMount === undefined || fstype === undefined)
+            continue;
+        if (!device.startsWith("/"))
+            continue;
+        if (PSEUDO_FS.has(fstype))
+            continue;
+        // /proc/mounts 用八进制转义空格与制表符，还原后才是真实路径
+        const mount = rawMount.replace(/\\040/g, " ").replace(/\\011/g, "\t");
+        seen.add(mount);
+    }
+    return [...seen].sort((a, b) => a.localeCompare(b));
+}
+/**
+ * 本机上要报告哪些挂载点
+ * @returns 挂载点数组
+ */
+async function mountsToProbe() {
+    const os = detectPlatform().os;
+    if (os === "windows")
+        return listDriveRoots();
+    if (os === "linux" || os === "android") {
+        const mounts = await readMountPoints();
+        // 读不到 /proc/mounts（权限受限的容器）时至少报根分区，而不是什么都不报
+        return mounts.length > 0 ? mounts : ["/"];
+    }
+    return ["/"];
+}
+/**
+ * 量一个挂载点
+ *
+ * 取 `bavail` 而不是 `bfree`：后者含为 root 预留的那一部分（ext4 默认 5%），
+ * 而面板上的「可用」要回答的是「我还能写进去多少」。
+ * @param mount 挂载点
+ * @returns 占用；量不到时 undefined
+ */
+async function measure(mount) {
+    try {
+        const st = await statfs(mount);
+        const total = Number(st.blocks) * Number(st.bsize);
+        const free = Number(st.bavail) * Number(st.bsize);
+        // 容量为 0 的挂载点无从画进度条：空的光驱、已卸载的容器层都会这样
+        if (!Number.isFinite(total) || total <= 0)
+            return undefined;
+        const capped = Math.min(Math.max(free, 0), total);
+        return { mount, total, free: capped, used: total - capped };
+    }
+    catch {
+        // 权限不足、设备已拔出、网络盘掉线：跳过这一个，不影响其余
+        return undefined;
+    }
+}
+/**
+ * 探测各分区占用
+ * @returns 各分区；一个都探不到时为空数组
+ */
+export async function probeDisks() {
+    const mounts = await mountsToProbe();
+    const measured = await Promise.all(mounts.map(measure));
+    return measured.filter((item) => item !== undefined).slice(0, MAX_DISKS);
+}
+/**
+ * 跑一次 nvidia-smi
+ *
+ * 参数以数组传递、不经 shell。`windowsHide` 免得每 5 秒在 Windows 上闪一个黑框。
+ * @returns 标准输出；命令不存在或失败时 undefined
+ */
+function runNvidiaSmi() {
+    return new Promise(resolve => {
+        execFile("nvidia-smi", ["--query-gpu=name,utilization.gpu,memory.used,memory.total", "--format=csv,noheader,nounits"], { timeout: GPU_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err) {
+                // ENOENT 意为本机没装驱动工具，此后不必再试；超时或其他错误则留待下次
+                if (err.code === "ENOENT")
+                    noNvidiaSmi = true;
+                resolve(undefined);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/**
+ * 解析 nvidia-smi 的 CSV 输出
+ *
+ * 取不到的字段 nvidia-smi 会写 `[N/A]`（如虚拟化环境下的占用率），此时该字段
+ * **不出现**而不是记 0 —— 理由同文件头第 3 条。
+ * @param raw 标准输出
+ * @returns 各显卡；一行都解不出时为空数组
+ */
+export function parseNvidiaSmi(raw) {
+    const gpus = [];
+    for (const line of raw.split("\n")) {
+        const cols = line.split(",").map(part => part.trim());
+        const [name, load, used, total] = cols;
+        if (name === undefined || name === "")
+            continue;
+        /**
+         * 一列数字，`[N/A]` 与非数字一律作「没有这个数」
+         * @param text 该列原文
+         * @returns 数值；取不到时 undefined
+         */
+        const num = (text) => {
+            if (text === undefined)
+                return undefined;
+            const value = Number(text);
+            return Number.isFinite(value) ? value : undefined;
+        };
+        const pct = num(load);
+        const usedMb = num(used);
+        const totalMb = num(total);
+        gpus.push({
+            name,
+            ...(pct === undefined ? {} : { load: Math.min(1, Math.max(0, pct / 100)) }),
+            ...(usedMb === undefined ? {} : { memoryUsed: usedMb * 1024 * 1024 }),
+            ...(totalMb === undefined ? {} : { memoryTotal: totalMb * 1024 * 1024 })
+        });
+    }
+    return gpus;
+}
+/**
+ * 探测显卡
+ * @returns 各显卡；测不到时 undefined（与「有 0 块」相区分）
+ */
+export async function probeGpus() {
+    if (noNvidiaSmi)
+        return undefined;
+    const raw = await runNvidiaSmi();
+    if (raw === undefined)
+        return undefined;
+    const gpus = parseNvidiaSmi(raw);
+    return gpus.length > 0 ? gpus : undefined;
+}
+/**
+ * 采一份系统快照
+ *
+ * 磁盘与显卡并发探测：两者互不相关，串行只是把 nvidia-smi 的耗时加到磁盘上。
+ * @param force 是否绕过缓存，仅测试用
+ * @returns 系统快照
+ */
+export async function sampleSystem(force = false) {
+    const now = Date.now();
+    if (!force && cache !== undefined && now - cache.at < CACHE_MS)
+        return cache.value;
+    const [disks, gpus] = await Promise.all([probeDisks(), probeGpus()]);
+    const value = { disks, ...(gpus === undefined ? {} : { gpus }) };
+    cache = { at: now, value };
+    return value;
+}
+/** 清掉缓存与「没有 nvidia-smi」的记忆，仅测试用 */
+export function resetSystemCache() {
+    cache = undefined;
+    noNvidiaSmi = false;
+}
+//# sourceMappingURL=system.js.map

package/dist/platform/system.js.map

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

package/dist/plugin/context.d.ts

@@ -0,0 +1,92 @@
+import type { AppView, CommandPattern, ConfigHandle, HttpClient, KvNamespace, Logger, PluginContext, RenderOptions, RenderablePage } from "@yunzai-ng/types";
+import { DisposalRegistry } from "../util/dispose.js";
+import type { CoreEventBus } from "./events.js";
+import type { KernelHooks } from "./hooks.js";
+import type { ServiceRegistry } from "./services.js";
+/** 插件注册计数（供 WebUI 的插件列表展示） */
+export interface PluginCounters {
+    /** 已注册命令数 */
+    commands: number;
+    /** 已注册中间件数 */
+    middlewares: number;
+    /** 已注册定时任务数 */
+    tasks: number;
+    /** 已注册路由数 */
+    routes: number;
+    /** 已提供服务数 */
+    services: number;
+}
+/** 构造上下文所需的依赖 */
+export interface PluginContextDeps {
+    /** 插件名 */
+    name: string;
+    /** 插件版本 */
+    version: string;
+    /** 插件安装目录（绝对路径） */
+    root: string;
+    /** 插件专属数据目录（绝对路径，调用方已确保存在） */
+    dataDir: string;
+    /** 插件专属日志器 */
+    logger: Logger;
+    /** 插件专属 KV 命名空间 */
+    kv: KvNamespace;
+    /** 插件配置句柄 */
+    config: ConfigHandle<unknown>;
+    /** 应用只读视图 */
+    app: AppView;
+    /** HTTP 客户端 */
+    http: HttpClient;
+    /** 服务注册表 */
+    services: ServiceRegistry;
+    /** 内核事件总线 */
+    events: CoreEventBus;
+    /** 子系统接缝 */
+    hooks: KernelHooks;
+    /** 本插件的回收登记簿 */
+    registry: DisposalRegistry;
+    /** 卸载信号 */
+    signal: AbortSignal;
+}
+/** 构造结果 */
+export interface PluginContextHandle {
+    /** 交给插件的上下文 */
+    ctx: PluginContext<unknown>;
+    /** 实时计数，宿主用它填 `PluginState` */
+    counters: PluginCounters;
+}
+/**
+ * 把模式数组渲染成可读文本
+ * @param patterns 模式数组
+ * @returns 可读字符串
+ */
+export declare function describePatterns(patterns: readonly CommandPattern[]): string;
+/** 归一化后的一次渲染调用 */
+export interface RenderCall {
+    /** 模板名：字符串通路为相对路径，TSX 通路为页面名（仅用于日志与临时文件名） */
+    template: string;
+    /** 模板数据；TSX 通路为空对象 —— 数据已在组件求值时消化完毕 */
+    data: Record<string, unknown>;
+    /** 已渲染好的 HTML；仅 TSX 通路有值 */
+    html?: string;
+    /** 渲染选项 */
+    opts: RenderOptions;
+}
+/**
+ * 把两条渲染通路的实参归一为一次调用描述
+ *
+ * `render()` 有两种形态：`render(page, opts)` 与 `render(template, data, opts)`。
+ * 以第一参是否为字符串判别 —— `RenderablePage` 是对象，二者不可能混淆。
+ * 判别只做这一处，两个调用点（`ctx.render` 与 `e.render`）共用同一份语义。
+ * @param first 页面或模板相对路径
+ * @param second 模板数据（字符串通路）或渲染选项（TSX 通路）
+ * @param third 渲染选项（字符串通路）
+ * @returns 归一化后的调用描述
+ */
+export declare function splitRenderArgs(first: RenderablePage | string, second?: Record<string, unknown> | RenderOptions, third?: RenderOptions): RenderCall;
+/**
+ * 构造插件上下文
+ * @param deps 依赖
+ * @returns 上下文与计数对象
+ */
+export declare function createPluginContext(deps: PluginContextDeps): PluginContextHandle;
+//# sourceMappingURL=context.d.ts.map

package/dist/plugin/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/plugin/context.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,OAAO,EAKP,cAAc,EACd,YAAY,EAMZ,UAAU,EAGV,WAAW,EACX,MAAM,EAIN,aAAa,EACb,aAAa,EACb,cAAc,EAaf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAIrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAuB,WAAW,EAAE,MAAM,YAAY,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAepD,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,aAAa;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe;IACf,KAAK,EAAE,MAAM,CAAA;IACb,aAAa;IACb,MAAM,EAAE,MAAM,CAAA;IACd,aAAa;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,iBAAiB;AACjB,MAAM,WAAW,iBAAiB;IAChC,UAAU;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW;IACX,OAAO,EAAE,MAAM,CAAA;IACf,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,cAAc;IACd,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,EAAE,EAAE,WAAW,CAAA;IACf,aAAa;IACb,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;IAC7B,aAAa;IACb,GAAG,EAAE,OAAO,CAAA;IACZ,eAAe;IACf,IAAI,EAAE,UAAU,CAAA;IAChB,YAAY;IACZ,QAAQ,EAAE,eAAe,CAAA;IACzB,aAAa;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY;IACZ,KAAK,EAAE,WAAW,CAAA;IAClB,gBAAgB;IAChB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,WAAW;IACX,MAAM,EAAE,WAAW,CAAA;CACpB;AAED,WAAW;AACX,MAAM,WAAW,mBAAmB;IAClC,eAAe;IACf,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC3B,+BAA+B;IAC/B,QAAQ,EAAE,cAAc,CAAA;CACzB;AA4HD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAE5E;AAED,kBAAkB;AAClB,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW;IACX,IAAI,EAAE,aAAa,CAAA;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,GAAG,MAAM,EAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,EAChD,KAAK,CAAC,EAAE,aAAa,GACpB,UAAU,CAKZ;AAwcD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAGhF"}