@yunzai-ng/cli 0.1.0

package/dist/terminal.d.ts

@@ -0,0 +1,43 @@
+/** 加粗 */
+export declare const bold: (text: string) => string;
+/** 变暗，用于次要信息 */
+export declare const dim: (text: string) => string;
+/** 红色，用于错误 */
+export declare const red: (text: string) => string;
+/** 绿色，用于成功 */
+export declare const green: (text: string) => string;
+/** 黄色，用于警告 */
+export declare const yellow: (text: string) => string;
+/** 青色，用于路径与命令 */
+export declare const cyan: (text: string) => string;
+/**
+ * 向标准输出写入一行
+ * @param text 文本，缺省为空行
+ */
+export declare function print(text?: string): void;
+/**
+ * 向标准错误写入一行
+ *
+ * 分流的目的在于使 `yzng doctor > report.txt` 之类的重定向仍能在终端观察到错误信息。
+ * @param text 文本
+ */
+export declare function printErr(text: string): void;
+/**
+ * 估算字符串在等宽终端中占用的列数
+ *
+ * 仅区分"宽字符"与"窄字符"两档，不处理组合字符与 emoji 变体选择符 ——
+ * CLI 中出现的仅为中文标签与 ASCII 取值，更高的精度并无收益。
+ * @param text 文本
+ * @returns 列数
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * 输出一组"标签 值"，标签按显示宽度在右侧补齐
+ *
+ * 使用 `displayWidth` 而非 `str.length` 度量宽度：标签为中文，中文在等宽字体中
+ * 占两列 —— 按 UTF-16 码元数补空格会使整张表格错位。
+ * @param rows 标签与值
+ * @param indent 每行前缀空格数
+ */
+export declare function printRows(rows: readonly (readonly [string, string])[], indent?: number): void;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AA8BA,SAAS;AACT,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,MAA0B,CAAA;AAC9D,gBAAgB;AAChB,eAAO,MAAM,GAAG,GAAI,MAAM,MAAM,KAAG,MAA0B,CAAA;AAC7D,cAAc;AACd,eAAO,MAAM,GAAG,GAAI,MAAM,MAAM,KAAG,MAA2B,CAAA;AAC9D,cAAc;AACd,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,MAA2B,CAAA;AAChE,cAAc;AACd,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,MAA2B,CAAA;AACjE,iBAAiB;AACjB,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,MAA2B,CAAA;AAE/D;;;GAGG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAK,GAAG,IAAI,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,SAAI,GAAG,IAAI,CAMxF"}

package/dist/terminal.js

