@yunzai-ng/core 0.1.0

package/src/server/table.ts

@@ -0,0 +1,351 @@
+/**
+ * 模块职责：路径表 —— 注册 / 注销 / 按请求路径查找，含参数与通配段
+ * 依赖方向：只依赖 `@yunzai-ng/types`；不认识 Fastify，也不认识业务
+ * 生命周期：随共享服务器创建；插件卸载时按 Disposer 逐条摘除
+ * 注意事项：**为什么要自己维护一张表，而不是直接用 Fastify 的路由树**
+ *
+ *          Fastify（find-my-way）只能加路由，没有删除单条路由的 API。而
+ *          "插件能装能卸能热重载"是本框架的核心不变量：重载一次插件如果留下
+ *          一条死路由，第二次注册同一路径就会被 duplicate route 直接抛错，
+ *          插件从此装不上。
+ *
+ *          于是服务器只在 Fastify 上注册两条 catch-all（`/` 与 `/*`），真正
+ *          的分发走这张表：注册是 Map/数组操作，注销就是删掉一项。代价是参数
+ *          解析与优先级排序要自己写 —— 也就是本文件。
+ *
+ *          排序在**注册时**一次算好（`#dynamic` 始终有序），查找路径上没有
+ *          sort、没有正则编译，理由同 pipeline/router.ts：注册低频、查找高频。
+ */
+import type { Disposer, HttpMethod } from "@yunzai-ng/types"
+
+/** 全部支持的 HTTP 方法，顺序即 `Allow` 响应头里的顺序 */
+export const HTTP_METHODS: readonly HttpMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+
+/** 静态段的具体度权重 */
+const RANK_STATIC = 3
+
+/** 参数段（`:id`）的具体度权重 */
+const RANK_PARAM = 2
+
+/** 通配段（`*rest`）的具体度权重 */
+const RANK_WILDCARD = 1
+
+/** 通配段没写名字时的缺省参数名 */
+const DEFAULT_WILDCARD_NAME = "*"
+
+/**
+ * 判断一个字符串是否是受支持的 HTTP 方法
+ * @param value 待判断的值（通常来自 `request.method`）
+ * @returns 是否受支持
+ */
+export function isHttpMethod(value: string): value is HttpMethod {
+  return (HTTP_METHODS as readonly string[]).includes(value)
+}
+
+/**
+ * 解码一个路径段
+ *
+ * 失败时原样返回而不抛错：畸形的 `%` 转义应当表现为"路由不存在"（404），
+ * 而非 500 —— 后者会将每个扫描器的探测请求都记为一条 error 日志。
+ * @param raw 原始段
+ * @returns 解码后的段
+ */
+function decodeSegment(raw: string): string {
+  if (!raw.includes("%")) return raw
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+/**
+ * 把路径切成已解码的段数组
+ *
+ * 先切后解码，顺序不能反：`%2F` 是段内的字面斜杠，先解码会让它变成分隔符，
+ * 那就等于把 `..%2F..%2Fetc` 这类穿越尝试翻译成了真正的路径分隔。
+ * @param path 路径（可含查询串之前的部分）
+ * @returns 已解码的非空段数组
+ */
+export function splitSegments(path: string): string[] {
+  const out: string[] = []
+  for (const raw of path.split("/")) {
+    if (raw === "" || raw === ".") continue
+    out.push(decodeSegment(raw))
+  }
+  return out
+}
+
+/**
+ * 归一化一个 URL 模式
+ *
+ * `scope` 与 `path` 各自可能带或不带首尾斜杠，插件作者两种写法都会用。
+ * @param scope URL 前缀，如 `/plugin/mhy-game`
+ * @param path 相对 scope 的路径，如 `webhook/:id`
+ * @returns 形如 `/plugin/mhy-game/webhook/:id` 的模式；根路径为 `/`
+ */
+export function joinPattern(scope: string, path: string): string {
+  const segs = [...splitRaw(scope), ...splitRaw(path)]
+  return segs.length === 0 ? "/" : `/${segs.join("/")}`
+}
+
+/**
+ * 切分但**不**解码
+ *
+ * 模式是插件作者手写的，本来就是解码后的形态；对它做 `decodeURIComponent`
+ * 会把 `%` 当转义处理，反而改坏了模式。
+ * @param path 路径
+ * @returns 非空段数组
+ */
+function splitRaw(path: string): string[] {
+  return path.split("/").filter(seg => seg !== "" && seg !== ".")
+}
+
+/** 一个已编译的路径段 */
+interface PathSegment {
+  /** 段类型 */
+  readonly kind: "static" | "param" | "wildcard"
+  /** 静态段为字面值；参数段与通配段为参数名 */
+  readonly value: string
+}
+
+/** 表内一项 */
+interface Bound<T> {
+  /** 归一化后的完整模式 */
+  readonly pattern: string
+  /** 承载的值（路由处理函数、WebSocket 处理函数、静态目录……） */
+  readonly value: T
+  /** 编译后的段 */
+  readonly segments: readonly PathSegment[]
+  /** 各段的具体度权重，用于排序 */
+  readonly ranks: readonly number[]
+  /** 注册序号，同具体度时保证先注册者优先且顺序稳定 */
+  readonly seq: number
+}
+
+/** 一次查找命中 */
+export interface PathHit<T> {
+  /** 命中的模式 */
+  readonly pattern: string
+  /** 承载的值 */
+  readonly value: T
+  /** 路径参数；无参数时是同一个空对象 */
+  readonly params: Readonly<Record<string, string>>
+}
+
+/** 没有参数时共用的空对象，省掉每次请求一次分配 */
+const NO_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
+
+/**
+ * 编译一个模式
+ * @param pattern 已归一化的模式
+ * @returns 段数组
+ * @throws 参数名为空、或通配段不在末尾时
+ */
+function compileSegments(pattern: string): PathSegment[] {
+  const raw = splitRaw(pattern)
+  const out: PathSegment[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const seg = raw[i]!
+    if (seg.startsWith(":")) {
+      const name = seg.slice(1)
+      if (name === "") throw new Error(`路由模式 ${pattern} 里有一个没写名字的参数段（应形如 /x/:id）`)
+      out.push({ kind: "param", value: name })
+      continue
+    }
+    if (seg.startsWith("*")) {
+      if (i !== raw.length - 1) {
+        throw new Error(`路由模式 ${pattern} 的通配段只能置于末尾：其将匹配后续的全部路径`)
+      }
+      out.push({ kind: "wildcard", value: seg.slice(1) === "" ? DEFAULT_WILDCARD_NAME : seg.slice(1) })
+      continue
+    }
+    out.push({ kind: "static", value: seg })
+  }
+  return out
+}
+
+/**
+ * 取段的具体度权重
+ * @param segment 段
+ * @returns 权重
+ */
+function rankOf(segment: PathSegment): number {
+  if (segment.kind === "static") return RANK_STATIC
+  return segment.kind === "param" ? RANK_PARAM : RANK_WILDCARD
+}
+
+/**
+ * 比较两项的匹配优先级
+ *
+ * 逐段比权重：`/api/config` 必须比 `/api/:name` 先试，`/api/:name` 又必须比
+ * `/api/*` 先试。前缀相同时段数多者更具体（`/a/b/*` 比 `/a/*` 更具体）。
+ * 完全同级时按注册顺序，保证行为可预期。
+ * @param a 项 a
+ * @param b 项 b
+ * @returns 排序结果，负数表示 a 先试
+ */
+function bySpecificity<T>(a: Bound<T>, b: Bound<T>): number {
+  const n = Math.min(a.ranks.length, b.ranks.length)
+  for (let i = 0; i < n; i++) {
+    const diff = b.ranks[i]! - a.ranks[i]!
+    if (diff !== 0) return diff
+  }
+  if (a.ranks.length !== b.ranks.length) return b.ranks.length - a.ranks.length
+  return a.seq - b.seq
+}
+
+/**
+ * 按已排好的顺序插入
+ * @param list 已排序数组（就地修改）
+ * @param item 待插入项
+ */
+function insertSorted<T>(list: Bound<T>[], item: Bound<T>): void {
+  let lo = 0
+  let hi = list.length
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1
+    if (bySpecificity(list[mid]!, item) <= 0) lo = mid + 1
+    else hi = mid
+  }
+  list.splice(lo, 0, item)
+}
+
+/**
+ * 一张路径表
+ *
+ * 静态模式（无参数无通配）走 Map 精确命中，其余按具体度顺序线性试。
+ * HTTP 路由、WebSocket 路径、静态目录挂载三者的查找规则完全一样，
+ * 所以共用这一个实现，只是承载的 `T` 不同。
+ */
+export class PathTable<T> {
+  /** 无参数模式：路径 → 项 */
+  readonly #exact = new Map<string, Bound<T>>()
+  /** 含参数或通配的模式，按具体度预排序 */
+  #dynamic: Bound<T>[] = []
+  /** 注册序号发号器 */
+  #seq = 0
+
+  /** 已注册的条数 */
+  get size(): number {
+    return this.#exact.size + this.#dynamic.length
+  }
+
+  /**
+   * 注册一条
+   * @param pattern 已归一化的模式
+   * @param value 承载的值
+   * @returns 注销句柄；幂等
+   * @throws 模式非法、或同一模式重复注册时
+   */
+  add(pattern: string, value: T): Disposer {
+    if (this.has(pattern)) {
+      // 不静默覆盖：两个插件争用同一个路径时，"后者生效"将表现为前者无故失效。
+      // 插件的 scope 天然带有插件名，可能冲突的只有同一插件内部的重复注册
+      throw new Error(`路径 ${pattern} 已经注册过了。热重载请先执行上一次注册返回的 Disposer`)
+    }
+
+    const segments = compileSegments(pattern)
+    const item: Bound<T> = {
+      pattern,
+      value,
+      segments,
+      ranks: segments.map(rankOf),
+      seq: this.#seq++
+    }
+
+    if (segments.every(seg => seg.kind === "static")) this.#exact.set(pattern, item)
+    else insertSorted(this.#dynamic, item)
+
+    let removed = false
+    return () => {
+      if (removed) return
+      removed = true
+      if (this.#exact.get(pattern) === item) this.#exact.delete(pattern)
+      const at = this.#dynamic.indexOf(item)
+      if (at >= 0) this.#dynamic.splice(at, 1)
+    }
+  }
+
+  /**
+   * 某个模式是否已注册
+   * @param pattern 已归一化的模式
+   * @returns 是否已注册
+   */
+  has(pattern: string): boolean {
+    return this.#exact.has(pattern) || this.#dynamic.some(item => item.pattern === pattern)
+  }
+
+  /**
+   * 按已解码的路径段查找
+   * @param parts 已解码的路径段（`splitSegments()` 的产物）
+   * @returns 命中项；未命中时 undefined
+   */
+  find(parts: readonly string[]): PathHit<T> | undefined {
+    const exact = this.#exact.get(parts.length === 0 ? "/" : `/${parts.join("/")}`)
+    if (exact !== undefined) return { pattern: exact.pattern, value: exact.value, params: NO_PARAMS }
+
+    for (const item of this.#dynamic) {
+      const params = matchSegments(item.segments, parts)
+      if (params !== undefined) return { pattern: item.pattern, value: item.value, params }
+    }
+    return undefined
+  }
+
+  /**
+   * 导出全部模式，按匹配顺序
+   * @returns 模式数组
+   */
+  list(): string[] {
+    return this.entries().map(item => item.pattern)
+  }
+
+  /**
+   * 导出全部注册项，按匹配顺序
+   *
+   * 面板需要展示的是"哪条路由属于哪个插件、是否需要鉴权"，仅有模式字符串不足，
+   * 因此连同 `value` 一并给出。
+   * @returns 模式与承载值的数组
+   */
+  entries(): { pattern: string; value: T }[] {
+    return [...this.#exact.values(), ...this.#dynamic]
+      .sort(bySpecificity)
+      .map(item => ({ pattern: item.pattern, value: item.value }))
+  }
+
+  /** 清空 */
+  clear(): void {
+    this.#exact.clear()
+    this.#dynamic = []
+  }
+}
+
+/**
+ * 拿一组段去匹配请求路径
+ * @param segments 编译后的模式段
+ * @param parts 请求路径的段
+ * @returns 路径参数；不匹配时 undefined
+ */
+function matchSegments(
+  segments: readonly PathSegment[],
+  parts: readonly string[]
+): Readonly<Record<string, string>> | undefined {
+  const params: Record<string, string> = {}
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i]!
+    if (seg.kind === "wildcard") {
+      // 通配段匹配剩余的全部路径，包括"无剩余内容"的情形（`/files/*` 亦匹配 `/files`）
+      params[seg.value] = parts.slice(i).join("/")
+      return params
+    }
+    const part = parts[i]
+    if (part === undefined) return undefined
+    if (seg.kind === "static") {
+      if (part !== seg.value) return undefined
+      continue
+    }
+    if (part === "") return undefined
+    params[seg.value] = part
+  }
+  return parts.length === segments.length ? params : undefined
+}

package/src/store/index.ts

@@ -0,0 +1,156 @@
+/**
+ * 模块职责：KV 存储的装配（驱动选择、自动降级、根命名空间）
+ * 依赖方向：依赖 store/{kv,memory,json,level}、util/fs、类型包
+ * 生命周期：应用级单例，`close()` 时落盘
+ * 注意事项：**存储不可用不等于机器人不可用。** `auto` 模式按 level → json → memory 逐级降级，
+ *          每次降级记一条 warn 说明原因；最坏退到纯内存（重启丢缓存），但机器人始终能收发消息。
+ *
+ *          外部注册的驱动（如 store-redis 插件）通过 `registerKvDriver()` 挂进来，
+ *          与内置驱动一视同仁 —— 这正是"一切皆可为插件"在存储层的落点。
+ */
+import { join } from "node:path"
+import type { KvDriver, KvNamespace, Logger } from "@yunzai-ng/types"
+import { Kv } from "./kv.js"
+import { MemoryKvDriver } from "./memory.js"
+import { JsonKvDriver } from "./json.js"
+import { LevelKvDriver, loadLevel } from "./level.js"
+
+/** 内置驱动 id */
+export type BuiltinDriverId = "auto" | "level" | "json" | "memory"
+
+/** 驱动工厂：拿到数据目录，产出一个尚未 open 的驱动 */
+export type KvDriverFactory = (dir: string) => Promise<KvDriver> | KvDriver
+
+/** 外部注册的驱动表（插件注册的驱动进这里） */
+const externalDrivers = new Map<string, KvDriverFactory>()
+
+/**
+ * 注册一个 KV 驱动
+ *
+ * 供 `store-redis` 这类插件调用；配置里把 `store.driver` 写成同一个 id 即可启用。
+ * @param id 驱动 id
+ * @param factory 驱动工厂
+ * @returns 取消注册
+ * @throws id 与内置驱动冲突时
+ */
+export function registerKvDriver(id: string, factory: KvDriverFactory): () => void {
+  if (id === "auto" || id === "level" || id === "json" || id === "memory") {
+    throw new Error(`驱动 id ${id} 与内置驱动冲突`)
+  }
+  externalDrivers.set(id, factory)
+  return () => void externalDrivers.delete(id)
+}
+
+/** 打开 KV 存储的参数 */
+export interface OpenKvOptions {
+  /** 数据目录（KV 数据会放在其子目录里） */
+  dir: string
+  /** 驱动 id，缺省 `auto` */
+  driver?: string
+  /** 日志器 */
+  logger: Logger
+}
+
+/** 已打开的 KV 存储 */
+export interface KvStore {
+  /** 实际生效的驱动 id（`auto` 会被解析为具体驱动） */
+  readonly driver: string
+  /** 根命名空间 */
+  readonly root: KvNamespace
+  /**
+   * 取一个子命名空间
+   * @param name 命名空间名
+   * @returns KV 视图
+   */
+  namespace(name: string): KvNamespace
+  /** 关闭并落盘 */
+  close(): Promise<void>
+}
+
+/**
+ * 打开 KV 存储
+ *
+ * `auto` 的降级顺序：level（性能最优）→ json（纯 JS，Termux 兜底）→ memory。
+ * 显式指定驱动时同样会降级，但会将"所指定的驱动为何不可用"记为 warn，
+ * 而非静默替换 —— 使用者配置了 redis 却运行于内存驱动之上而不知情是最糟的情形。
+ * @param opts 参数
+ * @returns 已打开的 KV 存储
+ */
+export async function openKv(opts: OpenKvOptions): Promise<KvStore> {
+  const logger = opts.logger.child({ scope: "store" })
+  const requested = opts.driver ?? "auto"
+  const chain = resolveChain(requested)
+
+  let driver: KvDriver | undefined
+  for (const id of chain) {
+    try {
+      const candidate = await createDriver(id, opts.dir)
+      if (!candidate) {
+        logger.warn(`KV 驱动 ${id} 不可用（未安装或未注册），尝试下一个`)
+        continue
+      }
+      await candidate.open()
+      driver = candidate
+      if (id !== requested && requested !== "auto") {
+        logger.warn(`配置指定的 KV 驱动 ${requested} 不可用，已降级为 ${id}`)
+      }
+      break
+    } catch (err) {
+      logger.warn(`KV 驱动 ${id} 打开失败，尝试下一个`, err)
+    }
+  }
+
+  if (!driver) {
+    // chain 末尾恒为 memory，理论上到不了这里；留着是为了让失败可诊断而不是空指针
+    throw new Error("所有 KV 驱动均不可用")
+  }
+
+  logger.info(`KV 存储就绪：驱动 ${driver.id}`)
+  const root = new Kv(driver)
+
+  return {
+    driver: driver.id,
+    root,
+    namespace: (name: string) => root.sub(name),
+    close: async () => {
+      await driver.close()
+    }
+  }
+}
+
+/**
+ * 把请求的驱动 id 展开成降级链
+ * @param requested 请求的驱动 id
+ * @returns 依次尝试的驱动 id 列表，末尾恒为 memory
+ */
+function resolveChain(requested: string): string[] {
+  if (requested === "auto") return ["level", "json", "memory"]
+  if (requested === "memory") return ["memory"]
+  if (requested === "json") return ["json", "memory"]
+  if (requested === "level") return ["level", "json", "memory"]
+  // 外部驱动（redis 等）失败后退回内置默认链
+  return [requested, "level", "json", "memory"]
+}
+
+/**
+ * 按 id 造驱动
+ * @param id 驱动 id
+ * @param dir 数据目录
+ * @returns 驱动实例；不可用时 undefined
+ */
+async function createDriver(id: string, dir: string): Promise<KvDriver | undefined> {
+  switch (id) {
+    case "memory":
+      return new MemoryKvDriver()
+    case "json":
+      return new JsonKvDriver(join(dir, "kv.json"))
+    case "level": {
+      const ctor = await loadLevel()
+      return ctor ? new LevelKvDriver(join(dir, "kv"), ctor) : undefined
+    }
+    default: {
+      const factory = externalDrivers.get(id)
+      return factory ? await factory(dir) : undefined
+    }
+  }
+}

package/src/store/json.ts

@@ -0,0 +1,198 @@
+/**
+ * 模块职责：JSON 文件 KV 驱动（纯 JS 兜底，Termux/无编译环境用）
+ * 依赖方向：依赖 util/{fs,deep}、类型包
+ * 生命周期：`open()` 载入全量数据，`close()` 落盘；进程存续期间数据常驻内存
+ * 注意事项：**这是兜底方案，不是主力**。全量数据常驻内存 + 每次写盘重写整个文件，
+ *          数据量大了必然吃内存与 IO；只在原生模块装不上（Android/Termux 常见）
+ *          时启用，`level` 驱动才是默认。
+ *
+ *          写盘做了两件事防丢数据：一是合并窗口内的多次写只落一次盘，
+ *          二是走 `atomicWrite`（同目录临时文件 + rename），断电不会留下半个文件。
+ *          进程退出前必须 `close()`，否则最后一个窗口内的写入会丢。
+ */
+import type { KvBatchOp, KvDriver, StoredEnvelope } from "@yunzai-ng/types"
+import { atomicWrite, ensureDir, readText } from "../util/fs.js"
+import { deepClone } from "../util/deep.js"
+import { dirname } from "node:path"
+import { isExpired } from "./kv.js"
+
+/** 落盘合并窗口（毫秒） */
+const FLUSH_DELAY = 300
+
+/** 文件格式版本，将来变更结构时用于迁移判断 */
+const FORMAT = 1
+
+/** 落盘结构 */
+interface JsonFileShape {
+  /** 格式版本 */
+  format: number
+  /** 数据表 */
+  data: Record<string, StoredEnvelope>
+}
+
+/** JSON 文件 KV 驱动 */
+export class JsonKvDriver implements KvDriver {
+  /** 驱动 id */
+  readonly id = "json"
+
+  /** 文件绝对路径 */
+  readonly #file: string
+  /** 数据表 */
+  #map = new Map<string, StoredEnvelope>()
+  /** 落盘定时器 */
+  #timer: NodeJS.Timeout | undefined
+  /** 是否有未落盘的改动 */
+  #dirty = false
+  /** 正在进行的落盘，用于串行化避免两次写互相覆盖 */
+  #writing: Promise<void> = Promise.resolve()
+  /** 是否已关闭 */
+  #closed = false
+
+  /**
+   * @param file 数据文件绝对路径
+   */
+  constructor(file: string) {
+    this.#file = file
+  }
+
+  /** 键数量 */
+  get size(): number {
+    return this.#map.size
+  }
+
+  /**
+   * 载入数据
+   *
+   * 文件损坏时不抛错也不删除：改名为 `.corrupt-<时间戳>` 留证，然后从空库启动。
+   * 存储坏了让机器人起不来，比丢一点缓存严重得多。
+   */
+  async open(): Promise<void> {
+    this.#closed = false
+    await ensureDir(dirname(this.#file))
+    const text = await readText(this.#file)
+    if (text === undefined || text.trim() === "") return
+
+    try {
+      const parsed = JSON.parse(text) as JsonFileShape
+      const data = parsed.format === FORMAT ? parsed.data : undefined
+      if (!data || typeof data !== "object") throw new Error("结构不符")
+      this.#map = new Map(Object.entries(data))
+      // 载入时清掉过期键，避免它们一直占内存直到被访问
+      for (const [key, env] of [...this.#map]) if (isExpired(env)) this.#map.delete(key)
+    } catch (err) {
+      const backup = `${this.#file}.corrupt-${Date.now()}`
+      await atomicWrite(backup, text).catch(() => undefined)
+      throw new Error(`KV 数据文件解析失败，已备份到 ${backup}：${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  /** 落盘并停止后续写入 */
+  async close(): Promise<void> {
+    this.#closed = true
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = undefined
+    }
+    await this.flush()
+  }
+
+  /**
+   * 读取
+   * @param key 完整键
+   * @returns 值信封副本
+   */
+  async get(key: string): Promise<StoredEnvelope | undefined> {
+    const env = this.#map.get(key)
+    return env === undefined ? undefined : deepClone(env)
+  }
+
+  /**
+   * 写入
+   * @param key 完整键
+   * @param value 值信封
+   */
+  async set(key: string, value: StoredEnvelope): Promise<void> {
+    this.#map.set(key, deepClone(value))
+    this.#schedule()
+  }
+
+  /**
+   * 删除
+   * @param key 完整键
+   */
+  async del(key: string): Promise<void> {
+    if (this.#map.delete(key)) this.#schedule()
+  }
+
+  /**
+   * 批量操作（只触发一次落盘）
+   * @param ops 操作列表
+   */
+  async batch(ops: KvBatchOp[]): Promise<void> {
+    let changed = false
+    for (const op of ops) {
+      if (op.op === "set") {
+        this.#map.set(op.key, deepClone(op.value))
+        changed = true
+      } else if (this.#map.delete(op.key)) changed = true
+    }
+    if (changed) this.#schedule()
+  }
+
+  /**
+   * 按前缀扫描
+   * @param prefix 键前缀
+   * @returns 键值对迭代器
+   */
+  async *scan(prefix: string): AsyncIterableIterator<readonly [string, StoredEnvelope]> {
+    for (const key of [...this.#map.keys()]) {
+      if (!key.startsWith(prefix)) continue
+      const env = this.#map.get(key)
+      if (env === undefined) continue
+      yield [key, deepClone(env)]
+    }
+  }
+
+  /**
+   * 原生原子自增（同步读改写，单线程下天然原子）
+   * @param key 完整键
+   * @param by 增量
+   * @param expireAt 首次创建时的过期时间点
+   * @returns 自增后的值
+   */
+  async incr(key: string, by: number, expireAt?: number): Promise<number> {
+    const env = this.#map.get(key)
+    const alive = env !== undefined && !isExpired(env)
+    const current = alive && typeof env.v === "number" ? env.v : 0
+    const next = current + by
+    const keep = alive ? env.e : expireAt
+    this.#map.set(key, keep === undefined ? { v: next } : { v: next, e: keep })
+    this.#schedule()
+    return next
+  }
+
+  /** 立即落盘（`close()` 与测试用） */
+  async flush(): Promise<void> {
+    if (!this.#dirty) return await this.#writing
+    this.#dirty = false
+
+    const snapshot: JsonFileShape = { format: FORMAT, data: Object.fromEntries(this.#map) }
+    // 串在上一次写之后：两次并发的 atomicWrite 会竞争同一个目标文件
+    this.#writing = this.#writing.then(async () => {
+      await atomicWrite(this.#file, JSON.stringify(snapshot))
+    })
+    await this.#writing
+  }
+
+  /** 安排一次延迟落盘 */
+  #schedule(): void {
+    this.#dirty = true
+    if (this.#closed || this.#timer) return
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined
+      void this.flush().catch(() => undefined)
+    }, FLUSH_DELAY)
+    // unref：等待落盘不该拖住进程退出，退出路径上有 close() 兜底
+    if (typeof this.#timer.unref === "function") this.#timer.unref()
+  }
+}