@napuketto/kernel 0.0.1 → 0.0.2

package/dist/index.mjs

@@ -1,14 +1,14 @@
-import { get } from "node:https";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, extname, join, resolve } from "node:path";
+import { parse, stringify } from "smol-toml";
 import process from "node:process";
 import pino from "pino";
 import pinoPretty from "pino-pretty";
 import { homedir, hostname } from "node:os";
 import { fileURLToPath } from "node:url";
+import { get } from "node:https";
 import { EventEmitter } from "node:events";
-import { readFile, rename, writeFile } from "node:fs/promises";
-import { parse, stringify } from "smol-toml";
 //#region src/infra/errors.ts
 /**
 * 全部错误码集合。协议层映射表可据此推导：
@@ -32,14 +32,371 @@ var KernelError = class extends Error {
 		this.name = "KernelError";
 		this.code = code;
 	}
-};
-/** 便捷构造：`kernelError('消息不存在', 'NOT_FOUND', { cause })`。 */
-function kernelError(message, code = "UNKNOWN", options) {
-	return new KernelError(message, code, options);
+};
+/** 便捷构造：`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 (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 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));
+		mkdirSync(dirname(this.path), { recursive: true });
+		const tmpPath = `${this.path}.tmp`;
+		await writeFile(tmpPath, `${this.serialize(parsed)}\n`, "utf8");
+		await rename(tmpPath, this.path);
+		this.value = parsed;
+	}
+	/** 对象 → 文本（TOML/JSON）。 */
+	serialize(value) {
+		if (this.format === "toml") return stringify(value);
+		return JSON.stringify(value, null, 4);
+	}
+	/** 文本 → 对象（TOML/JSON）。 */
+	deserialize(raw) {
+		if (this.format === "toml") return 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 parse(text);
+}
+/** 对象 → TOML 文本（config init 生成全局配置文件等场景）。 */
+function stringifyToml(value) {
+	return 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: pinoPretty({
+		colorize: true,
+		translateTime: "SYS:HH:MM:ss.l",
+		singleLine: false,
+		destination: process.stdout
+	}) });
+	if (file) {
+		mkdirSync(dirname(file), { recursive: true });
+		streams.push({ stream: pino.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: process.pid,
+		...base
+	};
+	let stream;
+	if (streams.length === 1) stream = toSingle(streams);
+	else stream = pino.multistream(streams);
+	return pino(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 homedir();
+	if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+	return p;
+}
+/**
+* 项目根查找：入口模块向上找 `pnpm-workspace.yaml`（monorepo 开发场景，即仓库根）→
+* cwd 向上找 `pnpm-workspace.yaml` / `package.json`（发布后用户项目）→ undefined（兜底）。
+*/
+function resolveProjectRoot() {
+	const moduleRoot = findProjectRoot(dirname(fileURLToPath(import.meta.url)), "pnpm-workspace.yaml");
+	if (moduleRoot !== void 0) return moduleRoot;
+	return findProjectRoot(process.cwd(), "pnpm-workspace.yaml") ?? findProjectRoot(process.cwd(), "package.json");
+}
+/**
+* 解析数据根：显式参数 > 环境变量 > `<项目根>/.napuketto`（默认）> 用户目录兜底（裸脚本）。
+* 支持 `~` 前缀（展开为用户主目录）与相对路径（相对 cwd 解析）。
+* 返回绝对路径。独立导出便于 cli / 探测脚本复用。
+*/
+function resolveDataRoot(dataRoot) {
+	const explicit = dataRoot ?? process.env["NAPKETTO_DATA"];
+	if (explicit !== void 0 && explicit !== "") return resolve(expandTilde(explicit));
+	const projectRoot = resolveProjectRoot();
+	if (projectRoot !== void 0) return join(projectRoot, DEFAULT_DATA_ROOT_NAME);
+	return join(homedir(), DEFAULT_DATA_ROOT_NAME);
+}
+/** 向上查找含标志文件的目录（项目根探测：monorepo 根 / 用户项目根）。 */
+function findProjectRoot(startDir, marker) {
+	let dir = startDir;
+	for (;;) {
+		if (existsSync(join(dir, marker))) return dir;
+		const parent = 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 = process.env["NAPKETTO_CONFIG"];
+	if (explicit !== void 0 && explicit !== "") return resolve(explicit);
+	const projectRoot = resolveProjectRoot();
+	if (projectRoot !== void 0) return join(projectRoot, MAIN_CONFIG_FILE);
+	return 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 = join(root, opts.account);
+		else this.accountDir = root;
+		this.configDir = join(this.accountDir, "config");
+		this.logsDir = join(this.accountDir, "logs");
+		this.cacheDir = join(this.accountDir, "cache");
+	}
+	/** 递归创建全部目录，启动装配时调用一次。 */
+	ensure() {
+		for (const dir of [
+			this.configDir,
+			this.logsDir,
+			this.cacheDir
+		]) mkdirSync(dir, { recursive: true });
+	}
+	/** 账号目录内的文件路径（如 `file('config', 'napuketto.json')`）。 */
+	file(...segments) {
+		return join(this.accountDir, ...segments);
+	}
+	/**
+	* 清空缓存目录（clean_cache 动作经注入回调消费）。
+	* 只删除 cacheDir 下的条目，保留目录本身。
+	*/
+	clearCache() {
+		let entries;
+		try {
+			entries = readdirSync(this.cacheDir);
+		} catch {
+			return;
+		}
+		for (const entry of entries) rmSync(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";
 }
-/** 类型守卫：协议层 catch 统一映射时区分 KernelError 与意外错误。 */
-function isKernelError(err) {
-	return err instanceof KernelError;
+/** 原生 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
@@ -51,11 +408,6 @@ function isKernelError(err) {
 * （getBuddyReq / approvalFriendRequest / setBuddyRemark / delBuddy /
 * getDoubtBuddyReq / approvalDoubtBuddyReq）。
 */
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap$3(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
-}
 /** 好友 API：从 session 拿 buddy service，包装成语义化方法。 */
 var FriendApi = class {
 	service;
@@ -126,7 +478,7 @@ var FriendApi = class {
 	/** 好友申请列表（set_friend_add_request 应答前查找匹配项）。 */
 	async getBuddyReqList() {
 		const raw = await this.service.getBuddyReq();
-		unwrap$3("getBuddyReq", raw.result, raw.errMsg);
+		unwrap("getBuddyReq", raw.result, raw.errMsg);
 		return raw.buddyReqs ?? [];
 	}
 	/** 应答好友申请（accept=true 同意；remark 由调用方另行 setFriendRemark）。 */
@@ -146,18 +498,17 @@ var FriendApi = class {
 	}
 	/** 删除好友（tempBlock=拉黑，tempBothDel=双向删除）。 */
 	async deleteFriend(uid, tempBlock = false, tempBothDel = false) {
-		const res = await this.service.delBuddy({
+		checkLooseResult("delBuddy", await this.service.delBuddy({
 			friendUid: uid,
 			tempBlock,
 			tempBothDel
-		});
-		if (res !== void 0 && res !== null && typeof res.result === "number" && res.result !== 0) throw kernelError(`delBuddy 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+		}));
 	}
 	/** 可疑好友申请列表（get_doubt_friends_add_request；uin 经 uidToUin 转换）。 */
 	async getDoubtFriendRequest(count) {
 		const reqId = String(Date.now());
 		const raw = await this.service.getDoubtBuddyReq(reqId, count, "");
-		unwrap$3("getDoubtBuddyReq", raw.result, raw.errMsg);
+		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));
@@ -226,6 +577,254 @@ const TipGroupElementType = {
 	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 = {
@@ -271,6 +870,36 @@ const NTGroupRequestOperateTypes = {
 	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 统一错误语义）
@@ -279,11 +908,6 @@ const NTGroupRequestOperateTypes = {
 * 方法面（P2-4 + P2-10）：群列表 / 群详情 / 成员列表 / 成员详情 / uin↔uid +
 * 群管操作（踢人 / 禁言 / 管理员 / 名片 / 群名 / 退群 / 精华消息 / @all 剩余）。
 */
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap$2(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
-}
 /** 群 API：从 session 拿 group service，包装成语义化方法。 */
 var GroupApi = class {
 	service;
@@ -300,7 +924,7 @@ var GroupApi = class {
 	/** 群列表（force=true 强制刷新，默认缓存）。 */
 	async getGroupList(force = false) {
 		const raw = await this.service.getGroupList(force);
-		if (raw.result !== 0) unwrap$2("getGroupList", raw.result, raw.errMsg);
+		if (raw.result !== 0) unwrap("getGroupList", raw.result, raw.errMsg);
 		const list = raw.groupList;
 		if (Array.isArray(list)) return list;
 		return [];
@@ -313,7 +937,7 @@ var GroupApi = class {
 	async getGroupInfo(groupCode) {
 		const raw = await this.service.getGroupDetailInfo(groupCode, 0);
 		const { result, errMsg } = raw;
-		if (typeof result === "number" && result !== 0) unwrap$2("getGroupDetailInfo", result, errMsg);
+		if (typeof result === "number" && result !== 0) unwrap("getGroupDetailInfo", result, errMsg);
 		if (result !== null && typeof result === "object") return result;
 		const detail = raw;
 		const candidate = detail.groupInfo ?? detail.detailInfo ?? detail.info;
@@ -330,7 +954,7 @@ var GroupApi = class {
 	async getGroupMemberInfo(groupCode, uids) {
 		if (uids.length === 0) return [];
 		const raw = await this.service.getMemberInfo(groupCode, uids, true);
-		unwrap$2("getMemberInfo", raw.result, raw.errMsg);
+		unwrap("getMemberInfo", raw.result, raw.errMsg);
 		const { infos } = raw;
 		if (infos instanceof Map) return [...infos.values()];
 		return [];
@@ -376,7 +1000,7 @@ var GroupApi = class {
 			kickMsg: reason
 		};
 		const raw = await this.service.kickMemberV2(req);
-		unwrap$2("kickMemberV2", raw.result, raw.errMsg);
+		unwrap("kickMemberV2", raw.result, raw.errMsg);
 	}
 	/** 成员禁言（duration 秒，0 解除禁言）。 */
 	async setMemberShutUp(groupCode, members) {
@@ -385,12 +1009,12 @@ var GroupApi = class {
 			uid: m.uid,
 			timeStamp: m.duration
 		})));
-		unwrap$2("setMemberShutUp", raw.result, raw.errMsg);
+		unwrap("setMemberShutUp", raw.result, raw.errMsg);
 	}
 	/** 全员禁言（enable=true 开启全群禁言）。 */
 	async setGroupShutUp(groupCode, enable) {
 		const raw = await this.service.setGroupShutUp(groupCode, enable);
-		unwrap$2("setGroupShutUp", raw.result, raw.errMsg);
+		unwrap("setGroupShutUp", raw.result, raw.errMsg);
 	}
 	/** 设置管理员（role=ADMIN 设管理，MEMBER 取消；void 语义乐观处理）。 */
 	setMemberRole(groupCode, uid, role) {
@@ -403,7 +1027,7 @@ var GroupApi = class {
 	/** 修改群名。 */
 	async modifyGroupName(groupCode, groupName) {
 		const raw = await this.service.modifyGroupName(groupCode, groupName, false);
-		unwrap$2("modifyGroupName", raw.result, raw.errMsg);
+		unwrap("modifyGroupName", raw.result, raw.errMsg);
 	}
 	/** 退群（needDeleteLocalMsg=is_dismiss：是否解散群，仅群主）。 */
 	async quitGroup(groupCode, needDeleteLocalMsg = false) {
@@ -411,7 +1035,7 @@ var GroupApi = class {
 			groupCode,
 			needDeleteLocalMsg
 		});
-		unwrap$2("quitGroupV2", raw.result, raw.errMsg);
+		unwrap("quitGroupV2", raw.result, raw.errMsg);
 	}
 	/** 设置精华消息（msgId 经 msgService 取 msgSeq/msgRandom）。 */
 	async addGroupEssence(groupCode, msgId) {
@@ -428,7 +1052,7 @@ var GroupApi = class {
 			peerUid: groupCode
 		};
 		const raw = await this.msgService.getMsgsByMsgId(peer, [msgId]);
-		unwrap$2("getMsgsByMsgId", raw.result, raw.errMsg);
+		unwrap("getMsgsByMsgId", raw.result, raw.errMsg);
 		const msg = raw.msgList?.[0];
 		if (msg === void 0) throw kernelError(`消息 ${msgId} 不存在`, "NOT_FOUND");
 		const param = {
@@ -442,7 +1066,7 @@ var GroupApi = class {
 			label = "addGroupEssence";
 			res = await this.service.addGroupEssence(param);
 		} else res = await this.service.removeGroupEssence(param);
-		if (res !== void 0 && res !== null && typeof res.result === "number" && res.result !== 0) throw kernelError(`${label} 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+		checkLooseResult(label, res);
 	}
 	/** @all 剩余次数（get_group_at_all_remain）。 */
 	async getGroupRemainAtTimes(groupCode) {
@@ -464,11 +1088,6 @@ var GroupApi = class {
 * getSingleScreenNotifies / getGroupShutUpMemberList 的列表可能走 listener 回调，
 * 直接调用返回形状待探测校准：兼容 result 数组 / 字段 / 直接数组。
 */
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap$1(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
-}
 /** 群通知 API：从 session 拿 group service，包装成语义化方法。 */
 var GroupNotifyApi = class {
 	service;
@@ -484,7 +1103,7 @@ var GroupNotifyApi = class {
 	/** 禁言成员列表（get_group_shut_list）。 */
 	async getGroupShutUpMemberList(groupCode) {
 		const raw = await this.service.getGroupShutUpMemberList(groupCode);
-		if (raw.result !== 0) unwrap$1("getGroupShutUpMemberList", raw.result, raw.errMsg);
+		if (raw.result !== 0) unwrap("getGroupShutUpMemberList", raw.result, raw.errMsg);
 		return extractMemberList(raw.result);
 	}
 	/** 处理群请求（set_group_add_request 应答；approve=true 同意 / false 拒绝）。 */
@@ -493,276 +1112,37 @@ var GroupNotifyApi = class {
 		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/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
-		};
+		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 [];
 }
-/** 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");
+/** 从 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 out;
+	return [];
 }
 //#endregion
 //#region src/apis/msg.ts
@@ -774,17 +1154,6 @@ function toSendElements(elements) {
 *
 * 方法面（P2-1）：发送 / 撤回 / 拉历史 / 标记已读。group/friend 等后续 apis 同构。
 */
-/** 原生结果解包：result !== 0 抛 KernelError（errMsg 语义映射错误码）。 */
-function unwrapResult(label, raw) {
-	if (raw.result === 0) return;
-	const msg = raw.errMsg || "无错误详情";
-	let code = "UNKNOWN";
-	if (msg.includes("未登录") || msg.includes("login")) code = "NOT_LOGIN";
-	else if (msg.includes("无权限") || msg.includes("permission")) code = "PERMISSION_DENIED";
-	else if (msg.includes("不存在") || msg.includes("not found")) code = "NOT_FOUND";
-	else if (label === "sendMsg") code = "SEND_FAILED";
-	throw kernelError(`${label} 失败: ${msg}`, code);
-}
 /** 消息 API：从 session 拿 msg service，包装成语义化方法。 */
 var MsgApi = class {
 	service;
@@ -902,77 +1271,49 @@ var MsgApi = class {
 	}
 };
 //#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 = 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));
-	});
+//#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: infoSimple?.coreInfo ?? byUinSimple?.coreInfo,
+		baseInfo: infoSimple?.baseInfo ?? byUinSimple?.baseInfo,
+		vasInfo: infoSimple?.vasInfo ?? byUinSimple?.vasInfo,
+		commonExt: info.detail?.commonExt ?? byUin.detail?.commonExt,
+		status: infoSimple?.status?.status ?? byUinSimple?.status?.status
+	};
 }
-/** 解析 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;
+/** 扁平化两份详情 → 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
@@ -994,13 +1335,11 @@ var ProfileApi = class {
 	}
 	/** 设置个性签名（set_self_longnick）。 */
 	async setLongNick(longNick) {
-		const res = await this.service.setLongNick(longNick);
-		if (res !== void 0 && res !== null && typeof res.result === "number" && res.result !== 0) throw kernelError(`setLongNick 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+		checkLooseResult("setLongNick", await this.service.setLongNick(longNick));
 	}
 	/** 设置昵称（set_qq_profile）。 */
 	async setNickName(nickName) {
-		const res = await this.service.setNickName(nickName);
-		if (res !== void 0 && res !== null && typeof res.result === "number" && res.result !== 0) throw kernelError(`setNickName 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+		checkLooseResult("setNickName", await this.service.setNickName(nickName));
 	}
 	/** 设置头像（set_qq_avatar；filePath 为本地路径）。 */
 	async setHeader(filePath) {
@@ -1017,37 +1356,6 @@ var ProfileApi = class {
 		return flattenStrangerInfo(uin, uid, byUin, info);
 	}
 };
-/** 扁平化两份详情 → StrangerInfo（宽松取值，字段缺失给默认）。 */
-function flattenStrangerInfo(uin, uid, byUin, info) {
-	const coreInfo = info.detail?.simpleInfo?.coreInfo ?? byUin.detail?.simpleInfo?.coreInfo;
-	const baseInfo = info.detail?.simpleInfo?.baseInfo ?? byUin.detail?.simpleInfo?.baseInfo;
-	const vasInfo = info.detail?.simpleInfo?.vasInfo ?? byUin.detail?.simpleInfo?.vasInfo;
-	const commonExt = info.detail?.commonExt ?? byUin.detail?.commonExt;
-	const status = info.detail?.simpleInfo?.status?.status ?? 0;
-	return {
-		user_id: Number(uin),
-		uid,
-		nickname: coreInfo?.nick ?? "",
-		age: baseInfo?.age ?? 0,
-		qid: baseInfo?.qid ?? "",
-		qq_level: commonExt?.qqLevel ?? 0,
-		sex: mapSex(baseInfo?.sex),
-		long_nick: baseInfo?.longNick ?? "",
-		reg_time: commonExt?.regTime ?? 0,
-		is_vip: vasInfo?.svipFlag ?? false,
-		is_years_vip: vasInfo?.yearVipFlag ?? false,
-		vip_level: vasInfo?.vipLevel ?? 0,
-		remark: coreInfo?.remark ?? "",
-		status,
-		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-like.ts
 /**
@@ -1096,11 +1404,6 @@ const HIDE_ONLINEDOC_FOLDER = 0;
 const DEFAULT_FILE_COUNT = 50;
 /** 空间查询文件数量（单条即可）。 */
 const SPACE_QUERY_FILE_COUNT = 1;
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
-}
 /** 富媒体 API：从 session 拿 rich media service，包装成语义化方法。 */
 var RichMediaApi = class {
 	service;
@@ -1183,21 +1486,94 @@ var RichMediaApi = class {
 		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") {
-		const obj = result;
-		if (Array.isArray(obj.items)) return obj.items;
-		if (Array.isArray(obj.fileList)) return obj.fileList;
-		if (Array.isArray(obj.list)) return obj.list;
-	}
-	return [];
+/** 从 getGroupFileList 返回提取文件列表（兼容数组 / { items } / { fileList }）。 */
+function extractFileList(result) {
+	if (Array.isArray(result)) return result;
+	if (result !== null && typeof result === "object") {
+		const obj = result;
+		if (Array.isArray(obj.items)) return obj.items;
+		if (Array.isArray(obj.fileList)) return obj.fileList;
+		if (Array.isArray(obj.list)) return obj.list;
+	}
+	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 = 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));
+	});
 }
-/** 统计文件数量（兼容数组 / { items }）。 */
-function countGroupFiles(result) {
-	if (Array.isArray(result)) return result.filter((item) => item.fileInfo !== void 0).length;
-	return 0;
+/** 解析 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
@@ -1280,29 +1656,33 @@ var WebApi = class {
 			type: String(type)
 		}).toString(), cookie);
 		if (text === null) return [];
-		const match = /window\.__INITIAL_STATE__=(.*?);/.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;
+		return parseHonorList(text, type);
 	}
 };
+/** 从 honorlist 页面提取 __INITIAL_STATE__ → 荣誉列表（解析失败返回空）。 */
+function parseHonorList(text, type) {
+	const match = /window\.__INITIAL_STATE__=(.*?);/.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 {
@@ -1405,15 +1785,6 @@ var MsgBridge = class {
 	}
 };
 //#endregion
-//#region src/types/listeners/group.ts
-/** 群列表更新类型（说明书参考，值待探测校准）。 */
-const GroupListUpdateType = {
-	/** 全量更新（groupList 为完整列表）。 */
-	ALL: 0,
-	/** 增量更新（合并到现有缓存）。 */
-	PARTIAL: 1
-};
-//#endregion
 //#region src/cache/group-cache.ts
 /**
 * 群/成员缓存：事件主动维护 + 查询惰性回填。
@@ -1566,181 +1937,6 @@ function createCoreContext(opts) {
 	};
 }
 //#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: pinoPretty({
-		colorize: true,
-		translateTime: "SYS:HH:MM:ss.l",
-		singleLine: false,
-		destination: process.stdout
-	}) });
-	if (file) {
-		mkdirSync(dirname(file), { recursive: true });
-		streams.push({ stream: pino.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: process.pid,
-		...base
-	};
-	let stream;
-	if (streams.length === 1) stream = toSingle(streams);
-	else stream = pino.multistream(streams);
-	return pino(pinoOptions, stream);
-}
-//#endregion
-//#region src/infra/paths.ts
-/**
-* 数据目录布局（ADR-016，2026-08-07 修订：配置文件独立于数据根）
-*
-* ```
-* <数据根>/<qq号>/             # 每账号独立目录（ADR-015 多账号前提）
-* ├── config/                  # 各账号独立配置（历史产物，协议段已走 seed）
-* ├── logs/                    # pino 文件日志
-* └── cache/                   # 临时文件、媒体缓存
-*
-* <项目根>/napuketto.toml      # 全局配置文件（2026-08-07 用户拍板：放项目根目录）
-* ```
-*
-* 数据根优先级：cli `--data-dir`（显式参数）> `NAPKETTO_DATA` 环境变量 > `~/.napuketto`（默认）。
-* 配置文件路径见 `resolveConfigPath`（项目根探测，与数据根解耦）。
-*/
-/** 默认数据根目录名（用户目录下，程序目录可能只读，见 ADR-016）。 */
-const DEFAULT_DATA_ROOT_NAME = ".napuketto";
-/** 全局配置文件名。 */
-const MAIN_CONFIG_FILE = "napuketto.toml";
-/**
-* 解析数据根：显式参数 > 环境变量 > 用户目录默认。
-* 返回绝对路径。独立导出便于 cli / 探测脚本复用。
-*/
-function resolveDataRoot(dataRoot) {
-	const explicit = dataRoot ?? process.env["NAPKETTO_DATA"];
-	if (explicit) return resolve(explicit);
-	return join(homedir(), DEFAULT_DATA_ROOT_NAME);
-}
-/** 向上查找含标志文件的目录（项目根探测：monorepo 根 / 用户项目根）。 */
-function findProjectRoot(startDir, marker) {
-	let dir = startDir;
-	for (;;) {
-		if (existsSync(join(dir, marker))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return;
-		dir = parent;
-	}
-}
-/**
-* 全局配置文件路径解析（2026-08-07 用户拍板：**配置文件放项目根目录，
-* 数据仍按数据根组织**——数据根只承载账号目录/日志/缓存/QQ 数据）。
-*
-* 优先级：
-*  1. `NAPKETTO_CONFIG` 环境变量（显式指定完整路径，任意场景可用）
-*  2. 入口模块向上找 `pnpm-workspace.yaml`（monorepo 开发场景，即项目根）
-*  3. 运行目录（cwd）向上找 `pnpm-workspace.yaml` / `package.json`（发布后用户项目）
-*  4. 数据根兜底 `<dataRoot>/napuketto.toml`（旧行为兼容）
-*
-* 返回绝对路径。独立导出便于 cli / loader 装配链复用。
-*/
-function resolveConfigPath(opts = {}) {
-	const explicit = process.env["NAPKETTO_CONFIG"];
-	if (explicit !== void 0 && explicit !== "") return resolve(explicit);
-	const moduleRoot = findProjectRoot(dirname(fileURLToPath(import.meta.url)), "pnpm-workspace.yaml");
-	if (moduleRoot !== void 0) return join(moduleRoot, MAIN_CONFIG_FILE);
-	const cwdRoot = findProjectRoot(process.cwd(), "pnpm-workspace.yaml") ?? findProjectRoot(process.cwd(), "package.json");
-	if (cwdRoot !== void 0) return join(cwdRoot, MAIN_CONFIG_FILE);
-	return 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 = join(root, opts.account);
-		else this.accountDir = root;
-		this.configDir = join(this.accountDir, "config");
-		this.logsDir = join(this.accountDir, "logs");
-		this.cacheDir = join(this.accountDir, "cache");
-	}
-	/** 递归创建全部目录，启动装配时调用一次。 */
-	ensure() {
-		for (const dir of [
-			this.configDir,
-			this.logsDir,
-			this.cacheDir
-		]) mkdirSync(dir, { recursive: true });
-	}
-	/** 账号目录内的文件路径（如 `file('config', 'napuketto.json')`）。 */
-	file(...segments) {
-		return join(this.accountDir, ...segments);
-	}
-	/**
-	* 清空缓存目录（clean_cache 动作经注入回调消费）。
-	* 只删除 cacheDir 下的条目，保留目录本身。
-	*/
-	clearCache() {
-		let entries;
-		try {
-			entries = readdirSync(this.cacheDir);
-		} catch {
-			return;
-		}
-		for (const entry of entries) rmSync(join(this.cacheDir, entry), {
-			recursive: true,
-			force: true
-		});
-	}
-};
-//#endregion
 //#region src/wrapper/wrapper-adapters.ts
 /** NAPI 回调占位（方法存在即可被反射调用，无副作用）。 */
 const noop = () => void 0;
@@ -1791,26 +1987,9 @@ function createLoginListener() {
 	return {};
 }
 //#endregion
-//#region src/login/lifecycle.ts
+//#region src/login/wait.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 解耦）：
-*  - 配置装配（buildEngineConfig / buildLoginConfig / buildSessionConfig）→ wrapper-config.ts
-*  - NAPI 回调适配器（GlobalAdapter / DependsAdapter / DispatcherAdapter / listener 工厂）→ wrapper-adapters.ts
-*  - 本文件只保留流程编排：快速登录 + session 初始化 + init 完成信号等待。
+* 等待/延迟工具（login 模块共享，2026-08-08 克隆合并）
 */
 /** 等待条件满足（轮询，带超时）。 */
 function waitFor(predicate, timeoutMs, intervalMs = 500) {
@@ -1830,32 +2009,21 @@ function waitFor(predicate, timeoutMs, intervalMs = 500) {
 		tick();
 	});
 }
-/** session init 默认超时（毫秒）。 */
-const DEFAULT_INIT_TIMEOUT_MS = 15e3;
-/** session 就绪等待默认超时（毫秒）。 */
-const SESSION_READY_TIMEOUT_MS = 3e4;
-/** session 就绪轮询间隔（毫秒）。 */
-const SESSION_READY_POLL_MS = 1e3;
+/** 短延迟。 */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#region src/login/login-connect.ts
 /**
-* 等待 QQ 自己完成 session 初始化（framework 复用模式，2026-08-05 修正）。
+* 登录连接与快速登录（从 lifecycle.ts 拆分，2026-08-08 FTA 优化）
 *
-* 背景：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 已挂载）。
+* - waitForNetworkConnection：等 MSF 网络连接就绪（getMsfStatus() === 3）
+* - ensureLoginConnected：connect() → 等 onLoginConnected（自建宿主必需）
+* - quickLogin：历史账号快速登录（网络异常 1006511 等就绪后重试）
 */
-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");
-}
 /**
 * 网络状态（MSF）常量。
 * 3 = 已连接（NapCat waitForNetworkConnection 语义，自研描述）。
@@ -1871,6 +2039,8 @@ 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 刚拉起、
@@ -1931,41 +2101,21 @@ async function ensureLoginConnected(ctx, opts) {
 	});
 	await sleep(CONNECTION_SETTLE_MS);
 }
-/** 连接稳定缓冲（毫秒，p0-kernel-flow 实证值）。 */
-const CONNECTION_SETTLE_MS = 3e3;
-/** 短延迟。 */
-function sleep(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
 /**
-* 快速登录：遍历历史登录列表尝试。
-* P2-1：失败且错误为网络异常（1006511）时，等网络就绪后重试（最多 NETWORK_RETRY_MAX 次）。
+* 目标账号选择（2026-08-07 修复：显式 uin 不在列表时**报错**而非静默 fallback——
+* 之前会退到第一个可快速登录账号，导致 `-q <uin>` 实际登成别的号）。
 */
-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");
-	let target;
-	if (opts.uin !== void 0) {
-		target = items.find((i) => i.uin === opts.uin);
-		if (target === void 0) {
-			const available = items.map((i) => i.uin).join("、");
-			throw kernelError(`账号 ${opts.uin} 不在登录列表（可用：${available}）`, "NOT_FOUND");
-		}
-	} else {
-		target = items.find((i) => i.isQuickLogin);
-		if (target === void 0) {
-			const [first] = items;
-			target = first;
-		}
-	}
-	if (target === void 0) throw kernelError("无可用登录账号", "NOT_LOGIN");
-	return loginWithNetworkRetry(ctx, loginService, target, opts);
+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）。
@@ -1986,6 +2136,69 @@ async function loginWithNetworkRetry(ctx, loginService, target, opts) {
 	}
 	throw kernelError(`快速登录失败: ${lastErrMsg}`, "NOT_LOGIN");
 }
+/**
+* 快速登录：遍历历史登录列表尝试。
+* 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;
@@ -2200,36 +2413,6 @@ function findInObject(value) {
 	return null;
 }
 //#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/wrapper/wrapper-config.ts
 /**
 * wrapper 交互配置装配（纯函数，无状态）
@@ -2542,20 +2725,8 @@ function startNapuketto(options) {
 	const isSelfHost = electronProcessType() === void 0;
 	if (qqSession !== void 0 && qqSession !== null) ctx.session = qqSession;
 	else if (isSelfHost) createSession(ctx);
-	let qqGlobalPath = null;
-	if (electronProcessType() !== "browser") {
-		const root = resolveQqUserDataRoot(wrapperExports);
-		if (root !== null) qqGlobalPath = resolveQqGlobalPath(root);
-	}
-	initEngine(ctx, engineConfig ?? defaultEngineConfig(env ?? {}, qqGlobalPath ?? void 0));
-	if (qqLoginService !== void 0 && qqLoginService !== null) ctx.loginService = qqLoginService;
-	else try {
-		const loginSvcCtor = ctx.exports.NodeIKernelLoginService;
-		if (loginSvcCtor !== null && typeof loginSvcCtor.get === "function") ctx.loginService = loginSvcCtor.get();
-		else ctx.loginService = new ctx.exports.NodeIKernelLoginService();
-	} catch {
-		ctx.loginService = null;
-	}
+	initEngine(ctx, engineConfig ?? defaultEngineConfig(env ?? {}, resolveBootQqGlobalPath(ctx)));
+	resolveLoginService(ctx, qqLoginService);
 	if (qqSession !== void 0 && qqSession !== null) ctx.session = qqSession;
 	else if (!isSelfHost) createSession(ctx);
 	if (sessionConfig !== void 0) {
@@ -2564,6 +2735,37 @@ function startNapuketto(options) {
 	}
 	return ctx;
 }
+/**
+* 解析 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;
+	}
+	try {
+		const loginSvcCtor = ctx.exports.NodeIKernelLoginService;
+		if (loginSvcCtor !== null && typeof loginSvcCtor.get === "function") ctx.loginService = loginSvcCtor.get();
+		else ctx.loginService = new ctx.exports.NodeIKernelLoginService();
+	} catch {
+		ctx.loginService = null;
+	}
+}
 //#endregion
 //#region src/core.ts
 /**
@@ -2686,9 +2888,14 @@ var NapukettoCore = class NapukettoCore {
 		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 });
 		});
 		const startOpts = {};
 		if (opts.quickUin !== void 0) startOpts.quickUin = opts.quickUin;
@@ -2754,6 +2961,7 @@ var NTEventChannel = class {
 	serviceName;
 	emitter = new EventEmitter();
 	errorHandlers = /* @__PURE__ */ new Set();
+	anyHandlers = /* @__PURE__ */ new Set();
 	constructor(serviceName) {
 		this.serviceName = serviceName;
 		this.emitter.setMaxListeners(0);
@@ -2765,170 +2973,69 @@ var NTEventChannel = class {
 	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，保证「单个订阅者
-	* 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
-	*/
-	emit(event, ...args) {
-		const listeners = this.emitter.listeners(event);
-		for (const listener of listeners) try {
-			listener(...args);
-		} catch (err) {
-			for (const handler of this.errorHandlers) handler(err);
-		}
-	}
-	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
-	onError(handler) {
-		this.errorHandlers.add(handler);
-		return () => {
-			this.errorHandlers.delete(handler);
-		};
-	}
-};
-//#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 (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;
+			this.emitter.removeListener(event, handler);
+		};
 	}
 	/**
-	* 加载配置：
-	* - seed 存在 → 直接用 seed（已校验，不读文件；全局 TOML 分段装配方式）；
-	* - 文件缺失 → 写入默认值并落盘（首次运行自动生成），返回默认值；
-	* - 文件存在 → 读取 + 校验，更新内存，返回。
+	* 请求-响应桥：注册临时监听 → filter 命中 → resolve；超时自动清理并 reject。
+	* 替代魔法字符串事件名方案。
 	*/
-	async load() {
-		if (this.seed !== void 0) {
-			this.value = this.seed;
-			return this.value;
-		}
-		let raw;
-		try {
-			raw = await 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));
-		mkdirSync(dirname(this.path), { recursive: true });
-		const tmpPath = `${this.path}.tmp`;
-		await writeFile(tmpPath, `${this.serialize(parsed)}\n`, "utf8");
-		await rename(tmpPath, this.path);
-		this.value = parsed;
-	}
-	/** 对象 → 文本（TOML/JSON）。 */
-	serialize(value) {
-		if (this.format === "toml") return stringify(value);
-		return JSON.stringify(value, null, 4);
+	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);
+		});
 	}
-	/** 文本 → 对象（TOML/JSON）。 */
-	deserialize(raw) {
-		if (this.format === "toml") return parse(raw);
-		return JSON.parse(raw);
+	/**
+	* 类型化派发：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);
+		};
 	}
-	/** 反序列化 + schema 校验，错误统一包装为 KernelError。 */
-	parse(raw) {
-		let input;
-		try {
-			input = this.deserialize(raw);
+	emit(event, ...args) {
+		for (const anyHandler of this.anyHandlers) try {
+			anyHandler(event, ...args);
 		} catch (err) {
-			throw new KernelError(`配置文件 ${this.format.toUpperCase()} 解析失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+			for (const errorHandler of this.errorHandlers) errorHandler(err);
 		}
-		try {
-			return this.schema.parse(input);
+		const listeners = this.emitter.listeners(event);
+		for (const listener of listeners) try {
+			listener(...args);
 		} catch (err) {
-			throw new KernelError(`配置文件校验失败: ${this.path}`, "INVALID_PARAM", { cause: err });
+			for (const handler of this.errorHandlers) handler(err);
 		}
 	}
+	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
+	onError(handler) {
+		this.errorHandlers.add(handler);
+		return () => {
+			this.errorHandlers.delete(handler);
+		};
+	}
 };
-/** 解析 TOML 文本 → 对象（boot.cjs / 探测脚本等无 ConfigBase 场景复用）。 */
-function parseToml(text) {
-	return parse(text);
-}
-/** 对象 → TOML 文本（config init 生成全局配置文件等场景）。 */
-function stringifyToml(value) {
-	return stringify(value);
-}
 //#endregion
 //#region src/wrapper/session-resolver.ts
 /** 从 getSessionIdList 的 Map 提取主 sessionId（nt_ 前缀优先）。 */
@@ -2990,50 +3097,14 @@ function getMainSession(ctx) {
 	return null;
 }
 //#endregion
-//#region src/wrapper/probe.ts
+//#region src/wrapper/probe/probe-serialize.ts
 /**
-* 运行时反射探测（ADR-006 落地，P1-4）
-*
-* 注入链路打通后（2026-08-05），wrapper exports 是 QQ 已注册的单例。
-* 本模块在 **QQ 主进程内**反射枚举 session / service 的真实方法名与返回形状，
-* 产出 JSON 到 NAPUTO_CFG_DIR/napuketto-probe.json，作为 types/services/ 的权威来源。
+* 运行时反射探测的序列化工具（从 probe.ts 拆分，2026-08-08 FTA 优化）
 *
-* 用法：boot.cjs 在 NAPUTO_PROBE=1 时于 startNapuketto 后调用 probeRuntime(ctx)。
-* 产物是研究工具数据，类型层据此补全（自研描述，非移植）。
+* - serialize：深度受限序列化（BigInt 转字符串，Map/Set/Promise 展开，循环引用防护）
+* - tryShape：解析 service getter 返回形状
+* - shapeKeyGetters：探测 service 关键数据 getter 返回形状
 */
-/** 反射枚举一个对象原型链上的方法名（去重、去构造器）。 */
-function listMethods(obj) {
-	if (obj === null || obj === void 0) return [];
-	const names = /* @__PURE__ */ new Set();
-	let proto = Object.getPrototypeOf(obj);
-	while (proto && proto !== Object.prototype && proto !== Function.prototype) {
-		for (const name of Object.getOwnPropertyNames(proto)) if (name !== "constructor") names.add(name);
-		proto = Object.getPrototypeOf(proto);
-	}
-	for (const name of Object.getOwnPropertyNames(obj)) if (name !== "constructor") names.add(name);
-	return [...names].sort();
-}
-/** 安全调用：尝试调用方法拿返回值，失败记录错误（不中断探测）。 */
-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
-		};
-	}
-}
 /** 序列化深度上限（循环引用/深层对象防护）。 */
 const MAX_SERIALIZE_DEPTH = 4;
 /** 数组序列化条数上限。 */
@@ -3048,34 +3119,52 @@ function serialize(value, depth = 0) {
 	if (typeof value !== "object") return value;
 	if (depth > MAX_SERIALIZE_DEPTH) return "[depth-limit]";
 	try {
-		if (Array.isArray(value)) return value.slice(0, MAX_ARRAY_ITEMS).map((v) => serialize(v, depth + 1));
-		if (value instanceof Map) {
-			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
-			};
-		}
-		if (value instanceof Set) return {
-			kind: "Set",
-			size: value.size,
-			values: [...value].slice(0, MAX_ARRAY_ITEMS).map((v) => serialize(v, depth + 1))
-		};
-		if (typeof value.then === "function") return "[Promise]";
-		const out = {};
-		for (const key of Object.keys(value).slice(0, MAX_OBJECT_KEYS)) out[key] = serialize(value[key], depth + 1);
-		return out;
+		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 {
@@ -3097,6 +3186,49 @@ function shapeKeyGetters(session, serviceMethods) {
 	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();
+	let proto = Object.getPrototypeOf(obj);
+	while (proto && proto !== Object.prototype && proto !== Function.prototype) {
+		for (const name of Object.getOwnPropertyNames(proto)) if (name !== "constructor") names.add(name);
+		proto = Object.getPrototypeOf(proto);
+	}
+	for (const name of Object.getOwnPropertyNames(obj)) if (name !== "constructor") names.add(name);
+	return [...names].sort();
+}
+/** 安全调用：尝试调用方法拿返回值，失败记录错误（不中断探测）。 */
+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 = [
@@ -3154,6 +3286,22 @@ function probeLoginService(ctx) {
 	]) if (typeof inst.value[m] === "function") out[m] = tryShape(inst.value, m);
 	return out;
 }
+//#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;
@@ -3184,47 +3332,38 @@ function enumerateSessionIds(ctx) {
 	} catch {}
 	return out;
 }
-/** 探测 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) {
-		const started = tryCall(created.value, "start");
-		out["start"] = started.ok ? { ok: true } : { error: started.error };
-		const ids = tryCall(created.value, "getSessionIdList");
-		const idsValue = ids.ok ? serialize(ids.value) : null;
-		out["createdGetSessionIdList"] = ids.ok ? { value: idsValue } : { error: ids.error };
-		const foundIds = [];
-		if (ids.ok && ids.value instanceof Map) for (const [k, v] of ids.value) {
-			const id = typeof v === "string" ? v : String(k);
-			foundIds.push(id);
-		}
-		out["sessionIds"] = foundIds;
-		if (foundIds.length > 0) {
-			const mainId = foundIds.find((id) => id.startsWith("nt_")) ?? foundIds[0];
-			out["mainSessionId"] = mainId;
-			const S = ctx.exports.NodeIQQNTWrapperSession;
-			const fn = S["getNTWrapperSession"];
-			if (typeof fn === "function" && mainId !== void 0) try {
-				const value = fn.call(S, mainId);
-				out["mainSession"] = value ? {
-					methods: listMethods(value),
-					ownKeys: Object.getOwnPropertyNames(value)
-				} : null;
-			} catch (e) {
-				out["mainSession"] = { error: e instanceof Error ? e.message : String(e) };
-			}
-			out["enumSessionIds"] = enumerateSessionIds(ctx);
-			return out;
-		}
+/** 探测 startup 实例：start() + getSessionIdList()，提取 sessionIds（Map 值或键）。 */
+function probeStartupChain(created) {
+	const started = tryCall(created, "start");
+	const ids = tryCall(created, "getSessionIdList");
+	const sessionIds = [];
+	if (ids.ok && ids.value instanceof Map) for (const [k, v] of ids.value) {
+		const id = typeof v === "string" ? v : String(k);
+		sessionIds.push(id);
 	}
-	out["enumSessionIds"] = enumerateSessionIds(ctx);
+	return {
+		start: started.ok ? { ok: true } : { error: started.error },
+		createdGetSessionIdList: ids.ok ? { value: serialize(ids.value) } : { error: ids.error },
+		sessionIds
+	};
+}
+/** 用真实 sessionId 取主 session（getNTWrapperSession(nt_x)）并记录方法面。 */
+function probeSessionById(ctx, id) {
+	const S = ctx.exports.NodeIQQNTWrapperSession;
+	const fn = S["getNTWrapperSession"];
+	if (typeof fn !== "function") return null;
+	try {
+		const value = fn.call(S, 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 S = ctx.exports.NodeIQQNTWrapperSession;
 	const candidates = [
 		"main",
@@ -3244,7 +3383,31 @@ function probeStartup(ctx) {
 	} catch (e) {
 		getResults[name === "" ? "<empty>" : name] = { error: e instanceof Error ? e.message : String(e) };
 	}
-	out["getNTWrapperSession"] = getResults;
+	return getResults;
+}
+/** 探测 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) {
+		const chain = probeStartupChain(created.value);
+		out["start"] = chain.start;
+		out["createdGetSessionIdList"] = chain.createdGetSessionIdList;
+		out["sessionIds"] = chain.sessionIds;
+		const mainId = chain.sessionIds.find((id) => id.startsWith("nt_")) ?? chain.sessionIds[0];
+		if (mainId !== void 0) {
+			out["mainSessionId"] = mainId;
+			out["mainSession"] = probeSessionById(ctx, mainId);
+		}
+	}
+	out["enumSessionIds"] = enumerateSessionIds(ctx);
+	if (out["sessionIds"] === void 0) out["getNTWrapperSession"] = probeByNameFallback(ctx);
 	return out;
 }
 /** 探测 session 与 service 方法（优先复用 QQ 主 session）。 */