@@ -0,0 +1,94 @@
+/**
+ * 模块职责：终端输出 —— 换行、缩进、颜色与表格对齐
+ * 依赖方向：仅依赖 node:process，不涉及内核
+ * 生命周期：无状态，颜色开关于模块加载时确定一次
+ * 注意事项：**刻意不使用 `console`，而是直接写入 `process.stdout`。** 理由有二：
+ *          1) CLI 的输出是**程序结果**，而非日志。日志具有级别与 scope 并需落盘，
+ *             应经由 `loggerHub`；而 `yzng doctor` 输出的表格不应被写入 yunzai.log，
+ *             亦不应因日志级别被调整为 warn 而消失。
+ *          2) 仓库的 eslint 规则禁用了 `console`（仅保留 `console.error`），其目的在于
+ *             使插件必须经由 `ctx.logger` 输出。CLI 自身不应为此开设例外 —— 直接写入
+ *             stdout 既满足该规则，亦更准确地表达了"此为命令的输出流"。
+ */
+import process from "node:process";
+/** ANSI 转义引导符。写作转义序列而非字面控制字符：后者会被部分编辑器与补丁工具丢弃 */
+const ESC = "\u001b";
+/** 是否启用 ANSI 颜色：非 TTY（输出被管道接收）或已设置 NO_COLOR 时一律关闭 */
+const COLOR = process.stdout.isTTY === true && process.env["NO_COLOR"] === undefined;
+/**
+ * 为文本附加 ANSI 颜色
+ * @param code SGR 参数
+ * @param text 文本
+ * @returns 着色后的文本；未启用颜色时原样返回
+ */
+function paint(code, text) {
+    return COLOR ? `${ESC}[${code}m${text}${ESC}[0m` : text;
+}
+/** 加粗 */
+export const bold = (text) => paint("1", text);
+/** 变暗，用于次要信息 */
+export const dim = (text) => paint("2", text);
+/** 红色，用于错误 */
+export const red = (text) => paint("31", text);
+/** 绿色，用于成功 */
+export const green = (text) => paint("32", text);
+/** 黄色，用于警告 */
+export const yellow = (text) => paint("33", text);
+/** 青色，用于路径与命令 */
+export const cyan = (text) => paint("36", text);
+/**
+ * 向标准输出写入一行
+ * @param text 文本，缺省为空行
+ */
+export function print(text = "") {
+    process.stdout.write(`${text}\n`);
+}
+/**
+ * 向标准错误写入一行
+ *
+ * 分流的目的在于使 `yzng doctor > report.txt` 之类的重定向仍能在终端观察到错误信息。
+ * @param text 文本
+ */
+export function printErr(text) {
+    process.stderr.write(`${text}\n`);
+}
+/**
+ * 估算字符串在等宽终端中占用的列数
+ *
+ * 仅区分"宽字符"与"窄字符"两档，不处理组合字符与 emoji 变体选择符 ——
+ * CLI 中出现的仅为中文标签与 ASCII 取值，更高的精度并无收益。
+ * @param text 文本
+ * @returns 列数
+ */
+export function displayWidth(text) {
+    let width = 0;
+    for (const ch of text) {
+        const code = ch.codePointAt(0) ?? 0;
+        const wide = (code >= 0x1100 && code <= 0x115f) ||
+            (code >= 0x2e80 && code <= 0xa4cf) ||
+            (code >= 0xac00 && code <= 0xd7a3) ||
+            (code >= 0xf900 && code <= 0xfaff) ||
+            (code >= 0xfe30 && code <= 0xfe6f) ||
+            (code >= 0xff00 && code <= 0xff60) ||
+            (code >= 0xffe0 && code <= 0xffe6) ||
+            (code >= 0x20000 && code <= 0x3fffd);
+        width += wide ? 2 : 1;
+    }
+    return width;
+}
+/**
+ * 输出一组"标签 值"，标签按显示宽度在右侧补齐
+ *
+ * 使用 `displayWidth` 而非 `str.length` 度量宽度：标签为中文，中文在等宽字体中
+ * 占两列 —— 按 UTF-16 码元数补空格会使整张表格错位。
+ * @param rows 标签与值
+ * @param indent 每行前缀空格数
+ */
+export function printRows(rows, indent = 2) {
+    const width = Math.max(0, ...rows.map(([label]) => displayWidth(label)));
+    const pad = " ".repeat(indent);
+    for (const [label, value] of rows) {
+        print(`${pad}${dim(label)}${" ".repeat(width - displayWidth(label) + 1)}${value}`);
+    }
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@yunzai-ng/cli",
+  "version": "0.1.0",
+  "description": "Yunzai NG 命令行：init / start / dev / doctor / plugin",
+  "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "yzng": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@yunzai-ng/core": "0.1.0",
+    "@yunzai-ng/jsx": "0.1.0",
+    "@yunzai-ng/types": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/src/args.test.ts

@@ -0,0 +1,52 @@
+/**
+ * 模块职责：参数解析的行为测试
+ * 依赖方向：测试文件
+ * 生命周期：纯函数，无需夹具
+ * 注意事项：重点覆盖两处易于出错的边界 —— "选项值与后续子命令"之间的歧义，
+ *          以及 `--no-x` 的取反。二者出错的表现均为"命令看似执行成功但行为不符"，
+ *          其排查难度远高于直接报错。
+ */
+import { describe, expect, it } from "vitest"
+import { flagBoolean, flagString, parseArgs } from "./args.js"
+
+describe("参数解析", () => {
+  it("第一个非选项 token 为子命令，其余计入位置参数", () => {
+    const args = parseArgs(["plugin", "new", "我的插件"])
+    expect(args.command).toBe("plugin")
+    expect(args.positional).toEqual(["new", "我的插件"])
+  })
+
+  it("--key=value 与 --key value 等价", () => {
+    expect(flagString(parseArgs(["start", "--home=D:/yz"]), "home")).toBe("D:/yz")
+    expect(flagString(parseArgs(["start", "--home", "D:/yz"]), "home")).toBe("D:/yz")
+  })
+
+  it("下一个 token 形似选项时不将其作为值，而按布尔开关处理", () => {
+    const args = parseArgs(["--debug", "start"])
+    // start 必须保留给子命令，不可被 --debug 并入
+    expect(args.command).toBe("start")
+    expect(flagBoolean(args, "debug")).toBe(true)
+  })
+
+  it("--no-x 取反，且优先级高于 fallback", () => {
+    expect(flagBoolean(parseArgs(["start", "--no-console"]), "console", true)).toBe(false)
+    expect(flagBoolean(parseArgs(["start"]), "console", true)).toBe(true)
+  })
+
+  it("短选项可合并书写，-c 后可接值", () => {
+    const args = parseArgs(["-dv"])
+    expect(flagBoolean(args, "debug")).toBe(true)
+    expect(flagBoolean(args, "version")).toBe(true)
+    expect(flagString(parseArgs(["start", "-c", "D:/yz"]), "home")).toBe("D:/yz")
+  })
+
+  it("-- 之后原样保留，不作解析", () => {
+    const args = parseArgs(["start", "--", "--debug", "任意"])
+    expect(args.rest).toEqual(["--debug", "任意"])
+    expect(flagBoolean(args, "debug")).toBe(false)
+  })
+
+  it("空串选项值视为未提供，以免 --home= 被解析为空的主目录", () => {
+    expect(flagString(parseArgs(["start", "--home="]), "home")).toBeUndefined()
+  })
+})

package/src/args.ts

@@ -0,0 +1,132 @@
+/**
+ * 模块职责：命令行参数解析
+ * 依赖方向：无依赖
+ * 生命周期：纯函数
+ * 注意事项：手写实现而非引入 commander / yargs。CLI 的参数总计不足十个，
+ *          而这两个库各自会引入 10~30 个传递依赖 —— 对一个需在 Termux 上
+ *          执行 `pnpm install` 的框架而言，装机体积与安装时长是真实成本。
+ *
+ *          `--` 之后的内容原样收入 `rest`，不作解析：`yzng plugin new x -- --raw`
+ *          这类"将其余参数转交给下游"的场景需要该行为。
+ */
+
+/** 解析结果 */
+export interface ParsedArgs {
+  /** 子命令，未提供时为空串 */
+  readonly command: string
+  /** 子命令之后的位置参数 */
+  readonly positional: readonly string[]
+  /** 长短选项；出现但未带值的记为 `true` */
+  readonly flags: Readonly<Record<string, string | boolean>>
+  /** `--` 之后的原样内容 */
+  readonly rest: readonly string[]
+}
+
+/** 单字母短选项到长名的映射 */
+const SHORT: Readonly<Record<string, string>> = {
+  h: "help",
+  v: "version",
+  d: "debug",
+  c: "home"
+}
+
+/**
+ * 会带值的选项
+ *
+ * 必须显式列出，不可依据"下一个 token 不似选项即视为其值"推断 —— 该规则会使
+ * `yzng --debug start` 中的 `start` 被 `--debug` 并入，子命令因此为空，
+ * CLI 转而输出帮助，而使用者无从察觉问题所在。清单之外的选项一律为布尔开关；
+ * 确需为其传值时应写 `--新选项=值`，等号形式的优先级恒高于本清单。
+ */
+const VALUE_FLAGS: ReadonlySet<string> = new Set(["home", "plugins", "port", "host"])
+
+/**
+ * 解析 `process.argv.slice(2)`
+ * @param argv 参数数组
+ * @returns 解析结果
+ */
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  const rest: string[] = []
+  let command = ""
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i] ?? ""
+
+    if (token === "--") {
+      rest.push(...argv.slice(i + 1))
+      break
+    }
+
+    if (token.startsWith("--")) {
+      const body = token.slice(2)
+      const eq = body.indexOf("=")
+      if (eq >= 0) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1)
+        continue
+      }
+      if (body.startsWith("no-")) {
+        flags[body.slice(3)] = false
+        continue
+      }
+      // 仅清单内的选项会消耗下一个 token 作为其值。代价是以横杠开头的值
+      // （`--home -x`）须写作 `--home=-x`；该代价换取的是子命令绝不会被误并入
+      const next = argv[i + 1]
+      if (VALUE_FLAGS.has(body) && next !== undefined && !next.startsWith("-")) {
+        flags[body] = next
+        i++
+      } else {
+        flags[body] = true
+      }
+      continue
+    }
+
+    if (token.startsWith("-") && token.length > 1) {
+      // 允许 `-dv` 形式的合并写法；合并时仅最后一个字母可能带值
+      const letters = [...token.slice(1)]
+      for (let k = 0; k < letters.length; k++) {
+        const name = SHORT[letters[k] ?? ""] ?? letters[k] ?? ""
+        const last = k === letters.length - 1
+        const next = argv[i + 1]
+        if (last && VALUE_FLAGS.has(name) && next !== undefined && !next.startsWith("-")) {
+          flags[name] = next
+          i++
+        } else {
+          flags[name] = true
+        }
+      }
+      continue
+    }
+
+    if (command === "") command = token
+    else positional.push(token)
+  }
+
+  return { command, positional, flags, rest }
+}
+
+/**
+ * 取字符串选项
+ * @param args 解析结果
+ * @param name 选项名
+ * @returns 值；未提供或仅为布尔开关时 undefined
+ */
+export function flagString(args: ParsedArgs, name: string): string | undefined {
+  const value = args.flags[name]
+  return typeof value === "string" && value !== "" ? value : undefined
+}
+
+/**
+ * 取布尔选项
+ * @param args 解析结果
+ * @param name 选项名
+ * @param fallback 未提供时的取值
+ * @returns 布尔值
+ */
+export function flagBoolean(args: ParsedArgs, name: string, fallback = false): boolean {
+  const value = args.flags[name]
+  if (value === undefined) return fallback
+  if (typeof value === "boolean") return value
+  return value !== "false" && value !== "0"
+}

