@napuketto/loader 0.0.9 → 0.0.10

package/dist/index.cjs

@@ -0,0 +1,849 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_process = require("node:process");
+node_process = __toESM(node_process, 1);
+let node_child_process = require("node:child_process");
+let node_url = require("node:url");
+let node_fs_promises = require("node:fs/promises");
+let node_crypto = require("node:crypto");
+let node_https = require("node:https");
+//#region src/instance-lock.ts
+/**
+* instance-lock.ts：单实例锁（2026-08-07 根治「多实例抢数据目录锁挂起」）
+*
+* 背景（实测）：同一账号数据目录（~/.napuketto/<uin>）只能被一个实例持有——
+* QQ 原生层（MMKV / 登录单例 / 数据库）有锁，第二个实例抢不到锁会卡在
+* loginService.initConfig 之后无响应（挂起）。此前 create-napukettoqq 生成的
+* 副本实例常驻占锁，导致用户后续启动全部卡死。
+*
+* 方案：以数据目录为粒度加锁文件 `<dataDir>/instance.lock`（JSON 内容：
+* pid / startedAt / cmdline 摘要）。启动前 checkInstanceLock：
+*   - 锁不存在 → 可启动（然后 acquireInstanceLock 写入）
+*   - 锁存在但 PID 已死 → 崩溃残留，自动清理（rm + 重新获取）
+*   - 锁存在且 PID 存活 → 已被占用，拒绝启动（返回占用 PID 供提示）
+*
+* 退出清理：进程正常退出时 releaseInstanceLock 删除锁文件；崩溃/强杀残留
+* 由下次启动的「PID 存活检测」兜底（PID 已死 → 残留视为过期）。
+*
+* 放置说明：放 loader 而非 kernel——self-host.cjs 是 rolldown 内联 bundle
+* （只内联 src/host/ 依赖树），静态 import kernel 会留 external 缺口；
+* 放 loader 则 self-host（内联）与 cli（@napuketto/loader 导入）双入口可用。
+*/
+/** 锁文件名（置于数据目录内）。 */
+const INSTANCE_LOCK_FILE = "instance.lock";
+/**
+* 检测指定数据目录是否已被其他实例占用。
+*
+* @param dataDir 数据目录（账号级，如 ~/.napuketto/3567141148）
+*/
+function checkInstanceLock(dataDir) {
+	const lockPath = (0, node_path.join)(dataDir, INSTANCE_LOCK_FILE);
+	let info = null;
+	try {
+		info = JSON.parse((0, node_fs.readFileSync)(lockPath, "utf-8"));
+	} catch {
+		return {
+			occupied: false,
+			pid: null,
+			lockPath
+		};
+	}
+	if (typeof info.pid !== "number" || Number.isNaN(info.pid) || info.pid <= 0) return {
+		occupied: false,
+		pid: null,
+		lockPath
+	};
+	let alive = false;
+	try {
+		node_process.default.kill(info.pid, 0);
+		alive = true;
+	} catch {
+		alive = false;
+	}
+	if (!alive) return {
+		occupied: false,
+		pid: null,
+		lockPath
+	};
+	return {
+		occupied: true,
+		pid: info.pid,
+		lockPath
+	};
+}
+/**
+* 获取数据目录锁。占用（其他实例存活）返回 false；成功或清理残留后返回 true。
+* 幂等：本进程已持有则直接返回 true（不重复写）。
+*/
+function acquireInstanceLock(dataDir, cmdline) {
+	const { occupied, pid, lockPath } = checkInstanceLock(dataDir);
+	if (occupied) {
+		if (pid === node_process.default.pid) return true;
+		return false;
+	}
+	const info = {
+		pid: node_process.default.pid,
+		startedAt: Date.now(),
+		...cmdline !== void 0 && cmdline !== "" ? { cmdline } : {}
+	};
+	try {
+		(0, node_fs.rmSync)(lockPath, { force: true });
+		(0, node_fs.writeFileSync)(lockPath, JSON.stringify(info), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 释放数据目录锁（正常退出时调用）。仅当持有者是本进程时才删除，
+* 避免误删新持有者的锁（PID 复用 / 快速重启场景）。
+*/
+function releaseInstanceLock(dataDir) {
+	const lockPath = (0, node_path.join)(dataDir, INSTANCE_LOCK_FILE);
+	try {
+		if (JSON.parse((0, node_fs.readFileSync)(lockPath, "utf-8")).pid === node_process.default.pid) (0, node_fs.rmSync)(lockPath, { force: true });
+	} catch {}
+}
+/** 注册进程退出清理（SIGINT/SIGTERM/exit 均触发；崩溃强杀由残留检测兜底）。 */
+function registerLockCleanup(dataDir) {
+	node_process.default.on("exit", () => {
+		releaseInstanceLock(dataDir);
+	});
+}
+//#endregion
+//#region src/qq-download.ts
+/**
+* qq-download.ts：QQ 官方安装包下载器（P1）。
+*
+* 无第三方依赖：Node 内置 https + crypto（sha256）。设计文档 §2.2。
+*  - https GET 流式写文件（低内存占用，313MB 安装包不整载入内存）
+*  - 下载同时流式累加 sha256，完成后与清单比对（防链接漂移劫持 / 下载不完整）
+*  - 支持 302 重定向（QQ CDN 可能跳转）
+*  - NAPUTO_QQ_URL 环境变量可覆盖下载地址（用户拿到新链接时用）
+*/
+/** 下载中断（超时 / 非 2xx / 网络错误）抛出的错误。 */
+var DownloadError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DownloadError";
+	}
+};
+/** 发起一次 https GET，返回响应（跟随重定向，最多 5 跳）。 */
+function httpsGet(url, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const request = (currentUrl, redirects) => {
+			const req = (0, node_https.get)(currentUrl, { headers: { "user-agent": "napuketto-loader/0.0.x" } }, (res) => {
+				const status = res.statusCode ?? 0;
+				if (status >= 300 && status < 400 && res.headers["location"] !== void 0) {
+					res.resume();
+					if (redirects >= 5) {
+						reject(new DownloadError(`重定向次数过多: ${currentUrl}`));
+						return;
+					}
+					request(new URL(res.headers["location"], currentUrl).toString(), redirects + 1);
+					return;
+				}
+				if (status !== 200) {
+					res.resume();
+					reject(new DownloadError(`HTTP ${status}: ${currentUrl}`));
+					return;
+				}
+				resolve(res);
+			});
+			req.setTimeout(timeoutMs, () => {
+				req.destroy(new DownloadError(`下载超时(${timeoutMs}ms): ${currentUrl}`));
+			});
+			req.on("error", (err) => {
+				reject(err instanceof Error ? err : new DownloadError(String(err)));
+			});
+		};
+		request(url, 0);
+	});
+}
+/**
+* 下载文件并（可选）校验 sha256。失败时清理半成品文件。
+* 返回实际 sha256（无论是否校验），便于调用方回填清单。
+*/
+async function downloadFile(options) {
+	const url = options.url ?? node_process.default.env["NAPUTO_QQ_URL"];
+	if (url === void 0 || url === "") throw new DownloadError("下载地址为空：请设置 NAPUTO_QQ_URL 或提供清单 URL");
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(options.dest), { recursive: true });
+	const hash = (0, node_crypto.createHash)("sha256");
+	const fileStream = (0, node_fs.createWriteStream)(options.dest);
+	let fileFailed = false;
+	try {
+		const res = await httpsGet(url, timeoutMs);
+		await new Promise((resolve, reject) => {
+			res.on("data", (chunk) => {
+				hash.update(chunk);
+			});
+			res.on("error", (err) => {
+				fileFailed = true;
+				reject(err instanceof Error ? err : new DownloadError(String(err)));
+			});
+			fileStream.on("error", (err) => {
+				fileFailed = true;
+				reject(err);
+			});
+			fileStream.on("finish", () => {
+				resolve();
+			});
+			res.pipe(fileStream);
+		});
+	} catch (err) {
+		fileStream.destroy();
+		if (!fileFailed) await (0, node_fs_promises.rm)(options.dest, { force: true });
+		throw err instanceof Error ? err : new DownloadError(String(err));
+	}
+	const sha256 = hash.digest("hex");
+	const expected = options.expectedSha256;
+	const verified = expected === void 0 || expected === "" ? true : sha256.toLowerCase() === expected.toLowerCase();
+	if (!verified) {
+		await (0, node_fs_promises.rm)(options.dest, { force: true });
+		throw new DownloadError(`sha256 校验失败: ${options.dest}\n期望 ${expected}\n实际 ${sha256}`);
+	}
+	return {
+		sha256,
+		verified
+	};
+}
+//#endregion
+//#region src/qq-extract.ts
+/**
+* qq-extract.ts：QQ 官方安装包解包与提取（P1）。
+*
+* ⚠️ 格式事实（2026-08-12 实测修正）：QQ 官方安装包是 NSIS 自解压格式，
+* **7za standalone 不支持 NSIS**（只支持 7z/zip/tar 等）——必须用完整版
+* 7z（7z.exe + 7z.dll）。设计文档 §2.3 原「内置 7za.exe」修正为：
+*  - Windows：内置 assets/7zip/7z.exe + 7z.dll（7-Zip 官方，LGPL 合规可分发）
+*  - Linux/Docker：系统 p7zip-full（7z 完整版）
+*
+* ⚠️ 提取策略（2026-08-12 实测修正，与设计 §2.3 不同）：
+*  1. NSIS 解包产物在 <extracted>/Files/（NSIS 内部布局），Files/ = 安装根
+*  2. 真实 QQNT.dll（214MB）位于 versions/<v>/QQNT.dll，**自建宿主不需要**
+*     ——stub QQNT.dll 已替代其宿主符号职责（wrapper.node 的 v8/node/napi/qq_magic
+*     符号由 stub 转发到 node.exe）
+*  3. 只提取 resources/app 顶层 *.node + *.dll（wrapper.node 的直接/传递/delay-load
+*     依赖全覆盖，版本无关；跳过 wmpfsdk/avsdk 等大子目录，共约 235MB）
+*
+* 提取目标（与安装目录同构，resolveFromRoot 可直接消费）：
+*   <数据根>/qq-files/<版本>/versions/<版本>/resources/app/   ← *.node + *.dll
+*/
+/** resources/app 下需要提取的文件扩展名（.node 原生模块 + .dll 依赖）。 */
+const EXTRACT_EXTENSIONS = /* @__PURE__ */ new Set([".node", ".dll"]);
+/**
+* 探测 7z 可执行文件：
+*   NAPUTO_7Z_PATH 环境变量 > 内置资产（assets/7zip/7z.exe，Windows）> 系统 PATH 7z。
+* Linux 上用 p7zip 提供的 7z 命令（系统 PATH）。
+*/
+function findSevenZip() {
+	const envPath = node_process.default.env["NAPUTO_7Z_PATH"];
+	if (envPath !== void 0 && envPath !== "" && (0, node_fs.existsSync)(envPath)) return {
+		exe: envPath,
+		source: "环境变量 NAPUTO_7Z_PATH"
+	};
+	if (node_process.default.platform === "win32") {
+		const bundled = (0, node_path.join)((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)), "..", "assets", "7zip", "7z.exe");
+		if ((0, node_fs.existsSync)(bundled)) return {
+			exe: bundled,
+			source: "内置资产 assets/7zip"
+		};
+	}
+	return {
+		exe: "7z",
+		source: "系统 PATH"
+	};
+}
+/** 解包安装包到指定目录（spawn 7z x，失败抛错）。 */
+async function extractInstaller(installerPath, destDir, sevenZipPath) {
+	const sevenZip = sevenZipPath ?? findSevenZip().exe;
+	await (0, node_fs_promises.mkdir)(destDir, { recursive: true });
+	await new Promise((resolve, reject) => {
+		(0, node_child_process.execFile)(sevenZip, [
+			"x",
+			installerPath,
+			`-o${destDir}`,
+			"-y"
+		], { maxBuffer: 67108864 }, (err, _stdout, stderr) => {
+			if (err !== null) {
+				const hint = err.code === "ENOENT" ? `未找到 7z 可执行文件: ${sevenZip}\n（Windows 请安装 7-Zip 或用 NAPUTO_7Z_PATH 指定；Linux 请安装 p7zip-full）` : "（QQ 安装包是 NSIS 格式，需完整版 7z 而非 7za）";
+				reject(/* @__PURE__ */ new Error(`7z 解包失败: ${installerPath}\n${stderr.trim()}\n${hint}`));
+				return;
+			}
+			resolve();
+		});
+	});
+}
+/**
+* 从解包目录提取运行所需文件到缓存：
+* resources/app 顶层全部 *.node + *.dll（保持同目录结构，PATH 前置即可解析依赖）。
+* 幂等：目标 wrapper.node 已存在则跳过。
+*/
+async function extractWrapperFiles(extractedDir, version, cacheRoot) {
+	const appDir = (0, node_path.join)(extractedDir, "Files", "versions", version, "resources", "app");
+	if (!(0, node_fs.existsSync)((0, node_path.join)(appDir, "wrapper.node"))) throw new Error(`解包产物缺少 wrapper.node: ${appDir}`);
+	const destAppDir = (0, node_path.join)(cacheRoot, version, "versions", version, "resources", "app");
+	const destWrapper = (0, node_path.join)(destAppDir, "wrapper.node");
+	if ((0, node_fs.existsSync)(destWrapper)) return buildCachedInfo(cacheRoot, version);
+	await (0, node_fs_promises.mkdir)(destAppDir, { recursive: true });
+	const entries = await (0, node_fs_promises.readdir)(appDir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const dot = entry.name.lastIndexOf(".");
+		const ext = dot >= 0 ? entry.name.slice(dot).toLowerCase() : "";
+		if (!EXTRACT_EXTENSIONS.has(ext)) continue;
+		await (0, node_fs_promises.copyFile)((0, node_path.join)(appDir, entry.name), (0, node_path.join)(destAppDir, entry.name));
+	}
+	if (!(0, node_fs.existsSync)(destWrapper)) throw new Error(`提取失败：wrapper.node 未复制到 ${destWrapper}`);
+	return buildCachedInfo(cacheRoot, version);
+}
+/** 构造 cached 来源的 QqInstallInfo（wrapperPath 指向缓存中 wrapper.node）。 */
+function buildCachedInfo(cacheRoot, version) {
+	const versionDir = (0, node_path.join)(cacheRoot, version);
+	return {
+		qqPath: (0, node_path.join)(versionDir, "QQ.exe"),
+		installDir: versionDir,
+		version,
+		wrapperPath: (0, node_path.join)(versionDir, "versions", version, "resources", "app", "wrapper.node"),
+		source: "cached"
+	};
+}
+/** 清理缓存版本目录（下载/解包失败残留，供调用方兜底）。 */
+async function clearCacheVersion(cacheRoot, version) {
+	await (0, node_fs_promises.rm)((0, node_path.join)(cacheRoot, version), {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+//#region src/win-node.ts
+/**
+* win-node.ts：Windows 版 node.exe 获取（P2，Linux/wine 场景用）。
+*
+* wine 只能跑 Windows PE 程序——自建宿主在 Linux 上必须用 Windows 版 node.exe
+* 作为宿主（wrapper.node 是 PE 原生模块，只能被 Windows node.exe dlopen）。
+* 来源：nodejs.org 官方 zip（开源软件官方发行版，但为保守起见同样不内置，
+* 运行时下载到 <数据根>/runtime/win-node/，可被 NAPUTO_WIN_NODE_PATH 覆盖）。
+*
+* 设计文档 §3.1。与 qq-download.ts 同构：https 下载 + 解压 + 缓存幂等。
+*/
+/** 目标 Windows node.exe 可执行文件名（zip 内）。 */
+const WIN_NODE_EXE = "node.exe";
+/** 运行时缓存子目录名（<数据根>/runtime/win-node/）。 */
+const WIN_NODE_DIR_NAME = "win-node";
+/** 解析 nodejs.org zip URL（与 dist 目录命名一致）。 */
+function nodeZipUrl(version) {
+	return `https://nodejs.org/dist/${version}/node-${version}-win-x64.zip`;
+}
+/**
+* 确保 Windows 版 node.exe 就绪（下载 + 解压 + 缓存）。
+* 幂等：<数据根>/runtime/win-node/<version>/node.exe 已存在则直接返回。
+*/
+async function ensureWinNode(options = {}) {
+	const explicit = options.exePath ?? node_process.default.env["NAPUTO_WIN_NODE_PATH"];
+	if (explicit !== void 0 && explicit !== "" && (0, node_fs.existsSync)(explicit)) return {
+		exePath: (0, node_path.resolve)(explicit),
+		version: "explicit"
+	};
+	const version = options.version ?? node_process.default.env["NAPUTO_WIN_NODE_VERSION"] ?? DEFAULT_WIN_NODE_VERSION;
+	const dataRoot = resolveDataRoot(options.dataRoot);
+	const cacheDir = (0, node_path.join)(dataRoot, "runtime", WIN_NODE_DIR_NAME, version);
+	const exePath = (0, node_path.join)(cacheDir, WIN_NODE_EXE);
+	if ((0, node_fs.existsSync)(exePath)) return {
+		exePath,
+		version
+	};
+	const zipPath = (0, node_path.join)(cacheDir, `node-${version}-win-x64.zip`);
+	const url = node_process.default.env["NAPUTO_WIN_NODE_URL"] ?? nodeZipUrl(version);
+	(0, node_fs.mkdirSync)(cacheDir, { recursive: true });
+	try {
+		await downloadFile({
+			dest: zipPath,
+			url
+		});
+		await unzipNode(zipPath, cacheDir);
+	} finally {
+		await (0, node_fs_promises.rm)(zipPath, { force: true });
+	}
+	if (!(0, node_fs.existsSync)(exePath)) throw new Error(`解压后未找到 node.exe: ${exePath}`);
+	return {
+		exePath,
+		version
+	};
+}
+/** 解压 node zip（zip 内为 node-<version>-win-x64/ 目录，取其中 node.exe 移到缓存根）。 */
+async function unzipNode(zipPath, cacheDir) {
+	const tmpDir = (0, node_path.join)(cacheDir, "_zip");
+	await extractInstaller(zipPath, tmpDir);
+	const nodeDir = (await (0, node_fs_promises.readdir)(tmpDir)).find((n) => n.startsWith("node-"));
+	const src = nodeDir === void 0 ? (0, node_path.join)(tmpDir, WIN_NODE_EXE) : (0, node_path.join)(tmpDir, nodeDir, WIN_NODE_EXE);
+	if (!(0, node_fs.existsSync)(src)) throw new Error(`node zip 解压后未找到 node.exe: ${src}`);
+	await (0, node_fs_promises.copyFile)(src, (0, node_path.join)(cacheDir, WIN_NODE_EXE));
+	await (0, node_fs_promises.rm)(tmpDir, {
+		recursive: true,
+		force: true
+	});
+}
+/** 默认 Windows node 版本（latest v24，LTS 线；可被环境变量/参数覆盖）。 */
+const DEFAULT_WIN_NODE_VERSION = "v24.16.0";
+/** 轻量数据根解析（与 locate-qq 内同构，避免循环依赖）。 */
+function resolveDataRoot(dataRoot) {
+	const explicit = dataRoot ?? node_process.default.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return (0, node_path.resolve)(explicit);
+	const projectRoot = findProjectRoot$1(node_process.default.cwd()) ?? node_process.default.cwd();
+	return (0, node_path.join)(projectRoot, ".napuketto");
+}
+/** 向上探测项目根（含 pnpm-workspace.yaml 或 package.json 的目录）。 */
+function findProjectRoot$1(start) {
+	let dir = (0, node_path.resolve)(start);
+	for (;;) {
+		if ((0, node_fs.existsSync)((0, node_path.join)(dir, "pnpm-workspace.yaml")) || (0, node_fs.existsSync)((0, node_path.join)(dir, "package.json"))) return dir;
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+//#endregion
+//#region src/wine.ts
+/**
+* wine.ts：Linux 上经 wine 运行 Windows 版 node.exe 的路径与 spawn 组装（P2）。
+*
+* 设计文档 §3.2（2026-08-12 拍板确认）。核心认知：
+*  - Windows 版 node.exe 在 wine 内把 Linux 根目录挂载在 `Z:\`
+*  - process.dlopen / 环境变量路径都是 wine 视角的 Windows 路径
+*  - 传给 wine 子进程的**所有路径**（wrapperPath / cfgDir / stubDir / self-host.cjs / PATH）
+*    都要过 toWinePath 转成 `Z:\...`
+*
+* 纯函数设计：不 import node:child_process，方便 Windows 上单测断言（P2 纯逻辑层）。
+*/
+/** Linux 绝对路径 → wine `Z:\` 路径（Windows 版 node.exe 视角）。幂等：已是 Windows 路径（含盘符）原样返回。 */
+function toWinePath(linuxPath) {
+	if (DRIVE_LETTER_RE.test(linuxPath)) return linuxPath;
+	return `Z:\\${linuxPath.replaceAll("/", "\\").replace(LEADING_SLASH_RE, "")}`;
+}
+/** 前导斜杠（toWinePath 去根用，顶层常量避免每次调用重建）。 */
+const LEADING_SLASH_RE = /^\\/;
+/** 盘符前缀（C: / Z: 等，识别已转换的 Windows 路径）。 */
+const DRIVE_LETTER_RE = /^[A-Za-z]:/;
+/** 判断当前是否 Linux（需 wine 的场景）。 */
+function isLinux() {
+	return process.platform === "linux";
+}
+/** wine 可执行文件（Linux 上 spawn 用；可被 NAPUTO_WINE 覆盖）。 */
+function wineBinary() {
+	return process.env["NAPUTO_WINE"] ?? "wine";
+}
+/** 组装 spawn 命令（win32 vs linux 分支）。 */
+function buildSpawnCommand(options) {
+	if ((options.platform ?? process.platform) === "win32") return {
+		command: options.winNodePath ?? process.execPath,
+		args: [options.selfHostPath]
+	};
+	return {
+		command: options.wine ?? wineBinary(),
+		args: [options.winNodePath ?? "node.exe", options.selfHostPath]
+	};
+}
+//#endregion
+//#region src/launcher.ts
+/**
+* launcher：自建宿主引导（2026-08-07 唯一路线）——spawn 标准 node 跑 self-host.cjs。
+*
+* 历史（V1/路线 B 事实链，已归档 archive/）：
+*  1. wrapper.node 只能在 QQ 定制版 Electron 里注册（实测纯 Node/普通 Electron 均 self-register 失败）
+*  2. QQ 是打包应用，禁 NODE_OPTIONS（实测 stderr）
+*  → 旧方案：NapukettoBootMain.exe 启动 QQ + 注入 NapukettoWinBootHook.dll（已废弃）
+*  → 现方案：stub QQNT.dll 转发宿主符号 → 标准 node 直接 dlopen wrapper.node（自建宿主）
+*
+* P2（2026-08-12）：平台分支——win32 本机 node；linux 经 wine 跑 Windows 版 node.exe
+* （ensureWinNode 下载）。所有传给 wine 子进程的路径过 toWinePath（Z:\）。
+*/
+const __dirname$1 = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+/**
+* 启动自建宿主（路线 A）：spawn 标准 node 直接跑 self-host.cjs，不拉起 QQ / 不注入。
+*
+* 关键（HANDOVER-V7 技术数据）：wrapper.node 从 QQNT.dll 导入 99 符号
+* （napi_*×40 + uv_*×56 + qq_magic×1 + v8/node mangled×2）——标准 node 无这些宿主
+* 符号，必须 PATH 前置 stub QQNT.dll 目录（转发到 node.exe）+ QQ resources\app
+* （wrapper.node 同目录依赖 DLL）才能 dlopen 成功。
+*
+* P2 平台分支：win32 用本机 node；linux 用 wine + Windows 版 node.exe
+* （ensureWinNode 自动下载，路径过 toWinePath）。async（win-node 可能需下载）。
+*/
+async function launchSelfHost(options) {
+	const selfHostPath = options.selfHostEntry ?? (0, node_path.join)(__dirname$1, "..", "dist", "host", "self-host.cjs");
+	if (!(0, node_fs.existsSync)(selfHostPath)) throw new Error(`self-host.cjs 缺失: ${selfHostPath}（先运行 pnpm --filter @napuketto/loader build）`);
+	const stub = options.stubDir ?? defaultStubDir();
+	if (!(0, node_fs.existsSync)((0, node_path.join)(stub, "QQNT.dll"))) throw new Error(`stub QQNT.dll 未找到: ${stub}（自建宿主必需：stub 转发 QQNT.dll 符号到 node.exe；请用 --stub-dir 或环境变量 NAPUTO_STUB_DIR 指定 stub 目录）`);
+	const { useWine, winNodePath } = await resolveNodeExecutable(options);
+	const env = buildLaunchEnv(options, useWine);
+	applyPathEnv(env, {
+		stub,
+		wrapperPath: options.qq.wrapperPath,
+		useWine
+	});
+	if (options.cwd !== void 0) (0, node_fs.mkdirSync)(options.cwd, { recursive: true });
+	const { command, args } = buildSpawnCommand({
+		...useWine && winNodePath !== void 0 ? { winNodePath } : { winNodePath: node_process.default.execPath },
+		selfHostPath: useWine ? toWinePath(selfHostPath) : selfHostPath,
+		wine: wineBinary$1()
+	});
+	return {
+		child: (0, node_child_process.spawn)(command, args, {
+			...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+			env,
+			stdio: options.stdio ?? "inherit",
+			windowsHide: false
+		}),
+		bootJsPath: selfHostPath
+	};
+}
+/** 平台分支解析 node 可执行：win32 本机；linux wine + Windows 版 node.exe。 */
+async function resolveNodeExecutable(options) {
+	if (!isLinux()) return {
+		useWine: false,
+		winNodePath: void 0
+	};
+	return {
+		useWine: true,
+		winNodePath: (await ensureWinNode({
+			...options.cwd !== void 0 ? { dataRoot: options.cwd } : {},
+			...options.winNodePath !== void 0 ? { exePath: options.winNodePath } : {}
+		})).exePath
+	};
+}
+/** 注入 PATH（stub 目录 + wrapper.node 目录前置）与 STUB_DIR（wine 场景转 Z:\）。 */
+function applyPathEnv(env, opts) {
+	const p = (linuxPath) => opts.useWine ? toWinePath(linuxPath) : linuxPath;
+	env["PATH"] = [
+		p(opts.stub),
+		p((0, node_path.dirname)(opts.wrapperPath)),
+		node_process.default.env["PATH"] ?? ""
+	].filter((entry) => entry !== void 0 && entry !== "").join(";");
+	env[ENV.STUB_DIR] = p(opts.stub);
+}
+/**
+* 默认 stub QQNT.dll 目录（loader 包内闭源 native/build/stub-test-env，开发机默认）。
+* src 与 native 同层，构建后 dist 与 native 同层——`../native` 恒正确。
+*/
+function defaultStubDir() {
+	return (0, node_path.join)(__dirname$1, "..", "native", "build", "stub-test-env");
+}
+/** 装配自建宿主环境变量（wine 场景路径转 Z:\；win32 原样）。 */
+function buildLaunchEnv(options, useWine) {
+	const cfg = (0, node_path.resolve)(options.cfgDir);
+	(0, node_fs.mkdirSync)(cfg, { recursive: true });
+	const p = (linuxPath) => useWine ? toWinePath(linuxPath) : linuxPath;
+	const env = {
+		...node_process.default.env,
+		[ENV.QQ_PATH]: p(options.qq.qqPath),
+		[ENV.KERNEL_ENTRY]: p((0, node_path.resolve)(options.kernelEntry)),
+		[ENV.CFG_DIR]: p(cfg),
+		[ENV.QQ_VERSION]: options.qq.version,
+		[ENV.WRAPPER_PATH]: p(options.qq.wrapperPath)
+	};
+	const optional = {
+		...options.selfHost === true ? { [ENV.SELF_HOST]: "1" } : {},
+		...options.adapterEntry !== void 0 ? { [ENV.ADAPTER_ENTRY]: p((0, node_path.resolve)(options.adapterEntry)) } : {},
+		...options.networkEntry !== void 0 ? { [ENV.NETWORK_ENTRY]: p((0, node_path.resolve)(options.networkEntry)) } : {},
+		...options.configPath !== void 0 ? { [ENV.CONFIG_PATH]: p((0, node_path.resolve)(options.configPath)) } : {},
+		...options.quickUin !== void 0 ? { [ENV.QUICK_UIN]: options.quickUin } : {},
+		...options.ipc === true ? { [ENV.IPC]: "1" } : {}
+	};
+	return {
+		...env,
+		...optional
+	};
+}
+/** wine 可执行文件（linux 场景；NAPUTO_WINE 可覆盖）。 */
+function wineBinary$1() {
+	return node_process.default.env["NAPUTO_WINE"] ?? "wine";
+}
+/** 环境变量名（self-host.cjs 与 kernel 引导读取）。 */
+const ENV = {
+	QQ_PATH: "NAPUTO_QQ_PATH",
+	KERNEL_ENTRY: "NAPUTO_KERNEL_ENTRY",
+	CFG_DIR: "NAPUTO_CFG_DIR",
+	QQ_VERSION: "NAPUTO_QQ_VERSION",
+	WRAPPER_PATH: "NAPUTO_WRAPPER_PATH",
+	/** 自建宿主：标准 node + stub QQNT.dll 引导（self-host.cjs 分支）。 */
+	SELF_HOST: "NAPUTO_SELF_HOST",
+	/** stub QQNT.dll 目录（launchSelfHost 注入，self-host.cjs 诊断用）。 */
+	STUB_DIR: "NAPUTO_STUB_DIR",
+	/** adapter 包入口（协议装配用）。 */
+	ADAPTER_ENTRY: "NAPUTO_ADAPTER_ENTRY",
+	/** network 包入口（协议装配用）。 */
+	NETWORK_ENTRY: "NAPUTO_NETWORK_ENTRY",
+	/** 全局配置文件路径（项目根 napuketto.toml，boot-protocols 读取）。 */
+	CONFIG_PATH: "NAPKETTO_CONFIG",
+	/** 强制指定快速登录账号（cli `-q <uin>` 透传，bootstrap 登录用）。 */
+	QUICK_UIN: "NAPUTO_QUICK_UIN",
+	/** IPC 子进程模式（koishi 插件驱动：stdout JSON 行 + stdin action/control）。 */
+	IPC: "NAPUTO_IPC"
+};
+//#endregion
+//#region src/qq-releases.ts
+/**
+* qq-releases.ts：版本清单读取（P1）。
+*
+* 运行时从包根 qq-releases.json 读取（发布时 files 含它，安装后位于
+* node_modules/@napuketto/loader/qq-releases.json）。清单由 CI/社区 PR 维护
+* （设计文档 §2.2）。NAPUTO_QQ_URL 可运行时覆盖下载地址。
+*/
+/** 清单解析失败。 */
+var QqReleasesError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "QqReleasesError";
+	}
+};
+/** 包根路径（dist 与包根同层：dist/index.mjs → ../qq-releases.json）。 */
+function packageRoot() {
+	return (0, node_path.dirname)((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)));
+}
+/** 读版本清单（同步，启动期调用一次即可）。 */
+function loadQqReleases() {
+	const file = (0, node_path.join)(packageRoot(), "qq-releases.json");
+	let raw;
+	try {
+		raw = (0, node_fs.readFileSync)(file, "utf8");
+	} catch {
+		throw new QqReleasesError(`版本清单缺失: ${file}（@napuketto/loader 包安装不完整？）`);
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed.schema !== 1 || !Array.isArray(parsed.known) || parsed.known.length === 0) throw new Error("结构不合法");
+		return parsed;
+	} catch {
+		throw new QqReleasesError(`版本清单解析失败: ${file}`);
+	}
+}
+/** 取最新已知可用版本（known 数组按录入顺序，取最后一项 = 最新）。 */
+function latestRelease(releases) {
+	const [latest] = [...releases.known].reverse();
+	if (latest === void 0) throw new QqReleasesError("版本清单为空");
+	return latest;
+}
+/**
+* 解析实际下载 URL：NAPUTO_QQ_URL 环境变量覆盖 > 清单 URL。
+* 供 downloadFile 使用（也支持按版本查询，当前固定取最新）。
+*/
+function resolveDownloadUrl(release) {
+	const override = node_process.default.env["NAPUTO_QQ_URL"];
+	return override !== void 0 && override !== "" ? override : release.url;
+}
+//#endregion
+//#region src/locate-qq.ts
+/**
+* 定位 QQ 原生文件（wrapper.node）来源（P0：多级来源纯定位，不下载）。
+*
+* 来源优先级（resolveQqFiles）：
+*   L0: NAPUTO_QQ_FILES / qqFilesDir —— 显式指定含 versions/ 结构的文件根（缓存/拷贝）
+*   L1: 本机 QQ 安装 —— NAPUTO_QQ_PATH / 注册表 / 常见路径（既有逻辑保留）
+*   L2: 数据根缓存 <数据根>/qq-files/<版本> —— 下载解包产物（P1 落地后才有）
+*/
+/** 数据根下 QQ 文件缓存目录名（<数据根>/qq-files/<版本>/，P1 下载解包产物）。 */
+const QQ_FILES_DIR_NAME = "qq-files";
+/** 注册表 UninstallString 查询（QQ 官方安装路径）。 */
+const REG_QUERY_RE = /"([^"]+)"/;
+/** 注册表 UninstallString 查询（QQ 官方安装路径）。 */
+function findQqViaRegistry() {
+	try {
+		const exe = (0, node_child_process.execFileSync)("reg", [
+			"query",
+			"HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\QQ",
+			"/v",
+			"UninstallString"
+		]).toString().match(REG_QUERY_RE)?.[1];
+		if (exe !== void 0) {
+			const dir = exe.replaceAll("\"", "").slice(0, exe.lastIndexOf("\\"));
+			const qq = (0, node_path.join)(dir, "QQ.exe");
+			if ((0, node_fs.existsSync)(qq)) return qq;
+		}
+	} catch {}
+	return null;
+}
+/** 常见安装路径探测。 */
+function findQqViaCommonPaths() {
+	const localAppData = node_process.default.env["LOCALAPPDATA"] ?? "";
+	const candidates = [
+		"C:/Program Files/Tencent/QQNT/QQ.exe",
+		"C:/Program Files (x86)/Tencent/QQNT/QQ.exe",
+		(0, node_path.join)(localAppData, "Programs", "Tencent", "QQNT", "QQ.exe"),
+		"C:/Dev/QQBot-Dev/QQNT/QQ.exe"
+	];
+	for (const p of candidates) if ((0, node_fs.existsSync)(p)) return p;
+	return null;
+}
+/** 找 QQ.exe 路径。 */
+function locateQqPath() {
+	const viaReg = findQqViaRegistry();
+	if (viaReg) return viaReg;
+	const viaCommon = findQqViaCommonPaths();
+	if (viaCommon) return viaCommon;
+	throw new Error("未找到 QQ.exe（请先安装 QQ，或通过 NAPUTO_QQ_PATH 指定）");
+}
+/** 从文件根定位最新版本 wrapper.node（local/cached 共用）。 */
+function resolveFromRoot(rootDir, source) {
+	const versionsDir = (0, node_path.join)(rootDir, "versions");
+	if (!(0, node_fs.existsSync)(versionsDir)) throw new Error(`QQ 版本目录不存在: ${versionsDir}`);
+	const [first] = (0, node_fs.readdirSync)(versionsDir).filter((v) => (0, node_fs.statSync)((0, node_path.join)(versionsDir, v)).isDirectory()).sort().reverse();
+	if (first === void 0) throw new Error(`QQ 版本目录为空: ${versionsDir}`);
+	const wrapperPath = (0, node_path.join)(versionsDir, first, "resources", "app", "wrapper.node");
+	if (!(0, node_fs.existsSync)(wrapperPath)) throw new Error(`未找到 wrapper.node: ${wrapperPath}`);
+	return {
+		qqPath: (0, node_path.join)(rootDir, "QQ.exe"),
+		installDir: rootDir,
+		version: first,
+		wrapperPath,
+		source
+	};
+}
+/** 从 QQ.exe 路径推导安装目录，并探测当前版本（L1：本机安装）。 */
+function resolveQqInstall(qqPath) {
+	const qq = qqPath ?? node_process.default.env["NAPUTO_QQ_PATH"] ?? locateQqPath();
+	return resolveFromRoot(qq.slice(0, qq.lastIndexOf("\\")), "local");
+}
+/**
+* 多级来源定位 QQ 原生文件：
+*   L0 → L1 → L2 依次尝试，全部失败且 autoDownload 时自动进入下载流程（ensureQqFiles）。
+* ⚠️ async：自动下载为异步流程（P1 起）；纯定位场景用 resolveQqInstall（同步）。
+*/
+async function resolveQqFiles(options = {}) {
+	const explicitDir = options.qqFilesDir ?? node_process.default.env["NAPUTO_QQ_FILES"];
+	if (explicitDir !== void 0 && explicitDir !== "") return resolveFromRoot((0, node_path.resolve)(explicitDir), "cached");
+	const qqPath = options.qqPath ?? node_process.default.env["NAPUTO_QQ_PATH"];
+	if (qqPath !== void 0 && qqPath !== "") return resolveQqInstall(qqPath);
+	try {
+		return resolveQqInstall();
+	} catch {}
+	const dataRoot = resolveDataRootLight(options.dataRoot);
+	const cached = tryResolveCached(dataRoot);
+	if (cached !== null) return cached;
+	if (options.autoDownload !== false) return ensureQqFiles({
+		dataRoot,
+		...options.sevenZipPath !== void 0 ? { sevenZipPath: options.sevenZipPath } : {}
+	});
+	throw new Error("未找到 QQ 原生文件（wrapper.node）：请安装 QQ、设置 NAPUTO_QQ_PATH/NAPUTO_QQ_FILES，或使用下载流程（ensureQqFiles）自动获取");
+}
+/** 扫描数据根缓存（L2）；命中返回，未命中返回 null。 */
+function tryResolveCached(dataRoot) {
+	const cacheRoot = (0, node_path.join)(dataRoot, QQ_FILES_DIR_NAME);
+	if (!(0, node_fs.existsSync)(cacheRoot)) return null;
+	const versionDirs = (0, node_fs.readdirSync)(cacheRoot).filter((v) => (0, node_fs.statSync)((0, node_path.join)(cacheRoot, v)).isDirectory()).sort().reverse();
+	for (const versionDir of versionDirs) try {
+		return resolveFromRoot((0, node_path.join)(cacheRoot, versionDir), "cached");
+	} catch {}
+	return null;
+}
+/**
+* 确保 QQ 原生文件就绪（P1）：幂等缓存检查 → 下载官方安装包 → sha256 校验
+* → 7z 解包 → 提取 wrapper.node/QQNT.dll → 缓存。返回缓存版本 QqInstallInfo。
+*/
+async function ensureQqFiles(options = {}) {
+	const dataRoot = resolveDataRootLight(options.dataRoot);
+	const cacheRoot = (0, node_path.join)(dataRoot, QQ_FILES_DIR_NAME);
+	(0, node_fs.mkdirSync)(cacheRoot, { recursive: true });
+	const existing = tryResolveCached(dataRoot);
+	if (existing !== null) return existing;
+	const release = latestRelease(loadQqReleases());
+	const url = resolveDownloadUrl(release);
+	const version = release.version;
+	const tmpDir = (0, node_path.join)(dataRoot, "tmp");
+	(0, node_fs.mkdirSync)(tmpDir, { recursive: true });
+	const installerPath = (0, node_path.join)(tmpDir, `qq-installer-${version}.exe`);
+	await downloadFile({
+		dest: installerPath,
+		url,
+		expectedSha256: release.sha256
+	});
+	const extractedDir = (0, node_path.join)(tmpDir, `qq-extracted-${version}`);
+	try {
+		await extractInstaller(installerPath, extractedDir, options.sevenZipPath);
+		return await extractWrapperFiles(extractedDir, version, cacheRoot);
+	} catch (err) {
+		await clearCacheVersion(cacheRoot, version);
+		throw err;
+	} finally {
+		await (0, node_fs_promises.rm)(installerPath, { force: true });
+		await (0, node_fs_promises.rm)(extractedDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* 轻量数据根解析（loader 侧，避免新增 kernel 依赖；P2 若需完整语义再切换）。
+* 优先级：显式参数 > NAPKETTO_DATA > 项目根/.napuketto > cwd 兜底。
+*/
+function resolveDataRootLight(dataRoot) {
+	const explicit = dataRoot ?? node_process.default.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return (0, node_path.resolve)(explicit);
+	const projectRoot = findProjectRoot(node_process.default.cwd()) ?? node_process.default.cwd();
+	return (0, node_path.join)(projectRoot, ".napuketto");
+}
+/** 向上探测项目根（含 pnpm-workspace.yaml 或 package.json 的目录）。 */
+function findProjectRoot(start) {
+	let dir = (0, node_path.resolve)(start);
+	for (;;) {
+		if ((0, node_fs.existsSync)((0, node_path.join)(dir, "pnpm-workspace.yaml")) || (0, node_fs.existsSync)((0, node_path.join)(dir, "package.json"))) return dir;
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+//#endregion
+exports.DownloadError = DownloadError;
+exports.ENV = ENV;
+exports.INSTANCE_LOCK_FILE = INSTANCE_LOCK_FILE;
+exports.QQ_FILES_DIR_NAME = QQ_FILES_DIR_NAME;
+exports.QqReleasesError = QqReleasesError;
+exports.WIN_NODE_DIR_NAME = WIN_NODE_DIR_NAME;
+exports.acquireInstanceLock = acquireInstanceLock;
+exports.buildSpawnCommand = buildSpawnCommand;
+exports.checkInstanceLock = checkInstanceLock;
+exports.clearCacheVersion = clearCacheVersion;
+exports.defaultStubDir = defaultStubDir;
+exports.downloadFile = downloadFile;
+exports.ensureQqFiles = ensureQqFiles;
+exports.ensureWinNode = ensureWinNode;
+exports.extractInstaller = extractInstaller;
+exports.extractWrapperFiles = extractWrapperFiles;
+exports.findSevenZip = findSevenZip;
+exports.isLinux = isLinux;
+exports.latestRelease = latestRelease;
+exports.launchSelfHost = launchSelfHost;
+exports.loadQqReleases = loadQqReleases;
+exports.locateQqPath = locateQqPath;
+exports.nodeZipUrl = nodeZipUrl;
+exports.registerLockCleanup = registerLockCleanup;
+exports.releaseInstanceLock = releaseInstanceLock;
+exports.resolveDownloadUrl = resolveDownloadUrl;
+exports.resolveQqFiles = resolveQqFiles;
+exports.resolveQqInstall = resolveQqInstall;
+exports.toWinePath = toWinePath;
+exports.wineBinary = wineBinary;

package/dist/index.d.cts

@@ -0,0 +1,365 @@
+import { StdioOptions, spawn } from "node:child_process";
+//#region src/instance-lock.d.ts
+/**
+ * instance-lock.ts：单实例锁（2026-08-07 根治「多实例抢数据目录锁挂起」）
+ *
+ * 背景（实测）：同一账号数据目录（~/.napuketto/<uin>）只能被一个实例持有——
+ * QQ 原生层（MMKV / 登录单例 / 数据库）有锁，第二个实例抢不到锁会卡在
+ * loginService.initConfig 之后无响应（挂起）。此前 create-napukettoqq 生成的
+ * 副本实例常驻占锁，导致用户后续启动全部卡死。
+ *
+ * 方案：以数据目录为粒度加锁文件 `<dataDir>/instance.lock`（JSON 内容：
+ * pid / startedAt / cmdline 摘要）。启动前 checkInstanceLock：
+ *   - 锁不存在 → 可启动（然后 acquireInstanceLock 写入）
+ *   - 锁存在但 PID 已死 → 崩溃残留，自动清理（rm + 重新获取）
+ *   - 锁存在且 PID 存活 → 已被占用，拒绝启动（返回占用 PID 供提示）
+ *
+ * 退出清理：进程正常退出时 releaseInstanceLock 删除锁文件；崩溃/强杀残留
+ * 由下次启动的「PID 存活检测」兜底（PID 已死 → 残留视为过期）。
+ *
+ * 放置说明：放 loader 而非 kernel——self-host.cjs 是 rolldown 内联 bundle
+ * （只内联 src/host/ 依赖树），静态 import kernel 会留 external 缺口；
+ * 放 loader 则 self-host（内联）与 cli（@napuketto/loader 导入）双入口可用。
+ */
+/** 锁文件名（置于数据目录内）。 */
+declare const INSTANCE_LOCK_FILE = "instance.lock";
+/** 锁文件内容。 */
+interface InstanceLockInfo {
+  /** 持有实例的进程 PID。 */
+  pid: number;
+  /** 获取锁的时间（epoch ms）。 */
+  startedAt: number;
+  /** 命令行摘要（诊断用，可选）。 */
+  cmdline?: string;
+}
+/** 数据目录锁检查结果。 */
+interface InstanceLockCheck {
+  /** 是否被其他实例占用。 */
+  occupied: boolean;
+  /** 占用进程 PID（occupied=true 时有效）。 */
+  pid: number | null;
+  /** 锁文件完整路径（提示/清理用）。 */
+  lockPath: string;
+}
+/**
+ * 检测指定数据目录是否已被其他实例占用。
+ *
+ * @param dataDir 数据目录（账号级，如 ~/.napuketto/3567141148）
+ */
+declare function checkInstanceLock(dataDir: string): InstanceLockCheck;
+/**
+ * 获取数据目录锁。占用（其他实例存活）返回 false；成功或清理残留后返回 true。
+ * 幂等：本进程已持有则直接返回 true（不重复写）。
+ */
+declare function acquireInstanceLock(dataDir: string, cmdline?: string): boolean;
+/**
+ * 释放数据目录锁（正常退出时调用）。仅当持有者是本进程时才删除，
+ * 避免误删新持有者的锁（PID 复用 / 快速重启场景）。
+ */
+declare function releaseInstanceLock(dataDir: string): void;
+/** 注册进程退出清理（SIGINT/SIGTERM/exit 均触发；崩溃强杀由残留检测兜底）。 */
+declare function registerLockCleanup(dataDir: string): void;
+//#endregion
+//#region src/locate-qq.d.ts
+/** 数据根下 QQ 文件缓存目录名（<数据根>/qq-files/<版本>/，P1 下载解包产物）。 */
+declare const QQ_FILES_DIR_NAME = "qq-files";
+/** QQ 文件来源。 */
+type QqFileSource = "local" | "cached";
+/** QQ 安装目录探测结果。 */
+interface QqInstallInfo {
+  /** QQ.exe 绝对路径（cached 来源为语义占位——缓存目录无 QQ.exe，当前无消费方）。 */
+  qqPath: string;
+  /** 安装根目录 / 文件根目录。 */
+  installDir: string;
+  /** 当前版本目录名（如 9.9.31-49919）。 */
+  version: string;
+  /** wrapper.node 绝对路径。 */
+  wrapperPath: string;
+  /** 来源：local = 本机安装；cached = NAPUTO_QQ_FILES / 数据根缓存。 */
+  source: QqFileSource;
+}
+/** resolveQqFiles 选项。 */
+interface ResolveQqFilesOptions {
+  /** 显式文件根（L0；缺省读 NAPUTO_QQ_FILES）。 */
+  qqFilesDir?: string;
+  /** 显式 QQ.exe 路径（L1；缺省读 NAPUTO_QQ_PATH）。 */
+  qqPath?: string;
+  /** 数据根（L2 缓存扫描；缺省轻量解析 NAPKETTO_DATA ?? 项目根/.napuketto）。 */
+  dataRoot?: string;
+  /** L0/L1/L2 全部失败时自动进入下载流程（P1；默认 true，测试可关）。 */
+  autoDownload?: boolean;
+  /** 7z 可执行文件路径（解包用；缺省自动探测）。 */
+  sevenZipPath?: string;
+}
+/** 找 QQ.exe 路径。 */
+declare function locateQqPath(): string;
+/** 从 QQ.exe 路径推导安装目录，并探测当前版本（L1：本机安装）。 */
+declare function resolveQqInstall(qqPath?: string): QqInstallInfo;
+/**
+ * 多级来源定位 QQ 原生文件：
+ *   L0 → L1 → L2 依次尝试，全部失败且 autoDownload 时自动进入下载流程（ensureQqFiles）。
+ * ⚠️ async：自动下载为异步流程（P1 起）；纯定位场景用 resolveQqInstall（同步）。
+ */
+declare function resolveQqFiles(options?: ResolveQqFilesOptions): Promise<QqInstallInfo>;
+/**
+ * 确保 QQ 原生文件就绪（P1）：幂等缓存检查 → 下载官方安装包 → sha256 校验
+ * → 7z 解包 → 提取 wrapper.node/QQNT.dll → 缓存。返回缓存版本 QqInstallInfo。
+ */
+declare function ensureQqFiles(options?: {
+  /** 数据根（缓存 <数据根>/qq-files/）。 */
+  dataRoot?: string;
+  /** 7z 路径（缺省自动探测）。 */
+  sevenZipPath?: string;
+}): Promise<QqInstallInfo>;
+//#endregion
+//#region src/launcher.d.ts
+interface LaunchOptions {
+  /** QQ 安装信息（qqPath/version/wrapperPath）。 */
+  qq: QqInstallInfo;
+  /** kernel 入口（.mjs，self-host.cjs 里 import）。 */
+  kernelEntry: string;
+  /** 配置目录（账号数据目录，NAPUTO_CFG_DIR）。 */
+  cfgDir: string;
+  /** 全局配置文件路径（项目根 napuketto.toml，注入 NAPKETTO_CONFIG 供装配链读取）。 */
+  configPath?: string;
+  /** adapter 入口（.mjs，协议装配用）。 */
+  adapterEntry?: string;
+  /** network 入口（.mjs，协议装配用）。 */
+  networkEntry?: string;
+  /** 自建宿主：标准 node + stub QQNT.dll 直接引导，不拉起 QQ（2026-08-07 唯一路线）。 */
+  selfHost?: boolean;
+  /** stub QQNT.dll 目录（PATH 前置，转发 napi_*、uv_* 符号到 node.exe）。 */
+  stubDir?: string;
+  /** 强制指定快速登录账号（注入 NAPUTO_QUICK_UIN；cli `-q <uin>` 透传，2026-08-07）。 */
+  quickUin?: string;
+  /** IPC 子进程模式（=1：stdout 走 JSON 行协议 + stdin 收 action/control，koishi 插件驱动）。 */
+  ipc?: boolean;
+  /** 自建宿主入口（默认 dist/host/self-host.cjs）。 */
+  selfHostEntry?: string;
+  /** Windows 版 node.exe 路径（linux 场景覆盖；缺省 ensureWinNode 下载）。 */
+  winNodePath?: string;
+  /**
+   * 子进程工作目录（缺省继承父进程 cwd）。
+   *
+   * ⚠️ 必须指向数据根（~/.napuketto）：QQ 原生层在账号上下文就绪前会
+   * fallback 到进程 cwd 落盘（如频道库 guild1.db），不指定则污染调用方
+   * 目录（实测写入项目根，guild1.db 08-07）。cli 传 dataRoot 根治。
+   */
+  cwd?: string;
+  /**
+   * 子进程 stdio（默认 "inherit"）。cli 传 ["inherit","pipe","pipe"] 并接管
+   * 子进程 stdout/stderr：逐行过滤 wrapper 原生噪音（MMKV 刷屏、Node 符号
+   * 查找失败警告），其余转发——原生 printf 直写 fd 的字节无法从 JS 层拦截。
+   */
+  stdio?: StdioOptions;
+}
+interface LaunchResult {
+  /** 子进程句柄（自建宿主 node 进程）。 */
+  child: ReturnType<typeof spawn>;
+  /** 自建宿主入口路径（self-host.cjs）。 */
+  bootJsPath: string;
+}
+/**
+ * 启动自建宿主（路线 A）：spawn 标准 node 直接跑 self-host.cjs，不拉起 QQ / 不注入。
+ *
+ * 关键（HANDOVER-V7 技术数据）：wrapper.node 从 QQNT.dll 导入 99 符号
+ * （napi_*×40 + uv_*×56 + qq_magic×1 + v8/node mangled×2）——标准 node 无这些宿主
+ * 符号，必须 PATH 前置 stub QQNT.dll 目录（转发到 node.exe）+ QQ resources\app
+ * （wrapper.node 同目录依赖 DLL）才能 dlopen 成功。
+ *
+ * P2 平台分支：win32 用本机 node；linux 用 wine + Windows 版 node.exe
+ * （ensureWinNode 自动下载，路径过 toWinePath）。async（win-node 可能需下载）。
+ */
+declare function launchSelfHost(options: LaunchOptions): Promise<LaunchResult>;
+/**
+ * 默认 stub QQNT.dll 目录（loader 包内闭源 native/build/stub-test-env，开发机默认）。
+ * src 与 native 同层，构建后 dist 与 native 同层——`../native` 恒正确。
+ */
+declare function defaultStubDir(): string;
+/** 环境变量名（self-host.cjs 与 kernel 引导读取）。 */
+declare const ENV: {
+  readonly QQ_PATH: "NAPUTO_QQ_PATH";
+  readonly KERNEL_ENTRY: "NAPUTO_KERNEL_ENTRY";
+  readonly CFG_DIR: "NAPUTO_CFG_DIR";
+  readonly QQ_VERSION: "NAPUTO_QQ_VERSION";
+  readonly WRAPPER_PATH: "NAPUTO_WRAPPER_PATH";
+  /** 自建宿主：标准 node + stub QQNT.dll 引导（self-host.cjs 分支）。 */
+  readonly SELF_HOST: "NAPUTO_SELF_HOST";
+  /** stub QQNT.dll 目录（launchSelfHost 注入，self-host.cjs 诊断用）。 */
+  readonly STUB_DIR: "NAPUTO_STUB_DIR";
+  /** adapter 包入口（协议装配用）。 */
+  readonly ADAPTER_ENTRY: "NAPUTO_ADAPTER_ENTRY";
+  /** network 包入口（协议装配用）。 */
+  readonly NETWORK_ENTRY: "NAPUTO_NETWORK_ENTRY";
+  /** 全局配置文件路径（项目根 napuketto.toml，boot-protocols 读取）。 */
+  readonly CONFIG_PATH: "NAPKETTO_CONFIG";
+  /** 强制指定快速登录账号（cli `-q <uin>` 透传，bootstrap 登录用）。 */
+  readonly QUICK_UIN: "NAPUTO_QUICK_UIN";
+  /** IPC 子进程模式（koishi 插件驱动：stdout JSON 行 + stdin action/control）。 */
+  readonly IPC: "NAPUTO_IPC";
+};
+//#endregion
+//#region src/qq-download.d.ts
+/** 下载选项。 */
+interface DownloadOptions {
+  /** 目标文件绝对路径。 */
+  dest: string;
+  /** 期望 sha256（十六进制小写）；缺省/空串 = 不校验（首次下载尚无参考值）。 */
+  expectedSha256?: string;
+  /** 覆盖下载地址（缺省读 NAPUTO_QQ_URL）。 */
+  url?: string;
+  /** 超时（毫秒，默认 60s 无数据则中断）。 */
+  timeoutMs?: number;
+}
+/** 下载结果。 */
+interface DownloadResult {
+  /** 实际 sha256（十六进制小写）。 */
+  sha256: string;
+  /** 是否通过期望值校验（无期望值时恒 true）。 */
+  verified: boolean;
+}
+/** 下载中断（超时 / 非 2xx / 网络错误）抛出的错误。 */
+declare class DownloadError extends Error {
+  constructor(message: string);
+}
+/**
+ * 下载文件并（可选）校验 sha256。失败时清理半成品文件。
+ * 返回实际 sha256（无论是否校验），便于调用方回填清单。
+ */
+declare function downloadFile(options: DownloadOptions): Promise<DownloadResult>;
+//#endregion
+//#region src/qq-extract.d.ts
+/** 7-Zip 可执行文件来源。 */
+interface SevenZipResult {
+  /** 7z 可执行文件绝对路径。 */
+  exe: string;
+  /** 来源说明（内置资产 / 系统 / 环境变量）。 */
+  source: string;
+}
+/** 提取选项。 */
+interface ExtractOptions {
+  /** 安装包绝对路径。 */
+  installerPath: string;
+  /** 目标版本目录（如 9.9.33-51802）。 */
+  version: string;
+  /** 缓存根目录（<数据根>/qq-files；版本子目录将建在其下）。 */
+  cacheRoot: string;
+  /** 7z 可执行文件路径（缺省自动探测）。 */
+  sevenZipPath?: string;
+}
+/**
+ * 探测 7z 可执行文件：
+ *   NAPUTO_7Z_PATH 环境变量 > 内置资产（assets/7zip/7z.exe，Windows）> 系统 PATH 7z。
+ * Linux 上用 p7zip 提供的 7z 命令（系统 PATH）。
+ */
+declare function findSevenZip(): SevenZipResult;
+/** 解包安装包到指定目录（spawn 7z x，失败抛错）。 */
+declare function extractInstaller(installerPath: string, destDir: string, sevenZipPath?: string): Promise<void>;
+/**
+ * 从解包目录提取运行所需文件到缓存：
+ * resources/app 顶层全部 *.node + *.dll（保持同目录结构，PATH 前置即可解析依赖）。
+ * 幂等：目标 wrapper.node 已存在则跳过。
+ */
+declare function extractWrapperFiles(extractedDir: string, version: string, cacheRoot: string): Promise<QqInstallInfo>;
+/** 清理缓存版本目录（下载/解包失败残留，供调用方兜底）。 */
+declare function clearCacheVersion(cacheRoot: string, version: string): Promise<void>;
+//#endregion
+//#region src/qq-releases.d.ts
+/** 清单中单个版本条目。 */
+interface QqReleaseEntry {
+  /** 版本目录名（如 9.9.33-51802）。 */
+  version: string;
+  /** 官方安装包下载 URL。 */
+  url: string;
+  /** sha256（十六进制小写）；空串 = 尚未校验（首次录入时 CI 计算后填入）。 */
+  sha256: string;
+  /** appid（预知信息，运行时仍从 major.node 解析）。 */
+  appid: number;
+  /** 来源标记（official = 官方）。 */
+  source: string;
+  /** 构建日期（YYYY-MM-DD，可选）。 */
+  buildDate?: string;
+}
+/** 清单文件结构。 */
+interface QqReleasesFile {
+  schema: number;
+  known: QqReleaseEntry[];
+}
+/** 清单解析失败。 */
+declare class QqReleasesError extends Error {
+  constructor(message: string);
+}
+/** 读版本清单（同步，启动期调用一次即可）。 */
+declare function loadQqReleases(): QqReleasesFile;
+/** 取最新已知可用版本（known 数组按录入顺序，取最后一项 = 最新）。 */
+declare function latestRelease(releases: QqReleasesFile): QqReleaseEntry;
+/**
+ * 解析实际下载 URL：NAPUTO_QQ_URL 环境变量覆盖 > 清单 URL。
+ * 供 downloadFile 使用（也支持按版本查询，当前固定取最新）。
+ */
+declare function resolveDownloadUrl(release: QqReleaseEntry): string;
+//#endregion
+//#region src/win-node.d.ts
+/** 运行时缓存子目录名（<数据根>/runtime/win-node/）。 */
+declare const WIN_NODE_DIR_NAME = "win-node";
+/** Windows node.exe 定位结果。 */
+interface WinNodeInfo {
+  /** node.exe 绝对路径（Windows 视角，供 wine 调用）。 */
+  exePath: string;
+  /** 已下载的完整版 node zip 版本号（如 v24.16.0）。 */
+  version: string;
+}
+/** 解析 nodejs.org zip URL（与 dist 目录命名一致）。 */
+declare function nodeZipUrl(version: string): string;
+/**
+ * 确保 Windows 版 node.exe 就绪（下载 + 解压 + 缓存）。
+ * 幂等：<数据根>/runtime/win-node/<version>/node.exe 已存在则直接返回。
+ */
+declare function ensureWinNode(options?: {
+  /** 数据根（缓存 <数据根>/runtime/win-node/）。 */
+  dataRoot?: string;
+  /** node 版本（缺省读 NAPUTO_WIN_NODE_VERSION，再兜底 latest v24）。 */
+  version?: string;
+  /** 显式 node.exe 路径（覆盖缓存逻辑，读 NAPUTO_WIN_NODE_PATH）。 */
+  exePath?: string;
+}): Promise<WinNodeInfo>;
+//#endregion
+//#region src/wine.d.ts
+/**
+ * wine.ts：Linux 上经 wine 运行 Windows 版 node.exe 的路径与 spawn 组装（P2）。
+ *
+ * 设计文档 §3.2（2026-08-12 拍板确认）。核心认知：
+ *  - Windows 版 node.exe 在 wine 内把 Linux 根目录挂载在 `Z:\`
+ *  - process.dlopen / 环境变量路径都是 wine 视角的 Windows 路径
+ *  - 传给 wine 子进程的**所有路径**（wrapperPath / cfgDir / stubDir / self-host.cjs / PATH）
+ *    都要过 toWinePath 转成 `Z:\...`
+ *
+ * 纯函数设计：不 import node:child_process，方便 Windows 上单测断言（P2 纯逻辑层）。
+ */
+/** Linux 绝对路径 → wine `Z:\` 路径（Windows 版 node.exe 视角）。幂等：已是 Windows 路径（含盘符）原样返回。 */
+declare function toWinePath(linuxPath: string): string;
+/** 判断当前是否 Linux（需 wine 的场景）。 */
+declare function isLinux(): boolean;
+/** wine 可执行文件（Linux 上 spawn 用；可被 NAPUTO_WINE 覆盖）。 */
+declare function wineBinary(): string;
+/** spawn 命令与参数（平台分支；纯函数，可单测）。 */
+interface SpawnCommand {
+  /** 命令（win32 = node.exe；linux = wine）。 */
+  command: string;
+  /** 参数（win32 = [selfHostPath]；linux = [winNodePath, selfHostPath]）。 */
+  args: string[];
+}
+/** 组装 spawn 命令（win32 vs linux 分支）。 */
+declare function buildSpawnCommand(options: {
+  /** 平台（缺省 process.platform，测试注入）。 */
+  platform?: NodeJS.Platform;
+  /** Windows 本机 node 路径（win32 用，缺省 process.execPath）。 */
+  winNodePath?: string;
+  /** wine 命令（linux 用，缺省 wineBinary()）。 */
+  wine?: string;
+  /** 自建宿主入口（self-host.cjs，传给 wine/win node）。 */
+  selfHostPath: string;
+}): SpawnCommand;
+//#endregion
+export { DownloadError, type DownloadOptions, type DownloadResult, ENV, type ExtractOptions, INSTANCE_LOCK_FILE, type InstanceLockCheck, type InstanceLockInfo, 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, ensureQqFiles, ensureWinNode, extractInstaller, extractWrapperFiles, findSevenZip, isLinux, latestRelease, launchSelfHost, loadQqReleases, locateQqPath, nodeZipUrl, registerLockCleanup, releaseInstanceLock, resolveDownloadUrl, resolveQqFiles, resolveQqInstall, toWinePath, wineBinary };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/instance-lock.ts","../src/locate-qq.ts","../src/launcher.ts","../src/qq-download.ts","../src/qq-extract.ts","../src/qq-releases.ts","../src/win-node.ts","../src/wine.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;cA2Ba;;UAGI;;EAEb;;EAEA;;EAEA;;;UAIa;;EAEb;;EAEA;;EAEA;;;;;;;iBAQY,kBAAkB,kBAAkB;;;;;iBA+BpC,oBAAoB,iBAAiB;;;;;iBA4BrC,oBAAoB;;iBAapB,oBAAoB;;;;cC5GvB;;KAiDD;;UAGK;;EAEb;;EAEA;;EAEA;;EAEA;;EAEA,QAAQ;;;UAIK;;EAEb;;EAEA;;EAEA;;EAEA;;EAEA;;;iBAIY;;iBAwCA,iBAAiB,kBAAkB;;;;;;iBAY7B,eAAe,UAAS,wBAA6B,QAAQ;;;;;iBA0D7D,cAClB;;EAEI;;EAEA;IAEL,QAAQ;;;UChMM;;EAEb,IAAI;;EAEJ;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;EAQA;;;;;;EAMA,QAAQ;;UAGK;;EAEb,OAAO,kBAAkB;;EAEzB;;;;;;;;;;;;;iBAckB,eAAe,SAAS,gBAAgB,QAAQ;;;;;iBAoFtD;;cA4CH;WACT;WACA;WACA;WACA;WACA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;UCnNa;;EAEb;;EAEA;;EAEA;;EAEA;;;UAIa;;EAEb;;EAEA;;;cAIS,sBAAsB;EAC/B,YAAY;;;;;;iBA8CM,aAAa,SAAS,kBAAkB,QAAQ;;;;UCrDrD;;EAEb;;EAEA;;;UAIa;;EAEb;;EAEA;;EAEA;;EAEA;;;;;;;iBAQY,gBAAgB;;iBAuBV,iBAClB,uBACA,iBACA,wBACD;;;;;;iBA8BmB,oBAClB,sBACA,iBACA,oBACD,QAAQ;;iBAkDW,kBAAkB,mBAAmB,kBAAkB;;;;UC1J5D;;EAEb;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIa;EACb;EACA,OAAO;;;cAIE,wBAAwB;EACjC,YAAY;;;iBAYA,kBAAkB;;iBAoBlB,cAAc,UAAU,iBAAiB;;;;;iBAYzC,mBAAmB,SAAS;;;;cC3D/B;;UAGI;;EAEb;;EAEA;;;iBAIY,WAAW;;;;;iBAQL,cAClB;;EAEI;;EAEA;;EAEA;IAEL,QAAQ;;;;;;;;;;;;;;;iBCpCK,WAAW;;iBAiBX;;iBAKA;;UAKC;;EAEb;;EAEA;;;iBAIY,kBAAkB;;EAE9B,WAAW,OAAO;;EAElB;;EAEA;;EAEA;IACA"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@napuketto/loader",
-    "version": "0.0.9",
+    "version": "0.0.10",
     "description": "NapukettoQQ 引导组件：自建宿主（标准 Node + stub QQNT.dll）dlopen wrapper.node 并启动 kernel，不拉起 QQ / 不注入",
     "type": "module",
     "files": [
@@ -9,15 +9,19 @@
         "qq-releases.json",
         "assets/7zip"
     ],
-    "main": "./dist/index.mjs",
+    "main": "./dist/index.cjs",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.mts",
     "exports": {
         ".": {
-            "types": "./dist/index.d.mts",
-            "import": "./dist/index.mjs",
-            "require": "./dist/index.mjs",
-            "default": "./dist/index.mjs"
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
         }
     },
     "scripts": {