@napuketto/kernel 0.0.9 → 0.0.12

package/dist/index.cjs

@@ -1341,9 +1341,9 @@ var MsgApi = class {
 	* 且发送后进程崩溃重启（supervisor 自动拉起）。完整字段（NapCat 同款，
 	* formatType/voiceType/canConvert2Text/waveAmplitudes 等）消除该错误。
 	*
-	* ⚠️ silk 格式：QQ 语音协议为 silk v3。传入非 silk（ogg/mp3 等）时发送器
-	* 可能拒绝上传（待实测）。转换点预留：此处直接放置原文件，后续接入
-	* ogg → PCM → silk 编码器（外部 ffmpeg + silk-wasm，见 docs/design.md）。
+	* ⚠️ silk 格式：QQ 语音协议为 silk v3。非 silk → silk 的转码在协议层
+	* （adapter，@napuketto/media 的 encodePcmToSilk，2026-08-12 接线）完成，
+	* 此处接收的已是 silk 路径，仅做放置。kernel 不 import media（解耦红线）。
 	*/
 	async preparePttElement(path) {
 		const file = await statFile(path);
@@ -2616,6 +2616,8 @@ function startupSessionStart(ctx) {
 /** 二维码过期错误码（errType=1 errCode=3，实测）。 */
 const QR_EXPIRED_ERR_TYPE = 1;
 const QR_EXPIRED_ERR_CODE = 3;
+/** 登录超时提示（参考项目文案，前端 failed 态展示）。 */
+const QR_LOGIN_TIMEOUT_MESSAGE = "登录超时，请刷新页面重试";
 /** 二维码过期判定。 */
 function isQrCodeExpired(errType, errCode) {
 	return errType === QR_EXPIRED_ERR_TYPE && errCode === QR_EXPIRED_ERR_CODE;
@@ -2630,10 +2632,17 @@ var QrLoginSession = class {
 	self = null;
 	qrCodeHandlers = /* @__PURE__ */ new Set();
 	stateHandlers = /* @__PURE__ */ new Set();
-	constructor(loginService) {
+	/** 超时定时器（refresh 后启动，登录成功/失败/stop 清理）。 */
+	timeoutTimer = null;
+	/** 失败原因（超时等，failed 态透出给上层提示文案）。 */
+	failureReasonValue = null;
+	/** 超时上限（毫秒，默认 QR_LOGIN_TIMEOUT_MS）。 */
+	timeoutMs;
+	constructor(loginService, options = {}) {
 		const svc = loginService;
 		if (svc === null || typeof svc.addKernelLoginListener !== "function") throw kernelError("loginService 无效（缺 addKernelLoginListener）", "INVALID_STATE");
 		this.loginService = svc;
+		this.timeoutMs = options.timeoutMs ?? 12e4;
 	}
 	/** 当前状态。 */
 	get currentState() {
@@ -2643,6 +2652,10 @@ var QrLoginSession = class {
 	get selfInfo() {
 		return this.self;
 	}
+	/** 失败原因（超时等；failed 态透出给上层提示文案）。 */
+	get failureReason() {
+		return this.failureReasonValue;
+	}
 	/** 订阅二维码（png base64 + url）。返回退订函数。 */
 	onQrCode(cb) {
 		this.qrCodeHandlers.add(cb);
@@ -2665,10 +2678,12 @@ var QrLoginSession = class {
 		});
 		else this.refresh();
 	}
-	/** 刷新二维码（手动 / 过期自动）。 */
+	/** 刷新二维码（手动 / 过期自动）。每次出码重启超时计时。 */
 	refresh() {
+		this.failureReasonValue = null;
 		this.setState("waiting_scan");
 		this.loginService.getQRCodePicture();
+		this.restartTimeout();
 	}
 	/** 构建登录监听（普通 JS 对象，NAPI 反射）。 */
 	buildListener() {
@@ -2687,6 +2702,7 @@ var QrLoginSession = class {
 			this.setState("scanned");
 		};
 		listener.onQRCodeLoginSucceed = (result) => {
+			this.clearTimeoutTimer();
 			this.self = {
 				uin: result.uin,
 				uid: result.uid,
@@ -2699,20 +2715,41 @@ var QrLoginSession = class {
 				this.refresh();
 				return;
 			}
+			this.clearTimeoutTimer();
+			this.failureReasonValue = null;
 			this.setState("failed");
 		};
 		listener.onLoginFailed = () => {
+			this.clearTimeoutTimer();
+			this.failureReasonValue = null;
 			this.setState("failed");
 		};
 		return listener;
 	}
 	/** 停止：注销监听（登录成功后调用，防重复回调）。 */
 	stop() {
+		this.clearTimeoutTimer();
 		if (this.listenerId !== null) {
 			this.loginService.removeKernelLoginListener(this.listenerId);
 			this.listenerId = null;
 		}
 	}
+	/** 重启超时计时器：超时未登录 → failed + 超时提示。 */
+	restartTimeout() {
+		this.clearTimeoutTimer();
+		this.timeoutTimer = setTimeout(() => {
+			this.timeoutTimer = null;
+			this.failureReasonValue = QR_LOGIN_TIMEOUT_MESSAGE;
+			this.setState("failed");
+		}, this.timeoutMs);
+	}
+	/** 清理超时计时器（幂等）。 */
+	clearTimeoutTimer() {
+		if (this.timeoutTimer !== null) {
+			clearTimeout(this.timeoutTimer);
+			this.timeoutTimer = null;
+		}
+	}
 	setState(next) {
 		this.state = next;
 		for (const cb of this.stateHandlers) cb(next);
@@ -2794,13 +2831,59 @@ function findInObject(value) {
 *
 * 与 lifecycle.ts（流程编排）解耦：本模块只回答「配置长什么样」，不管流程怎么走。
 * 字段为 wrapper.node 外部契约（appid/qua/版本），运行时实测确认，自研描述。
+* appid 唯一来源是 major.node 动态解析（每版本不同）；解析失败显式抛 KernelError，
+* 不再静默回退过期 appid（2026-08 硬编码审计：537237765 是 9.9.31 的 appid，该版本
+* 登录服务已被腾讯下线，静默用它会导致扫码「请下载最新版」且极难排查）。
+*/
+/** app_type=4：桌面端应用类型（engine.initWithDeskTopConfig 契约；移动端为其它值）。 */
+const APP_TYPE_DESKTOP = 4;
+/**
+* 缩略图生成参数（thumb_config，engine 契约）：
+* maxSide 最长边像素上限 / minSide 最短边像素下限 / longLimit 长图最长短边比例上限 /
+* density 像素密度倍数。
+*/
+const THUMB_CONFIG = {
+	maxSide: 324,
+	minSide: 48,
+	longLimit: 6,
+	density: 2
+};
+/**
+* session.init 的 deviceConfig（wrapper 契约，JSON 字符串字面量）：
+* appearance.isSplitViewMode 分屏模式开关，msg 空对象为占位。自建宿主无 UI，保持最小可用。
+*/
+const DEVICE_CONFIG_JSON = "{\"appearance\":{\"isSplitViewMode\":true},\"msg\":{}}";
+/** localId=2052：zh-CN（简体中文）locale 码（Windows LCID，deviceInfo.localId 契约）。 */
+const ZH_CN_LOCALE_ID = 2052;
+/** 平台名映射：os.platform() → wrapper devType 契约值（不写死具体构建号）。 */
+const DEV_TYPE_BY_PLATFORM = {
+	win32: "Windows",
+	darwin: "Mac",
+	linux: "Linux",
+	android: "Android",
+	freebsd: "FreeBSD",
+	openbsd: "OpenBSD",
+	sunos: "SunOS",
+	aix: "AIX"
+};
+/**
+* 系统信息运行时探测（wrapper 契约：platVer / osVersion / devType）。
+* 旧实现写死 "Windows 10.0.22631"/"Windows 10 Pro"——换机即失真（2026-08 硬编码审计整改）。
+* 探测失败时给通用值兜底，但不写死具体 Windows 构建号。
 */
-/** 系统信息（先用 fixed 值，真实环境探测后补）。 */
 function systemInfo() {
+	let devType = "Unknown";
+	let platVer = "Unknown";
+	let osVersion = "Unknown";
+	try {
+		devType = DEV_TYPE_BY_PLATFORM[(0, node_os.platform)()] ?? (0, node_os.platform)();
+		platVer = `${devType} ${(0, node_os.release)()}`;
+		osVersion = (0, node_os.version)() || (0, node_os.type)();
+	} catch {}
 	return {
-		platVer: "Windows 10.0.22631",
-		osVersion: "Windows 10 Pro",
-		devType: "Windows"
+		platVer,
+		osVersion,
+		devType
 	};
 }
 /** 纯数字串（major.node 提取的 appid 判定）。 */
@@ -2808,7 +2891,7 @@ const DIGITS_ONLY_RE = /^\d+$/;
 /**
 * 从 major.node 提取 appid（NapCat parseAppidFromMajorV2 的自研等价实现）。
 * major.node 含 `QQAppId/` 标记后跟数字（腾讯工具链产物，实测确认）。
-* 返回 null 表示解析失败（调用方回退硬编码表）。
+* 返回 null 表示解析失败（调用方应显式报错，不再回退硬编码 appid）。
 */
 function parseAppidFromMajor(majorPath) {
 	if (!(0, node_fs.existsSync)(majorPath)) return null;
@@ -2839,48 +2922,34 @@ function readMarkerValue(buf, start) {
 	while (end < buf.length && buf[end] !== 0) end += 1;
 	return buf.subarray(start, end).toString("utf-8");
 }
-/** Windows 兜底 appid / qua（major.node 解析失败时）。 */
-function fallbackAppidQua(fullVersion) {
-	return {
-		appid: "537237765",
-		qua: `V1_WIN_NQ_${fullVersion}_${fullVersion.split("-")[1] ?? ""}_GW_B`
-	};
-}
 /**
 * 解析 appid / qua（自研，参考 NapCat QQBasicInfoWrapper 思路但独立实现）：
-*  1. 优先从 major.node 提取 appid（实测 9.9.33-51802 = 537376818）
-*  2. 回退硬编码表（旧版 537237765）
-* majorPath 传 wrapper.node 同目录 major.node；不传则跳过 major 解析。
+* appid 唯一来源 = major.node 提取（实测 9.9.33-51802 = 537376818）。
+* majorPath 缺省或解析失败时抛 KernelError——不再静默回退过期 appid。
+* majorPath 传 wrapper.node 同目录 major.node。
 */
 function resolveAppidQua(fullVersion, majorPath) {
-	if (majorPath !== void 0) {
-		const appid = parseAppidFromMajor(majorPath);
-		if (appid !== null) return {
-			appid,
-			qua: `V1_WIN_NQ_${fullVersion}_${fullVersion.split("-")[1] ?? ""}_GW_B`
-		};
-	}
-	return fallbackAppidQua(fullVersion);
+	const appid = majorPath !== void 0 ? parseAppidFromMajor(majorPath) : null;
+	if (appid === null) throw kernelError("无法从 major.node 解析 appid，请确认 wrapper.node/major.node 完整，或更新 qq-releases.json", "INVALID_STATE");
+	return {
+		appid,
+		qua: `V1_WIN_NQ_${fullVersion}_${fullVersion.split("-")[1] ?? ""}_GW_B`
+	};
 }
-/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（解析 appid/qua）。 */
+/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（缺失/解析失败会抛错）。 */
 function buildEngineConfig(fullVersion, dataPathGlobal, majorPath) {
 	const { osVersion } = systemInfo();
 	const { qua } = resolveAppidQua(fullVersion, majorPath);
 	return {
 		base_path_prefix: "",
 		platform_type: PlatformType.KWINDOWS,
-		app_type: 4,
+		app_type: APP_TYPE_DESKTOP,
 		app_version: fullVersion,
 		os_version: osVersion,
 		use_xlog: true,
 		qua,
 		global_path_config: { desktopGlobalPath: dataPathGlobal },
-		thumb_config: {
-			maxSide: 324,
-			minSide: 48,
-			longLimit: 6,
-			density: 2
-		}
+		thumb_config: THUMB_CONFIG
 	};
 }
 /** 生成登录初始化配置（externalVersion: false 与 NapCat 同款，扫码兼容关键）。 */
@@ -2898,12 +2967,12 @@ function buildLoginConfig(appid, fullVersion, commonPath) {
 }
 /** 生成 session 初始化配置（登录成功后调用）。 */
 function buildSessionConfig(options) {
-	const { appid, fullVersion, selfUin, selfUid, accountPath, downloadPath } = options;
+	const { appid, fullVersion, selfUin, selfUid, accountPath, downloadPath, machineGuid } = options;
 	const { platVer, osVersion, devType } = systemInfo();
 	const deviceInfo = {
-		guid: "",
+		guid: machineGuid ?? "",
 		buildVer: fullVersion,
-		localId: 2052,
+		localId: ZH_CN_LOCALE_ID,
 		devName: (0, node_os.hostname)(),
 		devType,
 		vendorName: "",
@@ -2941,9 +3010,25 @@ function buildSessionConfig(options) {
 		},
 		defaultFileDownloadPath: downloadPath,
 		deviceInfo,
-		deviceConfig: "{\"appearance\":{\"isSplitViewMode\":true},\"msg\":{}}"
+		deviceConfig: DEVICE_CONFIG_JSON
 	};
 }
+/**
+* 读取设备指纹 guid（wrapper.node 字符串分析实证，2026-08-12）：
+* NodeIKernelLoginService::getMachineGuid（0 参，返回机器 GUID 字符串）。
+* 无 getMachineId 方法——TODO 里的方法名不存在，等价方法是 getMachineGuid。
+* 失败（无该方法 / 调用抛错 / 返回值非字符串）兜底空串。
+*/
+function readMachineGuid(loginService) {
+	try {
+		const fn = loginService?.["getMachineGuid"];
+		if (typeof fn !== "function") return "";
+		const value = fn.call(loginService);
+		return typeof value === "string" ? value : "";
+	} catch {
+		return "";
+	}
+}
 //#endregion
 //#region src/wrapper/wrapper-loader.ts
 /**
@@ -3099,7 +3184,7 @@ function startSession(ctx) {
 *  2. createSession（`new NodeIQQNTWrapperSession()`）——实测可用，默认路径
 *  （getMainSession 实测为空壳：service 全 null + 缺 startNT，仅 probe 探测参考）
 *
-* 由 loader runtime/boot.cjs 在 QQ 主进程内调用（import kernel dist 后）。
+* 由 kernel NapukettoCore（core.ts）装配调用；loader 自建宿主 bootstrap 也直接调用作回退。
 * 返回 WrapperContext；失败抛 KernelError。
 */
 function startNapuketto(options) {
@@ -3185,7 +3270,8 @@ function getOrCreateLoginService(exports) {
 * 典型用法（boot.cjs 截获 exports 后）：
 *   const core = await NapukettoCore.create({ dataRoot, account });
 *   core.attachWrapper(wrapperExports, { qqVersion, dataDir });
-*   await core.login({ appid: "537237765" });
+*   // appid 由 resolveAppidQua 从 major.node 动态解析（版本绑定，不写死）
+*   await core.login({ appid });
 *
 * 与手动拼 startNapuketto/quickLogin/initAndStartSession 等价，但把装配状态
 * （ctx）集中管理，协议层直接消费 core.ctx。
@@ -3197,6 +3283,8 @@ function getOrCreateLoginService(exports) {
 var NapukettoCore = class NapukettoCore {
 	/** 装配根（协议层 / apis / cache 的消费入口）。 */
 	ctx;
+	/** QR 登录会话句柄（登录期间非空；登录终态后清空）。refreshQr() 据此可达。 */
+	qrSession = null;
 	/** 由 create() 装配，不直接 new。 */
 	constructor(ctx) {
 		this.ctx = ctx;
@@ -3252,6 +3340,11 @@ var NapukettoCore = class NapukettoCore {
 		const { wrapper } = this.ctx;
 		if (wrapper === null) throw kernelError("wrapper 未装配，无法登录", "INVALID_STATE");
 		this.initLoginConfig(wrapper, opts.appid);
+		if (opts.qrOnly === true) {
+			const loginResult = await this.loginByQr(opts);
+			this.ctx.login = loginResult;
+			return loginResult;
+		}
 		let loginResult;
 		try {
 			const quickOpts = {};
@@ -3295,23 +3388,37 @@ var NapukettoCore = class NapukettoCore {
 		if (this.ctx.wrapper === null) throw kernelError("wrapper 未装配，无法设置 session", "INVALID_STATE");
 		this.ctx.wrapper.session = session;
 	}
+	/**
+	* 手动刷新二维码（QR 登录期间可用）。返回是否成功触发（false = 当前不在扫码态）。
+	* koishi 前端「刷新二维码」按钮经 loader IPC `login.refreshQr` 动作直达。
+	*/
+	refreshQr() {
+		if (this.qrSession === null) return false;
+		this.qrSession.refresh();
+		return true;
+	}
 	/** QR 登录：QrLoginSession 状态机 + 二维码写缓存目录（无 UI，cli 可打印路径）。 */
 	async loginByQr(opts) {
 		const { wrapper } = this.ctx;
 		if (wrapper === null || wrapper.loginService === null) throw kernelError("wrapper/loginService 不可用，无法 QR 登录", "INVALID_STATE");
 		const session = new QrLoginSession(wrapper.loginService);
+		this.qrSession = session;
 		const qrPath = opts.qrCodePath ?? this.ctx.paths.file("cache", "qrcode.png");
 		this.subscribeQrProgress(session, opts, qrPath);
-		session.start();
-		await waitQrLoggedIn(session);
-		const self = session.selfInfo;
-		if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
-		session.stop();
-		return {
-			uin: self.uin,
-			uid: self.uid,
-			nick: self.nick
-		};
+		try {
+			session.start();
+			await waitQrLoggedIn(session);
+			const self = session.selfInfo;
+			if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
+			return {
+				uin: self.uin,
+				uid: self.uid,
+				nick: self.nick
+			};
+		} finally {
+			session.stop();
+			this.qrSession = null;
+		}
 	}
 	/** 订阅 QR 进度：二维码写盘 + 状态机经 onLoginProgress 转发。 */
 	subscribeQrProgress(session, opts, qrPath) {
@@ -3325,7 +3432,11 @@ var NapukettoCore = class NapukettoCore {
 		});
 		session.onStateChange((state) => {
 			this.ctx.logger.info({ state }, "QR 登录状态");
-			opts.onLoginProgress?.({ state });
+			const message = state === "failed" ? session.failureReason ?? void 0 : void 0;
+			opts.onLoginProgress?.({
+				state,
+				...message !== void 0 ? { message } : {}
+			});
 		});
 	}
 	/** 停止：日志收尾（资源清理留给 P2 常驻管理）。 */
@@ -4104,6 +4215,7 @@ exports.parseAppidFromMajor = parseAppidFromMajor;
 exports.parseToml = parseToml;
 exports.probeRuntime = probeRuntime;
 exports.quickLogin = quickLogin;
+exports.readMachineGuid = readMachineGuid;
 exports.resolveAppidQua = resolveAppidQua;
 exports.resolveConfigPath = resolveConfigPath;
 exports.resolveDataRoot = resolveDataRoot;

package/dist/index.d.cts

@@ -977,6 +977,7 @@ interface NodeQQNTWrapperUtil {
 interface EnginInitDesktopConfig {
   base_path_prefix: string;
   platform_type: PlatformType;
+  /** 桌面端应用类型（engine.initWithDeskTopConfig 契约，桌面端固定 4；移动端为其它值）。 */
   app_type: 4;
   app_version: string;
   os_version: string;
@@ -985,6 +986,10 @@ interface EnginInitDesktopConfig {
   global_path_config: {
     desktopGlobalPath: string;
   };
+  /**
+   * 缩略图生成参数（wrapper 契约）：maxSide 最长边上限 / minSide 最短边下限 /
+   * longLimit 长图最长短边比例上限 / density 像素密度倍数。
+   */
   thumb_config: {
     maxSide: 324;
     minSide: 48;
@@ -1107,6 +1112,8 @@ interface NodeIKernelLoginService {
   quickLoginWithUin(uin: string): Promise<unknown>;
   getQRCodePicture(): boolean;
   getMsfStatus(): number;
+  /** 设备指纹 guid（wrapper.node 字符串分析实证，2026-08-12；无 getMachineId）。 */
+  getMachineGuid(): string;
 }
 /** NodeIKernelLoginService 构造器（含静态 get）。 */
 type NodeIKernelLoginServiceCtor = new () => NodeIKernelLoginService & {
@@ -1468,9 +1475,9 @@ declare class MsgApi {
    * 且发送后进程崩溃重启（supervisor 自动拉起）。完整字段（NapCat 同款，
    * formatType/voiceType/canConvert2Text/waveAmplitudes 等）消除该错误。
    *
-   * ⚠️ silk 格式：QQ 语音协议为 silk v3。传入非 silk（ogg/mp3 等）时发送器
-   * 可能拒绝上传（待实测）。转换点预留：此处直接放置原文件，后续接入
-   * ogg → PCM → silk 编码器（外部 ffmpeg + silk-wasm，见 docs/design.md）。
+   * ⚠️ silk 格式：QQ 语音协议为 silk v3。非 silk → silk 的转码在协议层
+   * （adapter，@napuketto/media 的 encodePcmToSilk，2026-08-12 接线）完成，
+   * 此处接收的已是 silk 路径，仅做放置。kernel 不 import media（解耦红线）。
    */
   private preparePttElement;
   /**
@@ -2026,7 +2033,7 @@ declare function startSession(ctx: WrapperContext): void;
  *  2. createSession（`new NodeIQQNTWrapperSession()`）——实测可用，默认路径
  *  （getMainSession 实测为空壳：service 全 null + 缺 startNT，仅 probe 探测参考）
  *
- * 由 loader runtime/boot.cjs 在 QQ 主进程内调用（import kernel dist 后）。
+ * 由 kernel NapukettoCore（core.ts）装配调用；loader 自建宿主 bootstrap 也直接调用作回退。
  * 返回 WrapperContext；失败抛 KernelError。
  */
 declare function startNapuketto(options: StartNapukettoOptions): WrapperContext;
@@ -2138,11 +2145,21 @@ declare class QrLoginSession {
   private self;
   private readonly qrCodeHandlers;
   private readonly stateHandlers;
-  constructor(loginService: unknown);
+  /** 超时定时器（refresh 后启动，登录成功/失败/stop 清理）。 */
+  private timeoutTimer;
+  /** 失败原因（超时等，failed 态透出给上层提示文案）。 */
+  private failureReasonValue;
+  /** 超时上限（毫秒，默认 QR_LOGIN_TIMEOUT_MS）。 */
+  private readonly timeoutMs;
+  constructor(loginService: unknown, options?: {
+    timeoutMs?: number;
+  });
   /** 当前状态。 */
   get currentState(): LoginState;
   /** selfInfo（登录成功后有值）。 */
   get selfInfo(): SelfInfo | null;
+  /** 失败原因（超时等；failed 态透出给上层提示文案）。 */
+  get failureReason(): string | null;
   /** 订阅二维码（png base64 + url）。返回退订函数。 */
   onQrCode(cb: (qr: QrCodeData) => void): () => void;
   /** 订阅状态变化。返回退订函数。 */
@@ -2151,12 +2168,16 @@ declare class QrLoginSession {
   start(opts?: {
     quickUin?: string;
   }): void;
-  /** 刷新二维码（手动 / 过期自动）。 */
+  /** 刷新二维码（手动 / 过期自动）。每次出码重启超时计时。 */
   refresh(): void;
   /** 构建登录监听（普通 JS 对象，NAPI 反射）。 */
   private buildListener;
   /** 停止：注销监听（登录成功后调用，防重复回调）。 */
   stop(): void;
+  /** 重启超时计时器：超时未登录 → failed + 超时提示。 */
+  private restartTimeout;
+  /** 清理超时计时器（幂等）。 */
+  private clearTimeoutTimer;
   private setState;
   private emitQrCode;
 }
@@ -2202,10 +2223,12 @@ interface LoginProgress {
   qr?: QrCodeData;
   /** 登录成功 selfInfo（state=logged_in 时有）。 */
   selfInfo?: SelfInfo;
+  /** 失败原因（state=failed 时有；如「登录超时，请刷新页面重试」）。 */
+  message?: string;
 }
 /** login 参数。 */
 interface CoreLoginOptions {
-  /** appid（登录握手，兜底 537237765）。 */
+  /** appid（登录握手，由 resolveAppidQua 从 major.node 动态解析，不写死）。 */
   appid: string;
   /** session.init 超时（毫秒），默认 15s。 */
   initTimeoutMs?: number;
@@ -2213,6 +2236,8 @@ interface CoreLoginOptions {
   quickUin?: string;
   /** 快速登录失败时回退 QR 登录（二维码写缓存目录），默认 false。 */
   qrFallback?: boolean;
+  /** 强制扫码：跳过快速登录，直接走 QR 登录（koishi 强制扫码 / 切账号）。默认 false。 */
+  qrOnly?: boolean;
   /** QR 二维码图片保存路径（默认缓存目录 qrcode.png）。 */
   qrCodePath?: string;
   /** 登录进度回调（QR 阶段：二维码数据 + 状态变化）。子进程 IPC 模式转发用。 */
@@ -2225,6 +2250,8 @@ interface CoreLoginOptions {
 declare class NapukettoCore {
   /** 装配根（协议层 / apis / cache 的消费入口）。 */
   readonly ctx: CoreContext;
+  /** QR 登录会话句柄（登录期间非空；登录终态后清空）。refreshQr() 据此可达。 */
+  private qrSession;
   /** 由 create() 装配，不直接 new。 */
   private constructor();
   /**
@@ -2265,6 +2292,11 @@ declare class NapukettoCore {
    * 在 QQ 主进程内由 boot.cjs 调用（登录成功后）。
    */
   setSession(session: NodeIQQNTWrapperSession): void;
+  /**
+   * 手动刷新二维码（QR 登录期间可用）。返回是否成功触发（false = 当前不在扫码态）。
+   * koishi 前端「刷新二维码」按钮经 loader IPC `login.refreshQr` 动作直达。
+   */
+  refreshQr(): boolean;
   /** QR 登录：QrLoginSession 状态机 + 二维码写缓存目录（无 UI，cli 可打印路径）。 */
   private loginByQr;
   /** 订阅 QR 进度：二维码写盘 + 状态机经 onLoginProgress 转发。 */
@@ -2333,20 +2365,20 @@ declare function createLoginListener(): IKernelLoginListener;
 /**
  * 从 major.node 提取 appid（NapCat parseAppidFromMajorV2 的自研等价实现）。
  * major.node 含 `QQAppId/` 标记后跟数字（腾讯工具链产物，实测确认）。
- * 返回 null 表示解析失败（调用方回退硬编码表）。
+ * 返回 null 表示解析失败（调用方应显式报错，不再回退硬编码 appid）。
  */
 declare function parseAppidFromMajor(majorPath: string): string | null;
 /**
  * 解析 appid / qua（自研，参考 NapCat QQBasicInfoWrapper 思路但独立实现）：
- *  1. 优先从 major.node 提取 appid（实测 9.9.33-51802 = 537376818）
- *  2. 回退硬编码表（旧版 537237765）
- * majorPath 传 wrapper.node 同目录 major.node；不传则跳过 major 解析。
+ * appid 唯一来源 = major.node 提取（实测 9.9.33-51802 = 537376818）。
+ * majorPath 缺省或解析失败时抛 KernelError——不再静默回退过期 appid。
+ * majorPath 传 wrapper.node 同目录 major.node。
  */
 declare function resolveAppidQua(fullVersion: string, majorPath?: string): {
   appid: string;
   qua: string;
 };
-/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（解析 appid/qua）。 */
+/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（缺失/解析失败会抛错）。 */
 declare function buildEngineConfig(fullVersion: string, dataPathGlobal: string, majorPath?: string): EnginInitDesktopConfig;
 /** 生成登录初始化配置（externalVersion: false 与 NapCat 同款，扫码兼容关键）。 */
 declare function buildLoginConfig(appid: string, fullVersion: string, commonPath: string): Record<string, unknown>;
@@ -2358,9 +2390,18 @@ interface SessionConfigOptions {
   selfUid: string;
   accountPath: string;
   downloadPath: string;
+  /** 设备指纹 guid（来自 loginService.getMachineGuid()；缺省空串）。 */
+  machineGuid?: string;
 }
 /** 生成 session 初始化配置（登录成功后调用）。 */
 declare function buildSessionConfig(options: SessionConfigOptions): WrapperSessionInitConfig;
+/**
+ * 读取设备指纹 guid（wrapper.node 字符串分析实证，2026-08-12）：
+ * NodeIKernelLoginService::getMachineGuid（0 参，返回机器 GUID 字符串）。
+ * 无 getMachineId 方法——TODO 里的方法名不存在，等价方法是 getMachineGuid。
+ * 失败（无该方法 / 调用抛错 / 返回值非字符串）兜底空串。
+ */
+declare function readMachineGuid(loginService: unknown): string;
 //#endregion
 //#region src/wrapper/wrapper-version.d.ts
 /**
@@ -2397,5 +2438,5 @@ interface QQVersionInfo {
   qua: string;
 }
 //#endregion
-export { type BootEnv, type BuddyCategory, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogLevel, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { type BootEnv, type BuddyCategory, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogLevel, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 //# sourceMappingURL=index.d.cts.map