@napuketto/cli 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -3,172 +3,16 @@ import process from "node:process";
 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 { spawn } from "node:child_process";
-import { access, readFile, writeFile } from "node:fs/promises";
-//#region src/config-template.ts
-/**
-* 配置模板（TOML 注释版，从 config-cmds.ts 拆分，2026-08-08 FTA 优化）。
-* `config init` 与首次启动（loadCliConfig）缺失时生成。
-*
-* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
-* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
-* dataDir 不再写死（缺省 = 项目根/.napuketto，跨平台），模板保持可移植。
-*/
-/** 保留占位 QQ 号（模板默认值）：必须替换为真实 QQ 号，否则启动校验报错。 */
-const RESERVED_PLACEHOLDER_QINS = ["123456", "654321"];
-function configTemplate() {
-	return `# ============================================================
-# NapukettoQQ 全局配置文件
-# ============================================================
-# 本文件由 \`napuketto config init\` 生成（或首次启动自动生成）。
-# 本机配置不入库（.gitignore）；修改后重启生效。
-#
-# 配置组织：一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在账号内
-# （[accounts.onebot11] / [accounts.satori] / [accounts.kurobot]）。账号没有写
-# 某协议段 = 该账号不启用该协议。账号必填（至少一个，qq 必填）。
-
-# ------------------------------------------------------------
-# 全局配置（跨账号）
-# ------------------------------------------------------------
-
-# 数据根目录：账号目录/日志/缓存/QQ 数据存放位置。
-# 缺省 = <项目根>/.napuketto（部署场景，跨平台，无需修改）。
-# 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录）。
-# dataDir = ".napuketto"
-
-# 多账号（supervisor）模式下，账号进程崩溃是否自动重启
-autoRestart = true
-
-# 崩溃后自动重启的延迟（毫秒）
-restartDelayMs = 2000
-
-# ------------------------------------------------------------
-# 日志（[log]，可选——不配置即用缺省：终端 pretty 多行 / 管道 single-line）
-# ------------------------------------------------------------
-# 嵌入式宿主（把 napuketto 打进服务端等场景）推荐：
-#   [log]
-#   format = "single-line"     # 或 "json"（NDJSON，宿主按 level/module 精确路由）
-#   level = "warn"             # 控制台只留警告以上，细节进文件（配 [log.file]）
-#   banner = false
-#
-# [log]
-# format = "pretty"            # pretty | single-line | json（缺省按 TTY 自动）
-# level = "info"               # trace|debug|info|warn|error|fatal（控制台级别）
-# banner = true                # 启动字符画
-# timestamp = "local"          # local | iso8601 | elapsed
-# unboundReceive = true        # false = 未绑定频道的接收行不打（kurobot 握手后生效）
-# [log.levels]                 # 按模块覆盖级别：cli / kernel / loader / ob11
-# # loader = "debug"           # 例：终端上看接收行（默认已降 debug）
-# # ob11 = "debug"             # 例：协议校准数据（含原始 hex）
-# [log.file]                   # 独立文件 sink（可选；级别可低于控制台）
-# # path = "logs/napuketto-console.log"
-# # level = "debug"
-#
-# 环境变量覆盖（优先级高于本文件）：NAPUKETTO_LOG_LEVEL / NAPUKETTO_LOG_FORMAT /
-# NAPUKETTO_NO_BANNER（兼容旧拼写 NAPKETTO_LOG_LEVEL）。
-
-# ------------------------------------------------------------
-# 账号（至少一个，qq 必填）
-# ------------------------------------------------------------
-
-[[accounts]]
-qq = "${RESERVED_PLACEHOLDER_QINS[0]}"            # 占位值，必须替换为你的 QQ 号，否则启动报错
-enabled = true           # 是否启用（可选，缺省 true）
-
-[accounts.onebot11]      # 该账号的 OneBot 11 配置（无此段 = 不启用 OB11）
-
-# 鉴权 token（全局默认）：HTTP/WS 连接必须携带。
-#   校验方式：Authorization: Bearer <token> / 裸 token / URL 参数 ?access_token=<token>
-#   每个网络实例可单独覆盖（见下文各实例的 token 字段）。
-#   留空 = 不鉴权（仅本机调试推荐）。
-# token = ""
-
-# 心跳 meta 事件间隔（毫秒）；0 = 关闭心跳事件
-heartbeatInterval = 3000
-
-# 是否上报机器人自己发的消息（OB11 规范默认不上报）
-reportSelfMessage = false
-
-# 消息内容格式：array = 消息段数组（标准 OneBot 11），string = CQ 码字符串
-messagePostFormat = "array"
-
-# 群文件报形式：false（默认）= message 事件 + file 段（go-cqhttp 兼容）；
-# true = 群文件消息改报 group_upload notice 事件（替代 message 事件）
-groupUploadAsNotice = false
-
-# ---- HTTP 反向服务器（接收第三方 POST 指令），可配置多个 ----
-[[accounts.onebot11.httpServers]]
-enabled = true
-host = "127.0.0.1"       # 监听地址；0.0.0.0 = 监听所有网卡（局域网可连）
-port = 3000
-# token = "abc"          # 可选：覆盖全局 token
-
-# ---- HTTP 正向上报（Webhook：把事件 POST 到第三方地址），可配置多个 ----
-# [[accounts.onebot11.httpPostUrls]]
-# enabled = true
-# url = "http://127.0.0.1:8080/onebot"   # 第三方接收地址
-# token = "abc"                          # 可选：覆盖全局 token
-# timeoutMs = 5000                       # 可选：上报超时（毫秒），缺省不超时
-
-# ---- WS 反向服务器（外部 WS 客户端主动连入），可配置多个 ----
-[[accounts.onebot11.wsServers]]
-enabled = true
-host = "127.0.0.1"
-port = 3001
-# token = "abc"                          # 可选：覆盖全局 token
-# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
-
-# ---- WS 正向客户端（主动连接外部 WS，双向），可配置多个 ----
-# [[accounts.onebot11.wsReverseUrls]]
-# enabled = true
-# url = "ws://127.0.0.1:8081/ws"         # 第三方 WS 地址（ws:// 或 wss://）
-# token = "abc"                          # 可选：覆盖全局 token
-# reconnectDelayMs = 5000                # 可选：断线重连延迟（毫秒）
-# maxReconnectAttempts = 10              # 可选：最大重连次数（缺省无限）
-# rejectUnauthorized = true              # 可选：wss:// 是否校验证书（自签证书设 false）
-# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
-
-# 第二个账号示例（只开 Satori）：
-# [[accounts]]
-# qq = "${RESERVED_PLACEHOLDER_QINS[1]}"
-# [accounts.satori]
-# # token = ""                           # 可选：Satori 鉴权 token
-# [[accounts.satori.httpServers]]        # HTTP RPC（POST /v1/{resource}.{method}）
-# enabled = true
-# host = "127.0.0.1"
-# port = 5500
-# [[accounts.satori.wsServers]]          # WS 事件服务（/v1/events）
-# enabled = true
-# host = "127.0.0.1"
-# port = 5501
-
-# ------------------------------------------------------------
-# KuroBot 群服互通（kurobridge-ws 客户端，MVP-3）
-# ------------------------------------------------------------
-# 账号内写 [accounts.kurobot] 段即启用；不写 = 不启用。作为 WS 客户端
-# 主动连入 KuroBot 服务端（Minecraft 服务器 kurobot 插件）。
-# QQ 群文字 ↔ 游戏聊天双向互通；群命令（前缀开头）→ 游戏命令。
-# [accounts.kurobot]
-# url = "ws://127.0.0.1:25580"           # 必填：KuroBot 服务端地址（ws:// 或 wss://）
-# # token = ""                           # 可选：鉴权 token（服务端配了则必填，错 token 拒连）
-# # client = "napukettoqq"               # 可选：自报身份（缺省 napukettoqq/<版本>）
-# # commandPrefix = "/"                  # 可选：群命令前缀
-# # pingIntervalMs = 15000               # 可选：应用层心跳间隔（毫秒，须 < 30000）
-# # chatTemplate = "[{player}] {content}"    # 游戏聊天渲染模板
-# # joinTemplate = "{player} 加入了服务器"    # 玩家进服模板
-# # leaveTemplate = "{player} 离开了服务器"   # 玩家退服模板
-# # deathTemplate = "{player} {message}"     # 玩家死亡模板（空消息显示「死亡了」）
-`;
-}
-//#endregion
-//#region src/config-parse.ts
+//#region src/config/schema.ts
 /**
-* 主配置类型与手写校验器（从 config-cmds.ts 拆分，2026-08-08 FTA 优化）
+* 主配置类型与手写校验器（原 config-cmds.ts 拆分，2026-08-08 FTA 优化）
 *
 * 主配置 parse（不引入 zod）：数据根 / 自动重启 / 重启延迟 / 账号列表。
 * 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
@@ -177,10 +21,12 @@ port = 3001
 * 全部校验错误为 ConfigError（2026-10-25 嵌入式退出码契约：CLI exit 78 一族，
 * 内联与文件两形态共用本校验器）。
 */
