using-stability-analyzer-ide-plugin

使用 Stability Analyzer IDE 插件——在编辑器中实时获取稳定性反馈

Compose Compiler 报告会在构建完成后向开发者提供稳定性信息。skydoves/compose-stability-analyzer IntelliJ 插件则会在编辑时提供反馈。装订线图标会用颜色标记每个 @Composable，悬停文档会显示包含原因的逐参数表格，行内提示会在每个参数类型旁显示彩色徽标，而 UnstableComposable 弱警告检查则会指出可采取行动的问题，并提供快速修复。

该插件使用 Kotlin K2 Analysis API 评估与 ../understanding-stability-inference/SKILL.md 相同的稳定性规则，因此编辑器反馈与 ../diagnosing-compose-stability/SKILL.md 后续在编译器报告中显示的内容一致。这样一来，反馈周期便从“发布 → 构建 → 阅读报告”缩短为“输入 → 查看装订线”。

何时使用此技能

• 开发者希望在编辑 Composable 文件时实时获取稳定性反馈。
• 审查者在本地阅读 PR，并希望在每个可组合项旁看到行内提示。
• 新成员希望一眼看出文件中哪些可组合项不可跳过。
• 用户询问为什么编辑器会用名为 UnstableComposable 的弱警告标记某个函数。
• 用户提到装订线图标、行内提示、稳定性检查、IDEA 插件、Compose 的 K2 Analysis API，或 Compose Stability Analyzer 工具窗口。

何时不使用此技能

• 需要在稳定性回归时阻止构建的 CI 门禁。请使用 ../enforcing-stability-in-ci/SKILL.md。
• 构建时的 Compose Compiler 报告分析。请使用 ../diagnosing-compose-stability/SKILL.md。
• 通过插件工具窗口主动跟踪运行时或调查视觉级联。请使用 ../visualizing-recomposition-cascades/SKILL.md。
• 有关编译器如何对类型进行分类的概念性问题。请使用 ../understanding-stability-inference/SKILL.md。

先决条件

• Android Studio 2024.2+ 或 IntelliJ IDEA 2024.2+（构建版本范围为 242 至 261，涵盖 2024.2 至 2026.1 EAP）。
• IDE 插件运行时中的 Kotlin 2.3.0，这是插件所依赖的 K2 Analysis API 的要求。
• 项目中已配置 Compose Compiler Gradle 插件（org.jetbrains.kotlin.plugin.compose）。分析器会使用相同的编译器模型评估稳定性。
• 目前开发期间需要从磁盘安装该插件；JetBrains Marketplace 上架申请仍在审核中。

工作流

1. 从源代码构建插件

克隆 skydoves/compose-stability-analyzer 并构建 IDEA 模块。

git clone https://github.com/skydoves/compose-stability-analyzer
cd compose-stability-analyzer
./gradlew :compose-stability-analyzer-idea:buildPlugin

