@napuketto/kernel 0.0.7 → 0.0.9

package/dist/index.cjs

@@ -0,0 +1,4120 @@
+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_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let smol_toml = require("smol-toml");
+let node_process = require("node:process");
+node_process = __toESM(node_process, 1);
+let pino = require("pino");
+pino = __toESM(pino, 1);
+let pino_pretty = require("pino-pretty");
+pino_pretty = __toESM(pino_pretty, 1);
+let node_os = require("node:os");
+let node_url = require("node:url");
+let node_crypto = require("node:crypto");
+let node_https = require("node:https");
+let node_events = require("node:events");
+//#region src/infra/errors.ts
+/**
+* 全部错误码集合。协议层映射表可据此推导：
+* `Record<(typeof KERNEL_ERROR_CODES)[number], number>`。
+*/
+const KERNEL_ERROR_CODES = [
+	"SEND_FAILED",
+	"PERMISSION_DENIED",
+	"NOT_FOUND",
+	"TIMEOUT",
+	"NOT_LOGIN",
+	"INVALID_PARAM",
+	"INVALID_STATE",
+	"UNKNOWN"
+];
+/** kernel 类型化错误：apis / 基础设施层抛出的统一错误形态。 */
+var KernelError = class extends Error {
+	code;
+	constructor(message, code = "UNKNOWN", options) {
+		super(message, options);
+		this.name = "KernelError";
+		this.code = code;
+	}
+};
+/** 便捷构造：`kernelError('消息不存在', 'NOT_FOUND', { cause })`。 */
+function kernelError(message, code = "UNKNOWN", options) {
+	return new KernelError(message, code, options);
+}
+/** 类型守卫：协议层 catch 统一映射时区分 KernelError 与意外错误。 */
+function isKernelError(err) {
+	return err instanceof KernelError;
+}
+//#endregion
+//#region src/infra/config.ts
+/**
+* 配置基类（ADR-012）
+*
+* 读文件 → 校验 → 内存对象 → 变更写回。支持 **JSON / TOML** 两种文本格式
+* （按扩展名推断：.toml → TOML（smol-toml），其余 → JSON）。
+*
+* kernel 不依赖 zod：只依赖校验器的最小 `parse` 形状（`ConfigSchema`），
+* 协议包的 zod schema 天然满足；kernel 主配置用手写校验器包装。
+* 协议配置 schema 在各自协议包，见各包 docs/design.md。
+*/
+/** 按扩展名推断格式（.toml → toml，其余 → json）。 */
+function inferFormat(path) {
+	if ((0, node_path.extname)(path).toLowerCase() === ".toml") return "toml";
+	return "json";
+}
+function isMissingFileError(err) {
+	if (err instanceof Error) return err.code === "ENOENT";
+	return false;
+}
+/**
+* 配置基类。每次 `load()` / `save()` 都经过 schema 校验，
+* 校验失败抛 `KernelError('INVALID_PARAM')`，不静默吞掉。
+* - `load()`：seed 存在 → 直接用 seed；否则读文件（缺失落默认值）。
+* - `save()`：按格式序列化（TOML/JSON）原子写。
+*/
+var ConfigBase = class {
+	path;
+	defaults;
+	schema;
+	format;
+	seed;
+	value;
+	constructor(opts) {
+		this.path = opts.path;
+		this.defaults = opts.defaults;
+		this.schema = opts.schema;
+		this.format = opts.format ?? inferFormat(opts.path);
+		this.seed = opts.seed;
+		this.value = opts.seed ?? opts.defaults;
+	}
+	/** 当前内存值（只读消费；外部不得直接修改返回对象）。 */
+	get() {
+		return this.value;
+	}
+	/**
+	* 加载配置：
+	* - seed 存在 → 直接用 seed（已校验，不读文件；全局 TOML 分段装配方式）；
+	* - 文件缺失 → 写入默认值并落盘（首次运行自动生成），返回默认值；
+	* - 文件存在 → 读取 + 校验，更新内存，返回。
+	*/
+	async load() {
+		if (this.seed !== void 0) {
+			this.value = this.seed;
+			return this.value;
+		}
+		let raw;
+		try {
+			raw = await (0, node_fs_promises.readFile)(this.path, "utf8");
+		} catch (err) {
+			if (isMissingFileError(err)) {
+				await this.save(this.defaults);
+				return this.value;
+			}
+			throw new KernelError(`读取配置文件失败: ${this.path}`, "UNKNOWN", { cause: err });
+		}
+		this.value = this.parse(raw);
+		return this.value;
+	}
+	/** 重新从磁盘加载（外部变更后的热更新入口，P2 配置热更新使用）。 */
+	reload() {
+		return this.load();
+	}
+	/** 校验并落盘（原子写：临时文件 + rename），随后更新内存。 */
+	async save(next) {
+		const parsed = this.parse(this.serialize(next));
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(this.path), { recursive: true });
+		const tmpPath = `${this.path}.tmp`;
+		await (0, node_fs_promises.writeFile)(tmpPath, `${this.serialize(parsed)}\n`, "utf8");
+		await (0, node_fs_promises.rename)(tmpPath, this.path);
+		this.value = parsed;
+	}
+	/** 对象 → 文本（TOML/JSON）。 */
+	serialize(value) {
+		if (this.format === "toml") return (0, smol_toml.stringify)(value);
+		return JSON.stringify(value, null, 4);
+	}
+	/** 文本 → 对象（TOML/JSON）。 */
+	deserialize(raw) {
+		if (this.format === "toml") return (0, smol_toml.parse)(raw);
+		return JSON.parse(raw);
+	}
+	/** 反序列化 + schema 校验，错误统一包装为 KernelError。 */
+	parse(raw) {
+		let input;
+		try {
+			input = this.deserialize(raw);
+		} catch (err) {
+			throw new KernelError(`配置文件 ${this.format.toUpperCase()} 解析失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+		}
+		try {
+			return this.schema.parse(input);
+		} catch (err) {
+			throw new KernelError(`配置文件校验失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+		}
+	}
+};
+/** 解析 TOML 文本 → 对象（boot.cjs / 探测脚本等无 ConfigBase 场景复用）。 */
+function parseToml(text) {
+	return (0, smol_toml.parse)(text);
+}
+/** 对象 → TOML 文本（config init 生成全局配置文件等场景）。 */
+function stringifyToml(value) {
+	return (0, smol_toml.stringify)(value);
+}
+//#endregion
+//#region src/infra/logger.ts
+/**
+* pino 日志封装（ADR-007）
+*
+* - console（pino-pretty 可读输出）+ 可选文件双目的地
+* - 统一 level 控制
+* - 内置 redact（token / 票据等敏感字段不打日志），可追加
+* - 无全局单例（ADR-015 推论）：每进程实例化一份，由装配层持有
+*/
+/** 默认 redact 路径：顶层 token/票据 + 任意深度的密码/密钥。 */
+const DEFAULT_REDACT_PATHS = [
+	"token",
+	"ticket",
+	"cookie",
+	"password",
+	"secret"
+];
+function toSingle(streams) {
+	const [only] = streams;
+	if (only === void 0) throw new KernelError("logger 内部错误：目的地列表为空", "UNKNOWN");
+	return only.stream;
+}
+/**
+* 创建 pino logger：console（pretty）+ 可选文件，统一 level / redact。
+*
+* 文件目的地用同步写入（`sync: true`）：日志量级下性能可接受，且进程退出不丢日志，
+* 无需额外的 flush 步骤（对比异步 SonicBoom 的 flushSync 时序陷阱）。
+*/
+function createLogger(opts = {}) {
+	const level = opts.level ?? "info";
+	const consoleEnabled = opts.console ?? true;
+	const { file, base } = opts;
+	const streams = [];
+	if (consoleEnabled) streams.push({ stream: (0, pino_pretty.default)({
+		colorize: true,
+		translateTime: "SYS:HH:MM:ss.l",
+		singleLine: false,
+		destination: node_process.default.stdout
+	}) });
+	if (file) {
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(file), { recursive: true });
+		streams.push({ stream: pino.default.destination({
+			dest: file,
+			sync: true
+		}) });
+	}
+	if (streams.length === 0) throw new KernelError("logger 至少需要一个输出目标：console 或 file", "INVALID_PARAM");
+	const pinoOptions = {
+		level,
+		redact: [...DEFAULT_REDACT_PATHS, ...opts.redact ?? []]
+	};
+	if (base) pinoOptions.base = {
+		pid: node_process.default.pid,
+		...base
+	};
+	let stream;
+	if (streams.length === 1) stream = toSingle(streams);
+	else stream = pino.default.multistream(streams);
+	return (0, pino.default)(pinoOptions, stream);
+}
+//#endregion
+//#region src/infra/paths.ts
+/**
+* 数据目录布局（ADR-016，2026-08-08 修订：数据根默认放项目根）
+*
+* ```
+* <数据根>/<qq号>/             # 每账号独立目录（ADR-015 多账号前提）
+* ├── config/                  # 各账号独立配置（历史产物，协议段已走 seed）
+* ├── logs/                    # pino 文件日志
+* └── cache/                   # 临时文件、媒体缓存
+*
+* <项目根>/napuketto.toml      # 全局配置文件（放项目根目录，不入库）
+* <项目根>/.napuketto/         # 数据根（默认值，2026-08-08 用户拍板：直接放项目主目录）
+* ```
+*
+* 数据根优先级：cli `--data-dir`（显式参数）> `NAPKETTO_DATA` 环境变量 >
+* `<项目根>/.napuketto`（默认，部署原因不放用户目录）。
+* 配置文件路径见 `resolveConfigPath`（项目根探测，与数据根解耦）。
+*/
+/** 默认数据根目录名（项目根下，2026-08-08 用户拍板：不放用户目录）。 */
+const DEFAULT_DATA_ROOT_NAME = ".napuketto";
+/** 全局配置文件名。 */
+const MAIN_CONFIG_FILE = "napuketto.toml";
+/** `~` 前缀展开为用户主目录（跨平台配置文件写法 `dataDir = "~/.napuketto"`）。 */
+function expandTilde(p) {
+	if (p === "~") return (0, node_os.homedir)();
+	if (p.startsWith("~/") || p.startsWith("~\\")) return (0, node_path.join)((0, node_os.homedir)(), p.slice(2));
+	return p;
+}
+/**
+* 项目根查找：入口模块向上找 `pnpm-workspace.yaml`（monorepo 开发场景，即仓库根）→
+* cwd 向上找 `pnpm-workspace.yaml` / `package.json`（发布后用户项目）→ undefined（兜底）。
+*/
+function resolveProjectRoot() {
+	const moduleRoot = findProjectRoot((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)), "pnpm-workspace.yaml");
+	if (moduleRoot !== void 0) return moduleRoot;
+	return findProjectRoot(node_process.default.cwd(), "pnpm-workspace.yaml") ?? findProjectRoot(node_process.default.cwd(), "package.json");
+}
+/**
+* 解析数据根：显式参数 > 环境变量 > `<项目根>/.napuketto`（默认）> 用户目录兜底（裸脚本）。
+* 支持 `~` 前缀（展开为用户主目录）与相对路径（相对 cwd 解析）。
+* 返回绝对路径。独立导出便于 cli / 探测脚本复用。
+*/
+function resolveDataRoot(dataRoot) {
+	const explicit = dataRoot ?? node_process.default.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return (0, node_path.resolve)(expandTilde(explicit));
+	const projectRoot = resolveProjectRoot();
+	if (projectRoot !== void 0) return (0, node_path.join)(projectRoot, DEFAULT_DATA_ROOT_NAME);
+	return (0, node_path.join)((0, node_os.homedir)(), DEFAULT_DATA_ROOT_NAME);
+}
+/** 向上查找含标志文件的目录（项目根探测：monorepo 根 / 用户项目根）。 */
+function findProjectRoot(startDir, marker) {
+	let dir = startDir;
+	for (;;) {
+		if ((0, node_fs.existsSync)((0, node_path.join)(dir, marker))) return dir;
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/**
+* 全局配置文件路径解析（2026-08-07 用户拍板：**配置文件放项目根目录，
+* 数据仍按数据根组织**——数据根只承载账号目录/日志/缓存/QQ 数据）。
+*
+* 优先级：
+*  1. `NAPKETTO_CONFIG` 环境变量（显式指定完整路径，任意场景可用）
+*  2. 项目根探测（入口模块向上找 pnpm-workspace.yaml → cwd 向上找，见 resolveProjectRoot）
+*  3. 数据根兜底 `<dataRoot>/napuketto.toml`（旧行为兼容）
+*
+* 返回绝对路径。独立导出便于 cli / loader 装配链复用。
+*/
+function resolveConfigPath(opts = {}) {
+	const explicit = node_process.default.env["NAPKETTO_CONFIG"];
+	if (explicit !== void 0 && explicit !== "") return (0, node_path.resolve)(explicit);
+	const projectRoot = resolveProjectRoot();
+	if (projectRoot !== void 0) return (0, node_path.join)(projectRoot, MAIN_CONFIG_FILE);
+	return (0, node_path.join)(opts.dataRoot ?? resolveDataRoot(), MAIN_CONFIG_FILE);
+}
+/**
+* 路径装配器：持有账号数据目录下的全部子目录。
+* 无全局单例（ADR-015 推论）——每账号每进程实例化一份。
+*/
+var PathWrapper = class {
+	/** 数据根（绝对路径）。 */
+	root;
+	/** 账号数据目录（绝对路径），缺省 account 时等于 root。 */
+	accountDir;
+	/** config 目录（napuketto.json + 各协议配置）。 */
+	configDir;
+	/** logs 目录（pino 文件日志）。 */
+	logsDir;
+	/** cache 目录（临时文件、媒体缓存）。 */
+	cacheDir;
+	constructor(opts = {}) {
+		const root = resolveDataRoot(opts.dataRoot);
+		this.root = root;
+		if (opts.account) this.accountDir = (0, node_path.join)(root, opts.account);
+		else this.accountDir = root;
+		this.configDir = (0, node_path.join)(this.accountDir, "config");
+		this.logsDir = (0, node_path.join)(this.accountDir, "logs");
+		this.cacheDir = (0, node_path.join)(this.accountDir, "cache");
+	}
+	/** 递归创建全部目录，启动装配时调用一次。 */
+	ensure() {
+		for (const dir of [
+			this.configDir,
+			this.logsDir,
+			this.cacheDir
+		]) (0, node_fs.mkdirSync)(dir, { recursive: true });
+	}
+	/** 账号目录内的文件路径（如 `file('config', 'napuketto.json')`）。 */
+	file(...segments) {
+		return (0, node_path.join)(this.accountDir, ...segments);
+	}
+	/**
+	* 清空缓存目录（clean_cache 动作经注入回调消费）。
+	* 只删除 cacheDir 下的条目，保留目录本身。
+	*/
+	clearCache() {
+		let entries;
+		try {
+			entries = (0, node_fs.readdirSync)(this.cacheDir);
+		} catch {
+			return;
+		}
+		for (const entry of entries) (0, node_fs.rmSync)((0, node_path.join)(this.cacheDir, entry), {
+			recursive: true,
+			force: true
+		});
+	}
+};
+//#endregion
+//#region src/apis/result.ts
+/**
+* 原生调用结果解包（ADR-009 统一错误语义）
+*
+* wrapper.node 的 service 方法大多返回 `{ result, errMsg }`：
+*  - unwrap：result 为 number 且非 0 → 抛 KernelError
+*  - checkLooseResult：宽松形状（result 可能缺失/非数字）→ 仅当 result 为
+*    数字且非 0 时抛错（探测期兼容：某些 API 成功时 result 缺省或为对象）
+*  - unwrapResult：result !== 0 → 按 errMsg 内容映射语义错误码（msg 系专用）
+*/
+/** errMsg 关键词 → 错误码规则（顺序即优先级，命中任一组关键词即映射）。 */
+const RESULT_CODE_RULES = [
+	{
+		code: "NOT_LOGIN",
+		keywords: ["未登录", "login"]
+	},
+	{
+		code: "PERMISSION_DENIED",
+		keywords: ["无权限", "permission"]
+	},
+	{
+		code: "NOT_FOUND",
+		keywords: ["不存在", "not found"]
+	}
+];
+/** 按 errMsg 关键词映射错误码（未命中 → UNKNOWN）。 */
+function mapResultCode(msg) {
+	for (const rule of RESULT_CODE_RULES) if (rule.keywords.some((k) => msg.includes(k))) return rule.code;
+	return "UNKNOWN";
+}
+/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
+function unwrap(label, result, errMsg) {
+	if (result === 0) return;
+	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
+}
+/** 宽松 result 校验（result 为数字非 0 视为失败；缺失/非数字视为成功）。 */
+function checkLooseResult(label, res) {
+	if (res === void 0 || res === null || typeof res.result !== "number" || res.result === 0) return;
+	throw kernelError(`${label} 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+}
+/** 原生结果解包：result !== 0 抛 KernelError（errMsg 语义映射错误码）。 */
+function unwrapResult(label, raw) {
+	if (raw.result === 0) return;
+	const msg = raw.errMsg || "无错误详情";
+	let code = mapResultCode(msg);
+	if (code === "UNKNOWN" && label === "sendMsg") code = "SEND_FAILED";
+	throw kernelError(`${label} 失败: ${msg}`, code);
+}
+//#endregion
+//#region src/apis/friend.ts
+/**
+* FriendApi：好友语义化 API（ADR-009 统一错误语义）
+*
+* 内部解包原生返回：成功返回纯业务值，失败抛 KernelError。
+* 方法面（P2-4 + P2-11）：好友列表（uid + 昵称/备注）+ 好友请求
+* （getBuddyReq / approvalFriendRequest / setBuddyRemark / delBuddy /
+* getDoubtBuddyReq / approvalDoubtBuddyReq）。
+*/
+/** 好友 API：从 session 拿 buddy service，包装成语义化方法。 */
+var FriendApi = class {
+	service;
+	uidToUin;
+	constructor(session, opts = {}) {
+		const service = session.getBuddyService();
+		if (service === null || service === void 0) throw kernelError("getBuddyService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+		this.uidToUin = opts.uidToUin;
+	}
+	/** 好友列表（分类拍平为 Friend[]；昵称/备注从 service 缓存读取）。 */
+	async getFriendList() {
+		let categories;
+		try {
+			categories = await this.service.getBuddyListFromCache(0);
+		} catch {
+			const raw = await this.service.getBuddyListV2("cli", true, 0);
+			if (raw.result !== 0) throw kernelError(`getBuddyListV2 失败: ${raw.errMsg}`, "UNKNOWN");
+			categories = raw.data;
+		}
+		const uids = categories.flatMap((cat) => cat.buddyUids);
+		let uinMap = /* @__PURE__ */ new Map();
+		if (this.uidToUin !== void 0) uinMap = await this.uidToUin(uids);
+		const out = [];
+		for (const uid of uids) out.push({
+			uid,
+			uin: uinMap.get(uid) ?? uid,
+			nickname: this.service.getBuddyNick(uid),
+			remark: this.service.getBuddyRemark(uid)
+		});
+		return out;
+	}
+	/** 带分类的好友列表（get_friends_with_category，分类保留）。 */
+	async getFriendCategories() {
+		const categories = await this.getBuddyCategories();
+		const friendMap = /* @__PURE__ */ new Map();
+		for (const friend of await this.getFriendList()) friendMap.set(friend.uid, friend);
+		return categories.map((cat) => {
+			const buddies = [];
+			for (const uid of cat.buddyUids) {
+				const friend = friendMap.get(uid);
+				if (friend !== void 0) buddies.push(friend);
+			}
+			return {
+				categoryId: cat.categoryId,
+				categorySortId: cat.categorySortId,
+				categoryName: cat.categroyName,
+				categoryMbCount: cat.categroyMbCount,
+				onlineCount: cat.onlineCount,
+				buddyList: buddies
+			};
+		});
+	}
+	/** 原始分类（getBuddyListV2 / 缓存）。 */
+	async getBuddyCategories() {
+		try {
+			return await this.service.getBuddyListFromCache(0);
+		} catch {
+			const raw = await this.service.getBuddyListV2("cli", true, 0);
+			if (raw.result !== 0) throw kernelError(`getBuddyListV2 失败: ${raw.errMsg}`, "UNKNOWN");
+			return raw.data;
+		}
+	}
+	/** 判断是否好友。 */
+	isBuddy(uid) {
+		return this.service.isBuddy(uid);
+	}
+	/** 好友申请列表（set_friend_add_request 应答前查找匹配项）。 */
+	async getBuddyReqList() {
+		const raw = await this.service.getBuddyReq();
+		unwrap("getBuddyReq", raw.result, raw.errMsg);
+		return raw.buddyReqs ?? [];
+	}
+	/** 应答好友申请（accept=true 同意；remark 由调用方另行 setFriendRemark）。 */
+	async handleFriendRequest(notify, accept) {
+		await this.service.approvalFriendRequest({
+			friendUid: notify.friendUid,
+			reqTime: notify.reqTime,
+			accept
+		});
+	}
+	/** 设置好友备注（void 语义乐观处理）。 */
+	setFriendRemark(uid, remark) {
+		this.service.setBuddyRemark({
+			uid,
+			remark
+		});
+	}
+	/** 删除好友（tempBlock=拉黑，tempBothDel=双向删除）。 */
+	async deleteFriend(uid, tempBlock = false, tempBothDel = false) {
+		checkLooseResult("delBuddy", await this.service.delBuddy({
+			friendUid: uid,
+			tempBlock,
+			tempBothDel
+		}));
+	}
+	/** 可疑好友申请列表（get_doubt_friends_add_request；uin 经 uidToUin 转换）。 */
+	async getDoubtFriendRequest(count) {
+		const reqId = String(Date.now());
+		const raw = await this.service.getDoubtBuddyReq(reqId, count, "");
+		unwrap("getDoubtBuddyReq", raw.result, raw.errMsg);
+		const list = raw.doubtList ?? [];
+		let uinMap = /* @__PURE__ */ new Map();
+		if (this.uidToUin !== void 0 && list.length > 0) uinMap = await this.uidToUin(list.map((item) => item.uid));
+		const out = [];
+		for (const item of list) out.push(this.toDoubtFriendRequestInfo(item, uinMap));
+		return out;
+	}
+	/** 单项转换：DoubtBuddyReq → OB11 结构（可选字段条件赋值，exactOptionalPropertyTypes）。 */
+	toDoubtFriendRequestInfo(item, uinMap) {
+		return toDoubtFriendRequestInfo(item, uinMap);
+	}
+	/** 处理可疑好友申请（set_doubt_friends_add_request；uid=flag）。 */
+	handleDoubtFriendRequest(uid) {
+		this.service.approvalDoubtBuddyReq(uid, "", "");
+	}
+};
+/** 可选字段条件赋值（undefined 跳过，兼容 exactOptionalPropertyTypes）。 */
+function assignOptional(info, key, value) {
+	if (value !== void 0) info[key] = value;
+}
+/** 单项转换：DoubtBuddyReq → OB11 结构（导出供单测，friend.test.ts）。 */
+function toDoubtFriendRequestInfo(item, uinMap) {
+	const info = {
+		flag: item.uid,
+		uin: Number(uinMap.get(item.uid) ?? item.uid),
+		type: "doubt"
+	};
+	assignOptional(info, "nick", item.nick);
+	assignOptional(info, "source", item.source);
+	assignOptional(info, "reason", item.reason);
+	assignOptional(info, "msg", item.msg);
+	assignOptional(info, "group_code", item.groupCode);
+	assignOptional(info, "time", item.reqTime);
+	return info;
+}
+//#endregion
+//#region src/types/entities.ts
+/**
+* 实体类型层（运行时探测产物 + 公开资料作说明书，ADR-006）
+*
+* ⚠️ 部分字段按公开资料（wrapper 外部契约）自研描述，待下一次进程内
+* 探测（probe.ts）校准——接口签名是外部系统事实，自研描述其形状。
+*/
+/** 会话类型（QQ wrapper 外部契约）。 */
+const ChatType = {
+	C2C: 1,
+	GROUP: 2,
+	DISC: 3,
+	GUILD: 4,
+	C2C_TEMP: 100
+};
+/** 灰色提示子类型（系统事件类型，QQ wrapper 契约）。 */
+const GrayTipSubType = {
+	REVOKE: 1,
+	PROCLAMATION: 2,
+	GROUP: 4,
+	BUDDY: 5,
+	FEED: 6,
+	ESSENCE: 7,
+	GROUP_NOTIFY: 8,
+	BUDDY_NOTIFY: 9,
+	FILE: 10,
+	JSON: 17
+};
+/** 群成员变动类型（TipGroupElement.type）。 */
+const TipGroupElementType = {
+	MEMBER_ADD: 1,
+	DISBANDED: 2,
+	QUIT: 3,
+	CREATED: 4,
+	GROUP_NAME_MODIFIED: 5,
+	BLOCK: 6,
+	UNBLOCK: 7,
+	SHUT_UP: 8
+};
+//#endregion
+//#region src/types/listeners/group.ts
+/** 群列表更新类型（说明书参考，值待探测校准）。 */
+const GroupListUpdateType = {
+	/** 全量更新（groupList 为完整列表）。 */
+	ALL: 0,
+	/** 增量更新（合并到现有缓存）。 */
+	PARTIAL: 1
+};
+//#endregion
+//#region src/types/services/msg-service.ts
+/** 消息元素类型枚举（QQ wrapper 外部契约，自研描述）。 */
+const ElementType = {
+	UNKNOWN: 0,
+	TEXT: 1,
+	PIC: 2,
+	FILE: 3,
+	PTT: 4,
+	VIDEO: 5,
+	FACE: 6,
+	REPLY: 7,
+	GRAY_TIP: 8,
+	WALLET: 9,
+	ARK: 10,
+	MFACE: 11,
+	LIVE_GIFT: 12,
+	STRUCT_LONG_MSG: 13,
+	MARKDOWN: 14,
+	GIPHY: 15,
+	MULTI_FORWARD: 16,
+	INLINE_KEYBOARD: 17,
+	INTEXT_GIFT: 18,
+	CALENDAR: 19
+};
+//#endregion
+//#region src/types/message-element.ts
+/**
+* canonical 消息元素模型（协议无关，ADR-008 延伸）
+*
+* 描述 QQ 消息的事实结构，是各协议翻译层的公共中间表示：
+* kernel 只做一次 NT ↔ canonical（toCanonicalElements / toSendElements），
+* 各协议（onebot11/satori）只写薄映射 canonical ↔ 协议格式。
+*/
+/** 文本 at 类型（QQ wrapper 契约，自研描述）。 */
+const AtType = {
+	ALL: 1,
+	ONE: 2,
+	ME: 4
+};
+/** TEXT 元素 → canonical（at 或纯文本）。 */
+function textToCanonical(textEl) {
+	if (textEl === void 0) return {
+		type: "text",
+		text: ""
+	};
+	const { atType, atUid, content } = textEl;
+	if (atType === AtType.ALL) return {
+		type: "at",
+		target: "all"
+	};
+	if (atType === AtType.ONE || atType === AtType.ME) {
+		const base = {
+			type: "at",
+			target: atUid ?? content
+		};
+		const display = content.startsWith("@") ? content.slice(1) : content;
+		if (display === "") return base;
+		return {
+			...base,
+			display
+		};
+	}
+	return {
+		type: "text",
+		text: content
+	};
+}
+/** PIC 元素 → canonical image。 */
+function picToCanonical(pic) {
+	if (pic === void 0) return {
+		type: "image",
+		path: ""
+	};
+	const path = pic.picPath ?? pic.picUrl ?? "";
+	const url = pic.picUrl;
+	if (url === void 0) return {
+		type: "image",
+		path
+	};
+	return {
+		type: "image",
+		path,
+		url
+	};
+}
+/** FACE 元素 → canonical face。 */
+function faceToCanonical(face) {
+	if (face === void 0) return {
+		type: "face",
+		id: "0"
+	};
+	return {
+		type: "face",
+		id: String(face.faceIndex)
+	};
+}
+/** PTT 元素 → canonical voice。 */
+function pttToCanonical(ptt) {
+	if (ptt === void 0) return {
+		type: "voice",
+		path: ""
+	};
+	return {
+		type: "voice",
+		path: ptt.filePath ?? ""
+	};
+}
+/** VIDEO 元素 → canonical video。 */
+function videoToCanonical(video) {
+	if (video === void 0) return {
+		type: "video",
+		path: ""
+	};
+	const path = video.filePath ?? video.videoUrl ?? "";
+	const url = video.videoUrl;
+	if (url === void 0) return {
+		type: "video",
+		path
+	};
+	return {
+		type: "video",
+		path,
+		url
+	};
+}
+/** FILE 元素 → canonical file。 */
+function fileToCanonical(file) {
+	if (file === void 0) return {
+		type: "file",
+		path: ""
+	};
+	const path = file.filePath ?? "";
+	const name = file.fileName;
+	if (name === void 0) return {
+		type: "file",
+		path
+	};
+	return {
+		type: "file",
+		path,
+		name
+	};
+}
+/** REPLY 元素 → canonical reply。 */
+function replyToCanonical(reply) {
+	if (reply === void 0) return {
+		type: "reply",
+		messageId: ""
+	};
+	return {
+		type: "reply",
+		messageId: reply.replayMsgId
+	};
+}
+/** 单个 NT 元素 → canonical（接收方向，宽容：无法表达回 unknown，不抛错）。 */
+function toCanonicalElement(el) {
+	switch (el.elementType) {
+		case ElementType.TEXT: return textToCanonical(el.textElement);
+		case ElementType.PIC: return picToCanonical(el.picElement);
+		case ElementType.FACE: return faceToCanonical(el.faceElement);
+		case ElementType.PTT: return pttToCanonical(el.pttElement);
+		case ElementType.VIDEO: return videoToCanonical(el.videoElement);
+		case ElementType.FILE: return fileToCanonical(el.fileElement);
+		case ElementType.REPLY: return replyToCanonical(el.replyElement);
+		default: return {
+			type: "unknown",
+			raw: el
+		};
+	}
+}
+/** NT RawMessage → canonical 元素（与 toSendElements 对称，接收方向）。 */
+function toCanonicalElements(msg) {
+	return msg.elements.map(toCanonicalElement);
+}
+/** canonical 元素 → NT 发送元素（text/at/face/image/voice/reply 核心五类）。 */
+function toSendElements(elements) {
+	const out = [];
+	for (const el of elements) switch (el.type) {
+		case "text":
+			out.push({
+				elementType: ElementType.TEXT,
+				textElement: { content: el.text }
+			});
+			break;
+		case "at":
+			if (el.target === "all") out.push({
+				elementType: ElementType.TEXT,
+				textElement: {
+					content: el.display ?? "@",
+					atType: 1
+				}
+			});
+			else out.push({
+				elementType: ElementType.TEXT,
+				textElement: {
+					content: el.display ?? "@",
+					atType: 2,
+					atUid: el.target
+				}
+			});
+			break;
+		case "face":
+			out.push({
+				elementType: ElementType.FACE,
+				faceElement: { faceIndex: Number(el.id) }
+			});
+			break;
+		case "image":
+			out.push({
+				elementType: ElementType.PIC,
+				picElement: { picPath: el.path }
+			});
+			break;
+		case "voice":
+			out.push({
+				elementType: ElementType.PTT,
+				pttElement: { filePath: el.path }
+			});
+			break;
+		case "reply":
+			out.push({
+				elementType: ElementType.REPLY,
+				replyElement: {
+					replayMsgId: el.messageId,
+					replayMsgSeq: el.messageId,
+					replayMsgTime: "0"
+				}
+			});
+			break;
+		case "video":
+		case "file":
+		case "forward":
+		case "json":
+		case "xml":
+		case "unknown": throw kernelError(`发送元素 ${el.type} 暂不支持（P2-2 探测后补）`, "INVALID_PARAM");
+	}
+	return out;
+}
+//#endregion
+//#region src/types/services/group-service.ts
+/** 群成员角色（QQ wrapper 契约）。 */
+const NTGroupMemberRole = {
+	UNSPECIFIED: 0,
+	STRANGER: 1,
+	MEMBER: 2,
+	ADMIN: 3,
+	OWNER: 4
+};
+/** 群通知类型（GroupNotifyMsgType，说明书参考）。 */
+const GroupNotifyMsgType = {
+	UN_SPECIFIED: 0,
+	INVITED_BY_MEMBER: 1,
+	REFUSE_INVITED: 2,
+	REFUSED_BY_ADMINI_STRATOR: 3,
+	AGREED_TOJOIN_DIRECT: 4,
+	INVITED_NEED_ADMINI_STRATOR_PASS: 5,
+	AGREED_TO_JOIN_BY_ADMINI_STRATOR: 6,
+	REQUEST_JOIN_NEED_ADMINI_STRATOR_PASS: 7,
+	SET_ADMIN: 8,
+	KICK_MEMBER_NOTIFY_ADMIN: 9,
+	KICK_MEMBER_NOTIFY_KICKED: 10,
+	MEMBER_LEAVE_NOTIFY_ADMIN: 11,
+	CANCEL_ADMIN_NOTIFY_CANCELED: 12,
+	CANCEL_ADMIN_NOTIFY_ADMIN: 13,
+	TRANSFER_GROUP_NOTIFY_OLDOWNER: 14,
+	TRANSFER_GROUP_NOTIFY_ADMIN: 15
+};
+/** 群通知处理状态（GroupNotifyMsgStatus，说明书参考）。 */
+const GroupNotifyMsgStatus = {
+	KINIT: 0,
+	KUNHANDLE: 1,
+	KAGREED: 2,
+	KREFUSED: 3,
+	KIGNORED: 4
+};
+/** 群请求操作类型（NTGroupRequestOperateTypes，说明书参考）。 */
+const NTGroupRequestOperateTypes = {
+	KUNSPECIFIED: 0,
+	KAGREE: 1,
+	KREFUSE: 2,
+	KIGNORE: 3,
+	KDELETE: 4
+};
+//#endregion
+//#region src/types/wrapper.ts
+/**
+* wrapper.node 的 NAPI 接口面（自研描述，非移植）
+*
+* 来源：wrapper.node 在 QQ 定制版 Electron 里通过 napi_define_class / napi_set_named_property
+* 注册的 JS 类（2026-08-05 Ghidra 反编译 FUN_180c6274a / FUN_180c80224 确认类名）。
+* 这些接口是 wrapper.node 对外暴露的外部系统契约——我们自研描述其形状，未复制任何第三方代码。
+*
+* 注意：这里所有对象由 QQ 运行时的 NAPI 层自动构建/转换，业务层禁止触碰 C++ ABI。
+*/
+/** 平台类型（与 wrapper.node 的 platform 字段对应）。 */
+const PlatformType = {
+	KUNKNOWN: 0,
+	KANDROID: 1,
+	KIOS: 2,
+	KWINDOWS: 3,
+	KMAC: 4,
+	KLINUX: 5
+};
+/** 厂商类型（deviceInfo.vendorType）。 */
+const VendorType = {
+	KNOSETONIOS: 0,
+	KUNSUPPORTANDROIDPUSH: 1,
+	KSUPPORTTPNS: 2,
+	KSUPPORTHMS: 3,
+	KSUPPORTOPPOPUSH: 4,
+	KSUPPORTVIVOPUSH: 5,
+	KSUPPORTGOOGLEPUSH: 99
+};
+//#endregion
+//#region src/apis/group.ts
+/**
+* GroupApi：群语义化 API（ADR-009 统一错误语义）
+*
+* 内部解包原生返回：成功返回纯业务值，失败抛 KernelError。
+* 方法面（P2-4 + P2-10）：群列表 / 群详情 / 成员列表 / 成员详情 / uin↔uid +
+* 群管操作（踢人 / 禁言 / 管理员 / 名片 / 群名 / 退群 / 精华消息 / @all 剩余）。
+*/
+/** 群 API：从 session 拿 group service，包装成语义化方法。 */
+var GroupApi = class {
+	service;
+	/** 精华消息需要 msg service（按 msgId 拉消息取 msgSeq/msgRandom）。 */
+	msgService;
+	constructor(session) {
+		const service = session.getGroupService();
+		if (service === null || service === void 0) throw kernelError("getGroupService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+		const msgService = session.getMsgService();
+		if (msgService === null || msgService === void 0) throw kernelError("getMsgService() 返回空（session 未 init）", "INVALID_STATE");
+		this.msgService = msgService;
+	}
+	/**
+	* 群列表（force=true 触发原生刷新）。
+	*
+	* ⚠️ 实测校准（2026-08-08 端到端联调）：原生 getGroupList 返回仅
+	* `{ result, errMsg }`——**列表数据经 onGroupListUpdate 事件推送**，
+	* 不走返回值。消费群列表一律从 `GroupCache.listGroups()` 读（缓存由
+	* 事件主动维护）；本方法仅作「触发刷新」用，返回值恒为 []。
+	*/
+	async getGroupList(force = false) {
+		const raw = await this.service.getGroupList(force);
+		if (raw.result !== 0) unwrap("getGroupList", raw.result, raw.errMsg);
+		return [];
+	}
+	/** 群详情（groupCode 为群号字符串）。
+	* getGroupDetailInfo 返回形状：失败 result=错误码；成功详情可能直接在 result
+	* 对象里，也可能在 groupInfo/detailInfo 字段——三种形状都兼容（探测校准）。
+	* 2026-08-07 修复：成功（result=0）时不再把 {result:0,errMsg} 原样当详情返回，
+	* 而是提取详情字段；形状异常抛 UNKNOWN 而非静默返回垃圾数据。 */
+	async getGroupInfo(groupCode) {
+		const raw = await this.service.getGroupDetailInfo(groupCode, 0);
+		const { result, errMsg } = raw;
+		if (typeof result === "number" && result !== 0) unwrap("getGroupDetailInfo", result, errMsg);
+		const detail = extractGroupDetail(result, raw);
+		if (detail === null) throw kernelError(`getGroupDetailInfo 返回形状异常（groupCode=${groupCode}）: ${errMsg}`, "UNKNOWN");
+		return detail;
+	}
+	/** 群成员列表（forceFetch=true 强制拉取，默认缓存优先）。 */
+	async getGroupMemberList(groupCode, forceFetch = false) {
+		const raw = await this.service.getAllMemberList(groupCode, forceFetch);
+		if (raw.errCode !== 0) throw kernelError(`getAllMemberList 失败: ${raw.errMsg}`, "UNKNOWN");
+		return [...raw.result.infos.values()];
+	}
+	/** 群成员详情（uids 为空返回空数组）。 */
+	async getGroupMemberInfo(groupCode, uids) {
+		if (uids.length === 0) return [];
+		const raw = await this.service.getMemberInfo(groupCode, uids, true);
+		unwrap("getMemberInfo", raw.result, raw.errMsg);
+		const { infos } = raw;
+		if (infos instanceof Map) return [...infos.values()];
+		return [];
+	}
+	/** uin → uid（私聊发送等需要）。 */
+	async uinToUid(uins) {
+		if (uins.length === 0) return /* @__PURE__ */ new Map();
+		const raw = await this.service.getUidByUins(uins);
+		if (raw.errCode !== 0) throw kernelError(`getUidByUins 失败: ${raw.errMsg}`, "UNKNOWN");
+		return raw.uids;
+	}
+	/** uid → uin。 */
+	async uidToUin(uids) {
+		if (uids.length === 0) return /* @__PURE__ */ new Map();
+		const raw = await this.service.getUinByUids(uids);
+		if (raw.errCode !== 0) throw kernelError(`getUinByUids 失败: ${raw.errMsg}`, "UNKNOWN");
+		return raw.uins;
+	}
+	/** 群成员角色 → OB11 role 字符串。 */
+	static roleToString(role) {
+		if (role === NTGroupMemberRole.OWNER) return "owner";
+		if (role === NTGroupMemberRole.ADMIN) return "admin";
+		return "member";
+	}
+	/**
+	* 踢人（set_group_kick）。memberUids 为成员 uid；refuseForever=true 拉黑拒绝再次入群。
+	* kickMemberV2 的 kickFlag/kickList 字段值待探测校准（TODO P3 联调）。
+	*/
+	async kickMember(groupCode, memberUids, refuseForever, reason = "") {
+		if (memberUids.length === 0) throw kernelError("kickMember 需要至少一个成员 uid", "INVALID_PARAM");
+		let optFlag = 1;
+		if (refuseForever) optFlag = 0;
+		const req = {
+			groupCode,
+			kickFlag: 0,
+			kickList: memberUids.map((uid) => ({
+				optFlag,
+				optOperate: 0,
+				optMemberUid: uid,
+				optBytesMsg: ""
+			})),
+			kickListUids: memberUids,
+			kickMsg: reason
+		};
+		const raw = await this.service.kickMemberV2(req);
+		unwrap("kickMemberV2", raw.result, raw.errMsg);
+	}
+	/** 成员禁言（duration 秒，0 解除禁言）。 */
+	async setMemberShutUp(groupCode, members) {
+		if (members.length === 0) throw kernelError("setMemberShutUp 需要至少一个成员", "INVALID_PARAM");
+		const raw = await this.service.setMemberShutUp(groupCode, members.map((m) => ({
+			uid: m.uid,
+			timeStamp: m.duration
+		})));
+		unwrap("setMemberShutUp", raw.result, raw.errMsg);
+	}
+	/** 全员禁言（enable=true 开启全群禁言）。 */
+	async setGroupShutUp(groupCode, enable) {
+		const raw = await this.service.setGroupShutUp(groupCode, enable);
+		unwrap("setGroupShutUp", raw.result, raw.errMsg);
+	}
+	/** 设置管理员（role=ADMIN 设管理，MEMBER 取消；void 语义乐观处理）。 */
+	setMemberRole(groupCode, uid, role) {
+		this.service.modifyMemberRole(groupCode, uid, role);
+	}
+	/** 设置群名片（void 语义乐观处理）。 */
+	setMemberCardName(groupCode, uid, cardName) {
+		this.service.modifyMemberCardName(groupCode, uid, cardName);
+	}
+	/** 修改群名。 */
+	async modifyGroupName(groupCode, groupName) {
+		const raw = await this.service.modifyGroupName(groupCode, groupName, false);
+		unwrap("modifyGroupName", raw.result, raw.errMsg);
+	}
+	/** 退群（needDeleteLocalMsg=is_dismiss：是否解散群，仅群主）。 */
+	async quitGroup(groupCode, needDeleteLocalMsg = false) {
+		const raw = await this.service.quitGroupV2({
+			groupCode,
+			needDeleteLocalMsg
+		});
+		unwrap("quitGroupV2", raw.result, raw.errMsg);
+	}
+	/** 设置精华消息（msgId 经 msgService 取 msgSeq/msgRandom）。 */
+	async addGroupEssence(groupCode, msgId) {
+		await this.setEssence(groupCode, msgId, true);
+	}
+	/** 取消精华消息。 */
+	async removeGroupEssence(groupCode, msgId) {
+		await this.setEssence(groupCode, msgId, false);
+	}
+	/** 精华消息公共流程：按 msgId 拉消息 → add/removeGroupEssence。 */
+	async setEssence(groupCode, msgId, add) {
+		const peer = {
+			chatType: ChatType.GROUP,
+			peerUid: groupCode
+		};
+		const raw = await this.msgService.getMsgsByMsgId(peer, [msgId]);
+		unwrap("getMsgsByMsgId", raw.result, raw.errMsg);
+		const msg = raw.msgList?.[0];
+		if (msg === void 0) throw kernelError(`消息 ${msgId} 不存在`, "NOT_FOUND");
+		const param = {
+			groupCode,
+			msgRandom: Number(msg.msgRandom ?? 0),
+			msgSeq: Number(msg.msgSeq)
+		};
+		let label = "removeGroupEssence";
+		let res;
+		if (add) {
+			label = "addGroupEssence";
+			res = await this.service.addGroupEssence(param);
+		} else res = await this.service.removeGroupEssence(param);
+		checkLooseResult(label, res);
+	}
+	/** @all 剩余次数（get_group_at_all_remain）。 */
+	async getGroupRemainAtTimes(groupCode) {
+		const raw = await this.service.getGroupRemainAtTimes(groupCode);
+		if (raw.errCode !== 0) throw kernelError(`getGroupRemainAtTimes 失败: ${raw.errMsg}`, "UNKNOWN");
+		return {
+			canAtAll: raw.atInfo.canAtAll,
+			remainAtAllCountForUin: raw.atInfo.remainAtAllCountForUin,
+			remainAtAllCountForGroup: raw.atInfo.remainAtAllCountForGroup
+		};
+	}
+};
+/**
+* 从 getGroupDetailInfo 返回提取群详情（兼容三种形状）：
+*  - result 为对象 → 详情直接在其中（最常见）
+*  - result 为 0/空 → 从 raw.groupInfo / detailInfo / info 提取
+* 提取不到返回 null（调用方抛 UNKNOWN）。导出供单测。
+*/
+function extractGroupDetail(result, raw) {
+	if (result !== null && typeof result === "object") return result;
+	const detail = raw;
+	const candidate = detail.groupInfo ?? detail.detailInfo ?? detail.info;
+	if (candidate !== void 0 && candidate !== null && typeof candidate === "object") return candidate;
+	return null;
+}
+//#endregion
+//#region src/apis/group-notify.ts
+/**
+* GroupNotifyApi：群通知/禁言列表语义化 API（ADR-009 统一错误语义，P2-13）
+*
+* get_group_system_msg / set_group_add_request / get_group_shut_list 共用。
+* getSingleScreenNotifies / getGroupShutUpMemberList 的列表可能走 listener 回调，
+* 直接调用返回形状待探测校准：兼容 result 数组 / 字段 / 直接数组。
+*/
+/** 群通知 API：从 session 拿 group service，包装成语义化方法。 */
+var GroupNotifyApi = class {
+	service;
+	constructor(session) {
+		const service = session.getGroupService();
+		if (service === null || service === void 0) throw kernelError("getGroupService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 单屏通知列表（get_group_system_msg / set_group_add_request 共用）。 */
+	async getSingleScreenNotifies(doubt, count) {
+		return extractNotifyList((await this.service.getSingleScreenNotifies(doubt, "", count)).result);
+	}
+	/** 禁言成员列表（get_group_shut_list）。 */
+	async getGroupShutUpMemberList(groupCode) {
+		const raw = await this.service.getGroupShutUpMemberList(groupCode);
+		if (raw.result !== 0) unwrap("getGroupShutUpMemberList", raw.result, raw.errMsg);
+		return extractMemberList(raw.result);
+	}
+	/** 处理群请求（set_group_add_request 应答；approve=true 同意 / false 拒绝）。 */
+	async handleGroupRequest(doubt, notify, operateType, reason) {
+		const { group, seq, type } = notify;
+		let groupCode = "";
+		if (group !== void 0) ({groupCode} = group);
+		let postscript = reason;
+		if (postscript === "") postscript = " ";
+		await this.service.operateSysNotify(doubt, {
+			operateType,
+			targetMsg: {
+				seq,
+				type,
+				groupCode,
+				postscript
+			}
+		});
+	}
+};
+/** 从 getSingleScreenNotifies 返回提取通知数组（兼容 result 数组 / notifies 字段）。 */
+function extractNotifyList(result) {
+	if (Array.isArray(result)) return result;
+	if (result !== null && typeof result === "object") {
+		const obj = result;
+		if (Array.isArray(obj.notifies)) return obj.notifies;
+		if (Array.isArray(obj.groupNotifies)) return obj.groupNotifies;
+	}
+	return [];
+}
+/** 从 getGroupShutUpMemberList 返回提取成员数组（兼容 result 数组 / memberList 字段）。 */
+function extractMemberList(result) {
+	if (Array.isArray(result)) return result;
+	if (result !== null && typeof result === "object") {
+		const obj = result;
+		if (Array.isArray(obj.memberList)) return obj.memberList;
+		if (Array.isArray(obj.list)) return obj.list;
+	}
+	return [];
+}
+//#endregion
+//#region src/apis/msg.ts
+/**
+* MsgApi：消息语义化 API（ADR-009 统一错误语义）
+*
+* 内部解包原生 `{ result, errMsg }`：成功返回纯业务值，失败抛 KernelError。
+* 协议层只维护 `KernelErrorCode → 协议错误码` 映射表，不解析错误逻辑。
+*
+* 方法面（P2-1）：发送 / 撤回 / 拉历史 / 标记已读。group/friend 等后续 apis 同构。
+*/
+/** 发送状态（onMsgInfoListUpdate 事件 msg.sendStatus）。 */
+const SEND_STATUS = {
+	FAILED: 0,
+	SENDING: 1,
+	SUCCESS: 2,
+	SUCCESS_NO_SEQ: 3
+};
+/** 发送确认超时（毫秒）。 */
+const SEND_CONFIRM_TIMEOUT_MS = 15e3;
+/** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
+async function statFile(path) {
+	try {
+		return await (0, node_fs_promises.stat)(path);
+	} catch {
+		throw kernelError(`图片文件不存在: ${path}`, "INVALID_PARAM");
+	}
+}
+/** 计算文件 md5（十六进制小写）。 */
+async function hashFile(path) {
+	try {
+		const buf = await (0, node_fs_promises.readFile)(path);
+		return (0, node_crypto.createHash)("md5").update(buf).digest("hex");
+	} catch {
+		throw kernelError(`图片文件读取失败: ${path}`, "INVALID_PARAM");
+	}
+}
+/** 消息 API：从 session 拿 msg service，包装成语义化方法。 */
+var MsgApi = class {
+	service;
+	/** 消息事件通道（sendMsg 后等 onMsgInfoListUpdate 确认发送结果）。 */
+	channel;
+	/** NodeQQNTWrapperUtil（富媒体发送 copyFile 用；session 拿不到时可为 null）。 */
+	util;
+	/** 上次生成 msgId 的时间（单调递增，2026-08-07 防同毫秒并发碰撞）。 */
+	lastMsgTime = 0;
+	constructor(session, channel, util) {
+		const service = session.getMsgService();
+		if (service === null || service === void 0) throw kernelError("getMsgService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+		this.channel = channel ?? null;
+		this.util = util !== null && util !== void 0 ? util : null;
+	}
+	/**
+	* 生成 msgId 时间戳（单调递增）。
+	* generateMsgUniqueId(chatType, time) 以 time 区分消息——同毫秒并发发送
+	* （机器人群发/多会话同时回复）Date.now() 会碰撞，msgId 相同导致 wrapper
+	* 拒绝或覆盖。严格单调递增保证进程内唯一。
+	*/
+	nextMsgTime() {
+		const now = Date.now();
+		if (now > this.lastMsgTime) this.lastMsgTime = now;
+		else this.lastMsgTime += 1;
+		return String(this.lastMsgTime);
+	}
+	/**
+	* 发送消息：canonical 元素 → NT 发送元素 → sendMsg（NapCat 式）。
+	* 返回 NT msgId（雪花 ID）。
+	*
+	* 2026-08-11 修复（NapCat 式，实测）：
+	*  - sendMsg 第一参传 '0'（固定），msgId 塞 peer.guildId —— 传 msgId 作第一参
+	*    时 wrapper 返回 result=5（失败），NapCat 同款调用返回 result=0。
+	*  - 发送结果以 onMsgInfoListUpdate 事件确认（sendStatus===2 成功）：sendMsg
+	*    返回值 result 可能为 5 但事件仍成功（异步确认），反之亦然。
+	*  - ⚠️ 必须先注册事件监听再调 sendMsg（事件可能在 sendMsg 返回前就触发）。
+	*/
+	async sendMessage(target, elements) {
+		const sendElements = await this.prepareSendElements(elements);
+		const msgId = this.service.generateMsgUniqueId(target.chatType, this.nextMsgTime());
+		const sendPeer = {
+			...target,
+			guildId: msgId
+		};
+		if (this.channel === null) {
+			unwrapResult("sendMsg", await this.service.sendMsg("0", sendPeer, sendElements, /* @__PURE__ */ new Map()));
+			return { msgId };
+		}
+		const confirm = this.confirmSend(msgId, target);
+		await this.service.sendMsg("0", sendPeer, sendElements, /* @__PURE__ */ new Map());
+		await confirm;
+		return { msgId };
+	}
+	/**
+	* canonical 元素 → 发送元素，富媒体（PIC/PTT）做 NapCat 式预处理。
+	* 2026-08-11 修复（实测）：图片发送必须 elementType=2（PIC）+ 完整 picElement
+	* （md5HexStr/fileSize/fileName/sourcePath），且文件须经 getRichMediaFilePathForGuild
+	* 计算目标路径 + util.copyFile 放置——缺任一环节 sendMsg 返回 rich media transfer failed。
+	* 2026-08-12（语音）：PTT 同理——只给 filePath 触发 wrapper 内部
+	* "Cannot convert undefined or null to object"（缺字段转换失败）。
+	*/
+	async prepareSendElements(elements) {
+		const out = [];
+		for (const el of elements) switch (el.type) {
+			case "image":
+				out.push(await this.prepareImageElement(el.path));
+				break;
+			case "voice":
+				out.push(await this.preparePttElement(el.path));
+				break;
+			default: out.push(...toSendElements([el]));
+		}
+		return out;
+	}
+	/** PIC 元素 NapCat 式预处理：md5 → 目标路径 → copyFile → 完整 picElement。 */
+	async prepareImageElement(path) {
+		const file = await statFile(path);
+		const md5 = await hashFile(path);
+		const fileName = (0, node_path.basename)(path);
+		const relPath = await this.placeMediaFile(path, ElementType.PIC, md5, fileName);
+		return {
+			elementType: ElementType.PIC,
+			elementId: "",
+			picElement: {
+				md5HexStr: md5,
+				fileSize: String(file.size),
+				picWidth: 0,
+				picHeight: 0,
+				fileName,
+				sourcePath: relPath,
+				original: true,
+				picType: 1e3,
+				picSubType: 0,
+				fileUuid: "",
+				fileSubId: "",
+				thumbFileSize: 0,
+				summary: ""
+			}
+		};
+	}
+	/**
+	* PTT 元素 NapCat 式预处理：md5 → 目标路径 → copyFile → 完整 pttElement。
+	*
+	* 2026-08-12（实测依据）：只给 filePath 时 wrapper 内部抛
+	* "Cannot convert undefined or null to object"（缺 md5HexStr/fileSize 等字段），
+	* 且发送后进程崩溃重启（supervisor 自动拉起）。完整字段（NapCat 同款，
+	* formatType/voiceType/canConvert2Text/waveAmplitudes 等）消除该错误。
+	*
+	* ⚠️ silk 格式：QQ 语音协议为 silk v3。传入非 silk（ogg/mp3 等）时发送器
+	* 可能拒绝上传（待实测）。转换点预留：此处直接放置原文件，后续接入
+	* ogg → PCM → silk 编码器（外部 ffmpeg + silk-wasm，见 docs/design.md）。
+	*/
+	async preparePttElement(path) {
+		const file = await statFile(path);
+		const md5 = await hashFile(path);
+		const fileName = (0, node_path.basename)(path);
+		const relPath = await this.placeMediaFile(path, ElementType.PTT, md5, fileName);
+		const duration = Math.max(1, Math.floor(file.size / 1024 / 3));
+		return {
+			elementType: ElementType.PTT,
+			elementId: "",
+			pttElement: {
+				fileName,
+				filePath: relPath,
+				md5HexStr: md5,
+				fileSize: String(file.size),
+				duration,
+				formatType: 1,
+				voiceType: 1,
+				voiceChangeType: 0,
+				canConvert2Text: true,
+				waveAmplitudes: [
+					0,
+					18,
+					9,
+					23,
+					16,
+					17,
+					16,
+					15,
+					44,
+					17,
+					24,
+					20,
+					14,
+					15,
+					17
+				],
+				fileSubId: "",
+				playState: 1,
+				autoConvertText: 0,
+				storeID: 0,
+				otherBusinessInfo: { aiVoiceType: 0 }
+			}
+		};
+	}
+	/**
+	* 富媒体文件放置（PIC/PTT 共用）：md5 + 文件名 → QQ 内部目标路径
+	* （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回相对数据根路径。
+	*/
+	async placeMediaFile(path, elementType, md5, fileName) {
+		const service = this.service;
+		const util = this.util;
+		const relPath = service.getRichMediaFilePathForGuild({
+			md5HexStr: md5,
+			fileName,
+			elementType,
+			elementSubType: 0,
+			thumbSize: 0,
+			needCreate: true,
+			downloadType: 1,
+			file_uuid: ""
+		});
+		if (util !== null) {
+			const instance = typeof util.get === "function" ? util.get() : util;
+			const copy = instance["copyFile"];
+			if (typeof copy === "function") await copy.call(instance, path, relPath);
+		}
+		return relPath;
+	}
+	/** 注册 onMsgInfoListUpdate 确认监听（返回 Promise，resolve 时发送成功）。 */
+	confirmSend(msgId, target) {
+		const channel = this.channel;
+		if (channel === null) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const off = channel.on("Msg/onMsgInfoListUpdate", (list) => {
+				const mine = list.find((m) => m.guildId === msgId);
+				if (mine === void 0) return;
+				if (mine.sendStatus === SEND_STATUS.SUCCESS || mine.sendStatus === SEND_STATUS.SUCCESS_NO_SEQ) {
+					off();
+					resolve();
+				} else if (mine.sendStatus === SEND_STATUS.FAILED) {
+					off();
+					reject(kernelError(`sendMsg 失败: sendStatus=${mine.sendStatus}`, "SEND_FAILED"));
+				}
+			});
+			setTimeout(() => {
+				off();
+				reject(kernelError(`sendMsg 等待确认超时（msgId=${msgId}, target=${JSON.stringify(target)}）`, "SEND_FAILED"));
+			}, SEND_CONFIRM_TIMEOUT_MS);
+		});
+	}
+	/** 撤回消息（群聊管理员 / 私聊 2 分钟内）。 */
+	async recallMessage(target, msgIds) {
+		if (msgIds.length === 0) throw kernelError("recallMessage 需要至少一个 msgId", "INVALID_PARAM");
+		unwrapResult("recallMsg", await this.service.recallMsg(target, msgIds));
+	}
+	/** 拉取历史消息（msgId 为空从最新拉；count 条，时间倒序）。 */
+	async fetchMessages(target, opts) {
+		const raw = await this.service.getMsgs(target, opts.msgId ?? "", opts.count, false);
+		unwrapResult("getMsgs", raw);
+		return raw.msgList ?? [];
+	}
+	/** 按 msgId 批量拉取消息（get_msg / 精华消息 / ptt 转文字共用）。 */
+	async fetchMsgsByMsgId(target, ids) {
+		if (ids.length === 0) return [];
+		const raw = await this.service.getMsgsByMsgId(target, ids);
+		unwrapResult("getMsgsByMsgId", raw);
+		return raw.msgList ?? [];
+	}
+	/** 消息表情表态（set_msg_emoji_like；like=true 点赞，false 取消）。 */
+	async setMsgEmojiLike(target, opts) {
+		unwrapResult("setMsgEmojiLikes", await this.service.setMsgEmojiLikes(target, opts.msgSeq, opts.emojiId, opts.emojiType, opts.like));
+	}
+	/**
+	* 语音转文字（fetch_ptt_text）。
+	* 流程：按 msgId 拉消息 → 找 PTT 元素 → translatePtt2Text（异步转写）
+	* → 再拉一次消息读 pttElement.text。
+	*/
+	async fetchPttText(msgId, target) {
+		const ptt = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
+		if (ptt === null) throw kernelError("消息中不包含语音", "NOT_FOUND");
+		unwrapResult("translatePtt2Text", await this.service.translatePtt2Text(msgId, target, ptt));
+		const text = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement?.text;
+		if (text === void 0 || text === "") throw kernelError("获取语音转文字结果失败", "UNKNOWN");
+		return text;
+	}
+	/** 标记会话已读。 */
+	async markRead(target) {
+		unwrapResult("setMsgRead", await this.service.setMsgRead(target));
+	}
+	/** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
+	async setInputStatus(target, eventType) {
+		await this.service.sendShowInputStatusReq(target.chatType, eventType, target.peerUid);
+	}
+	/**
+	* 发送合并转发（send_group/private_forward_msg）。
+	* buildMultiForwardMsg 组装 MULTI_FORWARD 元素 → 直接作 sendMsg 元素发送。
+	*/
+	async sendForwardMessage(target, sourcePeer, srcMsgIds) {
+		if (srcMsgIds.length === 0) throw kernelError("sendForwardMessage 需要至少一条源消息", "INVALID_PARAM");
+		const built = await this.service.buildMultiForwardMsg({
+			srcMsgIds,
+			srcContact: sourcePeer
+		});
+		unwrapResult("buildMultiForwardMsg", built);
+		const elements = built.rspInfo?.elements;
+		if (elements === void 0 || elements.length === 0) throw kernelError("合并转发组装失败：无元素", "UNKNOWN");
+		const msgId = this.service.generateMsgUniqueId(target.chatType, String(Date.now()));
+		unwrapResult("sendMsg", await this.service.sendMsg(msgId, target, elements, /* @__PURE__ */ new Map()));
+		return { msgId };
+	}
+	/** 获取合并转发内容（get_forward_msg；resId 取自 multiForwardMsgElement）。 */
+	async fetchForwardMessage(peer, msgId) {
+		const forward = findForwardElement(await this.fetchMsgsByMsgId(peer, [msgId]));
+		if (forward === null || forward.resId === "") throw kernelError("消息不包含合并转发内容", "NOT_FOUND");
+		const raw = await this.service.getMultiMsg(peer, msgId, forward.resId);
+		unwrapResult("getMultiMsg", raw);
+		return raw.msgList ?? [];
+	}
+	/** 单条转发（forward_group/friend_single_msg；srcMsgIds 源、dstPeer 目标）。 */
+	async forwardSingleMessage(sourcePeer, srcMsgIds, dstPeer) {
+		if (srcMsgIds.length === 0) throw kernelError("forwardSingleMessage 需要至少一条源消息", "INVALID_PARAM");
+		unwrapResult("forwardMsg", await this.service.forwardMsg(srcMsgIds, sourcePeer, [dstPeer], void 0));
+	}
+	/** 设置在线状态（set_online_status；customStatus 为自定义状态）。 */
+	async setOnlineStatus(opts) {
+		unwrapResult("setStatus", await this.service.setStatus(opts));
+	}
+};
+/** 在消息列表中找含 pttElement 的元素（找不到返回 null）。 */
+function findPttElement(msgs) {
+	const [first] = msgs;
+	if (first === void 0) return null;
+	return first.elements.find((el) => el.pttElement !== void 0) ?? null;
+}
+/** 在消息列表中找含 multiForwardMsgElement 的元素（找不到返回 null）。 */
+function findForwardElement(msgs) {
+	const [first] = msgs;
+	if (first === void 0) return null;
+	return first.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement ?? null;
+}
+//#endregion
+//#region src/apis/stranger-info.ts
+/** 宽松取值：undefined 时给默认值（null 也归默认）。 */
+function orDefault(value, fallback) {
+	return value ?? fallback;
+}
+/** 合并两份详情：优先 info（uid 完整详情），字段缺失回退 byUin（uin 初查详情）。 */
+function mergeDetail(info, byUin) {
+	const infoSimple = info.detail?.simpleInfo;
+	const byUinSimple = byUin.detail?.simpleInfo;
+	return {
+		coreInfo: pickField(infoSimple, byUinSimple, (s) => s?.coreInfo),
+		baseInfo: pickField(infoSimple, byUinSimple, (s) => s?.baseInfo),
+		vasInfo: pickField(infoSimple, byUinSimple, (s) => s?.vasInfo),
+		commonExt: pickField(info.detail, byUin.detail, (d) => d?.commonExt),
+		status: pickField(infoSimple, byUinSimple, (s) => s?.status?.status)
+	};
+}
+/** 字段级回退：primary 的字段取不到回退 fallback 的同名字段（宽松取值）。 */
+function pickField(primary, fallback, get) {
+	const fromPrimary = primary !== void 0 ? get(primary) : void 0;
+	if (fromPrimary !== void 0) return fromPrimary;
+	return fallback !== void 0 ? get(fallback) : void 0;
+}
+/** 扁平化两份详情 → StrangerInfo（宽松取值，字段缺失给默认）。 */
+function flattenStrangerInfo(uin, uid, byUin, info) {
+	const d = mergeDetail(info, byUin);
+	return {
+		user_id: Number(uin),
+		uid,
+		nickname: orDefault(d.coreInfo?.nick, ""),
+		age: orDefault(d.baseInfo?.age, 0),
+		qid: orDefault(d.baseInfo?.qid, ""),
+		qq_level: orDefault(d.commonExt?.qqLevel, 0),
+		sex: mapSex(d.baseInfo?.sex),
+		long_nick: orDefault(d.baseInfo?.longNick, ""),
+		reg_time: orDefault(d.commonExt?.regTime, 0),
+		is_vip: orDefault(d.vasInfo?.svipFlag, false),
+		is_years_vip: orDefault(d.vasInfo?.yearVipFlag, false),
+		vip_level: orDefault(d.vasInfo?.vipLevel, 0),
+		remark: orDefault(d.coreInfo?.remark, ""),
+		status: orDefault(d.status, 0),
+		login_days: 0
+	};
+}
+/** 性别数值 → OB11 字符串（1=男 2=女 其余 unknown）。 */
+function mapSex(raw) {
+	if (raw === 1) return "male";
+	if (raw === 2) return "female";
+	return "unknown";
+}
+//#endregion
+//#region src/apis/profile.ts
+/**
+* ProfileApi：资料语义化 API（ADR-009 统一错误语义，P2-14/P2-15）
+*
+* - setLongNick：set_self_longnick
+* - setNickName：set_qq_profile
+* - setHeader：set_qq_avatar
+* - getStrangerInfo：get_stranger_info（uin → uid → 详情扁平化）
+*/
+/** 资料 API：从 session 拿 profile service，包装成语义化方法。 */
+var ProfileApi = class {
+	service;
+	constructor(session) {
+		const service = session.getProfileService();
+		if (service === null || service === void 0) throw kernelError("getProfileService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 设置个性签名（set_self_longnick）。 */
+	async setLongNick(longNick) {
+		checkLooseResult("setLongNick", await this.service.setLongNick(longNick));
+	}
+	/** 设置昵称（set_qq_profile）。 */
+	async setNickName(nickName) {
+		checkLooseResult("setNickName", await this.service.setNickName(nickName));
+	}
+	/** 设置头像（set_qq_avatar；filePath 为本地路径）。 */
+	async setHeader(filePath) {
+		const raw = await this.service.setHeader(filePath);
+		if (raw.result !== 0) throw kernelError(`setHeader 失败: ${raw.errMsg}`, "UNKNOWN");
+	}
+	/** 获取陌生人信息（get_stranger_info；uin 为用户 QQ 号）。 */
+	async getStrangerInfo(uin) {
+		const byUin = await this.service.getUserDetailInfoByUin(uin);
+		const detailUid = byUin.detail?.uid;
+		let uid = uin;
+		if (detailUid !== void 0 && detailUid !== "") uid = detailUid;
+		const info = await this.service.getUserDetailInfo(uid);
+		return flattenStrangerInfo(uin, uid, byUin, info);
+	}
+};
+//#endregion
+//#region src/apis/profile-like.ts
+/**
+* ProfileLikeApi：资料点赞语义化 API（ADR-009 统一错误语义，P2-14）
+*
+* sendLike：send_like（sourceId=71 赞来源，doLikeCount 次数）。
+*/
+/** 点赞 API：从 session 拿 profile like service，包装成语义化方法。 */
+var ProfileLikeApi = class {
+	service;
+	constructor(session) {
+		const service = session.getProfileLikeService();
+		if (service === null || service === void 0) throw kernelError("getProfileLikeService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 点赞（send_like；uid 为目标 uid，count 次数）。 */
+	async sendLike(uid, count = 1) {
+		const raw = await this.service.setBuddyProfileLike({
+			friendUid: uid,
+			sourceId: 71,
+			doLikeCount: count,
+			doLikeTollCount: 0
+		});
+		if (raw.result !== 0) throw kernelError(`点赞失败: ${raw.errMsg}`, "UNKNOWN");
+	}
+};
+//#endregion
+//#region src/apis/richmedia.ts
+/**
+* RichMediaApi：富媒体语义化 API（ADR-009 统一错误语义，P2-14）
+*
+* - translateWords：translate_en2zh
+* - 群文件：列表 / 空间 / 建夹 / 删除文件 / 删除夹 / 重命名 / 移动 / 转存
+*/
+/** 群文件业务类型（deleteGroupFile/moveGroupFile/renameGroupFile 用，说明书参考）。 */
+const GROUP_FILE_BIZ_TYPE = 102;
+/** 排序方式（按时间）。 */
+const SORT_TYPE_TIME = 1;
+/** 排序方向（倒序）。 */
+const SORT_ORDER_DESC = 2;
+/** 起始下标（根目录）。 */
+const START_INDEX_ROOT = 0;
+/** 不显示在线文档文件夹。 */
+const HIDE_ONLINEDOC_FOLDER = 0;
+/** 默认文件数量。 */
+const DEFAULT_FILE_COUNT = 50;
+/** 空间查询文件数量（单条即可）。 */
+const SPACE_QUERY_FILE_COUNT = 1;
+/** 富媒体 API：从 session 拿 rich media service，包装成语义化方法。 */
+var RichMediaApi = class {
+	service;
+	constructor(session) {
+		const service = session.getRichMediaService();
+		if (service === null || service === void 0) throw kernelError("getRichMediaService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 英文单词翻译（translate_en2zh）。 */
+	async translateWords(words) {
+		const raw = await this.service.translateEnWordToZn(words);
+		unwrap("translateEnWordToZn", raw.result, raw.errMsg);
+		return raw.words ?? [];
+	}
+	/** 群文件列表（get_group_root_files；parent 缺省根目录）。 */
+	async getGroupFileList(groupCode, parentFolderId = "", fileCount = DEFAULT_FILE_COUNT) {
+		const params = {
+			sortType: SORT_TYPE_TIME,
+			fileCount,
+			startIndex: START_INDEX_ROOT,
+			sortOrder: SORT_ORDER_DESC,
+			showOnlinedocFolder: HIDE_ONLINEDOC_FOLDER
+		};
+		const raw = await this.service.getGroupFileList(groupCode, params);
+		if (raw.result !== 0) unwrap("getGroupFileList", raw.result, raw.errMsg);
+		const list = extractFileList(raw.result);
+		if (parentFolderId === "") return list;
+		return list.filter((item) => item.fileInfo !== void 0 && item.fileInfo.parent === parentFolderId || item.folderInfo !== void 0 && item.folderInfo.folderUid === parentFolderId);
+	}
+	/** 群文件系统信息（get_group_file_system_info；getGroupFileList 的 groupSpaceResult）。 */
+	async getGroupFileSystemInfo(groupCode) {
+		const params = {
+			sortType: SORT_TYPE_TIME,
+			fileCount: SPACE_QUERY_FILE_COUNT,
+			startIndex: START_INDEX_ROOT,
+			sortOrder: SORT_ORDER_DESC,
+			showOnlinedocFolder: HIDE_ONLINEDOC_FOLDER
+		};
+		const raw = await this.service.getGroupFileList(groupCode, params);
+		if (raw.result !== 0) unwrap("getGroupFileList", raw.result, raw.errMsg);
+		const space = raw.groupSpaceResult;
+		if (space === void 0) throw kernelError("getGroupFileList 无 groupSpaceResult", "UNKNOWN");
+		return {
+			fileCount: countGroupFiles(raw.result),
+			limitCount: 0,
+			usedSpace: space.usedSpace,
+			totalSpace: space.totalSpace
+		};
+	}
+	/** 创建群文件夹（create_group_file_folder）。 */
+	async createGroupFolder(groupCode, folderName) {
+		const raw = await this.service.createGroupFolder(groupCode, folderName);
+		if (raw.result !== 0) unwrap("createGroupFolder", raw.result, raw.errMsg);
+		const { result } = raw;
+		if (typeof result === "string") return result;
+		return "";
+	}
+	/** 删除群文件（delete_group_file）。 */
+	async deleteGroupFile(groupCode, fileIds) {
+		const raw = await this.service.deleteGroupFile(groupCode, [GROUP_FILE_BIZ_TYPE], fileIds);
+		if (raw.result !== 0) unwrap("deleteGroupFile", raw.result, raw.errMsg);
+	}
+	/** 删除群文件夹（delete_group_folder）。 */
+	async deleteGroupFolder(groupCode, folderId) {
+		const raw = await this.service.deleteGroupFolder(groupCode, folderId);
+		if (raw.result !== 0) unwrap("deleteGroupFolder", raw.result, raw.errMsg);
+	}
+	/** 重命名群文件（rename_group_file；参数语义待探测校准）。 */
+	async renameGroupFile(groupCode, fileId, newName) {
+		await this.service.renameGroupFile(groupCode, GROUP_FILE_BIZ_TYPE, fileId, newName, "");
+	}
+	/** 移动群文件（move_group_file；targetFolder 空为根目录）。 */
+	async moveGroupFile(groupCode, fileIds, targetFolderId) {
+		const raw = await this.service.moveGroupFile(groupCode, [GROUP_FILE_BIZ_TYPE], fileIds, "", targetFolderId);
+		if (raw.result !== 0) unwrap("moveGroupFile", raw.result, raw.errMsg);
+	}
+	/** 转存群文件（trans_group_file）。 */
+	async transGroupFile(groupCode, fileId) {
+		const raw = await this.service.transGroupFile(groupCode, fileId);
+		if (raw.result !== 0) unwrap("transGroupFile", raw.result, raw.errMsg);
+	}
+};
+/** 从 getGroupFileList 返回提取文件列表（兼容数组 / { items } / { fileList }）。导出供单测。 */
+function extractFileList(result) {
+	if (Array.isArray(result)) return result;
+	if (result === null || typeof result !== "object") return [];
+	const obj = result;
+	for (const key of [
+		"items",
+		"fileList",
+		"list"
+	]) {
+		const value = obj[key];
+		if (Array.isArray(value)) return value;
+	}
+	return [];
+}
+/** 统计文件数量（兼容数组 / { items }）。 */
+function countGroupFiles(result) {
+	if (Array.isArray(result)) return result.filter((item) => item.fileInfo !== void 0).length;
+	return 0;
+}
+//#endregion
+//#region src/apis/ticket.ts
+/**
+* TicketApi：票据语义化 API（ADR-009 统一错误语义，P2-13）
+*
+* - getClientKey：TicketService.forceFetchClientKey 解包（get_clientkey）
+* - getCookies：clientKey → ssl.ptlogin2.qq.com/jump 跳转 → 解析 set-cookie 头
+*   （fetch 会吞掉 Set-Cookie 头，故用 node:https 手动请求）
+*/
+/** 跳转请求超时（毫秒）。 */
+const JUMP_TIMEOUT_MS = 1e4;
+/** 票据 API：从 session 拿 ticket service，包装成语义化方法。 */
+var TicketApi = class {
+	service;
+	constructor(session) {
+		const service = session.getTicketService();
+		if (service === null || service === void 0) throw kernelError("getTicketService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 获取 clientKey（get_clientkey）。 */
+	async getClientKey() {
+		const raw = await this.service.forceFetchClientKey("");
+		if (raw.result !== 0 || raw.clientKey === "") throw kernelError(`forceFetchClientKey 失败: ${raw.errMsg}`, "UNKNOWN");
+		return raw;
+	}
+	/** 获取指定域名的 cookies（get_cookies；uin 为机器人 QQ 号）。 */
+	async getCookies(domain, uin) {
+		const { clientKey } = await this.getClientKey();
+		const u1 = `https://${domain}/${uin}/infocenter`;
+		return fetchJumpCookies(`https://ssl.ptlogin2.qq.com/jump?ptlang=1033&clientuin=${encodeURIComponent(uin)}&clientkey=${encodeURIComponent(clientKey)}&u1=${encodeURIComponent(u1)}&keyindex=19`);
+	}
+	/** 计算 bkn（get_csrf_token 与 web 接口共用；skey → bkn 哈希）。 */
+	static getBkn(skey) {
+		let hash = 5381;
+		for (let i = 0; i < skey.length; i += 1) {
+			const code = skey.charCodeAt(i);
+			hash = hash + (hash << 5) + code;
+		}
+		return (hash & 2147483647).toString();
+	}
+};
+/** 请求 jump 地址并解析 set-cookie → dict（fetch 吞 Set-Cookie，故用 node:https）。 */
+function fetchJumpCookies(url) {
+	return new Promise((resolve, reject) => {
+		const req = (0, node_https.get)(url, { headers: { "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" } }, (res) => {
+			const cookies = parseSetCookieHeaders(res.headers["set-cookie"]);
+			res.resume();
+			res.on("end", () => resolve(cookies));
+		});
+		req.setTimeout(JUMP_TIMEOUT_MS, () => {
+			req.destroy();
+			reject(/* @__PURE__ */ new Error("获取 cookies 超时"));
+		});
+		req.on("error", (err) => reject(err));
+	});
+}
+/** 解析 set-cookie 头数组 → { name: value } dict。 */
+function parseSetCookieHeaders(raw) {
+	const cookies = {};
+	if (raw === void 0) return cookies;
+	for (const line of raw) {
+		const [pair] = line.split(";");
+		if (pair !== void 0) {
+			const eq = pair.indexOf("=");
+			if (eq > 0) {
+				const name = pair.slice(0, eq).trim();
+				const value = pair.slice(eq + 1);
+				if (name !== "") cookies[name] = value;
+			}
+		}
+	}
+	return cookies;
+}
+//#endregion
+//#region src/apis/webapi.ts
+/**
+* WebApi：群空间 web 接口（P2-15）
+*
+* qun.qq.com 群空间接口需 Cookie（p_skey/skey）+ bkn（skey 哈希）。
+* 复用 TicketApi.getCookies('qun.qq.com') 取 Cookie，TicketApi.getBkn 算 bkn。
+* 零 NapCat 代码：接口契约（URL/参数/返回形状）是 qun.qq.com 外部系统的事实，
+* 自研描述。
+*/
+/** 群空间域名（Cookie 归属）。 */
+const QUN_DOMAIN = "qun.qq.com";
+/** 精华消息页大小（分页拉取）。 */
+const ESSENCE_PAGE_LIMIT = 50;
+/** 精华消息最大分页数。 */
+const ESSENCE_MAX_PAGES = 20;
+/** 群荣誉类型（1=龙王 2=群聊之火 3=群聊炽热 6=快乐源泉）。 */
+const WebHonorType = {
+	ALL: 0,
+	TALKATIVE: 1,
+	PERFORMER: 2,
+	LEGEND: 3,
+	EMOTION: 6
+};
+/** 群空间 web API（Cookie 经 TicketApi 注入）。 */
+var WebApi = class {
+	getCookies;
+	constructor(opts) {
+		this.getCookies = opts.getCookies;
+	}
+	/** 拉取单页精华消息（失败/retcode 非 0 返回 null）。 */
+	async fetchEssencePage(groupCode, cookie, bkn, page) {
+		const ret = await fetchQunJson("https://qun.qq.com/cgi-bin/group_digest/digest_list?" + new URLSearchParams({
+			bkn,
+			page_start: String(page * ESSENCE_PAGE_LIMIT),
+			page_limit: String(ESSENCE_PAGE_LIMIT),
+			group_code: groupCode
+		}).toString(), cookie);
+		if (ret === null || ret.retcode !== 0) return null;
+		const list = ret.data?.msg_list;
+		return {
+			items: Array.isArray(list) ? list.filter((item) => item !== null) : [],
+			isEnd: ret.data?.is_end === true
+		};
+	}
+	/** 获取群精华消息列表（get_essence_msg_list；分页拉取至 is_end）。 */
+	async getEssenceMsgList(groupCode) {
+		const cookie = await this.getCookies(QUN_DOMAIN);
+		const bkn = TicketApi.getBkn(cookie["skey"] ?? "");
+		const out = [];
+		for (let page = 0; page < ESSENCE_MAX_PAGES; page += 1) {
+			const result = await this.fetchEssencePage(groupCode, cookie, bkn, page);
+			if (result === null) break;
+			out.push(...result.items);
+			if (result.isEnd) break;
+		}
+		return out;
+	}
+	/** 获取群荣誉信息（get_group_honor_info；type 0=全部）。 */
+	async getGroupHonorInfo(groupCode, type) {
+		const cookie = await this.getCookies(QUN_DOMAIN);
+		const result = {
+			group_id: Number(groupCode),
+			current_talkative: null,
+			talkative_list: [],
+			performer_list: [],
+			legend_list: [],
+			emotion_list: [],
+			strong_newbie_list: []
+		};
+		await this.fillHonorLists(result, groupCode, cookie, type);
+		return result;
+	}
+	/** 按 type 填充荣誉列表（ALL 拉全部，单类型只拉对应类）。 */
+	async fillHonorLists(result, groupCode, cookie, type) {
+		for (const target of honorTargets(type)) {
+			const list = await this.fetchHonorList(groupCode, cookie, target.kind);
+			result[target.listKey] = list;
+			if (target.kind === WebHonorType.TALKATIVE) {
+				const [first] = list;
+				if (first !== void 0) result.current_talkative = first;
+			}
+		}
+	}
+	/** 拉取单类荣誉列表（honorlist 接口，正则提取 __INITIAL_STATE__）。 */
+	async fetchHonorList(groupCode, cookie, type) {
+		const text = await fetchQunText("https://qun.qq.com/interactive/honorlist?" + new URLSearchParams({
+			gc: groupCode,
+			type: String(type)
+		}).toString(), cookie);
+		if (text === null) return [];
+		return parseHonorList(text, type);
+	}
+};
+/** honorlist 页面 __INITIAL_STATE__ 提取。 */
+const INITIAL_STATE_RE = /window\.__INITIAL_STATE__=(.*?);/;
+/** 从 honorlist 页面提取 __INITIAL_STATE__ → 荣誉列表（解析失败返回空）。 */
+function parseHonorList(text, type) {
+	const match = INITIAL_STATE_RE.exec(text);
+	if (match === null || match[1] === void 0) return [];
+	let state;
+	try {
+		state = JSON.parse(match[1]);
+	} catch {
+		return [];
+	}
+	const raw = type === WebHonorType.TALKATIVE ? state.talkativeList : state.actorList;
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) if (item !== null && typeof item === "object") {
+		const obj = item;
+		out.push({
+			uin: String(obj.uin ?? ""),
+			name: String(obj.name ?? ""),
+			avatar: String(obj.avatar ?? ""),
+			desc: String(obj.desc ?? "")
+		});
+	}
+	return out;
+}
+/** 请求 qun.qq.com JSON 接口（带 Cookie；失败返回 null）。 */
+async function fetchQunJson(url, cookie) {
+	try {
+		const res = await fetch(url, { headers: { Cookie: cookieToString(cookie) } });
+		if (!res.ok) return null;
+		const json = await res.json();
+		return {
+			retcode: json.retcode ?? -1,
+			data: json.data
+		};
+	} catch (err) {
+		throw kernelError(`qun.qq.com 请求失败: ${String(err)}`, "UNKNOWN");
+	}
+}
+/** 请求 qun.qq.com 文本接口（带 Cookie；失败返回 null）。 */
+async function fetchQunText(url, cookie) {
+	try {
+		const res = await fetch(url, { headers: { Cookie: cookieToString(cookie) } });
+		if (!res.ok) return null;
+		return await res.text();
+	} catch (err) {
+		throw kernelError(`qun.qq.com 请求失败: ${String(err)}`, "UNKNOWN");
+	}
+}
+/** Cookie dict → 头字符串。 */
+function cookieToString(cookie) {
+	const parts = [];
+	for (const [key, value] of Object.entries(cookie)) parts.push(`${key}=${value}`);
+	return parts.join("; ");
+}
+/** 荣誉类型 → 目标列表（ALL 拉全部，单类型只拉对应类）。 */
+function honorTargets(type) {
+	const all = [
+		{
+			kind: WebHonorType.TALKATIVE,
+			listKey: "talkative_list"
+		},
+		{
+			kind: WebHonorType.PERFORMER,
+			listKey: "performer_list"
+		},
+		{
+			kind: WebHonorType.LEGEND,
+			listKey: "legend_list"
+		},
+		{
+			kind: WebHonorType.EMOTION,
+			listKey: "emotion_list"
+		}
+	];
+	if (type === WebHonorType.ALL) return [...all];
+	return all.filter((target) => target.kind === type);
+}
+//#endregion
+//#region src/bridge/group-bridge.ts
+/**
+* 群事件桥：注册原生监听 → 回调 emit 到 channel。
+* 无全局单例（ADR-015 推论）——每进程每 session 实例化一份。
+*/
+var GroupBridge = class {
+	service;
+	channel;
+	listenerId = null;
+	constructor(session, channel) {
+		const service = session.getGroupService();
+		if (service === null || service === void 0) throw kernelError("getGroupService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+		this.channel = channel;
+	}
+	/** 注册原生监听（幂等）。 */
+	register() {
+		if (this.listenerId !== null) return;
+		const listener = {
+			onGroupListInited: (listEmpty) => this.channel.emit("Group/onGroupListInited", listEmpty),
+			onGroupListUpdate: (updateType, groupList) => this.channel.emit("Group/onGroupListUpdate", updateType, groupList),
+			onGroupDetailInfoChange: (detailInfo) => this.channel.emit("Group/onGroupDetailInfoChange", detailInfo),
+			onMemberListChange: (arg) => this.channel.emit("Group/onMemberListChange", arg),
+			onMemberInfoChange: (groupCode, dataSource, members) => this.channel.emit("Group/onMemberInfoChange", groupCode, dataSource, members),
+			onGroupNotifiesUpdated: (doubt, notifies) => this.channel.emit("Group/onGroupNotifiesUpdated", doubt, notifies),
+			onGroupSingleScreenNotifies: (doubt, seq, notifies) => this.channel.emit("Group/onGroupSingleScreenNotifies", doubt, seq, notifies),
+			onShutUpMemberListChanged: (groupCode, members) => this.channel.emit("Group/onShutUpMemberListChanged", groupCode, members)
+		};
+		this.listenerId = this.service.addKernelGroupListener(listener);
+	}
+	/** 注销原生监听（幂等）。 */
+	unregister() {
+		if (this.listenerId === null) return;
+		this.service.removeKernelGroupListener(this.listenerId);
+		this.listenerId = null;
+	}
+};
+//#endregion
+//#region src/bridge/msg-bridge.ts
+/**
+* 消息事件桥：注册原生监听 → 回调 emit 到 channel。
+* 无全局单例（ADR-015 推论）——每进程每 session 实例化一份。
+*/
+var MsgBridge = class {
+	service;
+	channel;
+	listenerId = null;
+	constructor(session, channel) {
+		const service = session.getMsgService();
+		if (service === null || service === void 0) throw kernelError("getMsgService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+		this.channel = channel;
+	}
+	/** 注册原生监听（幂等）。 */
+	register() {
+		if (this.listenerId !== null) return;
+		const listener = {
+			onRecvMsg: (msgs) => this.channel.emit("Msg/onRecvMsg", msgs),
+			onRecvMsgReadReport: (reports) => this.channel.emit("Msg/onRecvMsgReadReport", reports),
+			onRecvMsgReceipt: (receipts) => this.channel.emit("Msg/onRecvMsgReceipt", receipts),
+			onMsgInfoListUpdate: (msgs) => this.channel.emit("Msg/onMsgInfoListUpdate", msgs)
+		};
+		this.listenerId = this.service.addKernelMsgListener(listener);
+	}
+	/** 注销原生监听（幂等）。 */
+	unregister() {
+		if (this.listenerId === null) return;
+		this.service.removeKernelMsgListener(this.listenerId);
+		this.listenerId = null;
+	}
+};
+//#endregion
+//#region src/login/wait.ts
+/**
+* 等待/延迟工具（login 模块共享，2026-08-08 克隆合并）
+*/
+/** 等待条件满足（轮询，带超时）。 */
+function waitFor(predicate, timeoutMs, intervalMs = 500) {
+	return new Promise((resolve) => {
+		const started = Date.now();
+		const tick = () => {
+			if (predicate()) {
+				resolve(true);
+				return;
+			}
+			if (Date.now() - started > timeoutMs) {
+				resolve(false);
+				return;
+			}
+			setTimeout(tick, intervalMs);
+		};
+		tick();
+	});
+}
+/** 短延迟。 */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#region src/cache/group-cache.ts
+/**
+* 群/成员缓存：事件主动维护 + 查询惰性回填。
+* 只读接口 getGroupDetail / getMembers / getMember / getGroup（列表项）。
+*/
+var GroupCache = class {
+	channel;
+	groupApi;
+	/** 群列表项（onGroupListUpdate / getGroupList 回填）。 */
+	groupList = /* @__PURE__ */ new Map();
+	/** 群详情（onGroupDetailInfoChange / getGroupInfo 回填）。 */
+	groupDetails = /* @__PURE__ */ new Map();
+	/** 群成员：groupCode → (uid → GroupMember)。 */
+	members = /* @__PURE__ */ new Map();
+	/** 惰性回填 in-flight 去重。 */
+	inFlight = /* @__PURE__ */ new Map();
+	unsubscribes = null;
+	constructor(opts) {
+		this.channel = opts.channel;
+		this.groupApi = opts.groupApi;
+	}
+	/** 订阅群事件通道（幂等）。 */
+	register() {
+		if (this.unsubscribes !== null) return;
+		const unsubs = [];
+		unsubs.push(this.channel.on("Group/onGroupListInited", (listEmpty) => {
+			if (listEmpty) this.groupList.clear();
+		}));
+		unsubs.push(this.channel.on("Group/onGroupListUpdate", (updateType, groupList) => {
+			if (updateType === GroupListUpdateType.ALL) this.groupList.clear();
+			for (const group of groupList) this.groupList.set(group.groupCode, group);
+		}));
+		unsubs.push(this.channel.on("Group/onGroupDetailInfoChange", (detailInfo) => {
+			this.groupDetails.set(detailInfo.groupCode, detailInfo);
+		}));
+		unsubs.push(this.channel.on("Group/onMemberListChange", (arg) => {
+			this.upsertMembers(arg.sceneId, arg.infos);
+		}));
+		unsubs.push(this.channel.on("Group/onMemberInfoChange", (_groupCode, _dataSource, members) => {
+			this.upsertMembers(_groupCode, members);
+		}));
+		this.unsubscribes = () => {
+			for (const unsub of unsubs) unsub();
+		};
+	}
+	/** 退订事件通道（幂等）。 */
+	unregister() {
+		this.unsubscribes?.();
+		this.unsubscribes = null;
+		this.groupList.clear();
+		this.groupDetails.clear();
+		this.members.clear();
+		this.inFlight.clear();
+	}
+	/** 合并成员到该群缓存（uid → GroupMember）。 */
+	upsertMembers(groupCode, infos) {
+		let map = this.members.get(groupCode);
+		if (map === void 0) {
+			map = /* @__PURE__ */ new Map();
+			this.members.set(groupCode, map);
+		}
+		for (const [uid, member] of infos) map.set(uid, member);
+	}
+	/** 群列表是否已有缓存（同步判断）。 */
+	hasGroup(groupCode) {
+		return this.groupList.has(groupCode) || this.groupDetails.has(groupCode);
+	}
+	/**
+	* 群列表快照（只读，缓存由 onGroupListUpdate 事件主动维护）。
+	* 群列表数据不走原生 getGroupList 返回值（实测仅 { result, errMsg }，
+	* 列表经事件推送）——协议/IPC 层消费列表一律经此方法。
+	*/
+	listGroups() {
+		return [...this.groupList.values()];
+	}
+	/**
+	* 群列表快照（缓存为空时主动触发原生刷新，等待事件回填后返回）。
+	*
+	* 实测（2026-08-08 端到端联调）：onGroupListUpdate 仅在登录后首轮同步
+	* 推送（MMKV 已有缓存后不再重复推送）——进程内缓存为空时列表读不到。
+	* 触发 getGroupList(true) 会重新拉取并推送事件回填缓存。
+	* 返回空数组 = 刷新后仍无数据（超时 5s）。
+	*/
+	async listGroupsRefreshed() {
+		if (this.groupList.size > 0) return [...this.groupList.values()];
+		await this.groupApi.getGroupList(true);
+		await waitFor(() => this.groupList.size > 0, 5e3, 200);
+		return [...this.groupList.values()];
+	}
+	/**
+	* 群列表项（只读；缺失惰性回填 getGroupList）。
+	* 返回 undefined 表示群不存在。
+	*/
+	async getGroup(groupCode) {
+		const cached = this.groupList.get(groupCode);
+		if (cached !== void 0) return cached;
+		await this.loadGroupList();
+		return this.groupList.get(groupCode);
+	}
+	/**
+	* 群详情（只读；缺失惰性回填 getGroupInfo）。
+	* getGroupInfo 恒返回对象（失败抛 KernelError），直接缓存。
+	*/
+	async getGroupDetail(groupCode) {
+		const cached = this.groupDetails.get(groupCode);
+		if (cached !== void 0) return cached;
+		const detail = await this.dedupe(`detail:${groupCode}`, () => this.groupApi.getGroupInfo(groupCode));
+		this.groupDetails.set(groupCode, detail);
+		return detail;
+	}
+	/**
+	* 群成员列表（只读；缺失惰性回填 getAllMemberList(forceFetch=true)）。
+	* 返回空数组表示该群无成员（或拉取失败已由 GroupApi 抛 KernelError）。
+	*/
+	async getMembers(groupCode) {
+		const map = this.members.get(groupCode);
+		if (map !== void 0 && map.size > 0) return [...map.values()];
+		const members = await this.dedupe(`members:${groupCode}`, () => this.groupApi.getGroupMemberList(groupCode, true));
+		const merged = /* @__PURE__ */ new Map();
+		for (const member of members) merged.set(member.uid, member);
+		this.members.set(groupCode, merged);
+		return members;
+	}
+	/**
+	* 群成员（只读；缺失回填：先整群拉取，再按 uid 取；仍无则 getMemberInfo 单查）。
+	* 返回 undefined 表示成员不在群。
+	*/
+	async getMember(groupCode, uid) {
+		const cached = await this.getCachedMember(groupCode, uid);
+		if (cached !== void 0) return cached;
+		const [member] = await this.dedupe(`member:${groupCode}:${uid}`, () => this.groupApi.getGroupMemberInfo(groupCode, [uid]));
+		if (member === void 0) return;
+		const target = this.members.get(groupCode);
+		if (target !== void 0) target.set(member.uid, member);
+		return member;
+	}
+	/** 读缓存成员（缺失先整群回填一次）。 */
+	async getCachedMember(groupCode, uid) {
+		let map = this.members.get(groupCode);
+		if (map === void 0 || map.size === 0) {
+			await this.getMembers(groupCode);
+			map = this.members.get(groupCode);
+		}
+		return map?.get(uid);
+	}
+	/** 惰性回填全量群列表（getGroup 缺失时）。 */
+	async loadGroupList() {
+		const list = await this.dedupe("group-list", () => this.groupApi.getGroupList(false));
+		for (const group of list) this.groupList.set(group.groupCode, group);
+	}
+	/** 惰性回填并发去重：同 key 并发只拉一次。 */
+	async dedupe(key, loader) {
+		const existing = this.inFlight.get(key);
+		if (existing !== void 0) return await existing;
+		const task = loader().catch((err) => {
+			throw err;
+		}).finally(() => {
+			this.inFlight.delete(key);
+		});
+		this.inFlight.set(key, task);
+		return await task;
+	}
+};
+//#endregion
+//#region src/context.ts
+/** 创建装配根（初始 wrapper/login 为 null）。 */
+function createCoreContext(opts) {
+	return {
+		logger: opts.logger,
+		paths: opts.paths,
+		wrapper: null,
+		login: null
+	};
+}
+//#endregion
+//#region src/wrapper/wrapper-adapters.ts
+/** NAPI 回调占位（方法存在即可被反射调用，无副作用）。 */
+const noop = () => void 0;
+/** NodeIGlobalAdapter 实现（engine.initWithDeskTopConfig 第二参）。 */
+var GlobalAdapter = class {
+	onLog = noop;
+	onGetSrvCalTime = noop;
+	onShowErrUITips = noop;
+	fixPicImgType = noop;
+	getAppSetting = noop;
+	onInstallFinished = noop;
+	onUpdateGeneralFlag = noop;
+	onGetOfflineMsg = noop;
+};
+/** NodeIDependsAdapter 实现（session.init 第二参）。 */
+var DependsAdapter = class {
+	onMSFStatusChange = noop;
+	onMSFSsoError = noop;
+	getGroupCode = noop;
+};
+/** NodeIDispatcherAdapter 实现（session.init 第三参）。 */
+var DispatcherAdapter = class {
+	dispatchRequest = noop;
+	dispatchCall = noop;
+	dispatchCallWithJson = noop;
+};
+/**
+* 创建会话监听器（默认静默，boot 阶段默认；login 模块接入后可覆盖）。
+* 回调方法必须存在（NAPI 按方法名反射），但输出与否由调用方决定——
+* onNTSessionCreate / onOpentelemetryInit 等对用户无信息量，默认不打 stdout。
+*/
+function createSessionListener(opts = {}) {
+	const { onEvent } = opts;
+	const emit = (name, ...args) => {
+		onEvent?.(name, ...args);
+	};
+	return {
+		onNTSessionCreate: (sessionId) => emit("onNTSessionCreate", sessionId),
+		onGProSessionCreate: (sessionId) => emit("onGProSessionCreate", sessionId),
+		onSessionInitComplete: (sessionId) => emit("onSessionInitComplete", sessionId),
+		onOpentelemetryInit: (info) => emit("onOpentelemetryInit", info),
+		onUserOnlineResult: (result) => emit("onUserOnlineResult", result),
+		onGetSelfTinyId: (result) => emit("onGetSelfTinyId", result)
+	};
+}
+/** 创建登录监听器（占位，登录器接入时填充）。 */
+function createLoginListener() {
+	return {};
+}
+//#endregion
+//#region src/login/login-connect.ts
+/**
+* 登录连接与快速登录（从 lifecycle.ts 拆分，2026-08-08 FTA 优化）
+*
+* - waitForNetworkConnection：等 MSF 网络连接就绪（getMsfStatus() === 3）
+* - ensureLoginConnected：connect() → 等 onLoginConnected（自建宿主必需）
+* - quickLogin：历史账号快速登录（网络异常 1006511 等就绪后重试）
+*/
+/**
+* 网络状态（MSF）常量。
+* 3 = 已连接（NapCat waitForNetworkConnection 语义，自研描述）。
+*/
+const MSF_STATUS_CONNECTED = 3;
+/** 快速登录网络异常错误码（1006511，P2-1 实测：登录前网络未就绪时报此错）。 */
+const NETWORK_ERROR_CODE = "1006511";
+/** 登录连接异常错误提示（自建宿主实测：connect 后未缓冲即 quickLogin 报此错）。 */
+const CONNECTION_ERROR_HINT = "登录系统连接异常";
+/** 网络重试最大次数（每次重试前等网络就绪）。 */
+const NETWORK_RETRY_MAX = 3;
+/** 网络就绪等待超时（毫秒）。 */
+const NETWORK_READY_TIMEOUT_MS = 15e3;
+/** 网络就绪轮询间隔（毫秒）。 */
+const NETWORK_READY_POLL_MS = 1e3;
+/** 连接稳定缓冲（毫秒，p0-kernel-flow 实证值）。 */
+const CONNECTION_SETTLE_MS = 3e3;
+/**
+* 等待网络连接就绪（loginService.getMsfStatus() === 3）。
+* 参考 NapCat waitForNetworkConnection 思路（自研实现）：快速登录在 QQ 刚拉起、
+* 网络栈未初始化时报 1006511 网络异常——等待 MSF 连接后再重试。
+* @returns 是否在超时前就绪。
+*/
+function waitForNetworkConnection(ctx, opts = {}) {
+	const raw = ctx.loginService;
+	if (raw === null || typeof raw.getMsfStatus !== "function") return Promise.resolve(false);
+	return waitFor(() => {
+		try {
+			return raw.getMsfStatus() === MSF_STATUS_CONNECTED;
+		} catch {
+			return false;
+		}
+	}, opts.timeoutMs ?? NETWORK_READY_TIMEOUT_MS, NETWORK_READY_POLL_MS);
+}
+/** 列出历史登录账号（boot.cjs 启动横幅用，「可用快速登录 of QQ」）。 */
+async function listLoginAccounts(ctx) {
+	const raw = ctx.loginService;
+	if (raw === null) throw kernelError("loginService 无效（缺 getLoginList）", "INVALID_STATE");
+	return (await raw.getLoginList()).LocalLoginInfoList;
+}
+/**
+* 登录服务连接（自建宿主必需，HANDOVER-V6/V10 p0-kernel-flow 实证顺序）：
+* connect() → 等 onLoginConnected。不 connect 则快速登录报「登录系统连接异常」。
+*
+* 对齐 p0-kernel-flow：initConfig → getLoginList → connect + onLoginConnected →
+* quickLoginWithUin。QQ 环境（worker/主进程）下可能已连接——connect 幂等，
+* 监听器超时兜底，不影响原流程。
+*/
+async function ensureLoginConnected(ctx, opts) {
+	const raw = ctx.loginService;
+	if (raw === null || typeof raw.connect !== "function") return;
+	await waitLoginConnected(raw, opts.timeoutMs);
+	await sleep(CONNECTION_SETTLE_MS);
+}
+/** 等 onLoginConnected（注册临时监听 + connect + 超时兜底）。 */
+function waitLoginConnected(raw, timeoutMs) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = () => {
+			if (!settled) {
+				settled = true;
+				resolve();
+			}
+		};
+		tryRegisterConnectListener(raw, finish);
+		setTimeout(finish, timeoutMs ?? NETWORK_READY_TIMEOUT_MS);
+		try {
+			raw.connect?.();
+		} catch {
+			finish();
+		}
+	});
+}
+/** 注册临时登录连接监听（失败不阻塞连接）。 */
+function tryRegisterConnectListener(raw, finish) {
+	try {
+		const listener = createLoginListener();
+		listener.onLoginConnected = () => {
+			finish();
+		};
+		if (typeof raw.addKernelLoginListener === "function") raw.addKernelLoginListener(listener);
+	} catch {}
+}
+/**
+* 目标账号选择（2026-08-07 修复：显式 uin 不在列表时**报错**而非静默 fallback——
+* 之前会退到第一个可快速登录账号，导致 `-q <uin>` 实际登成别的号）。
+* 导出供单测（login-connect.test.ts）。
+*/
+function pickLoginTarget(items, uin) {
+	if (uin !== void 0) {
+		const target = items.find((i) => i.uin === uin);
+		if (target === void 0) throw kernelError(`账号 ${uin} 不在登录列表（可用：${items.map((i) => i.uin).join("、")}）`, "NOT_FOUND");
+		return target;
+	}
+	const quick = items.find((i) => i.isQuickLogin);
+	if (quick !== void 0) return quick;
+	const [first] = items;
+	if (first === void 0) throw kernelError("无可用登录账号", "NOT_LOGIN");
+	return first;
+}
+/**
+* 带网络重试的快速登录（P2-1）。
+* 重试语义：仅当失败为网络异常（1006511）且未达上限时，等网络就绪后重试。
+*/
+async function loginWithNetworkRetry(ctx, loginService, target, opts) {
+	let lastErrMsg = "";
+	for (let attempt = 1; attempt <= NETWORK_RETRY_MAX; attempt += 1) {
+		const attemptResult = await attemptQuickLogin(loginService, target);
+		if (attemptResult.ok) return attemptResult.result;
+		lastErrMsg = attemptResult.errMsg;
+		if (!(isNetworkError(lastErrMsg) && attempt < NETWORK_RETRY_MAX)) break;
+		if (!await waitForNetworkConnection(ctx, { timeoutMs: opts.timeoutMs ?? NETWORK_READY_TIMEOUT_MS })) break;
+	}
+	throw kernelError(`快速登录失败: ${lastErrMsg}`, "NOT_LOGIN");
+}
+/** 单次快速登录尝试（成功带结果，失败带错误消息）。 */
+async function attemptQuickLogin(loginService, target) {
+	const { errMsg } = (await loginService.quickLoginWithUin(target.uin)).loginErrorInfo;
+	if (errMsg) return {
+		ok: false,
+		errMsg
+	};
+	return {
+		ok: true,
+		result: {
+			uin: target.uin,
+			uid: target.uid ?? "",
+			nick: target.nickName ?? ""
+		}
+	};
+}
+/** 判定快速登录失败是否为网络异常（重试语义）。导出供单测。 */
+function isNetworkError(errMsg) {
+	return errMsg.includes(NETWORK_ERROR_CODE) || errMsg.includes(CONNECTION_ERROR_HINT);
+}
+/**
+* 快速登录：遍历历史登录列表尝试。
+* P2-1：失败且错误为网络异常（1006511）时，等网络就绪后重试（最多 NETWORK_RETRY_MAX 次）。
+*/
+async function quickLogin(ctx, opts) {
+	const raw = ctx.loginService;
+	if (raw === null) throw kernelError("loginService 无效（缺 getLoginList）", "INVALID_STATE");
+	const loginService = raw;
+	await ensureLoginConnected(ctx, { ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} });
+	const items = (await loginService.getLoginList()).LocalLoginInfoList;
+	if (items.length === 0) throw kernelError("无历史登录账号", "NOT_LOGIN");
+	return loginWithNetworkRetry(ctx, loginService, pickLoginTarget(items, opts.uin), opts);
+}
+//#endregion
+//#region src/login/lifecycle.ts
+/**
+* 完整启动生命周期（wrapper.node 契约流程，2026-08-05 实测确认，自研实现）
+*
+* 启动顺序由 wrapper.node 外部契约决定（engine→login→session→startNT），
+* 运行时实测确认，自研实现：
+*  1. engine.initWithDeskTopConfig（appid/qua/版本）
+*  2. loginService.initConfig + addKernelLoginListener
+*  3. getLoginList() → quickLoginWithUin(uin)（或 QR 登录）
+*  4. 登录成功 → genSessionConfig → session.init(config, 3 adapter, listener) → startNT(0)
+*  5. 等 init 完成信号（onOpentelemetryInit(is_init) 为主，onSessionInitComplete 为辅）
+*
+* 关键（2026-08-05 实测修正）：
+*  - session 用 `new wrapper.NodeIQQNTWrapperSession()` 创建；exports 不含 NodeI*Adapter/Listener
+*    构造器（89 键实测无）——adapter 与 listener 一律传普通 JS 对象（NAPI 反射读取方法回调）。
+*
+* 模块边界（2026-08-05 解耦；2026-08-08 FTA 优化再拆）：
+*  - 配置装配（buildEngineConfig / buildLoginConfig / buildSessionConfig）→ wrapper-config.ts
+*  - NAPI 回调适配器（GlobalAdapter / DependsAdapter / DispatcherAdapter / listener 工厂）→ wrapper-adapters.ts
+*  - 登录连接 + 快速登录（waitForNetworkConnection / quickLogin 等）→ login-connect.ts
+*  - 本文件只保留 session 流程编排：就绪等待（waitSessionReady）+ session 初始化（initAndStartSession）。
+*/
+/** session init 默认超时（毫秒）。 */
+const DEFAULT_INIT_TIMEOUT_MS = 15e3;
+/** session 就绪等待默认超时（毫秒）。 */
+const SESSION_READY_TIMEOUT_MS = 3e4;
+/** session 就绪轮询间隔（毫秒）。 */
+const SESSION_READY_POLL_MS = 1e3;
+/**
+* 等待 QQ 自己完成 session 初始化（framework 复用模式，2026-08-05 修正）。
+*
+* 背景：QQ 9.9.31 实测——session 由 QQ 主进程自己创建并 init（登录后）。
+* 我们不自己 init（重复 init 断言 "implementation of IQQNTWrapperSession is not valid"），
+* 也不自己 create（登录前 create() 干扰 QQ，实测 QQ 退出 code=0）。
+* 正确做法：等 QQ 的 session 就绪（getMsgService 非 null = 核心 service 已挂载）。
+*/
+async function waitSessionReady(ctx, opts) {
+	const { session } = ctx;
+	if (session === null || session === void 0) throw kernelError("session 未创建", "INVALID_STATE");
+	if (!await waitFor(() => {
+		try {
+			const svc = session.getMsgService();
+			return svc !== null && svc !== void 0;
+		} catch {
+			return false;
+		}
+	}, opts.timeoutMs ?? SESSION_READY_TIMEOUT_MS, SESSION_READY_POLL_MS)) throw kernelError("等待 QQ session 就绪超时（QQ 未完成 init）", "TIMEOUT");
+}
+/** 登录连接 + 快速登录（quickLogin 等）已拆到 login-connect.ts（见文件头 re-export）。 */
+/** session 初始化（4 参全为普通 JS 对象，等 init 完成信号）。 */
+async function initAndStartSession(ctx, config, listener, opts) {
+	const { session } = ctx;
+	if (session === null || session === void 0) throw kernelError("session 未创建", "INVALID_STATE");
+	const depends = new DependsAdapter();
+	const dispatcher = new DispatcherAdapter();
+	const initComplete = watchInitSignal(listener);
+	session.init(config, depends, dispatcher, listener);
+	startSessionBestEffort(ctx, session);
+	if (!await Promise.race([initComplete.then(() => true), waitFor(() => false, opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS).then(() => false)])) throw kernelError("session init 超时", "TIMEOUT");
+}
+/** 监听 init 完成信号：onOpentelemetryInit(is_init) 为主，onSessionInitComplete(0) 为辅。 */
+function watchInitSignal(listener) {
+	return new Promise((resolve, reject) => {
+		const onOpentelemetry = listener.onOpentelemetryInit;
+		listener.onOpentelemetryInit = (info) => {
+			if (info.is_init) resolve();
+			if (typeof onOpentelemetry === "function") onOpentelemetry(info);
+		};
+		const onInitComplete = listener.onSessionInitComplete;
+		listener.onSessionInitComplete = (r) => {
+			if (r === 0 || r === "0") resolve();
+			else reject(kernelError(`session init 失败: ${String(r)}`, "UNKNOWN"));
+			if (typeof onInitComplete === "function") onInitComplete(r);
+		};
+	});
+}
+/**
+* 启动会话（best effort，失败不致命）：
+* **先 init 后 start（2026-08-07 V9 决定性修正）**。
+* 自建宿主实测（HANDOVER-V9，p0-napcat-min）：必须先 session.init 再
+* startupSession.start()——顺序颠倒（先 start 后 init）业务 service 不挂载
+* （getMsgService null）；init 后用 startNT（非 startupSession.start）也失败。
+* NapCat initializeSession 同款：有 startupSession 用 start()，否则 startNT(0)。
+*/
+function startSessionBestEffort(ctx, session) {
+	if (startupSessionStart(ctx)) return;
+	try {
+		session.startNT(0);
+	} catch {
+		try {
+			session.startNT();
+		} catch {}
+	}
+}
+/** 有 startupSession 则 start()（失败不致命），返回是否已处理。 */
+function startupSessionStart(ctx) {
+	const { startupSession } = ctx;
+	if (startupSession === null || typeof startupSession.start !== "function") return false;
+	try {
+		startupSession.start();
+	} catch {}
+	return true;
+}
+//#endregion
+//#region src/login/login.ts
+/**
+* login.ts：QR 登录流程编排 + 状态机 + selfInfo（ADR-010，2026-08-05）
+*
+* 流程（QQ wrapper 登录契约，自研实现）：
+*  loginService.initConfig（core.login 已做）→ addKernelLoginListener → connect()
+*  → 指定账号：quickLoginWithUin；否则 getQRCodePicture() 触发二维码
+*  → 回调驱动状态机：未登录 → 扫码中 → 已扫码 → 已登录（onQRCodeLoginSucceed）
+*  → 二维码过期（errType=1 errCode=3）→ refresh()
+*
+* 不含 UI 渲染（cli 只做二维码渲染/URL 打印）。
+*/
+/** 二维码过期错误码（errType=1 errCode=3，实测）。 */
+const QR_EXPIRED_ERR_TYPE = 1;
+const QR_EXPIRED_ERR_CODE = 3;
+/** 二维码过期判定。 */
+function isQrCodeExpired(errType, errCode) {
+	return errType === QR_EXPIRED_ERR_TYPE && errCode === QR_EXPIRED_ERR_CODE;
+}
+/** 二维码 png data URI 前缀剥离正则。 */
+const DATA_URI_PREFIX_RE = /^data:image\/\w+;base64,/;
+/** QR 登录会话（状态机 + 回调订阅）。 */
+var QrLoginSession = class {
+	loginService;
+	state = "idle";
+	listenerId = null;
+	self = null;
+	qrCodeHandlers = /* @__PURE__ */ new Set();
+	stateHandlers = /* @__PURE__ */ new Set();
+	constructor(loginService) {
+		const svc = loginService;
+		if (svc === null || typeof svc.addKernelLoginListener !== "function") throw kernelError("loginService 无效（缺 addKernelLoginListener）", "INVALID_STATE");
+		this.loginService = svc;
+	}
+	/** 当前状态。 */
+	get currentState() {
+		return this.state;
+	}
+	/** selfInfo（登录成功后有值）。 */
+	get selfInfo() {
+		return this.self;
+	}
+	/** 订阅二维码（png base64 + url）。返回退订函数。 */
+	onQrCode(cb) {
+		this.qrCodeHandlers.add(cb);
+		return () => this.qrCodeHandlers.delete(cb);
+	}
+	/** 订阅状态变化。返回退订函数。 */
+	onStateChange(cb) {
+		this.stateHandlers.add(cb);
+		return () => this.stateHandlers.delete(cb);
+	}
+	/** 开始登录：注册监听 → connect → 快速登录（指定账号）或触发二维码。 */
+	start(opts = {}) {
+		if (this.state !== "idle") return;
+		this.listenerId = this.loginService.addKernelLoginListener(this.buildListener());
+		this.loginService.connect();
+		if (opts.quickUin !== void 0 && opts.quickUin !== "") this.loginService.quickLoginWithUin(opts.quickUin).then((result) => {
+			if (result.loginErrorInfo.errMsg !== "") this.refresh();
+		}).catch(() => {
+			this.refresh();
+		});
+		else this.refresh();
+	}
+	/** 刷新二维码（手动 / 过期自动）。 */
+	refresh() {
+		this.setState("waiting_scan");
+		this.loginService.getQRCodePicture();
+	}
+	/** 构建登录监听（普通 JS 对象，NAPI 反射）。 */
+	buildListener() {
+		const listener = createLoginListener();
+		listener.onQRCodeGetPicture = ({ pngBase64QrcodeData, qrcodeUrl }) => {
+			const realBase64 = pngBase64QrcodeData.replace(DATA_URI_PREFIX_RE, "");
+			this.emitQrCode({
+				pngBase64: realBase64,
+				qrcodeUrl
+			});
+		};
+		listener.onQRCodeLoginPollingStarted = () => {
+			this.setState("waiting_scan");
+		};
+		listener.onQRCodeSessionUserScaned = () => {
+			this.setState("scanned");
+		};
+		listener.onQRCodeLoginSucceed = (result) => {
+			this.self = {
+				uin: result.uin,
+				uid: result.uid,
+				nick: result.nick ?? ""
+			};
+			this.setState("logged_in");
+		};
+		listener.onQRCodeSessionFailed = (errType, errCode) => {
+			if (isQrCodeExpired(errType, errCode)) {
+				this.refresh();
+				return;
+			}
+			this.setState("failed");
+		};
+		listener.onLoginFailed = () => {
+			this.setState("failed");
+		};
+		return listener;
+	}
+	/** 停止：注销监听（登录成功后调用，防重复回调）。 */
+	stop() {
+		if (this.listenerId !== null) {
+			this.loginService.removeKernelLoginListener(this.listenerId);
+			this.listenerId = null;
+		}
+	}
+	setState(next) {
+		this.state = next;
+		for (const cb of this.stateHandlers) cb(next);
+	}
+	emitQrCode(qr) {
+		for (const cb of this.qrCodeHandlers) cb(qr);
+	}
+};
+//#endregion
+//#region src/wrapper/qq-data-path.ts
+/**
+* QQ 数据根路径解析（P2-1，2026-08-06）
+*
+* 从 `getNTUserDataInfoConfig()` 的返回值中提取 QQ 真实数据根路径：
+* worker（utilityProcess）模式下 loginService 是 new 的，commonPath 必须指向
+* QQ 真实数据路径才能读到历史账号（cli 的 `.napuketto\default` 读不到，
+* getLoginList 空，P2-1 实测）。
+*
+* 返回值形态可能是 JSON 字符串（对象/数组）或纯路径字符串，此处做宽容解析。
+*/
+/**
+* QQ 全局数据目录（commonPath / desktopGlobalPath = 数据根/nt_qq/global，
+* HANDOVER-V6 自建宿主三要素之三，p0-kernel-flow 实证）。
+*
+* 防御：已含 nt_qq/global 后缀（worker 环境下 getNTUserDataInfoConfig 可能
+* 返回完整路径）则不重复拼接，避免 `nt_qq/global/nt_qq/global` 错位。
+*/
+function resolveQqGlobalPath(root) {
+	const norm = root.replace(/\\/g, "/");
+	if (norm.endsWith("/nt_qq/global")) return root;
+	if (norm.endsWith("/nt_qq")) return (0, node_path.join)(root, "global");
+	return (0, node_path.join)(root, "nt_qq", "global");
+}
+/** 从 getNTUserDataInfoConfig 返回值提取数据根（JSON 字符串解析或纯路径）。 */
+function extractDataRoot(raw) {
+	if (raw.startsWith("{") || raw.startsWith("[")) try {
+		return findPathInValue(JSON.parse(raw));
+	} catch {
+		return null;
+	}
+	return raw;
+}
+/** 递归在对象/数组里找含 QQ 数据路径特征的字符串值。 */
+function findPathInValue(value) {
+	if (typeof value === "string") return isQqDataPath(value) ? value : null;
+	if (Array.isArray(value)) return findInArray(value);
+	if (typeof value === "object" && value !== null) return findInObject(value);
+	return null;
+}
+/** 判断字符串是否含 QQ 数据路径特征。 */
+function isQqDataPath(value) {
+	return value.includes("Tencent Files") || value.includes("nt_qq");
+}
+/** 在数组里递归查找。 */
+function findInArray(value) {
+	for (const item of value) {
+		const found = findPathInValue(item);
+		if (found !== null) return found;
+	}
+	return null;
+}
+/** 在对象值里递归查找。 */
+function findInObject(value) {
+	for (const v of Object.values(value)) {
+		const found = findPathInValue(v);
+		if (found !== null) return found;
+	}
+	return null;
+}
+//#endregion
+//#region src/wrapper/wrapper-config.ts
+/**
+* wrapper 交互配置装配（纯函数，无状态）
+*
+* 生成 QQ wrapper 交互所需的三份配置：
+*  - buildEngineConfig  → engine.initWithDeskTopConfig（appid / qua / 版本 / 路径）
+*  - buildLoginConfig   → loginService.initConfig
+*  - buildSessionConfig → session.init（登录成功后调用）
+*
+* 与 lifecycle.ts（流程编排）解耦：本模块只回答「配置长什么样」，不管流程怎么走。
+* 字段为 wrapper.node 外部契约（appid/qua/版本），运行时实测确认，自研描述。
+*/
+/** 系统信息（先用 fixed 值，真实环境探测后补）。 */
+function systemInfo() {
+	return {
+		platVer: "Windows 10.0.22631",
+		osVersion: "Windows 10 Pro",
+		devType: "Windows"
+	};
+}
+/** 纯数字串（major.node 提取的 appid 判定）。 */
+const DIGITS_ONLY_RE = /^\d+$/;
+/**
+* 从 major.node 提取 appid（NapCat parseAppidFromMajorV2 的自研等价实现）。
+* major.node 含 `QQAppId/` 标记后跟数字（腾讯工具链产物，实测确认）。
+* 返回 null 表示解析失败（调用方回退硬编码表）。
+*/
+function parseAppidFromMajor(majorPath) {
+	if (!(0, node_fs.existsSync)(majorPath)) return null;
+	let buf;
+	try {
+		buf = (0, node_fs.readFileSync)(majorPath);
+	} catch {
+		return null;
+	}
+	return scanAppidMarkers(buf);
+}
+/** 扫描 buf 中所有 QQAppId/ 标记，返回第一个纯数字串（无则 null）。 */
+function scanAppidMarkers(buf) {
+	const marker = Buffer.from("QQAppId/", "utf-8");
+	let pos = 0;
+	while (pos < buf.length) {
+		const idx = buf.indexOf(marker, pos);
+		if (idx === -1) return null;
+		const str = readMarkerValue(buf, idx + marker.length);
+		if (DIGITS_ONLY_RE.test(str)) return str;
+		pos = idx + marker.length + str.length + 1;
+	}
+	return null;
+}
+/** 读取标记后的 C 字符串（到首个 0 字节为止）。 */
+function readMarkerValue(buf, start) {
+	let end = 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 解析。
+*/
+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);
+}
+/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（解析 appid/qua）。 */
+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_version: fullVersion,
+		os_version: osVersion,
+		use_xlog: true,
+		qua,
+		global_path_config: { desktopGlobalPath: dataPathGlobal },
+		thumb_config: {
+			maxSide: 324,
+			minSide: 48,
+			longLimit: 6,
+			density: 2
+		}
+	};
+}
+/** 生成登录初始化配置（externalVersion: false 与 NapCat 同款，扫码兼容关键）。 */
+function buildLoginConfig(appid, fullVersion, commonPath) {
+	const { platVer } = systemInfo();
+	return {
+		machineId: "",
+		appid,
+		platVer,
+		commonPath,
+		clientVer: fullVersion,
+		hostName: (0, node_os.hostname)(),
+		externalVersion: false
+	};
+}
+/** 生成 session 初始化配置（登录成功后调用）。 */
+function buildSessionConfig(options) {
+	const { appid, fullVersion, selfUin, selfUid, accountPath, downloadPath } = options;
+	const { platVer, osVersion, devType } = systemInfo();
+	const deviceInfo = {
+		guid: "",
+		buildVer: fullVersion,
+		localId: 2052,
+		devName: (0, node_os.hostname)(),
+		devType,
+		vendorName: "",
+		osVer: osVersion,
+		vendorOsName: devType,
+		setMute: false,
+		vendorType: VendorType.KNOSETONIOS
+	};
+	return {
+		selfUin,
+		selfUid,
+		desktopPathConfig: { account_path: accountPath },
+		clientVer: fullVersion,
+		a2: "",
+		d2: "",
+		d2Key: "",
+		machineId: "",
+		platform: PlatformType.KWINDOWS,
+		platVer,
+		appid,
+		rdeliveryConfig: {
+			appKey: "",
+			systemId: 0,
+			appId: "",
+			logicEnvironment: "",
+			platform: PlatformType.KWINDOWS,
+			language: "",
+			sdkVersion: "",
+			userId: "",
+			appVersion: "",
+			osVersion: "",
+			bundleId: "",
+			serverUrl: "",
+			fixedAfterHitKeys: [""]
+		},
+		defaultFileDownloadPath: downloadPath,
+		deviceInfo,
+		deviceConfig: "{\"appearance\":{\"isSplitViewMode\":true},\"msg\":{}}"
+	};
+}
+//#endregion
+//#region src/wrapper/wrapper-loader.ts
+/**
+* wrapper 引导（NAPI 范式，2026-08-05 重构，替代旧 koffi 方案）
+*
+* 事实（实测）：wrapper.node 不是标准 NAPI self-register 模块，只能在 QQ 定制版
+* Electron 主进程里由 preload 注册。@napuketto/loader 注入 hook DLL 后，boot.cjs
+* 在 QQ 主进程内截获 `process.dlopen` 的 `module.exports`，然后调用本模块初始化。
+*
+* 本模块**不再**使用 koffi / vtable / 内存偏移——所有对象由 QQ 的 NAPI 层自动构建。
+* 业务层拿到的都是真实 JS 对象：engine.initWithDeskTopConfig(config, adapter) 等。
+*/
+/** 默认 engine 配置（KWINDOWS + 版本号，字段待首个真实联调确认）。 */
+function defaultEngineConfig(env, qqDataPath) {
+	return {
+		base_path_prefix: env.dataDir ?? "",
+		platform_type: PlatformType.KWINDOWS,
+		app_type: 4,
+		app_version: env.qqVersion ?? "",
+		os_version: node_process.default.platform,
+		use_xlog: false,
+		qua: "",
+		global_path_config: { desktopGlobalPath: qqDataPath ?? env.dataDir ?? "" },
+		thumb_config: {
+			maxSide: 324,
+			minSide: 48,
+			longLimit: 6,
+			density: 2
+		}
+	};
+}
+/**
+* Electron 进程类型（Node 的 process 类型无此字段）。
+* - "browser"：QQ 主进程（V1 模式）
+* - "utility"：utilityProcess Worker（路线 B，2026-08-06）
+*/
+function electronProcessType() {
+	return node_process.default.type;
+}
+/**
+* 解析 QQ 用户数据根（登录数据目录，如 `C:\Users\<user>\Documents\Tencent Files`）。
+* 优先 NodeQQNTWrapperUtil.getNTUserDataInfoConfig()（QQ 官方 API），回退默认位置。
+*
+* 背景（2026-08-06 P2-1 实测）：worker（utilityProcess）模式下 loginService 是
+* `new NodeIKernelLoginService()` 新建的，其 initConfig 的 commonPath 必须指向
+* QQ 真实数据路径才能读到历史账号——cli 的 `.napuketto\default` 数据目录读不到
+* （getLoginList 返回空 → 只能 QR 登录）。V1 主进程模式 QQ 自己 initConfig 过
+* 正确路径，无需此解析。
+*/
+function resolveQqUserDataRoot(exports) {
+	return extractUserDataRoot(exports) ?? (0, node_path.join)((0, node_os.homedir)(), "Documents", "Tencent Files");
+}
+/** 从 QQ 官方 API 提取数据根（不可用返回 null，调用方回退默认）。 */
+function extractUserDataRoot(exports) {
+	try {
+		const raw = exports.NodeQQNTWrapperUtil?.get?.().getNTUserDataInfoConfig?.();
+		if (typeof raw === "string" && raw.trim() !== "") return extractDataRoot(raw.trim());
+	} catch {}
+	return null;
+}
+/**
+* 从 loader 截获的 NAPI exports 创建 wrapper 上下文。
+* 在 QQ 主进程内调用（boot.cjs → kernel 入口）。
+*/
+function createWrapper(exports, versionInfo) {
+	const engineMaybe = exports.NodeIQQNTWrapperEngine;
+	if (engineMaybe === null || typeof engineMaybe.get !== "function") throw kernelError("wrapper.node exports 无效（缺少 NodeIQQNTWrapperEngine）", "INVALID_PARAM");
+	const engine = engineMaybe.get();
+	if (!engine || typeof engine.initWithDeskTopConfig !== "function") throw kernelError("NodeIQQNTWrapperEngine.get() 返回对象无效", "INVALID_PARAM");
+	return {
+		exports,
+		engine,
+		versionInfo,
+		session: null,
+		startupSession: null,
+		loginService: null
+	};
+}
+/** engine 初始化（wrapper 契约：先 engine 后 session）。config 为普通 JS 对象。 */
+function initEngine(ctx, config) {
+	ctx.engine.initWithDeskTopConfig(config, new GlobalAdapter());
+}
+/**
+* 创建会话（2026-08-06 P2-0 实测修正——NapCat 方式自研等价）：
+*  1. StartupSessionWrapper.create()（启动会话包装）
+*  2. getNTWrapperSession("nt_1")（QQ 主 session，带完整 cpp_impl）
+*  3. S.create() 回退
+*
+* 背景：`new NodeIQQNTWrapperSession()` 构造对象缺 cpp_impl，session.init 断言
+* "implementation of IQQNTWrapperSession is not valid"（P2-0 实测确认）。
+* NapCat 用 StartupSessionWrapper.create() + getNTWrapperSession('nt_1') 解决——
+* 返回带完整实现的实例。worker（utilityProcess）继承 QQ env 后同样有效。
+*/
+function createSession(ctx) {
+	const S = ctx.exports.NodeIQQNTWrapperSession;
+	const session = createStartupSession(ctx) ?? getNTWrapperSession(S) ?? createNewSession(S) ?? new S();
+	ctx.session = session;
+	return session;
+}
+/** 步骤 1：StartupSessionWrapper.create()（建立启动 session，失败忽略）。 */
+function createStartupSession(ctx) {
+	const Ssw = ctx.exports.NodeIQQNTStartupSessionWrapper;
+	if (Ssw === void 0 || typeof Ssw.create !== "function") return null;
+	try {
+		ctx.startupSession = Ssw.create();
+	} catch {}
+	return null;
+}
+/** 步骤 2：getNTWrapperSession("nt_1")（QQ 主 session，带 cpp_impl）。 */
+function getNTWrapperSession(S) {
+	if (typeof S.getNTWrapperSession !== "function") return null;
+	try {
+		return S.getNTWrapperSession("nt_1");
+	} catch {
+		return null;
+	}
+}
+/** 步骤 3：S.create() 回退。 */
+function createNewSession(S) {
+	if (typeof S.create !== "function") return null;
+	try {
+		return S.create();
+	} catch {
+		return null;
+	}
+}
+/** session 初始化（4 参全为 JS 对象，NAPI 自动转换）。 */
+function initSession(ctx, config, listener) {
+	(ctx.session ?? createSession(ctx)).init(config, new DependsAdapter(), new DispatcherAdapter(), listener);
+}
+/**
+* 启动会话（有 startupSession 用 start()，否则 startNT(0)）。
+*
+* ⚠️ 2026-08-07 V9 修正：单纯 start() 只在「已 init」的 session 上有效。
+* 自建宿主必须走 initAndStartSession（先 session.init 再 startupSession.start()）——
+* 先 start 后 init 业务 service 不挂载（HANDOVER-V9 实测）。本函数保留给
+* 已 init 的 session 补启动用；新路径请用 initAndStartSession。
+*/
+function startSession(ctx) {
+	const { session, startupSession } = ctx;
+	if (session === null) throw kernelError("session 未创建，无法启动", "INVALID_STATE");
+	if (startupSession !== null && typeof startupSession.start === "function") {
+		startupSession.start();
+		return;
+	}
+	session.startNT(0);
+}
+/**
+* boot 装配入口：createWrapper → initEngine → session。
+*
+* **session 来源（2026-08-05 修正）**：
+*  1. qqSession（boot.cjs 拦截 `new` 窃取的 QQ 已 init session）——尚未落地
+*  2. createSession（`new NodeIQQNTWrapperSession()`）——实测可用，默认路径
+*  （getMainSession 实测为空壳：service 全 null + 缺 startNT，仅 probe 探测参考）
+*
+* 由 loader runtime/boot.cjs 在 QQ 主进程内调用（import kernel dist 后）。
+* 返回 WrapperContext；失败抛 KernelError。
+*/
+function startNapuketto(options) {
+	const { env, engineConfig, sessionConfig, wrapperExports, qqSession, qqLoginService } = options;
+	const ctx = createWrapper(wrapperExports, {
+		fullVersion: env?.qqVersion ?? "",
+		buildVersion: env?.qqVersion ?? ""
+	});
+	const hasCapturedSession = captureSession(ctx, qqSession);
+	const isSelfHost = electronProcessType() === void 0;
+	prepareSession(ctx, hasCapturedSession, isSelfHost);
+	initEngine(ctx, resolveEngineConfig(ctx, env, engineConfig));
+	resolveLoginService(ctx, qqLoginService);
+	finishSession(ctx, hasCapturedSession, isSelfHost, sessionConfig);
+	return ctx;
+}
+/** engine 前 session 准备（自建宿主必须先建，顺序决定性）。 */
+function prepareSession(ctx, hasCaptured, isSelfHost) {
+	if (!hasCaptured && isSelfHost) createSession(ctx);
+}
+/** engine 后收尾：非自建宿主补建 session；配置了 sessionConfig 则 init+start。 */
+function finishSession(ctx, hasCaptured, isSelfHost, sessionConfig) {
+	if (!hasCaptured && !isSelfHost) createSession(ctx);
+	if (sessionConfig !== void 0) {
+		initSession(ctx, sessionConfig, createSessionListener());
+		startSession(ctx);
+	}
+}
+/** engine 配置：显式覆盖优先，否则默认（含 QQ 数据根 global 路径解析）。 */
+function resolveEngineConfig(ctx, env, engineConfig) {
+	if (engineConfig !== void 0) return engineConfig;
+	return defaultEngineConfig(env ?? {}, resolveBootQqGlobalPath(ctx));
+}
+/** 捕获 QQ 已 init 的 session（boot.cjs 拦截 `new` 窃取），返回是否捕获成功。 */
+function captureSession(ctx, qqSession) {
+	if (qqSession === void 0 || qqSession === null) return false;
+	ctx.session = qqSession;
+	return true;
+}
+/**
+* 解析 QQ 真实数据目录的 global 路径（desktopGlobalPath 三要素之三）。
+* worker（utilityProcess）模式 + 自建宿主（标准 node）下必须指向 QQ 真实
+* 数据目录（数据根/nt_qq/global，HANDOVER-V6），否则登录数据读写错位
+* （P2-1 实测 2026-08-06；getLoginList 空）。QQ 主进程（V1）QQ 自己已配置
+* engine，无需解析。
+*/
+function resolveBootQqGlobalPath(ctx) {
+	if (electronProcessType() === "browser") return;
+	const root = resolveQqUserDataRoot(ctx.exports);
+	if (root === null) return;
+	return resolveQqGlobalPath(root);
+}
+/**
+* 解析 loginService：优先捕获实例，其次单例 get()（自建宿主/worker 下 QQ 环境
+* 创建的实例才完整——`new` 自建实例读不到登录列表（getLoginList 空），
+* HANDOVER-V6 p0-login3 实证），最后 new 回退。
+*/
+function resolveLoginService(ctx, qqLoginService) {
+	if (qqLoginService !== void 0 && qqLoginService !== null) {
+		ctx.loginService = qqLoginService;
+		return;
+	}
+	ctx.loginService = getOrCreateLoginService(ctx.exports);
+}
+/** 单例 get() 优先，缺失回退 new（都失败返回 null）。 */
+function getOrCreateLoginService(exports) {
+	try {
+		const loginSvcCtor = exports.NodeIKernelLoginService;
+		if (loginSvcCtor !== null && typeof loginSvcCtor.get === "function") return loginSvcCtor.get();
+		return new exports.NodeIKernelLoginService();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/core.ts
+/**
+* NapukettoCore：装配 + 启动（§9 第 6 项，2026-08-05 实现）
+*
+* 装配：paths（建目录）→ logger → CoreContext。
+* 启动：attachWrapper（wrapperExports → startNapuketto）→ login（快速登录 → session.init）。
+*
+* 典型用法（boot.cjs 截获 exports 后）：
+*   const core = await NapukettoCore.create({ dataRoot, account });
+*   core.attachWrapper(wrapperExports, { qqVersion, dataDir });
+*   await core.login({ appid: "537237765" });
+*
+* 与手动拼 startNapuketto/quickLogin/initAndStartSession 等价，但把装配状态
+* （ctx）集中管理，协议层直接消费 core.ctx。
+*/
+/**
+* 核心装配器：持有 CoreContext，负责启动/停止编排。
+* 无全局单例（ADR-015 推论）——每账号每进程实例化一份。
+*/
+var NapukettoCore = class NapukettoCore {
+	/** 装配根（协议层 / apis / cache 的消费入口）。 */
+	ctx;
+	/** 由 create() 装配，不直接 new。 */
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* 装配：paths（建目录）→ logger → CoreContext。
+	* 不加载 wrapper / 不登录——启动阶段由 attachWrapper + login 完成。
+	*/
+	static create(opts = {}) {
+		const paths = new PathWrapper(opts.paths);
+		paths.ensure();
+		const logger = createLogger({
+			level: opts.logLevel ?? "info",
+			console: opts.consoleLog ?? true,
+			file: opts.logFile ?? paths.file("logs", "napuketto.log"),
+			base: { name: "kernel" }
+		});
+		return new NapukettoCore(createCoreContext({
+			logger,
+			paths
+		}));
+	}
+	/**
+	* 装配 wrapper：wrapperExports → startNapuketto（engine.init + session 创建），
+	* 结果挂到 ctx.wrapper。在 QQ 主进程内调用（boot.cjs 截获 exports 后）。
+	* captured：boot.cjs 拦截 `new` 捕获的 QQ 实例（session/loginService，优先使用）。
+	*/
+	attachWrapper(wrapperExports, env, captured) {
+		let wrapper;
+		if (env === void 0) wrapper = startNapuketto({
+			wrapperExports,
+			...captured
+		});
+		else wrapper = startNapuketto({
+			wrapperExports,
+			env,
+			...captured
+		});
+		this.ctx.wrapper = wrapper;
+		this.ctx.logger.info({ version: env?.qqVersion }, "wrapper 装配完成（engine + session）");
+		return wrapper;
+	}
+	/**
+	* 登录 + session 初始化（wrapper 契约，2026-08-05 实测确认）：
+	* loginService.initConfig → 登录（快速/QR）→ **登录成功后** create session + init
+	* → 等 onOpentelemetryInit(is_init) 完成信号。成功后填 ctx.login。
+	*
+	* 关键（实测）：登录前 create()/init 均断言失败（session 未 init / 干扰 QQ）；
+	* 登录后 QQ 自己 init 并触发 listener.onOpentelemetryInit——我们只需在登录后
+	* create + init 并监听该信号。
+	*/
+	async login(opts) {
+		const { wrapper } = this.ctx;
+		if (wrapper === null) throw kernelError("wrapper 未装配，无法登录", "INVALID_STATE");
+		this.initLoginConfig(wrapper, opts.appid);
+		let loginResult;
+		try {
+			const quickOpts = {};
+			if (opts.quickUin !== void 0) quickOpts.uin = opts.quickUin;
+			loginResult = await quickLogin(wrapper, quickOpts);
+			this.ctx.logger.info({
+				uin: loginResult.uin,
+				uid: loginResult.uid
+			}, "快速登录成功");
+		} catch (err) {
+			if (opts.qrFallback !== true) throw err;
+			loginResult = await this.loginByQr(opts);
+		}
+		this.ctx.login = loginResult;
+		return loginResult;
+	}
+	/**
+	* loginService.initConfig（worker/自建宿主需指定 QQ 真实数据路径）。
+	* worker（utilityProcess）模式 + 自建宿主（标准 node）下 loginService 是
+	* new 的，commonPath 必须指向 QQ 真实数据目录（数据根/nt_qq/global，
+	* HANDOVER-V6 三要素之三）才能读到历史账号——cli 的 `.napuketto\default`
+	* 读不到（getLoginList 空，P2-1 实测 2026-08-06）。
+	* QQ 主进程（V1）模式 QQ 自己 initConfig 过正确路径，无需解析。
+	*/
+	initLoginConfig(wrapper, appid) {
+		const loginService = wrapper.loginService;
+		if (loginService === null || typeof loginService.initConfig !== "function") {
+			this.ctx.logger.warn("loginService 不可用，跳过 initConfig");
+			return;
+		}
+		const commonPath = resolveCommonPath(this.ctx, wrapper);
+		const loginCfg = buildLoginConfig(appid, wrapper.versionInfo.fullVersion, commonPath);
+		loginService.initConfig(loginCfg);
+		this.ctx.logger.info({ commonPath }, "loginService.initConfig OK");
+	}
+	/**
+	* 替换当前 session（登录后 Proxy 捕获的 QQ 新实例替换自己 create 的无效实例）。
+	* 在 QQ 主进程内由 boot.cjs 调用（登录成功后）。
+	*/
+	setSession(session) {
+		if (this.ctx.wrapper === null) throw kernelError("wrapper 未装配，无法设置 session", "INVALID_STATE");
+		this.ctx.wrapper.session = session;
+	}
+	/** 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);
+		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
+		};
+	}
+	/** 订阅 QR 进度：二维码写盘 + 状态机经 onLoginProgress 转发。 */
+	subscribeQrProgress(session, opts, qrPath) {
+		session.onQrCode((qr) => {
+			this.ctx.logger.warn(`请扫描二维码登录（保存: ${qrPath} | URL: ${qr.qrcodeUrl}）`);
+			if (qr.pngBase64 !== "") writeQrCodePng(qrPath, qr.pngBase64);
+			opts.onLoginProgress?.({
+				state: "waiting_scan",
+				qr
+			});
+		});
+		session.onStateChange((state) => {
+			this.ctx.logger.info({ state }, "QR 登录状态");
+			opts.onLoginProgress?.({ state });
+		});
+	}
+	/** 停止：日志收尾（资源清理留给 P2 常驻管理）。 */
+	stop() {
+		this.ctx.logger.info("NapukettoCore 停止");
+	}
+};
+/** 写二维码 png 到磁盘（base64 解码，供 cli/用户扫码）。 */
+function writeQrCodePng(filePath, pngBase64) {
+	try {
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(filePath), { recursive: true });
+		(0, node_fs.writeFileSync)(filePath, Buffer.from(pngBase64, "base64"));
+	} catch {}
+}
+/** 等待 QR 登录终态：logged_in resolve，failed reject。 */
+function waitQrLoggedIn(session) {
+	return new Promise((resolve, reject) => {
+		const offState = session.onStateChange((state) => {
+			if (state === "logged_in") {
+				offState();
+				resolve();
+			} else if (state === "failed") {
+				offState();
+				reject(kernelError("QR 登录失败", "NOT_LOGIN"));
+			}
+		});
+	});
+}
+/**
+* loginService.initConfig 的 commonPath：
+* worker/自建宿主（非 browser）优先 QQ 真实数据目录（数据根/nt_qq/global），
+* 否则回退账号目录。
+*/
+function resolveCommonPath(ctx, wrapper) {
+	if (electronProcessType() !== "browser") {
+		const root = resolveQqUserDataRoot(wrapper.exports);
+		if (root !== null) return resolveQqGlobalPath(root);
+	}
+	return ctx.paths.accountDir;
+}
+//#endregion
+//#region src/event-channel.ts
+/**
+* 类型化事件通道（ADR-003）
+*
+* - 事件名约定 `${Service}/${method}`（如 "Msg/onRecvMsg"），签名从 Listener 接口编译期推导
+* - 事件名写错 → 编译期报错（类型推导）
+* - `on` 返回 unsubscribe；`waitFor` 注册临时监听 → filter → 超时自动清理（替代魔法字符串方案）
+* - error 兜底：监听器抛异常不打断派发，统一经 `onError` 通知
+*
+* 组合实现而非 extends EventEmitter：EventEmitter.on 返回 `this`，与设计要求的
+* 返回 unsubscribe 冲突；组合更干净，且内核无全局单例（ADR-015 推论）。
+*
+* 类型推导说明：不直接 `ListenerEvents<L, Name>[E]` 索引（泛型下会扩宽到
+* string|number|symbol 索引，索引出 unknown），而是用 Extract 按事件名从
+* `{ name, fn }` 联合精确提取 handler / 参数类型，保证实例化后签名精确。
+*/
+/** waitFor 默认超时（毫秒）。 */
+const DEFAULT_WAIT_TIMEOUT_MS = 3e4;
+/**
+* 类型化事件通道。
+*
+* @typeParam L - Listener 接口（探测产物，如 MsgListener）
+* @typeParam Name - Service 名（事件名前缀，如 "Msg"）
+*/
+var NTEventChannel = class {
+	serviceName;
+	emitter = new node_events.EventEmitter();
+	errorHandlers = /* @__PURE__ */ new Set();
+	anyHandlers = /* @__PURE__ */ new Set();
+	constructor(serviceName) {
+		this.serviceName = serviceName;
+		this.emitter.setMaxListeners(0);
+	}
+	/**
+	* 订阅事件：返回 unsubscribe（只注销该 handler，不影响其他订阅者）。
+	* 每个 Service 只注册一次原生监听，缓存维护与协议翻译都订阅这里。
+	*/
+	on(event, handler) {
+		this.emitter.addListener(event, handler);
+		return () => {
+			this.emitter.removeListener(event, handler);
+		};
+	}
+	/**
+	* 请求-响应桥：注册临时监听 → filter 命中 → resolve；超时自动清理并 reject。
+	* 替代魔法字符串事件名方案。
+	*/
+	waitFor(event, opts = {}) {
+		const timeoutMs = opts.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+		return new Promise((resolve, reject) => {
+			const handler = (...args) => {
+				if (opts.filter && !opts.filter(...args)) return;
+				cleanup();
+				resolve(args);
+			};
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(new KernelError(`等待事件超时: ${event}`, "TIMEOUT"));
+			}, timeoutMs);
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.emitter.removeListener(event, handler);
+			};
+			this.emitter.addListener(event, handler);
+		});
+	}
+	/**
+	* 类型化派发：wrapper-loader 的原生回调经此推入通道。
+	* 2026-08-07 修复：原生 EventEmitter.emit 中一个 listener 抛异常会中断后续
+	* listener 派发（Node 语义）——改为快照数组逐个 try/catch，保证「单个订阅者
+	* 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
+	*/
+	/**
+	* 订阅所有事件（IPC 子进程模式整通道转发用：事件名 `"${service}/${method}"`
+	* 经 handler 首参透出，args 原样透传）。返回退订函数。
+	*/
+	onAny(handler) {
+		this.anyHandlers.add(handler);
+		return () => {
+			this.anyHandlers.delete(handler);
+		};
+	}
+	emit(event, ...args) {
+		for (const anyHandler of this.anyHandlers) try {
+			anyHandler(event, ...args);
+		} catch (err) {
+			this.notifyError(err);
+		}
+		const listeners = this.emitter.listeners(event);
+		for (const listener of listeners) try {
+			listener(...args);
+		} catch (err) {
+			this.notifyError(err);
+		}
+	}
+	/** 通知所有错误处理器（单个异常不打断其他处理器）。 */
+	notifyError(err) {
+		for (const handler of this.errorHandlers) handler(err);
+	}
+	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
+	onError(handler) {
+		this.errorHandlers.add(handler);
+		return () => {
+			this.errorHandlers.delete(handler);
+		};
+	}
+};
+//#endregion
+//#region src/wrapper/session-resolver.ts
+/** 从 getSessionIdList 的 Map 提取主 sessionId（nt_ 前缀优先）。 */
+function findMainSessionId(ids) {
+	return firstStringId(ids, (s) => s.startsWith("nt_")) ?? firstStringId(ids, () => true);
+}
+/** 遍历 Map 找第一个满足谓词的字符串 id（值优先，其次键）。 */
+function firstStringId(ids, pred) {
+	for (const [k, v] of ids) {
+		if (typeof v === "string" && pred(v)) return v;
+		if (typeof k === "string" && pred(k)) return k;
+	}
+	return null;
+}
+/** 通过 getNTWrapperSession 拿主 session（内部辅助）。 */
+function resolveMainSession(created, getNTWrapperSession) {
+	created.start?.();
+	const ids = typeof created.getSessionIdList === "function" ? created.getSessionIdList() : null;
+	if (!(ids instanceof Map)) return null;
+	const mainId = findMainSessionId(ids);
+	if (mainId === null) return null;
+	const maybe = getNTWrapperSession(mainId);
+	return maybe !== null && maybe !== void 0 && typeof maybe.getMsgService === "function" ? maybe : null;
+}
+/**
+* 复用 QQ 已有 session（P1-4：QQ 已登录，直接拿单例避免重复 init）。
+* 优先 `NodeIQQNTWrapperSession.get()`；返回 null 时回退 createSession。
+*/
+function getExistingSession(ctx) {
+	const got = trySessionGet(ctx);
+	if (got !== null) {
+		ctx.session = got;
+		return got;
+	}
+	return null;
+}
+/** NodeIQQNTWrapperSession.get() 单例（无效/异常返回 null）。 */
+function trySessionGet(ctx) {
+	try {
+		const S = ctx.exports.NodeIQQNTWrapperSession;
+		if (typeof S.get !== "function") return null;
+		const got = S.get();
+		return got && typeof got.getMsgService === "function" ? got : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 复用 QQ 主 session（P1-4 实测链路）：
+* `NodeIQQNTStartupSessionWrapper.create()` → `start()` → `getSessionIdList()`（Map
+* {nt:"nt_3", gpro:"gpro_3"}）→ `NodeIQQNTWrapperSession.getNTWrapperSession("nt_3")`。
+* 注：实测这些 session 是空壳（核心 service null），真正可用的是 new + init（lifecycle.ts）。
+*/
+function getMainSession(ctx) {
+	try {
+		return resolveMainFromStartup(ctx) ?? null;
+	} catch {
+		return null;
+	}
+}
+/** startup.create → start → getSessionIdList → getNTWrapperSession 链路。 */
+function resolveMainFromStartup(ctx) {
+	const startupRaw = ctx.exports.NodeIQQNTStartupSessionWrapper;
+	const sessionCtor = ctx.exports.NodeIQQNTWrapperSession;
+	if (typeof startupRaw.create !== "function" || typeof sessionCtor.getNTWrapperSession !== "function") return null;
+	const created = startupRaw.create();
+	if (!created) return null;
+	const getSession = (id) => sessionCtor.getNTWrapperSession(id);
+	const session = resolveMainSession(created, getSession);
+	if (session !== null) ctx.session = session;
+	return session;
+}
+//#endregion
+//#region src/wrapper/probe/probe-serialize.ts
+/**
+* 运行时反射探测的序列化工具（从 probe.ts 拆分，2026-08-08 FTA 优化）
+*
+* - serialize：深度受限序列化（BigInt 转字符串，Map/Set/Promise 展开，循环引用防护）
+* - tryShape：解析 service getter 返回形状
+* - shapeKeyGetters：探测 service 关键数据 getter 返回形状
+*/
+/** 序列化深度上限（循环引用/深层对象防护）。 */
+const MAX_SERIALIZE_DEPTH = 4;
+/** 数组序列化条数上限。 */
+const MAX_ARRAY_ITEMS = 20;
+/** 对象键序列化条数上限。 */
+const MAX_OBJECT_KEYS = 50;
+/** 序列化一个值（BigInt 转字符串，Map/Set/Promise 展开，循环引用防护）。 */
+function serialize(value, depth = 0) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "function") return `[function ${value.name ?? "anon"}]`;
+	if (typeof value !== "object") return value;
+	if (depth > MAX_SERIALIZE_DEPTH) return "[depth-limit]";
+	try {
+		return serializeContainer(value, depth);
+	} catch {
+		return "[unserializable]";
+	}
+}
+/** 序列化容器对象（数组 / Map / Set / Promise / 普通对象）。 */
+function serializeContainer(value, depth) {
+	if (Array.isArray(value)) return serializeArray(value, depth);
+	if (value instanceof Map) return serializeMap(value, depth);
+	if (value instanceof Set) return serializeSet(value, depth);
+	if (typeof value.then === "function") return "[Promise]";
+	return serializeObject(value, depth);
+}
+/** 数组序列化（条数截断）。 */
+function serializeArray(value, depth) {
+	return value.slice(0, MAX_ARRAY_ITEMS).map((v) => serialize(v, depth + 1));
+}
+/** Map 序列化（键转字符串，条目截断）。 */
+function serializeMap(value, depth) {
+	const out = {};
+	let i = 0;
+	for (const [k, v] of value) {
+		if (i >= MAX_OBJECT_KEYS) break;
+		out[String(k)] = serialize(v, depth + 1);
+		i += 1;
+	}
+	return {
+		kind: "Map",
+		size: value.size,
+		entries: out
+	};
+}
+/** Set 序列化（值截断）。 */
+function serializeSet(value, depth) {
+	return {
+		kind: "Set",
+		size: value.size,
+		values: [...value].slice(0, MAX_ARRAY_ITEMS).map((v) => serialize(v, depth + 1))
+	};
+}
+/** 普通对象序列化（键截断）。 */
+function serializeObject(value, depth) {
+	const out = {};
+	for (const key of Object.keys(value).slice(0, MAX_OBJECT_KEYS)) out[key] = serialize(value[key], depth + 1);
+	return out;
+}
+/** 尝试解析一个 service getter 的返回值形状（深度受限）。 */
+function tryShape(session, getter) {
+	try {
+		const fn = session[getter];
+		if (typeof fn !== "function") return null;
+		const value = fn.call(session);
+		if (value === null || value === void 0) return null;
+		return serialize(value);
+	} catch {
+		return "[error]";
+	}
+}
+/** 数据 getter 方法名模式（探测返回形状用）。 */
+const DATA_GETTER_RE = /^(get|query|fetch|load)/i;
+/** 探测 service 的关键数据 getter 返回形状（取前几个无参调用）。 */
+function shapeKeyGetters(session, serviceMethods) {
+	const out = {};
+	const candidates = serviceMethods.filter((m) => DATA_GETTER_RE.test(m) && !m.endsWith("Listener"));
+	for (const m of candidates.slice(0, 8)) out[m] = tryShape(session, m);
+	return out;
+}
+//#endregion
+//#region src/wrapper/probe/probe-utils.ts
+/**
+* 运行时反射探测基础工具（从 probe.ts 拆分，2026-08-08 FTA 优化）
+*
+* - listMethods：反射枚举对象原型链上的方法名（去重、去构造器）
+* - tryCall：安全调用方法拿返回值（失败记录错误，不中断探测）
+*/
+/** 反射枚举一个对象原型链上的方法名（去重、去构造器）。 */
+function listMethods(obj) {
+	if (obj === null || obj === void 0) return [];
+	const names = /* @__PURE__ */ new Set();
+	collectPrototypeNames(obj, names);
+	collectOwnNames(obj, names);
+	return [...names].sort();
+}
+/** 收集原型链上的属性名（到 Object/Function.prototype 为止，去构造器）。 */
+function collectPrototypeNames(obj, names) {
+	let proto = Object.getPrototypeOf(obj);
+	while (isProbeProto(proto)) {
+		for (const name of Object.getOwnPropertyNames(proto)) if (name !== "constructor") names.add(name);
+		proto = Object.getPrototypeOf(proto);
+	}
+}
+/** 是否仍需遍历的原型（非 Object/Function.prototype 且非空）。 */
+function isProbeProto(proto) {
+	return proto !== null && proto !== Object.prototype && proto !== Function.prototype;
+}
+/** 收集自有属性名（去构造器）。 */
+function collectOwnNames(obj, names) {
+	for (const name of Object.getOwnPropertyNames(obj)) if (name !== "constructor") names.add(name);
+}
+/** 安全调用：尝试调用方法拿返回值，失败记录错误（不中断探测）。 */
+function tryCall(obj, name) {
+	try {
+		const fn = obj[name];
+		if (typeof fn !== "function") return {
+			ok: false,
+			error: `not a function (typeof=${typeof fn})`
+		};
+		return {
+			ok: true,
+			value: fn.call(obj)
+		};
+	} catch (e) {
+		let message = String(e);
+		if (e instanceof Error) message = e.message;
+		return {
+			ok: false,
+			error: message
+		};
+	}
+}
+//#endregion
+//#region src/wrapper/probe/probe-services.ts
+/** 探测关键 export 构造器方法（get/create/getNTWrapperSession 等）。 */
+function probeExportCtors(ctx) {
+	const keys = [
+		"NodeIQQNTWrapperSession",
+		"NodeIQQNTStartupSessionWrapper",
+		"NodeQQNTWrapperUtil",
+		"NodeIKernelLoginService",
+		"NodeIQQNTWrapperEngine"
+	];
+	const out = {};
+	for (const key of keys) {
+		const ctor = ctx.exports[key];
+		if (ctor !== null && ctor !== void 0) out[key] = {
+			methods: listMethods(ctor),
+			ownKeys: Object.getOwnPropertyNames(ctor)
+		};
+	}
+	return out;
+}
+/** 探测 engine 关键调用（getDeviceInfo / getECDHService / getThirdPartySigService）。 */
+function probeEngineCalls(ctx) {
+	const out = {};
+	for (const m of ENGINE_CALL_PROBES) out[m] = probeEngineCall(ctx, m);
+	return out;
+}
+/** 探测单个 engine 方法调用（成功记录方法面/形状，失败记录错误）。 */
+function probeEngineCall(ctx, m) {
+	const call = tryCall(ctx.engine, m);
+	return call.ok ? {
+		value: serialize(call.value),
+		methods: call.value ? listMethods(call.value) : []
+	} : { error: call.error ?? "null/undefined" };
+}
+/** engine 关键调用候选。 */
+const ENGINE_CALL_PROBES = [
+	"getDeviceInfo",
+	"getECDHService",
+	"getThirdPartySigService",
+	"readyToShow"
+];
+/** 探测 LoginService 实例（QQ 已登录凭据入口）。 */
+function probeLoginService(ctx) {
+	const ctor = ctx.exports.NodeIKernelLoginService;
+	if (ctor === null || typeof ctor.get !== "function") return null;
+	const inst = tryCall(ctor, "get");
+	if (!(inst.ok && inst.value)) return { get: inst.error ?? "null/undefined" };
+	return {
+		methods: listMethods(inst.value),
+		ownKeys: Object.getOwnPropertyNames(inst.value).slice(0, 30),
+		...probeLoginGetters(inst.value)
+	};
+}
+/** 尝试关键登录信息 getter（无参调用，探测形状）。 */
+function probeLoginGetters(inst) {
+	const out = {};
+	for (const m of LOGIN_GETTER_PROBES) if (typeof inst[m] === "function") out[m] = tryShape(inst, m);
+	return out;
+}
+/** 登录信息 getter 候选（无参调用，探测形状）。 */
+const LOGIN_GETTER_PROBES = [
+	"getAccountInfo",
+	"getLoginInfo",
+	"getA2",
+	"getTicket",
+	"getUin",
+	"getUid",
+	"getSelfUin"
+];
+//#endregion
+//#region src/wrapper/probe/probe.ts
+/**
+* 运行时反射探测（ADR-006 落地，P1-4）
+*
+* 注入链路打通后（2026-08-05），wrapper exports 是 QQ 已注册的单例。
+* 本模块在 **QQ 主进程内**反射枚举 session / service 的真实方法名与返回形状，
+* 产出 JSON 到 NAPUTO_CFG_DIR/napuketto-probe.json，作为 types/services/ 的权威来源。
+*
+* 用法：boot.cjs 在 NAPUTO_PROBE=1 时于 startNapuketto 后调用 probeRuntime(ctx)。
+* 产物是研究工具数据，类型层据此补全（自研描述，非移植）。
+*
+* 工具拆分（2026-08-08 FTA 优化）：方法枚举/安全调用 → probe-utils.ts；
+* 序列化/形状探测 → probe-serialize.ts；exports/service 探测 → probe-services.ts；
+* 本文件只留 session 探测编排（probeStartup/probeSession/probeRuntime）。
+*/
+/** 枚举候选 sessionId（nt_0..nt_9 / gpro_0..gpro_9）找 QQ 已 init 的 session。 */
+function enumerateSessionIds(ctx) {
+	const S = ctx.exports.NodeIQQNTWrapperSession;
+	const enumFn = getNTWrapperSessionFn(ctx);
+	if (enumFn === null) return {};
+	const out = {};
+	for (let i = 0; i < 10; i += 1) {
+		probeSessionId(enumFn, S, `nt_${i}`, out);
+		probeSessionId(enumFn, S, `gpro_${i}`, out);
+	}
+	return out;
+}
+/** 探测单个 sessionId（getter 存在性 + getMsgService 调用结果）。 */
+function probeSessionId(enumFn, thisCtx, id, out) {
+	try {
+		const value = enumFn.call(thisCtx, id);
+		if (!value) return;
+		out[id] = probeSessionRecord(value);
+	} catch {}
+}
+/** 探测单个 session 记录（getter 存在性 + msgService 调用结果 + 方法面）。 */
+function probeSessionRecord(value) {
+	const rec = value;
+	const msg = tryMsgService(rec, value);
+	return {
+		hasMsgServiceGetter: typeof rec["getMsgService"] === "function",
+		msgServiceOk: msg.service !== null,
+		msgServiceMethods: msg.service ? listMethods(msg.service).length : 0,
+		msgError: msg.error,
+		methods: listMethods(value)
+	};
+}
+/** 尝试调用 getMsgService（失败记录错误，成功返回实例）。 */
+function tryMsgService(rec, thisCtx) {
+	try {
+		return {
+			service: rec["getMsgService"].call(thisCtx) ?? null,
+			error: null
+		};
+	} catch (e) {
+		return {
+			service: null,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** 取 NodeIQQNTWrapperSession.getNTWrapperSession 函数（无则 null）。 */
+function getNTWrapperSessionFn(ctx) {
+	const fn = ctx.exports.NodeIQQNTWrapperSession["getNTWrapperSession"];
+	return typeof fn === "function" ? fn : null;
+}
+/** 探测 startup 实例：start() + getSessionIdList()，提取 sessionIds（Map 值或键）。 */
+function probeStartupChain(created) {
+	const started = tryCall(created, "start");
+	const ids = tryCall(created, "getSessionIdList");
+	return {
+		start: started.ok ? { ok: true } : { error: started.error },
+		createdGetSessionIdList: ids.ok ? { value: serialize(ids.value) } : { error: ids.error },
+		sessionIds: extractSessionIds(ids)
+	};
+}
+/** 从 getSessionIdList 结果提取 sessionIds（Map 值或键优先）。 */
+function extractSessionIds(ids) {
+	if (!(ids.ok && ids.value instanceof Map)) return [];
+	const out = [];
+	for (const [k, v] of ids.value) out.push(typeof v === "string" ? v : String(k));
+	return out;
+}
+/** 用真实 sessionId 取主 session（getNTWrapperSession(nt_x)）并记录方法面。 */
+function probeSessionById(ctx, id) {
+	const fn = getNTWrapperSessionFn(ctx);
+	if (fn === null) return null;
+	try {
+		const value = fn.call(ctx.exports.NodeIQQNTWrapperSession, id);
+		return value ? {
+			methods: listMethods(value),
+			ownKeys: Object.getOwnPropertyNames(value)
+		} : null;
+	} catch (e) {
+		return { error: e instanceof Error ? e.message : String(e) };
+	}
+}
+/** 兜底：候选名字 getNTWrapperSession（无 Map 数据时）。 */
+function probeByNameFallback(ctx) {
+	const candidates = [
+		"main",
+		"primary",
+		"session1",
+		"default",
+		""
+	];
+	const getResults = {};
+	for (const name of candidates) getResults[name === "" ? "<empty>" : name] = probeSessionByName(ctx, name);
+	return getResults;
+}
+/** 探测单个候选名（getNTWrapperSession(name)，记录方法面或错误）。 */
+function probeSessionByName(ctx, name) {
+	try {
+		const fn = getNTWrapperSessionFn(ctx);
+		if (fn === null) return null;
+		const value = fn.call(ctx.exports.NodeIQQNTWrapperSession, name);
+		return value ? {
+			methods: listMethods(value),
+			ownKeys: Object.getOwnPropertyNames(value)
+		} : null;
+	} catch (e) {
+		return { error: e instanceof Error ? e.message : String(e) };
+	}
+}
+/** 探测 startup session 链路：create() → start() → getSessionIdList → getNTWrapperSession。 */
+function probeStartup(ctx) {
+	const startup = ctx.exports.NodeIQQNTStartupSessionWrapper;
+	if (startup === null || typeof startup.create !== "function") return null;
+	const out = { staticMethods: listMethods(startup) };
+	const created = tryCall(startup, "create");
+	out["create"] = created.ok ? {
+		methods: created.value ? listMethods(created.value) : [],
+		value: serialize(created.value)
+	} : { error: created.error };
+	if (created.ok && created.value) Object.assign(out, probeCreatedChain(ctx, created.value));
+	out["enumSessionIds"] = enumerateSessionIds(ctx);
+	if (out["sessionIds"] === void 0) out["getNTWrapperSession"] = probeByNameFallback(ctx);
+	return out;
+}
+/** 探测 create 后的实例链：start / getSessionIdList / 主 session。 */
+function probeCreatedChain(ctx, created) {
+	const chain = probeStartupChain(created);
+	const out = {
+		start: chain.start,
+		createdGetSessionIdList: chain.createdGetSessionIdList,
+		sessionIds: chain.sessionIds
+	};
+	const mainId = findMainProbeId(chain.sessionIds);
+	if (mainId !== void 0) {
+		out["mainSessionId"] = mainId;
+		out["mainSession"] = probeSessionById(ctx, mainId);
+	}
+	return out;
+}
+/** 选主 sessionId（nt_ 前缀优先，否则第一个）。 */
+function findMainProbeId(sessionIds) {
+	return sessionIds.find((id) => id.startsWith("nt_")) ?? sessionIds[0];
+}
+/** 探测 session 与 service 方法（优先复用 QQ 主 session）。 */
+function probeSession(ctx) {
+	const out = {};
+	const session = pickProbeSession(ctx, out);
+	out["session"] = session ? {
+		methods: listMethods(session),
+		ownKeys: Object.getOwnPropertyNames(session)
+	} : null;
+	if (session !== null && session !== void 0) out["services"] = collectServiceGetters(session);
+	return out;
+}
+/** 选探测目标 session：优先 QQ 主 session（getMainSession），回退 ctx.session。 */
+function pickProbeSession(ctx, out) {
+	try {
+		const main = getMainSession(ctx);
+		if (main !== null) {
+			out["sessionSource"] = "mainSession(getNTWrapperSession)";
+			return main;
+		}
+	} catch {}
+	if (ctx.session !== null) {
+		out["sessionSource"] = "own-create";
+		return ctx.session;
+	}
+	return null;
+}
+/** 收集 session 的 get*Service getter 方法面与返回形状。 */
+function collectServiceGetters(session) {
+	const getters = listMethods(session).filter((m) => m.startsWith("get") && m.endsWith("Service"));
+	const services = {};
+	for (const getter of getters) services[getter] = probeServiceGetter(session, getter);
+	return services;
+}
+/** 探测单个 getter：成功记录方法面/形状，失败记录错误。 */
+function probeServiceGetter(session, getter) {
+	const call = tryCall(session, getter);
+	if (!(call.ok && call.value)) return {
+		error: call.error ?? "null/undefined",
+		ok: call.ok
+	};
+	const methods = listMethods(call.value);
+	return {
+		methods,
+		ownKeys: Object.getOwnPropertyNames(call.value).slice(0, 20),
+		shapes: shapeKeyGetters(call.value, methods)
+	};
+}
+/**
+* 探测 wrapper 运行时：dump session 方法与各 service 方法到 JSON。
+* 返回探测结果对象；同时写文件（NAPUTO_CFG_DIR/<file>，默认 napuketto-probe.json）。
+*/
+function probeRuntime(ctx, file = "napuketto-probe.json") {
+	const result = {
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		exports: listMethods(ctx.exports),
+		engineMethods: listMethods(ctx.engine),
+		exportCtors: probeExportCtors(ctx),
+		engineCalls: probeEngineCalls(ctx),
+		loginService: probeLoginService(ctx),
+		startup: probeStartup(ctx),
+		...probeSession(ctx)
+	};
+	try {
+		const dir = node_process.default.env["NAPUTO_CFG_DIR"] ?? node_process.default.cwd();
+		(0, node_fs.mkdirSync)(dir, { recursive: true });
+		const full = (0, node_path.join)(dir, file);
+		(0, node_fs.writeFileSync)(full, JSON.stringify(result, null, 2), "utf8");
+		result["probeFile"] = full;
+	} catch (e) {
+		result["probeFileError"] = e instanceof Error ? e.message : String(e);
+	}
+	return result;
+}
+//#endregion
+//#region src/wrapper/wrapper-version.ts
+/**
+* QQ 安装目录探测（ADR-018）
+*
+* wrapper.node 路径随 QQ 版本变化：`<安装目录>/versions/<版本>/resources/app/wrapper.node`。
+* 加载前必须知道版本（登录握手参数 appid/qua 与版本强相关）。
+*
+* 已实测确认（2026-08-05，QQ 9.9.31-49919）：
+* - 目录结构：versions/<9.9.31-49919>/resources/app/wrapper.node
+* - 版本信息在 versions/<版本>/resources/app/package.json（name=qq-chat / version / buildVersion）
+* - wrapper.node 是 C++ ABI 模块（非 N-API），导出 INTSessionShell 等符号
+*/
+/** 从 versions 目录读取版本 package.json（拿 name/version/buildVersion）。 */
+function readVersionPackage(installDir, version) {
+	const pkgPath = (0, node_path.join)(installDir, "versions", version, "resources", "app", "package.json");
+	if (!(0, node_fs.existsSync)(pkgPath)) throw kernelError(`QQ 版本目录缺少 package.json: ${pkgPath}`, "NOT_FOUND");
+	try {
+		const raw = JSON.parse((0, node_fs.readFileSync)(pkgPath, "utf8"));
+		return {
+			name: raw.name ?? "",
+			version: raw.version ?? "",
+			...raw.buildVersion !== void 0 ? { buildVersion: raw.buildVersion } : {}
+		};
+	} catch (cause) {
+		throw kernelError(`QQ 版本 package.json 解析失败: ${pkgPath}`, "INVALID_PARAM", { cause });
+	}
+}
+/** 解析 wrapper.node 绝对路径（按 ADR-018 目录约定）。 */
+function resolveWrapperPath(installDir, version) {
+	return (0, node_path.join)(installDir, "versions", version, "resources", "app", "wrapper.node");
+}
+/**
+* 探测指定版本信息（校验 wrapper.node 存在）。
+* 版本号不匹配目录时抛 NOT_FOUND（明确失败而非静默）。
+*/
+function resolveQQVersion(installDir, version) {
+	const wrapperPath = resolveWrapperPath(installDir, version);
+	if (!(0, node_fs.existsSync)(wrapperPath)) throw kernelError(`未找到 wrapper.node: ${wrapperPath}`, "NOT_FOUND");
+	const pkg = readVersionPackage(installDir, version);
+	return {
+		fullVersion: pkg.version || version,
+		buildVersion: pkg.buildVersion ?? "",
+		wrapperPath,
+		appid: "",
+		qua: ""
+	};
+}
+/** 扫描 versions 目录，取可加载的版本列表（按目录名倒序，最新在前）。 */
+function listQQVersions(installDir) {
+	const versionsDir = (0, node_path.join)(installDir, "versions");
+	if (!(0, node_fs.existsSync)(versionsDir)) return [];
+	return (0, node_fs.readdirSync)(versionsDir).filter((name) => {
+		const full = (0, node_path.join)(versionsDir, name);
+		return (0, node_fs.statSync)(full).isDirectory() && (0, node_fs.existsSync)((0, node_path.join)(full, "resources", "app", "wrapper.node"));
+	}).sort().reverse();
+}
+//#endregion
+exports.ChatType = ChatType;
+exports.ConfigBase = ConfigBase;
+exports.DEFAULT_DATA_ROOT_NAME = DEFAULT_DATA_ROOT_NAME;
+exports.ElementType = ElementType;
+exports.FriendApi = FriendApi;
+exports.GrayTipSubType = GrayTipSubType;
+exports.GroupApi = GroupApi;
+exports.GroupBridge = GroupBridge;
+exports.GroupCache = GroupCache;
+exports.GroupListUpdateType = GroupListUpdateType;
+exports.GroupNotifyApi = GroupNotifyApi;
+exports.GroupNotifyMsgStatus = GroupNotifyMsgStatus;
+exports.GroupNotifyMsgType = GroupNotifyMsgType;
+exports.KERNEL_ERROR_CODES = KERNEL_ERROR_CODES;
+exports.KernelError = KernelError;
+exports.MAIN_CONFIG_FILE = MAIN_CONFIG_FILE;
+exports.MsgApi = MsgApi;
+exports.MsgBridge = MsgBridge;
+exports.NTEventChannel = NTEventChannel;
+exports.NTGroupMemberRole = NTGroupMemberRole;
+exports.NTGroupRequestOperateTypes = NTGroupRequestOperateTypes;
+exports.NapukettoCore = NapukettoCore;
+exports.PathWrapper = PathWrapper;
+exports.ProfileApi = ProfileApi;
+exports.ProfileLikeApi = ProfileLikeApi;
+exports.QrLoginSession = QrLoginSession;
+exports.RichMediaApi = RichMediaApi;
+exports.TicketApi = TicketApi;
+exports.TipGroupElementType = TipGroupElementType;
+exports.WebApi = WebApi;
+exports.WebHonorType = WebHonorType;
+exports.buildEngineConfig = buildEngineConfig;
+exports.buildLoginConfig = buildLoginConfig;
+exports.buildSessionConfig = buildSessionConfig;
+exports.createCoreContext = createCoreContext;
+exports.createLifecycleSessionListener = createSessionListener;
+exports.createLogger = createLogger;
+exports.createLoginListener = createLoginListener;
+exports.createSession = createSession;
+exports.createSessionListener = createSessionListener;
+exports.createWrapper = createWrapper;
+exports.electronProcessType = electronProcessType;
+exports.getExistingSession = getExistingSession;
+exports.getMainSession = getMainSession;
+exports.initAndStartSession = initAndStartSession;
+exports.initEngine = initEngine;
+exports.initSession = initSession;
+exports.isKernelError = isKernelError;
+exports.kernelError = kernelError;
+exports.listLoginAccounts = listLoginAccounts;
+exports.listQQVersions = listQQVersions;
+exports.parseAppidFromMajor = parseAppidFromMajor;
+exports.parseToml = parseToml;
+exports.probeRuntime = probeRuntime;
+exports.quickLogin = quickLogin;
+exports.resolveAppidQua = resolveAppidQua;
+exports.resolveConfigPath = resolveConfigPath;
+exports.resolveDataRoot = resolveDataRoot;
+exports.resolveQQVersion = resolveQQVersion;
+exports.resolveQqGlobalPath = resolveQqGlobalPath;
+exports.resolveQqUserDataRoot = resolveQqUserDataRoot;
+exports.resolveWrapperPath = resolveWrapperPath;
+exports.startNapuketto = startNapuketto;
+exports.startSession = startSession;
+exports.stringifyToml = stringifyToml;
+exports.toCanonicalElements = toCanonicalElements;
+exports.toSendElements = toSendElements;
+exports.waitForNetworkConnection = waitForNetworkConnection;
+exports.waitSessionReady = waitSessionReady;