@napuketto/cli 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,99 +1,436 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { ConfigBase, createLogger, kernelError, parseLogConfig, parseToml, resolveConfigPath, resolveDataRoot, stringifyToml } from "@napuketto/kernel";
+import { ConfigBase, ConfigError, EXIT_CONFIG_INVALID, configError, createLogger, kernelError, parseLogConfig, parseToml, resolveConfigPath, resolveDataRoot, stringifyToml } from "@napuketto/kernel";
 import { Command } from "commander";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import path, { dirname, extname, isAbsolute, join } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { checkInstanceLock, defaultStubDir, isNativeNoiseLine, launchSelfHost, removeStopSentinel, resolveQqFiles, watchStopSentinel, writeStopSentinel } from "@napuketto/loader";
 import QRCode from "qrcode";
-import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { access, readFile, writeFile } from "node:fs/promises";
-//#region src/logger.ts
+//#region src/config-template.ts
 /**
-* cli 进程级 logger（ADR-007 日志规范，2026-08-07 统一改造；2026-10-25 日志可配置化）。
-*
-* 复用 kernel `createLogger`；输出格式/级别/时间戳/颜色由 napuketto.toml [log] 段 +
-* 环境变量决定（kernel parseLogConfig 单一解析源）。懒构造：commander preAction
-* 钩子先 resolveCliLogConfig(dataDir)（banner 决策 + 缓存），首个日志调用时按
-* 缓存配置构造；未初始化时兜底用缺省数据根解析（-d 生效前的极早期日志）。
+* 配置模板（TOML 注释版，从 config-cmds.ts 拆分，2026-08-08 FTA 优化）。
+* `config init` 与首次启动（loadCliConfig）缺失时生成。
 *
-* 环境变量（优先级高于 toml，见 kernel parseLogConfig）：NAPUKETTO_LOG_LEVEL /
-* NAPUKETTO_LOG_FORMAT / NAPUKETTO_NO_BANNER / NAPUKETTO_LOG_COLORIZE，
-* 兼容旧拼写 NAPKETTO_LOG_LEVEL。
+* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
+* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
+* dataDir 不再写死（缺省 = 项目根/.napuketto，跨平台），模板保持可移植。
 */
