@napuketto/cli 0.2.0 → 0.3.1

package/dist/index.mjs

@@ -1,15 +1,226 @@
 #!/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 { access, readFile, writeFile } from "node:fs/promises";
 import path, { dirname, extname, isAbsolute, join } from "node:path";
+import { checkInstanceLock, defaultStubDir, isNativeNoiseLine, launchSelfHost, removeStopSentinel, resolveQqFiles, watchStopSentinel, writeStopSentinel } from "@napuketto/loader";
+import { spawn } from "node:child_process";
 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/config/schema.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 一族，
+* 内联与文件两形态共用本校验器）。
+*/
+/** 保留占位 QQ 号（模板默认值）：必须替换为真实 QQ 号，否则启动校验报错。 */
+const RESERVED_PLACEHOLDER_QINS = ["123456", "654321"];
+/** 默认自动重启。 */
+const DEFAULT_AUTO_RESTART = true;
+/** 默认重启延迟（毫秒；supervisor 显式 -q 场景复用，避免两处常量漂移）。 */
+const DEFAULT_RESTART_DELAY_MS = 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;
+	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），嵌入式配置形状远小于该限（超限宿主退回文件形态）。
+*
+* 读取口径分两档（有意为之）：
+* - parseInlineConfig：严格，主配置加载 / config validate 用；JSON 解析失败、
+*   非对象、字段校验失败一律 ConfigError（exit 78 一族）。
+* - readInlineConfigDoc / readInlineConfigSection：宽松，logger 读 [log] 段用；
+*   坏文档返回 undefined（日志配置损坏不阻塞启动，严格校验由主配置路径负责）。
+* loader 引导进程另有自己的宽松读取（编译期不静态依赖 kernel），两套不合并。
+*
+* 错误文案指明来源为「内联配置」且不含任何 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.parse 产物 → 配置对象（数组 / null / 原始值 → undefined）。 */
+function asConfigObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return;
+	return value;
+}
+/**
+* 读内联配置文档（宽松口径：未设置 / 空串 / JSON 解析失败 / 非对象 → undefined）。
+* 供日志段等「坏配置不阻塞启动」的消费方使用。
+*/
+function readInlineConfigDoc() {
+	const text = readInlineConfigText();
+	if (text === void 0) return;
+	try {
+		return asConfigObject(JSON.parse(text));
+	} catch {
+		return;
+	}
+}
+/** 读内联配置的单个顶层段（坏文档 → undefined；logger 读 [log] 用）。 */
+function readInlineConfigSection(key) {
+	const doc = readInlineConfigDoc();
+	return doc === void 0 ? void 0 : doc[key];
+}
+/** 严格解析内联 JSON 对象（主配置校验入口；错误一概 ConfigError）。 */
+function parseJsonObject(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 });
+	}
+	const object = asConfigObject(doc);
+	if (object === void 0) throw configError("内联配置必须是 JSON 对象（与 napuketto.toml 同构）");
+	return object;
+}
+/**
+* 内联 JSON 文本 → 校验后的主配置。JSON 解析失败 / 非对象 / 字段校验失败
+* 均抛 ConfigError（宿主消费 exit 78，不重试）。
+*/
+function parseInlineConfig(text) {
+	return parseCliConfig(parseJsonObject(text));
+}
+//#endregion
 //#region src/logger.ts
 /**
 * cli 进程级 logger（ADR-007 日志规范，2026-08-07 统一改造；2026-10-25 日志可配置化）。
@@ -27,13 +238,15 @@ import { access, readFile, writeFile } from "node:fs/promises";
 let cachedConfig = null;
 /** 解析配置时用的数据根（[log.file] 相对路径展开基准）。 */
 let cachedDataRoot = resolveDataRoot();
