@napuketto/kernel 0.0.1 → 0.0.3

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
 /**
 * 全部错误码集合。协议层映射表可据此推导：
@@ -42,489 +42,549 @@ function isKernelError(err) {
 	return err instanceof KernelError;
 }
 //#endregion
-//#region src/apis/friend.ts
+//#region src/infra/config.ts
 /**
-* FriendApi：好友语义化 API（ADR-009 统一错误语义）
+* 配置基类（ADR-012）
 *
-* 内部解包原生返回：成功返回纯业务值，失败抛 KernelError。
-* 方法面（P2-4 + P2-11）：好友列表（uid + 昵称/备注）+ 好友请求
-* （getBuddyReq / approvalFriendRequest / setBuddyRemark / delBuddy /
-* getDoubtBuddyReq / approvalDoubtBuddyReq）。
+* 读文件 → 校验 → 内存对象 → 变更写回。支持 **JSON / TOML** 两种文本格式
+* （按扩展名推断：.toml → TOML（smol-toml），其余 → JSON）。
+*
+* kernel 不依赖 zod：只依赖校验器的最小 `parse` 形状（`ConfigSchema`），
+* 协议包的 zod schema 天然满足；kernel 主配置用手写校验器包装。
+* 协议配置 schema 在各自协议包，见各包 docs/design.md。
 */
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap$3(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
+/** 按扩展名推断格式（.toml → toml，其余 → json）。 */
+function inferFormat(path) {
+	if (extname(path).toLowerCase() === ".toml") return "toml";
+	return "json";
 }
-/** 好友 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;
+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_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
-			};
-		});
+	/** 当前内存值（只读消费；外部不得直接修改返回对象）。 */
+	get() {
+		return this.value;
 	}
-	/** 原始分类（getBuddyListV2 / 缓存）。 */
-	async getBuddyCategories() {
+	/**
+	* 加载配置：
+	* - seed 存在 → 直接用 seed（已校验，不读文件；全局 TOML 分段装配方式）；
+	* - 文件缺失 → 写入默认值并落盘（首次运行自动生成），返回默认值；
+	* - 文件存在 → 读取 + 校验，更新内存，返回。
+	*/
+	async load() {
+		if (this.seed !== void 0) {
+			this.value = this.seed;
+			return this.value;
+		}
+		let raw;
 		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;
+			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;
 	}
-	/** 判断是否好友。 */
-	isBuddy(uid) {
-		return this.service.isBuddy(uid);
-	}
-	/** 好友申请列表（set_friend_add_request 应答前查找匹配项）。 */
-	async getBuddyReqList() {
-		const raw = await this.service.getBuddyReq();
-		unwrap$3("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
-		});
+	/** 重新从磁盘加载（外部变更后的热更新入口，P2 配置热更新使用）。 */
+	reload() {
+		return this.load();
 	}
-	/** 删除好友（tempBlock=拉黑，tempBothDel=双向删除）。 */
-	async deleteFriend(uid, tempBlock = false, tempBothDel = false) {
-		const res = 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");
+	/** 校验并落盘（原子写：临时文件 + 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;
 	}
-	/** 可疑好友申请列表（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);
-		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;
+	/** 对象 → 文本（TOML/JSON）。 */
+	serialize(value) {
+		if (this.format === "toml") return stringify(value);
+		return JSON.stringify(value, null, 4);
 	}
-	/** 单项转换：DoubtBuddyReq → OB11 结构（可选字段条件赋值，exactOptionalPropertyTypes）。 */
-	toDoubtFriendRequestInfo(item, uinMap) {
-		const info = {
-			flag: item.uid,
-			uin: Number(uinMap.get(item.uid) ?? item.uid),
-			type: "doubt"
-		};
-		if (item.nick !== void 0) info.nick = item.nick;
-		if (item.source !== void 0) info.source = item.source;
-		if (item.reason !== void 0) info.reason = item.reason;
-		if (item.msg !== void 0) info.msg = item.msg;
-		if (item.groupCode !== void 0) info.group_code = item.groupCode;
-		if (item.reqTime !== void 0) info.time = item.reqTime;
-		return info;
+	/** 文本 → 对象（TOML/JSON）。 */
+	deserialize(raw) {
+		if (this.format === "toml") return parse(raw);
+		return JSON.parse(raw);
 	}
-	/** 处理可疑好友申请（set_doubt_friends_add_request；uid=flag）。 */
-	handleDoubtFriendRequest(uid) {
-		this.service.approvalDoubtBuddyReq(uid, "", "");
+	/** 反序列化 + 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/types/entities.ts
+//#region src/infra/logger.ts
 /**
-* 实体类型层（运行时探测产物 + 公开资料作说明书，ADR-006）
+* pino 日志封装（ADR-007）
 *
-* ⚠️ 部分字段按公开资料（wrapper 外部契约）自研描述，待下一次进程内
-* 探测（probe.ts）校准——接口签名是外部系统事实，自研描述其形状。
+* - console（pino-pretty 可读输出）+ 可选文件双目的地
+* - 统一 level 控制
+* - 内置 redact（token / 票据等敏感字段不打日志），可追加
+* - 无全局单例（ADR-015 推论）：每进程实例化一份，由装配层持有
 */
-/** 会话类型（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/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
-};
+/** 默认 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/apis/group.ts
+//#region src/infra/paths.ts
 /**
-* GroupApi：群语义化 API（ADR-009 统一错误语义）
+* 数据目录布局（ADR-016，2026-08-08 修订：数据根默认放项目根）
 *
-* 内部解包原生返回：成功返回纯业务值，失败抛 KernelError。
-* 方法面（P2-4 + P2-10）：群列表 / 群详情 / 成员列表 / 成员详情 / uin↔uid +
-* 群管操作（踢人 / 禁言 / 管理员 / 名片 / 群名 / 退群 / 精华消息 / @all 剩余）。
+* ```
+* <数据根>/<qq号>/             # 每账号独立目录（ADR-015 多账号前提）
+* ├── config/                  # 各账号独立配置（历史产物，协议段已走 seed）
+* ├── logs/                    # pino 文件日志
+* └── cache/                   # 临时文件、媒体缓存
+*
+* <项目根>/napuketto.toml      # 全局配置文件（放项目根目录，不入库）
+* <项目根>/.napuketto/         # 数据根（默认值，2026-08-08 用户拍板：直接放项目主目录）
+* ```
+*
+* 数据根优先级：cli `--data-dir`（显式参数）> `NAPKETTO_DATA` 环境变量 >
+* `<项目根>/.napuketto`（默认，部署原因不放用户目录）。
+* 配置文件路径见 `resolveConfigPath`（项目根探测，与数据根解耦）。
 */
-/** 原生 result 解包（result 字段非 0 抛 KernelError）。 */
-function unwrap$2(label, result, errMsg) {
-	if (result === 0) return;
-	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
+/** 默认数据根目录名（项目根下，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;
 }
-/** 群 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 强制刷新，默认缓存）。 */
-	async getGroupList(force = false) {
-		const raw = await this.service.getGroupList(force);
-		if (raw.result !== 0) unwrap$2("getGroupList", raw.result, raw.errMsg);
-		const list = raw.groupList;
-		if (Array.isArray(list)) return list;
-		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$2("getGroupDetailInfo", result, errMsg);
-		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;
-		throw kernelError(`getGroupDetailInfo 返回形状异常（groupCode=${groupCode}）: ${errMsg}`, "UNKNOWN");
-	}
-	/** 群成员列表（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$2("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$2("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$2("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);
-	}
-	/** 设置管理员（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$2("modifyGroupName", raw.result, raw.errMsg);
-	}
-	/** 退群（needDeleteLocalMsg=is_dismiss：是否解散群，仅群主）。 */
-	async quitGroup(groupCode, needDeleteLocalMsg = false) {
-		const raw = await this.service.quitGroupV2({
-			groupCode,
-			needDeleteLocalMsg
-		});
-		unwrap$2("quitGroupV2", raw.result, raw.errMsg);
-	}
-	/** 设置精华消息（msgId 经 msgService 取 msgSeq/msgRandom）。 */
-	async addGroupEssence(groupCode, msgId) {
-		await this.setEssence(groupCode, msgId, true);
+/**
+* 项目根查找：入口模块向上找 `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;
 	}
-	/** 取消精华消息。 */
-	async removeGroupEssence(groupCode, msgId) {
-		await this.setEssence(groupCode, msgId, false);
+}
+/**
+* 全局配置文件路径解析（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");
 	}
-	/** 精华消息公共流程：按 msgId 拉消息 → add/removeGroupEssence。 */
-	async setEssence(groupCode, msgId, add) {
-		const peer = {
-			chatType: ChatType.GROUP,
-			peerUid: groupCode
-		};
-		const raw = await this.msgService.getMsgsByMsgId(peer, [msgId]);
-		unwrap$2("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);
-		if (res !== void 0 && res !== null && typeof res.result === "number" && res.result !== 0) throw kernelError(`${label} 失败: ${String(res.errMsg ?? "")}`, "UNKNOWN");
+	/** 递归创建全部目录，启动装配时调用一次。 */
+	ensure() {
+		for (const dir of [
+			this.configDir,
+			this.logsDir,
+			this.cacheDir
+		]) mkdirSync(dir, { recursive: true });
 	}
-	/** @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
-		};
+	/** 账号目录内的文件路径（如 `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/group-notify.ts
+//#region src/apis/result.ts
 /**
-* GroupNotifyApi：群通知/禁言列表语义化 API（ADR-009 统一错误语义，P2-13）
+* 原生调用结果解包（ADR-009 统一错误语义）
 *
-* get_group_system_msg / set_group_add_request / get_group_shut_list 共用。
-* getSingleScreenNotifies / getGroupShutUpMemberList 的列表可能走 listener 回调，
-* 直接调用返回形状待探测校准：兼容 result 数组 / 字段 / 直接数组。
+* 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$1(label, result, errMsg) {
+function unwrap(label, result, errMsg) {
 	if (result === 0) return;
 	throw kernelError(`${label} 失败: ${errMsg ?? "无错误详情"}`, "UNKNOWN");
 }
-/** 群通知 API：从 session 拿 group service，包装成语义化方法。 */
-var GroupNotifyApi = class {
+/** 宽松 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;
-	constructor(session) {
-		const service = session.getGroupService();
-		if (service === null || service === void 0) throw kernelError("getGroupService() 返回空（session 未 init）", "INVALID_STATE");
+	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;
 	}
-	/** 单屏通知列表（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$1("getGroupShutUpMemberList", raw.result, raw.errMsg);
-		return extractMemberList(raw.result);
+	/** 好友列表（分类拍平为 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;
 	}
-	/** 处理群请求（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
+	/** 带分类的好友列表（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
+			};
 		});
 	}
-};
-/** 从 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;
+	/** 原始分类（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;
+		}
 	}
-	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;
+	/** 判断是否好友。 */
+	isBuddy(uid) {
+		return this.service.isBuddy(uid);
 	}
-	return [];
-}
+	/** 好友申请列表（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) {
+		const info = {
+			flag: item.uid,
+			uin: Number(uinMap.get(item.uid) ?? item.uid),
+			type: "doubt"
+		};
+		if (item.nick !== void 0) info.nick = item.nick;
+		if (item.source !== void 0) info.source = item.source;
+		if (item.reason !== void 0) info.reason = item.reason;
+		if (item.msg !== void 0) info.msg = item.msg;
+		if (item.groupCode !== void 0) info.group_code = item.groupCode;
+		if (item.reqTime !== void 0) info.time = item.reqTime;
+		return info;
+	}
+	/** 处理可疑好友申请（set_doubt_friends_add_request；uid=flag）。 */
+	handleDoubtFriendRequest(uid) {
+		this.service.approvalDoubtBuddyReq(uid, "", "");
+	}
+};
+//#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 外部契约，自研描述）。 */
@@ -762,7 +822,332 @@ function toSendElements(elements) {
 		case "xml":
 		case "unknown": throw kernelError(`发送元素 ${el.type} 暂不支持（P2-2 探测后补）`, "INVALID_PARAM");
 	}
-	return out;
+	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);
+		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;
+		throw kernelError(`getGroupDetailInfo 返回形状异常（groupCode=${groupCode}）: ${errMsg}`, "UNKNOWN");
+	}
+	/** 群成员列表（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
+		};
+	}
+};
+//#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
@@ -774,17 +1159,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 +1276,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 +1340,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 +1361,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 +1409,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;
@@ -1200,6 +1508,79 @@ function countGroupFiles(result) {
 	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));
+	});
+}
+/** 解析 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）
@@ -1280,29 +1661,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,14 +1790,34 @@ var MsgBridge = class {
 	}
 };
 //#endregion
-//#region src/types/listeners/group.ts
-/** 群列表更新类型（说明书参考，值待探测校准）。 */
-const GroupListUpdateType = {
-	/** 全量更新（groupList 为完整列表）。 */
-	ALL: 0,
-	/** 增量更新（合并到现有缓存）。 */
-	PARTIAL: 1
-};
+//#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
 /**
@@ -1482,6 +1887,28 @@ var GroupCache = class {
 		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 表示群不存在。
 	*/
@@ -1566,181 +1993,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;
@@ -1784,78 +2036,21 @@ function createSessionListener(opts = {}) {
 		onOpentelemetryInit: (info) => emit("onOpentelemetryInit", info),
 		onUserOnlineResult: (result) => emit("onUserOnlineResult", result),
 		onGetSelfTinyId: (result) => emit("onGetSelfTinyId", result)
-	};
-}
-/** 创建登录监听器（占位，登录器接入时填充）。 */
-function createLoginListener() {
-	return {};
-}
-//#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 解耦）：
-*  - 配置装配（buildEngineConfig / buildLoginConfig / buildSessionConfig）→ wrapper-config.ts
-*  - NAPI 回调适配器（GlobalAdapter / DependsAdapter / DispatcherAdapter / listener 工厂）→ wrapper-adapters.ts
-*  - 本文件只保留流程编排：快速登录 + session 初始化 + init 完成信号等待。
-*/
-/** 等待条件满足（轮询，带超时）。 */
-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();
-	});
+	};
 }
-/** session init 默认超时（毫秒）。 */
-const DEFAULT_INIT_TIMEOUT_MS = 15e3;
-/** session 就绪等待默认超时（毫秒）。 */
-const SESSION_READY_TIMEOUT_MS = 3e4;
-/** session 就绪轮询间隔（毫秒）。 */
-const SESSION_READY_POLL_MS = 1e3;
+/** 创建登录监听器（占位，登录器接入时填充）。 */
+function createLoginListener() {
+	return {};
+}
+//#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 +2066,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 +2128,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 +2163,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 +2440,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 +2752,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 +2762,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 +2915,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 +2988,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 +3000,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 +3124,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 +3146,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 +3213,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 +3313,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 +3359,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 +3410,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）。 */