@napuketto/kernel 0.2.5 → 0.4.0

package/dist/index.mjs

@@ -42,6 +42,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
 /**
@@ -107,14 +126,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) {
@@ -135,18 +158,18 @@ var ConfigBase = class {
 		if (this.format === "toml") return 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 });
 		}
 	}
 };
@@ -159,14 +182,311 @@ function stringifyToml(value) {
 	return 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 ?? process.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 = [
@@ -176,39 +496,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 pinoPretty({
+		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 ?? process.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: pinoPretty({
-		colorize: true,
-		translateTime: "SYS:HH:MM:ss.l",
-		singleLine: false,
-		destination: process.stdout
-	}) });
+	if ((opts.console ?? true) === true) streams.push({
+		stream: buildConsoleStream(render),
+		level: consoleLevel
+	});
 	if (file) {
 		mkdirSync(dirname(file), { recursive: true });
-		streams.push({ stream: pino.destination({
-			dest: file,
-			sync: true
-		}) });
+		streams.push({
+			stream: pino.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: process.pid,
@@ -3745,7 +4117,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,
@@ -3790,22 +4169,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 真实数据路径）。
@@ -3854,8 +4234,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,
@@ -3877,14 +4256,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 停止");
@@ -3897,6 +4276,27 @@ function writeQrCodePng(filePath, pngBase64) {
 		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) => {
@@ -4498,6 +4898,6 @@ function listQQVersions(installDir) {
 	}).sort().reverse();
 }
 //#endregion
-export { BuddyCache, ChatType, ConfigBase, DEFAULT_DATA_ROOT_NAME, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { BuddyCache, ChatType, ConfigBase, ConfigError, DEFAULT_DATA_ROOT_NAME, EXIT_CONFIG_INVALID, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 
 //# sourceMappingURL=index.mjs.map