@napuketto/loader 0.0.8 → 0.0.10

package/dist/index.mjs

@@ -1,8 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import process from "node:process";
-import { execFileSync, spawn } from "node:child_process";
+import process$1 from "node:process";
+import { execFile, execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { copyFile, mkdir, readdir, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { get } from "node:https";
 //#region src/instance-lock.ts
 /**
 * instance-lock.ts：单实例锁（2026-08-07 根治「多实例抢数据目录锁挂起」）
@@ -51,7 +54,7 @@ function checkInstanceLock(dataDir) {
 	};
 	let alive = false;
 	try {
-		process.kill(info.pid, 0);
+		process$1.kill(info.pid, 0);
 		alive = true;
 	} catch {
 		alive = false;
@@ -74,11 +77,11 @@ function checkInstanceLock(dataDir) {
 function acquireInstanceLock(dataDir, cmdline) {
 	const { occupied, pid, lockPath } = checkInstanceLock(dataDir);
 	if (occupied) {
-		if (pid === process.pid) return true;
+		if (pid === process$1.pid) return true;
 		return false;
 	}
 	const info = {
-		pid: process.pid,
+		pid: process$1.pid,
 		startedAt: Date.now(),
 		...cmdline !== void 0 && cmdline !== "" ? { cmdline } : {}
 	};
@@ -97,16 +100,351 @@ function acquireInstanceLock(dataDir, cmdline) {
 function releaseInstanceLock(dataDir) {
 	const lockPath = join(dataDir, INSTANCE_LOCK_FILE);
 	try {
-		if (JSON.parse(readFileSync(lockPath, "utf-8")).pid === process.pid) rmSync(lockPath, { force: true });
+		if (JSON.parse(readFileSync(lockPath, "utf-8")).pid === process$1.pid) rmSync(lockPath, { force: true });
 	} catch {}
 }
 /** 注册进程退出清理（SIGINT/SIGTERM/exit 均触发；崩溃强杀由残留检测兜底）。 */
 function registerLockCleanup(dataDir) {
-	process.on("exit", () => {
+	process$1.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 = 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 ?? process$1.env["NAPUTO_QQ_URL"];
+	if (url === void 0 || url === "") throw new DownloadError("下载地址为空：请设置 NAPUTO_QQ_URL 或提供清单 URL");
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	mkdirSync(dirname(options.dest), { recursive: true });
+	const hash = createHash("sha256");
+	const fileStream = 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 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 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 = process$1.env["NAPUTO_7Z_PATH"];
+	if (envPath !== void 0 && envPath !== "" && existsSync(envPath)) return {
+		exe: envPath,
+		source: "环境变量 NAPUTO_7Z_PATH"
+	};
+	if (process$1.platform === "win32") {
+		const bundled = join(dirname(fileURLToPath(import.meta.url)), "..", "assets", "7zip", "7z.exe");
+		if (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 mkdir(destDir, { recursive: true });
+	await new Promise((resolve, reject) => {
+		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 = join(extractedDir, "Files", "versions", version, "resources", "app");
+	if (!existsSync(join(appDir, "wrapper.node"))) throw new Error(`解包产物缺少 wrapper.node: ${appDir}`);
+	const destAppDir = join(cacheRoot, version, "versions", version, "resources", "app");
+	const destWrapper = join(destAppDir, "wrapper.node");
+	if (existsSync(destWrapper)) return buildCachedInfo(cacheRoot, version);
+	await mkdir(destAppDir, { recursive: true });
+	const entries = await 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 copyFile(join(appDir, entry.name), join(destAppDir, entry.name));
+	}
+	if (!existsSync(destWrapper)) throw new Error(`提取失败：wrapper.node 未复制到 ${destWrapper}`);
+	return buildCachedInfo(cacheRoot, version);
+}
+/** 构造 cached 来源的 QqInstallInfo（wrapperPath 指向缓存中 wrapper.node）。 */
+function buildCachedInfo(cacheRoot, version) {
+	const versionDir = join(cacheRoot, version);
+	return {
+		qqPath: join(versionDir, "QQ.exe"),
+		installDir: versionDir,
+		version,
+		wrapperPath: join(versionDir, "versions", version, "resources", "app", "wrapper.node"),
+		source: "cached"
+	};
+}
+/** 清理缓存版本目录（下载/解包失败残留，供调用方兜底）。 */
+async function clearCacheVersion(cacheRoot, version) {
+	await rm(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 ?? process$1.env["NAPUTO_WIN_NODE_PATH"];
+	if (explicit !== void 0 && explicit !== "" && existsSync(explicit)) return {
+		exePath: resolve(explicit),
+		version: "explicit"
+	};
+	const version = options.version ?? process$1.env["NAPUTO_WIN_NODE_VERSION"] ?? DEFAULT_WIN_NODE_VERSION;
+	const dataRoot = resolveDataRoot(options.dataRoot);
+	const cacheDir = join(dataRoot, "runtime", WIN_NODE_DIR_NAME, version);
+	const exePath = join(cacheDir, WIN_NODE_EXE);
+	if (existsSync(exePath)) return {
+		exePath,
+		version
+	};
+	const zipPath = join(cacheDir, `node-${version}-win-x64.zip`);
+	const url = process$1.env["NAPUTO_WIN_NODE_URL"] ?? nodeZipUrl(version);
+	mkdirSync(cacheDir, { recursive: true });
+	try {
+		await downloadFile({
+			dest: zipPath,
+			url
+		});
+		await unzipNode(zipPath, cacheDir);
+	} finally {
+		await rm(zipPath, { force: true });
+	}
+	if (!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 = join(cacheDir, "_zip");
+	await extractInstaller(zipPath, tmpDir);
+	const nodeDir = (await readdir(tmpDir)).find((n) => n.startsWith("node-"));
+	const src = nodeDir === void 0 ? join(tmpDir, WIN_NODE_EXE) : join(tmpDir, nodeDir, WIN_NODE_EXE);
+	if (!existsSync(src)) throw new Error(`node zip 解压后未找到 node.exe: ${src}`);
+	await copyFile(src, join(cacheDir, WIN_NODE_EXE));
+	await 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 ?? process$1.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return resolve(explicit);
+	const projectRoot = findProjectRoot$1(process$1.cwd()) ?? process$1.cwd();
+	return join(projectRoot, ".napuketto");
+}
+/** 向上探测项目根（含 pnpm-workspace.yaml 或 package.json 的目录）。 */
+function findProjectRoot$1(start) {
+	let dir = resolve(start);
+	for (;;) {
+		if (existsSync(join(dir, "pnpm-workspace.yaml")) || existsSync(join(dir, "package.json"))) return dir;
+		const parent = 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。
@@ -116,32 +454,42 @@ function registerLockCleanup(dataDir) {
 *  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 = dirname(fileURLToPath(import.meta.url));
 /**
-* 启动自建宿主（路线 A，2026-08-07 产品化）：spawn 标准 node 直接跑 self-host.cjs，
-* 不拉起 QQ / 不注入。
+* 启动自建宿主（路线 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 可能需下载）。
 */
-function launchSelfHost(options) {
+async function launchSelfHost(options) {
 	const selfHostPath = options.selfHostEntry ?? join(__dirname, "..", "dist", "host", "self-host.cjs");
 	if (!existsSync(selfHostPath)) throw new Error(`self-host.cjs 缺失: ${selfHostPath}（先运行 pnpm --filter @napuketto/loader build）`);
 	const stub = options.stubDir ?? defaultStubDir();
 	if (!existsSync(join(stub, "QQNT.dll"))) throw new Error(`stub QQNT.dll 未找到: ${stub}（自建宿主必需：stub 转发 QQNT.dll 符号到 node.exe；请用 --stub-dir 或环境变量 NAPUTO_STUB_DIR 指定 stub 目录）`);
-	const env = buildLaunchEnv(options);
-	env["PATH"] = [
+	const { useWine, winNodePath } = await resolveNodeExecutable(options);
+	const env = buildLaunchEnv(options, useWine);
+	applyPathEnv(env, {
 		stub,
-		dirname(options.qq.wrapperPath),
-		process.env["PATH"] ?? ""
-	].filter((p) => p !== void 0 && p !== "").join(";");
-	env[ENV.STUB_DIR] = stub;
+		wrapperPath: options.qq.wrapperPath,
+		useWine
+	});
 	if (options.cwd !== void 0) mkdirSync(options.cwd, { recursive: true });
+	const { command, args } = buildSpawnCommand({
+		...useWine && winNodePath !== void 0 ? { winNodePath } : { winNodePath: process$1.execPath },
+		selfHostPath: useWine ? toWinePath(selfHostPath) : selfHostPath,
+		wine: wineBinary$1()
+	});
 	return {
-		child: spawn(process.execPath, [selfHostPath], {
+		child: spawn(command, args, {
 			...options.cwd !== void 0 ? { cwd: options.cwd } : {},
 			env,
 			stdio: options.stdio ?? "inherit",
@@ -150,6 +498,30 @@ function launchSelfHost(options) {
 		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(dirname(opts.wrapperPath)),
+		process$1.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` 恒正确。
@@ -157,25 +529,35 @@ function launchSelfHost(options) {
 function defaultStubDir() {
 	return join(__dirname, "..", "native", "build", "stub-test-env");
 }
-/** 装配自建宿主环境变量。 */
-function buildLaunchEnv(options) {
+/** 装配自建宿主环境变量（wine 场景路径转 Z:\；win32 原样）。 */
+function buildLaunchEnv(options, useWine) {
 	const cfg = resolve(options.cfgDir);
 	mkdirSync(cfg, { recursive: true });
+	const p = (linuxPath) => useWine ? toWinePath(linuxPath) : linuxPath;
 	const env = {
-		...process.env,
-		[ENV.QQ_PATH]: options.qq.qqPath,
-		[ENV.KERNEL_ENTRY]: resolve(options.kernelEntry),
-		[ENV.CFG_DIR]: cfg,
+		...process$1.env,
+		[ENV.QQ_PATH]: p(options.qq.qqPath),
+		[ENV.KERNEL_ENTRY]: p(resolve(options.kernelEntry)),
+		[ENV.CFG_DIR]: p(cfg),
 		[ENV.QQ_VERSION]: options.qq.version,
-		[ENV.WRAPPER_PATH]: options.qq.wrapperPath
+		[ENV.WRAPPER_PATH]: p(options.qq.wrapperPath)
+	};
+	const optional = {
+		...options.selfHost === true ? { [ENV.SELF_HOST]: "1" } : {},
+		...options.adapterEntry !== void 0 ? { [ENV.ADAPTER_ENTRY]: p(resolve(options.adapterEntry)) } : {},
+		...options.networkEntry !== void 0 ? { [ENV.NETWORK_ENTRY]: p(resolve(options.networkEntry)) } : {},
+		...options.configPath !== void 0 ? { [ENV.CONFIG_PATH]: p(resolve(options.configPath)) } : {},
+		...options.quickUin !== void 0 ? { [ENV.QUICK_UIN]: options.quickUin } : {},
+		...options.ipc === true ? { [ENV.IPC]: "1" } : {}
+	};
+	return {
+		...env,
+		...optional
 	};
-	if (options.selfHost === true) env[ENV.SELF_HOST] = "1";
-	if (options.adapterEntry !== void 0) env[ENV.ADAPTER_ENTRY] = resolve(options.adapterEntry);
-	if (options.networkEntry !== void 0) env[ENV.NETWORK_ENTRY] = resolve(options.networkEntry);
-	if (options.configPath !== void 0) env[ENV.CONFIG_PATH] = resolve(options.configPath);
-	if (options.quickUin !== void 0) env[ENV.QUICK_UIN] = options.quickUin;
-	if (options.ipc === true) env[ENV.IPC] = "1";
-	return env;
+}
+/** wine 可执行文件（linux 场景；NAPUTO_WINE 可覆盖）。 */
+function wineBinary$1() {
+	return process$1.env["NAPUTO_WINE"] ?? "wine";
 }
 /** 环境变量名（self-host.cjs 与 kernel 引导读取）。 */
 const ENV = {
@@ -200,10 +582,68 @@ const ENV = {
 	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 dirname(dirname(fileURLToPath(import.meta.url)));
+}
+/** 读版本清单（同步，启动期调用一次即可）。 */
+function loadQqReleases() {
+	const file = join(packageRoot(), "qq-releases.json");
+	let raw;
+	try {
+		raw = 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 = process$1.env["NAPUTO_QQ_URL"];
+	return override !== void 0 && override !== "" ? override : release.url;
+}
+//#endregion
 //#region src/locate-qq.ts
 /**
-* 定位 QQ 安装目录与版本（复用 kernel wrapper-version 的探测逻辑）
+* 定位 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 官方安装路径）。 */
@@ -225,7 +665,7 @@ function findQqViaRegistry() {
 }
 /** 常见安装路径探测。 */
 function findQqViaCommonPaths() {
-	const localAppData = process.env["LOCALAPPDATA"] ?? "";
+	const localAppData = process$1.env["LOCALAPPDATA"] ?? "";
 	const candidates = [
 		"C:/Program Files/Tencent/QQNT/QQ.exe",
 		"C:/Program Files (x86)/Tencent/QQNT/QQ.exe",
@@ -243,24 +683,116 @@ function locateQqPath() {
 	if (viaCommon) return viaCommon;
 	throw new Error("未找到 QQ.exe（请先安装 QQ，或通过 NAPUTO_QQ_PATH 指定）");
 }
-/** 从 QQ.exe 路径推导安装目录，并探测当前版本。 */
-function resolveQqInstall(qqPath) {
-	const qq = qqPath ?? process.env["NAPUTO_QQ_PATH"] ?? locateQqPath();
-	const installDir = qq.slice(0, qq.lastIndexOf("\\"));
-	const versionsDir = join(installDir, "versions");
+/** 从文件根定位最新版本 wrapper.node（local/cached 共用）。 */
+function resolveFromRoot(rootDir, source) {
+	const versionsDir = join(rootDir, "versions");
 	if (!existsSync(versionsDir)) throw new Error(`QQ 版本目录不存在: ${versionsDir}`);
 	const [first] = readdirSync(versionsDir).filter((v) => statSync(join(versionsDir, v)).isDirectory()).sort().reverse();
 	if (first === void 0) throw new Error(`QQ 版本目录为空: ${versionsDir}`);
 	const wrapperPath = join(versionsDir, first, "resources", "app", "wrapper.node");
 	if (!existsSync(wrapperPath)) throw new Error(`未找到 wrapper.node: ${wrapperPath}`);
 	return {
-		qqPath: qq,
-		installDir,
+		qqPath: join(rootDir, "QQ.exe"),
+		installDir: rootDir,
 		version: first,
-		wrapperPath
+		wrapperPath,
+		source
 	};
 }
+/** 从 QQ.exe 路径推导安装目录，并探测当前版本（L1：本机安装）。 */
+function resolveQqInstall(qqPath) {
+	const qq = qqPath ?? process$1.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 ?? process$1.env["NAPUTO_QQ_FILES"];
+	if (explicitDir !== void 0 && explicitDir !== "") return resolveFromRoot(resolve(explicitDir), "cached");
+	const qqPath = options.qqPath ?? process$1.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 = join(dataRoot, QQ_FILES_DIR_NAME);
+	if (!existsSync(cacheRoot)) return null;
+	const versionDirs = readdirSync(cacheRoot).filter((v) => statSync(join(cacheRoot, v)).isDirectory()).sort().reverse();
+	for (const versionDir of versionDirs) try {
+		return resolveFromRoot(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 = join(dataRoot, QQ_FILES_DIR_NAME);
+	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 = join(dataRoot, "tmp");
+	mkdirSync(tmpDir, { recursive: true });
+	const installerPath = join(tmpDir, `qq-installer-${version}.exe`);
+	await downloadFile({
+		dest: installerPath,
+		url,
+		expectedSha256: release.sha256
+	});
+	const extractedDir = 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 rm(installerPath, { force: true });
+		await rm(extractedDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* 轻量数据根解析（loader 侧，避免新增 kernel 依赖；P2 若需完整语义再切换）。
+* 优先级：显式参数 > NAPKETTO_DATA > 项目根/.napuketto > cwd 兜底。
+*/
+function resolveDataRootLight(dataRoot) {
+	const explicit = dataRoot ?? process$1.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return resolve(explicit);
+	const projectRoot = findProjectRoot(process$1.cwd()) ?? process$1.cwd();
+	return join(projectRoot, ".napuketto");
+}
+/** 向上探测项目根（含 pnpm-workspace.yaml 或 package.json 的目录）。 */
+function findProjectRoot(start) {
+	let dir = resolve(start);
+	for (;;) {
+		if (existsSync(join(dir, "pnpm-workspace.yaml")) || existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
 //#endregion
-export { ENV, INSTANCE_LOCK_FILE, acquireInstanceLock, checkInstanceLock, defaultStubDir, launchSelfHost, locateQqPath, registerLockCleanup, releaseInstanceLock, resolveQqInstall };
+export { DownloadError, ENV, INSTANCE_LOCK_FILE, QQ_FILES_DIR_NAME, QqReleasesError, WIN_NODE_DIR_NAME, 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.mjs.map