+/** 保留占位 QQ 号（模板默认值）：必须替换为真实 QQ 号，否则启动校验报错。 */
+const RESERVED_PLACEHOLDER_QINS = ["123456", "654321"];
 /** 默认自动重启。 */
 const DEFAULT_AUTO_RESTART = true;
-/** 默认重启延迟（毫秒）。 */
-const DEFAULT_RESTART_DELAY_MS$1 = 2e3;
+/** 默认重启延迟（毫秒；supervisor 显式 -q 场景复用，避免两处常量漂移）。 */
+const DEFAULT_RESTART_DELAY_MS = 2e3;
 /** QQ 号格式：纯数字 5-11 位（QQ 号合法范围，勿写死 11 位）。 */
 const QQ_IN_FORMAT_RE = /^\d{5,11}$/;
 /** 解析账号内协议段（宽松对象，装配时由 zod schema 严格校验）。 */
@@ -208,7 +54,7 @@ function parseAutoRestart(raw) {
 }
 /** 解析 restartDelayMs（毫秒）。 */
 function parseRestartDelayMs(raw) {
-	if (raw["restartDelayMs"] === void 0) return DEFAULT_RESTART_DELAY_MS$1;
+	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"];
 }
@@ -238,7 +84,7 @@ function applyAccountEnabled(out, enabled) {
 	if (typeof enabled !== "boolean") throw configError("主配置账号 enabled 必须是布尔值");
 	out.enabled = enabled;
 }
