@napuketto/loader 0.0.38 → 0.1.0

package/dist/host/self-host.cjs

@@ -227,6 +227,111 @@ function registerLockCleanup(dataDir) {
 	});
 }
 //#endregion
+//#region src/shutdown.ts
+/**
+* 优雅关停（2026-10-25 生命周期契约）：停止哨兵 + 关停钩子 + 信号接入。
+*
+* 背景：Windows 下 SIGTERM 无法投递给无控制台进程（嵌入式宿主 pipe 场景），
+* 既有 `napuketto stop` / 宿主只能 taskkill /T /F 树杀——被杀进程退出码 1，
+* 与真实崩溃无法区分。本模块提供两层机制，三层常驻进程
+* （supervisor / cli boot / self-host）共用：
+*
+* 1. 停止哨兵（规范化通道，宿主零 win32 依赖）：向 `<数据根>/napuketto.stop`
+*    写文件即请求该数据根下的进程树优雅退出。文件内容为目标账号
+*    （空 / "all" = 全部；"<uin>" = 单账号——`napuketto stop -q` 用）。
+*    守卫：mtime 晚于进程启动才触发（陈旧哨兵不触发，守护重启不误杀），
+*    每进程至多触发一次。轮询 500ms（fs.watch 跨平台创建事件不可靠）。
+* 2. 信号（终端场景）：SIGINT/SIGTERM/SIGBREAK（Windows CTRL_BREAK_EVENT
+*    可达）→ requestShutdown，走同一关停编排。
+*
+* 退出码契约：0 = 请求式正常退出；非 0 = 引导失败/运行时致命。taskkill /F
+* 兜底仍产出 code 1，宿主应优先用哨兵通道。
+*/
+/** 哨兵文件名（置于数据根）。 */
+const STOP_SENTINEL_FILENAME = "napuketto.stop";
+/** 哨兵轮询间隔（毫秒）。 */
+const SENTINEL_POLL_MS = 500;
+/** 哨兵文件路径。 */
+function stopSentinelPath(dataRoot) {
+	return (0, node_path.join)(dataRoot, STOP_SENTINEL_FILENAME);
+}
+/** 哨兵内容是否命中本观察者（all/空 = 全部；否则精确匹配账号）。 */
+function sentinelMatches(content, account) {
+	const trimmed = content.trim();
+	if (trimmed === "" || trimmed === "all") return true;
+	return account !== void 0 && trimmed === account;
+}
+/**
+* 观察停止哨兵：存在、mtime 晚于进程启动且内容命中 → onTrigger（一次性）。
+* 返回取消函数。mtime 守卫：进程启动前遗留的哨兵不触发（守护重启安全）。
+*/
+function watchStopSentinel(opts) {
+	const path = stopSentinelPath(opts.dataRoot);
+	const processStartMs = performance.timeOrigin;
+	let triggered = false;
+	const timer = setInterval(() => {
+		if (triggered) return;
+		let mtimeMs = 0;
+		let content = "";
+		try {
+			if (!(0, node_fs.existsSync)(path)) return;
+			mtimeMs = (0, node_fs.statSync)(path).mtimeMs;
+			content = (0, node_fs.readFileSync)(path, "utf8");
+		} catch {
+			return;
+		}
+		if (mtimeMs <= processStartMs) return;
+		if (sentinelMatches(content, opts.account)) {
+			triggered = true;
+			opts.onTrigger();
+		}
+	}, opts.pollMs ?? SENTINEL_POLL_MS);
+	timer.unref?.();
+	return () => {
+		triggered = true;
+		clearInterval(timer);
+	};
+}
+const shutdownHooks = [];
+let shutdownStarted = false;
+/** 注册关停钩子（按注册逆序执行）。 */
+function registerShutdownHook(hook) {
+	if (!shutdownStarted) shutdownHooks.push(hook);
+}
+/**
+* 执行关停编排：逆序跑全部钩子（单钩子异常不阻断后续）后 exit 0。
+* 幂等（重复调用只跑一次）。退出码 0 = 请求式正常退出（生命周期契约）。
+*/
+async function requestShutdown(reason) {
+	if (shutdownStarted) return;
+	shutdownStarted = true;
+	node_process.default.stdout.write(`[self-host] 优雅关停：${reason}\n`);
+	while (shutdownHooks.length > 0) {
+		const hook = shutdownHooks.pop();
+		if (hook === void 0) break;
+		try {
+			await hook();
+		} catch (err) {
+			const message = err?.message ?? String(err);
+			node_process.default.stdout.write(`[self-host] 关停钩子异常（继续）: ${message}\n`);
+		}
+	}
+	node_process.default.exit(0);
+}
+/**
+* 信号接入（SIGINT/SIGTERM/SIGBREAK → requestShutdown）。
+* Windows CTRL_BREAK_EVENT 以 SIGBREAK 到达（宿主 CREATE_NEW_PROCESS_GROUP +
+* GenerateConsoleCtrlEvent 可优雅停整树）；终端 Ctrl+C 以 SIGINT 到达。
+*/
+function installSignalShutdown() {
+	const handler = (signal) => {
+		requestShutdown(`信号 ${signal}`);
+	};
+	node_process.default.on("SIGINT", () => handler("SIGINT"));
+	node_process.default.on("SIGTERM", () => handler("SIGTERM"));
+	node_process.default.on("SIGBREAK", () => handler("SIGBREAK"));
+}
+//#endregion
 //#region src/host/env.ts
 /**
 * env.ts：引导进程环境变量访问层（2026-08-07 阶段 2）。
@@ -269,7 +374,9 @@ const env = {
 	/** 全局 TOML 配置显式路径（优先级最高）。 */
 	NAPKETTO_CONFIG: process.env["NAPKETTO_CONFIG"],
 	/** 数据根（kernel 数据目录，cleanCache 用）。 */