-/** 同步解析日志配置（toml [log] 段 + env 覆盖）。损坏/缺失配置回退缺省（不阻塞启动：
-* 配置的严格校验由 loadCliConfig 主路径负责报错）。 */
+/** 同步解析日志配置（内联 > toml 文件的 [log] 段 + env 覆盖）。损坏/缺失配置回退缺省
+* （不阻塞启动：配置的严格校验由 loadCliConfig 主路径负责报错）。内联生效时不读
+* 任何 toml 文件（嵌入式契约，2026-10-25）。 */
 function resolveCliLogConfig(dataDir) {
 	if (cachedConfig !== null) return cachedConfig;
 	cachedDataRoot = resolveDataRoot(dataDir);
 	let section;
-	try {
+	if (isInlineConfigActive()) section = readInlineConfigSection("log");
+	else try {
 		const configPath = resolveConfigPath({ dataRoot: cachedDataRoot });
 		section = parseToml(readFileSync(configPath, "utf8"))["log"];
 	} catch {
@@ -115,309 +328,15 @@ var LazyCliLogger = class {
 /** cli 进程日志（懒构造，配置见 resolveCliLogConfig）。 */
 const logger = new LazyCliLogger();
 //#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 ";
-/** 优雅停等待上限（毫秒）：超时 kill 兜底（Windows 下为硬杀）。 */
-const GRACEFUL_STOP_TIMEOUT_MS = 1e4;
+//#region src/config/template.ts
 /**
-* 逐行转发子进程输出到父进程，过滤原生噪音。
-* 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 优化）。
+* 配置模板（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 全局配置文件
@@ -547,125 +466,31 @@ port = 3001
 # ------------------------------------------------------------
 # 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
-/**
-* 主配置类型与手写校验器（从 config-cmds.ts 拆分，2026-08-08 FTA 优化）
-*
-* 主配置 parse（不引入 zod）：数据根 / 自动重启 / 重启延迟 / 账号列表。
-* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
-* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
-* 协议段为宽松对象，装配时由对应协议包的 zod schema 严格校验。
-*/
-/** 默认自动重启。 */
-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;
-}
-/**
-* 解析 dataDir（缺省用当前解析的数据根 = 项目根/.napuketto）。
-* 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录），
-* 消费端 resolveDataRoot 统一展开为绝对路径。
-*/
-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"];
-}
-/** 解析 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"];
-}
-/** 解析 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"];
-}
-/** 解析 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;
-}
-/** 解析单个账号项（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;
-	}
-	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 值。
-*/
-function stripUndefinedFormat(log) {
-	const { format, ...rest } = log;
-	return format === void 0 ? rest : {
-		...rest,
-		format
-	};
-}
-/** 手写校验器：主配置 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;
-	return {
-		dataDir,
-		autoRestart,
-		restartDelayMs,
-		accounts,
-		...log !== void 0 ? { log } : {}
-	};
+# 账号内写 [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-cmds.ts
+//#region src/config/store.ts
+/**
+* 主配置 store：默认值、ConfigBase 子类、模板落盘、内联/文件来源加载。
+*
+* 从 config-cmds.ts 拆出（2026-10-25 模块收拢）：
+* - `CliConfigStore` 只负责 napuketto.toml 的读写/校验（kernel ConfigBase）；
+* - `loadCliConfigWithSource` 负责来源决议（NAPKETTO_CONFIG_JSON 优先）与来源日志；
+* - 4 个 config 子命令留在 commands/config.ts，不反向依赖本文件的私有实现。
+*/
 /** 主配置默认值（dataRoot 为当前解析的数据根 = 项目根/.napuketto）。 */
 function defaultCliConfig(dataRoot) {
 	return {
@@ -696,12 +521,58 @@ var CliConfigStore = class extends ConfigBase {
 		});
 	}
 };
-/** 读取主配置（缺失自动落模板）。 */
+/** 读取主配置（缺失自动落模板；loadCliConfigWithSource 文件分支内部用）。 */
 async function loadCliConfig(dataRoot) {
 	const store = new CliConfigStore(dataRoot);
 	await ensureConfigTemplate(store.path);
 	return await store.load();
 }
+/**
+* 解析生效配置来源（loadCliConfigWithSource 与 config validate 无参分支共用）：
+* 内联非空 → inline；否则按 kernel resolveConfigPath 解析文件路径，并带回数据根。
+*/
+function resolveCliConfigSource(opts = {}) {
+	const inlineText = readInlineConfigText();
+	if (inlineText !== void 0) return {
+		source: "inline",
+		text: inlineText
+	};
+	const dataRoot = resolveDataRoot(opts.dataDir);
+	return {
+		source: "file",
+		path: resolveConfigPath({ dataRoot }),
+		dataRoot
+	};
+}
+/** 「配置来源」日志每进程至多一行（autoStart 与 runSupervisor 各加载一次）。 */
+let sourceLogged = false;
+/**
+* 加载主配置（内联优先，2026-10-25 嵌入式契约）：
+* NAPKETTO_CONFIG_JSON 非空 → 内存文档校验（不读 / 不写 / 不校验任何 toml
+* 文件），打一行来源日志；否则现行文件链路（缺失自动落模板）。校验失败两形态
+* 同为 ConfigError（exit 78），文案区别只在来源标注。
+*/
+async function loadCliConfigWithSource(opts = {}) {
+	const resolved = resolveCliConfigSource(opts);
+	if (resolved.source === "inline") {
+		const config = parseInlineConfig(resolved.text);
+		if (!sourceLogged) {
+			sourceLogged = true;
+			logger.info("配置来源: inline（NAPKETTO_CONFIG_JSON）");
+		}
+		return {
+			config,
+			source: "inline"
+		};
+	}
+	return {
+		config: await loadCliConfig(resolved.dataRoot),
+		source: "file",
+		path: resolved.path
+	};
+}
+//#endregion
+//#region src/commands/config.ts
 /** CliConfig → 普通对象（smol-toml stringify 入参）。 */
 function toRecord(config) {
 	return config;
@@ -794,12 +665,175 @@ 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");
+	if (configJson !== void 0) {
+		parseInlineConfig(configJson);
+		return { source: "inline" };
+	}
+	if (configPath !== void 0) {
+		await validateConfigFile(configPath, resolveDataRoot(opts.dataDir));
+		return {
+			source: "file",
+			path: configPath
+		};
+	}
+	const resolved = resolveCliConfigSource(opts);
+	if (resolved.source === "inline") {
+		parseInlineConfig(resolved.text);
+		return { source: "inline" };
+	}
+	await validateConfigFile(resolved.path, resolved.dataRoot);
+	return {
+		source: "file",
+		path: resolved.path
+	};
+}
+//#endregion
+//#region src/runtime/state.ts
+/**
+* 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/ops-commands.ts
+//#region src/commands/ops.ts
 /**
-* ops-commands.ts：status / stop / restart 运维命令实现（2026-09-08 T8）。
+* ops.ts：status / stop / restart 运维命令实现（2026-09-08 T8）。
 *
-* 数据源：runtime-state 状态文件（supervisor/单账号 boot 写入）+ liveness 检测。
+* 数据源：runtime/state 状态文件（supervisor/单账号 boot 写入）+ liveness 检测。
 * stop/restart 语义（2026-10-25 优雅化）：
 *  - stop -q <uin>：写单账号停止哨兵 → 等该账号进程链优雅退出 → 超时树杀兜底。
 *    ⚠️ supervisor 在跑且 autoRestart 时账号会被自动拉起——提示用户先 `napuketto stop`。
@@ -879,57 +913,294 @@ async function stopSingleAccount(dataRoot, target) {
 	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) {
-		const target = runtimes.find((r) => r.uin === opts.qq);
-		if (target === void 0) {
-			logger.error({ uin: opts.qq }, "账号无运行时状态（未启动过）");
-			process.exitCode = 1;
-			return;
-		}
-		await stopSingleAccount(dataRoot, target);
+async function cmdStop(dataRoot, opts) {
+	const runtimes = listAccountRuntimes(dataRoot);
+	if (opts.qq !== void 0) {
+		const target = runtimes.find((r) => r.uin === opts.qq);
+		if (target === void 0) {
+			logger.error({ uin: opts.qq }, "账号无运行时状态（未启动过）");
+			process.exitCode = 1;
+			return;
+		}
+		await stopSingleAccount(dataRoot, target);
+		return;
+	}
+	const supervisor = readSupervisorRuntime(dataRoot);
+	const supervisorPid = supervisor !== null && isPidAlive(supervisor.pid) ? supervisor.pid : 0;
+	if (supervisor !== null) {
+		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 未运行（无状态文件）");
+	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) {
+	await cmdStop(dataRoot, opts);
+	await new Promise((resolve) => setTimeout(resolve, 1500));
+	const entry = process.argv[1] ?? "";
+	const args = opts.qq !== void 0 ? [
+		entry,
+		"-q",
+		opts.qq,
+		"--data-dir",
+		dataRoot
+	] : [
+		entry,
+		"--data-dir",
+		dataRoot
+	];
+	spawnDetached(args);
+	logger.info({
+		args: args.slice(1),
+		qq: opts.qq ?? "(supervisor 全量)"
+	}, "已 detached 拉起（日志不再接入当前终端，见数据目录 logs/）");
+}
+//#endregion
+//#region src/runtime/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;
+/**
+* 逐行转发子进程输出到父进程，过滤原生噪音。
+* 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 {}
+}
+/** 解析自建宿主装配面的三个包入口（ESM 解析，顺序同旧实现）。 */
+async function resolvePackageEntries() {
+	return {
+		kernelEntry: await packageEntry("@napuketto/kernel"),
+		adapterEntry: await packageEntry("@napuketto/adapter"),
+		networkEntry: await packageEntry("@napuketto/network")
+	};
+}
+/** stub QQNT.dll 目录（--stub-dir > NAPUTO_STUB_DIR > loader 包内闭源 submodule 默认）。 */
+function resolveStubDir(opts) {
+	return opts.stubDir ?? process.env["NAPUTO_STUB_DIR"] ?? defaultStubDir();
+}
+/** 错误文案提取（Error 用 message，其余字符串化——保留旧日志文案语义）。 */
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** 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 supervisor = readSupervisorRuntime(dataRoot);
-	const supervisorPid = supervisor !== null && isPidAlive(supervisor.pid) ? supervisor.pid : 0;
-	if (supervisor !== null) {
-		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 未运行（无状态文件）");
-	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) {
-	await cmdStop(dataRoot, opts);
-	await new Promise((resolve) => setTimeout(resolve, 1500));
-	const entry = process.argv[1] ?? "";
-	const args = opts.qq !== void 0 ? [
-		entry,
-		"-q",
-		opts.qq,
-		"--data-dir",
-		dataRoot
-	] : [
-		entry,
-		"--data-dir",
-		dataRoot
-	];
-	spawnDetached(args);
-	logger.info({
-		args: args.slice(1),
-		qq: opts.qq ?? "(supervisor 全量)"
-	}, "已 detached 拉起（日志不再接入当前终端，见数据目录 logs/）");
+/**
+* 单实例锁预检（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 {
+		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/supervisor.ts
+//#region src/runtime/supervisor.ts
 /**
 * supervisor：多账号子进程编排（P6，2026-08-05；2026-08-07 自建宿主唯一）
 *
@@ -940,8 +1211,6 @@ async function cmdRestart(dataRoot, opts) {
 *   - 守护：账号异常退出且 autoRestart → 延迟重启
 *   - 信号转发：SIGINT/SIGTERM → 停止全部子进程 → 父进程退出
 */
-/** 默认重启延迟（毫秒）。 */
-const DEFAULT_RESTART_DELAY_MS = 2e3;
 /** 退出轮询间隔（毫秒）。 */
 const EXIT_POLL_MS = 100;
 /** 子进程优雅退出时限（毫秒）：哨兵/信号后子进程自行停止，超时强杀兜底。 */
@@ -1014,6 +1283,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 +1349,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 为空或全部禁用）");
@@ -1109,18 +1394,103 @@ async function runSupervisor(opts = {}) {
 	await new Promise(() => {});
 }
 //#endregion
-//#region src/index.ts
+//#region src/commands/start.ts
 /**
-* @napuketto/cli 入口（P2-6 + P6，2026-08-05；2026-08-07 用户拍板：只保留自建宿主；
-* 2026-08-08 配置结构拍板：账号必填，协议配置嵌在账号内）
+* 默认动作（无子命令）用例：-q 单账号 / 多 -q supervisor / 无 -q 读配置拉起全部账号。
 *
-* commander 参数解析：
-*   - 单账号：-q <uin> → runSingleAccount（自建宿主：标准 node + stub QQNT.dll，不拉起 QQ）
-*   - 多账号：-q A -q B 或 supervisor 子命令 → runSupervisor（子进程编排）
-*   - 无 -q：读全局配置 accounts（至少一个，账号必填）→ supervisor 拉起全部启用账号
-*   - config 子命令：init / list / apply（主配置管理）
+* 从 index.ts 拆出（2026-10-25 模块收拢）：这里只做编排，不 import commander；
+* 参数解析、帮助文案与退出码收敛在 cli/program.ts。
+*/
+/** 构造可选 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 };
+}
+/** 单账号启动分支（-q 单值；构造 bootOptions 后走 runSingleAccount）。 */
+async function runSingleAccountBranch(opts, qqs) {
+	const [only] = qqs;
+	if (only === void 0) return;
+	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) {
+	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({
+		qqs,
+		...withDataDir(opts.dataDir),
+		...withStubDir(opts.stubDir)
+	});
+}
+/** supervisor 子命令用例（读主配置 accounts 批量拉起；-d 复用主命令 option）。 */
+async function runSupervisorCommand(opts) {
+	await runSupervisor(withDataDir(opts.dataDir));
+}
+//#endregion
+//#region src/cli/error.ts
+/**
+* CLI 动作错误出口（2026-10-25 退出码契约）：
+*   0 = 请求式优雅关停（0.2.0 已有，不经此路径）；78 = 配置校验失败
+*   （ConfigError 一族，宿主据此区分「配置未就绪」与运行时崩溃，免重启）；
+*   其余 = 1（运行时崩溃，现状不变）。
 *
-* 路线 B（拉起 QQ + 注入）已淘汰（2026-08-07 用户拍板），相关入口已移除。
+* 退出码只认错误类型（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/cli/program.ts
+/**
+* commander 装配层：全局选项、banner、子命令注册、默认动作分发。
+*
+* 从 index.ts 拆出（2026-10-25 模块收拢）：只做 CLI 契约适配（参数/帮助/输出/
+* 退出码），用例实现见 commands/。禁止在此写业务逻辑。
 */
 /** commander collect：累积 -q 多值。 */
 function collectQq(value, prev) {
@@ -1136,23 +1506,10 @@ 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 };
-}
 /** 读主命令已解析的 data-dir（-d 定义在主命令，子命令经此共享）。 */
 function rootDataDir(program) {
-	return withDataDir(program.opts().dataDir);
+	const { dataDir } = program.opts();
+	return dataDir === void 0 ? {} : { dataDir };
 }
 /** 注册 config 子命令（init/list/apply，P6；-d 复用主命令 option）。 */
 function registerConfigCommands(program) {
@@ -1161,103 +1518,69 @@ 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);
 		}
 	});
