feat: 增加 Native Hook 应用 Trace 采集

[qiqingzhixin]

变更

• 将通用 Trace 编排与应用操作场景分离：采集流程只依赖场景名称、目标 Bundle、prepare 和 exercise。
• 提供 ApplicationScenario interface，以及 CalculatorScenario、NoteScenario 两个 adapter；后续应用通过新增并注册 adapter 扩展。
• 新增 --scenario {calculator,note} 参数，默认仍为 calculator，保持原有命令兼容。
• calculator 场景在采集前校验 100 * 100 = 10000，采集期间动态发现按钮并持续随机点击。
• note 场景启动 com.ohos.note/MainAbility，确认 pages/MyNoteHome，在采集前从搜索框边界计算并缓存左、中、右三个安全点，采集期间持续随机点击。
• 场景启动和必要准备是硬条件；profiler 启动后的随机操作只用于制造负载，失败记录告警但不否定成功生成的 Trace。
• 所有点击坐标均从本次真实布局动态计算，不硬编码屏幕坐标。
• 不使用 hmdriver2、Hypium Python Driver，也不创建、构建或安装额外 HAP。
• SQLite 和 Excel 仅用于串联、验证 Trace 与符号转换，不在本 PR 建设生产级数据管道。

使用

脚本只使用 Python 标准库，无需安装额外 Python 依赖：

py tools/native_hook_capture.py --scenario calculator --duration 30
py tools/native_hook_capture.py --scenario note --duration 30

省略 --scenario 时默认使用 calculator。多设备或工具不在 PATH 时：