package/src/bin.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * 模块职责：`yzng` 可执行入口 —— 唯一允许调用 `process.exit` 的位置
+ * 依赖方向：仅调用 run()
+ * 生命周期：进程入口
+ * 注意事项：**未捕获异常在此处理，而非交由 Node 缺省处理。** Node 缺省会输出
+ *          完整调用栈，其中绝大部分为内核与 fastify 的栈帧；对使用者不具信息量，
+ *          反而将真正有用的第一行挤出屏幕。此处仅输出消息，调用栈保留给 `--debug`。
+ *
+ *          `unhandledRejection` 必须显式接管：自 Node 20 起其缺省行为是终止进程，
+ *          而"某个插件的 promise 未附加 catch"不应导致整个机器人下线。
+ */
+import process from "node:process"
+import { run } from "./run.js"
+
+/**
+ * 输出一条致命错误
+ * @param label 场景
+ * @param err 错误
+ */
+function fatal(label: string, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err)
+  process.stderr.write(`\n${label}：${message}\n`)
+  if (err instanceof Error && err.stack !== undefined && process.argv.includes("--debug")) {
+    process.stderr.write(`${err.stack}\n`)
+  } else {
+    process.stderr.write("附加 --debug 可查看完整调用栈\n")
+  }
+}
+
+process.on("unhandledRejection", reason => {
+  fatal("未处理的 promise 拒绝", reason)
+})
+
+try {
+  process.exitCode = await run(process.argv.slice(2))
+} catch (err) {
+  fatal("命令执行失败", err)
+  process.exitCode = 1
+}

