@yunzai-ng/core 0.1.0 → 0.1.1

package/src/kernel/policy.ts

@@ -1,120 +1,120 @@
-/**
- * 模块职责：内核策略 —— 主人、命令前缀、昵称、维护模式
- * 依赖方向：依赖 config/core-config 与类型包；不依赖任何子系统
- * 生命周期：与应用同寿，无需回收
- * 注意事项：所有取值均**即时读取配置**而不缓存，故改完主人号对下一条消息即生效，不必重启。
- *          `ConfigFile.get()` 在配置未变更时返回同一个对象，故"即时读取"只是一次属性访问。
- *
- *          此处刻意**不做鉴权**：`addMaster` 对任何调用方均开放。凭据校验是入口的职责
- *          （WebUI 经由令牌，命令经由 `isMaster`），策略层仅负责"名单的内容"。
- *          两者混于一层将导致"经由修改配置绕过鉴权"这类漏洞。
- */
-import type { PolicyView } from "@yunzai-ng/types"
-import type { CoreConfigHandle } from "../config/core-config.js"
-
-/**
- * 内核策略
- *
- * 实现类型包里的 `PolicyView`（适配器与插件只看得到那个只读接口），
- * 另外多给内核自己用的几项：前缀、昵称、维护模式。
- */
-export class KernelPolicy implements PolicyView {
-  /** 内核配置句柄 */
-  readonly #config: CoreConfigHandle
-
-  /**
-   * @param config 内核配置句柄
-   */
-  constructor(config: CoreConfigHandle) {
-    this.#config = config
-  }
-
-  /** 主人账号列表 */
-  get masters(): readonly string[] {
-    return this.#config.get().bot.masterQQ
-  }
-
-  /**
-   * 命令前缀
-   *
-   * 空数组表示不限制前缀。命令路由据此分桶，见 pipeline 层。
-   */
-  get prefixes(): readonly string[] {
-    return this.#config.get().bot.prefix
-  }
-
-  /** 机器人昵称（群里以昵称开头等同于 @ 机器人） */
-  get nicknames(): readonly string[] {
-    return this.#config.get().bot.nickname
-  }
-
-  /** 是否忽略自身发出的消息 */
-  get ignoreSelf(): boolean {
-    return this.#config.get().bot.ignoreSelf
-  }
-
-  /** 是否处于维护模式（只响应主人） */
-  get maintenance(): boolean {
-    return this.#config.get().bot.onlyMaster
-  }
-
-  /**
-   * 判断是否主人
-   *
-   * 主人名单为空时一律返回 false —— 不存在"没配主人就人人是主人"的默认，
-   * 那会让首次启动的机器人对全世界开放管理命令。
-   * @param uid 用户 id
-   * @returns 是否主人
-   */
-  isMaster(uid: string): boolean {
-    if (uid === "") return false
-    return this.masters.includes(uid)
-  }
-
-  /**
-   * 判断该用户当前是否应被响应
-   *
-   * 维护模式下只放行主人。这是**唯一**的全局开关判定点，管线里不要再各自判一次。
-   * @param uid 用户 id
-   * @returns 是否响应
-   */
-  canRespond(uid: string): boolean {
-    return !this.maintenance || this.isMaster(uid)
-  }
-
-  /**
-   * 添加主人并落盘
-   * @param uid 用户 id（纯数字）
-   * @returns 是否真的添加了（已在名单里时 false）
-   * @throws SchemaError uid 不是合法 id 时；此时配置与文件都不变
-   */
-  async addMaster(uid: string): Promise<boolean> {
-    const current = this.masters
-    if (current.includes(uid)) return false
-    // 整个数组一起写：deepMerge 对数组是整体替换而非追加，
-    // 只传新增项会把原有主人全冲掉
-    await this.#config.patch({ bot: { masterQQ: [...current, uid] } })
-    return true
-  }
-
-  /**
-   * 移除主人并落盘
-   * @param uid 用户 id
-   * @returns 是否真的移除了
-   */
-  async removeMaster(uid: string): Promise<boolean> {
-    const current = this.masters
-    if (!current.includes(uid)) return false
-    await this.#config.patch({ bot: { masterQQ: current.filter(id => id !== uid) } })
-    return true
-  }
-}
-
-/**
- * 创建内核策略
- * @param config 内核配置句柄
- * @returns 内核策略
- */
-export function createPolicy(config: CoreConfigHandle): KernelPolicy {
-  return new KernelPolicy(config)
-}
+/**
+ * 模块职责：内核策略 —— 主人、命令前缀、昵称、维护模式
+ * 依赖方向：依赖 config/core-config 与类型包；不依赖任何子系统
+ * 生命周期：与应用同寿，无需回收
+ * 注意事项：所有取值均**即时读取配置**而不缓存，故改完主人号对下一条消息即生效，不必重启。
+ *          `ConfigFile.get()` 在配置未变更时返回同一个对象，故"即时读取"只是一次属性访问。
+ *
+ *          此处刻意**不做鉴权**：`addMaster` 对任何调用方均开放。凭据校验是入口的职责
+ *          （WebUI 经由令牌，命令经由 `isMaster`），策略层仅负责"名单的内容"。
+ *          两者混于一层将导致"经由修改配置绕过鉴权"这类漏洞。
+ */
+import type { PolicyView } from "@yunzai-ng/types"
+import type { CoreConfigHandle } from "../config/core-config.js"
+
+/**
+ * 内核策略
+ *
+ * 实现类型包里的 `PolicyView`（适配器与插件只看得到那个只读接口），
+ * 另外多给内核自己用的几项：前缀、昵称、维护模式。
+ */
+export class KernelPolicy implements PolicyView {
+  /** 内核配置句柄 */
+  readonly #config: CoreConfigHandle
+
+  /**
+   * @param config 内核配置句柄
+   */
+  constructor(config: CoreConfigHandle) {
+    this.#config = config
+  }
+
+  /** 主人账号列表 */
+  get masters(): readonly string[] {
+    return this.#config.get().bot.masterQQ
+  }
+
+  /**
+   * 命令前缀
+   *
+   * 空数组表示不限制前缀。命令路由据此分桶，见 pipeline 层。
+   */
+  get prefixes(): readonly string[] {
+    return this.#config.get().bot.prefix
+  }
+
+  /** 机器人昵称（群里以昵称开头等同于 @ 机器人） */
+  get nicknames(): readonly string[] {
+    return this.#config.get().bot.nickname
+  }
+
+  /** 是否忽略自身发出的消息 */
+  get ignoreSelf(): boolean {
+    return this.#config.get().bot.ignoreSelf
+  }
+
+  /** 是否处于维护模式（只响应主人） */
+  get maintenance(): boolean {
+    return this.#config.get().bot.onlyMaster
+  }
+
+  /**
+   * 判断是否主人
+   *
+   * 主人名单为空时一律返回 false —— 不存在"没配主人就人人是主人"的默认，
+   * 那会让首次启动的机器人对全世界开放管理命令。
+   * @param uid 用户 id
+   * @returns 是否主人
+   */
+  isMaster(uid: string): boolean {
+    if (uid === "") return false
+    return this.masters.includes(uid)
+  }
+
+  /**
+   * 判断该用户当前是否应被响应
+   *
+   * 维护模式下只放行主人。这是**唯一**的全局开关判定点，管线里不要再各自判一次。
+   * @param uid 用户 id
+   * @returns 是否响应
+   */
+  canRespond(uid: string): boolean {
+    return !this.maintenance || this.isMaster(uid)
+  }
+
+  /**
+   * 添加主人并落盘
+   * @param uid 用户 id（纯数字）
+   * @returns 是否真的添加了（已在名单里时 false）
+   * @throws SchemaError uid 不是合法 id 时；此时配置与文件都不变
+   */
+  async addMaster(uid: string): Promise<boolean> {
+    const current = this.masters
+    if (current.includes(uid)) return false
+    // 整个数组一起写：deepMerge 对数组是整体替换而非追加，
+    // 只传新增项会把原有主人全冲掉
+    await this.#config.patch({ bot: { masterQQ: [...current, uid] } })
+    return true
+  }
+
+  /**
+   * 移除主人并落盘
+   * @param uid 用户 id
+   * @returns 是否真的移除了
+   */
+  async removeMaster(uid: string): Promise<boolean> {
+    const current = this.masters
+    if (!current.includes(uid)) return false
+    await this.#config.patch({ bot: { masterQQ: current.filter(id => id !== uid) } })
+    return true
+  }
+}
+
+/**
+ * 创建内核策略
+ * @param config 内核配置句柄
+ * @returns 内核策略
+ */
+export function createPolicy(config: CoreConfigHandle): KernelPolicy {
+  return new KernelPolicy(config)
+}

