refactor-mpx-perf

.agents/skills/mpx2rn/references/rn-script-reference.md

@@ -687,36 +687,48 @@ createComponent({
 
 ## 运行时性能探针
 
-`@mpxjs/perf` 为 Mpx2RN 提供编译期按需开启的耗时聚合和 mark 时间线。使用前在 `mpx.config.js` 的 `pluginOptions.mpx.plugin.perf` 中设置 `enable` 与 `probes: ['framework', 'user']`；关闭态会通过 DefinePlugin、tree-shaking 与 Terser 消除探针实现和名称字符串。
+`@mpxjs/perf` 为 Mpx2RN 提供编译期按需开启的三类性能统计。使用前在 `mpx.config.js` 的 `pluginOptions.mpx.plugin.perf` 中设置 `enable` 与 `probes: ['framework', 'user']`；关闭态会通过 DefinePlugin、tree-shaking 与 Terser 消除探针实现和名称字符串。
 
 | API | RN 语义 |
 | --- | --- |
-| `start()` / `end(reporter?)` | 打开/结束录制窗口，并自动生成名为 start/end 的时间线边界。空窗口也会触发 reporter。 |
-| `scopeStart(name)` / `scopeEnd(id)` | 用数字句柄记录高频同步耗时；未录制时 start 返回 `-1`。 |
-| `measureStart(name)` / `measureEnd(name)` | 用同一个 name 配对跨作用域耗时，并聚合到同名桶。 |
-| `mark(name)` | 记录独立、有序的时间线里程碑，同名 mark 不合并。 |
+| `aggrStart(name, useName?)` / `aggrEnd(idOrName)` | 区段聚类统计，输出 count/sum/avg/max。默认数字 id 模式适合高频、嵌套、同名并发；传 `true` 改用 name 配对。 |
+| `traceStart(name, useName?)` / `traceEnd(idOrName, info?)` | 区段序列统计，保存每次开始位置和持续时长，可生成火焰图/瀑布图。默认数字 id 模式；传 `true` 改用 name 配对。 |
+| `mark(name, info?)` | 点序列统计，记录独立、有序的时间线里程碑，同名 mark 不合并。 |
+| `start(options?)` / `end(reporter?)` | 打开/结束录制窗口。`start` 可配置 `markLimit` / `traceLimit`，并自动生成 mark 的 start/end 边界。 |
+| `scope*` / `measure*` | 旧聚类 API 兼容导出，内部复用 `aggr*`；新代码优先使用 `aggr*`。 |
 
-Reporter 签名为 `(measures: Map<string, AggResult>, timeline?: MarkTimeline) => void`。`MarkTimeline.events` 中的 `at` 是相对当前 `start()` 的毫秒偏移；包含边界在内最多保留 256 条（start + 最多 254 个显式 mark + end），超出数量记录在 `dropped`，end 始终保留。
+Reporter 签名为 `(aggregates: Map<string, AggrResult>, marks?: MarkTimeline, traces?: TraceTimeline) => void`。正常结束的窗口始终传入 marks 和 traces；后两个参数保持可选，兼容一、二参数 Reporter。
+
+`MarkEvent` 与 `TraceEvent` 都使用 `start` 表示相对录制窗口的毫秒偏移、`timestamp` 表示原始时钟值；TraceEvent 另含 `duration`。两类事件都可保存可选 `info` 引用，调用侧应只传小型、可序列化的诊断字段。mark 和 trace 的默认容量均为 1024，分别用 `start({ markLimit, traceLimit })` 覆盖；trace 未完成区段计入 `incomplete`，容量溢出计入各自 `dropped`。
 
 ```ts
 import {
   start, end, mark,
-  measureStart, measureEnd
+  aggrStart, aggrEnd,
+  traceStart, traceEnd
 } from '@mpxjs/perf'
 
-if (__mpx_perf__) start()
-if (__mpx_perf_user__) measureStart('goods:request')
+if (__mpx_perf__) start({ traceLimit: 2048 })
 
-loadPageData().finally(() => {
-  if (__mpx_perf_user__) {
-    measureEnd('goods:request')
-    mark('goods:data-ready')
-  }
-  if (__mpx_perf__) end()
-})
+let renderId = -1
+let moduleId = -1
+if (__mpx_perf_user__) {
+  renderId = aggrStart('goods:render')
+  moduleId = traceStart('goods:module')
+}
+
+renderGoods()
+
+if (__mpx_perf_user__) {
+  aggrEnd(renderId)
+  traceEnd(moduleId, { module: 'goods' })
+  mark('goods:data-ready', { source: 'cache' })
+}
+
+if (__mpx_perf__) end()
 ```
 
-所有调用必须直接置于 `if (__mpx_perf__)`、`if (__mpx_perf_framework__)` 或 `if (__mpx_perf_user__)` 字面量门禁中，确保关闭分组时零残留。`mark` 仅用于时间线，不是 measure 起点；旧 `mark/measure` 耗时写法需直接迁移为 `measureStart/measureEnd`，旧 `measure` 不再导出。
+所有调用必须直接置于 `if (__mpx_perf__)`、`if (__mpx_perf_framework__)` 或 `if (__mpx_perf_user__)` 字面量门禁中，确保关闭分组时零残留。聚类 id 模式沿用数组槽位和 free list，适合高频 render；trace/mark 会保留事件对象，只用于有限插桩点和诊断窗口。同名并发、递归或嵌套的 aggr/trace 必须使用默认 id 模式，name 模式后一次 start 会覆盖前一次映射。
 
 ---