package/src/commands/doctor.ts

@@ -0,0 +1,205 @@
+/**
+ * 模块职责：`yzng doctor` —— 环境自检：运行环境、目录、可选原生依赖、端口占用
+ * 依赖方向：依赖 @yunzai-ng/core 的公开入口与 node:net
+ * 生命周期：一次性，执行完毕即退出
+ * 注意事项：**每一项均须给出后续处置方式，否则本命令不具备存在价值。**
+ *          一句"Redis 连接失败"不指明该改哪里，等于把排障推回给使用者；故每条不合格项
+ *          都附一条可执行的下一步。
+ *
+ *          退出码：存在 `error` 级问题时为 1，仅有 `warn` 时仍为 0 ——
+ *          `yzng doctor && yzng start` 是自然的用法，不应被"尚未配置账号"一类提示阻断。
+ */
+import net from "node:net"
+import process from "node:process"
+import { createRequire } from "node:module"
+import { access } from "node:fs/promises"
+import { detectPlatform, resolvePaths, sampleUsage } from "@yunzai-ng/core"
+import { bold, cyan, dim, green, print, printRows, red, yellow } from "../terminal.js"
+
+/** Node 最低版本，与根 package.json 的 engines 保持一致 */
+const MIN_NODE_MAJOR = 20
+
+/** 一条自检结论 */
+interface Finding {
+  /** 严重程度 */
+  readonly level: "ok" | "warn" | "error"
+  /** 检查项名称 */
+  readonly title: string
+  /** 结论 */
+  readonly detail: string
+  /** 不合格时的下一步；合格时省略 */
+  readonly next?: string
+}
+
+/**
+ * 检查 Node 版本
+ * @returns 结论
+ */
+function checkNode(): Finding {
+  const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10)
+  if (major >= MIN_NODE_MAJOR) return { level: "ok", title: "Node 版本", detail: process.version }
+  return {
+    level: "error",
+    title: "Node 版本",
+    detail: `${process.version}，低于要求的 ${MIN_NODE_MAJOR}`,
+    next: "将 Node 升级至 20.11 或更高版本：内核使用了 import.meta.dirname 与原生 ESM 解析"
+  }
+}
+
+/**
+ * 检查一个可选原生依赖能否加载
+ *
+ * **解析基准必须是内核而非 CLI 自身。** pnpm 的隔离式 node_modules 将
+ * `classic-level` 安装于 `packages/core/node_modules` 之下，CLI 的模块图中并不含有
+ * 该包 —— 自 CLI 自身解析将一律得到"未安装"，而该结论会将使用者引向
+ * 一个并不存在的问题（去安装一个实际已安装完毕的包）。
+ *
+ * 使用 `createRequire` 而非 `await import()`：这两个包均为 CommonJS 原生扩展，
+ * 而此处需要区分的是"未安装"与"已安装但 ABI 不匹配"—— 仅 `require` 的报错信息中
+ * 携带 `NODE_MODULE_VERSION` 一段，动态 import 会将其重新包装并丢失该细节。
+ * @param name 包名
+ * @param purpose 该包的用途
+ * @param fallback 缺失时的降级说明
+ * @returns 结论
+ */
+function checkNative(name: string, purpose: string, fallback: string): Finding {
+  const self = createRequire(import.meta.url)
+  let require = self
+  try {
+    require = createRequire(self.resolve("@yunzai-ng/core/package.json"))
+  } catch {
+    // 未找到内核时退回自身解析：此情形下 CLI 属于单独安装，
+    // 报告"未安装"至少不构成误导，而真正的问题（内核缺失）由其他检查项覆盖
+  }
+  try {
+    require.resolve(name)
+  } catch {
+    return { level: "warn", title: name, detail: `未安装（${purpose}）`, next: `${fallback}。需要时执行：pnpm add -w ${name}` }
+  }
+  try {
+    require(name)
+    return { level: "ok", title: name, detail: `可用（${purpose}）` }
+  } catch (err) {
+    return {
+      level: "warn",
+      title: name,
+      detail: `已安装但加载失败：${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+      next: `原生模块与当前 Node ABI 不匹配，重建即可解决：pnpm rebuild ${name}。${fallback}`
+    }
+  }
+}
+
+/**
+ * 检查目录可达
+ * @param label 检查项名称
+ * @param dir 路径
+ * @returns 结论
+ */
+async function checkDir(label: string, dir: string): Promise<Finding> {
+  try {
+    await access(dir)
+    return { level: "ok", title: label, detail: cyan(dir) }
+  } catch {
+    return {
+      level: "warn",
+      title: label,
+      detail: `${cyan(dir)} ${dim("尚不存在")}`,
+      next: "首次启动时将自动创建；亦可先执行 yzng init"
+    }
+  }
+}
+
+/**
+ * 检查端口是否可监听
+ *
+ * 实际执行一次 bind 而非查询进程列表：其行为跨平台一致，且"能否监听"本身即为
+ * 内核关注的问题 —— 端口被同一用户的另一实例占用，与被防火墙策略拦截，
+ * 对启动而言结果相同。
+ * @param host 监听地址
+ * @param port 端口
+ * @returns 结论
+ */
+function checkPort(host: string, port: number): Promise<Finding> {
+  return new Promise<Finding>(resolve => {
+    const probe = net.createServer()
+    probe.once("error", (err: NodeJS.ErrnoException) => {
+      resolve({
+        level: "error",
+        title: "面板端口",
+        detail: `${host}:${port} 不可用（${err.code ?? err.message}）`,
+        next:
+          err.code === "EADDRINUSE"
+            ? "该端口已被其他程序占用（通常为另一个 Yunzai 实例）。请修改 config/yunzai.yaml 中的 server.port，或先停止该程序"
+            : "请检查监听地址是否属于本机网卡"
+      })
+    })
+    probe.once("listening", () => {
+      probe.close(() => resolve({ level: "ok", title: "面板端口", detail: `${host}:${port} 可用` }))
+    })
+    probe.listen(port, host)
+  })
+}
+
+/**
+ * 输出一条结论
+ * @param finding 结论
+ */
+function printFinding(finding: Finding): void {
+  const mark = finding.level === "ok" ? green("✓") : finding.level === "warn" ? yellow("!") : red("✗")
+  print(`  ${mark} ${finding.title}  ${finding.detail}`)
+  if (finding.next !== undefined) print(`      ${dim(`→ ${finding.next}`)}`)
+}
+
+/** 自检参数 */
+export interface DoctorOptions {
+  /** 应用主目录 */
+  readonly home?: string | undefined
+  /** 待探测的面板端口，缺省 2536（与配置缺省值一致） */
+  readonly port?: number | undefined
+  /** 待探测的监听地址 */
+  readonly host?: string | undefined
+}
+
+/**
+ * 执行一次环境自检
+ * @param opts 参数
+ * @returns 进程退出码；存在 error 级问题时为 1
+ */
+export async function runDoctor(opts: DoctorOptions = {}): Promise<number> {
+  const platform = detectPlatform()
+  const paths = resolvePaths({ home: opts.home })
+  const usage = sampleUsage()
+
+  print()
+  print(`  ${bold("环境")}`)
+  printRows([
+    ["系统", `${platform.os}/${platform.arch}${platform.isTermux ? " · Termux" : ""}${platform.isContainer ? " · 容器" : ""}`],
+    ["Node", platform.nodeVersion],
+    ["CPU", `${platform.cpus} 核`],
+    ["常驻内存", `${(usage.rss / 1024 / 1024).toFixed(1)} MB`]
+  ])
+
+  const findings: Finding[] = [
+    checkNode(),
+    await checkDir("主目录", paths.home),
+    await checkDir("配置目录", paths.config),
+    await checkDir("数据目录", paths.data),
+    checkNative("classic-level", "内嵌 KV，用于计数与冷却", "缺失时内核降级为 JSON 文件存储，功能不受影响但写入速度较低"),
+    checkNative("better-sqlite3", "关系数据，用于插件建表", "缺失时依赖 SQL 的插件将取得一条错误说明，而非静默失效"),
+    await checkPort(opts.host ?? "127.0.0.1", opts.port ?? 2536)
+  ]
+
+  print()
+  print(`  ${bold("检查")}`)
+  for (const finding of findings) printFinding(finding)
+
+  const errors = findings.filter(f => f.level === "error").length
+  const warns = findings.filter(f => f.level === "warn").length
+  print()
+  if (errors > 0) print(`  ${red(`${errors} 项需要处理`)}${warns > 0 ? dim(`，${warns} 项提示`) : ""}`)
+  else if (warns > 0) print(`  ${yellow(`${warns} 项提示`)}${dim("，不影响启动")}`)
+  else print(`  ${green("全部检查项正常")}`)
+  print()
+
+  return errors > 0 ? 1 : 0
+}

package/src/commands/init.ts

@@ -0,0 +1,65 @@
+/**
+ * 模块职责：`yzng init` —— 在主目录中建立目录布局与缺省配置文件
+ * 依赖方向：依赖 @yunzai-ng/core 的公开入口
+ * 生命周期：一次性，执行完毕即退出
+ * 注意事项：**刻意不经由 `createApp()`。** `createApp` 会一并打开 KV 数据库、
+ *          建立 HTTP 客户端连接池、装配插件宿主 —— 在"仅需查看配置文件结构"
+ *          的场景中，上述工作均属额外开销，且 KV 无法打开时会直接抛出异常，
+ *          使一次本应成功的初始化转为失败。此处仅执行两项必要工作：建立目录、
+ *          声明配置（从而将缺省值落盘）。
+ *
+ *          幂等：已存在的目录与配置文件均不会被覆盖（`ConfigStore` 仅在文件
+ *          缺失时写入缺省值），因此对一个已长期运行的实例再次执行 init 是安全的。
+ */
+import { ConfigStore, createLoggerHub, defineCoreConfig, ensurePaths, resolvePaths } from "@yunzai-ng/core"
+import { linkFramework } from "../link.js"
+import { bold, cyan, dim, green, print, printErr, printRows, red, yellow } from "../terminal.js"
+
+/** 初始化参数 */
+export interface InitOptions {
+  /** 应用主目录；缺省时按内核的探测顺序确定 */
+  readonly home?: string | undefined
+}
+
+/**
+ * 建立主目录与缺省配置
+ * @param opts 参数
+ * @returns 进程退出码
+ */
+export async function runInit(opts: InitOptions = {}): Promise<number> {
+  // 仅输出至控制台、级别限制为 warn：ConfigStore 自身会输出"已写出缺省配置"一类的
+  // info，而本命令需要给出的是一份经过整理的清单，两者叠加将降低可读性
+  const hub = createLoggerHub({ level: "warn", console: true })
+  try {
+    const paths = await ensurePaths(resolvePaths({ home: opts.home }))
+    const store = new ConfigStore({ dir: paths.config, logger: hub.root, watch: false })
+    const config = await defineCoreConfig(store)
+    const link = await linkFramework(paths.home)
+
+    print()
+    print(`  ${bold(green("已就绪"))} ${dim("目录与缺省配置均已建立")}`)
+    print()
+    printRows([
+      ["主目录", cyan(paths.home)],
+      ["配置", cyan(paths.config)],
+      ["数据", cyan(paths.data)],
+      ["日志", cyan(paths.logs)],
+      ["插件", cyan(paths.plugins)],
+      ["临时", cyan(paths.temp)]
+    ])
+    print()
+    if (link.failed.length > 0) {
+      print(`  ${yellow("!")} 框架包未能链接至主目录，插件将无法 import @yunzai-ng/core`)
+      for (const [name, reason] of link.failed) print(`      ${dim(`${name}：${reason}`)}`)
+      print()
+    }
+    print(`  ${dim("下一步")} ${cyan("yzng start")} ${dim(`随后访问 http://${config.get().server.host}:${config.get().server.port}/`)}`)
+    print()
+    return 0
+  } catch (err) {
+    printErr(red(`初始化失败：${err instanceof Error ? err.message : String(err)}`))
+    return 1
+  } finally {
+    hub.close()
+  }
+}