-/** 账号内协议段装配（onebot11/satori/kurobot 缺省 = 不启用该协议）。 */
+/** 账号内协议段装配（onebot11/satori/kurobot/milky 缺省 = 不启用该协议）。 */
 function applyProtocolSections(raw, out) {
 	const onebot11 = parseProtocolSection(raw, "onebot11");
 	if (onebot11 !== void 0) out.onebot11 = onebot11;
@@ -246,6 +92,8 @@ function applyProtocolSections(raw, out) {
 	if (satori !== void 0) out.satori = satori;
 	const kurobot = parseProtocolSection(raw, "kurobot");
 	if (kurobot !== void 0) out.kurobot = kurobot;
+	const milky = parseProtocolSection(raw, "milky");
+	if (milky !== void 0) out.milky = milky;
 }
 /** 解析单个账号项（qq 必填；协议段缺省 = 不启用）。 */
 function parseAccount(item) {
@@ -297,7 +145,7 @@ function parseCliConfig(input) {
 	};
 }
 //#endregion
-//#region src/config-inline.ts
+//#region src/config/inline.ts
 /**
 * 内联配置（NAPKETTO_CONFIG_JSON，2026-10-25 嵌入式宿主契约）。
 *
@@ -307,8 +155,15 @@ function parseCliConfig(input) {
 * 内联生效时不读 / 不写 / 不校验任何 toml 文件。Windows 单环境变量上限 32767
 * 字符（约 32KB），嵌入式配置形状远小于该限（超限宿主退回文件形态）。
 *
-* 错误一概 ConfigError（exit 78 一族），文案指明来源为「内联配置」且不含任何
-* toml 文件路径。本模块不 import logger（logger.ts 反向依赖本模块判内联来源）。
+* 读取口径分两档（有意为之）：
+* - 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";
@@ -324,11 +179,31 @@ function 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 文本 → 校验后的主配置。JSON 解析失败 / 非对象 / 字段校验失败
-* 均抛 ConfigError（宿主消费 exit 78，不重试）。
+* 读内联配置文档（宽松口径：未设置 / 空串 / JSON 解析失败 / 非对象 → undefined）。
+* 供日志段等「坏配置不阻塞启动」的消费方使用。
 */
-function parseInlineConfig(text) {
+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);
@@ -336,8 +211,16 @@ function parseInlineConfig(text) {
 		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);
+	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
@@ -364,12 +247,7 @@ 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;
-	}
+	if (isInlineConfigActive()) section = readInlineConfigSection("log");
 	else try {
 		const configPath = resolveConfigPath({ dataRoot: cachedDataRoot });
 		section = parseToml(readFileSync(configPath, "utf8"))["log"];
@@ -452,381 +330,183 @@ var LazyCliLogger = class {
 /** cli 进程日志（懒构造，配置见 resolveCliLogConfig）。 */
 const logger = new LazyCliLogger();
 //#endregion
-//#region src/action-error.ts
-/**
-* CLI 动作错误出口（2026-10-25 退出码契约）：
-*   0 = 请求式优雅关停（0.2.0 已有，不经此路径）；78 = 配置校验失败
-*   （ConfigError 一族，宿主据此区分「配置未就绪」与运行时崩溃，免重启）；
-*   其余 = 1（运行时崩溃，现状不变）。
-*
-* 退出码只认错误类型（instanceof ConfigError），与日志文案完全解耦——
-* 文案是人读的，退出码是宿主消费的机器契约。
-*/
-/** 统一错误输出（结构化日志，错误对象经 pino serializer 带堆栈）。 */
-function reportError(err) {
-	let message = String(err);
-	if (err instanceof Error) {
-		const { message: errMessage } = err;
-		message = errMessage;
-	}
-	logger.error({ err }, message);
-}
-/** 统一 catch 出口：打印错误并按类型设置进程退出码（78 = 配置校验失败）。 */
-function handleActionError(err) {
-	reportError(err);
-	process.exitCode = err instanceof ConfigError ? EXIT_CONFIG_INVALID : 1;
-}
-//#endregion
-//#region src/runtime-state.ts
+//#region src/config/template.ts
 /**
-* runtime-state.ts：账号运行时状态文件 + 进程控制原语（2026-09-08 T8）。
+* 配置模板（TOML 注释版，原 config-cmds.ts 拆分，2026-08-08 FTA 优化）。
+* `config init` 与首次启动（loadCliConfig）缺失时生成。
 *
-* 跨进程通信选型（决策记录）：现有 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 重启。
+* 2026-08-08 结构拍板：**一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在
+* 账号内**（[accounts.onebot11] / [accounts.satori]）；账号必填（至少一个）。
+* dataDir 不再写死（缺省 = 项目根/.napuketto，跨平台），模板保持可移植。
 */
-/** 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;
-/**
-* 逐行转发子进程输出到父进程，过滤原生噪音。
-* 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;
-	}
-}
-/**
-* 单实例锁预检（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));
+function configTemplate() {
+	return `# ============================================================
+# NapukettoQQ 全局配置文件
+# ============================================================
+# 本文件由 \`napuketto config init\` 生成（或首次启动自动生成）。
+# 本机配置不入库（.gitignore）；修改后重启生效。
+#
+# 配置组织：一个 QQ 账号一个 [[accounts]] 段，协议与通信配置嵌在账号内
+# （[accounts.onebot11] / [accounts.satori] / [accounts.kurobot]）。账号没有写
+# 某协议段 = 该账号不启用该协议。账号必填（至少一个，qq 必填）。
+
+# ------------------------------------------------------------
+# 全局配置（跨账号）
+# ------------------------------------------------------------
+
+# 数据根目录：账号目录/日志/缓存/QQ 数据存放位置。
+# 缺省 = <项目根>/.napuketto（部署场景，跨平台，无需修改）。
+# 支持绝对路径、"~/" 前缀（用户主目录）、相对路径（相对启动目录）。
+# dataDir = ".napuketto"
+
+# 多账号（supervisor）模式下，账号进程崩溃是否自动重启
+autoRestart = true
+
+# 崩溃后自动重启的延迟（毫秒）
+restartDelayMs = 2000
+
+# ------------------------------------------------------------
+# 日志（[log]，可选——不配置即用缺省：终端 pretty 多行 / 管道 single-line）
+# ------------------------------------------------------------
+# 嵌入式宿主（把 napuketto 打进服务端等场景）推荐：
+#   [log]
+#   format = "single-line"     # 或 "json"（NDJSON，宿主按 level/module 精确路由）
+#   level = "warn"             # 控制台只留警告以上，细节进文件（配 [log.file]）
+#   banner = false
+#
+# [log]
+# format = "pretty"            # pretty | single-line | json（缺省按 TTY 自动）
+# level = "info"               # trace|debug|info|warn|error|fatal（控制台级别）
+# banner = true                # 启动字符画
+# timestamp = "local"          # local | iso8601 | elapsed
+# unboundReceive = true        # false = 未绑定频道的接收行不打（kurobot 握手后生效）
+# [log.levels]                 # 按模块覆盖级别：cli / kernel / loader / ob11
+# # loader = "debug"           # 例：终端上看接收行（默认已降 debug）
+# # ob11 = "debug"             # 例：协议校准数据（含原始 hex）
+# [log.file]                   # 独立文件 sink（可选；级别可低于控制台）
+# # path = "logs/napuketto-console.log"
+# # level = "debug"
+#
+# 环境变量覆盖（优先级高于本文件）：NAPUKETTO_LOG_LEVEL / NAPUKETTO_LOG_FORMAT /
+# NAPUKETTO_NO_BANNER（兼容旧拼写 NAPKETTO_LOG_LEVEL）。
+
+# ------------------------------------------------------------
+# 账号（至少一个，qq 必填）
+# ------------------------------------------------------------
+
+[[accounts]]
+qq = "${RESERVED_PLACEHOLDER_QINS[0]}"            # 占位值，必须替换为你的 QQ 号，否则启动报错
+enabled = true           # 是否启用（可选，缺省 true）
+
+[accounts.onebot11]      # 该账号的 OneBot 11 配置（无此段 = 不启用 OB11）
+
+# 鉴权 token（全局默认）：HTTP/WS 连接必须携带。
+#   校验方式：Authorization: Bearer <token> / 裸 token / URL 参数 ?access_token=<token>
+#   每个网络实例可单独覆盖（见下文各实例的 token 字段）。
+#   留空 = 不鉴权（仅本机调试推荐）。
+# token = ""
+
+# 心跳 meta 事件间隔（毫秒）；0 = 关闭心跳事件
+heartbeatInterval = 3000
+
+# 是否上报机器人自己发的消息（OB11 规范默认不上报）
+reportSelfMessage = false
+
+# 消息内容格式：array = 消息段数组（标准 OneBot 11），string = CQ 码字符串
+messagePostFormat = "array"
+
+# 群文件报形式：false（默认）= message 事件 + file 段（go-cqhttp 兼容）；
+# true = 群文件消息改报 group_upload notice 事件（替代 message 事件）
+groupUploadAsNotice = false
+
+# ---- HTTP 反向服务器（接收第三方 POST 指令），可配置多个 ----
+[[accounts.onebot11.httpServers]]
+enabled = true
+host = "127.0.0.1"       # 监听地址；0.0.0.0 = 监听所有网卡（局域网可连）
+port = 3000
+# token = "abc"          # 可选：覆盖全局 token
+
+# ---- HTTP 正向上报（Webhook：把事件 POST 到第三方地址），可配置多个 ----
+# [[accounts.onebot11.httpPostUrls]]
+# enabled = true
+# url = "http://127.0.0.1:8080/onebot"   # 第三方接收地址
+# token = "abc"                          # 可选：覆盖全局 token
+# timeoutMs = 5000                       # 可选：上报超时（毫秒），缺省不超时
+
+# ---- WS 反向服务器（外部 WS 客户端主动连入），可配置多个 ----
+[[accounts.onebot11.wsServers]]
+enabled = true
+host = "127.0.0.1"
+port = 3001
+# token = "abc"                          # 可选：覆盖全局 token
+# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
+
+# ---- WS 正向客户端（主动连接外部 WS，双向），可配置多个 ----
+# [[accounts.onebot11.wsReverseUrls]]
+# enabled = true
+# url = "ws://127.0.0.1:8081/ws"         # 第三方 WS 地址（ws:// 或 wss://）
+# token = "abc"                          # 可选：覆盖全局 token
+# reconnectDelayMs = 5000                # 可选：断线重连延迟（毫秒）
+# maxReconnectAttempts = 10              # 可选：最大重连次数（缺省无限）
+# rejectUnauthorized = true              # 可选：wss:// 是否校验证书（自签证书设 false）
+# heartbeatInterval = 30000              # 可选：WS ping 间隔（毫秒）
+
+# 第二个账号示例（只开 Satori）：
+# [[accounts]]
+# qq = "${RESERVED_PLACEHOLDER_QINS[1]}"
+# [accounts.satori]
+# # token = ""                           # 可选：Satori 鉴权 token
+# [[accounts.satori.httpServers]]        # HTTP RPC（POST /v1/{resource}.{method}）
+# enabled = true
+# host = "127.0.0.1"
+# port = 5500
+# [[accounts.satori.wsServers]]          # WS 事件服务（/v1/events）
+# enabled = true
+# host = "127.0.0.1"
+# port = 5501
+
+# ------------------------------------------------------------
+# KuroBot 群服互通（kurobridge-ws 客户端，MVP-3）
+# ------------------------------------------------------------
+# 账号内写 [accounts.kurobot] 段即启用；不写 = 不启用。作为 WS 客户端
+# 主动连入 KuroBot 服务端（Minecraft 服务器 kurobot 插件）。
+# QQ 群文字 ↔ 游戏聊天双向互通；群命令（前缀开头）→ 游戏命令。
+# [accounts.kurobot]
+# url = "ws://127.0.0.1:25580"           # 必填：KuroBot 服务端地址（ws:// 或 wss://）
+# # token = ""                           # 可选：鉴权 token（服务端配了则必填，错 token 拒连）
+# # client = "napukettoqq"               # 可选：自报身份（缺省 napukettoqq/<版本>）
+# # commandPrefix = "/"                  # 可选：群命令前缀
+# # pingIntervalMs = 15000               # 可选：应用层心跳间隔（毫秒，须 < 30000）
+# # chatTemplate = "[{player}] {content}"    # 游戏聊天渲染模板
+# # joinTemplate = "{player} 加入了服务器"    # 玩家进服模板
+
+# ------------------------------------------------------------
+# Milky 协议（P0）
+# ------------------------------------------------------------
+# 账号内写 [accounts.milky] 段且 enabled = true 即启用；不写 = 不启用。
+# 单端口 HTTP：POST /api/:api 调用动作 + GET /event 事件推送（SSE / WS）。
+# [accounts.milky]
+# enabled = true                         # 启用开关（false = 不生效）
+# host = "127.0.0.1"                     # 监听地址
+# port = 3001                            # 监听端口（/api 与 /event 同端口）
+# # token = ""                           # 可选：access_token（空 = 不校验，仅限内网）
+# # eventModes = ["sse", "ws"]           # /event 允许的连接形态
+# # webhooks = []                        # 可选：额外事件推送地址（WebHook POST）
+# # cacheDir = "cache"                   # 可选：发送远程媒体 URI 的下载缓存目录
+# # 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 {
@@ -863,6 +543,23 @@ async function loadCliConfig(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;
 /**
@@ -872,9 +569,9 @@ let sourceLogged = false;
 * 同为 ConfigError（exit 78），文案区别只在来源标注。
 */
 async function loadCliConfigWithSource(opts = {}) {
-	const inlineText = readInlineConfigText();
-	if (inlineText !== void 0) {
-		const config = parseInlineConfig(inlineText);
+	const resolved = resolveCliConfigSource(opts);
+	if (resolved.source === "inline") {
+		const config = parseInlineConfig(resolved.text);
 		if (!sourceLogged) {
 			sourceLogged = true;
 			logger.info("配置来源: inline（NAPKETTO_CONFIG_JSON）");
@@ -884,14 +581,14 @@ async function loadCliConfigWithSource(opts = {}) {
 			source: "inline"
 		};
 	}
-	const dataRoot = resolveDataRoot(opts.dataDir);
-	const configPath = resolveConfigPath({ dataRoot });
 	return {
-		config: await loadCliConfig(dataRoot),
+		config: await loadCliConfig(resolved.dataRoot),
 		source: "file",
-		path: configPath
+		path: resolved.path
 	};
 }
+//#endregion
+//#region src/commands/config.ts
 /** CliConfig → 普通对象（smol-toml stringify 入参）。 */
 function toRecord(config) {
 	return config;
@@ -1013,36 +710,146 @@ async function validateConfigFile(path, dataRoot) {
 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);
+		await validateConfigFile(configPath, resolveDataRoot(opts.dataDir));
 		return {
 			source: "file",
 			path: configPath
 		};
 	}
-	const inlineText = readInlineConfigText();
-	if (inlineText !== void 0) {
-		parseInlineConfig(inlineText);
+	const resolved = resolveCliConfigSource(opts);
+	if (resolved.source === "inline") {
+		parseInlineConfig(resolved.text);
 		return { source: "inline" };
 	}
-	const path = resolveConfigPath({ dataRoot });
-	await validateConfigFile(path, dataRoot);
+	await validateConfigFile(resolved.path, resolved.dataRoot);
 	return {
 		source: "file",
-		path
+		path: resolved.path
 	};
 }
 //#endregion
-//#region src/ops-commands.ts
+//#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/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`。
@@ -1122,57 +929,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);
-		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);
+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;
+	}
+}
+/**
+* 单实例锁预检（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();
+		});
+	});
 }
-/** 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/）");
+/** 启动单个账号（自建宿主 + 常驻）。 */
+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 自建宿主唯一）
 *
