@yunzai-ng/core 0.1.0

package/src/platform/detect.ts

@@ -0,0 +1,178 @@
+/**
+ * 模块职责：探测运行环境（操作系统族、Termux、容器、内存档位、资源占用）
+ * 依赖方向：仅依赖 node 内置模块与类型包
+ * 生命周期：`detectPlatform()` 结果在进程内不变，缓存一份
+ * 注意事项：Termux 上的 Node 通常把 `process.platform` 报成 `"linux"`，
+ *          单看它会把安卓当普通 Linux，进而按桌面策略去找 Chromium、
+ *          按大内存开并发 —— 这是安卓端最常见的 OOM 原因。
+ *          所以这里做多重取证：环境变量 PREFIX / TERMUX_VERSION、
+ *          `/data/data/com.termux` 目录、`/system/build.prop`。
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { arch, cpus, platform, totalmem } from "node:os"
+import type { PlatformInfo, OsFamily, ResourceUsage } from "@yunzai-ng/types"
+
+/** 低内存判定阈值：2GB */
+const LOW_MEMORY_BYTES = 2 * 1024 * 1024 * 1024
+
+/** 探测结果缓存 */
+let cached: PlatformInfo | undefined
+
+/**
+ * 是否运行在 Termux（安卓）里
+ * @returns 是否为 Termux 环境
+ */
+function detectTermux(): boolean {
+  if (process.env.TERMUX_VERSION) return true
+  const prefix = process.env.PREFIX ?? ""
+  if (prefix.includes("com.termux")) return true
+  if (existsSync("/data/data/com.termux/files/usr")) return true
+  return false
+}
+
+/**
+ * 是否运行在安卓上（含非 Termux 的其他安卓运行环境）
+ * @returns 是否为安卓
+ */
+function detectAndroid(): boolean {
+  if (platform() === "android") return true
+  if (detectTermux()) return true
+  // 非 Termux 的安卓容器：靠系统属性文件判断
+  return existsSync("/system/build.prop") && existsSync("/system/bin/app_process")
+}
+
+/**
+ * 是否运行在容器里
+ *
+ * 容器内可用内存往往远小于 `os.totalmem()` 报告的宿主机内存，
+ * 日志和并发策略需要知道这件事。
+ * @returns 是否为容器环境
+ */
+function detectContainer(): boolean {
+  if (existsSync("/.dockerenv")) return true
+  if (process.env.KUBERNETES_SERVICE_HOST) return true
+  try {
+    const cgroup = readFileSync("/proc/1/cgroup", "utf8")
+    return /docker|kubepods|containerd|lxc/.test(cgroup)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 判定操作系统族
+ * @returns 操作系统族
+ */
+function detectOs(): OsFamily {
+  if (detectAndroid()) return "android"
+  switch (platform()) {
+    case "win32":
+      return "windows"
+    case "darwin":
+      return "macos"
+    case "linux":
+      return "linux"
+    default:
+      return "unknown"
+  }
+}
+
+/**
+ * 读取 cgroup v2/v1 的内存上限
+ *
+ * 容器里 `os.totalmem()` 给的是宿主机内存，会让"低内存档位"判断失效。
+ * @returns 字节数；读不到时 undefined
+ */
+function readCgroupMemoryLimit(): number | undefined {
+  const candidates = ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"]
+  for (const file of candidates) {
+    try {
+      const text = readFileSync(file, "utf8").trim()
+      if (text === "max") continue
+      const value = Number(text)
+      // cgroup v1 未设限时是一个接近 2^63 的巨大数，直接忽略
+      if (Number.isFinite(value) && value > 0 && value < Number.MAX_SAFE_INTEGER) return value
+    } catch {
+      continue
+    }
+  }
+  return undefined
+}
+
+/**
+ * 探测运行环境
+ * @returns 环境信息（进程内缓存，多次调用返回同一对象）
+ */
+export function detectPlatform(): PlatformInfo {
+  if (cached) return cached
+
+  const isContainer = detectContainer()
+  const hostMemory = totalmem()
+  const limited = readCgroupMemoryLimit()
+  const totalMemory = limited !== undefined ? Math.min(hostMemory, limited) : hostMemory
+
+  cached = Object.freeze({
+    os: detectOs(),
+    arch: arch(),
+    isTermux: detectTermux(),
+    isContainer,
+    nodeVersion: process.versions.node,
+    cpus: Math.max(1, cpus().length),
+    totalMemory,
+    lowMemory: totalMemory > 0 && totalMemory < LOW_MEMORY_BYTES
+  })
+  return cached
+}
+
+/** 上一次 CPU 采样点 */
+let lastCpuSample: { time: bigint; usage: NodeJS.CpuUsage } | undefined
+
+/**
+ * 采样进程资源占用
+ *
+ * `cpu` 是**两次调用之间**的平均占用率，因此第一次调用必然返回 0。
+ * WebUI 的资源曲线按固定间隔轮询即可。
+ * @returns 资源占用快照
+ */
+export function sampleUsage(): ResourceUsage {
+  const mem = process.memoryUsage()
+  const now = process.hrtime.bigint()
+  const usage = process.cpuUsage()
+
+  let cpu = 0
+  if (lastCpuSample) {
+    const elapsedUs = Number(now - lastCpuSample.time) / 1000
+    if (elapsedUs > 0) {
+      const usedUs = usage.user - lastCpuSample.usage.user + (usage.system - lastCpuSample.usage.system)
+      // 除以核心数，让多核机器上的数值仍落在 0~1
+      cpu = Math.min(1, Math.max(0, usedUs / elapsedUs / detectPlatform().cpus))
+    }
+  }
+  lastCpuSample = { time: now, usage }
+
+  return {
+    rss: mem.rss,
+    heapUsed: mem.heapUsed,
+    heapTotal: mem.heapTotal,
+    external: mem.external + (mem.arrayBuffers ?? 0),
+    uptime: Math.round(process.uptime()),
+    cpu: Number(cpu.toFixed(4))
+  }
+}
+
+/**
+ * 按内存档位给出建议的并发上限
+ *
+ * 渲染器、图片下载这类"每个任务几十 MB"的操作用它定并发，
+ * 而不是各自拍一个魔数。
+ * @param kind 任务类型：`render` 每任务约 80MB，`io` 约 2MB
+ * @returns 建议并发数，至少 1
+ */
+export function suggestConcurrency(kind: "render" | "io"): number {
+  const info = detectPlatform()
+  if (kind === "io") return info.lowMemory ? 4 : Math.min(16, info.cpus * 2)
+  // 渲染：低内存设备强制串行，避免 Chromium 多标签把内存打满
+  if (info.lowMemory) return 1
+  const byMemory = Math.floor(info.totalMemory / (1024 * 1024 * 1024))
+  return Math.max(1, Math.min(4, Math.min(byMemory - 1, info.cpus)))
+}

package/src/platform/paths.ts

@@ -0,0 +1,147 @@
+/**
+ * 模块职责：确定并创建运行时目录布局
+ * 依赖方向：依赖 util/fs、platform/detect
+ * 生命周期：启动时解析一次，之后只读
+ * 注意事项：全程不使用 `process.cwd()` —— 以 Windows 服务、开机自启或 pm2 启动时
+ *          工作目录并非项目目录。启动时把八个目录一次性定死成绝对路径，
+ *          其余模块只准通过 `app.paths` 取。
+ *
+ *          优先级：显式参数 > `YZNG_HOME` 环境变量 > 便携模式标记 > 系统默认位置。
+ *          便携模式（安装目录下有 `.portable` 文件）让 ZIP 解压即用、
+ *          换机拷走整个文件夹就能迁移 —— Windows 用户最常见的诉求。
+ */
+import { homedir } from "node:os"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { existsSync } from "node:fs"
+import type { RuntimePaths } from "@yunzai-ng/types"
+import { ensureDir } from "../util/fs.js"
+import { detectPlatform } from "./detect.js"
+
+/** 便携模式标记文件名 */
+const PORTABLE_MARKER = ".portable"
+
+/** 应用目录名（系统默认位置下使用） */
+const APP_DIR_NAME = "YunzaiNG"
+
+/** 类 Unix 系统下的隐藏目录名 */
+const APP_DIR_NAME_UNIX = ".yunzai-ng"
+
+/** 解析目录布局的参数 */
+export interface ResolvePathsOptions {
+  /** 显式指定数据根目录；相对路径按 `process.cwd()` 解析 */
+  home?: string
+  /** 内核包所在目录；缺省由 `import.meta.url` 推导 */
+  runtime?: string
+}
+
+/**
+ * 推导内核自身所在目录
+ *
+ * 编译后本文件位于 `<pkg>/dist/platform/paths.js`，上溯两级即包根。
+ * @returns 内核包根目录的绝对路径
+ */
+function detectRuntimeDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  return resolve(here, "..", "..")
+}
+
+/**
+ * 寻找便携模式标记
+ *
+ * 依次检查工作目录、内核包上两级（`node_modules/@yunzai-ng/core` → 安装根）。
+ * @param runtimeDir 内核包目录
+ * @returns 命中的便携根目录；未命中时 undefined
+ */
+function findPortableRoot(runtimeDir: string): string | undefined {
+  const candidates = [process.cwd(), resolve(runtimeDir, "..", "..", ".."), resolve(runtimeDir, "..", "..")]
+  for (const dir of candidates) {
+    if (existsSync(join(dir, PORTABLE_MARKER))) return dir
+  }
+  return undefined
+}
+
+/**
+ * 系统默认的数据根目录
+ * @returns 绝对路径
+ */
+function defaultHome(): string {
+  const info = detectPlatform()
+  const home = homedir()
+
+  if (info.os === "windows") {
+    const base = process.env.LOCALAPPDATA ?? process.env.APPDATA ?? join(home, "AppData", "Local")
+    return join(base, APP_DIR_NAME)
+  }
+  if (info.os === "macos") {
+    return join(home, "Library", "Application Support", APP_DIR_NAME)
+  }
+  if (info.os === "android") {
+    // Termux 的 $HOME 已经在应用私有目录里，再套 XDG 只会加深路径
+    return join(home, APP_DIR_NAME_UNIX)
+  }
+  const xdg = process.env.XDG_DATA_HOME
+  if (xdg && isAbsolute(xdg)) return join(xdg, "yunzai-ng")
+  return join(home, APP_DIR_NAME_UNIX)
+}
+
+/**
+ * 解析目录布局
+ *
+ * 只做路径计算，不创建目录 —— 便于测试与 `yzng doctor` 之类"只想看看
+ * 路径解析成什么"的场景。创建请调用 `ensurePaths`。
+ * @param opts 解析参数
+ * @returns 目录布局（全为绝对路径）
+ */
+export function resolvePaths(opts: ResolvePathsOptions = {}): RuntimePaths {
+  const runtime = opts.runtime ? resolve(opts.runtime) : detectRuntimeDir()
+
+  const explicit = opts.home ?? process.env.YZNG_HOME
+  const home = explicit ? resolve(process.cwd(), explicit) : (findPortableRoot(runtime) ?? defaultHome())
+
+  return Object.freeze({
+    home,
+    config: join(home, "config"),
+    data: join(home, "data"),
+    logs: join(home, "logs"),
+    temp: join(home, "temp"),
+    plugins: join(home, "plugins"),
+    cache: join(home, "cache"),
+    runtime
+  })
+}
+
+/**
+ * 创建目录布局里的所有目录
+ *
+ * `runtime` 不创建（它是安装目录，理应已存在且可能只读）。
+ * @param paths 目录布局
+ * @returns 传入的布局本身，便于链式使用
+ * @throws 目录无法创建时抛出（磁盘只读、权限不足），此时应终止启动
+ */
+export async function ensurePaths(paths: RuntimePaths): Promise<RuntimePaths> {
+  await Promise.all([
+    ensureDir(paths.home),
+    ensureDir(paths.config),
+    ensureDir(paths.data),
+    ensureDir(paths.logs),
+    ensureDir(paths.temp),
+    ensureDir(paths.plugins),
+    ensureDir(paths.cache)
+  ])
+  return paths
+}
+
+/**
+ * 在临时目录下生成一个带前缀的路径
+ *
+ * 用完请自行删除；`temp` 目录也会在启动时按保留期清理。
+ * @param paths 目录布局
+ * @param prefix 文件名前缀
+ * @param ext 扩展名（含点），如 `".png"`
+ * @param unique 唯一后缀，通常传 `randomId()`
+ * @returns 临时文件绝对路径
+ */
+export function tempFile(paths: RuntimePaths, prefix: string, ext: string, unique: string): string {
+  return join(paths.temp, `${prefix}-${unique}${ext}`)
+}

package/src/platform/system.test.ts

@@ -0,0 +1,102 @@
+/**
+ * 模块职责：`platform/system.ts` 的用例 —— 磁盘量测、nvidia-smi 解析与缓存
+ * 依赖方向：测试文件，依赖被测模块
+ * 生命周期：每个用例前清一次缓存
+ * 注意事项：**磁盘一节跑在真实文件系统上，不打桩。** 要验的恰是「`fs.statfs` 在这台
+ *          机器上给出什么」—— 把它打成桩就只是在验证桩自己，而 Windows 盘根与
+ *          Linux 挂载点的行为差异全在真实文件系统一侧。因此断言只挑**与平台无关的
+ *          性质**（总量为正、可用不超过总量、已用与可用相加等于总量），不断言具体数值。
+ *
+ *          GPU 一节反过来全部是纯函数解析：`nvidia-smi` 在 CI 与多数开发机上不存在，
+ *          用例若依赖它的存在就会在没有 N 卡的机器上红。故把「跑命令」与「解析输出」
+ *          分成两个函数，用例只验后者。
+ */
+import { beforeEach, describe, expect, it } from "vitest"
+import { parseNvidiaSmi, probeDisks, resetSystemCache, sampleSystem } from "./system.js"
+
+describe("系统探测", () => {
+  beforeEach(() => {
+    resetSystemCache()
+  })
+
+  describe("磁盘", () => {
+    it("至少探到一个分区，且每一项的数字自洽", async () => {
+      const disks = await probeDisks()
+      expect(disks.length).toBeGreaterThan(0)
+      for (const disk of disks) {
+        expect(disk.mount).not.toBe("")
+        expect(disk.total).toBeGreaterThan(0)
+        expect(disk.free).toBeGreaterThanOrEqual(0)
+        expect(disk.free).toBeLessThanOrEqual(disk.total)
+        // used 由 total - free 算出，故这条等式必然成立；验它是为了防止日后有人
+        // 改成各自独立采样 —— 那时两个数就会来自不同时刻，相加不再等于总量
+        expect(disk.used + disk.free).toBe(disk.total)
+      }
+    })
+
+    it("挂载点不重复 —— bind mount 与同一盘的多次探测都不该各记一条", async () => {
+      const disks = await probeDisks()
+      expect(new Set(disks.map(d => d.mount)).size).toBe(disks.length)
+    })
+  })
+
+  describe("nvidia-smi 输出解析", () => {
+    it("解析常规的一行", () => {
+      const gpus = parseNvidiaSmi("NVIDIA GeForce RTX 4090, 37, 2048, 24564\n")
+      expect(gpus).toEqual([
+        { name: "NVIDIA GeForce RTX 4090", load: 0.37, memoryUsed: 2048 * 1024 * 1024, memoryTotal: 24564 * 1024 * 1024 }
+      ])
+    })
+
+    it("解析多块显卡", () => {
+      const gpus = parseNvidiaSmi("Tesla T4, 0, 12, 15360\nTesla T4, 99, 15000, 15360\n")
+      expect(gpus).toHaveLength(2)
+      expect(gpus[0]?.load).toBe(0)
+      expect(gpus[1]?.load).toBe(0.99)
+    })
+
+    it("**`[N/A]` 的字段不出现，而不是记 0** —— 0% 会被读成「空闲」，而真相是「测不到」", () => {
+      const gpus = parseNvidiaSmi("NVIDIA A100, [N/A], 512, 40960\n")
+      expect(gpus[0]?.name).toBe("NVIDIA A100")
+      expect(gpus[0]).not.toHaveProperty("load")
+      expect(gpus[0]?.memoryUsed).toBe(512 * 1024 * 1024)
+    })
+
+    it("占用率钳在 0~1 内 —— 驱动偶有报出 101 的记录", () => {
+      expect(parseNvidiaSmi("X, 101, 1, 2")[0]?.load).toBe(1)
+      expect(parseNvidiaSmi("X, -5, 1, 2")[0]?.load).toBe(0)
+    })
+
+    it("空输出与空行给出空数组，不抛错", () => {
+      expect(parseNvidiaSmi("")).toEqual([])
+      expect(parseNvidiaSmi("\n\n")).toEqual([])
+    })
+
+    it("缺列的行只丢掉缺的那几项，型号仍在", () => {
+      const gpus = parseNvidiaSmi("NVIDIA T1000\n")
+      expect(gpus).toEqual([{ name: "NVIDIA T1000" }])
+    })
+  })
+
+  describe("快照", () => {
+    it("**测不到显卡时不出现 `gpus` 字段** —— 空数组会被读成「确实有 0 块」", async () => {
+      const snapshot = await sampleSystem(true)
+      // 本机有无 N 卡未知，故两种情形都接受，但「有这个字段且为空数组」不接受
+      if ("gpus" in snapshot) expect(snapshot.gpus?.length).toBeGreaterThan(0)
+      else expect(snapshot.gpus).toBeUndefined()
+    })
+
+    it("缓存生效：连续两次取到同一个对象", async () => {
+      const first = await sampleSystem()
+      const second = await sampleSystem()
+      expect(second).toBe(first)
+    })
+
+    it("force 绕过缓存，取到的是另一次采样", async () => {
+      const first = await sampleSystem()
+      const forced = await sampleSystem(true)
+      expect(forced).not.toBe(first)
+      expect(forced.disks.length).toBe(first.disks.length)
+    })
+  })
+})