package/src/kernel/runtime.ts

@@ -16,7 +16,7 @@
  *
  *          **配置一律取 getter 或取值函数，不缓存快照。** 面板改了 `message.splitLength` 应当自下
  *          一条消息即生效。唯一的例外是 `message.concurrency` —— 信号量容量在创建时固定，这一点
- *          已写进它的配置说明。
+ *          已写进它的配置说明。
  */
 import type { Disposer, Logger } from "@yunzai-ng/types"
 import { AccountManager } from "../adapter/accounts.js"

package/src/pipeline/event.ts

@@ -12,7 +12,7 @@
  *          实例**刻意不 freeze、不 seal**：`EventExtensions` 的正规用法就是插件在事件上挂自有字段。
  *
  *          `e.render()` 依赖「当前执行的是哪个插件」（模板根随插件而定），故该绑定由 dispatch 在调
- *          每个 handler 之前经 `bind()` 替换，而不写进事件的构造参数 —— 一条消息会依次流经多个插件。
+ *          每个 handler 之前经 `bind()` 替换，而不写进事件的构造参数 —— 一条消息会依次流经多个插件。
  */
 import type {
   BotApi,

package/src/platform/system.ts

@@ -17,7 +17,7 @@
  *          返回空数组：空数组会被前端读成「确实有 0 块显卡」，而 0% 会被读成「GPU 空闲」。
  *
  *          **`nvidia-smi` 不存在这件事只查一次。** 没有 N 卡的机器上每 5 秒 spawn 一个必然
- *          ENOENT 的进程，一天是一万七千次。
+ *          ENOENT 的进程，一天是一万七千次。
  */
 import { constants as fsConstants } from "node:fs"
 import { access, readFile, statfs } from "node:fs/promises"

package/src/plugin/market.ts

@@ -623,7 +623,7 @@ export class PluginMarket {
       await this.#move(root, target)
       this.#deps.logger.info(`插件 ${name}@${version} 已安装至 ${target}`)
       if (needsDependencies) this.#deps.logger.warn(`插件 ${name} 声明了运行时依赖，需在其目录内自行执行包管理器安装`)
-      // 带 `.git` 的目录此后可就地拉取；归档装出来的每次更新都要整目录重下
+      // 带 `.git` 的目录此后可就地拉取；归档装出来的每次更新都要整目录重下
       return { name, dir: target, via, version, needsDependencies, updatable: via === "git" ? "pull" : "reinstall" }
     } finally {
       await rm(staging, { recursive: true, force: true })

package/src/plugin/services.ts

@@ -11,7 +11,7 @@
  *          且无从知道谁在用谁）。
  *
  *          键的所有者被记录下来，插件卸载时它提供的服务一起消失 —— 使用方拿到的是 undefined，
- *          而不是一个指向已卸载模块的失效引用。
+ *          而不是一个指向已卸载模块的失效引用。
  */
 import type { Disposer, DurationLike } from "@yunzai-ng/types"
 import { defer, type Deferred } from "../util/defer.js"

package/src/render/registry.ts

@@ -17,7 +17,7 @@
  *          抛出 —— 只报最后一个的话，真实原因常在第一个里。
  *
  *          **此处不限并发。** 同时渲染多张图会不会耗尽内存，取决于渲染器自己页面池的大小，
- *          只有渲染器插件知道那个数。内核再加一层信号量只会与插件内部的池互相干扰。
+ *          只有渲染器插件知道那个数。内核再加一层信号量只会与插件内部的池互相干扰。
  */
 import type {
   Disposer,

package/src/scheduler/index.ts

@@ -17,7 +17,7 @@
  *          停止等待，并记 error。
  *
  *          **执行出错同样计为已执行。** `lastRun` 在开始时就写，不等成功 —— 隐去失败的那次会让
- *          人误认为调度器没工作。
+ *          人误认为调度器没工作。
  */
 import type { Disposer, Logger, TaskFn, TaskInfo, TaskOptions } from "@yunzai-ng/types"
 import { Cron } from "croner"

package/src/server/auth.ts

@@ -16,7 +16,7 @@
  *          等于把「长度对不对」变成一个旁路信号；先摘要则两边恒为 32 字节。
  *
  *          **没设令牌时只放行本机**，判据是 TCP 对端地址，且服务器强制 `trustProxy: false` ——
- *          否则任何人都能靠一个 `X-Forwarded-For: 127.0.0.1` 把自己伪装成本机。
+ *          否则任何人都能靠一个 `X-Forwarded-For: 127.0.0.1` 把自己伪装成本机。
  */
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto"
 

package/src/server/files.ts

@@ -13,7 +13,7 @@
  *          这类服务器最致命的漏洞，值得两道锁。
  *
  *          **本文件不定位面板前端产物。** 面板是插件，产物目录由它自己解析并经 `ctx.panel()` 传入
- *          —— 内核一旦掌握前端的目录约定，「替换面板」就退化成必须改内核。
+ *          —— 内核一旦掌握前端的目录约定，「替换面板」就退化成必须改内核。
  */
 import { isDirectory, isFile, safeJoin } from "../util/fs.js"
 

package/src/server/index.ts

@@ -17,7 +17,7 @@
  *          等进了 `wsHandler` 再关连接，对方只看到一次没有理由的断线。
  *
  *          **静态资源刻意不鉴权。** 浏览器请求文档时设不了请求头，要鉴权就只剩 Cookie 一条路，
- *          那会把 auth.ts 刻意避开的 CSRF 面重新引进来。HTML/JS 本身不是机密，要保护的是 API。
+ *          那会把 auth.ts 刻意避开的 CSRF 面重新引进来。HTML/JS 本身不是机密，要保护的是 API。
  */
 import { isAbsolute } from "node:path"
 import type { IncomingMessage } from "node:http"

package/src/store/index.ts

@@ -1,156 +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
-    }
-  }
-}
+/**
+ * 模块职责：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
+    }
+  }
+}