打包后的插件位于 compose-stability-analyzer-idea/build/distributions/*.zip。

2. 从磁盘安装

在 IDE 中打开 Settings → Plugins → ⚙ → Install Plugin from Disk…，然后选择步骤 1 生成的 ZIP 文件。按提示重启 IDE。DO NOT 现在就去 JetBrains Marketplace 查找该插件；撰写本文时，它仍在审核中。

3. 确认设置面板

打开 Settings → Tools → Compose Stability Analyzer。确认 isStabilityCheckEnabled 已开启。所有开关都从 StabilitySettingsState 读取，完整列表如下：

键	默认值	效果
isStabilityCheckEnabled	true	所有编辑器功能的总开关。
isStrongSkippingEnabled	true	匹配 Compose Compiler 2.0.20+ 的运行时行为：启用强跳过进行分类。
showGutterIcons	true	在每个 @Composable 旁边的装订线中显示彩色图标。
showGutterIconsOnlyForUnskippable	false	隐藏绿色／灰色图标，只显示问题。适用于内容密集的文件。
showGutterIconsInTests	false	也在测试源码根目录中显示装订线图标。
showWarnings	true	启用 UnstableComposable 检查。
showInlineHints	true	在行内显示彩色参数类型徽标。
showOnlyUnstableHints	false	不显示稳定参数的行内徽标。
stableGutterColorRGB	#5FB865 (95, 184, 101)	稳定可组合项的装订线／提示颜色。
unstableGutterColorRGB	#E8684A (232, 104, 74)	不稳定可组合项的装订线／提示颜色。
runtimeGutterColorRGB	#F0C674 (240, 198, 116)	运行时稳定性可组合项的装订线／提示颜色。
stableHintColorRGB / unstableHintColorRGB / runtimeHintColorRGB	使用上述默认值	行内提示颜色覆盖值。
ignoredTypePatterns	""	以换行符或逗号分隔的 glob 类型列表，这些类型将被视为稳定。
stabilityConfigurationPath	""	可选路径，指向编译器读取的同一 stability_config.conf。
isHeatmapEnabled	true	启用实时重组热力图（参见 ../visualizing-recomposition-cascades/SKILL.md）。

将 stabilityConfigurationPath 指向项目的 stability_config.conf，以确保编辑器内的分类与编译器的分类一致。

4. 查看装订线颜色

打开任意包含 @Composable 函数的 Kotlin 文件。确认每个函数旁边都显示彩色图标。四种颜色及其含义如下：

颜色	十六进制	含义
绿色	#5FB865	可跳过；所有参数都稳定。
红色	#E8684A	至少有一个不稳定参数；不可跳过。
黄色	#F0C674	至少有一个运行时稳定性参数（跨独立编译单元解析）。
灰色	#808080	没有参数（仍可重启，但显然可跳过）。

灰色装订线没有问题；该函数没有可比较的内容。绿色装订线表示分析器认为，当参数相等时，Compose 会跳过重组。红色或黄色装订线表示存在诊断问题：父项重组时，该函数会发生超出必要次数的重组。

5. 悬停查看参数表

将鼠标悬停在任意可组合项名称上。由 StabilityDocumentationProvider 提供的弹出窗口会显示可跳过性徽标、按参数列出的稳定性分类表，以及分析器能够给出的建议修复（例如“将 List<Item> 包装在 ImmutableList 中”）。在打开完整编译器报告之前，可用此功能进行初步排查。

6. 为内容密集的文件调整行内提示

StabilityInlayHintsProvider 会在函数签名中每个参数类型旁显示彩色徽标。屏幕上有许多可组合项时，这可能会显得杂乱。在 Settings → Tools → Compose Stability Analyzer 中启用 showOnlyUnstableHints，即可隐藏稳定参数的徽标，只保留有待处理的徽标。若要让文件更清爽，可启用 showGutterIconsOnlyForUnskippable，使装订线只显示红色／黄色图标。

7. 查看 UnstableComposable 检查结果

StabilityInspection（简称 UnstableComposable，分组为 Compose，严重性为弱警告）会标记至少有一个不稳定参数且不可跳过的可组合项。它会实时运行，也会在 Code → Inspect Code… 中运行。检查结果会以两种方式呈现：

• 编辑器中的弱警告下划线。
• Inspection Results 工具窗口中的检查结果，归类在 Compose / Unstable Composable 下。

它有意设为弱警告：是否可跳过属于诊断信息，而不是会阻止构建的错误。它不会让文件变红、阻止提交，也不会单独导致 CI 失败。请将其视为待办事项的提示。

8. 仅在有充分理由时应用快速修复

此检查提供两个抑制意图，可通过在带下划线的可组合项上按 Alt+Enter 使用：

• @Suppress("NonSkippableComposable") — 由 AddSuppressAnnotationFix / AddSuppressIntentionAction 应用。用于在开发者已明确认定某个函数可以接受的情况下（例如，调试覆盖层从不处于热路径中）关闭该函数的检查提示。
• @Suppress("ParamsComparedByRef") — 使用相同的修复路径，但范围更窄：当参数有意按引用进行比较时，关闭此警告。

仅在具体函数上应用抑制。不要将其移到文件级别。

9. 使用 @TraceRecomposition 标注热路径

任何 @Composable 上都可以通过 Alt+Enter 使用 AddTraceRecompositionIntention。它会插入 @TraceRecomposition 注解，这是实时热力图以及 ../../measurement/tracing-recompositions-at-runtime/SKILL.md 使用的运行时插桩入口。边栏已识别出疑似热点后，可在这些热点可组合项上使用此注解。

模式

模式：热路径中的红色边栏可采取行动，即使构建成功

// WRONG
PriceTicker has a red gutter icon.
Build is green, the team ships, jank reports come in two days later.

// WRONG because: the inspection is a weak warning by design and does not block the build.
// The gutter is the only signal until the developer opens the compiler reports.
// Treat red gutters on hot-path composables as actionable; confirm with
// `../diagnosing-compose-stability/SKILL.md`, then fix via `../stabilizing-compose-types/SKILL.md`.

// RIGHT
PriceTicker has a red gutter icon.
Hover -> "price: Price unstable (var price)".
Open the compiler reports for confirmation.
Stabilize `Price` (val + immutable fields) per `../stabilizing-compose-types/SKILL.md`.
Gutter turns green; confirm with the live heatmap per `../visualizing-recomposition-cascades/SKILL.md`.

模式：在函数上抑制，绝不要在文件上抑制

// WRONG
@file:Suppress("UnstableComposable")

package com.example.feature.cart

// WRONG because: file-level suppression hides every future regression in that file.
// New unstable composables added to the file will never surface in the inspection.

// RIGHT — narrow, justified suppression on a single function
@Suppress("NonSkippableComposable")
@Composable
fun DebugOverlay(state: MutableState<DebugInfo>) {
    // dev-only overlay; never on hot path; intentional MutableState parameter.
}

模式：不要一味追求 100% 绿色边栏

// WRONG
"All composables in :feature-search must show green gutters before merge."

// WRONG because: skippability is a diagnostic, not a KPI. Some composables legitimately
// take unstable parameters (interop with Java POJOs, third-party data classes the team
// does not own). The goal is "no regression in hot-path composables", not "all green".
// Use `../enforcing-stability-in-ci/SKILL.md` to gate against regressions, not absolutes.

// RIGHT
Hot-path composables (list rows, scroll items, animation tickers) are green or yellow.
Cold-path composables (settings screens, debug tools) may be red and that is acceptable.

模式：通过设置消除噪声，而不是禁用检查

// WRONG
Settings -> Editor -> Inspections -> Compose -> Unstable Composable -> off

// WRONG because: turning the inspection off globally silences real regressions
// across the whole codebase. The next unstable parameter slipping into a hot
// composable will not surface anywhere in the editor.

// RIGHT
Settings -> Tools -> Compose Stability Analyzer:
  showGutterIconsOnlyForUnskippable = true
  showOnlyUnstableHints = true
The inspection stays on; only the visual noise is reduced.

模式：让编辑器内的分类器与编译器保持一致

// RIGHT — in Settings -> Tools -> Compose Stability Analyzer
isStrongSkippingEnabled = true
stabilityConfigurationPath = "<repo-root>/stability_config.conf"

Kotlin 2.0.20+ 默认启用强跳过，编译器也会读取相同的 stability_config.conf（参见 ../stabilizing-compose-types/SKILL.md）。两项设置一致时，开发者看到的边栏颜色就会与编译器在 ../diagnosing-compose-stability/SKILL.md 中产生的结果相符。

强制规则

• MUST 将热路径中任何可组合项旁边的红色或黄色装订线视为需要处理的问题。根据 ../diagnosing-compose-stability/SKILL.md，通过编译器报告进行确认，然后按照 ../stabilizing-compose-types/SKILL.md 修复。
• MUST 将 stabilityConfigurationPath 指向 Compose 编译器读取的同一个 stability_config.conf，确保编辑器与编译器的分类一致。
• MUST NOT 使用文件级 @file:Suppress("UnstableComposable")。应在具体函数上使用 @Suppress("NonSkippableComposable") 或 @Suppress("ParamsComparedByRef")，并在注释中说明原因。
• MUST NOT 为了消除噪声而全局禁用检查。请先在 Settings → Tools → Compose Stability Analyzer 中设置 showGutterIconsOnlyForUnskippable = true 和 showOnlyUnstableHints = true。
• MUST NOT 一味追求装订线全部变绿。可跳过性是诊断信息，不是 KPI。稳定性配置是一份契约，不是魔法咒语——将可变类型标记为稳定，意味着编译器信任开发者；违反契约会导致重组悄无声息地缺失。
• PREFERRED： 保持 isStrongSkippingEnabled = true，使分析器的分类与 Kotlin 2.0.20+ 上编译器的实际运行时行为一致。
• PREFERRED： 对疑似热点的可组合项使用 Add @TraceRecomposition 意图添加 @TraceRecomposition，然后按照 ../../measurement/tracing-recompositions-at-runtime/SKILL.md 配置运行时部分。
• PREFERRED： 开发期间从磁盘安装；JetBrains Marketplace 上的条目尚在等待发布，MUST NOT 假定现在已经可以使用。

验证

• 已通过 Settings → Plugins → ⚙ → Install Plugin from Disk… 从磁盘安装插件；IDE 已重启。
• Settings → Tools → Compose Stability Analyzer 已显示，且 isStabilityCheckEnabled 已开启。
• 打开包含 @Composable 声明的 Kotlin 文件时，每个声明旁都显示有颜色的装订线图标。
• 将鼠标悬停在可组合项名称上时，会显示由 StabilityDocumentationProvider 提供的参数稳定性表格弹出窗口。
• 函数签名中的每个参数旁都显示内联参数类型提示；切换 showOnlyUnstableHints 后，稳定参数的提示会隐藏。
• UnstableComposable 检查（分组 Compose，弱警告）会标记打开的文件中至少一个已知的不稳定可组合项（如果存在）。
• 在已标记的可组合项上按 Alt+Enter，会提供 @Suppress("NonSkippableComposable") 和 @Suppress("ParamsComparedByRef") 快速修复。
• 在任何 @Composable 上按 Alt+Enter，会提供 Add @TraceRecomposition 意图。
• stabilityConfigurationPath 指向项目 Gradle 配置中 Compose 编译器使用的同一个 stability_config.conf。

参考资料

• skydoves/compose-stability-analyzer — https://github.com/skydoves/compose-stability-analyzer
• 该仓库中的 compose-stability-analyzer-idea 模块 — https://github.com/skydoves/compose-stability-analyzer/tree/main/compose-stability-analyzer-idea
• skydoves，《通过掌握稳定性优化应用性能》 — https://medium.com/proandroiddev/optimize-app-performance-by-mastering-stability-in-jetpack-compose-69f40a8c785d
• Compose 稳定性概览 — https://developer.android.com/develop/ui/compose/performance/stability
• 强跳过 — https://developer.android.com/develop/ui/compose/performance/stability/strongskipping
• IntelliJ Platform K2 Analysis API — https://plugins.jetbrains.com/docs/intellij/analysis-api.html

如需在 CI 端设置门禁，将红色装订线转为构建失败，请参阅 ../enforcing-stability-in-ci/SKILL.md。如需了解与装订线颜色一致的构建时 Compose Compiler 报告，请参阅 ../diagnosing-compose-stability/SKILL.md。如需查看可将红色装订线变为绿色的上游类型修复，请参阅 ../stabilizing-compose-types/SKILL.md。如需了解同一插件中的主动调查工具（级联可视化工具、实时热力图），请参阅 ../visualizing-recomposition-cascades/SKILL.md。如需了解 Add @TraceRecomposition 意图设置的运行时检测，请参阅 ../../measurement/tracing-recompositions-at-runtime/SKILL.md。