-	NAPKETTO_DATA: process.env["NAPKETTO_DATA"]
+	NAPKETTO_DATA: process.env["NAPKETTO_DATA"],
+	/** 数据根（launcher 注入，停止哨兵目录解析用）。 */
+	NAPUTO_DATA_ROOT: process.env["NAPUTO_DATA_ROOT"]
 };
 //#endregion
 //#region src/host/util.ts
@@ -1206,6 +1313,48 @@ function handleControl(payload, onExit, onLogin) {
 	});
 }
 //#endregion
+//#region src/host/log-cfg.ts
+/**
+* loader 引导链日志配置解析（2026-10-25 日志可配置化）。
+*
+* 自建宿主进程（self-host → bootstrap → NapukettoCore / kernel-services）不经过
+* cli 的 loadCliConfig，这里按同一契约解析：读全局 TOML（路径优先级与
+* loadProtocolSections 一致：NAPKETTO_CONFIG > NAPUTO_CFG_DIR 兜底）的 [log] 段，
+* 经 kernel.parseLogConfig（env 覆盖在内）解析。kernel 无该导出（老版本）或
+* 配置读取失败时回退缺省——日志配置损坏不阻塞引导。
+*/
+/** 缺省（kernel parseLogConfig 缺省值的最小面镜像；未配置/解析失败兜底）。 */
+function defaultLogConfig() {
+	return {
+		level: "info",
+		banner: true,
+		timestamp: "local",
+		unboundReceive: true,
+		levels: {}
+	};
+}
+/** 解析引导链日志配置（toml [log] 段 + env 覆盖；失败回退缺省）。 */
+function resolveLoaderLogConfig(kernel) {
+	if (typeof kernel.parseLogConfig !== "function") return defaultLogConfig();
+	const cfgFile = env.NAPKETTO_CONFIG || (0, node_path.join)(env.NAPUTO_CFG_DIR || ".", "napuketto.toml");
+	try {
+		const parsed = kernel.parseToml((0, node_fs.readFileSync)(cfgFile, "utf8"));
+		return kernel.parseLogConfig(parsed["log"], process.env);
+	} catch {
+		return defaultLogConfig();
+	}
+}
+/** [log.file] 相对路径展开基准（数据根：NAPUTO_DATA_ROOT > NAPKETTO_DATA > CFG_DIR 父目录）。 */
+function logFileBaseDir() {
+	if (env.NAPUTO_DATA_ROOT !== void 0 && env.NAPUTO_DATA_ROOT !== "") return env.NAPUTO_DATA_ROOT;
+	if (env.NAPKETTO_DATA !== void 0 && env.NAPKETTO_DATA !== "") return env.NAPKETTO_DATA;
+	return env.NAPUTO_CFG_DIR !== void 0 && env.NAPUTO_CFG_DIR !== "" ? (0, node_path.join)(env.NAPUTO_CFG_DIR, "..") : ".";
+}
+/** [log.file] path → 绝对路径。 */
+function resolveLogFilePath(path) {
+	return (0, node_path.isAbsolute)(path) ? path : (0, node_path.join)(logFileBaseDir(), path);
+}
+//#endregion
 //#region src/host/core/login.ts
 /** 打印可用快速登录账号 + 返回目标账号（启动横幅）。forcedUin（cli `-q` / NAPUTO_QUICK_UIN）优先。 */
 async function pickLoginAccount(kernel, ctx, loginResultRef, forcedUin) {
@@ -1351,7 +1500,7 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 			groupChannel: services.groupChannel,
 			friendChannel: services.friendChannel,
 			buddyCacheEvents: services.buddyCache?.events,
-			logger: services.logger,
+			logger: services.calibLogger,
 			msgApi: services.msgApi,
 			groupApi: services.groupApi,
 			groupNotifyApi: services.groupNotifyApi,
@@ -1420,6 +1569,7 @@ async function assembleOb11AndSatori(kernel, services, loginResult) {
 				msgChannel: channel,
 				msgApi: services.msgApi,
 				self: services.self,
+				receiveFilter: services.receiveFilter,
 				logger: services.logger
 			});
 			await kurobot.start();
