--- name: kuikly-recomposition-analyzer description: "Analyze KuiklyUI Compose DSL recomposition performance issues from Recomposition Profiler output. Use when the user mentions 重组分析、重组优化、卡顿分析、recomp 报告、recomposition analysis, or asks to analyze profiler_report.json / profiler_frames.jsonl log files generated by KuiklyUI Recomposition Profiler." --- # Kuikly Recomposition Analyzer 三阶段漏斗分析 KuiklyUI Compose DSL 的重组性能问题:report 筛查 → frames 深挖 → 源码确认。 ## 阈值配置 读取 `references/config.md` 获取默认阈值。用户在请求中指定参数可覆盖(如 `scopeCountThreshold=10`)。 ## 工作流 ### Phase 0 — 获取日志 读取 `references/log-format.md` 了解日志字段格式。按优先级获取 `profiler_report.json` 和 `profiler_frames.jsonl`: 1. 用户直接提供路径 → Read 工具读取 2. 检查当前目录约定路径:`./profiler_logs/`、`./profiler_report.json` 3. 自动从设备拉取 → 读 `references/log-retrieval.md` 执行对应平台命令 4. 均失败 → 输出引导: > 未找到 profiler 日志。请先采集数据: > 1. 在代码中调用 `RecompositionProfiler.start()` 开始录制,操作完成后调用 `stop()` > 2. 或在 Profiler Overlay 面板点击「开始」录制,操作完成后点击「停止」,再点击「获取报告」 > 3. 采集完成后告诉我文件路径,或提供 App 包名让我来拉取 ### Phase 1 — 数据健康检查 - `totalFrames < minFramesThreshold`(默认 30)→ 告警,询问是否继续 - `totalRecompositions == 0` → 提示无重组记录 - `filteredNames` 非空 → 报告中声明排除的组件 ### Phase 2 — Report 筛查 **前置步骤(必须先执行)**:按 `recompositionCount` 降序排列所有非 noScope 组件,列出 TOP 20。**任何 `recompositionCount > 50` 的组件必须进入报告**,无论总耗时多低。这一步防止高频但低耗时的组件被后续按总耗时排序时遗漏。 读 `references/detection-rules.md`,遍历 `composables[]`: | 条件 | 处理 | |------|------| | `noScopeRecompositions == recompositionCount` | 归入**正常重组清单**,跳过后续分析 | | `maxDurationMs > singleRecompDurationThreshold`(默认 10ms) | **无论重组次数多少,必须输出到报告**,进入 Phase 3 深挖 | | `scopeDistribution` 某 key 计数 > `scopeCountThreshold` | 标记嫌疑,进入 Phase 3 | | `paramChangeFrequency["#N"] / recompositionCount > paramChangeRateThreshold` | 标记 **RULE-C** 嫌疑(需结合源码判断参数类型) | | `triggerStates[i].readers.length > stateReadersThreshold` | 标记 **RULE-B** 嫌疑 | ### Phase 3 — Frames 深挖 + 源码确认 **注意**:`profiler_frames.jsonl` 是 JSONL 格式(每行一个独立 JSON 对象),不是单个 JSON 文件。必须逐行读取并 parse,不能整个文件当 JSON 解析。用 Read 工具读取后按行处理。 如果分析对象是 LazyList/LazyGrid/Pager 内的 item 组件,读取 `references/lazylist-rules.md` 了解 item 闭包重建与业务组件 skip 的区别。 逐行读 `profiler_frames.jsonl`,按 `type` 字段分流(`frame` / `touch_context` / `scroll_context`)。 **帧级检查:** 对每个耗时超标帧,按以下流程处理: 1. **先判断是否正常**: - 对照 `scroll_context`:若该帧紧跟滚动事件,且帧内事件以 `noScope`(首次组合)为主 → 归为**正常渲染开销**,在报告中简短说明原因,不进入后续分析 - 若帧内事件数很多但绝大多数是 noScope → 同上,属于列表滑入时的正常批量首次组合 2. **确认是真实问题后,做帧内根因分析**: - 找出帧内耗时最长的 composable 事件(`durationMs` 最大的几个) - 检查这些组件是否被同一个 State 级联触发(`triggerStates` 相同) - 对耗时最高的组件执行完整的链式推理(Step 1-5,同嫌疑项流程) 3. **报告中每个真实问题帧必须包含**: - 帧耗时 + 帧内事件数 - 判断结论(正常 / 有问题)及理由 - 若有问题:耗时最高的 1-3 个组件的名称、耗时、触发 State - 根因分析(参照链式推理 Step 2-4) - 优化建议(有具体方向时给出,无法判断时说明需要补充什么信息) - 单次 `composable_recomposed.durationMs > durationThreshold` → 进入链式推理 - 同帧多组件被同一 State 触发 → 级联嫌疑,分析该 State 的写入时机 **上下文辅助判断(touch/scroll 可用时):** - touchBegin~touchEnd 之间某 scope 重组 > 3 次 → 标注「一次点击触发 N 次重组,疑似可优化」 - scroll_context index 变化 + item 重组 ≈ 滑入数量 → 归入正常 - scroll_context index 未变 + item 重组 → 标注「非滚动导致的重组,需分析」 **源码确认(仅对确认嫌疑项):** 对每个嫌疑项,按以下链式推理步骤深入分析(不得跳过): **Step 1 — 定位代码** 取 `sourceLocation`(格式 `FileName.kt:行号`),用 `Glob "**/.kt"` 定位文件,读取函数声明及其周围 30 行代码。 **Step 2 — 理解数据信号** 回答:这个组件的 `scopeDistribution` 显示哪个 scope 被反复触发?`triggerStates` 显示是哪个 State 在驱动?`paramChangeFrequency` 中哪个参数每次都在变?把具体数值写出来(如「scope=223833166 被触发 61 次,平均耗时 0.75ms」)。 如果 `paramChangeFrequency` 显示某参数高频变化,**必须先判断变化的本质**: - **业务数据确实在变**(如滚动时坐标每帧不同、翻页时列表内容更新)→ 根因是写入逻辑,不是类型稳定性问题 - **数据内容没变但引用变了**(每次传入新实例,值相同但 `===` 不等)→ 才是类型稳定性或对象创建问题 两者根因完全不同,不能混淆。 **Step 3 — 追溯根因** 结合代码,回答:这个 State 是谁写入的?在什么时机写入?为什么每次重组都会触发?找到真正的"写入者"(不是"读取者")。如果 State 是在 `LaunchedEffect` / `onGloballyPositioned` / `snapshotFlow` 等副作用中写入,说明具体的触发时机。 **对于 CompositionLocal 子树重组,额外回答**:传入 `CompositionLocalProvider` 的值是新实例还是缓存实例?`CompositionLocalProvider` 用 `===` 引用比较,即使内容相同,每次传入新实例都会触发整个子树重组。根因可能是「每次重组都 `copy()`/新建对象」,不一定是类型不稳定。 **判断参数变化根因的通用流程**(适用于任何 paramChangeFrequency 高频情况): 1. 读源码找到参数的调用侧——是谁在传这个参数? 2. 传入的是新建对象(`copy()`、`listOf()`、lambda)还是稳定引用(单例、`remember` 缓存)? 3. 如果是新建对象:检查是否有必要每次新建,还是可以用 `remember` 缓存 4. 如果是稳定引用但还是判定为变化:才考虑类型稳定性(是否有 `var`、`List`、跨模块类型) **RULE-C 专项:命中 RULE-C 时额外执行** 读取 `references/stability-rules.md` 了解完整的稳定性判断规则,然后: - 读源码,按声明顺序将 `#N` 对应到具体参数名和类型 - **先判断变化本质**:参数值每次确实不同(业务数据在变)?还是值相同但每次传入新实例(引用不等)?前者不是稳定性问题,后者才考虑类型稳定性 - **`@Stable`/`@Immutable` 注解会覆盖编译器推断**:加了注解的类,编译器信任其稳定,不会因 `var`/`List` 判为不稳定。若加了 `@Stable` 但参数仍 100% 变化,真正原因是「每次传入新实例」而非类型推断问题 - **注意 `@Stable` + var 直接赋值的 bug**:skip 会发生,但界面不更新(显示过时数据),比「不 skip」更危险 - 若确认是「相同值重复创建新实例」,再按类型选方案,详见 `references/optimization-patterns.md` - **Strong Skipping 已开启时,禁止建议手写 `remember { { ... } }` 包裹 lambda**——手写是多余的。若 lambda 参数仍高频变化,问题在 lambda 捕获的变量稳定性 **Step 4 — 评估影响范围** 回答:这个 State 被几个组件订阅(readers)?这些组件是否都真的需要在每次 State 变化时重组?哪些是可以 skip 的?哪些是必须响应的? **Step 5 — 提出方案并说明权衡** 读取 `references/optimization-patterns.md` 获取对应规则的优化方案。给出 1-2 个具体优化方案,每个方案必须: - 提供修改前/后的代码对比 - 说明为什么这个改法能解决问题(从 Compose 运行时机制角度解释) - 说明可能的副作用或注意事项 - 如果有多个方案,说明推荐哪个,以及在什么场景下选另一个 **推荐加 `@Stable`/`@Immutable` 注解前,必须通过以下两项检查,任一不满足则不推荐:** 1. 类的属性是否满足注解的承诺(`@Immutable` = 构造后永不变;`@Stable` = 变化只通过 MutableState 通知)?若含 `var` 直接赋值,skip 仍会发生(注解让编译器信任),但**界面不会更新**(Compose 不知道值变了),会产生界面 bug 2. 调用方是否会复用实例或传相同引用?若每次都 `copy()`/`new`/`listOf()` 创建新对象传入,注解无法让 skip 发生 如果两项检查通不过,不要推荐加注解,而是从**调用方如何传参**或**数据模型如何设计**角度给出方案。 如果遇到分析受限的情况(无法定位源码、参数索引无法映射等),读取 `references/known-limitations.md` 确认是否属于已知限制,按限制说明处理。 ### Phase 4 — 输出报告 读 `references/report-template.md`,生成: 1. **对话摘要**:数据概览 + TOP 3 问题 2. **Markdown 报告**:`recomp-analysis-YYYYMMDD-HHmm.md`,含数据概览、正常重组清单、问题诊断(按严重度降序)、过滤配置声明。严重度评级和排序规则见 `references/detection-rules.md`:**总耗时**(重组次数 × 平均单次耗时)为第一排序维度,次数多但单次耗时极低的问题排在真正耗时高的问题之后。 **报告写作规范(必须遵守):** 1. **数据概览的帧统计**:只写帧数,不写占比。例如「慢帧:14 帧」,不写「14 帧(占 7.4%)」。 2. **问题描述禁止使用内部术语**:不得在问题描述中出现 `RULE-A`、`RULE-B`、`RULE-C`、`RULE-SCOPE` 等字眼。用用户能理解的语言描述,例如「每次滚动都触发该组件重渲染」而不是「命中 RULE-B」。规则标识只允许出现在**过滤配置声明**段。 3. **上下文描述要区分触发来源**:描述重组次数时必须明确是「一次点击触发 N 次重组」还是「N 帧滚动累计触发 M 次重组」,两者不可混用。若是跨多帧的累计,说明「在 X 帧滚动过程中,该组件共重组 N 次」。 4. **每个问题必须包含两个关键数据**:① 同一 scope 触发的重组次数(或总重组次数);② 平均单次耗时(avgDurationMs)。缺少任一数据时标注「数据不足,无法评估严重程度」。 5. **问题分析必须有深度**:根因分析要说明「谁在写这个 State、在什么时机写、为什么频繁触发」,不能只说「State 变化导致重组」。优化建议必须提供修改前后的代码对比,并解释为什么这个改法有效,不能只给出结论。 6. **原因不明时直接告知,并给出排查引导**:如果某个问题(如单次耗时异常)通过现有日志和源码无法定位根因,不要猜测或给出模糊结论。直接写:「当前日志不足以确定根因,建议进一步排查」,并给出具体的排查建议,例如: - 在该组件函数体内增加耗时打点(`measureTimeMillis`)定位慢在哪个子操作 - 或直接说「可以告诉我,我来帮你做更深入的分析」 7. **重组次数高但总耗时低的组件不能省略**:所有命中检测规则的组件都必须出现在报告中,不能因为总耗时低就跳过。对于重组次数明显偏高(如 >50 次)但单次耗时极低(<0.5ms)的组件: - 仍然列入报告,标注严重度为「低」 - 说明重组次数和平均耗时 - 如果未做深入分析,明确注明「单次耗时极低,暂未深入分析,但重组次数偏高,建议关注」 - 对于次数极高的(如 >100 次),即使耗时低也应做简要根因分析(至少说明是什么 State 在驱动、是否可以减少重组次数) 8. **尊重已有的 `@Stable`/`@Immutable` 注解,不质疑其准确性**: - 类已标注 `@Stable` 或 `@Immutable` → 编译器信任它是稳定的,**不要说「标注不准确」「标注是无效的」** - 类含 `Map`/`List`/`lambda` 属性但已标注 `@Immutable` → 注解覆盖了编译器推断,这是开发者的有意设计,不是错误 - Strong Skipping 已开启时,`@Stable` 类含 lambda 属性 → lambda 自动 `remember`,引用稳定,**不要说「lambda 引用稳定性取决于调用方」** - 如果加了注解的类参数仍然高频变化,问题在**调用方每次传入新实例**,不是注解有问题。分析方向是调用方如何传参,而不是质疑注解 9. **建议使用 `remember` 缓存对象时,必须分析依赖项**: - **禁止**直接建议无 key 的 `remember {}`,除非已确认对象创建不依赖任何外部状态 - 如果工厂函数内部可能读取 CompositionLocal(如主题色、字体大小、深色模式)→ `remember` 必须带正确的 key(如 `remember(isDarkTheme) { markdownColor() }`),否则主题切换后配置不更新,造成界面 bug - 如果**无法确认**工厂函数的内部依赖(没有读到源码)→ 不建议 `remember`,而是建议「检查该函数是否依赖主题等外部状态后再决定是否缓存」 - 错误示例:`val colors = remember { markdownColor() }` — 如果 `markdownColor()` 读了深色模式,切换主题后颜色不更新 - 正确示例:`val isDark = isAppInDarkTheme(); val colors = remember(isDark) { markdownColor() }` ### 形态 C:聚焦特定页面 用户说「我只想看 XX 页」时: > 请在 profiler 面板点「重置」按钮,进入目标页面操作一遍,然后让我分析。 ## References - `references/config.md` — 可配置阈值默认值 - `references/log-format.md` — report.json / frames.jsonl 字段说明 - `references/log-retrieval.md` — 各平台(adb/xcrun/hdc)拉取命令 - `references/detection-rules.md` — 检测规则详细逻辑 - `references/lazylist-rules.md` — LazyList item 重组分析规则(闭包重建 vs 业务组件 skip、错误结论规避) - `references/stability-rules.md` — Compose 稳定性规则(已实测验证):编译器推断规则、skip 条件、注解有效/危险场景、Profiler 中的表现差异 - `references/optimization-patterns.md` — 每条规则对应的优化方案和代码样例 - `references/known-limitations.md` — 已知限制(paramChanges 索引无参数名、不稳定类型 scope 重建等) - `references/report-template.md` — Markdown 报告模板