@yunzai-ng/core 0.1.0

package/src/util/duration.ts

@@ -0,0 +1,82 @@
+/**
+ * 模块职责：时长表达式解析
+ * 依赖方向：仅依赖类型包
+ * 生命周期：纯函数
+ * 注意事项：一律写 `"30d"` 而不是 `60 * 60 * 24 * 30`：手工算出来的秒数改一处要通查全部
+ *          调用点，而配置文件里也读不出那串数字是多久。
+ */
+import type { DurationLike } from "@yunzai-ng/types"
+
+/** 各单位对应的毫秒数 */
+const UNIT_MS: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000
+}
+
+const DURATION_RE = /^(-?\d+(?:\.\d+)?)(ms|s|m|h|d)$/
+
+/**
+ * 把时长表达式解析为毫秒
+ * @param value 毫秒数字，或形如 `"5s"` / `"30d"` 的字符串
+ * @param fallback 无法解析时返回的默认值，缺省 0
+ * @returns 毫秒数
+ */
+export function parseDuration(value: DurationLike | string | undefined | null, fallback = 0): number {
+  if (value === undefined || value === null) return fallback
+  if (typeof value === "number") return Number.isFinite(value) ? value : fallback
+
+  const trimmed = value.trim()
+  if (trimmed === "") return fallback
+
+  // 纯数字串按毫秒处理，兼容从 YAML 里读到的 "5000"
+  if (/^-?\d+$/.test(trimmed)) return Number(trimmed)
+
+  const m = DURATION_RE.exec(trimmed)
+  if (!m) return fallback
+  const [, num, unit] = m
+  return Number(num) * (UNIT_MS[unit as string] ?? 1)
+}
+
+/**
+ * 把毫秒格式化为人类可读的中文时长
+ * @param ms 毫秒数
+ * @returns 形如 `"1天2小时3分"` 的字符串；小于 1 秒时返回 `"<1秒"`
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "-"
+  if (ms < 1000) return "<1秒"
+
+  const d = Math.floor(ms / UNIT_MS.d!)
+  const h = Math.floor((ms % UNIT_MS.d!) / UNIT_MS.h!)
+  const m = Math.floor((ms % UNIT_MS.h!) / UNIT_MS.m!)
+  const s = Math.floor((ms % UNIT_MS.m!) / 1000)
+
+  const parts: string[] = []
+  if (d) parts.push(`${d}天`)
+  if (h) parts.push(`${h}小时`)
+  if (m) parts.push(`${m}分`)
+  // 只有在没有更大单位时才显示秒，避免 "1天0小时0分3秒" 这种噪音
+  if (s && !d && !h) parts.push(`${s}秒`)
+  return parts.join("") || "<1秒"
+}
+
+/**
+ * 把字节数格式化为可读大小
+ * @param bytes 字节数
+ * @returns 形如 `"12.34MB"` 的字符串
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes)) return "-"
+  const units = ["B", "KB", "MB", "GB", "TB"]
+  let value = Math.abs(bytes)
+  let i = 0
+  while (value >= 1024 && i < units.length - 1) {
+    value /= 1024
+    i++
+  }
+  const sign = bytes < 0 ? "-" : ""
+  return `${sign}${i === 0 ? value : value.toFixed(2)}${units[i]}`
+}

package/src/util/fs.ts

@@ -0,0 +1,279 @@
+/**
+ * 模块职责：文件系统助手（原子写、目录保证、路径越界防护）
+ * 依赖方向：仅依赖 node:fs / node:path 与 util/defer
+ * 生命周期：纯函数
+ * 注意事项：**原子写是必需品**，一律走"写临时文件 → rename"。直接 `writeFileSync` 时，
+ *          进程恰在此刻被杀（Windows 关窗口、安卓被系统回收）会留下一个截断的配置文件，
+ *          下次启动即崩。
+ *
+ *          Windows 上 rename 会因杀软/资源管理器短暂占用而抛 EPERM
+ *          （本项目 pnpm install 就撞过一次），所以带退避重试。
+ */
+import { constants as fsConstants } from "node:fs"
+import {
+  access,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  unlink,
+  writeFile
+} from "node:fs/promises"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { randomId } from "./id.js"
+import { sleep } from "./defer.js"
+
+/** rename 遇到占用类错误时的重试次数 */
+const RENAME_RETRIES = 5
+
+/** 判定为"临时占用、可重试"的错误码 */
+const TRANSIENT_CODES = new Set(["EPERM", "EACCES", "EBUSY"])
+
+/**
+ * 从未知错误里取出 errno code
+ * @param err 错误
+ * @returns 错误码，取不到时 undefined
+ */
+export function errorCode(err: unknown): string | undefined {
+  if (err !== null && typeof err === "object" && "code" in err) {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string") return code
+  }
+  return undefined
+}
+
+/**
+ * 路径是否存在
+ * @param path 路径
+ * @returns 是否存在
+ */
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, fsConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 是否是目录
+ * @param path 路径
+ * @returns 是目录则 true；不存在或不是目录则 false
+ */
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 是否是文件
+ * @param path 路径
+ * @returns 是文件则 true
+ */
+export async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 确保目录存在
+ * @param path 目录路径
+ * @returns 目录路径本身，便于链式使用
+ */
+export async function ensureDir(path: string): Promise<string> {
+  await mkdir(path, { recursive: true })
+  return path
+}
+
+/**
+ * 带重试的 rename
+ *
+ * Windows 下杀软扫描、编辑器索引会短暂锁住新建文件，导致 rename 抛 EPERM。
+ * 这类错误重试即可，不该让一次配置保存失败。
+ * @param from 源路径
+ * @param to 目标路径
+ * @throws 重试用尽后抛出最后一次错误
+ */
+async function renameWithRetry(from: string, to: string): Promise<void> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await rename(from, to)
+      return
+    } catch (err) {
+      const code = errorCode(err)
+      if (attempt >= RENAME_RETRIES || !code || !TRANSIENT_CODES.has(code)) throw err
+      await sleep(20 * attempt)
+    }
+  }
+}
+
+/**
+ * 原子写文件
+ *
+ * 先写同目录下的 `.tmp-*` 文件再 rename 覆盖 —— 同目录是关键，
+ * 跨分区 rename 不是原子操作。
+ * @param path 目标文件路径
+ * @param data 内容
+ * @throws 写入或替换失败时抛出；此时原文件保持不变
+ */
+export async function atomicWrite(path: string, data: string | Uint8Array): Promise<void> {
+  const dir = dirname(path)
+  await ensureDir(dir)
+  const tmp = join(dir, `.tmp-${randomId(8)}`)
+  try {
+    await writeFile(tmp, data)
+    await renameWithRetry(tmp, path)
+  } catch (err) {
+    // 清理临时文件，失败也不掩盖原始错误
+    await unlink(tmp).catch(() => undefined)
+    throw err
+  }
+}
+
+/**
+ * 读文本文件
+ * @param path 路径
+ * @returns 文件内容；不存在时 undefined
+ * @throws 除"不存在"以外的读取错误
+ */
+export async function readText(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8")
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return undefined
+    throw err
+  }
+}
+
+/**
+ * 读 JSON 文件
+ * @param path 路径
+ * @returns 解析结果；文件不存在时 undefined
+ * @throws JSON 解析失败时抛出，错误信息带上文件路径
+ */
+export async function readJson<T = unknown>(path: string): Promise<T | undefined> {
+  const text = await readText(path)
+  if (text === undefined) return undefined
+  try {
+    return JSON.parse(text) as T
+  } catch (err) {
+    throw new Error(`解析 JSON 失败：${path} —— ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/**
+ * 原子写 JSON 文件
+ * @param path 路径
+ * @param value 数据
+ * @param pretty 是否缩进，缺省 true（配置类文件要能手改）
+ */
+export async function writeJson(path: string, value: unknown, pretty = true): Promise<void> {
+  await atomicWrite(path, JSON.stringify(value, null, pretty ? 2 : undefined))
+}
+
+/**
+ * 列出目录下的子目录名
+ * @param path 目录路径
+ * @returns 子目录名数组；目录不存在时空数组
+ */
+export async function listDirs(path: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true })
+    return entries.filter(e => e.isDirectory()).map(e => e.name)
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return []
+    throw err
+  }
+}
+
+/**
+ * 列出目录下的文件名
+ * @param path 目录路径
+ * @param ext 可选扩展名过滤，如 `".yaml"`
+ * @returns 文件名数组；目录不存在时空数组
+ */
+export async function listFiles(path: string, ext?: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true })
+    const files = entries.filter(e => e.isFile()).map(e => e.name)
+    return ext ? files.filter(name => name.endsWith(ext)) : files
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return []
+    throw err
+  }
+}
+
+/**
+ * 删除文件或目录（不存在时静默）
+ * @param path 路径
+ */
+export async function remove(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true })
+}
+
+/**
+ * 取文件修改时间
+ * @param path 路径
+ * @returns 毫秒时间戳；文件不存在时 undefined
+ */
+export async function mtimeOf(path: string): Promise<number | undefined> {
+  try {
+    return (await stat(path)).mtimeMs
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 取文件大小
+ * @param path 路径
+ * @returns 字节数；文件不存在时 undefined
+ */
+export async function sizeOf(path: string): Promise<number | undefined> {
+  try {
+    return (await stat(path)).size
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 在根目录内安全拼接路径，阻止 `../` 越界
+ *
+ * WebUI 的静态资源、插件模板资源都要按外部传入的相对路径取文件，
+ * 不做这层校验就是任意文件读取漏洞。
+ * @param root 允许访问的根目录
+ * @param requested 外部传入的相对路径
+ * @returns 解析后的绝对路径
+ * @throws 当结果落在 root 之外，或传入了绝对路径时
+ */
+export function safeJoin(root: string, requested: string): string {
+  if (isAbsolute(requested)) throw new Error(`路径越界：不接受绝对路径 ${requested}`)
+  const rootAbs = resolve(root)
+  const target = resolve(rootAbs, requested)
+  const rel = relative(rootAbs, target)
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`路径越界：${requested}`)
+  }
+  return target
+}
+
+/**
+ * 判断路径是否在某目录内
+ * @param root 根目录
+ * @param target 待判定路径
+ * @returns 是否在根目录内（含自身）
+ */
+export function isInside(root: string, target: string): boolean {
+  const rel = relative(resolve(root), resolve(target))
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel))
+}

package/src/util/id.ts

@@ -0,0 +1,94 @@
+/**
+ * 模块职责：id 生成与哈希
+ * 依赖方向：仅依赖 node:crypto
+ * 生命周期：纯函数
+ * 注意事项：事件 id 采用"时间前缀 + 随机后缀"而非纯 uuid —— 排障时可直接
+ *          按时间排序，且在日志中可直接辨识所属批次。
+ *          刻意不引入 nanoid：一个 60 行的功能不值得增加一个依赖，在
+ *          Termux 上安装依赖时尤为如此。
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto"
+
+/** id 字符表：去掉了易混淆的 0/O/1/l/I */
+const ALPHABET = "23456789abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ"
+
+/**
+ * 生成随机字符串
+ * @param size 长度，缺省 12
+ * @returns 随机 id
+ */
+export function randomId(size = 12): string {
+  const bytes = randomBytes(size)
+  let out = ""
+  for (let i = 0; i < size; i++) {
+    // 取模引入的偏差在 56/256 上可忽略；这里不用于密码学场景
+    out += ALPHABET[bytes[i]! % ALPHABET.length]
+  }
+  return out
+}
+
+/**
+ * 生成事件 id
+ *
+ * 形如 `"m9x2k1qa-7Kd3"`：前段是 36 进制毫秒时间戳，后段随机。
+ * @param prefix 可选前缀，如 `"evt"`
+ * @returns 事件 id
+ */
+export function createEventId(prefix?: string): string {
+  const stamp = Date.now().toString(36)
+  const tail = randomId(4)
+  return prefix ? `${prefix}-${stamp}-${tail}` : `${stamp}-${tail}`
+}
+
+/**
+ * 生成 UUID v4
+ * @returns 标准 uuid 字符串
+ */
+export function uuid(): string {
+  return randomUUID()
+}
+
+/**
+ * 单调递增的自增 id 工厂
+ *
+ * 用于适配器的 `echo` 序号等只需进程内唯一的场景，比随机串更省。
+ * @param prefix 前缀
+ * @returns 每次调用返回下一个 id
+ */
+export function createSeqFactory(prefix = ""): () => string {
+  let seq = 0
+  // 加一个进程内随机段，避免重启后与对端残留的旧 echo 撞号
+  const salt = randomId(4)
+  return () => `${prefix}${salt}${(++seq).toString(36)}`
+}
+
+/**
+ * 计算字符串的 sha256 十六进制摘要
+ * @param input 输入
+ * @param length 截断长度，缺省完整 64 位
+ * @returns 十六进制摘要
+ */
+export function sha256(input: string, length?: number): string {
+  const hex = createHash("sha256").update(input, "utf8").digest("hex")
+  return length ? hex.slice(0, length) : hex
+}
+
+/**
+ * 计算字符串的 md5 十六进制摘要
+ *
+ * 仅用于兼容米游社等平台的签名算法，**不要用于任何安全用途**。
+ * @param input 输入
+ * @returns 十六进制摘要
+ */
+export function md5(input: string): string {
+  return createHash("md5").update(input, "utf8").digest("hex")
+}
+
+/**
+ * 稳定的短哈希，用于给任意字符串生成缓存键
+ * @param input 输入
+ * @returns 12 位十六进制
+ */
+export function shortHash(input: string): string {
+  return sha256(input, 12)
+}

package/src/util/lru.ts

@@ -0,0 +1,185 @@
+/**
+ * 模块职责：LRU + TTL 缓存，带并发去重
+ * 依赖方向：仅依赖类型包
+ * 生命周期：随创建者（插件 / 账号）一起被回收
+ * 注意事项：三项机制合起来使缓存的内存占用具备上界 —— 裸 Map 存群成员表且从不淘汰时，
+ *          数十个千人群即是数百 MB 常驻：
+ *          1) 硬性上限 + LRU 淘汰；
+ *          2) TTL 惰性过期；
+ *          3) single-flight 合并同 key 的并发请求，避免一条群消息中多处判定权限时
+ *             各发一次平台请求。
+ *
+ *          **不采用定时器扫描**：定时器或造成泄漏，或需额外的生命周期管理。改为每次写入时
+ *          清理队首若干过期项，摊还成本 O(1)。
+ */
+import type { ContactCache, ContactCacheOptions } from "@yunzai-ng/types"
+import { parseDuration } from "./duration.js"
+
+/** 缓存条目 */
+interface Entry<V> {
+  /** 缓存的值 */
+  value: V
+  /** 过期时间点（毫秒），Infinity 表示不过期 */
+  expireAt: number
+}
+
+/** 每次写入时顺带检查的队首条目数 */
+const SWEEP_PER_WRITE = 4
+
+/**
+ * LRU + TTL 缓存
+ *
+ * 利用 `Map` 的插入顺序实现 LRU：读命中时把条目挪到队尾，
+ * 于是队首恒为最久未使用者，淘汰只需 `keys().next()`。
+ */
+export class LruCache<V> implements ContactCache<V> {
+  /** 主存储，键序即 LRU 序（队首最久未用） */
+  readonly #map = new Map<string, Entry<V>>()
+  /** 进行中的 loader，用于并发去重 */
+  readonly #pending = new Map<string, Promise<V | undefined>>()
+  /** 条目上限 */
+  readonly #max: number
+  /** 默认存活毫秒 */
+  readonly #ttl: number
+
+  /** 命中次数（诊断用） */
+  #hits = 0
+  /** 未命中次数（诊断用） */
+  #misses = 0
+
+  /**
+   * @param opts 缓存参数；`max` 至少为 1，`ttl` 为 0 表示不过期
+   */
+  constructor(opts: ContactCacheOptions) {
+    this.#max = Math.max(1, Math.floor(opts.max))
+    const ttl = parseDuration(opts.ttl, 0)
+    this.#ttl = ttl > 0 ? ttl : Number.POSITIVE_INFINITY
+  }
+
+  /** 当前条目数（含尚未被清理的过期项） */
+  get size(): number {
+    return this.#map.size
+  }
+
+  /** 命中率统计，供 `/api/diagnostics` 展示缓存是否配得合理 */
+  get stats(): { hits: number; misses: number; size: number; max: number } {
+    return { hits: this.#hits, misses: this.#misses, size: this.#map.size, max: this.#max }
+  }
+
+  /**
+   * 取缓存
+   * @param key 键
+   * @returns 值；未命中或已过期时 undefined
+   */
+  get(key: string): V | undefined {
+    const entry = this.#map.get(key)
+    if (!entry) {
+      this.#misses++
+      return undefined
+    }
+    if (entry.expireAt <= Date.now()) {
+      this.#map.delete(key)
+      this.#misses++
+      return undefined
+    }
+    // 命中即挪到队尾：delete + set 是 Map 上唯一能改插入序的手段
+    this.#map.delete(key)
+    this.#map.set(key, entry)
+    this.#hits++
+    return entry.value
+  }
+
+  /**
+   * 写缓存
+   * @param key 键
+   * @param value 值
+   * @param ttl 覆盖默认存活时长（毫秒）
+   */
+  set(key: string, value: V, ttl?: number): void {
+    this.#sweep()
+    const expireAt = ttl === undefined ? this.#ttl : ttl
+    this.#map.delete(key)
+    this.#map.set(key, {
+      value,
+      expireAt: Number.isFinite(expireAt) ? Date.now() + expireAt : Number.POSITIVE_INFINITY
+    })
+    // 超限时从队首淘汰，直到回到上限内
+    while (this.#map.size > this.#max) {
+      const oldest = this.#map.keys().next()
+      if (oldest.done) break
+      this.#map.delete(oldest.value)
+    }
+  }
+
+  /**
+   * 删除
+   * @param key 键
+   */
+  delete(key: string): void {
+    this.#map.delete(key)
+  }
+
+  /**
+   * 取缓存，未命中时用 loader 拉取并回填
+   *
+   * 同一 key 的并发调用共享同一个 loader promise。loader 抛错时不缓存，
+   * 但会把错误传播给所有等待者——避免"一次网络抖动被缓存成永久失败"。
+   * @param key 键
+   * @param loader 拉取函数
+   * @returns 值；loader 返回 undefined 时不缓存
+   */
+  async fetch(key: string, loader: (key: string) => Promise<V | undefined>): Promise<V | undefined> {
+    const cached = this.get(key)
+    if (cached !== undefined) return cached
+
+    const inflight = this.#pending.get(key)
+    if (inflight) return inflight
+
+    const task = (async () => {
+      try {
+        const value = await loader(key)
+        if (value !== undefined) this.set(key, value)
+        return value
+      } finally {
+        this.#pending.delete(key)
+      }
+    })()
+
+    this.#pending.set(key, task)
+    return task
+  }
+
+  /** 清空全部条目与进行中的 loader 记录 */
+  clear(): void {
+    this.#map.clear()
+    this.#pending.clear()
+    this.#hits = 0
+    this.#misses = 0
+  }
+
+  /**
+   * 清理队首若干个过期条目
+   *
+   * 只看队首是因为 LRU 序下队首最可能已经过期；全量扫描在千级条目上
+   * 会让每次写入都变成 O(n)。
+   */
+  #sweep(): void {
+    if (this.#ttl === Number.POSITIVE_INFINITY) return
+    const now = Date.now()
+    let checked = 0
+    for (const [key, entry] of this.#map) {
+      if (checked++ >= SWEEP_PER_WRITE) break
+      if (entry.expireAt <= now) this.#map.delete(key)
+      else break // 队首未过期时后续项更不可能过期（近似成立，满足本场景需要）
+    }
+  }
+}
+
+/**
+ * 创建 LRU + TTL 缓存
+ * @param opts 缓存参数
+ * @returns 缓存实例
+ */
+export function createCache<V>(opts: ContactCacheOptions): LruCache<V> {
+  return new LruCache<V>(opts)
+}