@@ -1183,8 +1227,6 @@ async function cmdRestart(dataRoot, opts) {
 *   - 守护：账号异常退出且 autoRestart → 延迟重启
 *   - 信号转发：SIGINT/SIGTERM → 停止全部子进程 → 父进程退出
 */
-/** 默认重启延迟（毫秒）。 */
-const DEFAULT_RESTART_DELAY_MS = 2e3;
 /** 退出轮询间隔（毫秒）。 */
 const EXIT_POLL_MS = 100;
 /** 子进程优雅退出时限（毫秒）：哨兵/信号后子进程自行停止，超时强杀兜底。 */
@@ -1368,35 +1410,13 @@ 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 配置结构拍板：账号必填，协议配置嵌在账号内）
-*
-* 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 统一出口）
+* 默认动作（无子命令）用例：-q 单账号 / 多 -q supervisor / 无 -q 读配置拉起全部账号。
 *
-* 路线 B（拉起 QQ + 注入）已淘汰（2026-08-07 用户拍板），相关入口已移除。
+* 从 index.ts 拆出（2026-10-25 模块收拢）：这里只做编排，不 import commander；
+* 参数解析、帮助文案与退出码收敛在 cli/program.ts。
 */
-/** commander collect：累积 -q 多值。 */
-function collectQq(value, prev) {
-	prev.push(value);
-	return prev;
-}
-/** 启动字符画（NapukettoQQ 品牌标识，内嵌；art 含反引号/反斜杠，用数组逐行转义）。 */
-const BANNER = [
-	"    _   __                  __        __  __        ____  ____ ",
-	"   / | / /___ _____  __  __/ /_____  / /_/ /_____  / __ \\/ __ \\",
-	"  /  |/ / __ `/ __ \\/ / / / //_/ _ \\/ __/ __/ __ \\/ / / / / / /",
-	" / /|  / /_/ / /_/ / /_/ / ,< /  __/ /_/ /_/ /_/ / /_/ / /_/ / ",
-	"/_/ |_/\\__,_/ .___/\\__,_/_/|_|\\___/\\__/\\__/\\____/\\___\\_\\___\\_\\ ",
-	"           /_/                                                 "
-].join("\n");
 /** 构造可选 dataDir 参数（exactOptionalPropertyTypes 不允许显式 undefined）。 */
 function withDataDir(dataDir) {
 	if (dataDir === void 0) return {};
@@ -1412,9 +1432,100 @@ 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（运行时崩溃，现状不变）。
+*
+* 退出码只认错误类型（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) {
+	prev.push(value);
+	return prev;
+}
+/** 启动字符画（NapukettoQQ 品牌标识，内嵌；art 含反引号/反斜杠，用数组逐行转义）。 */
+const BANNER = [
+	"    _   __                  __        __  __        ____  ____ ",
+	"   / | / /___ _____  __  __/ /_____  / /_/ /_____  / __ \\/ __ \\",
+	"  /  |/ / __ `/ __ \\/ / / / //_/ _ \\/ __/ __/ __ \\/ / / / / / /",
+	" / /|  / /_/ / /_/ / /_/ / ,< /  __/ /_/ /_/ /_/ / /_/ / /_/ / ",
+	"/_/ |_/\\__,_/ .___/\\__,_/_/|_|\\___/\\__/\\__/\\____/\\___\\_\\___\\_\\ ",
+	"           /_/                                                 "
+].join("\n");
 /** 读主命令已解析的 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) {
@@ -1457,7 +1568,7 @@ function registerConfigCommands(program) {
 function registerSupervisorCommand(program) {
 	program.command("supervisor").description("多账号编排（读全局配置 accounts 拉起子进程）").action(async () => {
 		try {
-			await runSupervisor(rootDataDir(program));
+			await runSupervisorCommand(rootDataDir(program));
 		} catch (err) {
 			handleActionError(err);
 		}
@@ -1479,45 +1590,6 @@ function registerOpsCommands(program) {
 	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;
-	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)
-	});
-}
 /** 注册主命令 action（-q 单账号 / 多 -q supervisor / 无 -q 读配置 supervisor 拉起）。 */
 function registerMainAction(program) {
 	program.action(async (opts) => {
@@ -1542,6 +1614,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 {};