py tools/native_hook_capture.py `
  --scenario note `
  --duration 60 `
  --target 7001005458323933328a521c3c503800 `
  --hdc D:/soft/hdc/toolchains/hdc.exe `
  --trace-streamer D:/soft/trace_streamer_binary/trace_streamer_windows.exe

成功产物位于 target/trace/YYYYMMDD-HHMMSS/，包含 native_heap.htrace、trace.db、hiprofiler.log、uitest.log 和 trace-streamer.log。核心产物是 htrace；数据库是当前串联验证产物。

验证

• 目标设备：7001005458323933328a521c3c503800，API 26，uitest 7.0.0.1。
• calculator：前置结果 10000，动态发现 18 个按钮。
• note：动态发现三个搜索框安全点，30 秒采集期间随机点击 14 次，未修改笔记数据。
• 备忘录数据库的 143,913 条 native_hook 记录全部关联 process.name=com.ohos.note。
• 最新 10 秒主流程回归生成 38,917,475 B htrace。
• py -m py_compile tools/native_hook_capture.py tools/test_native_hook_capture.py
• py tools/test_native_hook_capture.py：27 passed。
• git diff --check

场景	配置时长	数据库时间范围	htrace 大小	trace.db 大小	native_hook 行数	结果	随机点击
calculator	30 秒	29.83 秒	42,669,350 B	16,986,112 B	182,324	10000	26
calculator	60 秒	59.89 秒	50,121,912 B	28,323,840 B	362,378	10000	26
calculator	120 秒	119.83 秒	58,813,446 B	42,143,744 B	572,425	10000	81
note	30 秒	28.20 秒	45,050,281 B	29,716,480 B	143,913	首页搜索框	14

四次均完成 trace_streamer 转换。

符号转换由 #170 独立交付。

Closes #168

Refs #152

[qiqingzhixin]

Review Agent 评审结果（head 87b7f784）

固定对象：base / merge-base 02312047，head 87b7f784；实际变更为 4 个文件，新增 1146 行。PR 当前为 Draft、MERGEABLE、BEHIND；CI 的 test、pr-guard 成功，full-test 跳过。

总分 ★★★★☆
├── 冷读评审 ★★★★☆
│   ├── 表达结构 ★★★★★ high
│   ├── 信息自足性 ★★★★☆ high
│   └── 命名准确性 ★★★★☆ high
├── 一致性评审 ★★★★☆
│   ├── 对象—设计一致性 ★★★★☆ high
│   └── 决策演进完整性 ★★★★☆ medium
└── 同行评审 ★★★★☆
    ├── 技术成立性 ★★★★★ high
    └── 生态适配性 ★★★★☆ high

三个分支父分均为 4 星，因此总分为 4 星。

冷读评审 findings

CR-F1：设计文档没有说明 #152 与 #168 的关系

• Problem：PR 关闭 feat: Native Hook 应用 Trace 采集 #168、引用 feat: Native Hook Trace 采集与符号转换 #152，但设计文档只关联 feat: Native Hook Trace 采集与符号转换 #152，没有说明 feat: Native Hook 应用 Trace 采集 #168 是拆分需求、验收载体还是交付跟踪项。
• Static evidence：docs/superpowers/specs/2026-07-20-native-hook-trace-capture-design.md:3；PR 正文末尾的 Closes #168 与 Refs #152。
• Project impact：仅阅读 PR 和设计文档时，无法完整重建“总需求—子需求—设计—交付”的对应关系。
• 限制叶子：信息自足性。

CR-F2：模块说明仍把脚本描述成计算器专用

• Problem：模块 docstring 仍写着操作 distributedcalc，但脚本已经是 calculator 和 note 双场景通用入口。
• Static evidence：tools/native_hook_capture.py:2,20-22,473-498。
• Project impact：阅读模块首部或生成模块文档时，会把通用采集入口误认为计算器专用脚本。
• 限制叶子：命名准确性。

CR-F3：PR 正文中的 Excel 语境不够准确

• Problem：PR 正文把 SQLite 和 Excel 并列为串联验证组成，但设计明确当前切片不实现 Excel，代码产物也没有 Excel。
• Static evidence：PR 正文“SQLite 和 Excel 仅用于串联”；设计文档 :10；tools/native_hook_capture.py:608-612。
• Project impact：无法仅凭 PR 正文确定 Excel 属于当前采集 PR，还是属于独立符号转换 PR。
• 限制叶子：命名准确性。

一致性评审 findings

CONS-F1：对象顶层自述没有跟随双场景设计演进

设计已经明确通用场景 seam 和两个 adapter，但模块 docstring 仍停留在计算器单场景，限制对象—设计一致性为 4 星。

CONS-F2：设计链路没有记录 #168

设计文档定义了完整最小切片，却只关联 #152，没有记录当前 PR 实际关闭的 #168，限制决策演进完整性为 4 星。

没有发现 accepted ADR 冲突：核心产物仍是 htrace；TraceStreamer SQLite 只作为临时串联验证胶水；没有把 TraceStreamer 表结构提升为 Hitrace Datasource 的可复用 facts；本 PR 不实现符号解析或 Excel 导出。

同行评审

技术成立性：★★★★★

静态同行评审没有发现限制技术成立性的 finding：通用采集流程与场景 adapter 边界成立；Calculator/Note 场景职责清楚；准备失败和采集期随机负载失败的分级符合需求；HDC、UiTest、hiprofiler 与 TraceStreamer 的组合与项目目标匹配。真机结果未在本轮复跑，仅作为 pending，不参与静态技术评分。

PEER-F1：.gitignore 保留了未交付的 Hypium 探索路径

• Problem：最终方案明确不使用 Hypium、不交付额外 HAP，但 .gitignore 仍包含 tools/hypium_calculator_probe 的专用规则。
• Static evidence：.gitignore:3-6；设计文档 :13-15。
• Project impact：已退出最终切片的探索目录被固化进仓库忽略策略，并可能隐藏未来同路径文件，降低交付边界的可审计性。
• 限制叶子：生态适配性。

Pending（不参与评分）

• 本轮没有重新执行 27 个 Python 测试。
• 没有复现 30/60/120 秒计算器和 30 秒备忘录真机采集。
• 没有重新核验 Trace 大小、数据库记录和进程关联。
• 其他设备与 UiTest 版本兼容性未知。
• Issue feat: Native Hook Trace 采集与符号转换 #152/feat: Native Hook 应用 Trace 采集 #168 仍记录旧交付 PR feat: 增加 Native Hook 应用 Trace 采集 #166；这是外部跟踪状态，没有用于当前对象扣分。
• PR 落后于 main，但当前显示可合并。

本轮只进行了静态评审，没有修改文件、运行测试或操作设备。