@@ -1471,21 +1621,29 @@ function formatMessageLog(kernel, msg) {
 	const content = rendered.replace(/\n/g, "\n    ");
 	return {
 		plain: `接收 <- ${kind} ${plainTags}： ${content}`,
-		colored: `${ANSI.gray}loader | 接收 <- ${kind}${ANSI.reset} ${coloredTags}： ${content}`
+		colored: `${ANSI.gray}loader | 接收 <- ${kind}${ANSI.reset} ${coloredTags}： ${content}`,
+		isGroup,
+		peerUin
 	};
 }
 /**
 * 消息日志订阅（onRecvMsg 回调参数为消息数组——2026-08-07 运行时实证，遍历逐条打印）。
 * 返回退订函数（软重登重装配时清理旧订阅，2026-09-08）；通道返回面宽松
 * （EventChannelLike.on 返回 unknown），非函数时退化为 no-op。
+*
+* 2026-10-25 级别重分配：接收行 info → debug（运行状态无信息量的高频行；
+* 终端要看配 [log.levels] loader = "debug"）。
 */
-function setupMsgLogging(kernel, channel, logger, colorize) {
+function setupMsgLogging(kernel, channel, logger, colorize, receiveFilter) {
 	const off = channel.on("Msg/onRecvMsg", (msgs) => {
 		forEachRawMessage(msgs, (m) => {
 			try {
-				const { plain, colored } = formatMessageLog(kernel, m);
+				const { plain, colored, isGroup, peerUin } = formatMessageLog(kernel, m);
+				if (receiveFilter?.current !== null && receiveFilter !== void 0) {
+					if (!receiveFilter.current(peerUin, isGroup)) return;
+				}
 				log(plain);
-				logger?.info(colorize ? colored : plain);
+				logger?.debug(colorize ? colored : plain);
 			} catch (e) {
 				const line2 = `接收消息（解析失败: ${errMsg(e)}）`;
 				log(line2);
@@ -1504,15 +1662,37 @@ function setupMsgLogging(kernel, channel, logger, colorize) {
 * IPC 模式（koishi 插件）经此拿服务装配 ipc-server；非 IPC（cli）经此拿服务
 * 装配 OB11/Satori 适配器。
 */
+/** 静默 logger（kernel.createLogger 不可用时的兜底）。 */
+const NOOP_LOGGER = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+/** loader logger 构造参数（[log] 段 + IPC/文件路径折叠；直传 undefined，免条件展开）。 */
+function buildLoaderLoggerOptions(logCfg, consoleEnabled, logFile, account) {
+	const cfg = logCfg ?? defaultLogConfig();
+	return {
+		console: consoleEnabled,
+		file: logFile,
+		fileLevel: cfg.file?.level,
+		level: cfg.levels.loader ?? cfg.level,
+		format: cfg.format,
+		timestamp: cfg.timestamp,
+		colorize: cfg.colorize,
+		base: {
+			name: "loader",
+			account
+		}
+	};
+}
 /** 登录成功后创建 kernel 业务服务（channel/bridge/cache/apis）。失败返回 null。 */
-async function createKernelServices(kernel, ctx, loginResult) {
+async function createKernelServices(kernel, ctx, loginResult, logCfg) {
 	const ipcMode = env.NAPUTO_IPC === "1";
-	const logFile = env.NAPUTO_CFG_DIR !== void 0 ? (0, node_path.join)(env.NAPUTO_CFG_DIR, "logs", "loader.log") : (0, node_path.join)((0, node_os.tmpdir)(), "napuketto-loader.log");
-	const logger = kernel.createLogger?.({
-		console: !ipcMode,
-		file: logFile,
-		base: { name: "loader" }
-	});
+	const logFile = logCfg?.file !== void 0 ? resolveLogFilePath(logCfg.file.path) : env.NAPUTO_CFG_DIR !== void 0 ? (0, node_path.join)(env.NAPUTO_CFG_DIR, "logs", "loader.log") : (0, node_path.join)((0, node_os.tmpdir)(), "napuketto-loader.log");
+	const logger = kernel.createLogger?.(buildLoaderLoggerOptions(logCfg, !ipcMode, logFile, loginResult.uin));
+	const ob11Level = logCfg?.levels.ob11;
+	const calibLogger = logger !== void 0 && typeof logger.child === "function" ? ob11Level !== void 0 ? logger.child({ module: "ob11" }, { level: ob11Level }) : logger.child({ module: "ob11" }) : logger;
 	const session = ctx.session;
 	if (!session) {
 		log("bootstrap: session 为空，无法创建 kernel 服务");
@@ -1521,7 +1701,8 @@ async function createKernelServices(kernel, ctx, loginResult) {
 	const channel = new kernel.NTEventChannel("Msg");
 	const bridge = new kernel.MsgBridge(session, channel);
 	bridge.register();
-	const offMsgLogging = setupMsgLogging(kernel, channel, logger, !ipcMode);
+	const receiveFilter = { current: null };
+	const offMsgLogging = setupMsgLogging(kernel, channel, logger, !ipcMode && (logCfg?.colorize ?? true), logCfg?.unboundReceive === false ? receiveFilter : void 0);
 	const groupApi = new kernel.GroupApi(session);
 	const util = ctx.exports?.NodeQQNTWrapperUtil;
 	const msgApi = new kernel.MsgApi(session, channel, util);
@@ -1581,6 +1762,8 @@ async function createKernelServices(kernel, ctx, loginResult) {
 			uin: loginResult.uin,
 			nickname: loginResult.nick ?? ""
 		},
+		calibLogger: calibLogger ?? NOOP_LOGGER,
+		receiveFilter,
 		session,
 		engine: ctx.engine,
 		util: ctx.exports?.NodeQQNTWrapperUtil,
@@ -1611,10 +1794,11 @@ async function createKernelServices(kernel, ctx, loginResult) {
 *
 * 返回 null = 服务未装配（session 缺失 / OB11/Satori 装配失败）——调用方据此判
 * 引导失败。env 未注入 adapter/network 入口时「跳过装配」仍返回服务（合法运行形态，
-* 如纯 kernel 探测），不算失败。
+* 如纯 kernel 探测），不算失败。logCfg 为日志配置（loader logger 构造与接收行
+* 过滤用，2026-10-25）。
 */
-async function startProtocols(kernel, ctx, loginResult) {
-	const services = await createKernelServices(kernel, ctx, loginResult);
+async function startProtocols(kernel, ctx, loginResult, logCfg) {
+	const services = await createKernelServices(kernel, ctx, loginResult, logCfg);
 	if (services === null) return null;
 	if (env.NAPUTO_IPC === "1") {
 		log("bootstrap: IPC 模式，跳过 OB11/Satori 装配（koishi 插件直接消费 kernel 服务）");
@@ -2155,17 +2339,30 @@ function runProbePhase(kernel, ctx) {
 		log(`bootstrap: probe error: ${errMsg(e)}`);
 	}
 }
+/** NapukettoCore.create 选项（[log] 段 + env 折叠；IPC 模式关 console）。 */
+function buildCoreCreateOptions(logCfg, bootEnv) {
+	return {
+		paths: { dataRoot: bootEnv.dataDir },
+		logLevel: logCfg.levels.kernel ?? logCfg.level,
+		...logCfg.format !== void 0 ? { logFormat: logCfg.format } : {},
+		...logCfg.timestamp !== void 0 ? { logTimestamp: logCfg.timestamp } : {},
+		...logCfg.colorize !== void 0 ? { logColorize: logCfg.colorize } : {},
+		...logCfg.file !== void 0 ? {
+			logFile: resolveLogFilePath(logCfg.file.path),
+			logFileLevel: logCfg.file.level
+		} : {},
+		...env.NAPUTO_QUICK_UIN !== void 0 ? { account: env.NAPUTO_QUICK_UIN } : {},
+		...env.NAPUTO_IPC === "1" ? { consoleLog: false } : {}
+	};
+}
 /** NapukettoCore 装配路径：create → attachWrapper → 登录 → 激活 → 协议 → 探测。
 * @returns 引导是否完整完成（协议服务装配成功 = true；登录失败/服务装配失败等
 *   静默收敛为 false，具体原因见 napuketto-boot.log）。 */
 async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
+	const logCfg = resolveLoaderLogConfig(kernel);
 	const coreCtor = kernel.NapukettoCore;
 	if (coreCtor === void 0) return false;
-	const core = coreCtor.create({
-		paths: { dataRoot: bootEnv.dataDir },
-		logLevel: "info",
-		...env.NAPUTO_IPC === "1" ? { consoleLog: false } : {}
-	});
+	const core = coreCtor.create(buildCoreCreateOptions(logCfg, bootEnv));
 	let ipcActions = null;
 	const preempt = { resolve: null };
 	const preemptLogin = new Promise((resolve) => {
@@ -2192,6 +2389,7 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 	let services = null;
 	let stopIpcServices = null;
 	let stopOb11Bridge = null;
+	let shutdownHooksRegistered = false;
 	/**
 	* 装配链尾部（登录成功后；初次引导与软重登共用）。
 	* @returns 装配是否成功（协议服务未装配 = false，调用方判引导失败）。
@@ -2202,7 +2400,7 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 		await waitSessionReady(kernel, ctx);
 		if (env.NAPUTO_IPC === "1") sendStatus("sessioning");
 		if (initial) await runSmokeIfEnabled(kernel, ctx, loginResult);
-		const newServices = await startProtocols(kernel, ctx, loginResult);
+		const newServices = await startProtocols(kernel, ctx, loginResult, logCfg);
 		if (newServices === null) {
 			log("bootstrap: 协议服务装配失败，引导中止");
 			return false;
@@ -2212,6 +2410,19 @@ async function bootstrapWithCore(kernel, state, bootEnv, Appid) {
 			stopOb11Bridge = await attachOb11IpcBridge(ipcActions, newServices);
 		}
 		services = newServices;
+		if (!shutdownHooksRegistered) {
+			shutdownHooksRegistered = true;
+			registerShutdownHook(() => {
+				services?.dispose();
+			});
+			registerShutdownHook(() => {
+				stopIpcServices?.();
+				stopOb11Bridge?.();
+			});
+			registerShutdownHook(() => {
+				return services?.stopAdapters?.();
+			});
+		}
 		return true;
 	};
 	/**
@@ -2422,6 +2633,17 @@ async function bootstrap(state) {
 *     → kernel 装配 → 登录（快速/QR）→ session（先 init 后 start）→ 冒烟 → 协议装配
 */
 const state = createState();
+installSignalShutdown();
+{
+	const dataRoot = env.NAPUTO_DATA_ROOT;
+	if (dataRoot !== void 0 && dataRoot !== "") watchStopSentinel({
+		dataRoot,
+		account: env.NAPUTO_CFG_DIR !== void 0 && env.NAPUTO_CFG_DIR !== "" ? env.NAPUTO_CFG_DIR.split(/[\\/]/).filter(Boolean).pop() ?? "default" : "default",
+		onTrigger: () => {
+			requestShutdown("停止哨兵");
+		}
+	});
+}
 const ipcMode = env.NAPUTO_IPC === "1";
 if (ipcMode) {
 	enableIpc();

package/dist/index.cjs

@@ -209,11 +209,13 @@ const IpcMessageSchema = zod.z.discriminatedUnion("type", [
 *    失败的加载警告（无害，纯噪音）
 *  - `loaded [mmkv.*] with N key-values`：MMKV 初始化完成行（野生日志，风格三，
 *    无统一前缀/时间戳，过滤）
+*  - `:N::loadFromFile> loading [mmkv.*] with crc`：MMKV 载入变体行
+*    （2026-10-25 补：`loading` 拼写与 `loaded` 并存，此前漏过滤外泄到宿主控制台）
 *
 * 边界：只处理「整条」噪音行；原生输出插进 JSON 协议行字节中间的撕裂不归这里管
 * （IPC 路径由 status 重播与脏行诊断兜底，见 ipc-sender.ts / koishi 插件 client）。
 */
-const NATIVE_NOISE = /<MMKV|<MemoryFile_Win32|<MMKV_IO|loadSymbolFromShell|getNodeGetJsListApi|get symbol failed|loaded \[mmkv/i;
+const NATIVE_NOISE = /<MMKV|<MemoryFile_Win32|<MMKV_IO|loadSymbolFromShell|getNodeGetJsListApi|get symbol failed|loaded \[mmkv|loadFromFile> loading \[mmkv/i;
 /** IPC 协议行前缀（encodeIpcMessage 走 JSON.stringify 无空白，前缀恒定）。 */
 const IPC_LINE_PREFIX = `{"v":1`;
 /**
@@ -1121,7 +1123,8 @@ function buildLaunchEnv(options, useWine) {
 		...options.configPath !== void 0 ? { [ENV.CONFIG_PATH]: p((0, node_path.resolve)(options.configPath)) } : {},
 		...options.quickUin !== void 0 ? { [ENV.QUICK_UIN]: options.quickUin } : {},
 		...options.qrOnly === true ? { [ENV.QR_ONLY]: "1" } : {},
-		...options.ipc === true ? { [ENV.IPC]: "1" } : {}
+		...options.ipc === true ? { [ENV.IPC]: "1" } : {},
+		...options.extraEnv !== void 0 ? options.extraEnv : {}
 	};
 	return {
 		...env,
@@ -1150,7 +1153,9 @@ const ENV = {
 	/** 强制扫码登录（跳过快速登录直接 QR；koishi 面板「扫码登录」重启路径用）。 */
 	QR_ONLY: "NAPUTO_QR_ONLY",
 	/** IPC 子进程模式（koishi 插件驱动：stdout JSON 行 + stdin action/control）。 */
-	IPC: "NAPUTO_IPC"
+	IPC: "NAPUTO_IPC",
+	/** 数据根（cli 注入：停止哨兵目录解析用，self-host 不再从 CFG_DIR 反推）。 */
+	DATA_ROOT: "NAPUTO_DATA_ROOT"
 };
 //#endregion
 //#region src/locate-qq.ts
@@ -1394,6 +1399,125 @@ async function ensureQqFiles(options = {}) {
 	}
 }
 //#endregion
+//#region src/shutdown.ts
+/**
+* 优雅关停（2026-10-25 生命周期契约）：停止哨兵 + 关停钩子 + 信号接入。
+*
+* 背景：Windows 下 SIGTERM 无法投递给无控制台进程（嵌入式宿主 pipe 场景），
+* 既有 `napuketto stop` / 宿主只能 taskkill /T /F 树杀——被杀进程退出码 1，
+* 与真实崩溃无法区分。本模块提供两层机制，三层常驻进程
+* （supervisor / cli boot / self-host）共用：
+*
+* 1. 停止哨兵（规范化通道，宿主零 win32 依赖）：向 `<数据根>/napuketto.stop`
+*    写文件即请求该数据根下的进程树优雅退出。文件内容为目标账号
+*    （空 / "all" = 全部；"<uin>" = 单账号——`napuketto stop -q` 用）。
+*    守卫：mtime 晚于进程启动才触发（陈旧哨兵不触发，守护重启不误杀），
+*    每进程至多触发一次。轮询 500ms（fs.watch 跨平台创建事件不可靠）。
+* 2. 信号（终端场景）：SIGINT/SIGTERM/SIGBREAK（Windows CTRL_BREAK_EVENT
+*    可达）→ requestShutdown，走同一关停编排。
+*
+* 退出码契约：0 = 请求式正常退出；非 0 = 引导失败/运行时致命。taskkill /F
+* 兜底仍产出 code 1，宿主应优先用哨兵通道。
+*/
+/** 哨兵文件名（置于数据根）。 */
+const STOP_SENTINEL_FILENAME = "napuketto.stop";
+/** 哨兵轮询间隔（毫秒）。 */
+const SENTINEL_POLL_MS = 500;
+/** 哨兵文件路径。 */
+function stopSentinelPath(dataRoot) {
+	return (0, node_path.join)(dataRoot, STOP_SENTINEL_FILENAME);
+}
+/**
+* 写停止哨兵（请求优雅关停）。target = "all"/空 = 全部账号；"<uin>" = 单账号。
+* 任何内容（含空）都视为请求；mtime 由写入时刻决定。
+*/
+function writeStopSentinel(dataRoot, target) {
+	(0, node_fs.writeFileSync)(stopSentinelPath(dataRoot), target === "all" ? "all\n" : `${target}\n`, "utf8");
+}
+/** 删除停止哨兵（napuketto stop 等待结束后清理，防陈旧文件累积）。 */
+function removeStopSentinel(dataRoot) {
+	const path = stopSentinelPath(dataRoot);
+	if ((0, node_fs.existsSync)(path)) try {
+		(0, node_fs.rmSync)(path);
+	} catch {}
+}
+/** 哨兵内容是否命中本观察者（all/空 = 全部；否则精确匹配账号）。 */
+function sentinelMatches(content, account) {
+	const trimmed = content.trim();
+	if (trimmed === "" || trimmed === "all") return true;
+	return account !== void 0 && trimmed === account;
+}
+/**
+* 观察停止哨兵：存在、mtime 晚于进程启动且内容命中 → onTrigger（一次性）。
+* 返回取消函数。mtime 守卫：进程启动前遗留的哨兵不触发（守护重启安全）。
+*/
+function watchStopSentinel(opts) {
+	const path = stopSentinelPath(opts.dataRoot);
+	const processStartMs = performance.timeOrigin;
+	let triggered = false;
+	const timer = setInterval(() => {
+		if (triggered) return;
+		let mtimeMs = 0;
+		let content = "";
+		try {
+			if (!(0, node_fs.existsSync)(path)) return;
+			mtimeMs = (0, node_fs.statSync)(path).mtimeMs;
+			content = (0, node_fs.readFileSync)(path, "utf8");
+		} catch {
+			return;
+		}
+		if (mtimeMs <= processStartMs) return;
+		if (sentinelMatches(content, opts.account)) {
+			triggered = true;
+			opts.onTrigger();
+		}
+	}, opts.pollMs ?? SENTINEL_POLL_MS);
+	timer.unref?.();
+	return () => {
+		triggered = true;
+		clearInterval(timer);
+	};
+}
+const shutdownHooks = [];
+let shutdownStarted = false;
+/** 注册关停钩子（按注册逆序执行）。 */
+function registerShutdownHook(hook) {
+	if (!shutdownStarted) shutdownHooks.push(hook);
+}
+/**
+* 执行关停编排：逆序跑全部钩子（单钩子异常不阻断后续）后 exit 0。
+* 幂等（重复调用只跑一次）。退出码 0 = 请求式正常退出（生命周期契约）。
+*/
+async function requestShutdown(reason) {
+	if (shutdownStarted) return;
+	shutdownStarted = true;
+	node_process.default.stdout.write(`[self-host] 优雅关停：${reason}\n`);
+	while (shutdownHooks.length > 0) {
+		const hook = shutdownHooks.pop();
+		if (hook === void 0) break;
+		try {
+			await hook();
+		} catch (err) {
+			const message = err?.message ?? String(err);
+			node_process.default.stdout.write(`[self-host] 关停钩子异常（继续）: ${message}\n`);
+		}
+	}
+	node_process.default.exit(0);
+}
+/**
+* 信号接入（SIGINT/SIGTERM/SIGBREAK → requestShutdown）。
+* Windows CTRL_BREAK_EVENT 以 SIGBREAK 到达（宿主 CREATE_NEW_PROCESS_GROUP +
+* GenerateConsoleCtrlEvent 可优雅停整树）；终端 Ctrl+C 以 SIGINT 到达。
+*/
+function installSignalShutdown() {
+	const handler = (signal) => {
+		requestShutdown(`信号 ${signal}`);
+	};
+	node_process.default.on("SIGINT", () => handler("SIGINT"));
+	node_process.default.on("SIGTERM", () => handler("SIGTERM"));
+	node_process.default.on("SIGBREAK", () => handler("SIGBREAK"));
+}
+//#endregion
 exports.DownloadError = DownloadError;
 exports.ENV = ENV;
 exports.INSTANCE_LOCK_FILE = INSTANCE_LOCK_FILE;
@@ -1410,6 +1534,7 @@ exports.IpcResultPayloadSchema = IpcResultPayloadSchema;
 exports.IpcStatusPayloadSchema = IpcStatusPayloadSchema;
 exports.QQ_FILES_DIR_NAME = QQ_FILES_DIR_NAME;
 exports.QqReleasesError = QqReleasesError;
+exports.STOP_SENTINEL_FILENAME = STOP_SENTINEL_FILENAME;
 exports.WIN_NODE_DIR_NAME = WIN_NODE_DIR_NAME;
 exports.acquireInstanceLock = acquireInstanceLock;
 exports.buildSpawnCommand = buildSpawnCommand;
@@ -1423,6 +1548,7 @@ exports.ensureWinNode = ensureWinNode;
 exports.extractInstaller = extractInstaller;
 exports.extractWrapperFiles = extractWrapperFiles;
 exports.findSevenZip = findSevenZip;
+exports.installSignalShutdown = installSignalShutdown;
 exports.isLinux = isLinux;
 exports.isNativeNoiseLine = isNativeNoiseLine;
 exports.latestRelease = latestRelease;
@@ -1433,9 +1559,15 @@ exports.locateQqPath = locateQqPath;
 exports.nodeZipUrl = nodeZipUrl;
 exports.readCmdlineForPid = readCmdlineForPid;
 exports.registerLockCleanup = registerLockCleanup;
+exports.registerShutdownHook = registerShutdownHook;
 exports.releaseInstanceLock = releaseInstanceLock;
+exports.removeStopSentinel = removeStopSentinel;
+exports.requestShutdown = requestShutdown;
 exports.resolveDownloadUrl = resolveDownloadUrl;
 exports.resolveQqFiles = resolveQqFiles;
 exports.resolveQqInstall = resolveQqInstall;
+exports.stopSentinelPath = stopSentinelPath;
 exports.toWinePath = toWinePath;
+exports.watchStopSentinel = watchStopSentinel;
 exports.wineBinary = wineBinary;
+exports.writeStopSentinel = writeStopSentinel;

package/dist/index.d.cts

@@ -572,6 +572,12 @@ interface LaunchOptions {
    * 查找失败警告），其余转发——原生 printf 直写 fd 的字节无法从 JS 层拦截。
    */
   stdio?: StdioOptions;
+  /**
+   * 追加注入子进程的环境变量（覆盖同名继承值；值按原样传递，不转 wine 路径）。
+   * cli 用：传播有效控制台渲染决策（NAPUKETTO_LOG_FORMAT/COLORIZE——子进程
+   * stdout 恒为 pipe，TTY 判定失真）与数据根（NAPUTO_DATA_ROOT，停止哨兵用）。
+   */
+  extraEnv?: Record<string, string>;
   /**
    * 阶段回调（stub 校验/win-node 下载/spawn 提示，2026-08-23 起——下载
    * 313MB 安装包与 win-node 全程静默的坑）。调用方接 logger.info。
@@ -624,6 +630,8 @@ declare const ENV: {
   readonly QR_ONLY: "NAPUTO_QR_ONLY";
   /** IPC 子进程模式（koishi 插件驱动：stdout JSON 行 + stdin action/control）。 */
   readonly IPC: "NAPUTO_IPC";
+  /** 数据根（cli 注入：停止哨兵目录解析用，self-host 不再从 CFG_DIR 反推）。 */
+  readonly DATA_ROOT: "NAPUTO_DATA_ROOT";
 };
 //#endregion
 //#region src/pid-cmdline.d.ts
@@ -735,6 +743,50 @@ declare function latestRelease(releases: QqReleasesFile): QqReleaseEntry;
  */
 declare function resolveDownloadUrl(release: QqReleaseEntry): string;
 //#endregion
+//#region src/shutdown.d.ts
+/** 哨兵文件名（置于数据根）。 */
+declare const STOP_SENTINEL_FILENAME = "napuketto.stop";
+/** 哨兵文件路径。 */
+declare function stopSentinelPath(dataRoot: string): string;
+/**
+ * 写停止哨兵（请求优雅关停）。target = "all"/空 = 全部账号；"<uin>" = 单账号。
+ * 任何内容（含空）都视为请求；mtime 由写入时刻决定。
+ */
+declare function writeStopSentinel(dataRoot: string, target: "all" | string): void;
+/** 删除停止哨兵（napuketto stop 等待结束后清理，防陈旧文件累积）。 */
+declare function removeStopSentinel(dataRoot: string): void;
+/** 哨兵观察选项。 */
+interface StopSentinelWatchOptions {
+  /** 数据根（哨兵所在目录）。 */
+  dataRoot: string;
+  /** 本进程对应账号（uin 或 "default"；undefined = 仅响应 all/空）。 */
+  account?: string;
+  /** 触发回调（每进程至多一次）。 */
+  onTrigger: () => void;
+  /** 轮询间隔（测试注入用）。 */
+  pollMs?: number;
+}
+/**
+ * 观察停止哨兵：存在、mtime 晚于进程启动且内容命中 → onTrigger（一次性）。
+ * 返回取消函数。mtime 守卫：进程启动前遗留的哨兵不触发（守护重启安全）。
+ */
+declare function watchStopSentinel(opts: StopSentinelWatchOptions): () => void;
+/** 关停钩子（自建宿主引导链注册：协议适配器停止 / 桥退订等）。 */
+type ShutdownHook = () => void | Promise<void>;
+/** 注册关停钩子（按注册逆序执行）。 */
+declare function registerShutdownHook(hook: ShutdownHook): void;
+/**
+ * 执行关停编排：逆序跑全部钩子（单钩子异常不阻断后续）后 exit 0。
+ * 幂等（重复调用只跑一次）。退出码 0 = 请求式正常退出（生命周期契约）。
+ */
+declare function requestShutdown(reason: string): Promise<void>;
+/**
+ * 信号接入（SIGINT/SIGTERM/SIGBREAK → requestShutdown）。
+ * Windows CTRL_BREAK_EVENT 以 SIGBREAK 到达（宿主 CREATE_NEW_PROCESS_GROUP +
+ * GenerateConsoleCtrlEvent 可优雅停整树）；终端 Ctrl+C 以 SIGINT 到达。
+ */
+declare function installSignalShutdown(): void;
+//#endregion
 //#region src/wine.d.ts
 /**
  * wine.ts：Linux 上经 wine 运行 Windows 版 node.exe 的路径与 spawn 组装（P2）。
@@ -772,5 +824,5 @@ declare function buildSpawnCommand(options: {
   selfHostPath: string;
 }): SpawnCommand;
 //#endregion
-export { DownloadError, type DownloadOptions, type DownloadResult, ENV, type ExtractOptions, INSTANCE_LOCK_FILE, IPC_VERSION, type InstanceLockCheck, type InstanceLockInfo, type IpcActionMessage, type IpcActionPayload, IpcActionPayloadSchema, type IpcBootPhase, IpcBootPhaseSchema, type IpcControlMessage, type IpcControlPayload, IpcControlPayloadSchema, type IpcEventMessage, type IpcEventPayload, IpcEventPayloadSchema, type IpcLogLevel, IpcLogLevelSchema, type IpcLogMessage, type IpcLogPayload, IpcLogPayloadSchema, type IpcLoginMessage, type IpcLoginPayload, IpcLoginPayloadSchema, type IpcMessage, IpcMessageSchema, type IpcPingMessage, type IpcPongMessage, type IpcQrMessage, type IpcResultMessage, type IpcResultPayload, IpcResultPayloadSchema, type IpcStatusMessage, type IpcStatusPayload, IpcStatusPayloadSchema, type LaunchOptions, type LaunchResult, QQ_FILES_DIR_NAME, type QqFileSource, type QqInstallInfo, type QqReleaseEntry, QqReleasesError, type QqReleasesFile, type ResolveQqFilesOptions, type SevenZipResult, type SpawnCommand, WIN_NODE_DIR_NAME, type WinNodeInfo, acquireInstanceLock, buildSpawnCommand, checkInstanceLock, clearCacheVersion, defaultStubDir, downloadFile, ensureLinuxSevenZip, ensureQqFiles, ensureWinNode, extractInstaller, extractWrapperFiles, findSevenZip, isLinux, isNativeNoiseLine, latestRelease, launchSelfHost, linuxSevenZipUrl, loadQqReleases, locateQqPath, nodeZipUrl, readCmdlineForPid, registerLockCleanup, releaseInstanceLock, resolveDownloadUrl, resolveQqFiles, resolveQqInstall, toWinePath, wineBinary };
+export { DownloadError, type DownloadOptions, type DownloadResult, ENV, type ExtractOptions, INSTANCE_LOCK_FILE, IPC_VERSION, type InstanceLockCheck, type InstanceLockInfo, type IpcActionMessage, type IpcActionPayload, IpcActionPayloadSchema, type IpcBootPhase, IpcBootPhaseSchema, type IpcControlMessage, type IpcControlPayload, IpcControlPayloadSchema, type IpcEventMessage, type IpcEventPayload, IpcEventPayloadSchema, type IpcLogLevel, IpcLogLevelSchema, type IpcLogMessage, type IpcLogPayload, IpcLogPayloadSchema, type IpcLoginMessage, type IpcLoginPayload, IpcLoginPayloadSchema, type IpcMessage, IpcMessageSchema, type IpcPingMessage, type IpcPongMessage, type IpcQrMessage, type IpcResultMessage, type IpcResultPayload, IpcResultPayloadSchema, type IpcStatusMessage, type IpcStatusPayload, IpcStatusPayloadSchema, type LaunchOptions, type LaunchResult, QQ_FILES_DIR_NAME, type QqFileSource, type QqInstallInfo, type QqReleaseEntry, QqReleasesError, type QqReleasesFile, type ResolveQqFilesOptions, STOP_SENTINEL_FILENAME, type SevenZipResult, type SpawnCommand, type StopSentinelWatchOptions, WIN_NODE_DIR_NAME, type WinNodeInfo, acquireInstanceLock, buildSpawnCommand, checkInstanceLock, clearCacheVersion, defaultStubDir, downloadFile, ensureLinuxSevenZip, ensureQqFiles, ensureWinNode, extractInstaller, extractWrapperFiles, findSevenZip, installSignalShutdown, isLinux, isNativeNoiseLine, latestRelease, launchSelfHost, linuxSevenZipUrl, loadQqReleases, locateQqPath, nodeZipUrl, readCmdlineForPid, registerLockCleanup, registerShutdownHook, releaseInstanceLock, removeStopSentinel, requestShutdown, resolveDownloadUrl, resolveQqFiles, resolveQqInstall, stopSentinelPath, toWinePath, watchStopSentinel, wineBinary, writeStopSentinel };
 //# sourceMappingURL=index.d.cts.map