@napuketto/cli 0.1.27 → 0.3.0

package/dist/index.mjs

@@ -1,307 +1,15 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { ConfigBase, createLogger, kernelError, 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 path, { dirname, extname, join } from "node:path";
+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, resolveQqFiles } from "@napuketto/loader";
+import { checkInstanceLock, defaultStubDir, isNativeNoiseLine, launchSelfHost, removeStopSentinel, resolveQqFiles, watchStopSentinel, writeStopSentinel } from "@napuketto/loader";
 import QRCode from "qrcode";
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { access, readFile, writeFile } from "node:fs/promises";
-//#region src/logger.ts
-/**
-* cli 进程级 logger（ADR-007 日志规范，2026-08-07 统一改造）。
-*
-* 复用 kernel `createLogger`（console pretty + redact，格式与 kernel 子进程完全一致：
-* `[时间] LEVEL (name/pid): 消息` + 缩进元数据）。只打 console 不写文件——文件日志由
-* kernel 装配（NapukettoCore.create → `<数据根>/logs/napuketto.log`）负责。
-*
-* 无全局单例（ADR-015 推论）：cli 每进程一份，模块级单例即可；`base.name` 用 pino
-* 保留字段 name（logger name）标注来源——pino-pretty 自动渲染为 `(cli/pid)` 元数据头，
-* 不占额外属性行，文件/JSON 侧仍保留 name 字段可过滤。
-*
-* 级别：`NAPKETTO_LOG_LEVEL` 环境变量可覆盖（缺省 info，非法值忽略）。
-*/
-/** 合法级别集合（pino 标准级别）。 */
-const LOG_LEVELS = [
-	"trace",
-	"debug",
-	"info",
-	"warn",
-	"error",
-	"fatal",
-	"silent"
-];
-/** 解析日志级别（env 覆盖，非法/缺失回退 info）。 */
-function resolveLevel() {
-	const raw = process.env["NAPKETTO_LOG_LEVEL"];
-	if (raw !== void 0 && LOG_LEVELS.includes(raw)) return raw;
-	return "info";
-}
-/** cli 进程日志（name 渲染为 (cli/pid) 元数据头，文件 JSON 保留 name 字段可过滤）。 */
-const logger = createLogger({
-	level: resolveLevel(),
-	console: true,
-	base: { service: "cli" }
-});
-//#endregion
-//#region src/runtime-state.ts
-/**
-* runtime-state.ts：账号运行时状态文件 + 进程控制原语（2026-09-08 T8）。
-*
-* 跨进程通信选型（决策记录）：现有 IPC 为 stdio JSON 行协议（NAPUTO_IPC=1，
-* koishi 插件专用），supervisor 子进程不在此模式；引入独立通道（socket/pipe）
-* 复杂度高。采用 **PID 状态文件**：supervisor/单账号 boot 启动时把进程信息写
-* `<数据根>/<uin>/runtime.json`，supervisor 自身写 `<数据根>/supervisor.json`；
-* `napuketto status/stop/restart` 读文件 + liveness 检测 + 树杀（win32
-* taskkill /T /F，杀 boot 进程树连带 self-host 孙进程）+ detached 重启。
-*/
-/** runtime.json 文件名。 */
-const RUNTIME_FILE = "runtime.json";
-/** supervisor.json 文件名。 */
-const SUPERVISOR_FILE = "supervisor.json";
-/** 账号状态文件路径。 */
-function runtimeStatePath(dataRoot, uin) {
-	return join(dataRoot, uin, RUNTIME_FILE);
-}
-/** supervisor 状态文件路径。 */
-function supervisorStatePath(dataRoot) {
-	return join(dataRoot, SUPERVISOR_FILE);
-}
-/** 写账号运行时状态（原子覆盖）。 */
-function writeAccountRuntime(dataRoot, state) {
-	const path = runtimeStatePath(dataRoot, state.uin);
-	mkdirSync(join(path, ".."), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
-}
-/** 读账号运行时状态（缺失/损坏返回 null）。 */
-function readAccountRuntime(dataRoot, uin) {
-	return readJson(runtimeStatePath(dataRoot, uin));
-}
-/** 写 supervisor 运行时状态。 */
-function writeSupervisorRuntime(dataRoot, state) {
-	writeFileSync(supervisorStatePath(dataRoot), `${JSON.stringify(state, null, 2)}\n`, "utf8");
-}
-/** 读 supervisor 运行时状态（缺失返回 null）。 */
-function readSupervisorRuntime(dataRoot) {
-	return readJson(supervisorStatePath(dataRoot));
-}
-/** 读 JSON 文件（缺失/解析失败返回 null）。 */
-function readJson(path) {
-	try {
-		return JSON.parse(readFileSync(path, "utf8"));
-	} catch {
-		return null;
-	}
-}
-/** 列出数据根下全部账号运行时状态（扫一级目录 runtime.json）。 */
-function listAccountRuntimes(dataRoot) {
-	let entries = [];
-	try {
-		entries = readdirSync(dataRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
-	} catch {
-		return [];
-	}
-	const out = [];
-	for (const uin of entries) {
-		const state = readAccountRuntime(dataRoot, uin);
-		if (state !== null) out.push(state);
-	}
-	return out;
-}
-/** pid 存活检测（signal 0；EPERM 视为存活——进程存在但无权限）。 */
-function isPidAlive(pid) {
-	if (!Number.isInteger(pid) || pid <= 0) return false;
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (err) {
-		return err.code === "EPERM";
-	}
-}
-/** 树杀命令构造（win32：taskkill /T /F 连孙进程；posix：kill 信号）。 */
-function killProcessTree(pid) {
-	if (process.platform === "win32") {
-		spawn("taskkill", [
-			"/PID",
-			String(pid),
-			"/T",
-			"/F"
-		], { stdio: "ignore" });
-		return;
-	}
-	try {
-		process.kill(pid, "SIGTERM");
-	} catch {}
-}
-/** detached 拉起 node 进程（restart 用；立即返回不等待）。 */
-function spawnDetached(args, cwd) {
-	const child = spawn(process.execPath, args, {
-		detached: true,
-		stdio: "ignore",
-		...cwd !== void 0 ? { cwd } : {}
-	});
-	child.unref();
-	return child;
-}
-/** 聚合各账号状态（liveness 修正：文件 running 但 pid 已死 → not running）。 */
-function aggregateStatus(runtimes, aliveFn = isPidAlive) {
-	return runtimes.map((r) => ({
-		uin: r.uin,
-		pid: r.pid,
-		alive: r.status === "running" ? aliveFn(r.pid) : false,
-		kind: r.kind,
-		startedAt: r.startedAt,
-		restartCount: r.restartCount ?? 0,
-		exitCode: r.exitCode
-	}));
-}
-//#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);
-	return fileURLToPath(url);
-}
-/** QR 透出标记行前缀（loader bootstrap-core 非 IPC 模式输出，cli 解析终端渲染）。 */
-const QR_LINE_PREFIX = "NAPUTO_QR ";
-/**
-* 逐行转发子进程输出到父进程，过滤原生噪音。
-* 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.info({
-		qqVersion: qq.version,
-		qqPath: qq.qqPath,
-		source: qq.source
-	}, "QQ 文件来源");
-	logger.info({ dataDir: cfgDir }, "数据目录");
-	logger.info("自建宿主引导（标准 node + stub QQNT.dll）");
-	const { child } = await launchSelfHost({
-		qq,
-		kernelEntry,
-		adapterEntry,
-		networkEntry,
-		cfgDir,
-		cwd: dataRoot,
-		configPath: resolveConfigPath({ dataRoot }),
-		selfHost: true,
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		],
-		...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"
-	});
-	await new Promise((resolve) => {
-		child.on("exit", (code) => {
-			logger.info({ code }, "自建宿主进程退出");
-			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 优化）。
@@ -339,6 +47,31 @@ 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 必填）
 # ------------------------------------------------------------
@@ -433,89 +166,664 @@ port = 3001
 `;
 }
 //#endregion
-//#region src/config-parse.ts
+//#region src/config-parse.ts
+/**
+* 主配置类型与手写校验器（从 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 一族，
+* 内联与文件两形态共用本校验器）。
+*/
+/** 默认自动重启。 */
+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;
+}
+/**
+* 解析 dataDir（缺省用当前解析的数据根 = 项目根/.napuketto）。
+* 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录），
+* 消费端 resolveDataRoot 统一展开为绝对路径。
+*/
+function parseDataDir(raw) {
+	if (raw["dataDir"] === void 0) return resolveDataRoot();
+	if (typeof raw["dataDir"] !== "string" || raw["dataDir"] === "") throw configError("主配置 dataDir 必须是非空字符串");
+	return raw["dataDir"];
+}
+/** 解析 autoRestart。 */
+function parseAutoRestart(raw) {
+	if (raw["autoRestart"] === void 0) return DEFAULT_AUTO_RESTART;
+	if (typeof raw["autoRestart"] !== "boolean") throw configError("主配置 autoRestart 必须是布尔值");
+	return raw["autoRestart"];
+}
+/** 解析 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"];
+}
+/** 解析 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) {
+		this.#ensure().warn(obj, msg);
+	}
+	error(obj, msg) {
+		this.#ensure().error(obj, msg);
+	}
+	debug(obj, msg) {
+		this.#ensure().debug(obj, msg);
+	}
+	trace(obj, msg) {
+		this.#ensure().trace(obj, msg);
+	}
+	fatal(obj, msg) {
+		this.#ensure().fatal(obj, msg);
+	}
+};
+/** 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）。
+*
+* 跨进程通信选型（决策记录）：现有 IPC 为 stdio JSON 行协议（NAPUTO_IPC=1，
+* koishi 插件专用），supervisor 子进程不在此模式；引入独立通道（socket/pipe）
+* 复杂度高。采用 **PID 状态文件**：supervisor/单账号 boot 启动时把进程信息写
+* `<数据根>/<uin>/runtime.json`，supervisor 自身写 `<数据根>/supervisor.json`；
+* `napuketto status/stop/restart` 读文件 + liveness 检测 + 树杀（win32
+* taskkill /T /F，杀 boot 进程树连带 self-host 孙进程）+ detached 重启。
+*/
+/** runtime.json 文件名。 */
+const RUNTIME_FILE = "runtime.json";
+/** supervisor.json 文件名。 */
+const SUPERVISOR_FILE = "supervisor.json";
+/** 账号状态文件路径。 */
+function runtimeStatePath(dataRoot, uin) {
+	return join(dataRoot, uin, RUNTIME_FILE);
+}
+/** supervisor 状态文件路径。 */
+function supervisorStatePath(dataRoot) {
+	return join(dataRoot, SUPERVISOR_FILE);
+}
+/** 写账号运行时状态（原子覆盖）。 */
+function writeAccountRuntime(dataRoot, state) {
+	const path = runtimeStatePath(dataRoot, state.uin);
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+/** 读账号运行时状态（缺失/损坏返回 null）。 */
+function readAccountRuntime(dataRoot, uin) {
+	return readJson(runtimeStatePath(dataRoot, uin));
+}
+/** 写 supervisor 运行时状态。 */
+function writeSupervisorRuntime(dataRoot, state) {
+	writeFileSync(supervisorStatePath(dataRoot), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+/** 读 supervisor 运行时状态（缺失返回 null）。 */
+function readSupervisorRuntime(dataRoot) {
+	return readJson(supervisorStatePath(dataRoot));
+}
+/** 读 JSON 文件（缺失/解析失败返回 null）。 */
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** 列出数据根下全部账号运行时状态（扫一级目录 runtime.json）。 */
+function listAccountRuntimes(dataRoot) {
+	let entries = [];
+	try {
+		entries = readdirSync(dataRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const uin of entries) {
+		const state = readAccountRuntime(dataRoot, uin);
+		if (state !== null) out.push(state);
+	}
+	return out;
+}
+/** pid 存活检测（signal 0；EPERM 视为存活——进程存在但无权限）。 */
+function isPidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+}
+/** 树杀命令构造（win32：taskkill /T /F 连孙进程；posix：kill 信号）。 */
+function killProcessTree(pid) {
+	if (process.platform === "win32") {
+		spawn("taskkill", [
+			"/PID",
+			String(pid),
+			"/T",
+			"/F"
+		], { stdio: "ignore" });
+		return;
+	}
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {}
+}
+/** detached 拉起 node 进程（restart 用；立即返回不等待）。 */
+function spawnDetached(args, cwd) {
+	const child = spawn(process.execPath, args, {
+		detached: true,
+		stdio: "ignore",
+		...cwd !== void 0 ? { cwd } : {}
+	});
+	child.unref();
+	return child;
+}
+/** 聚合各账号状态（liveness 修正：文件 running 但 pid 已死 → not running）。 */
+function aggregateStatus(runtimes, aliveFn = isPidAlive) {
+	return runtimes.map((r) => ({
+		uin: r.uin,
+		pid: r.pid,
+		alive: r.status === "running" ? aliveFn(r.pid) : false,
+		kind: r.kind,
+		startedAt: r.startedAt,
+		restartCount: r.restartCount ?? 0,
+		exitCode: r.exitCode
+	}));
+}
+//#endregion
+//#region src/boot.ts
+/** 解析 workspace 包的 dist 入口（ESM 解析：包是 ESM-only，exports 无 require 条件）。 */
+async function packageEntry(pkg) {
+	const url = await import.meta.resolve(pkg);
+	return fileURLToPath(url);
+}
+/** QR 透出标记行前缀（loader bootstrap-core 非 IPC 模式输出，cli 解析终端渲染）。 */
+const QR_LINE_PREFIX = "NAPUTO_QR ";
+/** 优雅停等待上限（毫秒）：超时 kill 兜底（Windows 下为硬杀）。 */
+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;
 }
-/** 手写校验器：主配置 parse（不引入 zod）。 */
-function parseCliConfig(input) {
-	if (typeof input !== "object" || input === null) throw kernelError("主配置必须是对象", "INVALID_PARAM");
-	const raw = input;
+/**
+* 单实例锁预检（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 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;
+}
+/** 启动信息走结构化日志（时间戳 + 级别 + 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: parseDataDir(raw),
-		autoRestart: parseAutoRestart(raw),
-		restartDelayMs: parseRestartDelayMs(raw),
-		accounts: parseAccounts(raw)
+		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
@@ -549,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;
@@ -647,20 +984,86 @@ 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
 /**
 * ops-commands.ts：status / stop / restart 运维命令实现（2026-09-08 T8）。
 *
 * 数据源：runtime-state 状态文件（supervisor/单账号 boot 写入）+ liveness 检测。
-* stop/restart 语义：
-*  - stop -q <uin>：树杀该账号 boot 进程（连带 self-host）。⚠️ supervisor 在跑
-*    且 autoRestart 时账号会被自动拉起——提示用户先 `napuketto stop`（停 supervisor）。
-*  - stop（无 -q）：树杀 supervisor（子进程随 supervisor 的信号转发退出；若
-*    残留按各账号 runtime pid 逐个树杀兜底）。
+* stop/restart 语义（2026-10-25 优雅化）：
+*  - stop -q <uin>：写单账号停止哨兵 → 等该账号进程链优雅退出 → 超时树杀兜底。
+*    ⚠️ supervisor 在跑且 autoRestart 时账号会被自动拉起——提示用户先 `napuketto stop`。
+*  - stop（无 -q）：写 all 哨兵（supervisor + 全部账号优雅退出）→ 超时树杀兜底。
 *  - restart：stop 同目标 + detached 重新拉起（-q → 单账号 boot；无 -q →
 *    supervisor autoStart）。
 */
+/** 优雅停等待上限（毫秒）：哨兵后子进程链自行退出，超时树杀兜底。 */
+const GRACEFUL_STOP_WAIT_MS = 8e3;
+/** 存活轮询间隔（毫秒）。 */
+const LIVENESS_POLL_MS = 200;
+/** 等待 pid 列表全部退出（返回超时仍未退的 pid）。 */
+async function waitForPidsExit(pids) {
+	const deadline = Date.now() + GRACEFUL_STOP_WAIT_MS;
+	let alive = pids.filter((pid) => pid > 0 && isPidAlive(pid));
+	while (alive.length > 0 && Date.now() < deadline) {
+		await new Promise((resolve) => setTimeout(resolve, LIVENESS_POLL_MS));
+		alive = alive.filter((pid) => isPidAlive(pid));
+	}
+	return alive;
+}
 /** status：聚合输出各账号运行状态（含 supervisor 自身）。 */
 function cmdStatus(dataRoot, opts) {
 	const supervisor = readSupervisorRuntime(dataRoot);
@@ -694,7 +1097,31 @@ function stopAccount(runtime) {
 		pid: runtime.pid
 	}, "已发送停止（树杀）");
 }
-/** stop：-q 停单账号；无 -q 停 supervisor + 全部账号兜底。 */
+/** stop：-q 停单账号；无 -q 停 supervisor + 全部账号兜底。
+*
+* 2026-10-25 优雅化：先写停止哨兵（目标账号或 all）→ 等进程链自行有序退出
+* （退出码 0）→ 超时残留树杀兜底 → 清理哨兵。单账号哨兵只命中对应 boot/self-host，
+* 不干扰同数据根的其他账号。
+*/
+/** stop -q：写单账号哨兵 → 等优雅退出 → 超时树杀兜底 → 清哨兵。 */
+async function stopSingleAccount(dataRoot, target) {
+	logger.info({
+		uin: target.uin,
+		pid: target.pid
+	}, "已发送停止请求（哨兵），等待退出");
+	writeStopSentinel(dataRoot, target.uin);
+	const stragglers = await waitForPidsExit([target.pid]);
+	for (const pid of stragglers) {
+		logger.warn({
+			uin: target.uin,
+			pid
+		}, "限时内未退出，树杀兜底");
+		killProcessTree(pid);
+	}
+	removeStopSentinel(dataRoot);
+	const supervisor = readSupervisorRuntime(dataRoot);
+	if (supervisor !== null) logger.warn({ supervisorPid: supervisor.pid }, "supervisor 仍在运行且 autoRestart 开启时会自动拉起该账号；如需彻底停止请执行 napuketto stop（停 supervisor）");
+}
 async function cmdStop(dataRoot, opts) {
 	const runtimes = listAccountRuntimes(dataRoot);
 	if (opts.qq !== void 0) {
@@ -704,17 +1131,23 @@ async function cmdStop(dataRoot, opts) {
 			process.exitCode = 1;
 			return;
 		}
-		stopAccount(target);
-		const supervisor = readSupervisorRuntime(dataRoot);
-		if (supervisor !== null) logger.warn({ supervisorPid: supervisor.pid }, "supervisor 仍在运行且 autoRestart 开启时会自动拉起该账号；如需彻底停止请执行 napuketto stop（停 supervisor）");
+		await stopSingleAccount(dataRoot, target);
 		return;
 	}
 	const supervisor = readSupervisorRuntime(dataRoot);
+	const supervisorPid = supervisor !== null && isPidAlive(supervisor.pid) ? supervisor.pid : 0;
 	if (supervisor !== null) {
-		killProcessTree(supervisor.pid);
-		logger.info({ pid: supervisor.pid }, "已停止 supervisor（树杀，子进程随信号转发退出）");
+		logger.info({ pid: supervisor.pid }, "已发送停止请求（哨兵），等待 supervisor 退出");
+		writeStopSentinel(dataRoot, "all");
+		const alive = await waitForPidsExit([supervisorPid]);
+		for (const pid of alive) {
+			logger.warn({ pid }, "supervisor 限时内未退出，树杀兜底");
+			killProcessTree(pid);
+		}
 	} else logger.warn("supervisor 未运行（无状态文件）");
-	for (const runtime of runtimes) stopAccount(runtime);
+	const stragglers = await waitForPidsExit(runtimes.map((r) => r.pid));
+	for (const runtime of runtimes) if (stragglers.includes(runtime.pid)) stopAccount(runtime);
+	removeStopSentinel(dataRoot);
 }
 /** restart：stop 同目标 + detached 拉起。 */
 async function cmdRestart(dataRoot, opts) {
@@ -754,8 +1187,8 @@ async function cmdRestart(dataRoot, opts) {
 const DEFAULT_RESTART_DELAY_MS = 2e3;
 /** 退出轮询间隔（毫秒）。 */
 const EXIT_POLL_MS = 100;
-/** 子进程强制退出时限（毫秒，超时未退则父进程强制退出）。 */
-const FORCE_EXIT_MS = 5e3;
+/** 子进程优雅退出时限（毫秒）：哨兵/信号后子进程自行停止，超时强杀兜底。 */
+const FORCE_EXIT_MS = 8e3;
 /** 解析账号列表（显式 -q 优先，否则主配置 accounts 过滤启用项）。 */
 function resolveAccounts(opts, config) {
 	if (opts.qqs !== void 0 && opts.qqs.length > 0) return opts.qqs.map((qq) => ({ qq }));
@@ -766,18 +1199,22 @@ function resolveRestartDelay(opts, config) {
 	if (opts.qqs === void 0) return config.restartDelayMs;
 	return DEFAULT_RESTART_DELAY_MS;
 }
-/** 子进程输出前缀转发（stdout/stderr 逐行 `[uin] ` 前缀；pino 行结构化保留在行内）。 */
-function forwardPrefixed(stream, uin) {
+/**
+* 子进程输出前缀转发（stdout/stderr 逐行）：pretty 模式加 `[uin] ` 前缀
+* （pino 行结构化保留在行内）；single-line/json 模式记录自身已带结构化
+* account 字段（json 加前缀会破坏逐行 JSON.parse），原样透传。
+*/
+function forwardPrefixed(stream, uin, prefixEnabled) {
 	if (stream === null) return;
 	createInterface({ input: stream }).on("line", (line) => {
-		process.stdout.write(`[${uin}] ${line}\n`);
+		process.stdout.write(prefixEnabled ? `[${uin}] ${line}\n` : `${line}\n`);
 	});
 }
 /** 启动一个账号子进程（exit 后按 autoRestart 守护重启）。 */
 function startAccount(ctx, acct) {
 	if (ctx.isStopping()) return;
 	const restartCount = ctx.restartCounts.get(acct.qq) ?? 0;
-	logger.info({
+	logger.debug({
 		qq: acct.qq,
 		pid: process.pid,
 		restartCount
@@ -790,13 +1227,20 @@ function startAccount(ctx, acct) {
 		ctx.dataRoot
 	];
 	if (ctx.stubDir !== void 0) args.push("--stub-dir", ctx.stubDir);
-	const child = spawn(process.execPath, args, { stdio: [
-		"inherit",
-		"pipe",
-		"pipe"
-	] });
-	forwardPrefixed(child.stdout, acct.qq);
-	forwardPrefixed(child.stderr, acct.qq);
+	const child = spawn(process.execPath, args, {
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
+		env: {
+			...process.env,
+			NAPUKETTO_NO_BANNER: "1",
+			...ctx.childEnv
+		}
+	});
+	forwardPrefixed(child.stdout, acct.qq, ctx.prefixEnabled);
+	forwardPrefixed(child.stderr, acct.qq, ctx.prefixEnabled);
 	ctx.children.set(acct.qq, child);
 	writeAccountRuntime(ctx.dataRoot, {
 		uin: acct.qq,
@@ -813,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(() => {
@@ -837,14 +1297,21 @@ function startAccount(ctx, acct) {
 		ctx.children.delete(acct.qq);
 	});
 }
-/** 停止全部子进程，全部退出后父进程退出（2026-08-07：超时强杀兜底）。 */
+/** 停止全部子进程，全部退出后父进程退出（2026-10-25 优雅化）。
+*
+* 优雅路径：写停止哨兵（all）→ 子进程链（boot / self-host）自行有序退出 →
+* 全部退出后 exit 0（退出码契约：0 = 请求式正常退出）。超时（FORCE_EXIT_MS）
+* 未退的子进程 kill 兜底（Windows 下为硬杀）后仍 exit 0——关停请求本身是正常路径，
+* 与崩溃（非 0）区分是契约的核心目标。
+*/
 function stopAll(ctx) {
 	logger.info("收到退出信号，停止全部账号");
-	for (const child of ctx.children.values()) child.kill();
+	writeStopSentinel(ctx.dataRoot, "all");
 	const forceTimer = setTimeout(() => {
-		logger.warn("子进程未在限时内退出，强制退出");
-		process.exit(1);
+		for (const child of ctx.children.values()) child.kill();
+		process.exit(0);
 	}, FORCE_EXIT_MS);
+	forceTimer.unref?.();
 	const wait = setInterval(() => {
 		if (ctx.children.size === 0) {
 			clearInterval(wait);
@@ -856,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 为空或全部禁用）");
@@ -867,6 +1334,7 @@ async function runSupervisor(opts = {}) {
 	const children = /* @__PURE__ */ new Map();
 	const restartCounts = /* @__PURE__ */ new Map();
 	let stopping = false;
+	const logCfg = resolveCliLogConfig(opts.dataDir);
 	const ctx = {
 		dataRoot,
 		entry,
@@ -875,6 +1343,8 @@ async function runSupervisor(opts = {}) {
 		...opts.stubDir !== void 0 ? { stubDir: opts.stubDir } : {},
 		children,
 		restartCounts,
+		childEnv: effectiveConsoleEnv(logCfg),
+		prefixEnabled: effectiveConsoleFormat(logCfg) === "pretty",
 		isStopping: () => stopping
 	};
 	writeSupervisorRuntime(dataRoot, {
@@ -890,6 +1360,11 @@ async function runSupervisor(opts = {}) {
 	};
 	process.on("SIGINT", shutdown);
 	process.on("SIGTERM", shutdown);
+	process.on("SIGBREAK", shutdown);
+	watchStopSentinel({
+		dataRoot,
+		onTrigger: shutdown
+	});
 	await new Promise(() => {});
 }
 //#endregion
@@ -902,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 用户拍板），相关入口已移除。
 */
@@ -920,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);
@@ -945,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);
 		}
 	});
 }
@@ -972,85 +1459,83 @@ 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({
+		...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({
-		...opts.dataDir !== void 0 ? { dataDir: opts.dataDir } : {},
-		...opts.stubDir !== void 0 ? { stubDir: opts.stubDir } : {}
+		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);
 		}
 	});
 }
 /** 入口：注册全部子命令与主命令后解析。 */
 function main() {
-	process.stdout.write(`${BANNER}\n`);
 	const program = new Command();
 	program.name("napuketto").version("0.0.1").description("NapukettoQQ 机器人框架（OneBot 11 兼容）");
 	program.option("-q, --qq <uin>", "QQ 号（可重复；多个时 supervisor 拉起多账号子进程）", collectQq, []).option("-d, --data-dir <dir>", "数据根目录（缺省 <项目根>/.napuketto）").option("--qq-path <path>", "QQ 安装路径（联调覆盖）").option("--stub-dir <dir>", "stub QQNT.dll 目录（自建宿主 PATH 前置，缺省 loader/native/stub-test-env，Git Submodule）");
+	program.hook("preAction", () => {
+		if (resolveCliLogConfig(rootDataDir(program).dataDir).banner) process.stdout.write(`${BANNER}\n`);
+	});
 	registerConfigCommands(program);
 	registerSupervisorCommand(program);
 	registerOpsCommands(program);