feat: 增加 Native Hook 符号化与 Excel 导出

[qiqingzhixin]

变更

• 增加 get_symbols 批量符号化接口，支持 demangle、源码位置、内联链、缺失 SO 汇总和显式 SO 名称映射。
• 增加调用方持有的进程内 SymbolResolver，复用 SO 路径索引、模块命中/缺失缓存和 Symbolizer。
• 保留单次调用兼容函数 get_symbols。
• 增加 kat-native-hook-symbolize CLI，从 trace_streamer SQLite 导出 Excel 和 missing_modules 工作表。
• SQLite/Excel 仅作为真实 Trace 到符号结果的串联验证胶水，不作为独立生产级数据管道。
• 增加独立的符号化 SDD；不包含应用操作或真机采集脚本。

核心代码调用方式

单次调用 get_symbols

use std::{collections::HashMap, path::Path};

use kat_rs_native_hook_symbolize_poc::get_symbols;

let addresses = vec![
    "/system/lib/ld-musl-arm.so.1+0x1234".to_owned(),
    "/system/lib/libexample.so+0x5678".to_owned(),
];
let module_name_map = HashMap::from([
    ("/system/lib/ld-musl-arm.so.1".to_owned(), "libc.so".to_owned()),
]);

let result = get_symbols(
    &addresses,
    Path::new(r"D:\zxlDown\images\laster"),
    &module_name_map,
    true,
)?;

for symbol in result.symbols {
    println!("{symbol}");
}
for missing in result.missing_modules {
    eprintln!("{}: {}", missing.module_path, missing.occurrence_count);
}

参数约定：

• addr_list：批量输入，地址格式为 模块路径或名称+0x十六进制地址；不能解析的输入保持原样。
• symbol_dir：本地符号表根目录；存在合法地址输入时，目录不存在会报错。
• module_name_map：Trace 中的 SO 名称/路径 -> 符号目录中的 SO 名称/路径；可传空表。
• include_source_location：true 返回完整源码路径、行号和内联链；false 只返回函数符号。
• 返回值 SymbolizationResult：symbols 与输入顺序一一对应；missing_modules 汇总未找到的 SO 及出现次数。

项目内连续调用

整个项目连续处理多批地址时，推荐在进程内复用同一个 SymbolResolver：

use std::collections::HashMap;

use kat_rs_native_hook_symbolize_poc::SymbolResolver;

let mut resolver = SymbolResolver::new(r"D:\zxlDown\images\laster");
let module_name_map = HashMap::new();

let first = resolver.get_symbols(&first_batch, &module_name_map, false)?;
let second = resolver.get_symbols(&second_batch, &module_name_map, false)?;

SymbolResolver 首次遇到合法查询时建立一次目录索引，并缓存模块命中和缺失结果。实例存活期间应将符号目录视为只读；目录内容变化后创建新实例。

Trace 转符号示例

cargo run -p kat-rs-native-hook-symbolize-poc `
  --release `
  --bin kat-native-hook-symbolize -- `
  target/trace/run/trace.db `
  --symbol-dir D:/zxlDown/images/laster `
  --output target/trace/run/symbols.xlsx `
  --module-map /system/lib/ld-musl-arm.so.1=libc.so `
  --include-source-location

输出 Excel 的 symbols 工作表包含 callchain_id、depth、original_symbol 和 resolved_symbol；missing_modules 工作表记录缺失 SO 和出现次数。超过单个 Excel 工作表上限时自动分页。

真实 120 秒 Trace 测试

测试条件：Release 模式；符号目录 D:\zxlDown\images\laster，约 23.37 GB、3171 个 SO；启用源码位置、行号、内联链和 musl loader 名称映射。Release 构建耗时不计入转换耗时。

数据与转换结果

指标	结果
Trace 实际时长	119.832 秒
trace.db 大小	42,143,744 B
Native Hook 栈帧总数	131,949
已经是符号或无需转换的输入	60,227
待转换地址	71,722
成功转换地址	69,517
地址转换成功率	96.93%
包含源码文件和行号	68,003
包含内联调用链	26,197
未转换地址	2,205
Excel 大小	2,554,987 B

2,205 条未转换地址全部来自同一个缺失模块：

/vendor/lib/chipsetsdk/libmali-bifrost-g52-g7p0-ohos.so

耗时

场景	耗时
冷缓存 SQLite -> get_symbols -> Excel	36.739 秒
热缓存 SQLite -> get_symbols -> Excel	8.589 秒
热缓存读取 SQLite	0.341 秒
热缓存 get_symbols 首次实例调用	5.443～7.712 秒
同一进程复用 SymbolResolver，相同批次再次调用	0.448 秒
写入 Excel	2.723 秒

热缓存 get_symbols 处理速度约 2.42 万帧/秒。相同批次复用实例约 29.5 万帧/秒，属于目录索引、模块路径和文件系统缓存充分的最佳情况；不同地址批次会高于 0.448 秒，但仍能复用目录索引和模块缓存。

批量规模回归

以下是基于一份真实 30 秒帧序列进行 1×/2×/4× 复制的核心接口规模测试，用于观察输入规模增长趋势，不等同于真实 60/120 秒采集结果：

等效规模	总输入	每次新建实例	复用实例	提升
30s / 1×	282,982	2,593 ms	395 ms	6.6×
60s / 2×	565,964	3,887 ms	1,065 ms	3.6×
120s / 4×	1,131,928	5,981 ms	2,509 ms	2.4×

验证

• cargo test -p kat-rs-native-hook-symbolize-poc：14 passed（9 个库测试、3 个 CLI 单元测试、2 个 CLI 集成测试）。
• cargo fmt --all -- --check。
• cargo clippy -p kat-rs-native-hook-symbolize-poc --all-targets -- -D warnings。
• git diff --check。
• PR CI：pr-guard、test 均通过。
• 真实 120 秒 Trace 已完成 SQLite 读取、批量符号化、缺失模块汇总和 Excel 导出的完整串联验证。

Trace 采集由 #166 独立交付。

Closes #169

Refs #152

[qiqingzhixin]

Branch was pushed to the upstream repository by mistake. Replaced by fork-based PR #170.