@napuketto/kernel 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { readFile, rename, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parse, stringify } from "smol-toml";
@@ -5167,6 +5167,185 @@ function writeProbeFile(result, file) {
 	}
 }
 //#endregion
+//#region src/wrapper/probe/probe-listener.ts
+/**
+* listener 录制器（批次三前置探测，docs/protocols/milky.md §0.8.1、本包 design.md §10）
+*
+* 动机：无源事件缺的不是方法名而是回调证据——现有 bridge 只注册已知回调名，
+* 原生 listener 回调面之外的派发行为从未被观测。原理：原生 listener 是普通
+* JS 对象 + NAPI 按名反射回调（MsgBridge 模式），用 Proxy get 陷阱构造万能
+* 监听器，原生调什么记什么，不需要预先知道回调名。
+*
+* 开关：NAPUTO_LISTENER_RECORD=1（loader bootstrap 挂起，位置与 runProbePhase 相邻）。
+* 产物：NAPUTO_CFG_DIR/napuketto-listener-record.jsonl（JSONL 追加，注册过程
+* 逐行落盘，原生崩溃保留断点定位肇事服务）。
+*
+* 安全边界：记录函数只序列化入参后回调 onEvent，绝不反向调用原生；录制器与
+* 业务 bridge 并存（addKernelXListener 多监听各自独立 id），不干扰协议链路。
+*/
+/** 默认仪器面：与 5 个无源事件 + sysmsg 样本采集相关的 listener 服务（design.md §10）。 */
+const INSTRUMENTED_SERVICE_GETTERS = [
+	"getMsgService",
+	"getGroupService",
+	"getRecentContactService",
+	"getBdhUploadService",
+	"getOnlineStatusService",
+	"getLockService",
+	"getFileAssistantService",
+	"getBuddyService",
+	"getProfileLikeService",
+	"getNodeMiscService"
+];
+/** 服务 getter 前缀 / 后缀（getMsgService → Msg）。 */
+const GETTER_PREFIX_RE = /^get/;
+const SERVICE_SUFFIX_RE = /Service$/;
+/** listener 注册 / 注销方法名（addKernelMsgListener / 裸 addListener 同规则）。 */
+const ADD_LISTENER_RE = /^add(Kernel)?\w*Listener$/;
+const REMOVE_LISTENER_RE = /^remove(Kernel)?\w*Listener$/;
+/** 服务简称（getMsgService → Msg；getBdhUploadService → BdhUpload）。 */
+function serviceShortName(getter) {
+	return getter.replace(GETTER_PREFIX_RE, "").replace(SERVICE_SUFFIX_RE, "");
+}
+/** 从服务方法面选 listener 注册方法（addKernelMsgListener / 裸 addListener 同规则）。 */
+function findAddMethod(service) {
+	return listMethods(service).find((m) => ADD_LISTENER_RE.test(m)) ?? null;
+}
+/** 从服务方法面选 listener 注销方法（缺失允许——录制器不主动注销）。 */
+function findRemoveMethod(service) {
+	return listMethods(service).find((m) => REMOVE_LISTENER_RE.test(m)) ?? null;
+}
+/**
+* 构造万能监听器：Proxy get 陷阱对任意字符串属性返回记录函数（同时记录原生
+* 查过的名字，即使从未调用）；has / ownKeys 也记录（判定原生按名 Get 还是
+* 枚举发现回调）；非字符串键（Symbol，如 util.inspect 触发）放行默认行为。
+*/
+function createRecordingListener(service, onEvent) {
+	const record = (event, args) => {
+		onEvent({
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			service,
+			event,
+			args
+		});
+	};
+	return new Proxy({}, {
+		get(target, prop, receiver) {
+			if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+			record("<get>", [prop]);
+			return (...args) => {
+				record(prop, [...args].map((a) => serialize(a)));
+			};
+		},
+		has(_target, prop) {
+			if (typeof prop === "string") record("<has>", [prop]);
+			return true;
+		},
+		ownKeys() {
+			record("<ownKeys>", []);
+			return [];
+		}
+	});
+}
+/**
+* 启动 listener 录制：session 十服务 + LoginService（exports 单例）逐服务注册
+* 万能监听器，JSONL 逐行追加。返回摘要；文件路径写入结果（bootstrap 日志用）。
+*
+* ⚠️ 调用时序约束：必须在任何探测（probeRuntime / getMainSession）之前调用——
+* resolveMainFromStartup 会把空壳主 session 写回 ctx.session（session-resolver.ts），
+* 空壳的 service getter 函数仍在但调用返回 null（late probe 61/63 null 的根因）。
+*/
+function startListenerRecording(ctx, file = "napuketto-listener-record.jsonl") {
+	const dir = process.env["NAPUTO_CFG_DIR"] ?? process.cwd();
+	mkdirSync(dir, { recursive: true });
+	const full = join(dir, file);
+	writeFileSync(full, "", "utf8");
+	const emit = (record) => {
+		try {
+			appendFileSync(full, `${JSON.stringify(record)}\n`, "utf8");
+		} catch {}
+	};
+	const registered = {};
+	const session = ctx.session;
+	if (session !== null && session !== void 0) for (const getter of INSTRUMENTED_SERVICE_GETTERS) registered[serviceShortName(getter)] = recordService(session, getter, emit);
+	registered["Login"] = recordLoginService(ctx, emit);
+	return {
+		file: full,
+		registered
+	};
+}
+/** 对单个服务注册万能监听器（getter 失败/null/无 add 方法均记录原因）。 */
+function recordService(session, getter, emit) {
+	const name = serviceShortName(getter);
+	try {
+		const fn = session[getter];
+		if (typeof fn !== "function") return {
+			ok: false,
+			error: `getter 缺失（typeof=${typeof fn}）`
+		};
+		const service = fn.call(session);
+		if (service === null || service === void 0) return {
+			ok: false,
+			error: "null/undefined"
+		};
+		return attachRecordingListener(name, service, emit);
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** LoginService 单例录制（NodeIKernelLoginService.get()，bot_offline 候选源）。 */
+function recordLoginService(ctx, emit) {
+	const ctor = ctx.exports["NodeIKernelLoginService"];
+	try {
+		if (ctor === null || ctor === void 0 || typeof ctor.get !== "function") return {
+			ok: false,
+			error: "NodeIKernelLoginService.get 缺失"
+		};
+		const service = ctor.get();
+		if (service === null || service === void 0) return {
+			ok: false,
+			error: "null/undefined"
+		};
+		return attachRecordingListener("Login", service, emit);
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** 在服务实例上挂万能监听器（add 方法自动选取；注册事件即行落盘）。 */
+function attachRecordingListener(name, service, emit) {
+	const addMethod = findAddMethod(service);
+	if (addMethod === null) return {
+		ok: false,
+		error: "无 add*Listener 方法"
+	};
+	const add = service[addMethod];
+	if (typeof add !== "function") return {
+		ok: false,
+		error: `${addMethod} 非函数`
+	};
+	const listener = createRecordingListener(name, emit);
+	const listenerId = add.call(service, listener);
+	emit({
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		service: name,
+		event: "<registered>",
+		args: [{
+			addMethod,
+			removeMethod: findRemoveMethod(service),
+			listenerId: serialize(listenerId)
+		}]
+	});
+	return {
+		ok: true,
+		...typeof listenerId === "number" ? { listenerId } : {}
+	};
+}
+//#endregion
 //#region src/wrapper/wrapper-version.ts
 /**
 * QQ 安装目录探测（ADR-018）
@@ -5224,6 +5403,6 @@ function listQQVersions(installDir) {
 	}).sort().reverse();
 }
 //#endregion
-export { BuddyCache, ChatType, ConfigBase, ConfigError, DEFAULT_DATA_ROOT_NAME, EXIT_CONFIG_INVALID, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RecentContactApi, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { BuddyCache, ChatType, ConfigBase, ConfigError, DEFAULT_DATA_ROOT_NAME, EXIT_CONFIG_INVALID, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RecentContactApi, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createRecordingListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startListenerRecording, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 
 //# sourceMappingURL=index.mjs.map