@napuketto/kernel 0.2.5 → 0.4.0

package/dist/index.cjs

@@ -68,6 +68,25 @@ function kernelError(message, code = "UNKNOWN", options) {
 function isKernelError(err) {
 	return err instanceof KernelError;
 }
+/**
+* 配置校验失败（INVALID_PARAM 子型，2026-10-25 嵌入式宿主契约）：仅用于
+* 「配置未就绪」一族——主配置校验/反序列化、内联配置、协议段 seed 校验。
+* code 恒为 INVALID_PARAM，协议层错误码映射零涟漪；退出码分类走 instanceof
+* （CLI/self-host 进程以 EXIT_CONFIG_INVALID 退出），与错误文案完全解耦——
+* 文案是人读的，退出码是宿主消费的机器契约。
+*/
+var ConfigError = class extends KernelError {
+	constructor(message, options) {
+		super(message, "INVALID_PARAM", options);
+		this.name = "ConfigError";
+	}
+};
+/** 便捷构造：`configError('主配置缺少 accounts', { cause })`。 */
+function configError(message, options) {
+	return new ConfigError(message, options);
+}
+/** 配置校验失败的进程退出码（UNIX sysexits EX_CONFIG 惯例）。 */
+const EXIT_CONFIG_INVALID = 78;
 //#endregion
 //#region src/infra/config.ts
 /**
@@ -133,14 +152,18 @@ var ConfigBase = class {
 				await this.save(this.defaults);
 				return this.value;
 			}
-			throw new KernelError(`读取配置文件失败: ${this.path}`, "UNKNOWN", { cause: err });
+			throw new ConfigError(`读取配置文件失败: ${this.path}`, { cause: err });
 		}
 		this.value = this.parse(raw);
 		return this.value;
 	}
-	/** 重新从磁盘加载（外部变更后的热更新入口，P2 配置热更新使用）。 */
-	reload() {
-		return this.load();
+	/**
+	* 校验纯文本配置（反序列化 + schema 校验，不读写文件；`config validate`
+	* 等只读场景用）。错误包装与 load()/save() 完全一致（ConfigError，
+	* 文案含 this.path），保证 validate 与运行时校验逐字一致。
+	*/
+	parseText(raw) {
+		return this.parse(raw);
 	}
 	/** 校验并落盘（原子写：临时文件 + rename），随后更新内存。 */
 	async save(next) {
@@ -161,18 +184,18 @@ var ConfigBase = class {
 		if (this.format === "toml") return (0, smol_toml.parse)(raw);
 		return JSON.parse(raw);
 	}
-	/** 反序列化 + schema 校验，错误统一包装为 KernelError。 */
+	/** 反序列化 + schema 校验，错误统一包装为 ConfigError（配置未就绪一族）。 */
 	parse(raw) {
 		let input;
 		try {
 			input = this.deserialize(raw);
 		} catch (err) {
-			throw new KernelError(`配置文件 ${this.format.toUpperCase()} 解析失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+			throw new ConfigError(`配置文件 ${this.format.toUpperCase()} 解析失败: ${this.path}`, { cause: err });
 		}
 		try {
 			return this.schema.parse(input);
 		} catch (err) {
-			throw new KernelError(`配置文件校验失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+			throw new ConfigError(`配置文件校验失败: ${this.path}`, { cause: err });
 		}
 	}
 };
@@ -185,14 +208,311 @@ function stringifyToml(value) {
 	return (0, smol_toml.stringify)(value);
 }
 //#endregion
+//#region src/infra/log-config.ts
+/**
+* [log] 配置段解析（napuketto.toml 全局段，2026-10-25 日志可配置化）。
+*
+* 统一解析入口：cli（apps/cli）与 loader 引导链共用本函数（经 kernel 导出），
+* 避免两处手写解析漂移。输入为 TOML 解析后的 [log] 段原对象（缺失传 undefined）
+* + 环境变量快照；输出为已解析的 LogConfig（env 覆盖优先于 toml）。
+*
+* 环境变量（优先级高于 toml；非法值忽略——与既有 NAPKETTO_LOG_LEVEL 行为一致）：
+*   - NAPUKETTO_LOG_LEVEL / NAPKETTO_LOG_LEVEL（兼容旧拼写，NAPUKETTO_ 优先）
+*   - NAPUKETTO_LOG_FORMAT（pretty | single-line | json）
+*   - NAPUKETTO_NO_BANNER（1/true = 关 banner）
+*   - NAPUKETTO_LOG_COLORIZE（1/true/0/false，CLI 顶层进程向子进程传播控制台
+*     渲染决策用；toml 不暴露此键）
+*/
+/** pino 标准级别 + silent。 */
+const LOG_LEVEL_VALUES = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal",
+	"silent"
+];
+const LOG_FORMAT_VALUES = [
+	"pretty",
+	"single-line",
+	"json"
+];
+const TIMESTAMP_MODE_VALUES = [
+	"local",
+	"iso8601",
+	"elapsed"
+];
+const MODULE_NAME_VALUES = [
+	"cli",
+	"kernel",
+	"loader",
+	"ob11"
+];
+/** 校验级别字面量；非法值抛 INVALID_PARAM。 */
+function requireLevel(value, key) {
+	if (typeof value !== "string" || !LOG_LEVEL_VALUES.includes(value)) throw kernelError(`主配置 ${key} 必须是日志级别（${LOG_LEVEL_VALUES.join(" / ")}）`, "INVALID_PARAM");
+	return value;
+}
+/** 宽松级别解析（env 覆盖用；非法/缺失返回 undefined 不生效）。 */
+function optionalLevel(value) {
+	if (value === void 0) return;
+	return LOG_LEVEL_VALUES.includes(value) ? value : void 0;
+}
+/** 宽松格式解析（env 覆盖用）。 */
+function optionalFormat(value) {
+	if (value === void 0) return;
+	return LOG_FORMAT_VALUES.includes(value) ? value : void 0;
+}
+/** 宽松布尔解析（env 用：仅识别 1/true/0/false，其余忽略）。 */
+function optionalBool(value) {
+	if (value === "1" || value === "true") return true;
+	if (value === "0" || value === "false") return false;
+}
+/** 解析 [log.levels] 按模块覆盖表（未知模块名报错，键集封闭防拼写错误）。 */
+function parseModuleLevels(raw) {
+	if (raw === void 0) return {};
+	if (typeof raw !== "object" || raw === null) throw kernelError("主配置 log.levels 必须是对象", "INVALID_PARAM");
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (!MODULE_NAME_VALUES.includes(key)) throw kernelError(`主配置 log.levels 未知模块 "${key}"（合法模块：${MODULE_NAME_VALUES.join(" / ")}）`, "INVALID_PARAM");
+		out[key] = requireLevel(value, `log.levels.${key}`);
+	}
+	return out;
+}
+/** 解析 [log.file] 独立文件 sink。 */
+function parseLogFile(raw, fallbackLevel) {
+	if (typeof raw !== "object" || raw === null) throw kernelError("主配置 log.file 必须是对象", "INVALID_PARAM");
+	const record = raw;
+	const path = record["path"];
+	if (typeof path !== "string" || path === "") throw kernelError("主配置 log.file.path 必须是非空字符串", "INVALID_PARAM");
+	return {
+		path,
+		level: record["level"] === void 0 ? fallbackLevel : requireLevel(record["level"], "log.file.level")
+	};
+}
+/** 校验字面量枚举值（非法抛 INVALID_PARAM，报错文案带键名与合法值集）。 */
+function requireEnum(value, key, values) {
+	if (typeof value !== "string" || !values.includes(value)) throw kernelError(`主配置 ${key} 必须是（${values.join(" / ")}）`, "INVALID_PARAM");
+	return value;
+}
+/** 校验布尔字段（undefined 保留原值）。 */
+function applyBoolean(draft, raw, key) {
+	if (raw[key] === void 0) return;
+	if (typeof raw[key] !== "boolean") throw kernelError(`主配置 log.${key} 必须是布尔值`, "INVALID_PARAM");
+	draft[key] = raw[key];
+}
+/** toml [log] 段字段填充（level/format/timestamp/banner/unboundReceive）。 */
+function applySectionFields(draft, raw) {
+	if (raw["level"] !== void 0) draft.level = requireLevel(raw["level"], "log.level");
+	if (raw["format"] !== void 0) draft.format = requireEnum(raw["format"], "log.format", LOG_FORMAT_VALUES);
+	if (raw["timestamp"] !== void 0) draft.timestamp = requireEnum(raw["timestamp"], "log.timestamp", TIMESTAMP_MODE_VALUES);
+	applyBoolean(draft, raw, "banner");
+	applyBoolean(draft, raw, "unboundReceive");
+}
+/** env 覆盖（优先级高于 toml；非法值忽略）：兼容旧拼写 NAPKETTO_LOG_LEVEL。
+* file.level 显式配置时不被 env 全局级别顶掉（缺省跟随全局）。 */
+function applyEnvOverrides(draft, env) {
+	const envLevel = optionalLevel(env["NAPUKETTO_LOG_LEVEL"]) ?? optionalLevel(env["NAPKETTO_LOG_LEVEL"]);
+	if (envLevel !== void 0) {
+		draft.level = envLevel;
+		if (draft.file !== void 0 && draft.fileLevelExplicit !== true) draft.file = {
+			...draft.file,
+			level: envLevel
+		};
+	}
+	const envFormat = optionalFormat(env["NAPUKETTO_LOG_FORMAT"]);
+	if (envFormat !== void 0) draft.format = envFormat;
+	if (optionalBool(env["NAPUKETTO_NO_BANNER"]) === true) draft.banner = false;
+	const envColorize = optionalBool(env["NAPUKETTO_LOG_COLORIZE"]);
+	if (envColorize !== void 0) draft.colorize = envColorize;
+}
+/**
+* 解析 [log] 段 + 环境变量覆盖。
+*
+* @param section TOML 解析后的 [log] 段（缺失/undefined = 全缺省）
+* @param env 环境变量快照（默认空对象 = 无 env 覆盖）
+*/
+function parseLogConfig(section, env = {}) {
+	const draft = {
+		level: "info",
+		banner: true,
+		timestamp: "local",
+		unboundReceive: true,
+		levels: {}
+	};
+	if (section !== void 0) {
+		if (typeof section !== "object" || section === null) throw kernelError("主配置 log 段必须是对象", "INVALID_PARAM");
+		const raw = section;
+		applySectionFields(draft, raw);
+		draft.levels = parseModuleLevels(raw["levels"]);
+		if (raw["file"] !== void 0) {
+			draft.file = parseLogFile(raw["file"], draft.level);
+			draft.fileLevelExplicit = typeof raw["file"] === "object" && raw["file"] !== null && raw["file"]["level"] !== void 0;
+		}
+	}
+	applyEnvOverrides(draft, env);
+	delete draft.fileLevelExplicit;
+	return draft;
+}
+//#endregion
+//#region src/infra/log-format.ts
+/**
+* 结构化控制台流（single-line / json 格式，2026-10-25 日志可配置化）。
+*
+* pino-pretty 面向交互终端（多行展开 / JSON 内联渲染），其 singleLine 输出为
+* `msg {"k":"v"}` 形态且 messageFormat 会与字段追加双重渲染——无法干净满足
+* 嵌入式宿主的「一条记录一行、字段 k=v / NDJSON」契约，故自写轻量渲染流：
+*
+*   single-line：[时间] LEVEL (name/pid): 消息 key=value key=value
+*   json：NDJSON，每行 {time, level, module, account?, pid, msg, ...fields}
+*
+* 时间渲染（LogConfig.timestamp）：local = [HH:MM:ss.l]（与 pretty 缺省一致）、
+* iso8601 = 2026-10-25T16:01:33.294+08:00、elapsed = +123.456s（进程内单调秒）。
+* json 的 time 恒为 ISO8601（机器可解析契约，不受 timestamp 键影响）。
+*/
+/** 级别数值 → 名称（pino 标准映射）。 */
+const LEVEL_LABELS = {
+	10: "trace",
+	20: "debug",
+	30: "info",
+	40: "warn",
+	50: "error",
+	60: "fatal"
+};
+/** single-line 颜色（colorize 时仅着色级别与元数据头，正文默认色）。 */
+const LEVEL_COLORS = {
+	trace: "\x1B[34m",
+	debug: "\x1B[36m",
+	info: "\x1B[32m",
+	warn: "\x1B[33m",
+	error: "\x1B[31m",
+	fatal: "\x1B[91m"
+};
+const DIM = "\x1B[2m";
+const RESET = "\x1B[0m";
+/** 2 位补零。 */
+function pad2(n) {
+	return String(n).padStart(2, "0");
+}
+/** 单调墙钟毫秒 → 本地时区 ISO8601（+08:00 形态；new Date(epoch) 构造不受 Date.now 篡改影响）。 */
+function isoLocalTime(epochMs) {
+	const d = new Date(epochMs);
+	const offsetMinutes = -d.getTimezoneOffset();
+	const sign = offsetMinutes >= 0 ? "+" : "-";
+	const abs = Math.abs(offsetMinutes);
+	return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}T${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+}
+/** 单调墙钟毫秒 → 本地时分秒（与 pino-pretty SYS:HH:MM:ss.l 一致的短格式）。 */
+function localShortTime(epochMs) {
+	const d = new Date(epochMs);
+	return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}`;
+}
+/** 单调墙钟毫秒 → 进程内相对秒（+123.456s）。 */
+function elapsedLabel(epochMs, timeOriginMs) {
+	return `+${((epochMs - timeOriginMs) / 1e3).toFixed(3)}s`;
+}
+/** 渲染记录时间（timestamp 模式分发；json 恒 ISO8601）。 */
+function renderTime(rawTime, mode, forceIso, timeOriginMs) {
+	if (typeof rawTime === "string") return rawTime;
+	const epoch = typeof rawTime === "number" ? rawTime : timeOriginMs;
+	if (forceIso || mode === "iso8601") return isoLocalTime(epoch);
+	if (mode === "elapsed") return elapsedLabel(epoch, timeOriginMs);
+	return localShortTime(epoch);
+}
+/** 级别数值 → 标签名。 */
+function levelLabel(raw) {
+	if (typeof raw === "number") return LEVEL_LABELS[raw] ?? String(raw);
+	return typeof raw === "string" ? raw.toUpperCase() : "LOG";
+}
+/** k=v 内联值：字符串裸输出（含空格时不加引号——宽松人类格式），其余 JSON 序列化。 */
+function inlineValue(value) {
+	if (typeof value === "string") return value;
+	return JSON.stringify(value) ?? "null";
+}
+/** 结构化输出忽略的标准字段（渲染进头/独立字段，不进 k=v 尾部）。 */
+const RESERVED_KEYS = /* @__PURE__ */ new Set([
+	"pid",
+	"hostname",
+	"level",
+	"time",
+	"msg",
+	"name"
+]);
+/** json 渲染：NDJSON 契约 {time, level, module, account?, pid, msg, ...fields}。 */
+function renderJsonLine(record, ctx) {
+	const { time, level, name, module, account, pid, msg: _msg, ...fields } = record;
+	const msg = typeof record["msg"] === "string" ? record["msg"] : "";
+	const jsonLine = {
+		time: renderTime(time, ctx.timestamp, true, ctx.timeOriginMs),
+		level: levelLabel(level).toLowerCase(),
+		...module !== void 0 ? { module } : typeof name === "string" ? { module: name } : {},
+		...account !== void 0 ? { account } : {},
+		...typeof pid === "number" ? { pid } : {},
+		msg,
+		...fields
+	};
+	return `${JSON.stringify(jsonLine)}\n`;
+}
+/** single-line 元数据头：(name/pid)，无 name 时 (pid)。 */
+function renderMeta(record) {
+	const pid = record["pid"] ?? "-";
+	const name = record["name"];
+	return typeof name === "string" ? `(${name}/${pid})` : `(${pid})`;
+}
+/** single-line 附加字段：非保留键按 k=v 内联（无字段时空串）。 */
+function renderKvFields(record) {
+	const fields = [];
+	for (const [key, value] of Object.entries(record)) if (!RESERVED_KEYS.has(key)) fields.push(`${key}=${inlineValue(value)}`);
+	return fields.length > 0 ? ` ${fields.join(" ")}` : "";
+}
+/** single-line 渲染：[时间] LEVEL (name/pid): 消息 k=v k=v（级别大写与 pretty 一致）。 */
+function renderSingleLine(record, ctx) {
+	const label = levelLabel(record["level"]);
+	const msg = typeof record["msg"] === "string" ? record["msg"] : "";
+	const time = renderTime(record["time"], ctx.timestamp, false, ctx.timeOriginMs);
+	const labelUpper = label.toUpperCase();
+	const meta = renderMeta(record);
+	const fieldsSuffix = renderKvFields(record);
+	if (ctx.useColor) {
+		const color = LEVEL_COLORS[label.toLowerCase()] ?? "";
+		return `${DIM}[${time}]${RESET} ${color}${labelUpper}${RESET} ${DIM}${meta}:${RESET} ${msg}${fieldsSuffix}\n`;
+	}
+	return `[${time}] ${labelUpper} ${meta}: ${msg}${fieldsSuffix}\n`;
+}
+/** 创建结构化控制台流（single-line / json）。 */
+function createConsoleFormatStream(opts) {
+	const out = opts.destination ?? node_process.default.stdout;
+	const ctx = {
+		timestamp: opts.timestamp,
+		timeOriginMs: performance.timeOrigin,
+		useColor: opts.format === "single-line" && opts.colorize
+	};
+	const render = opts.format === "json" ? renderJsonLine : renderSingleLine;
+	return { write(line) {
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			out.write(`${line}\n`);
+			return;
+		}
+		out.write(render(record, ctx));
+	} };
+}
+//#endregion
 //#region src/infra/logger.ts
 /**
 * pino 日志封装（ADR-007）
 *
-* - console（pino-pretty 可读输出）+ 可选文件双目的地
-* - 统一 level 控制
+* - console（pretty 可读输出 / single-line / json 结构化）+ 可选文件双目的地
+* - 统一 level 控制（控制台与文件可分别设级，2026-10-25 日志可配置化）
 * - 内置 redact（token / 票据等敏感字段不打日志），可追加
 * - 无全局单例（ADR-015 推论）：每进程实例化一份，由装配层持有
+*
+* 时间源（2026-10-25 修复）：QQNT 原生层会在 onRecvSysMsg 回调窗口内篡改进程
+* Date（实测记录时间冻结为假值、回调外恢复），故时间戳统一取
+* performance.timeOrigin + performance.now() 单调派生墙钟，不受 Date 篡改影响。
 */
 /** 默认 redact 路径：顶层 token/票据 + 任意深度的密码/密钥。 */
 const DEFAULT_REDACT_PATHS = [
@@ -202,39 +522,91 @@ const DEFAULT_REDACT_PATHS = [
 	"password",
 	"secret"
 ];
+/** 级别数值序（求多目的地最低级别用）。 */
+const LEVEL_ORDER = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal",
+	"silent"
+];
+/** 取两级别中更低（更宽容）的一个。 */
+function minLevel(a, b) {
+	return LEVEL_ORDER.indexOf(a) <= LEVEL_ORDER.indexOf(b) ? a : b;
+}
+/** 单调墙钟毫秒（timeOrigin 为进程启动真实 Unix 时间，不受进程内 Date 篡改影响）。 */
+function wallMs() {
+	return performance.timeOrigin + performance.now();
+}
+/** 进程内相对秒标签（elapsed 模式，pretty 字符串时间路径用）。 */
+function elapsedLabelNow() {
+	return `+${(performance.now() / 1e3).toFixed(3)}s`;
+}
 function toSingle(streams) {
 	const [only] = streams;
 	if (only === void 0) throw new KernelError("logger 内部错误：目的地列表为空", "UNKNOWN");
 	return only.stream;
 }
-/**
-* 创建 pino logger：console（pretty）+ 可选文件，统一 level / redact。
-*
-* 文件目的地用同步写入（`sync: true`）：日志量级下性能可接受，且进程退出不丢日志，
-* 无需额外的 flush 步骤（对比异步 SonicBoom 的 flushSync 时序陷阱）。
-*/
+/** 构造控制台流：pretty 走 pino-pretty，single-line/json 走结构化渲染流。 */
+function buildConsoleStream(params) {
+	const { format, timestampMode, colorize, destination } = params;
+	if (format !== "pretty") return createConsoleFormatStream({
+		format,
+		timestamp: timestampMode,
+		colorize,
+		destination
+	});
+	return (0, pino_pretty.default)({
+		colorize,
+		...timestampMode === "local" ? { translateTime: "SYS:HH:MM:ss.l" } : {},
+		...timestampMode === "iso8601" ? { translateTime: "SYS:yyyy-mm-dd'T'HH:MM:ss.l Z" } : {},
+		singleLine: false,
+		destination
+	});
+}
+/** 折叠 LoggerOptions 的渲染缺省：格式按 TTY 自动（TTY pretty / pipe single-line）、
+* 颜色仅在 pretty 且 TTY 时开。 */
+function resolveRenderParams(opts) {
+	const destination = opts.destination ?? node_process.default.stdout;
+	const isTty = destination.isTTY === true;
+	const format = opts.format ?? (isTty ? "pretty" : "single-line");
+	return {
+		format,
+		timestampMode: opts.timestamp ?? "local",
+		colorize: opts.colorize ?? (format === "pretty" && isTty),
+		destination
+	};
+}
 function createLogger(opts = {}) {
-	const level = opts.level ?? "info";
-	const consoleEnabled = opts.console ?? true;
+	const consoleLevel = opts.level ?? "info";
+	const fileLevel = opts.fileLevel ?? consoleLevel;
 	const { file, base } = opts;
+	const render = resolveRenderParams(opts);
 	const streams = [];
-	if (consoleEnabled) streams.push({ stream: (0, pino_pretty.default)({
-		colorize: true,
-		translateTime: "SYS:HH:MM:ss.l",
-		singleLine: false,
-		destination: node_process.default.stdout
-	}) });
+	if ((opts.console ?? true) === true) streams.push({
+		stream: buildConsoleStream(render),
+		level: consoleLevel
+	});
 	if (file) {
 		(0, node_fs.mkdirSync)((0, node_path.dirname)(file), { recursive: true });
-		streams.push({ stream: pino.default.destination({
-			dest: file,
-			sync: true
-		}) });
+		streams.push({
+			stream: pino.default.destination({
+				dest: file,
+				sync: true
+			}),
+			level: fileLevel
+		});
 	}
 	if (streams.length === 0) throw new KernelError("logger 至少需要一个输出目标：console 或 file", "INVALID_PARAM");
+	let gate = "fatal";
+	for (const entry of streams) gate = minLevel(gate, entry.level);
+	const pinoTimestamp = render.format === "pretty" && render.timestampMode === "elapsed" ? () => `,"time":"${elapsedLabelNow()}"` : () => `,"time":${wallMs()}`;
 	const pinoOptions = {
-		level,
-		redact: [...DEFAULT_REDACT_PATHS, ...opts.redact ?? []]
+		level: gate,
+		redact: [...DEFAULT_REDACT_PATHS, ...opts.redact ?? []],
+		timestamp: pinoTimestamp
 	};
 	if (base) pinoOptions.base = {
 		pid: node_process.default.pid,
@@ -3771,7 +4143,14 @@ var NapukettoCore = class NapukettoCore {
 			level: opts.logLevel ?? "info",
 			console: opts.consoleLog ?? true,
 			file: opts.logFile ?? paths.file("logs", "napuketto.log"),
-			base: { name: "kernel" }
+			fileLevel: opts.logFileLevel,
+			format: opts.logFormat,
+			timestamp: opts.logTimestamp,
+			colorize: opts.logColorize,
+			base: {
+				name: "kernel",
+				account: opts.account
+			}
 		});
 		return new NapukettoCore(createCoreContext({
 			logger,
@@ -3816,22 +4195,23 @@ var NapukettoCore = class NapukettoCore {
 			this.ctx.login = loginResult;
 			return loginResult;
 		}
-		let loginResult;
+		const loginResult = await this.loginQuickFirst(wrapper, opts);
+		this.ctx.login = loginResult;
+		return loginResult;
+	}
+	/** 快速登录优先，失败按 qrFallback 决定是否回退 QR（QR 应直接出码，见 loginByQr 注）。 */
+	async loginQuickFirst(wrapper, opts) {
 		try {
-			const quickOpts = {};
-			if (opts.quickUin !== void 0) quickOpts.uin = opts.quickUin;
-			if (opts.quickLoginTimeoutMs !== void 0) quickOpts.quickLoginTimeoutMs = opts.quickLoginTimeoutMs;
-			loginResult = await quickLogin(wrapper, quickOpts);
+			const result = await quickLogin(wrapper, buildQuickLoginOptions(opts));
 			this.ctx.logger.info({
-				uin: loginResult.uin,
-				uid: loginResult.uid
+				uin: result.uin,
+				uid: result.uid
 			}, "快速登录成功");
+			return result;
 		} catch (err) {
 			if (opts.qrFallback !== true) throw err;
-			loginResult = await this.loginByQr(opts);
+			return await this.loginByQr(opts);
 		}
-		this.ctx.login = loginResult;
-		return loginResult;
 	}
 	/**
 	* loginService.initConfig（worker/自建宿主需指定 QQ 真实数据路径）。
@@ -3880,8 +4260,7 @@ var NapukettoCore = class NapukettoCore {
 		try {
 			session.start();
 			await waitQrLoggedIn(session);
-			const self = session.selfInfo;
-			if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
+			const self = requireQrSelfInfo(session);
 			return {
 				uin: self.uin,
 				uid: self.uid,
@@ -3903,14 +4282,14 @@ var NapukettoCore = class NapukettoCore {
 			});
 		});
 		session.onStateChange((state) => {
-			this.ctx.logger.info({ state }, "QR 登录状态");
-			const message = state === "failed" ? session.failureReason ?? void 0 : void 0;
-			opts.onLoginProgress?.({
-				state,
-				...message !== void 0 ? { message } : {}
-			});
+			this.forwardQrState(session, opts, state);
 		});
 	}
+	/** QR 状态转发：日志 + onLoginProgress（failed 附 failureReason）。 */
+	forwardQrState(session, opts, state) {
+		this.ctx.logger.info({ state }, "QR 登录状态");
+		opts.onLoginProgress?.(qrProgressEvent(state, session.failureReason ?? void 0));
+	}
 	/** 停止：日志收尾（资源清理留给 P2 常驻管理）。 */
 	stop() {
 		this.ctx.logger.info("NapukettoCore 停止");
@@ -3923,6 +4302,27 @@ function writeQrCodePng(filePath, pngBase64) {
 		(0, node_fs.writeFileSync)(filePath, Buffer.from(pngBase64, "base64"));
 	} catch {}
 }
+/** CoreLoginOptions → quickLogin 参数（仅取快速登录相关两键，QR 键不透传）。 */
+function buildQuickLoginOptions(opts) {
+	const quickOpts = {};
+	if (opts.quickUin !== void 0) quickOpts.uin = opts.quickUin;
+	if (opts.quickLoginTimeoutMs !== void 0) quickOpts.quickLoginTimeoutMs = opts.quickLoginTimeoutMs;
+	return quickOpts;
+}
+/** QR 登录终态后的 selfInfo 提取（空值按登录失败抛出）。 */
+function requireQrSelfInfo(session) {
+	const self = session.selfInfo;
+	if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
+	return self;
+}
+/** QR 进度事件折叠（failed 附 failureReason 为 message，其余不带 message 键）。 */
+function qrProgressEvent(state, reason) {
+	const message = state === "failed" ? reason : void 0;
+	return {
+		state,
+		...message !== void 0 ? { message } : {}
+	};
+}
 /** 等待 QR 登录终态：logged_in resolve，failed reject。 */
 function waitQrLoggedIn(session) {
 	return new Promise((resolve, reject) => {
@@ -4527,7 +4927,9 @@ function listQQVersions(installDir) {
 exports.BuddyCache = BuddyCache;
 exports.ChatType = ChatType;
 exports.ConfigBase = ConfigBase;
+exports.ConfigError = ConfigError;
 exports.DEFAULT_DATA_ROOT_NAME = DEFAULT_DATA_ROOT_NAME;
+exports.EXIT_CONFIG_INVALID = EXIT_CONFIG_INVALID;
 exports.ElementType = ElementType;
 exports.FriendApi = FriendApi;
 exports.FriendBridge = FriendBridge;
@@ -4560,6 +4962,7 @@ exports.WebHonorType = WebHonorType;
 exports.buildEngineConfig = buildEngineConfig;
 exports.buildLoginConfig = buildLoginConfig;
 exports.buildSessionConfig = buildSessionConfig;
+exports.configError = configError;
 exports.createCoreContext = createCoreContext;
 exports.createLifecycleSessionListener = createSessionListener;
 exports.createLogger = createLogger;
@@ -4579,6 +4982,7 @@ exports.listLoginAccounts = listLoginAccounts;
 exports.listQQVersions = listQQVersions;
 exports.narrowBuddyCategories = narrowBuddyCategories;
 exports.parseAppidFromMajor = parseAppidFromMajor;
+exports.parseLogConfig = parseLogConfig;
 exports.parseToml = parseToml;
 exports.probeRuntime = probeRuntime;
 exports.quickLogin = quickLogin;