-}
-/** 注册 supervisor 子命令（读主配置 accounts 批量拉起，P6；-d 复用主命令 option）。 */
-function registerSupervisorCommand(program) {
-	program.command("supervisor").description("多账号编排（读全局配置 accounts 拉起子进程）").action(async () => {
+	configCmd.command("validate").description("校验配置（--config <path> / --config-json <json> 二选一；无参 = 校验生效配置）").option("--config <path>", "待校验配置文件路径（.toml/.json 按扩展名解析）").option("--config-json <json>", "待校验内联配置 JSON 文本").action(async (opts) => {
 		try {
-			await runSupervisor(rootDataDir(program));
+			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) {
-			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) => {
+/** 注册 supervisor 子命令（读主配置 accounts 批量拉起，P6；-d 复用主命令 option）。 */
+function registerSupervisorCommand(program) {
+	program.command("supervisor").description("多账号编排（读全局配置 accounts 拉起子进程）").action(async () => {
 		try {
-			await cmdStop(resolveDataRoot(rootDataDir(program).dataDir), { ...opts.qq !== void 0 ? { qq: opts.qq } : {} });
+			await runSupervisorCommand(rootDataDir(program));
 		} catch (err) {
-			reportError(err);
-			process.exitCode = 1;
+			handleActionError(err);
 		}
 	});
-	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);
 		}
-	});
-}
-/** 单账号启动分支（-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);
+	};
 }
-/** 无 -q 时：读全局配置 accounts（账号必填，2026-08-08 拍板），supervisor 拉起全部启用账号。
-* 不再有「配置为空 → 交互式单账号登录」老路径：缺账号直接报错提示编辑模板。 */
-async function autoStart(opts) {
-	if ((await loadCliConfig(resolveDataRoot(opts.dataDir))).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 } : {}
-	});
+/** 注册运维子命令（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)));
 }
 /** 注册主命令 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);
 		}
 	});
 }
@@ -1275,6 +1598,25 @@ function main() {
 	registerMainAction(program);
 	program.parse(process.argv);
 }
+//#endregion
+//#region src/index.ts
+/**
+* @napuketto/cli 入口（P2-6 + P6，2026-08-05；2026-08-07 用户拍板：只保留自建宿主；
+* 2026-08-08 配置结构拍板：账号必填，协议配置嵌在账号内）
+*
+* commander 参数解析：
+*   - 单账号：-q <uin> → runSingleAccount（自建宿主：标准 node + stub QQNT.dll，不拉起 QQ）
+*   - 多账号：-q A -q B 或 supervisor 子命令 → runSupervisor（子进程编排）
+*   - 无 -q：读全局配置 accounts（至少一个，账号必填）→ supervisor 拉起全部启用账号
+*   - config 子命令：init / list / apply / validate（主配置管理）
+*   - 退出码契约（2026-10-25）：0 = 请求式优雅关停；78 = 配置校验失败（ConfigError
+*     一族，宿主消费，免重启）；其余错误 = 1（handleActionError 统一出口）
+*
+* 路线 B（拉起 QQ + 注入）已淘汰（2026-08-07 用户拍板），相关入口已移除。
+*
+* 2026-10-25 模块收拢：本文件只保留进程入口；commander 装配在 cli/program.ts，
+* 用例在 commands/，配置领域在 config/，运行期在 runtime/。
+*/
 main();
 //#endregion
 export {};