nt_helper.node 接口文档
nt_helper.node是一个用 Rust(napi-rs)编译的原生 N-API 模块,已经把「QQ 进程检测、数据库解密 / 直查 / 导出、ptlogin2 cookie、只读内存取会话物料、原生 SSO 发包、商城表情 / 字体 / 装扮资源」这些重活全部封装好了。Node 侧(主进程、@weq/db、@weq/protocol、各种 worker)直接加载调用即可,不要重新实现里面的任何一个能力。下面每个接口往下翻——如果在写代码时发现某件事「看起来很底层」,大概率这里已经提供了现成函数。先搜文档,再决定要不要动手。
1. 模块总览
- 加载方式:纯 Node 原生模块(N-API),
require()/createRequire()直接加载,无需 rebuild、无需 Electron 主线程。 - 文件名来源:Cargo
[lib] name = "nt_helper",crate-type = ["cdylib"],产物以nt_helper.node落在native/<platform>/<arch>/下。 - 命名约定:导出函数一律为 camelCase(NAPI 自动由 Rust 的 snake_case 转换),下文的接口名均为直接可用的 JS 名称。返回的对象字段同理(
page_hmac_algorithm→pageHmacAlgorithm)。 - 异步:
async原生函数在 Node 侧返回 Promise;内部用spawn_blocking把耗时工作丢到阻塞线程池,不阻塞 JS 事件循环。 - 跨平台:同一套 JS 接口,Windows / Linux / macOS 全部可用;个别接口输入与行为按平台有差异,下面逐个标注。
1.1 加载与初始化(必须先做)
import { createRequire } from 'node:module';
const requireFn = createRequire(__filename);
const nt = requireFn('native/linux/x64/nt_helper.node');仓库里不带
native/**/nt_helper.node(历史太大,已拆到 nt_helper_release 分发)。 新克隆运行pnpm dev自动准备锚定的发布版;独立维护时用pnpm native:fetch,默认也取固定 tag,不是 latest。 装扮索引另由应用按需获取,本地 native 源码模式仍使用自己的配套资源。细节见 原生二进制与装扮资源的分发。
所有功能函数在真正干活前都会内部调用 logger::init_logger() 与环境校验(有效期检查)。务必按下面的顺序初始化:
- 先
setLogPath(可选但建议):配置日志路径,否则日志落到默认位置。 - 再
getInitStatus():返回初始化状态;0= 可用,继续;- 非
0= 环境校验失败(构建过期 / 损坏 / 源码改动被检测到),此时多数接口会直接抛错("Environment validation failed")或返回一个默认的“失败”值,详见 §2.
getInitStatus()可以且应该在每次加载require之后调用一次,作为对「模块是否可用」的硬性检查(如attach_worker.ts的做法)。
dev 构建无时间戳 → 跳过校验:本地
cargo/npm build出的.node不带BUILD_TIMESTAMP,getInitStatus()直接返回0,没有任何有效期 / LICENSE 限制;带时间戳的 CI release 构建才会走有效期检查。有效期长度只由 nt_helper 的 Rust 定义一处,查询用getBuildInfo()(返回buildTime/expireTime/validitySecs/isDev)。
2. 环境与工具函数
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
getInitStatus() | — | number | 全局初始化状态:0=可用,-1=过期,-200=损坏,-201=被篡改,99=未知。 |
getBuildInfo() | — | BuildInfo | 构建时间 / 有效期窗口:{ buildTime: number | null; expireTime: number | null; validitySecs: number; isDev: boolean; authorizationInterface: number }(Unix 秒)。expireTime = buildTime + validitySecs。有效期长度只在 native 侧定义一处。不经过初始化校验,过期后仍可查询(用于驱动更新提示)。authorizationInterface 是权限助手接口版本,用来判断系统里已装的长期授权助手是否还兼容。 |
setLogPath(path) | path: string | void | 配置日志输出路径;内部 logger::set_log_path。同步,不返回 Promise。 |
setDebugLog(enabled) / isDebugLogEnabled() | boolean | void / boolean | 运行时可切底层调试日志(trace 级),不用重启、不用改环境变量。报文与认证数据只记状态和长度,不写原始字节。默认关闭。 |
resolveAppidFromMajor(majorPath) | majorPath: string | AppidInfo | 从 QQ NT 的 resources/app/major.node 直接扫描出 appid / qua / version / build,所见即所得,无静态版本表。同步。 |
resolveQqRuntimeModules(pid) | pid: number | QqRuntimeModules | null | 从运行中的 QQ 进程解析出 wrapper.node / major.node 等运行时模块路径。null = 模块没找到或不适用。给了 pid 就不用猜安装路径。 |
convertFont(inputPath, outputPath, options?) | 俩字符串路径 + 可选 ConvertFontOptions | string | FTF → 标准 TTF 转换(同步版);本来就是 TTF 则直接拷贝。耗时场景用 convertFontAsync(语义、返回值相同,丢到阻塞线程池)。默认还会把 brsh/cglf 编译成彩色字体(COLR v1 + CPAL v0)、把 eimg 炫彩帧导到 <输出名>_assets/(frame_<槽位>.png)、并用本机 ots-sanitize 预检产物。返回说明消息,如 converted FTF to TTF; exported 109 eimg frame(s) (350x141) to …; OTS ok。 |
getFontPipelineVersion() | — | number | native 侧字体转换链的版本号(font::FONT_PIPELINE_VERSION):改 src/font/** 的产物字节就 +1。宿主把产出 fonts/<id>.ttf 时的这个号写进 sidecar,读缓存时对不上就地重解 —— 这样「native 修了字体的表处理」不必再等宿主手改版本号(hdmx/LTSH 那次就是漏在这里)。 |
getMarketFaceKey(packetId) | packetId: string | Promise<MarketFaceKey | null> | 恢复商城表情包 QQTEA 密钥(自包含:抓 android.json 提示 → xydata 快路径 → 采样爆破)。返回 null 表示拿不到。 |
queryDressResourceUrl(dtype, itemId, name) | 三个字符串 | DressResourceUrl | null | 纯本地查装扮资源下载 URL(font/bubble/widget × 部件名),不联网、不依赖协议。null = 本地索引缺失、密钥不匹配或未命中;索引下载与在线协议补全由共享服务层编排。 |
装扮业务复用 @weq/service 的 DressSharedCache 与索引管理器,不应在各调用方重复实现下载。 native 的上述同步函数自身不会自动取索引;共享服务按固定清单下载、校验和迁移旧索引,在线 QQ 协议不等待后台下载。 发布版和本地源码构建的资源来源区别见分发说明。
携带数据的封箱类型
AppidInfo = { appid: string; qua?: string; version?: string; build?: string }BuildInfo = { buildTime: number | null; expireTime: number | null; validitySecs: number; isDev: boolean; authorizationInterface: number }MarketFaceKey = { timestamp: number; key: string; source: 'xydata' | 'brute-force' }DressResourceUrl = { url: string; size: number }ConvertFontOptions = { color?: boolean; colorChars?: string; assetsDir?: string; checkOts?: boolean }(缺省即全开;assetsDir: ''关图包,color: false关彩色,checkOts: false关校验)。早于该开关的 nt_helper 会忽略第三个参数(只做转换),调用方不必探测版本。
3. QQ 进程 / 登录状态检测
这些是纯只读探测,不注入、不改库。注意:大部分 probe 函数失败时不抛错,而是返回带 success / msg 字段的“失败”对象(不满足某先决条件时会返回与真实失败相同形状的默认值),调用方按字段判断即可。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
getQqProcesses(headless?) | headless?: boolean | Promise<number[]> | 全部 QQ 主进程 PID。macOS 按 headless 二选一:默认走 bundle id 直查(需 GUI),true 走 libproc 全量枚举。 |
probeQqLoginInfo(pid) | pid: number | Promise<QqPortLoginInfo | null> | 通过本地端口探测登录态 / UIN / 昵称。null = 没拿到信息。 |
probePtLoginPort(pid) | pid: number | PtLoginPortProbeResult | 探测 pt_login 端口(奇数 HTTPS / 偶数 HTTP,优先 HTTPS)。 |
probeDbLock(dbPath) | dbPath: string | DbLockProbeResult | 反查哪些进程占用了数据库文件(success+locked+holders)。Windows 用 Restart Manager,Unix 用 fcntl 写锁探测。只读。 |
isQqLoggedIn(dbPath) | 该账号 nt_msg.db 的绝对路径 | boolean | 某账号是否登录中。三端同一套机制:只看这个库有没有被 QQ 独占持有(Windows 打开句柄 / Unix POSIX advisory 写锁),命名互斥体、端口探测那套已删。数据目录由调用方解析,native 不猜。 |
返回类型
QqPortLoginInfo = { port: number; uin: string; uid?: string; nickName?: string; loggedIn: boolean }PtLoginPortProbeResult = { success: boolean; msg: string; port: number }DbLockProbeResult = { success: boolean; msg: string; locked: boolean; holders: DbLockHolder[] }DbLockHolder = { pid: number; name: string }
桌面常规轮询在 macOS 使用 @weq/platform 的有界异步 pgrep + lsof 探测,仍要求 QQ 进程实际持有该账号的 nt_msg.db,不以进程存在或端口信息代替账号归属。 同账号并发调用合并,不同账号独立探测,最多保留 8 个未退出的探测任务。 探测超时、启动失败和异常退出通过拒绝 Promise 表示“未能确认”,不返回离线结果; 正常查无持有者才返回 null。账号监控遇到单次空结果会在下一轮复核,连续两次未发现 才清理在线凭据;已确认在线后遇到探测错误,最多保留 30 秒状态并暂停本轮采集, 持续不可用则转离线,防止永久复用旧凭据。失败记录 online-probe-failed,下线记录 reason(no-db-holder 或 probe-unavailable),便于区分真正未发现与探测故障。
QQ 运行态未读计数另有三个可选导出:getQqUnreadCapability()、 readQqUnreadCounts({ pid, databasePath, targets?, timeoutMs? })、clearQqUnreadCache(pid?)。 当前提供 macOS arm64/QQNT 7.0.3-54395 和 Windows x64/x64 QQ 9.9.37-54395 布局, 实际加载模块、进程代和账号持库关系由 native 核验;缺失目标不等于零,快照没有 QQ 有效阅读位置。 WeQ 仅显式诊断调用内存路径,不接管数据库小表角标;来源和验证范围见未读计数来源。
3.1 纯协议登录(装号 / 取密钥)
登录已与 QQ 进程解耦:不读内存、不注入、不提权,直接把 login.db 里缓存的 a1(扫码路径不需要) 和设备 guid 传给 native,由 native 直连登录服务器(wtlogin)换 a2/d2/d2key。有 a1 → 快登 (服务端判异常设备时转手机点确认);无 a1 → 扫码。快登失败由调用方回退到扫码。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
quickLogin(options, onEvent?) | QuickLoginOptions + 进度回调 | Promise<QuickLoginResult> | 用缓存 a1 换票据;keyMeta 给了就顺带发 0xcde_2 取 dbKey。 |
qrLogin(options, onEvent?) | 同上(a1 可留空) | Promise<QuickLoginResult> | 出二维码等扫码/确认,再走经典 wtlogin.login 换票据;同样顺带 dbkey / pskey。 |
QuickLoginOptions:uin / a1 / guid / appId / subAppId / os / platform / deviceName / kernelVersion(appId 是 EasyLogin 常量、subAppId 必须扫描 major.node), 另可选 appName / qua / clientVersion / wrapperPath(签名用)/ uid / keyMeta(nt_msg.db 头 0x2f..0xaf 的 128 字节)/ pskeyDomains。
QuickLoginResult:a2 / d2 / d2Key / uin,外加 dbKey?(0xcde_2 结果)与 pskey?: Record<string, string>(0x102a_0 结果,域 → p_skey;未请求或没拿到时缺省)。 pskeyDomains 走的是同一条登录连接、属尽力而为:取不到只记日志,不会让登录失败。 一个域名一轮请求(服务端一轮只回一个域,真机抓包里客户端也每轮只带一个域),所以两个域就是两轮 0x102a_0。WeQ 侧默认要 vip.qq.com(首页装扮 zb.vip.qq.com 用)与 qzone.qq.com (QQ 空间 Web cgi / 空间窗口用)。
onEvent(err, event) 推送进度:state(阶段文案)、unusual-device(异常设备需确认, 带 unusualDeviceCheckSig / unusualDeviceQrSig / uinToken)、qr-code (qrUrl / qrImage)、qr-state(state / stateCode / uin)。
3.2 ptlogin2 凭据与邮箱会话
凭据获取的 HTTP 流程只有 native 这一份实现,TS 侧只负责选域、缓存和业务编排, 不要自己发 xlogin / jump 请求或解析 JSONP。
取票顺序:OIDB 优先、本地 pt_login 兜底。 本地快速登录端口 (xlogin → pt_get_uins → pt_get_st → jump → check_sig)在账号安全等级 不足 / 需要手机确认时会直接返回 403,且各平台监听情况不一;clientKey 走的 OIDB 0x102a_1 复用的是同机 QQ 已在维持的会话,更稳定、更普适。
ptFetchCredentials 的三级链路:
clientKey(OIDB0x102a_1为主、本地端口兜底)→ ptlogin2jump,沿途收下 整条 302 链的 cookie jar。这一级同时给出域无关的skey、目标域的p_skey和 含风控 cookie 的完整cookie。- 本地 pt_login 端口跑完整登录流程(固定四域 / 邮箱)。
- OIDB
0x102a_0只取p_skey(拿不到skey,也没有风控 cookie)。
任一级拿到 p_skey 即返回;全部失败时 msg 会逐级累积各自的失败原因,不再 只报最后一步。未注入 / 未登记 setSsoSession 时第 1、3 级会立即报错(不是超时), 此时只能靠第 2 级的本地端口。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
ptFetchCredentials(pid, uin, domain) | pid / uin / 目标域 | Promise<PtCredentialsResult> | 三级链路(clientKey jump → 本地 ptlogin2 → OIDB 0x102a_0),固定四域与任意域一致;邮箱域走第 2 / 3 级取面板 p_skey。 |
ptFetchClientKey(pid, uin) | pid / uin | Promise<PtClientKeyResult> | OIDB 0x102a_1 优先,失败回退本机快速登录端口。 |
ptFetchJumpUrl(pid, uin, landingUrl) | pid / uin / https 落地页 | Promise<PtJumpUrlResult> | 生成一次性免登录跳转地址;clientKey 只应在本次点击使用。 |
ptFetchMailSession(pid, uin) | pid / uin | Promise<PtMailSessionResult> | 邮箱登录:优先使用客户端 delegateCode → auth_type=7 → sid,兼容 ptlogin,并返回独立提醒票据 panelPskey 和可灌入 CookieJar 的 cookie。 |
返回类型
PtCredentialsResult = { success; msg; skey; pskey; cookie; errorKind }PtClientKeyResult = { success; msg; clientKey; keyIndex; ttlSeconds }PtJumpUrlResult = { success; msg; url; clientKey; keyIndex }PtMailSessionResult = { success; msg; sid; panelPskey; cookie; errorKind }
cookie 是 native 在跳转链上收到的完整 Cookie 头(含 pt4_token / RK / ptcz 等风控字段),调用方应优先原样发送;拿不到时才回退到 uin/skey/p_uin/p_skey 四字段。panelPskey 是邮箱面板提醒专用票据,网页登录清掉 CookieJar 后仍需独立保留。 ptFetchSkey(port, uin) / ptFetchPskey(port, uin, domain) 是底层兼容接口, 新代码优先用 ptFetchCredentials。
4. 数据库密钥获取与校验
获取 QQ NT 加密库的解密密钥,三条路线都在这里,优先复用,别自己重写内存扫描。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
scanKeyFromDatabase(dbPath, pid) | dbPath: string, pid: number | Promise<KeyScanResult> | 零注入内存扫描拿 raw master key,用 dbPath 过滤候选。扫描逻辑移植自 x_key_scanner(含强力模式:锚点/簇扫描失败时回退扫整个内存),候选并行校验。 |
scanKeyFromDatabaseWithProgress(dbPath, pid, onProgress?) | 同上 + 进度回调 | Promise<KeyScanResult> | 同上,额外通过 onProgress(err, progress) 持续回报两阶段进度。可选能力(老产物没有,调用方需回退到 scanKeyFromDatabase)。 |
testDatabaseKey(dbPath, key) | dbPath, key | Promise<KeyTestResult> | 试 key 是否能解开库,穷举 page-HMAC × KDF-HMAC 全部 12 种组合,返回能解开的那组算法。用于不知道 algo 时先探测一次。 |
decryptLoginDb(loginDbPath, algo) | 路径 + CipherAlgo | LoginAccount[](同步) | 走 offset VFS 解密 login.db 拿缓存登录账号,不落临时明文文件。algo 可先用 testDatabaseKey 探测。 |
getGuildDbKey(dbPath, uin) | 路径 + uin | string(同步) | 计算 QQ 频道(gpro)库的密钥:读库内 16 字节 salt + 特定 md5 公式。算法结论见 gpro 频道库密钥。 |
两种 scanKeyFromDatabase* 接口只读数据库前 5120 字节(QQ 包装头 + 首个加密页) 用于候选校验,不整库分配内存;短文件或读取错误直接返回失败。所以它可以安全地 在 10 GiB 级的库上用,也不会因为大库把 Electron 进程打死。
返回类型
KeyScanResult = { success: boolean; key?: string; keyContextHex?: string; error?: string }key:恢复出的 16 字节 raw master key;keyContextHex:密钥前后各 256 字节内存窗口的 hex(定位佐证)。
KeyScanProgress = { phase: string; percent: number; message: string }phase:'anchor'(锚点/簇扫描)或'strong'(回退全内存扫描);percent是当前阶段内的 0–100(阶段切换会从 0 重新开始),message是给用户看的短句。
KeyTestResult = { success: boolean; pageHmacAlgorithm?: string; kdfHmacAlgorithm?: string }- 成功时
pageHmacAlgorithm∈'none' | 'SHA1' | 'SHA256' | 'SHA512',kdfHmacAlgorithm∈'SHA1' | 'SHA256' | 'SHA512'。
- 成功时
LoginAccount = { uin: string; uid: string; avatarUrl: string; userName: string; a1Key: string; lastLoginAt: number }
5. 加密库直查 / 解密 / 导出(@weq/db 的基础)
对 QQ NT 加密库(SQLCipher v4 + 1024 字节 wrapper 头)的读写与导出。全部走自定义 offset VFS 透明跳过文件头,连接默认缓存:每条连接只在创建时初始化解密,后续借用复用句柄。better-sqlite3 在 running code 里零引用,读库统一走这里。
SQLite 的保留页按文件设置:QQ 库因 1024 字节头保留 262144,标准 SQLite 保留 262145。nt_helper 从文件头自动识别布局,同一进程可以同时打开两类库与解密产物,不再需要子进程。详见 QQ 数据库布局:按文件设置保留页。
多连接入口的 timing 分别返回 nativeQueueMs(阻塞线程池等待)、connectionWaitMs(读取池等待)、connectionOpenMs(开库与解密初始化)和 executionMs(准备语句及读取行)。不能把 native Promise 总等待冒称 SQL 执行。budgetMs 为 1–50 毫秒,仅在 SQL 开始后计时;请求另有 120 秒期限。严格与宽容连接不混用,但共同计入同库上限;进程只读连接最多 32 条,空闲一分钟后由周期回收器释放。每次原生调用持有一个独占借用,分块扫描内的多步读取保持在该连接内,返回后清理查询钩子和遗留事务。JS 对旧 native 保持单路调度,写入与建索引继续独占协调。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
executeDatabaseRead(input)(可选) | dbPath、sql、requestId,可选 params / key / algo / bulk / budgetMs / level / scan | Promise<DatabaseReadResult> | 同库有界多连接入口;普通、短预算、宽容查询与扫描共用容量,level / scan 沿用原有语义。返回 rows、salvage 或 scan;SQL 错误在 error 中返回,调用方恢复为原来的拒绝语义。 |
configureDatabaseReads(concurrency)(可选) | 1–8 的整数 | void | 进程级同库只读上限,默认 4;调低不打断在途读取。 |
cancelDatabaseRead(requestId)(可选) | 本次读取 ID | boolean | 仅取消此 ID 对应的请求;完成后 ID 注销,不中断复用连接的下一次查询。 |
executeSql(dbPath, sql, params?, layout?) | 路径 + SQL + 可选参数 + 可选布局 | Promise<SqlValue[][]> | 只读查询(offset VFS,无密钥)。注意:这只适用于无需 SQLCipher 密钥的库;带密钥的库首次需要用 executeSqlWithKey 领证,之后才能用 executeSql 复用。layout('qq' / 'standard')缺省时按文件头自动识别。 |
executeSqlBudgeted(dbPath, sql, params, budgetMs, key?, algo?) | 路径 + SQL + 参数 + 毫秒预算 + 可选密钥 / 算法 | Promise<SqlValue[][]> | 带时间预算的查询:长查询到点就中止并报错,用来保护启动期 / UI 线程不被慢查询拖死。 |
executeSqlWithKey(dbPath, sql, key, algo, params?, layout?) | + key + CipherAlgo + 可选布局 | Promise<SqlValue[][]> | 带密钥查询。密钥只消费一次:首个调用驱动 PRAGMA cipher 舞步并缓存连接,之后可省略密钥用 executeSql。 |
executeSqlWrite(dbPath, sql, params?) | 同上(写) | Promise<number> | 写操作,返回受影响行数。带空闲检测 + BEGIN IMMEDIATE 重试。谨慎使用:写前注意备份。 |
executeSqlWriteWithKey(...) | + key + algo | Promise<number> | 带密钥的写操作。 |
closeDb(dbPath) | 路径 | number | 关闭该路径所有缓存连接,返回关闭数。登出 / 释放文件句柄时调用。 |
closeAllDb() | — | number | 关闭全部缓存连接。 |
fastDecryptDatabase(dbPath, outPath, key, algo) | 路径们 + key + algo | void | 快速解密为标准布局的明文 SQLite(直接落盘),可直接被任何 SQLite 工具打开。 |
safeDecryptDatabase(dbPath, outPath, key, algo) | 同上 | void | 安全解密:所有读走 SQLite(offset VFS + sqlcipher_export),长导出期间不怕 QQ checkpoint 撕页;无中间文件。产物同样是标准布局明文。 |
fastDecryptDatabaseAsync / safeDecryptDatabaseAsync | 同上 | Promise<void> | 上面两个的异步版:丢进阻塞线程池,不占调用方线程。UI 触发的导出优先用它。 |
checkpointWal(dbPath, key, algo) | 路径 + key + algo | Promise<WalCheckpointResult> | 把 -wal 里的帧并回主库。报告里的 merged 是结论:为 false 时那批改动还没进主文件,不能声称「修复包含了全部消息」。 |
checkDatabaseHealth(dbPath, key, algo, onProgress?) | 路径 + key + algo + 可选进度回调 | Promise<DatabaseHealthResult> | 完整 PRAGMA integrity_check 体检;页结构与引用、各表记录与索引对应、索引条目数量复核分别回报真实进度,整体失败时仍逐表定位。 |
recoverDatabase(options, onProgress?) | RecoverOptions,必须提供已完成的 sourceScan | Promise<RecoverReport> | 直接消费同一维护锁内的页扫描,执行解密、SQLite recover、重新加密、补 QQ 头与产物自检;不再扫描源库,缺扫描结果直接拒绝。源库只读,是否提交产物由宿主决定。sourceLayout / targetLayout 默认 qq,布局迁移传 standard → qq,报告回显实际布局。 |
beginDatabaseMaintenance(id, targets) | 会话标识 + 此数据源全部目标的路径、密钥、算法 | Promise<MaintenanceDatabase[]> | 专用持锁进程中取得 SQLite 保留锁、WAL 写入及检查点锁;准备时合并 WAL,无法合并的库单独返回未就绪原因。禁止在普通主进程直接创建持续锁。 |
protectDatabaseMaintenanceProduct(id, dbPath, product) | 已持锁源库 + 本轮临时产物 | void | 先给产物加保留锁,再允许宿主替换;原文件锁继续保留到账号维护结束。 |
endDatabaseMaintenance(id) | 会话标识 | boolean | 统一释放本次账号维护的源库与产物锁。 |
setDatabaseMaintenanceWriteBarrier(id, paths, enabled) | 会话标识 + 目标路径 + 状态 | void | 宿主进程快速拦截原生写连接,不等待 SQLite busy 超时;持锁进程实际退出后才撤销。 |
databaseRepairStorageVersion()(可选) | 无 | number | 返回 1 表示重建后提前释放明文源库、通过 offset VFS 直接加密带头产物;方法缺失按旧模块预算预检。能力标记与实际加载模块绑定,不以应用版本推断。 |
executeSqlSalvage(dbPath, sql, params?, level?) | 路径 + SQL + 可选参数 + 宽容级别 | Promise<SalvageQueryOutcome> | 宽容只读查询(独立的 salvage 连接)。不因“损坏”抛异常,而是返回 ok:false + 错误码,由调用方决定放弃还是切更小的一段;其它错误照旧抛。级别 ≥ 1 时遇到损坏会换访问路径(NOT INDEXED)重试。 |
executeSqlSalvageWithKey(dbPath, sql, key, algo, params?, level?) | 同上 + key + algo | 同上 | 带密钥版本,语义相同。 |
executeSqlSalvageScan(dbPath, sql, params, options, level?) | + SalvageScanOptions | Promise<SalvageScanOutcome> | 分块容错扫描(L2/L3):读不出来的块先换访问路径、再二分到 minSpan,仍坏就记成“跳过区间”;ok:false(超预算 / 未授权 L2 / 表被隔离)时行集被清空,不许把部分数据当完整数据用。 |
executeSqlSalvageScanWithKey(...) | 同上 + key + algo | 同上 | 带密钥版本。 |
closeSalvageDb(dbPath) | 路径 | number | 只释放该库的 salvage 只读连接(严格连接一律不动),并清掉该库的 L3 隔离记录。用户把宽容级别调回严格时用它。 |
scanBadPages(dbPath, key, algo, onProgress?) | 路径 + key + algo + 可选进度回调 | Promise<BadPageScanResult> | 逐页复算页 HMAC,产出物理坏页清单(“坏页地图”)。回调包含实际已处理页数、总页数及累计坏页/全零页数。⚠ usedHmac=false 时 badPages 必为空 —— 那不是“库是好的”,而是“这个库没开页 HMAC(或压根是明文库,见 plaintext),地图没有意义”。只读密文。 |
listQuarantinedTables() | — | QuarantinedTable[] | 当前被 L3(整表放弃)隔离的表。进程内状态,条目默认 300 秒自动失效(到点自动再试)。 |
clearQuarantinedTables(dbPath?, table?) | 可选两级过滤 | number | 清掉隔离记录让那些表立刻再试。只给 dbPath → 清该库;再加 table → 只清那一张;都不给 → 全清。 |
数据库维护进度回调遵循 N-API 的 (error, progress) 约定。DatabaseProgress 包含 step、message 和可选的 completed、total、unit、objectName、badPages、zeroPages;计数是实际工作量,total 缺省表示没有可靠分母。recoverDatabase 保留旧的 phase/估算 percent/message,并在 detail 中补充同一结构的页扫描、解密、字段解析及产物检查进度。字段计数不是消息条数,当前遇到的最大页号也不是已处理页数。原生线程通常每 200ms 最多回报一次,步骤切换及末次页计数始终回报;不改变最终报告的判断口径。旧组件未提供这些回调或 detail 时,应用仅展示阶段与耗时,不从旧估算值补造百分比。
维护编排在 DatabaseMaintenance 中按账号与数据源管理,窗口不拥有任务生命周期。持锁、扫描/深度检查、临时重建分别使用独立进程:POSIX 记录锁属于进程,若主进程持锁后又为备份、哈希打开并关闭同一文件的其他 fd,会意外释放锁,因此不能把持续锁迁回普通业务进程。持锁进程准备好后持续接收产物保护与结束命令;父进程退出、stdin 关闭时释放锁。意外退出会结束本次维护,旧报告保留,但旧结果不能继续提交修复。
常规扫描先收集修复必需的页信息与布局,深度体检再执行额外结构检查。已完成结果留在维护会话中,停止额外检查不撤销它们。扫描和重建进程都等真实退出后才算停止;重建尚未提交时可以中断并清理本次私有目录,已经提交成功的数据库不回退,单库失败不阻止后续库。扫描结束保持锁等待决定,修复批次结束统一释放。
修复页和任务详情共用阶段时间线及步骤快照;百分比仅用于有可靠分母的当前步骤,账号显示完成库数,不拼接整体进度。备份与哈希异步分块回报,修复产物检查、替换和报告保存结束后才完成本轮任务;等待决定停止执行计时。每次主动执行使用新的报告标识,结果保存在数据源的 db_repair 历史目录,不跟随重建缓存位置移动,也不因查看、关窗或重启自动清理。
整库结构检查保留 SQLite 原有完整检查,不以逐表检查代替。integrity-pages 按实际检查的页数显示 pages 进度;该轮扫描顺带统计各 root 的记录数和 B-tree 页数,不额外执行全库计数查询。integrity-records-<root> 按已检查记录数显示 records 进度,integrity-index-<root> 按索引计数复核实际遍历的 B-tree 页数显示 pages 进度,objectName 给出对应表或索引。各步骤的百分比独立,某一步到 100% 不表示整库体检结束。损坏导致分母不可靠时省略 total,错误上限、取消或执行异常导致提前退出时不补发完成计数;旧原生组件继续显示不定进度。
QQ 专用分词器不可用时仍检查可用的普通表,但必须返回 complete: false 及 unverifiedTables,并回报 integrity-unverified 步骤。healthy: true 此时仅表示已检查部分正常,不代表整库全部通过;深度体检标记部分完成,未核验项保留可见,常规扫描结果仍可用于后续操作。修复产物的 verification 同样保留这些字段,报告不得把缺少核验能力写成相关结构已修复。
调用解密接口前使用 @weq/native 的 selectDatabaseDecryptMethod(dbPath, mode): 它保留用户指定的安全模式,并把 ≥ 512 MiB 的快速解密请求切换到安全模式。 搜索索引重建和数据库导出共用该选择逻辑,避免快速接口整库分配内存导致 Electron 进程崩溃(worker 线程也不能隔离原生内存分配失败)。
5.1 参数类型 CipherAlgo
几乎所有带密钥操作都要传 algo(page-HMAC × KDF-HMAC 组合)。先用 testDatabaseKey 探测未知库得到这对算法,再喂给本节的各函数:
{ pageHmacAlgorithm: 'SHA1', kdfHmacAlgorithm: 'SHA1' }
// page: 'none' | 'SHA1' | 'SHA256' | 'SHA512'
// kdf : 'SHA1' | 'SHA256' | 'SHA512'字符串大小写不敏感。
5.2 SQL 参数与返回值 SqlValue
只读连接额外注册 QQ 搜索查询适配:weq_qq_pinyin0_query_version()、 weq_trigram_contains(body, keyword) 与 weq_trigram_equivalents(scalar)。 它们与 pinyin_letter 0 查询分词器共用内置 SQLite,不用于写回或重建 QQ 文档索引。 旧 native 不提供这些函数时,宿主能力探测失败并退回已有读取路径。
params 支持 null | bigint | number | string | Buffer | Uint8Array;返回行内每个单元格为:
- NULL →
null - INTEGER →
bigint(保留完整 i64 精度,QQ 的 µs/ns 时间戳不会溢出) - REAL →
number - TEXT →
string - BLOB →
Buffer
executeSqlWithKey 返回行示例:
[
[1n, "文本", Buffer.from([...]), 123n],
...
]5.3 返回类型
KeyTestResult / DatabaseHealthResult = { healthy: boolean; corruptedTables: string[] }。
WalCheckpointResult = { busy: number; log: number; checkpointed: number; walBytes: number; merged: boolean }:busy == 1 表示被其他连接挡住,merged 是「帧是否已全部回主库」的结论。
5.4 损坏宽容(salvage)等级与契约
上面四个 *Salvage* 接口是同一套降级机制的四档,级别由调用方给定,native 不自行升级。低层接口仍支持 0–3;应用日常读取固定使用无损的级别 1,不再读取旧账号级别。私聊/群聊导出的任务私有消息源使用级别 2 做分块扫描,但在接受含未读区间的结果前等待任务内确认;拒绝时不交付部分行,也不记成已跳过。应用不再启用级别 3 的全局整表隔离,无法继续分块读取时由任务单独决定是否结束该表,不影响其他任务。设置只保留数据库检查与修复入口,未读范围进入对应任务日志及完整性报告。
| 级别 | 含义 | 会丢数据吗 | 生效范围 |
|---|---|---|---|
| 0 | 严格:任何错误原样报出 | —(默认) | 默认路径 |
| 1 | 换访问路径(NOT INDEXED),只改 SQLite 的访问方式 | 不会 | 走宽容入口的读查询 |
| 2 | 跳过坏页覆盖的行区间(分块扫描) | 会 | 只有满足下面第 1 条契约的查询(WeQ 接在导出链路上) |
| 3 | 整表放弃:隔离读不动的表,保证其它表可用 | 会 | 在级别 2 的基础上启用,(db_path, table) 粒度 |
5.4.1 能救什么、救不了什么(2026-09-20 真实损坏库实测)
阈值与代价都是量出来的,不是估的;写在这里以免界面或文档再一次把能力写宽:
- 聚合查询救不了,级别再高也一样。SQLite 没有“跳过坏页继续执行”的开关 —— 任何语句 一旦碰到坏页就整条以
SQLITE_CORRUPT中止。实测同一条GROUP BY聚合在级别 0 / 1 / 2 / 3 下都是kind=corrupt, code=11, 0 行(约 120–230 ms)。年度报告、群分析这类整表聚合因此 完全不受宽容级别影响,只有修复数据库才能恢复。 - 级别 1 只在“坏在索引上”时有救。它的做法是把语句改写成
NOT INDEXED重试一次; 若坏的是数据页本身,换哪条路都要读那一页 —— 实测坏页同时在索引路径与全表路径上时, 重试 121 ms 后仍然失败。 - 级别 2 的代价按“坏键”线性增长:二分地板是
span = 1,一个读不出来的键约 215 ms (两次 native 尝试,~110 ms/次)。所以一个 4096 宽的导出窗口若横跨很宽的坏区间,第一块 就要十几分钟才走得完;maxSkippedSpan决定的是“要假死多久才肯放弃”。WeQ 的驱动层因此 故意收紧到 20 / 500(native 那份 256 / 8192 的默认值留给明确要求长扫的场景), 约 108 秒就会干净地按严格语义失败。 - 级别 2 的“跳过”是键轴上的,不是行上的:
GROUP BY/ JOIN 这类没有整数键轴的查询 无法切块,契约对不上时是报错,不会给出一份“看着完整、其实位置不明”的结果。 - 级别 3 的隔离粒度是整张表:
(db_path, table)连续失败 3 次(DEFAULT_MAX_FAILURES) 即隔离,存活 300 s(DEFAULT_TTL_SECS)。隔离期内这张表所有读都会短路返回quarantined—— 包括本来健康的会话,所以界面必须说清这一点。
几条必须遵守的契约:
- 分块扫描的 SQL 契约(native 不解析 SQL):末两个
?是区间边界(lo, hi]、结果按 key 升序、第一列必须是整数 key(一般是rowid)。seekSql(已知键探针)的过滤条件 必须与扫描语句一字不差,否则会按契约违规报错。 - 只有损坏进宽容路径:按 native 返回的错误码判定(11 = CORRUPT / 26 = NOTADB), 不看错误文案;开库失败、
BUSY、权限、语法错一律照旧抛。 skipped/skippedSpan不是行数:区间内部有多少行读不出来就无从得知,而键跨度 也不是行数上界(同一个键可能对应多行 —— 共享seq的灰条、贴表情)。报告里只能说 “这一段读不出来”,不能说“最多丢 N 行”。- 预算是上界,不是许可:
maxSkippedRanges/maxSkippedSpan用尽(native 默认 256 / 8192, 相邻同类区间会先合并)就按严格语义整体失败,绝不“越救越多”。驱动层默认更紧(20 / 500, 理由见 5.4.1)。 跨度按区间几何(hi - lo)累计,不照抄 native 单次返回的skippedSpan: 后者会把本次调用里已经知道的区间再算一遍;同一段坏区间被相邻窗口各报一次时,账本只记 新增的那一截(实测 7 键的洞会被重复上报成 2 处 / 跨度 14)。 quarantined与损坏分开:ok=false && quarantined=true表示“这次根本没查”,errorKind是"quarantined"、errorCode为null—— 调用方的账本/报告必须与 “替代路径也救不回来”分开计数。
6. 内存取会话物料与原生 SSO 发包
拿在线数据(图片 rkey、cookie、skey 等)的链路只有两步,都在 native 里:① 只读 QQ 进程内存取出该会话的 a2 / d2 / d2key;② native 自己组帧、签名、直连 QQ 服务器收发。发包不再经过「注入 hook + unix socket / named pipe 管道转发」那套(hook 传输层已删),也就没有「等 hook 就绪」这一环。
登录取密钥不走这条链路
(NineBird 已删):装号 / 取密钥走纯协议 quickLogin / qrLogin(wtlogin 快登或扫码),从 login.db 取缓存的 a1 + 设备 guid 直连登录服务器换 a2/d2/d2key,再顺带发 OIDB 0xcde_2 取 dbKey;不读内存、不注入、不提权。这条 attach 链路仍服务于在线实例功能(图片 rkey / 装扮 / 红包 / 抓包等):prepareInstanceAttach(读内存拿 a2/d2/d2key + 登记原生 SSO 会话)→ fetchKeyFromInstance(发包 OIDB 0xcde_2 取 dbKey)。登记是必备的一步 —— sendOidbPacket / sendPacket 只认已登记的 pid,setSsoSession 之前第一包必然报「还没有登记 SSO 会话」。登记用的 uid 从 login.db 解析、guid 从 QQ 数据根离线算(都无需额外权限)。
读内存这一步仍有权限门槛:Linux 要 root(或 CAP_SYS_PTRACE)且 /proc/sys/kernel/yama/ptrace_scope 放行;macOS 要 root 且目标未开强化运行时保护(QQ 开了,所以得先关 SIP);Windows 要管理员。macOS 上 SIP 开着时读内存无解(task_for_pid 连 root 都拒),因此在线实例功能在此之前不可用 —— 但登录本身已与内存解耦,纯协议即可完成。
Linux 先试免密
Linux 宿主总是先试免密直连:yama ptrace_scope=0(或 CAP_SYS_PTRACE)时同用户 attach 直接成功,不弹窗、不要密码;只有内核真的拒了(EPERM/EACCES)才回到提权。引导弹窗里的「不再提醒」只静音该弹窗,不影响这个顺序——被拒后仍会尝试提权。顺序钉在 packages/service/src/bootstrap/attach_flow.ts(有单测)。
例外
root 读不到安装目录的宿主(AppImage —— payload 在没开 allow_other 的 FUSE 挂载上;以及单用户 FUSE 家目录)跑不了 elevated worker,连 exec 我们自己的二进制都是 EACCES(env: "…": 权限不够)。这类宿主改为「root 只临时放开 yama ptrace 保护 → 非特权进程自己读 → 写回原值」,见 apps/desktop/src/main/attach_elevation.ts 的 escalateViaPtraceScope。
6.1 取物料
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
scanSessionMaterial(pid, uin?, uid?) | pid + 账号 uin / uid(可选) | Promise<SessionMaterial> | 运行时 RTTI 自举、零硬编码 RVA,读出该会话的 a2 / d2 / d2key 与 SecToken(a2/d2/d2key 是十六进制串,SecToken 是 12 字符 base64 原文;没扫到的项为 undefined,不影响其它项)。uin / uid 只用于给 SecToken 的候选消歧(Windows 的记录附近带 uid,macOS/Linux 带 uin)。失败时 reject,错误信息本身就是提权/版本变化的诊断提示。 |
readDeviceGuid(dataRoot) | QQ 数据根路径 | string | null | 离线算出设备 guid(32 位小写 hex)。不需要任何权限、不碰进程;算不出返回 null。 |
writeDeviceGuid(dataRoot) | QQ 数据根路径 | string | null | 随机换一个设备 guid 并写回数据目录,返回新值。三端各改写自己那份来源(Linux machine-info 的 MAC / macOS machineid-info 的 machine_id / Windows Registry20 或 Registry2.0.db)。与 readDeviceGuid 一样同步——只改文件,不 await 任何东西。调用方必须先确认没有 QQ 实例在跑(在线时会被 QQ 覆盖回去);不需要权限。老产物没有这个方法,调用方要按"旧产物"处理。 |
setSsoSession(pid, session, wrapperPath?) | 物料 + wrapper.node 路径 | Promise<void> | 登记这一场会话。只存不连:不读内存、不发包时一个 socket 都不存在;TCP 等到第一次发包才建,闲置一分钟丢弃,断了下次发包自动重连。 |
hasSsoSession(pid) / clearSsoSession(pid) | pid | Promise<boolean> | 诊断 / 忘掉物料(账号下线、QQ 重启时调用,会一并关掉可能存在的连接)。 |
SessionMaterial = { a2?: string; d2?: string; d2Key?: string; secToken?: string }secToken只对需要签名的命令有意义,缺它不阻塞发包;但本地缓存复用的判据(canReuseSessionMaterial)要求它也在,否则升级后老物料会一直复用、签名始终缺 token。- 扫描 resolve 不代表物料完整:attach 缓存只保留三项均为有效 hex 且 d2key 为 16 字节的结果,部分结果原样返回、不跨扫描合并。账号 monitor 即使已有未过期的 rkey/clientKey,也会补齐当前 PID 的物料;失败按 30 秒起、最长 5 分钟退避重试。uid/guid 暂缺只检查账号配置及补读离线设备身份,不读内存、不弹密码框;仅用户明确取消授权会暂停本 PID 的自动重试。原生登记完成后仍通过
onlineCredentialsReady通知界面重查实际能力,不把提交密码当作成功。 - 桌面端能力查询同时返回账号身份是否齐全、是否需要重新读内存,以及
hasSsoSession确认的ssoReady。在线能力受限仅在当前 PID 的有效物料、账号/设备身份和原生登记都就绪后解除;查询不触发内存读取或网络请求,异步查询期间切号会拒绝旧结果。 credentialsPending包括正在读取、等待授权、原生登记和未取消的自动重试,不包括登记完成后的网络取票。界面保留「正在启用 QQ 在线能力」及常驻进度;提交授权后须等新的状态查询完成,不用提交前缓存的就绪状态提前结束。- 长期授权助手存在但需要修复(协议/接口/有效期/通道不匹配)时,
attach不再静默回退:监视器把credentialsPending置为 false,并通过credentialsIssue把原因交给「在线能力受限」详情;后台仍按退避重试,修复后自动恢复。 - SIP 开启且直接读取、长期助手均未取得调试读取权限时,桌面端抛出
DebugReadUnavailableError;监视器保留退避重试,但等待期间的credentialsPending为 false,让界面显示 QQ 调试副本引导,不持续冒称正在启用。实际读取及登记中的进度判定不变。 - 前端授权请求优先于
credentialsPending:存在尚未提交的密码或 ptrace 引导请求时显示「待提权」,标题栏、详情和横幅均暂停进入中进度;最后一项请求处理后才恢复进入中。横幅原地更新,避免退场动画残留相反的阶段提示。 SsoSessionConfig = { uin; a2: Buffer; d2: Buffer; d2Key: Buffer; guid; uid; subAppId; secToken?; qua?; clientConnSeq?; traceParent? }(traceParent只给离线比对用)。secToken/qua是签名三件套里本进程算不出来的两项:签名函数跑在 WeQ 里、没有 QQ 的登录会话,产出的SecToken/SecExtra恒为空。前者由scanSessionMaterial从 QQ 内存扫出,后者由major.node解析的 QUA 本地拼成;两者都缺时退回签名函数的空产出(旧行为),不会报错。 ⚠️subAppId必须等于当前运行 QQ 构建的 appid(major.node里QQAppId/537xxxxxx,resolveAppidFromMajor扫出来的那个值);QQ 每次更新 都会换 appid,用错值服务端一律回Reply status error: -10003 身份验证失败。 WeQ 侧见packages/service/src/account/sso_session.ts的resolveSubAppId(不传就动态解析,兜底常量只是应急)。
刻意不做上线注册与心跳
(对照 ../LagrangeV2):那是个纯协议框架,机器上只有它一个客户端,所以它必须自己发 SsoInfoSync 上线、自己心跳。我们不是 —— a2/d2/d2key 就是从同机 QQ 进程内存里读的,那条会话的在线状态与心跳由 QQ 本体维持;再注册一次只会让服务端看到「同设备 guid + 同一份 d2 的第二个客户端」。这里只借凭据发包,其余交给 QQ。
6.2 发包(pid 需先经 setSsoSession 登记)
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
sendOidbPacket(pid, command, subCommand, body, isUid, needSign?, mode?) | OIDB 命令/子命令/protobuf body/isUid | Promise<Buffer> | 通用 OIDB 发包:任何 OIDB 请求都行,无需改 native。isUid=true 走 UIN-form 变体(reserved=1)。needSign(缺省 true)与 mode(签名器 VM mode,缺省 3)由 @weq/protocol 的签名表解析后传入。 |
sendPacket(pid, cmd, body, needSign?, mode?) | 完整 SSO 命令串 + protobuf body | Promise<Buffer> | 通用原始发包,给不是 OIDB 的 trpc 服务用(命令串如 QunAlbum.trpc.qzone.webapp_qun_media.QunMedia.GetMediaList)。needSign / mode 同上。 |
resetPacketSequence() / currentPacketSequence() | — | number | 全局发包序号。重连 / 换会话时先 resetPacketSequence() 回收起点;currentPacketSequence() 仅供诊断。 |
locateSignFunction(wrapperPath) / signPacket(wrapperPath, cmd, src, seq) | wrapper.node 路径 + 命令 + 明文 + 序号 | RVA / SignOutput | wrapper.node 签名函数的定位与调用:needSign 的命令靠它算 SecSign(以及本进程里恒为空的 SecToken / SecExtra)。离线逐字节核对抓包用 buildSsoPacket(req)。 |
warmupSigner(wrapperPath, signCoreRva?, vmRva?) / checkSigner(wrapperPath, repeat?) | wrapper.node 路径 + 可选 RVA / 重复次数 | Promise<boolean> / SignCheckReport | 预热签名器与自检:首次调用要建 VM 解释器,几百毫秒;自检报告用来看签名是否稳定(新旧 wrapper 兼容性排障)。 |
signerRvas(wrapperPath) | wrapper.node 路径 | SignerRvas | null | 只探测、不预热:返回签名核心与 VM 的 RVA,供诊断页展示。 |
signPacketWithToken(wrapperPath, cmd, src, tokenHex, extraHex, mode?) | + 外部传入的 token / extra | SignOutput | 已有 SecToken / SecExtra 时直接签名(不需要自己算)。 |
signRedBagRequest(signInput) | 待签字节 | Buffer | 红包请求的专用签名,与主签名链分开。 |
原生发包按 PID 复用连接。已开始发送的请求超过 30 秒仍未收到应答时,回收该连接并唤醒其余等待者;凭据登记保留,后续请求懒建新连接,不自动重发旧请求。超时仍返回 sso_request_outcome_unknown_timeout,表示无法确认本次动作是否已生效;正常收到的业务拒绝不因此断线。该恢复行为需要包含此修复的 native,只有更新 WeQ 的 TypeScript 代码或刷新页面不会替换已加载的原生产物。
needSign 只收当前平台的值
QQ 的签名集合按平台不同(Linux / Windows / macOS),@weq/protocol 的 sign-policy.ts 按 wire 命令查表再解析成本平台的值传进来;不要在这里按白名单或并集推导,业务代码也不要 绕过 transport.ts 直接调这两个接口。
业务命令不在 native
clientKey / 下载 rkey / decryptKey / skey / p_skey / bkn 的请求构造与解析已经在 @weq/protocol + @weq/service(account/online_ticket.ts)里实现,只通过上面的两个通用 接口发包。新增「走后门业务」继续走 sendOidbPacket / sendPacket + TS schema, 不要为此改 native 引入新接口。
唯一的例外是登录流程自己
quickLogin / qrLogin 在换到 a2/d2/d2key 的那条连接上顺带发 0xcde_2(dbkey)与 0x102a_0(pskeyDomains → p_skey,一域一轮,默认 vip.qq.com + qzone.qq.com)。 这两步必须在登录连接里完成(会话物料刚拿到、连接还热),所以留在 native;除此之外的业务 命令一律走上面的通用接口,不要在 login 里继续加。
7. 网卡抓包(capture)
非侵入式、不注入:直接读网卡 → TCP 重组 → MSF 帧切分 → 用调用方传入的 d2key 做 TEA 解密(native 不再自己扫密钥)。
7.1 为什么是「会话 + 游标」而不是一次抓 N 秒
pcap_open_live + 装 BPF 过滤要几十到几百毫秒,而被抓的应答可能个位数毫秒就回来 (例如 QQ 语音转录:请求 → 立即 ack → 真正的结果稍后由服务端 push 推回)。先发包 再开抓,首包必漏。所以抓包是一条可提前 armed 的长生命周期会话:
startCapture(pid) // 直到网卡已打开、BPF 已装、读循环即将开始才 resolve
→ 调用方发包(setSsoSession / sendOidbPacket / sendPacket …)
→ takeFrames(pid, { waitMs: 10_000 }) // 等到窗口结束,一次性取回全部帧,自己筛
→ stopCapture(pid)取帧是环形缓冲 + 游标的拉模型:native 侧保证不漏,环形满了会如实把 dropped 报出来;onFrame 回调只是同一份数据的可选推送通道,JS 慢顶多丢投递,不影响 环形缓冲里的真相。会话按 pid 索引,与 setSsoSession 一致;多个 QQ 进程可各抓各的。
7.2 接口
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
probeCaptureSupport() | — | CaptureSupport | 抓包后端是否就绪。Windows 检查 Npcap(wpcap.dll);Linux/macOS 后端一定在,能否抓到取决于 elevated(权限)。hint 是缺后端/缺权限时的引导。 |
startCapture(pid, options?, onFrame?) | pid + 可选 CaptureOptions + 可选回调 | Promise<CaptureSession> | 开启(或替换)抓包会话。请在发包之前调用 —— 它直到网卡已打开、BPF 已装、读循环即将开始才 resolve。 |
takeFrames(pid, options?) | pid + 可选 TakeOptions | Promise<FrameBatch> | 取帧。waitMs > 0 时一直收集到窗口结束再返回。 |
stopCapture(pid) | pid | Promise<CaptureStats> | 停止并释放,返回统计。 |
桌面应用的 startAccountCapture 另返回应用层 sessionId,UI 和在线转写在轮询、停止时回传它。它不是 nt_helper 原生选项:原生仍按 pid 管理和替换会话。应用层串行化同 pid 的启动/停止,并在轮询前后检查身份,避免旧窗口关闭或迟到结果影响后来建立的会话。旧 IPC 请求可不带此字段,兼容原参数;新调用方应始终使用返回的 ID。会话 ID 仅在运行期间持有,不写入账号配置或设置备份。
类型
CaptureOptions = { d2key?; iface?; port?; ringFrames?; pcapFile? }d2key:32 字符 hex;省略时回退到该 pid 已登记的setSsoSession物料里的 d2key。iface:默认auto(自动选默认路由出口网卡),也可填eth0/en0/Npcap 设备名。port:默认auto(持续按 MSF 帧签名识别,端口中途切换也不漏);也可14000/14000,443,80/auto,443。ringFrames:环形缓冲帧数上限(默认 512)。
CaptureSession = { pid; iface; port; linktype }TakeOptions = { cursor?; waitMs?; minFrames?; maxFrames?; matchCmd? }CapturedFrame = { cursor; ts; direction; proto; encryptType; seq; cmd?; body?: Buffer; plain?: Buffer; raw: Buffer }cmd/body/plain在 TEA 解密 + SSO 头解析成功后才有;raw永远是完整原始帧(含 4 字节长度前缀)。body是解密后的 protobuf 原始字节,展开交给@weq/protocol—— native 不引 protobuf 描述符。
FrameBatch = { frames; nextCursor; dropped }:dropped是累计溢出淘汰帧数;nextCursor下次原样传回来即可续取。CaptureStats = { frames; dropped; packets }CaptureSupport = { available; backend; elevated; hint }
7.3 语音转录(异步结果)的用法
服务端的异步推送落在 startCapture 之后,所以「请求 → 监听 10 秒 → 自己筛」是安全的:
await nt.startCapture(pid, { d2key }); // 先 armed(早于发包)
try {
await nt.sendPacket(pid, 'pttTrans.TransC2CPttReq', body);
const batch = await nt.takeFrames(pid, { waitMs: 10_000 }); // 窗口内全部帧
// batch.frames 里自己按 cmd / body 筛出 TransC2CPttRsp 与 OlPushService.MsgPush
} finally {
await nt.stopCapture(pid);
}7.4 权限与依赖
- Linux:需要 root 或
CAP_NET_RAW(与 attach 同档);产物静态链接 libpcap,不依赖用户机的libpcap.so.*。 - macOS:需要 root(BPF 设备默认 root 可读)。
- Windows:需要管理员 且 已安装 Npcap;缺失时
probeCaptureSupport()返回available: false+ 安装引导。
7.5 WeQ 侧怎么拿到这个权限(提权子进程)
Electron 不能以 root 运行,而抓包要 root —— 所以桌面端把「抓包会话」整段放进一个 临时 root 子进程,主进程只做代理:
渲染层点「开始抓包」
→ 主进程(wonderful_tools.captureStart)先登记 SSO 会话(读内存拿 d2key)
→ sudo -S 起 captureWorker.mjs(ELECTRON_RUN_AS_NODE,见 src/main/capture_elevation.ts)
→ 子进程 require nt_helper.node,拿到 {port, token} hello 后走环回套接字协议
→ 主进程把 start / take / stop 原样转给子进程(协议见 src/main/capture_protocol.ts)要点:
- 密码来自渲染层自绘的密码框(
elev::request-password,macOS 姿势的sudo -S,不走 polkit); 起子进程前先sudo -n true探一次缓存,刚刚读过内存的机器不会再弹第二个框。 - 协议走 127.0.0.1 环回套接字而不是 stdin/stdout:
sudo -S要从 stdin 读密码,复用同一条 管道会被 sudo 的缓冲读写吃掉。hello 里的随机token是门禁(端口只有本机可达)。 - 子进程是另一个 native 实例,主进程
setSsoSession注册的物料它看不见,所以start必须显式带d2key;setcap cap_net_raw,cap_net_admin+eip <binary>也能免掉提权, 但不改系统是默认选择。 - 生命周期:主进程持着环回连接,断开(退出 / 崩溃)时子进程自己停会话再退出;退出时会 主动
dispose。不会把 root 抓包留在后台。
7.6 UDP 抓包(同一套接口,transport: 'udp')
UDP 复用上面的 start / take / stop,只多一个选项:
| 字段 | 说明 |
|---|---|
CaptureOptions.transport | 'tcp'(默认,MSF 帧解密)或 'udp' |
CapturedFrame.udp | UDP 五元组 + 载荷;TCP 帧为 null |
UDP 模式下 cmd / body / plain 恒为空,raw 是完整 IP 包。不解析任何业务 协议 —— 载荷原样交给调用方。
两个内核行为必须知道(2026-10-30 真机验证):
- socket 必须在目标 cgroup 内创建。
cgroup/sendmsg只对属于被 attach 的 cgroup 的 socket 生效,而 socket 归属创建它时进程所在的 cgroup —— 事后移动进程 无效。所以会话要在目标进程创建 socket 之前 armed;已存在的 socket 由seed_existing(pidfd_getfd+SO_COOKIE)补登记。 sendmsg(2)≠sendto(2)。cgroup/sendmsg4|6只拦sendmsg。实测 QQ 的 avsdk 用的是sendmsg,所以能抓到;若哪天改用sendto,只能靠seed_existing兜底。
另有一个独立接口,用于抓包面板的进程选择:
listProcessesWithModule(moduleHint: string): ProcessScanEntry[]
// ProcessScanEntry = { pid, ppid, name, cmdline, modules: string[] }列出所有映射了路径含 moduleHint 的库的进程(大小写不敏感)。传 "avsdk" 就是 「找 QQ 的通话媒体进程」(Chromium 的 --type=ppapi 子进程)。只读进程元数据 (maps / 模块列表),不附加、不读内存、不联网。老产物没有这个导出,调用方先用 typeof 探测。
8. 通话与媒体编解码
QQ 的语音 / 视频不是标准编码:语音是腾讯改过码表的 Opus,私聊视频用 t265(改过的 x265), 群通话用 H.264。所以必须加载 QQ 安装目录里那一版插件,不能拿系统 libopus / libx265 代替 —— 两边码表不一致时,对端听到的是噪声、看到的是一屏花屏。
modulesDir 传 QQ 的 resources/app(Linux 下的 avsdk/libAVSDKPlugin.so 也在这个目录树里)。 每个编解码器进程内只打开一次,重复调用幂等;挂断时对应 close*。
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
openCallCodec(modulesDir) / closeCallCodec() / isCallCodecOpen() | QQ resources/app | Promise<void> / void / boolean | 语音编解码器。 |
encodeCallFrame(pcm) | 640 字节 16 kHz 单声道 16-bit PCM(小端) | Buffer(Opus) | 一帧固定 20 ms(320 采样),不接受其它长度 —— 服务端按 20 ms 排帧。 |
decodeCallFrame(opus) | 一帧 Opus | Buffer(640 字节 PCM) | 反过来解一帧。 |
openVideoEncoder(modulesDir, width?, height?, fps?, bitrateKbps?, keyint?, allIntra?) | 可选参数缺省用与客户端一致的 640×360 / 15 fps / 400 kbps | Promise<void> | 私聊视频(H.265 / t265)。 |
encodeVideoFrame(y, u, v) | I420 三个平面(Y 全尺寸,U/V 各 1/4) | VideoFrameResult | null | Annex B 裸流。编码器还在 lookahead 里攒帧时返回 null,下一帧再取。 |
openH264Encoder(...) / encodeH264Frame(y, u, v) / closeH264Encoder() / isH264EncoderOpen() | 同上 | 同上 | 群通话用的 H.264(libopenh264.so)。目前只有 Linux 支持:macOS / Windows 的 openh264 没有独立动态库。 |
VideoFrameResult = { data: Buffer; keyframe: boolean }(含 00 00 00 01 起始码)。
9. 平台相关 / 其它
| JS 函数 | 参数 | 返回 | 说明 |
|---|---|---|---|
checkWindowsHelloAvailability() | — | Promise<{ code: number; available: boolean }> | 查询 Windows Hello 可用性。非 Windows 恒返回 NotSupported(100)。 |
verifyWindowsHello(message, hwnd?) | 提示文案 + 可选 hwnd(预留) | Promise<{ code: number; success: boolean }> | Windows Hello 弹窗验证。实现细节勿改:native 在专用 MTA 线程执行 WinRT 异步,避免 Electron STA 主线程死锁。 |
10. 常见坑 & 约定
- 先
getInitStatus()再干活:环境校验失败时,check_init!类函数会抛EnvIrreversiblyError/"Environment validation failed";check_init_or_default!类则返回“失败默认值”(如 probe 返回success:false)而非抛错。调用方两种都要处理。 setLogPath尽早调用:每个接口内部都会logger::init_logger(),日志目标取决于当时配置。默认只记 info 及以上事件;高频路径(probeDbLock、closeDb、testDatabaseKey、逐包接收、端口探测)都在 debug 级。排查时用setDebugLog(true)运行时抬到trace(首选,不用重启、不用改环境变量),或启动前设WEQ_LOG_LEVEL=debug|trace(error/warn/off也可)。loader 侧的逐文件资产校验同理,用WEQ_NATIVE_DEBUG=1打开。- 连接缓存:
executeSql*对同一dbPath缓存连接。登出 / 换号记得closeDb/closeAllDb释放句柄与密钥。 - SQL 只读优先:
executeSql注释明确“SELECT only recommended”;写接口存在且可用,但改动 QQ 运行时数据库前务必先备份。 algo别假设:QQ NT 各库、各客户端版本的 page/KDF HMAC 不固定。未知库一律先testDatabaseKey,得到CipherAlgo再喂给其它函数;不要硬编码SHA1/SHA1。- 在线发包需先登记物料:
sendOidbPacket/sendPacket的前提是「该 pid 已setSsoSession登记过、且物料来自在线 QQ」。 - 业务命令去 TS 找:
clientKey/ rkey / decryptKey / skey / p_skey / bkn 见packages/protocol与packages/service/src/account/online_ticket.ts,不要在 native 层重复实现。 - 不要重复造轮子:上面列的每一项 native 能力都已实现并经过验证。给 WeQ 加功能前,先在本页 /
packages/db/packages/protocol里找现成能力
11. 相关链接
- 源码:
../nt_helper/src/(Rust / napi-rs),入口lib.rs - 使用示例:
apps/desktop/src/main/attach_worker.ts(加载 + 初始化 + 调用) - 数据库层封装:
packages/db(基于executeSqlWithKey等) - 纯协议登录(装号 / 取密钥):
packages/service/src/bootstrap/key.ts+nt_helper的quickLogin/qrLogin