-/** 已解析日志配置缓存（preAction 首次解析后固定；-d 后续变化不影响已构造 logger）。 */
-let cachedConfig = null;
-/** 解析配置时用的数据根（[log.file] 相对路径展开基准）。 */
-let cachedDataRoot = resolveDataRoot();
-/** 同步解析日志配置（toml [log] 段 + env 覆盖）。损坏/缺失配置回退缺省（不阻塞启动：
-* 配置的严格校验由 loadCliConfig 主路径负责报错）。 */
-function resolveCliLogConfig(dataDir) {
-	if (cachedConfig !== null) return cachedConfig;
-	cachedDataRoot = resolveDataRoot(dataDir);
-	let section;
-	try {
-		const configPath = resolveConfigPath({ dataRoot: cachedDataRoot });
-		section = parseToml(readFileSync(configPath, "utf8"))["log"];
-	} catch {
-		section = void 0;
-	}
-	try {
-		cachedConfig = parseLogConfig(section, process.env);
-	} catch {
-		cachedConfig = parseLogConfig(void 0, process.env);
-	}
-	return cachedConfig;
+/** 保留占位 QQ 号（模板默认值）：必须替换为真实 QQ 号，否则启动校验报错。 */
+const RESERVED_PLACEHOLDER_QINS = ["123456", "654321"];
+function configTemplate() {
+	return `# ============================================================
+# NapukettoQQ 全局配置文件
+# ============================================================
+# 本文件由 \`napuketto config init\` 生成（或首次启动自动生成）。
+# 本机配置不入库（.gitignore）；修改后重启生效。
+#
+# 配置组织：一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在账号内
+# （[accounts.onebot11] / [accounts.satori] / [accounts.kurobot]）。账号没有写
+# 某协议段 = 该账号不启用该协议。账号必填（至少一个，qq 必填）。
+
+# ------------------------------------------------------------
+# 全局配置（跨账号）
+# ------------------------------------------------------------
+
+# 数据根目录：账号目录/日志/缓存/QQ 数据存放位置。
+# 缺省 = <项目根>/.napuketto（部署场景，跨平台，无需修改）。
+# 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录）。
+# dataDir = ".napuketto"
+
+# 多账号（supervisor）模式下，账号进程崩溃是否自动重启
+autoRestart = true
+
+# 崩溃后自动重启的延迟（毫秒）
+restartDelayMs = 2000
+
+# ------------------------------------------------------------
+# 日志（[log]，可选——不配置即用缺省：终端 pretty 多行 / 管道 single-line）
+# ------------------------------------------------------------
+# 嵌入式宿主（把 napuketto 打进服务端等场景）推荐：
+#   [log]
+#   format = "single-line"     # 或 "json"（NDJSON，宿主按 level/module 精确路由）
+#   level = "warn"             # 控制台只留警告以上，细节进文件（配 [log.file]）
+#   banner = false
+#
+# [log]
+# format = "pretty"            # pretty | single-line | json（缺省按 TTY 自动）
+# level = "info"               # trace|debug|info|warn|error|fatal（控制台级别）
+# banner = true                # 启动字符画
+# timestamp = "local"          # local | iso8601 | elapsed
+# unboundReceive = true        # false = 未绑定频道的接收行不打（kurobot 握手后生效）
+# [log.levels]                 # 按模块覆盖级别：cli / kernel / loader / ob11
+# # loader = "debug"           # 例：终端上看接收行（默认已降 debug）
+# # ob11 = "debug"             # 例：协议校准数据（含原始 hex）
+# [log.file]                   # 独立文件 sink（可选；级别可低于控制台）
+# # path = "logs/napuketto-console.log"
+# # level = "debug"
+#
+# 环境变量覆盖（优先级高于本文件）：NAPUKETTO_LOG_LEVEL / NAPUKETTO_LOG_FORMAT /
+# NAPUKETTO_NO_BANNER（兼容旧拼写 NAPKETTO_LOG_LEVEL）。
+
+# ------------------------------------------------------------
+# 账号（至少一个，qq 必填）
+# ------------------------------------------------------------
+
+[[accounts]]
+qq = "${RESERVED_PLACEHOLDER_QINS[0]}"            # 占位值，必须替换为你的 QQ 号，否则启动报错
+enabled = true           # 是否启用（可选，缺省 true）
+
+[accounts.onebot11]      # 该账号的 OneBot 11 配置（无此段 = 不启用 OB11）
+
+# 鉴权 token（全局默认）：HTTP/WS 连接必须携带。
+#   校验方式：Authorization: Bearer <token> / 裸 token / URL 参数 ?access_token=<token>
+#   每个网络实例可单独覆盖（见下文各实例的 token 字段）。
+#   留空 = 不鉴权（仅本机调试推荐）。
+# token = ""
+
+# 心跳 meta 事件间隔（毫秒）；0 = 关闭心跳事件
+heartbeatInterval = 3000
+
+# 是否上报机器人自己发的消息（OB11 规范默认不上报）
+reportSelfMessage = false
+
+# 消息内容格式：array = 消息段数组（标准 OneBot 11），string = CQ 码字符串
+messagePostFormat = "array"
+
+# 群文件报形式：false（默认）= message 事件 + file 段（go-cqhttp 兼容）；
+# true = 群文件消息改报 group_upload notice 事件（替代 message 事件）
+groupUploadAsNotice = false
+
+# ---- HTTP 反向服务器（接收第三方 POST 指令），可配置多个 ----
+[[accounts.onebot11.httpServers]]
+enabled = true
+host = "127.0.0.1"       # 监听地址；0.0.0.0 = 监听所有网卡（局域网可连）
+port = 3000
+# token = "abc"          # 可选：覆盖全局 token
+
+# ---- HTTP 正向上报（Webhook：把事件 POST 到第三方地址），可配置多个 ----
+# [[accounts.onebot11.httpPostUrls]]
+# enabled = true
+# url = "http://127.0.0.1:8080/onebot"   # 第三方接收地址
+# token = "abc"                          # 可选：覆盖全局 token
+# timeoutMs = 5000                       # 可选：上报超时（毫秒），缺省不超时
+
+# ---- WS 反向服务器（外部 WS 客户端主动连入），可配置多个 ----
+[[accounts.onebot11.wsServers]]
+enabled = true
+host = "127.0.0.1"
+port = 3001
+# token = "abc"                          # 可选：覆盖全局 token
+# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
+
+# ---- WS 正向客户端（主动连接外部 WS，双向），可配置多个 ----
+# [[accounts.onebot11.wsReverseUrls]]
+# enabled = true
+# url = "ws://127.0.0.1:8081/ws"         # 第三方 WS 地址（ws:// 或 wss://）
+# token = "abc"                          # 可选：覆盖全局 token
+# reconnectDelayMs = 5000                # 可选：断线重连延迟（毫秒）
+# maxReconnectAttempts = 10              # 可选：最大重连次数（缺省无限）
+# rejectUnauthorized = true              # 可选：wss:// 是否校验证书（自签证书设 false）
+# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
+
+# 第二个账号示例（只开 Satori）：
+# [[accounts]]
+# qq = "${RESERVED_PLACEHOLDER_QINS[1]}"
+# [accounts.satori]
+# # token = ""                           # 可选：Satori 鉴权 token
+# [[accounts.satori.httpServers]]        # HTTP RPC（POST /v1/{resource}.{method}）
+# enabled = true
+# host = "127.0.0.1"
+# port = 5500
+# [[accounts.satori.wsServers]]          # WS 事件服务（/v1/events）
+# enabled = true
+# host = "127.0.0.1"
+# port = 5501
+
+# ------------------------------------------------------------
+# KuroBot 群服互通（kurobridge-ws 客户端，MVP-3）
+# ------------------------------------------------------------
+# 账号内写 [accounts.kurobot] 段即启用；不写 = 不启用。作为 WS 客户端
+# 主动连入 KuroBot 服务端（Minecraft 服务器 kurobot 插件）。
+# QQ 群文字 ↔ 游戏聊天双向互通；群命令（前缀开头）→ 游戏命令。
+# [accounts.kurobot]
+# url = "ws://127.0.0.1:25580"           # 必填：KuroBot 服务端地址（ws:// 或 wss://）
+# # token = ""                           # 可选：鉴权 token（服务端配了则必填，错 token 拒连）
+# # client = "napukettoqq"               # 可选：自报身份（缺省 napukettoqq/<版本>）
+# # commandPrefix = "/"                  # 可选：群命令前缀
+# # pingIntervalMs = 15000               # 可选：应用层心跳间隔（毫秒，须 < 30000）
+# # chatTemplate = "[{player}] {content}"    # 游戏聊天渲染模板
+# # joinTemplate = "{player} 加入了服务器"    # 玩家进服模板
+# # leaveTemplate = "{player} 离开了服务器"   # 玩家退服模板
+# # deathTemplate = "{player} {message}"     # 玩家死亡模板（空消息显示「死亡了」）
+`;
 }
+//#endregion
+//#region src/config-parse.ts
 /**
-* 顶层进程的最终控制台格式（[log] format 显式优先，否则按 TTY 自动：
-* 终端 pretty / 管道 single-line）。supervisor 的前缀转发决策同源。
+* 主配置类型与手写校验器（从 config-cmds.ts 拆分，2026-08-08 FTA 优化）
+*
+* 主配置 parse（不引入 zod）：数据根 / 自动重启 / 重启延迟 / 账号列表。
+* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
+* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
+* 协议段为宽松对象，装配时由对应协议包的 zod schema 严格校验。
+* 全部校验错误为 ConfigError（2026-10-25 嵌入式退出码契约：CLI exit 78 一族，
+* 内联与文件两形态共用本校验器）。
 */
-function effectiveConsoleFormat(cfg) {
-	const isTty = process.stdout.isTTY === true;
-	return cfg.format ?? (isTty ? "pretty" : "single-line");
+/** 默认自动重启。 */
+const DEFAULT_AUTO_RESTART = true;
+/** 默认重启延迟（毫秒）。 */
+const DEFAULT_RESTART_DELAY_MS$1 = 2e3;
+/** QQ 号格式：纯数字 5-11 位（QQ 号合法范围，勿写死 11 位）。 */
+const QQ_IN_FORMAT_RE = /^\d{5,11}$/;
+/** 解析账号内协议段（宽松对象，装配时由 zod schema 严格校验）。 */
+function parseProtocolSection(raw, key) {
+	const section = raw[key];
+	if (section === void 0) return;
+	if (typeof section !== "object" || section === null) throw configError(`主配置账号 ${key} 段必须是对象`);
+	return section;
 }
 /**
-* 顶层进程的有效控制台渲染决策（传播给子进程）：
-* 子进程 stdout 恒为 pipe（TTY 判定失真），由本进程按最终控制台形态决定
-* format/colorize 并经 env 注入（NAPUKETTO_LOG_FORMAT/NAPUKETTO_LOG_COLORIZE）。
+* 解析 dataDir（缺省用当前解析的数据根 = 项目根/.napuketto）。
+* 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录），
+* 消费端 resolveDataRoot 统一展开为绝对路径。
 */
-function effectiveConsoleEnv(cfg) {
-	const isTty = process.stdout.isTTY === true;
-	const format = effectiveConsoleFormat(cfg);
-	return {
-		NAPUKETTO_LOG_FORMAT: format,
-		NAPUKETTO_LOG_COLORIZE: cfg.colorize ?? (format === "pretty" && isTty) ? "1" : "0"
-	};
+function parseDataDir(raw) {
+	if (raw["dataDir"] === void 0) return resolveDataRoot();
+	if (typeof raw["dataDir"] !== "string" || raw["dataDir"] === "") throw configError("主配置 dataDir 必须是非空字符串");
+	return raw["dataDir"];
 }
-/** [log.file] 相对路径按数据根展开。 */
-function resolveLogFilePath(path) {
-	return isAbsolute(path) ? path : join(cachedDataRoot, path);
+/** 解析 autoRestart。 */
+function parseAutoRestart(raw) {
+	if (raw["autoRestart"] === void 0) return DEFAULT_AUTO_RESTART;
+	if (typeof raw["autoRestart"] !== "boolean") throw configError("主配置 autoRestart 必须是布尔值");
+	return raw["autoRestart"];
 }
-/** cli logger 构造参数（[log] 段折叠；file/fileLevel 成对生效，其余直传 undefined）。 */
-function cliLoggerOptions(cfg) {
-	return {
-		level: cfg.levels.cli ?? cfg.level,
-		format: cfg.format,
-		timestamp: cfg.timestamp,
-		colorize: cfg.colorize,
-		file: cfg.file !== void 0 ? resolveLogFilePath(cfg.file.path) : void 0,
-		fileLevel: cfg.file?.level,
-		base: {
-			name: "cli",
-			service: "cli"
-		}
-	};
+/** 解析 restartDelayMs（毫秒）。 */
+function parseRestartDelayMs(raw) {
+	if (raw["restartDelayMs"] === void 0) return DEFAULT_RESTART_DELAY_MS$1;
+	if (typeof raw["restartDelayMs"] !== "number" || !Number.isInteger(raw["restartDelayMs"]) || raw["restartDelayMs"] <= 0) throw configError("主配置 restartDelayMs 必须是正整数");
+	return raw["restartDelayMs"];
 }
-/** 懒构造 cli 进程日志（name 渲染为 (cli/pid) 元数据头，文件 JSON 保留 name 字段可过滤）。 */
-var LazyCliLogger = class {
-	#inner = null;
-	#ensure() {
-		if (this.#inner === null) this.#inner = createLogger(cliLoggerOptions(resolveCliLogConfig()));
-		return this.#inner;
-	}
-	info(obj, msg) {
+/** 解析 accounts（必须至少一个账号，qq 必填）。 */
+function parseAccounts(raw) {
+	if (raw["accounts"] === void 0) throw configError("主配置缺少 accounts（必须至少一个账号）；首次启动已生成模板，请编辑后重试");
+	if (!Array.isArray(raw["accounts"]) || raw["accounts"].length === 0) throw configError("主配置 accounts 必须是非空数组（至少一个 QQ 账号）；首次启动已生成模板，请编辑后重试");
+	const accounts = [];
+	for (const item of raw["accounts"]) accounts.push(parseAccount(item));
+	return accounts;
+}
+/** 账号 qq 必填校验（非空字符串）。 */
+function parseAccountQq(raw) {
+	const qq = raw["qq"];
+	if (typeof qq !== "string" || qq === "") throw configError("主配置账号缺少非空 qq");
+	assertValidQqFormat(qq);
+	return qq;
+}
+/** qq 格式与占位值校验（5-11 位纯数字；模板占位号显式指路不静默）。 */
+function assertValidQqFormat(qq) {
+	if (!QQ_IN_FORMAT_RE.test(qq)) throw configError("主配置账号 qq 必须是 5-11 位纯数字 QQ 号");
+	if (RESERVED_PLACEHOLDER_QINS.some((placeholder) => placeholder === qq)) throw configError(`主配置账号 qq "${qq}" 是模板占位值，请编辑配置文件填入真实 QQ 号后再启动`);
+}
+/** 账号 enabled 可选校验（缺省 = 启用；显式给值必须是布尔）。 */
+function applyAccountEnabled(out, enabled) {
+	if (enabled === void 0) return;
+	if (typeof enabled !== "boolean") throw configError("主配置账号 enabled 必须是布尔值");
+	out.enabled = enabled;
+}
+/** 账号内协议段装配（onebot11/satori/kurobot 缺省 = 不启用该协议）。 */
+function applyProtocolSections(raw, out) {
+	const onebot11 = parseProtocolSection(raw, "onebot11");
+	if (onebot11 !== void 0) out.onebot11 = onebot11;
+	const satori = parseProtocolSection(raw, "satori");
+	if (satori !== void 0) out.satori = satori;
+	const kurobot = parseProtocolSection(raw, "kurobot");
+	if (kurobot !== void 0) out.kurobot = kurobot;
+}
+/** 解析单个账号项（qq 必填；协议段缺省 = 不启用）。 */
+function parseAccount(item) {
+	if (typeof item !== "object" || item === null) throw configError("主配置 accounts 元素必须是对象");
+	const raw = item;
+	const out = { qq: parseAccountQq(raw) };
+	applyAccountEnabled(out, raw["enabled"]);
+	applyProtocolSections(raw, out);
+	return out;
+}
+/**
+* [log] 段落库净化：format 为 undefined（= 按 TTY 自动）时剔除该键，
+* 避免 toml 回写（config list/apply 的 stringifyToml）遇到 undefined 值。
+*/
+function stripUndefinedFormat(log) {
+	const { format, ...rest } = log;
+	return format === void 0 ? rest : {
+		...rest,
+		format
+	};
+}
+/**
+* [log] 段解析（kernel parseLogConfig 错误归一为 ConfigError）：日志段非法同属
+* 「配置未就绪」一族（exit 78）；错误文案保持 kernel 原文（主配置 log.xxx ...）。
+*/
+function parseLogSection(input) {
+	try {
+		return parseLogConfig(input);
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		throw configError(`主配置 [log] 段非法: ${detail}`, { cause: err });
+	}
+}
+/** 手写校验器：主配置 parse（不引入 zod）。全部校验错误为 ConfigError（exit 78 一族）。 */
+function parseCliConfig(input) {
+	if (typeof input !== "object" || input === null) throw configError("主配置必须是对象");
+	const raw = input;
+	const dataDir = parseDataDir(raw);
+	const autoRestart = parseAutoRestart(raw);
+	const restartDelayMs = parseRestartDelayMs(raw);
+	const accounts = parseAccounts(raw);
+	const log = raw["log"] !== void 0 ? stripUndefinedFormat(parseLogSection(raw["log"])) : void 0;
+	return {
+		dataDir,
+		autoRestart,
+		restartDelayMs,
+		accounts,
+		...log !== void 0 ? { log } : {}
+	};
+}
+//#endregion
+//#region src/config-inline.ts
+/**
+* 内联配置（NAPKETTO_CONFIG_JSON，2026-10-25 嵌入式宿主契约）。
+*
+* KuroBridge 等嵌入式宿主每次拉起前整体生成配置，经环境变量喂 JSON 文本
+* （与 napuketto.toml 同构：parseCliConfig 直接吃 JSON.parse 产物），消除托管
+* toml 文件本体。优先级 NAPKETTO_CONFIG_JSON > NAPKETTO_CONFIG > 缺省模板生成；
+* 内联生效时不读 / 不写 / 不校验任何 toml 文件。Windows 单环境变量上限 32767
+* 字符（约 32KB），嵌入式配置形状远小于该限（超限宿主退回文件形态）。
+*
+* 错误一概 ConfigError（exit 78 一族），文案指明来源为「内联配置」且不含任何
+* toml 文件路径。本模块不 import logger（logger.ts 反向依赖本模块判内联来源）。
+*/
+/** 内联配置 env 键（读取为精确键访问；Windows 上 process.env 本身大小写不敏感）。 */
+const INLINE_CONFIG_ENV = "NAPKETTO_CONFIG_JSON";
+/**
+* 读取内联配置文本（未设置 / 空串 / 纯空白 → undefined，回退文件形态）。
+*/
+function readInlineConfigText() {
+	const raw = process.env[INLINE_CONFIG_ENV];
+	if (raw === void 0 || raw.trim() === "") return;
+	return raw;
+}
+/** 内联是否生效（boot/装配链决定「不碰文件」的判定口径，与 readInlineConfigText 同源）。 */
+function isInlineConfigActive() {
+	return readInlineConfigText() !== void 0;
+}
+/**
+* 内联 JSON 文本 → 校验后的主配置。JSON 解析失败 / 非对象 / 字段校验失败
+* 均抛 ConfigError（宿主消费 exit 78，不重试）。
+*/
+function parseInlineConfig(text) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		throw configError(`内联配置 JSON 解析失败: ${detail}`, { cause: err });
+	}
+	if (typeof doc !== "object" || doc === null || Array.isArray(doc)) throw configError("内联配置必须是 JSON 对象（与 napuketto.toml 同构）");
+	return parseCliConfig(doc);
+}
+//#endregion
+//#region src/logger.ts
+/**
+* cli 进程级 logger（ADR-007 日志规范，2026-08-07 统一改造；2026-10-25 日志可配置化）。
+*
+* 复用 kernel `createLogger`；输出格式/级别/时间戳/颜色由 napuketto.toml [log] 段 +
+* 环境变量决定（kernel parseLogConfig 单一解析源）。懒构造：commander preAction
+* 钩子先 resolveCliLogConfig(dataDir)（banner 决策 + 缓存），首个日志调用时按
+* 缓存配置构造；未初始化时兜底用缺省数据根解析（-d 生效前的极早期日志）。
+*
+* 环境变量（优先级高于 toml，见 kernel parseLogConfig）：NAPUKETTO_LOG_LEVEL /
+* NAPUKETTO_LOG_FORMAT / NAPUKETTO_NO_BANNER / NAPUKETTO_LOG_COLORIZE，
+* 兼容旧拼写 NAPKETTO_LOG_LEVEL。
+*/
+/** 已解析日志配置缓存（preAction 首次解析后固定；-d 后续变化不影响已构造 logger）。 */
+let cachedConfig = null;
+/** 解析配置时用的数据根（[log.file] 相对路径展开基准）。 */
+let cachedDataRoot = resolveDataRoot();
+/** 同步解析日志配置（内联 > toml 文件的 [log] 段 + env 覆盖）。损坏/缺失配置回退缺省
+* （不阻塞启动：配置的严格校验由 loadCliConfig 主路径负责报错）。内联生效时不读
+* 任何 toml 文件（嵌入式契约，2026-10-25）。 */
+function resolveCliLogConfig(dataDir) {
+	if (cachedConfig !== null) return cachedConfig;
+	cachedDataRoot = resolveDataRoot(dataDir);
+	let section;
+	const inlineText = readInlineConfigText();
+	if (inlineText !== void 0) try {
+		section = JSON.parse(inlineText)["log"];
+	} catch {
+		section = void 0;
+	}
+	else try {
+		const configPath = resolveConfigPath({ dataRoot: cachedDataRoot });
+		section = parseToml(readFileSync(configPath, "utf8"))["log"];
+	} catch {
+		section = void 0;
+	}
+	try {
+		cachedConfig = parseLogConfig(section, process.env);
+	} catch {
+		cachedConfig = parseLogConfig(void 0, process.env);
+	}
+	return cachedConfig;
+}
+/**
+* 顶层进程的最终控制台格式（[log] format 显式优先，否则按 TTY 自动：
+* 终端 pretty / 管道 single-line）。supervisor 的前缀转发决策同源。
+*/
+function effectiveConsoleFormat(cfg) {
+	const isTty = process.stdout.isTTY === true;
+	return cfg.format ?? (isTty ? "pretty" : "single-line");
+}
+/**
+* 顶层进程的有效控制台渲染决策（传播给子进程）：
+* 子进程 stdout 恒为 pipe（TTY 判定失真），由本进程按最终控制台形态决定
+* format/colorize 并经 env 注入（NAPUKETTO_LOG_FORMAT/NAPUKETTO_LOG_COLORIZE）。
+*/
+function effectiveConsoleEnv(cfg) {
+	const isTty = process.stdout.isTTY === true;
+	const format = effectiveConsoleFormat(cfg);
+	return {
+		NAPUKETTO_LOG_FORMAT: format,
+		NAPUKETTO_LOG_COLORIZE: cfg.colorize ?? (format === "pretty" && isTty) ? "1" : "0"
+	};
+}
+/** [log.file] 相对路径按数据根展开。 */
+function resolveLogFilePath(path) {
+	return isAbsolute(path) ? path : join(cachedDataRoot, path);
+}
+/** cli logger 构造参数（[log] 段折叠；file/fileLevel 成对生效，其余直传 undefined）。 */
+function cliLoggerOptions(cfg) {
+	return {
+		level: cfg.levels.cli ?? cfg.level,
+		format: cfg.format,
+		timestamp: cfg.timestamp,
+		colorize: cfg.colorize,
+		file: cfg.file !== void 0 ? resolveLogFilePath(cfg.file.path) : void 0,
+		fileLevel: cfg.file?.level,
+		base: {
+			name: "cli",
+			service: "cli"
+		}
+	};
+}
+/** 懒构造 cli 进程日志（name 渲染为 (cli/pid) 元数据头，文件 JSON 保留 name 字段可过滤）。 */
+var LazyCliLogger = class {
+	#inner = null;
+	#ensure() {
+		if (this.#inner === null) this.#inner = createLogger(cliLoggerOptions(resolveCliLogConfig()));
+		return this.#inner;
+	}
+	info(obj, msg) {
 		this.#ensure().info(obj, msg);
 	}
 	warn(obj, msg) {
@@ -115,6 +452,31 @@ var LazyCliLogger = class {
 /** cli 进程日志（懒构造，配置见 resolveCliLogConfig）。 */
 const logger = new LazyCliLogger();
 //#endregion
+//#region src/action-error.ts
+/**
+* CLI 动作错误出口（2026-10-25 退出码契约）：
+*   0 = 请求式优雅关停（0.2.0 已有，不经此路径）；78 = 配置校验失败
+*   （ConfigError 一族，宿主据此区分「配置未就绪」与运行时崩溃，免重启）；
+*   其余 = 1（运行时崩溃，现状不变）。
+*
+* 退出码只认错误类型（instanceof ConfigError），与日志文案完全解耦——
+* 文案是人读的，退出码是宿主消费的机器契约。
+*/
+/** 统一错误输出（结构化日志，错误对象经 pino serializer 带堆栈）。 */
+function reportError(err) {
+	let message = String(err);
+	if (err instanceof Error) {
+		const { message: errMessage } = err;
+		message = errMessage;
+	}
+	logger.error({ err }, message);
+}
+/** 统一 catch 出口：打印错误并按类型设置进程退出码（78 = 配置校验失败）。 */
+function handleActionError(err) {
+	reportError(err);
+	process.exitCode = err instanceof ConfigError ? EXIT_CONFIG_INVALID : 1;
+}
+//#endregion
 //#region src/runtime-state.ts
 /**
 * runtime-state.ts：账号运行时状态文件 + 进程控制原语（2026-09-08 T8）。
@@ -228,22 +590,6 @@ function aggregateStatus(runtimes, aliveFn = isPidAlive) {
 }
 //#endregion
 //#region src/boot.ts
-/**
-* cli boot：单账号启动序列（2026-08-07 用户拍板：只保留自建宿主）
-*
-* resolveQqFiles（多级来源定位 QQ 原生文件）→ 解析各包 dist 入口 → launchSelfHost
-* （标准 node + stub QQNT.dll 直接 dlopen，不拉起 QQ / 不注入）→ 常驻。
-*
-* QQ 原生文件来源（本机未装 QQ 也能跑，2026-08-16 接入）：
-*   L0 NAPUTO_QQ_FILES 显式文件根 → L1 本机 QQ 安装（--qq-path / NAPUTO_QQ_PATH /
-*      注册表 / 常见路径）→ L2 数据根缓存 <数据根>/qq-files/<版本> → 全部缺失时
-*      自动下载官方安装包（sha256 校验 + 7z 解包 + 提取缓存，幂等）。
-* cached 来源下 qq.qqPath 为语义占位（缓存目录无 QQ.exe）——launchSelfHost 只消费
-* qq.wrapperPath / qq.version（NAPUTO_QQ_PATH 仅注入、self-host 未读取），占位安全。
-*
-* 不写业务逻辑：kernel 装配 + 登录 + 协议装配全部在 self-host.cjs → boot-bootstrap.js 完成。
-* 路线 B（拉起 QQ + 注入）已淘汰（launchQqWithLoader 已移除，cli 只走自建宿主）。
-*/
 /** 解析 workspace 包的 dist 入口（ESM 解析：包是 ESM-only，exports 无 require 条件）。 */
 async function packageEntry(pkg) {
 	const url = await import.meta.resolve(pkg);
@@ -252,417 +598,232 @@ async function packageEntry(pkg) {
 /** QR 透出标记行前缀（loader bootstrap-core 非 IPC 模式输出，cli 解析终端渲染）。 */
 const QR_LINE_PREFIX = "NAPUTO_QR ";
 /** 优雅停等待上限（毫秒）：超时 kill 兜底（Windows 下为硬杀）。 */
-const GRACEFUL_STOP_TIMEOUT_MS = 1e4;
-/**
-* 逐行转发子进程输出到父进程，过滤原生噪音。
-* readline 按 UTF-8 解码 pipe 字节流，再经 process.stdout（TTY 路径，
-* WriteConsoleW UTF-16）输出——顺带修复 pino 中文在 cmd.exe/管道 936 转码
-* 链路下的乱码（原生 printf 字节流无法从 JS 侧改编码，转 pipe 后统一解码）。
-*
-* NAPUTO_QR 标记行（loader bootstrap-core 输出，QR 登录二维码数据）不转发，
-* 解析后用 qrcode 包渲染终端二维码；png 落盘与 URL 提示由 kernel 日志完成。
-* 噪音判定走 loader 共享单一来源（isNativeNoiseLine，与 koishi IPC 路径同源）。
-*/
-function forwardFiltered(input, out) {
-	createInterface({ input }).on("line", (line) => {
-		if (line.startsWith(QR_LINE_PREFIX)) {
-			renderTerminalQr(line.slice(10));
-			return;
-		}
-		if (isNativeNoiseLine(line)) return;
-		out.write(`${line}\n`);
-	});
-}
-/**
-* 渲染终端二维码（qrcode 包 terminal 模式，half-block 字符）。
-* 解析失败/无 url 时静默丢弃——标记行是内部协议，坏行不影响登录。
-*/
-function renderTerminalQr(raw) {
-	try {
-		const { qrcodeUrl } = JSON.parse(raw);
-		if (qrcodeUrl === void 0 || qrcodeUrl === "") return;
-		QRCode.toString(qrcodeUrl, {
-			type: "terminal",
-			small: true
-		}).then((str) => {
-			process.stdout.write(`${str}\n`);
-		}).catch(() => {});
-	} catch {}
-}
-/** 启动单个账号（自建宿主 + 常驻）。 */
-async function runSingleAccount(opts = {}) {
-	const dataRoot = resolveDataRoot(opts.dataDir);
-	let qq;
-	try {
-		qq = await resolveQqFiles({
-			dataRoot,
-			...opts.qqPath !== void 0 ? { qqPath: opts.qqPath } : {}
-		});
-	} catch (err) {
-		logger.error({ err }, `定位/下载 QQ 原生文件失败：${err instanceof Error ? err.message : String(err)}\n（本机未装 QQ 时自动下载官方安装包；若下载失败请检查网络，或手动安装 QQ、设置 NAPUTO_QQ_PATH 指定已有安装、NAPUTO_QQ_FILES 指定文件根、NAPUTO_QQ_URL 覆盖下载地址）`);
-		process.exitCode = 1;
-		return;
-	}
-	const cfgDir = path.join(dataRoot, opts.qq ?? "default");
-	const { occupied, pid: holderPid } = checkInstanceLock(cfgDir);
-	if (occupied) {
-		logger.error({
-			pid: holderPid,
-			dataDir: cfgDir
-		}, "数据目录已被其他实例占用，拒绝启动（同一账号数据目录仅允许一个实例；占用校验已含 pid 复用检测，如仍误报请删除该目录下的 instance.lock）");
-		process.exitCode = 1;
-		return;
-	}
-	const kernelEntry = await packageEntry("@napuketto/kernel");
-	const adapterEntry = await packageEntry("@napuketto/adapter");
-	const networkEntry = await packageEntry("@napuketto/network");
-	const stubDir = opts.stubDir ?? process.env["NAPUTO_STUB_DIR"] ?? defaultStubDir();
-	logger.debug({
-		qqVersion: qq.version,
-		qqPath: qq.qqPath,
-		source: qq.source
-	}, "QQ 文件来源");
-	logger.debug({ dataDir: cfgDir }, "数据目录");
-	logger.debug("自建宿主引导（标准 node + stub QQNT.dll）");
-	const { child } = await launchSelfHost({
-		qq,
-		kernelEntry,
-		adapterEntry,
-		networkEntry,
-		cfgDir,
-		cwd: dataRoot,
-		configPath: resolveConfigPath({ dataRoot }),
-		selfHost: true,
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		],
-		extraEnv: {
-			...effectiveConsoleEnv(resolveCliLogConfig(opts.dataDir)),
-			NAPUTO_DATA_ROOT: dataRoot
-		},
-		...opts.qq !== void 0 ? { quickUin: opts.qq } : {},
-		...stubDir !== void 0 ? { stubDir } : {}
-	});
-	if (child.stdout !== null) forwardFiltered(child.stdout, process.stdout);
-	if (child.stderr !== null) forwardFiltered(child.stderr, process.stderr);
-	writeAccountRuntime(dataRoot, {
-		uin: opts.qq ?? "default",
-		pid: process.pid,
-		...child.pid !== void 0 ? { selfHostPid: child.pid } : {},
-		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		kind: "single-boot",
-		status: "running"
-	});
-	const account = opts.qq ?? "default";
-	let stopArmed = false;
-	const armGracefulStop = (reason) => {
-		if (stopArmed) return;
-		stopArmed = true;
-		logger.info({
-			account,
-			reason
-		}, "收到停止请求，等待自建宿主退出");
-		setTimeout(() => {
-			if (child.exitCode === null && !child.killed) {
-				logger.warn({ account }, "自建宿主未在限时内退出，强制结束");
-				child.kill();
-			}
-		}, GRACEFUL_STOP_TIMEOUT_MS).unref?.();
-	};
-	watchStopSentinel({
-		dataRoot,
-		account,
-		onTrigger: () => armGracefulStop("停止哨兵")
-	});
-	const onSignal = (signal) => {
-		writeStopSentinel(dataRoot, account);
-		armGracefulStop(`信号 ${signal}`);
-	};
-	process.on("SIGINT", () => onSignal("SIGINT"));
-	process.on("SIGTERM", () => onSignal("SIGTERM"));
-	process.on("SIGBREAK", () => onSignal("SIGBREAK"));
-	await new Promise((resolve) => {
-		child.on("exit", (code) => {
-			logger.info({
-				code,
-				graceful: stopArmed
-			}, "自建宿主进程退出");
-			writeAccountRuntime(dataRoot, {
-				uin: opts.qq ?? "default",
-				pid: process.pid,
-				...child.pid !== void 0 ? { selfHostPid: child.pid } : {},
-				startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				kind: "single-boot",
-				status: "exited",
-				exitCode: code
-			});
-			resolve();
-		});
-		child.on("error", (err) => {
-			logger.error({ err }, "自建宿主进程启动失败");
-			resolve();
-		});
-	});
-}
-//#endregion
-//#region src/config-template.ts
-/**
-* 配置模板（TOML 注释版，从 config-cmds.ts 拆分，2026-08-08 FTA 优化）。
-* `config init` 与首次启动（loadCliConfig）缺失时生成。
-*
-* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
-* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
-* dataDir 不再写死（缺省 = 项目根/.napuketto，跨平台），模板保持可移植。
-*/
-/** 保留占位 QQ 号（模板默认值）：必须替换为真实 QQ 号，否则启动校验报错。 */
-const RESERVED_PLACEHOLDER_QINS = ["123456", "654321"];
-function configTemplate() {
-	return `# ============================================================
-# NapukettoQQ 全局配置文件
-# ============================================================
-# 本文件由 \`napuketto config init\` 生成（或首次启动自动生成）。
-# 本机配置不入库（.gitignore）；修改后重启生效。
-#
-# 配置组织：一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在账号内
-# （[accounts.onebot11] / [accounts.satori] / [accounts.kurobot]）。账号没有写
-# 某协议段 = 该账号不启用该协议。账号必填（至少一个，qq 必填）。
-
-# ------------------------------------------------------------
-# 全局配置（跨账号）
-# ------------------------------------------------------------
-
-# 数据根目录：账号目录/日志/缓存/QQ 数据存放位置。
-# 缺省 = <项目根>/.napuketto（部署场景，跨平台，无需修改）。
-# 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录）。
-# dataDir = ".napuketto"
-
-# 多账号（supervisor）模式下，账号进程崩溃是否自动重启
-autoRestart = true
-
-# 崩溃后自动重启的延迟（毫秒）
-restartDelayMs = 2000
-
-# ------------------------------------------------------------
-# 日志（[log]，可选——不配置即用缺省：终端 pretty 多行 / 管道 single-line）
-# ------------------------------------------------------------
-# 嵌入式宿主（把 napuketto 打进服务端等场景）推荐：
-#   [log]
-#   format = "single-line"     # 或 "json"（NDJSON，宿主按 level/module 精确路由）
-#   level = "warn"             # 控制台只留警告以上，细节进文件（配 [log.file]）
-#   banner = false
-#
-# [log]
-# format = "pretty"            # pretty | single-line | json（缺省按 TTY 自动）
-# level = "info"               # trace|debug|info|warn|error|fatal（控制台级别）
-# banner = true                # 启动字符画
-# timestamp = "local"          # local | iso8601 | elapsed
-# unboundReceive = true        # false = 未绑定频道的接收行不打（kurobot 握手后生效）
-# [log.levels]                 # 按模块覆盖级别：cli / kernel / loader / ob11
-# # loader = "debug"           # 例：终端上看接收行（默认已降 debug）
-# # ob11 = "debug"             # 例：协议校准数据（含原始 hex）
-# [log.file]                   # 独立文件 sink（可选；级别可低于控制台）
-# # path = "logs/napuketto-console.log"
-# # level = "debug"
-#
-# 环境变量覆盖（优先级高于本文件）：NAPUKETTO_LOG_LEVEL / NAPUKETTO_LOG_FORMAT /
-# NAPUKETTO_NO_BANNER（兼容旧拼写 NAPKETTO_LOG_LEVEL）。
-
-# ------------------------------------------------------------
-# 账号（至少一个，qq 必填）
-# ------------------------------------------------------------
-
-[[accounts]]
-qq = "${RESERVED_PLACEHOLDER_QINS[0]}"            # 占位值，必须替换为你的 QQ 号，否则启动报错
-enabled = true           # 是否启用（可选，缺省 true）
-
-[accounts.onebot11]      # 该账号的 OneBot 11 配置（无此段 = 不启用 OB11）
-
-# 鉴权 token（全局默认）：HTTP/WS 连接必须携带。
-#   校验方式：Authorization: Bearer <token> / 裸 token / URL 参数 ?access_token=<token>
-#   每个网络实例可单独覆盖（见下文各实例的 token 字段）。
-#   留空 = 不鉴权（仅本机调试推荐）。
-# token = ""
-
-# 心跳 meta 事件间隔（毫秒）；0 = 关闭心跳事件
-heartbeatInterval = 3000
-
-# 是否上报机器人自己发的消息（OB11 规范默认不上报）
-reportSelfMessage = false
-
-# 消息内容格式：array = 消息段数组（标准 OneBot 11），string = CQ 码字符串
-messagePostFormat = "array"
-
-# 群文件报形式：false（默认）= message 事件 + file 段（go-cqhttp 兼容）；
-# true = 群文件消息改报 group_upload notice 事件（替代 message 事件）
-groupUploadAsNotice = false
-
-# ---- HTTP 反向服务器（接收第三方 POST 指令），可配置多个 ----
-[[accounts.onebot11.httpServers]]
-enabled = true
-host = "127.0.0.1"       # 监听地址；0.0.0.0 = 监听所有网卡（局域网可连）
-port = 3000
-# token = "abc"          # 可选：覆盖全局 token
-
-# ---- HTTP 正向上报（Webhook：把事件 POST 到第三方地址），可配置多个 ----
-# [[accounts.onebot11.httpPostUrls]]
-# enabled = true
-# url = "http://127.0.0.1:8080/onebot"   # 第三方接收地址
-# token = "abc"                          # 可选：覆盖全局 token
-# timeoutMs = 5000                       # 可选：上报超时（毫秒），缺省不超时
-
-# ---- WS 反向服务器（外部 WS 客户端主动连入），可配置多个 ----
-[[accounts.onebot11.wsServers]]
-enabled = true
-host = "127.0.0.1"
-port = 3001
-# token = "abc"                          # 可选：覆盖全局 token
-# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
-
-# ---- WS 正向客户端（主动连接外部 WS，双向），可配置多个 ----
-# [[accounts.onebot11.wsReverseUrls]]
-# enabled = true
-# url = "ws://127.0.0.1:8081/ws"         # 第三方 WS 地址（ws:// 或 wss://）
-# token = "abc"                          # 可选：覆盖全局 token
-# reconnectDelayMs = 5000                # 可选：断线重连延迟（毫秒）
-# maxReconnectAttempts = 10              # 可选：最大重连次数（缺省无限）
-# rejectUnauthorized = true              # 可选：wss:// 是否校验证书（自签证书设 false）
-# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
-
-# 第二个账号示例（只开 Satori）：
-# [[accounts]]
-# qq = "${RESERVED_PLACEHOLDER_QINS[1]}"
-# [accounts.satori]
-# # token = ""                           # 可选：Satori 鉴权 token
-# [[accounts.satori.httpServers]]        # HTTP RPC（POST /v1/{resource}.{method}）
-# enabled = true
-# host = "127.0.0.1"
-# port = 5500
-# [[accounts.satori.wsServers]]          # WS 事件服务（/v1/events）
-# enabled = true
-# host = "127.0.0.1"
-# port = 5501
-
-# ------------------------------------------------------------
-# KuroBot 群服互通（kurobridge-ws 客户端，MVP-3）
-# ------------------------------------------------------------
-# 账号内写 [accounts.kurobot] 段即启用；不写 = 不启用。作为 WS 客户端
-# 主动连入 KuroBot 服务端（Minecraft 服务器 kurobot 插件）。
-# QQ 群文字 ↔ 游戏聊天双向互通；群命令（前缀开头）→ 游戏命令。
-# [accounts.kurobot]
-# url = "ws://127.0.0.1:25580"           # 必填：KuroBot 服务端地址（ws:// 或 wss://）
-# # token = ""                           # 可选：鉴权 token（服务端配了则必填，错 token 拒连）
-# # client = "napukettoqq"               # 可选：自报身份（缺省 napukettoqq/<版本>）
-# # commandPrefix = "/"                  # 可选：群命令前缀
-# # pingIntervalMs = 15000               # 可选：应用层心跳间隔（毫秒，须 < 30000）
-# # chatTemplate = "[{player}] {content}"    # 游戏聊天渲染模板
-# # joinTemplate = "{player} 加入了服务器"    # 玩家进服模板
-# # leaveTemplate = "{player} 离开了服务器"   # 玩家退服模板
-# # deathTemplate = "{player} {message}"     # 玩家死亡模板（空消息显示「死亡了」）
-`;
-}
-//#endregion
-//#region src/config-parse.ts
+const GRACEFUL_STOP_TIMEOUT_MS = 1e4;
 /**
-* 主配置类型与手写校验器（从 config-cmds.ts 拆分，2026-08-08 FTA 优化）
+* 逐行转发子进程输出到父进程，过滤原生噪音。
+* readline 按 UTF-8 解码 pipe 字节流，再经 process.stdout（TTY 路径，
+* WriteConsoleW UTF-16）输出——顺带修复 pino 中文在 cmd.exe/管道 936 转码
+* 链路下的乱码（原生 printf 字节流无法从 JS 侧改编码，转 pipe 后统一解码）。
 *
-* 主配置 parse（不引入 zod）：数据根 / 自动重启 / 重启延迟 / 账号列表。
-* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
-* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
-* 协议段为宽松对象，装配时由对应协议包的 zod schema 严格校验。
+* NAPUTO_QR 标记行（loader bootstrap-core 输出，QR 登录二维码数据）不转发，
+* 解析后用 qrcode 包渲染终端二维码；png 落盘与 URL 提示由 kernel 日志完成。
+* 噪音判定走 loader 共享单一来源（isNativeNoiseLine，与 koishi IPC 路径同源）。
 */
-/** 默认自动重启。 */
-const DEFAULT_AUTO_RESTART = true;
-/** 默认重启延迟（毫秒）。 */
-const DEFAULT_RESTART_DELAY_MS$1 = 2e3;
-/** QQ 号格式：纯数字 5-11 位（QQ 号合法范围，勿写死 11 位）。 */
-const QQ_IN_FORMAT_RE = /^\d{5,11}$/;
-/** 解析账号内协议段（宽松对象，装配时由 zod schema 严格校验）。 */
-function parseProtocolSection(raw, key) {
-	const section = raw[key];
-	if (section === void 0) return;
-	if (typeof section !== "object" || section === null) throw kernelError(`主配置账号 ${key} 段必须是对象`, "INVALID_PARAM");
-	return section;
+function forwardFiltered(input, out) {
+	createInterface({ input }).on("line", (line) => {
+		if (line.startsWith(QR_LINE_PREFIX)) {
+			renderTerminalQr(line.slice(10));
+			return;
+		}
+		if (isNativeNoiseLine(line)) return;
+		out.write(`${line}\n`);
+	});
 }
 /**
-* 解析 dataDir（缺省用当前解析的数据根 = 项目根/.napuketto）。
-* 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录），
-* 消费端 resolveDataRoot 统一展开为绝对路径。
+* 渲染终端二维码（qrcode 包 terminal 模式，half-block 字符）。
+* 解析失败/无 url 时静默丢弃——标记行是内部协议，坏行不影响登录。
 */
-function parseDataDir(raw) {
-	if (raw["dataDir"] === void 0) return resolveDataRoot();
-	if (typeof raw["dataDir"] !== "string" || raw["dataDir"] === "") throw kernelError("主配置 dataDir 必须是非空字符串", "INVALID_PARAM");
-	return raw["dataDir"];
+function renderTerminalQr(raw) {
+	try {
+		const { qrcodeUrl } = JSON.parse(raw);
+		if (qrcodeUrl === void 0 || qrcodeUrl === "") return;
+		QRCode.toString(qrcodeUrl, {
+			type: "terminal",
+			small: true
+		}).then((str) => {
+			process.stdout.write(`${str}\n`);
+		}).catch(() => {});
+	} catch {}
 }
-/** 解析 autoRestart。 */
-function parseAutoRestart(raw) {
-	if (raw["autoRestart"] === void 0) return DEFAULT_AUTO_RESTART;
-	if (typeof raw["autoRestart"] !== "boolean") throw kernelError("主配置 autoRestart 必须是布尔值", "INVALID_PARAM");
-	return raw["autoRestart"];
+/** 解析自建宿主装配面的三个包入口（ESM 解析，顺序同旧实现）。 */
+async function resolvePackageEntries() {
+	return {
+		kernelEntry: await packageEntry("@napuketto/kernel"),
+		adapterEntry: await packageEntry("@napuketto/adapter"),
+		networkEntry: await packageEntry("@napuketto/network")
+	};
 }
-/** 解析 restartDelayMs（毫秒）。 */
-function parseRestartDelayMs(raw) {
-	if (raw["restartDelayMs"] === void 0) return DEFAULT_RESTART_DELAY_MS$1;
-	if (typeof raw["restartDelayMs"] !== "number" || !Number.isInteger(raw["restartDelayMs"]) || raw["restartDelayMs"] <= 0) throw kernelError("主配置 restartDelayMs 必须是正整数", "INVALID_PARAM");
-	return raw["restartDelayMs"];
+/** stub QQNT.dll 目录（--stub-dir > NAPUTO_STUB_DIR > loader 包内闭源 submodule 默认）。 */
+function resolveStubDir(opts) {
+	return opts.stubDir ?? process.env["NAPUTO_STUB_DIR"] ?? defaultStubDir();
 }
-/** 解析 accounts（必须至少一个账号，qq 必填）。 */
-function parseAccounts(raw) {
-	if (raw["accounts"] === void 0) throw kernelError("主配置缺少 accounts（必须至少一个账号）；首次启动已生成模板，请编辑后重试", "INVALID_PARAM");
-	if (!Array.isArray(raw["accounts"]) || raw["accounts"].length === 0) throw kernelError("主配置 accounts 必须是非空数组（至少一个 QQ 账号）；首次启动已生成模板，请编辑后重试", "INVALID_PARAM");
-	const accounts = [];
-	for (const item of raw["accounts"]) accounts.push(parseAccount(item));
-	return accounts;
+/** 错误文案提取（Error 用 message，其余字符串化——保留旧日志文案语义）。 */
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
 }
-/** 解析单个账号项（qq 必填；协议段缺省 = 不启用）。 */
-function parseAccount(item) {
-	if (typeof item !== "object" || item === null) throw kernelError("主配置 accounts 元素必须是对象", "INVALID_PARAM");
-	const { qq, enabled } = item;
-	if (typeof qq !== "string" || qq === "") throw kernelError("主配置账号缺少非空 qq", "INVALID_PARAM");
-	if (!QQ_IN_FORMAT_RE.test(qq)) throw kernelError("主配置账号 qq 必须是 5-11 位纯数字 QQ 号", "INVALID_PARAM");
-	if (RESERVED_PLACEHOLDER_QINS.some((placeholder) => placeholder === qq)) throw kernelError(`主配置账号 qq "${qq}" 是模板占位值，请编辑配置文件填入真实 QQ 号后再启动`, "INVALID_PARAM");
-	const out = { qq };
-	if (enabled !== void 0) {
-		if (typeof enabled !== "boolean") throw kernelError("主配置账号 enabled 必须是布尔值", "INVALID_PARAM");
-		out.enabled = enabled;
+/** QQ 原生文件多级来源 + 自动下载（本机未装 QQ 时走下载管线）。
+* 失败记录可操作提示并置 exitCode 1，返回 undefined（调用方提前返回）。 */
+async function locateQqFiles(dataRoot, opts) {
+	try {
+		return await resolveQqFiles({
+			dataRoot,
+			...opts.qqPath !== void 0 ? { qqPath: opts.qqPath } : {}
+		});
+	} catch (err) {
+		logger.error({ err }, `定位/下载 QQ 原生文件失败：${errorMessage(err)}\n（本机未装 QQ 时自动下载官方安装包；若下载失败请检查网络，或手动安装 QQ、设置 NAPUTO_QQ_PATH 指定已有安装、NAPUTO_QQ_FILES 指定文件根、NAPUTO_QQ_URL 覆盖下载地址）`);
+		process.exitCode = 1;
+		return;
 	}
-	const raw = item;
-	const onebot11 = parseProtocolSection(raw, "onebot11");
-	if (onebot11 !== void 0) out.onebot11 = onebot11;
-	const satori = parseProtocolSection(raw, "satori");
-	if (satori !== void 0) out.satori = satori;
-	const kurobot = parseProtocolSection(raw, "kurobot");
-	if (kurobot !== void 0) out.kurobot = kurobot;
-	return out;
 }
 /**
-* [log] 段落库净化：format 为 undefined（= 按 TTY 自动）时剔除该键，
-* 避免 toml 回写（config list/apply 的 stringifyToml）遇到 undefined 值。
+* 单实例锁预检（2026-08-07 根治「多实例抢数据目录锁挂起」）：同一账号数据
+* 目录只允许一个实例（QQ 原生层 MMKV/登录单例有锁，第二个实例抢不到锁会卡死）。
+* 占用 → 快速失败并提示占用 PID；残留（PID 已死 / PID 被复用，2026-09-10
+* cmdline 校验根治）→ self-host 会自动接管。真正的锁由 self-host 子进程
+* 获取/释放（它才是数据目录的实际持有者），cli 这里只做 spawn 前预检，
+* 给用户友好提示（supervisor 等批量拉起同用）。
+* @returns 可用 true；占用时记录错误并置 exitCode 1 返回 false
 */
-function stripUndefinedFormat(log) {
-	const { format, ...rest } = log;
-	return format === void 0 ? rest : {
-		...rest,
-		format
-	};
+function ensureInstanceLockFree(cfgDir) {
+	const { occupied, pid: holderPid } = checkInstanceLock(cfgDir);
+	if (!occupied) return true;
+	logger.error({
+		pid: holderPid,
+		dataDir: cfgDir
+	}, "数据目录已被其他实例占用，拒绝启动（同一账号数据目录仅允许一个实例；占用校验已含 pid 复用检测，如仍误报请删除该目录下的 instance.lock）");
+	process.exitCode = 1;
+	return false;
 }
-/** 手写校验器：主配置 parse（不引入 zod）。 */
-function parseCliConfig(input) {
-	if (typeof input !== "object" || input === null) throw kernelError("主配置必须是对象", "INVALID_PARAM");
-	const raw = input;
-	const dataDir = parseDataDir(raw);
-	const autoRestart = parseAutoRestart(raw);
-	const restartDelayMs = parseRestartDelayMs(raw);
-	const accounts = parseAccounts(raw);
-	const log = raw["log"] !== void 0 ? stripUndefinedFormat(parseLogConfig(raw["log"])) : void 0;
+/** 启动信息走结构化日志（时间戳 + 级别 + pid + 元数据，与 kernel 子进程格式一致）。
+* 2026-10-25 级别重分配：引导细节降 debug（banner 之外的定位/路径细节对运行
+* 状态无信息量），致命错误与登录/退出生命周期保持 info 及以上。 */
+function logBootInfo(qq, cfgDir) {
+	logger.debug({
+		qqVersion: qq.version,
+		qqPath: qq.qqPath,
+		source: qq.source
+	}, "QQ 文件来源");
+	logger.debug({ dataDir: cfgDir }, "数据目录");
+	logger.debug("自建宿主引导（标准 node + stub QQNT.dll）");
+}
+/** launchSelfHost 调用参数构造（唯一启动路径：自建宿主，2026-08-07 用户拍板）。
+* configPath：全局配置文件（项目根 napuketto.toml），注入 NAPKETTO_CONFIG 供装配链读取；
+*   内联配置生效（NAPKETTO_CONFIG_JSON）时不解析、不注入——子进程经 env 继承
+*   内联文本，装配链按同一优先级读取；避免项目根探测出无关路径注入孙进程。
+* extraEnv：传播有效控制台渲染决策（子进程 stdout 恒 pipe，TTY 判定失真）+
+*   数据根（NAPUTO_DATA_ROOT，self-host 停止哨兵目录）。
+* cwd：子进程 cwd 指向数据根——QQ 原生层 fallback 落盘（guild1.db 等）落在专门
+*   的数据目录，不污染项目根（实测 08-07）。 */
+function buildLaunchOptions(ctx) {
+	const { opts, qq, cfgDir, dataRoot, entries, stubDir } = ctx;
 	return {
-		dataDir,
-		autoRestart,
-		restartDelayMs,
-		accounts,
-		...log !== void 0 ? { log } : {}
+		qq,
+		kernelEntry: entries.kernelEntry,
+		adapterEntry: entries.adapterEntry,
+		networkEntry: entries.networkEntry,
+		cfgDir,
+		cwd: dataRoot,
+		...isInlineConfigActive() ? {} : { configPath: resolveConfigPath({ dataRoot }) },
+		selfHost: true,
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
+		extraEnv: {
+			...effectiveConsoleEnv(resolveCliLogConfig(opts.dataDir)),
+			NAPUTO_DATA_ROOT: dataRoot
+		},
+		...opts.qq !== void 0 ? { quickUin: opts.qq } : {},
+		stubDir
+	};
+}
+/** 启动自建宿主子进程（包入口解析 → stub 目录 → 启动信息 → launchSelfHost）。
+* ⚠️ P2（2026-08-12）：launchSelfHost 变 async（linux 场景需下载 win-node）。 */
+async function startSelfHost(opts, qq, cfgDir, dataRoot) {
+	const entries = await resolvePackageEntries();
+	const stubDir = resolveStubDir(opts);
+	logBootInfo(qq, cfgDir);
+	return await launchSelfHost(buildLaunchOptions({
+		opts,
+		qq,
+		cfgDir,
+		dataRoot,
+		entries,
+		stubDir
+	}));
+}
+/** 接管子进程 stdout/stderr：过滤 MMKV / 符号查找失败等原生噪音，其余转发。 */
+function forwardChildOutput(child) {
+	if (child.stdout !== null) forwardFiltered(child.stdout, process.stdout);
+	if (child.stderr !== null) forwardFiltered(child.stderr, process.stderr);
+}
+/** 单账号运行时状态落盘（napuketto status/stop 消费，2026-09-08 T8；
+* pid 记 boot 进程——树杀连带 self-host 孙进程）。 */
+function recordRuntimeState(dataRoot, account, child, status, exitCode) {
+	writeAccountRuntime(dataRoot, {
+		uin: account,
+		pid: process.pid,
+		...child.pid !== void 0 ? { selfHostPid: child.pid } : {},
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		kind: "single-boot",
+		status,
+		...exitCode !== void 0 ? { exitCode } : {}
+	});
+}
+/** 优雅关停编排（2026-10-25 生命周期契约）：触发后等 self-host 经自身哨兵/信号
+* 处理自行退出（exit 0），10s 未退则 kill 兜底（Windows 下为硬杀）——
+* boot 进程随后随 child 退出自然返回（退出码 0 = 请求式正常退出）。
+* @returns 「是否已收到停止请求」查询（退出日志 graceful 标注） */
+function installGracefulStop(child, dataRoot, account) {
+	let stopArmed = false;
+	const killIfHung = () => {
+		if (child.exitCode !== null || child.killed) return;
+		logger.warn({ account }, "自建宿主未在限时内退出，强制结束");
+		child.kill();
+	};
+	const armGracefulStop = (reason) => {
+		if (stopArmed) return;
+		stopArmed = true;
+		logger.info({
+			account,
+			reason
+		}, "收到停止请求，等待自建宿主退出");
+		setTimeout(killIfHung, GRACEFUL_STOP_TIMEOUT_MS).unref?.();
+	};
+	watchStopSentinel({
+		dataRoot,
+		account,
+		onTrigger: () => armGracefulStop("停止哨兵")
+	});
+	const onSignal = (signal) => {
+		writeStopSentinel(dataRoot, account);
+		armGracefulStop(`信号 ${signal}`);
 	};
+	process.on("SIGINT", () => onSignal("SIGINT"));
+	process.on("SIGTERM", () => onSignal("SIGTERM"));
+	process.on("SIGBREAK", () => onSignal("SIGBREAK"));
+	return () => stopArmed;
+}
+/** 常驻：等待自建宿主进程退出（exit / error 两路径均 resolve，去留由 self-host 决定）。 */
+async function waitSelfHostExit(child, dataRoot, account, isStopping) {
+	await new Promise((resolve) => {
+		child.on("exit", (code) => {
+			logger.info({
+				code,
+				graceful: isStopping()
+			}, "自建宿主进程退出");
+			recordRuntimeState(dataRoot, account, child, "exited", code);
+			resolve();
+		});
+		child.on("error", (err) => {
+			logger.error({ err }, "自建宿主进程启动失败");
+			resolve();
+		});
+	});
+}
+/** 启动单个账号（自建宿主 + 常驻）。 */
+async function runSingleAccount(opts = {}) {
+	const dataRoot = resolveDataRoot(opts.dataDir);
+	const qq = await locateQqFiles(dataRoot, opts);
+	if (qq === void 0) return;
+	const account = opts.qq ?? "default";
+	const cfgDir = path.join(dataRoot, account);
+	if (!ensureInstanceLockFree(cfgDir)) return;
+	const { child } = await startSelfHost(opts, qq, cfgDir, dataRoot);
+	forwardChildOutput(child);
+	recordRuntimeState(dataRoot, account, child, "running");
+	await waitSelfHostExit(child, dataRoot, account, installGracefulStop(child, dataRoot, account));
 }
 //#endregion
 //#region src/config-cmds.ts
@@ -696,12 +857,41 @@ var CliConfigStore = class extends ConfigBase {
 		});
 	}
 };
-/** 读取主配置（缺失自动落模板）。 */
+/** 读取主配置（缺失自动落模板；loadCliConfigWithSource 文件分支内部用）。 */
 async function loadCliConfig(dataRoot) {
 	const store = new CliConfigStore(dataRoot);
 	await ensureConfigTemplate(store.path);
 	return await store.load();
 }
+/** 「配置来源」日志每进程至多一行（autoStart 与 runSupervisor 各加载一次）。 */
+let sourceLogged = false;
+/**
+* 加载主配置（内联优先，2026-10-25 嵌入式契约）：
+* NAPKETTO_CONFIG_JSON 非空 → 内存文档校验（不读 / 不写 / 不校验任何 toml
+* 文件），打一行来源日志；否则现行文件链路（缺失自动落模板）。校验失败两形态
+* 同为 ConfigError（exit 78），文案区别只在来源标注。
+*/
+async function loadCliConfigWithSource(opts = {}) {
+	const inlineText = readInlineConfigText();
+	if (inlineText !== void 0) {
+		const config = parseInlineConfig(inlineText);
+		if (!sourceLogged) {
+			sourceLogged = true;
+			logger.info("配置来源: inline（NAPKETTO_CONFIG_JSON）");
+		}
+		return {
+			config,
+			source: "inline"
+		};
+	}
+	const dataRoot = resolveDataRoot(opts.dataDir);
+	const configPath = resolveConfigPath({ dataRoot });
+	return {
+		config: await loadCliConfig(dataRoot),
+		source: "file",
+		path: configPath
+	};
+}
 /** CliConfig → 普通对象（smol-toml stringify 入参）。 */
 function toRecord(config) {
 	return config;
@@ -794,6 +984,59 @@ async function cmdConfigApply(file, opts) {
 	logger.info({ path: store.path }, "全局配置已更新");
 	process.stdout.write(`${stringifyToml(toRecord(next))}\n`);
 }
+/** 读取配置文件文本（validate 纯只读：ENOENT 不落模板，按「配置缺失」报 ConfigError）。 */
+async function readConfigTextForValidate(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") throw configError(`配置文件不存在: ${path}`);
+		throw configError(`读取配置文件失败: ${path}`, { cause: err });
+	}
+}
+/**
+* 校验配置文件（与运行时同构：ConfigBase.parseText 反序列化 + 校验，报错文案
+* 含路径且与 loadCliConfig 主路径逐字一致；格式按扩展名推断，同 ConfigBase）。
+*/
+async function validateConfigFile(path, dataRoot) {
+	const raw = await readConfigTextForValidate(path);
+	new ConfigBase({
+		path,
+		schema: { parse: parseCliConfig },
+		defaults: defaultCliConfig(dataRoot)
+	}).parseText(raw);
+}
+/**
+* config validate：校验配置（exit 0 = 合法；exit 78 = 校验失败，ConfigError 一族；
+* --config 与 --config-json 同给 = 用法错误，exit 1）。纯只读——文件形态不落模板
+* （无参形态文件缺失按配置缺失报 78），不触碰数据目录。
+*/
+async function cmdConfigValidate(opts) {
+	const { configPath, configJson } = opts;
+	if (configPath !== void 0 && configJson !== void 0) throw kernelError("config validate：--config 与 --config-json 只能二选一", "INVALID_PARAM");
+	const dataRoot = resolveDataRoot(opts.dataDir);
+	if (configJson !== void 0) {
+		parseInlineConfig(configJson);
+		return { source: "inline" };
+	}
+	if (configPath !== void 0) {
+		await validateConfigFile(configPath, dataRoot);
+		return {
+			source: "file",
+			path: configPath
+		};
+	}
+	const inlineText = readInlineConfigText();
+	if (inlineText !== void 0) {
+		parseInlineConfig(inlineText);
+		return { source: "inline" };
+	}
+	const path = resolveConfigPath({ dataRoot });
+	await validateConfigFile(path, dataRoot);
+	return {
+		source: "file",
+		path
+	};
+}
 //#endregion
 //#region src/ops-commands.ts
 /**
@@ -1014,6 +1257,22 @@ function startAccount(ctx, acct) {
 			code,
 			signal: signal ?? "none"
 		}, "账号退出");
+		if (code === EXIT_CONFIG_INVALID) {
+			logger.error({
+				qq: acct.qq,
+				code
+			}, "账号因配置校验失败退出（78），不自动重启");
+			writeAccountRuntime(ctx.dataRoot, {
+				uin: acct.qq,
+				pid: child.pid ?? 0,
+				startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				kind: "supervisor-child",
+				status: "exited",
+				exitCode: code,
+				restartCount
+			});
+			return;
+		}
 		if (!ctx.isStopping() && ctx.autoRestart) {
 			ctx.restartCounts.set(acct.qq, restartCount + 1);
 			setTimeout(() => {
@@ -1064,7 +1323,7 @@ function stopAll(ctx) {
 /** 运行 supervisor（多账号编排）。 */
 async function runSupervisor(opts = {}) {
 	const dataRoot = resolveDataRoot(opts.dataDir);
-	const config = await loadCliConfig(dataRoot);
+	const { config } = await loadCliConfigWithSource(opts.dataDir !== void 0 ? { dataDir: opts.dataDir } : {});
 	const accounts = resolveAccounts(opts, config);
 	if (accounts.length === 0) {
 		logger.warn("supervisor：没有启用的账号（主配置 accounts 为空或全部禁用）");
@@ -1118,7 +1377,9 @@ async function runSupervisor(opts = {}) {
 *   - 单账号：-q <uin> → runSingleAccount（自建宿主：标准 node + stub QQNT.dll，不拉起 QQ）
 *   - 多账号：-q A -q B 或 supervisor 子命令 → runSupervisor（子进程编排）
 *   - 无 -q：读全局配置 accounts（至少一个，账号必填）→ supervisor 拉起全部启用账号
-*   - config 子命令：init / list / apply（主配置管理）
+*   - config 子命令：init / list / apply / validate（主配置管理）
+*   - 退出码契约（2026-10-25）：0 = 请求式优雅关停；78 = 配置校验失败（ConfigError
+*     一族，宿主消费，免重启）；其余错误 = 1（handleActionError 统一出口）
 *
 * 路线 B（拉起 QQ + 注入）已淘汰（2026-08-07 用户拍板），相关入口已移除。
 */
@@ -1136,20 +1397,21 @@ const BANNER = [
 	"/_/ |_/\\__,_/ .___/\\__,_/_/|_|\\___/\\__/\\__/\\____/\\___\\_\\___\\_\\ ",
 	"           /_/                                                 "
 ].join("\n");
-/** 统一错误输出（结构化日志，错误对象经 pino serializer 带堆栈）。 */
-function reportError(err) {
-	let message = String(err);
-	if (err instanceof Error) {
-		const { message: errMessage } = err;
-		message = errMessage;
-	}
-	logger.error({ err }, message);
-}
 /** 构造可选 dataDir 参数（exactOptionalPropertyTypes 不允许显式 undefined）。 */
 function withDataDir(dataDir) {
 	if (dataDir === void 0) return {};
 	return { dataDir };
 }
+/** 构造可选 stubDir 参数（同 withDataDir）。 */
+function withStubDir(stubDir) {
+	if (stubDir === void 0) return {};
+	return { stubDir };
+}
+/** 构造可选 qqPath 参数（同 withDataDir）。 */
+function withQqPath(qqPath) {
+	if (qqPath === void 0) return {};
+	return { qqPath };
+}
 /** 读主命令已解析的 data-dir（-d 定义在主命令，子命令经此共享）。 */
 function rootDataDir(program) {
 	return withDataDir(program.opts().dataDir);
@@ -1161,24 +1423,33 @@ function registerConfigCommands(program) {
 		try {
 			await cmdConfigInit(rootDataDir(program));
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
 	});
 	configCmd.command("list").description("列出全局配置与账号配置").action(async () => {
 		try {
 			await cmdConfigList(rootDataDir(program));
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
 	});
 	configCmd.command("apply <file>").description("应用外部配置（TOML/JSON，校验后写回全局配置）").action(async (file) => {
 		try {
 			await cmdConfigApply(file, rootDataDir(program));
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
+		}
+	});
+	configCmd.command("validate").description("校验配置（--config <path> / --config-json <json> 二选一；无参 = 校验生效配置）").option("--config <path>", "待校验配置文件路径（.toml/.json 按扩展名解析）").option("--config-json <json>", "待校验内联配置 JSON 文本").action(async (opts) => {
+		try {
+			const result = await cmdConfigValidate({
+				configPath: opts.config,
+				configJson: opts.configJson,
+				...rootDataDir(program)
+			});
+			process.stdout.write(result.source === "inline" ? "配置校验通过（来源: inline）\n" : `配置校验通过（来源: file ${result.path}）\n`);
+		} catch (err) {
+			handleActionError(err);
 		}
 	});
 }
@@ -1188,76 +1459,72 @@ function registerSupervisorCommand(program) {
 		try {
 			await runSupervisor(rootDataDir(program));
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
 	});
 }
-/** 注册运维子命令（status/stop/restart，2026-09-08 T8；-d 复用主命令 option）。 */
-function registerOpsCommands(program) {
-	program.command("status").description("查看各账号运行状态（读 runtime.json + 进程存活检测）").option("-q, --qq <uin>", "只看指定账号").action(async (opts) => {
-		try {
-			cmdStatus(resolveDataRoot(rootDataDir(program).dataDir), { ...opts.qq !== void 0 ? { qq: opts.qq } : {} });
-		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
-		}
-	});
-	program.command("stop").description("停止账号进程树（无 -q 停 supervisor 全部；-q 停单账号，supervisor 守护时会自动拉起）").option("-q, --qq <uin>", "目标账号（缺省停 supervisor + 全部账号）").action(async (opts) => {
-		try {
-			await cmdStop(resolveDataRoot(rootDataDir(program).dataDir), { ...opts.qq !== void 0 ? { qq: opts.qq } : {} });
-		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
-		}
-	});
-	program.command("restart").description("重启账号（无 -q 重启 supervisor 全量；-q 重启单账号；detached 拉起）").option("-q, --qq <uin>", "目标账号（缺省重启 supervisor 全量）").action(async (opts) => {
+/** 运维子命令公共壳：解析数据根 + 可选 -q 参数，统一 handleActionError 出口。 */
+function opsAction(program, run) {
+	return async (opts) => {
 		try {
-			await cmdRestart(resolveDataRoot(rootDataDir(program).dataDir), { ...opts.qq !== void 0 ? { qq: opts.qq } : {} });
+			await run(resolveDataRoot(rootDataDir(program).dataDir), opts.qq !== void 0 ? { qq: opts.qq } : {});
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
-	});
+	};
+}
+/** 注册运维子命令（status/stop/restart，2026-09-08 T8；-q 复用主命令 option）。 */
+function registerOpsCommands(program) {
+	program.command("status").description("查看各账号运行状态（读 runtime.json + 进程存活检测）").option("-q, --qq <uin>", "只看指定账号").action(opsAction(program, (dataRoot, arg) => cmdStatus(dataRoot, arg)));
+	program.command("stop").description("停止账号进程树（无 -q 停 supervisor 全部；-q 停单账号，supervisor 守护时会自动拉起）").option("-q, --qq <uin>", "目标账号（缺省停 supervisor + 全部账号）").action(opsAction(program, (dataRoot, arg) => cmdStop(dataRoot, arg)));
+	program.command("restart").description("重启账号（无 -q 重启 supervisor 全量；-q 重启单账号；detached 拉起）").option("-q, --qq <uin>", "目标账号（缺省重启 supervisor 全量）").action(opsAction(program, (dataRoot, arg) => cmdRestart(dataRoot, arg)));
 }
 /** 单账号启动分支（-q 单值；构造 bootOptions 后走 runSingleAccount）。 */
 async function runSingleAccountBranch(opts, qqs) {
 	const [only] = qqs;
 	if (only === void 0) return;
-	const bootOptions = { qq: only };
-	if (opts.dataDir !== void 0) bootOptions.dataDir = opts.dataDir;
-	if (opts.qqPath !== void 0) bootOptions.qqPath = opts.qqPath;
-	if (opts.stubDir !== void 0) bootOptions.stubDir = opts.stubDir;
-	await runSingleAccount(bootOptions);
+	await runSingleAccount({
+		qq: only,
+		...withDataDir(opts.dataDir),
+		...withQqPath(opts.qqPath),
+		...withStubDir(opts.stubDir)
+	});
 }
 /** 无 -q 时：读全局配置 accounts（账号必填，2026-08-08 拍板），supervisor 拉起全部启用账号。
-* 不再有「配置为空 → 交互式单账号登录」老路径：缺账号直接报错提示编辑模板。 */
+* 不再有「配置为空 → 交互式单账号登录」老路径：缺账号直接报错提示编辑模板。
+* 配置加载内联优先（NAPKETTO_CONFIG_JSON > 文件）；校验失败 ConfigError → exit 78。 */
 async function autoStart(opts) {
-	if ((await loadCliConfig(resolveDataRoot(opts.dataDir))).accounts.length === 0) throw new Error("主配置没有账号，请编辑 napuketto.toml 填写 [[accounts]] 段");
+	const { config } = await loadCliConfigWithSource(withDataDir(opts.dataDir));
+	if (config.accounts.length === 0) throw new Error("主配置没有账号，请编辑 napuketto.toml 填写 [[accounts]] 段");
 	await runSupervisor({
-		...opts.dataDir !== void 0 ? { dataDir: opts.dataDir } : {},
-		...opts.stubDir !== void 0 ? { stubDir: opts.stubDir } : {}
+		...withDataDir(opts.dataDir),
+		...withStubDir(opts.stubDir)
+	});
+}
+/** 主命令分发：无 -q 读配置 supervisor 拉起 / 单 -q 单账号 / 多 -q supervisor。 */
+async function dispatchMainAction(opts) {
+	const qqs = opts.qq ?? [];
+	if (qqs.length === 0) {
+		await autoStart(opts);
+		return;
+	}
+	if (qqs.length === 1) {
+		await runSingleAccountBranch(opts, qqs);
+		return;
+	}
+	await runSupervisor({
+		qqs,
+		...withDataDir(opts.dataDir),
+		...withStubDir(opts.stubDir)
 	});
 }
 /** 注册主命令 action（-q 单账号 / 多 -q supervisor / 无 -q 读配置 supervisor 拉起）。 */
 function registerMainAction(program) {
 	program.action(async (opts) => {
 		try {
-			const qqs = opts.qq ?? [];
-			if (qqs.length === 0) {
-				await autoStart(opts);
-				return;
-			}
-			if (qqs.length === 1) await runSingleAccountBranch(opts, qqs);
-			else {
-				const supOpts = { qqs };
-				if (opts.dataDir !== void 0) supOpts.dataDir = opts.dataDir;
-				if (opts.stubDir !== void 0) supOpts.stubDir = opts.stubDir;
-				await runSupervisor(supOpts);
-			}
+			await dispatchMainAction(opts);
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
 	});
 }