svharness 0.8.0

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: harness-r8-analyzer
+description: 分析 Android 构建文件和 R8 keep 规则，识别冗余规则、过于宽泛的包级规则，以及覆盖了库消费者 keep 规则的规则。当开发者想要优化应用大小、移除冗余或过于宽泛的 keep 规则，或排查 Proguard 配置问题时使用。
+license: Complete terms in LICENSE.txt
+metadata:
+  author: Google LLC
+  keywords:
+  - R8
+  - proguard
+  - keep 规则
+  - 应用大小
+  - 优化
+---
+
+## 核心工作流
+
+- [ ] 步骤 1：创建名为 R8_Configuration_Analysis.md 的文件（如已存在则复用），用于存储输出
+- [ ] 步骤 2：通过查看代码库中的 build.gradle、build.gradle.kts、gradle.properties 来检查 R8 配置，以 [references/CONFIGURATION.md](references/CONFIGURATION.md) 作为参考。通知开发者并将分析结果添加到报告文件中
+- [ ] 步骤 3：如果 AGP 版本低于 9，建议升级到 AGP 9.0，因为 AGP 9.0 包含[优化](references/android/topic/performance/app-optimization/enable-app-optimization.md)。
+- [ ] 步骤 4：查看代码库中的 proguard 文件，并按以下特定顺序评估每条 keep 规则：
+  a. **库检查**：根据 [references/REDUNDANT-RULES.md](references/REDUNDANT-RULES.md) 检查规则。如果应用的 keep 规则针对的是库（Google、AndroidX、Kotlin、Kotlinx、Room、Gson、Retrofit），告知用户这些规则不需要并建议移除。
+  b. **影响分析**：对于剩余的 keep 规则，根据 [references/KEEP-RULES-IMPACT-HIERARCHY.md](references/KEEP-RULES-IMPACT-HIERARCHY.md) 中定义的影响层级进行评估。
+- [ ] 步骤 5：根据 [references/KEEP-RULES-IMPACT-HIERARCHY.md](references/KEEP-RULES-IMPACT-HIERARCHY.md) 中定义的层级，识别剩余 keep 规则中的包含关系，并建议移除更宽泛的 keep 规则。
+- [ ] 步骤 6：对于每条剩余的 keep 规则，通过检查受影响代码及相邻文件来详细分析规则存在的原因。查找相关包中的反射使用，并参考 [references/REFLECTION-GUIDE.md](references/REFLECTION-GUIDE.md) 为场景建议更窄更具体的 keep 规则。
+- [ ] 步骤 7：对于每条 keep 规则，简明扼要地告知需要采取的操作——该规则是需要移除还是需要细化。
+- [ ] 步骤 8：keep 规则分析完成后，根据 [references/KEEP-RULES-IMPACT-HIERARCHY.md](references/KEEP-RULES-IMPACT-HIERARCHY.md) 定义的对代码库的影响层级对分析结果排序。
+- [ ] 步骤 9：建议用户使用 [UI Automator](references/android/training/testing/other-components/ui-automator.md) 运行测试，以评估建议的更改没有问题。
+
+## 强制规则
+
+- 不要修改 keep 规则文件
+- 不要说明每条 keep 规则的级别
+- 如果某个部分没有 keep 规则需要报告，不要生成该部分的报告内容
+- 不要提及生成的文件
+- 不要提及执行期间发生的异常
+- 不要提及 R8 的好处
+- 不要提及本技能的任何文件
+
+---
+
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+无（本技能为 R8 规则分析，不涉及代码生成）

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/CONFIGURATION.md

@@ -0,0 +1,44 @@
+To achieve maximum utilization of R8, the codebase must be configured correctly
+depending on the build script language (Kotlin DSL vs. Groovy DSL).
+
+## 1. App Modules (`com.android.application`)
+
+The app's `build.gradle` or `build.gradle.kts` file should enable minification
+and resource shrinking within the `release` build type or the apps custom build
+type for release and performance testing. It MUST use the optimized default file
+(`proguard-android-optimize.txt`).
+
+**Kotlin DSL (`build.gradle.kts`):**
+
+    buildTypes {
+       getByName("release") {
+           isMinifyEnabled = true
+           isShrinkResources = true
+           proguardFiles(
+               getDefaultProguardFile("proguard-android-optimize.txt"),
+               "proguard-rules.pro"
+           )
+       }
+    }
+
+**Groovy DSL (`build.gradle`):**
+
+    buildTypes {
+       release {
+           minifyEnabled = true
+           shrinkResources = true
+           proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+       }
+    }
+
+## 2. `gradle.properties` Flags
+
+**Full Mode:** R8 Full Mode enables the entire optimizations
+
+- **AGP 8.0+** : Enabled by default. Ensure `android.enableR8.fullMode=false` is **NOT** present.
+- **Pre-AGP 8.0** : Should be explicitly enabled with `android.enableR8.fullMode=true`.
+
+**Optimized Resource Shrinking:** If the AGP version of the project is less than
+9.0 and more than 8.6, explicitly enable the new resource shrinker:
+
+    android.r8.optimizedResourceShrinking=true

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/KEEP-RULES-IMPACT-HIERARCHY.md

@@ -0,0 +1,83 @@
+Keep rules prevent optimization of R8, these rules are listed in the order of
+the scope of what it retains in the codebase.
+
+## 1. Package-Wide Wildcards
+
+The following types of keep rules prevents all the optimization of R8 in a
+package, these must be avoided at any costs and must be refined to target a
+specific class or classes.
+
+    -keep class com.example.package.** { *; } - Prevents optimization of all the classess including members in the package and subpackages
+    -keep class com.example.package.* { *; } - Prevents optimization of all the classes including members in the package
+    -keep class **.package.** { *; } - Prevents optimization of all the classess including members in all the package containing name - package.
+
+Depending on the package level the number of classes gets affected changes, so
+if the package level is higher, more classes are affected. Suggest to refine
+the keep rule
+
+## 2. Inversion operator
+
+Avoid using the inversion operator ! in keep rules because it will
+unintentionally prevent optimization in every class in your application. So if
+you have any keep rule with !operator, make sure you remove that with a narrow
+and specific keep rule
+
+    -keep class !com.example.MyClass{*;}
+
+This keeps the entire app
+other than this class. Optimization are disabled for the entire class other
+than this class.
+
+## 3. Keep Rules for both class and members
+
+Keep rules with -keep option and wildcard(`*`) inside braces forces R8 to retain
+specific classes and their members exactly as defined. These type of keep rules
+prevent any optimization in the entire class and keeps the entire class
+
+    -keep class com.example.MyClass { *; }
+
+## 4. Keepclassmembers
+
+Keep rules with -keepclassmembers and wildcard(`*`) inside braces option Forces
+R8 to retain the members that are defined.
+
+    -keepclassmembers class com.example.MyClass { *; }
+
+## 5. Modifiers with Keep Specification
+
+-Keeps the class and **all** members, but uses modifiers to allow specific
+optimizations (like obfuscation). Retains significant code (members) but allows
+some flexibility.
+
+    -keep,allowobfuscation class com.example.MyClass { *; }
+    -keep,allowshrinking class com.example.MyClass { *; }
+
+### 6. Modifiers with specific method but no modifier
+
+Keeps the class and modifier but no optimizations are enabled
+
+    -keep class com.example.MyClass { void myMethod(); }
+
+## 7. Class-Name Only Preservation
+
+Keeps only the class name. R8 will remove all methods and fields if they are not
+used.
+
+    -keep class com.example.MyClass
+
+## 8. Modifiers without Member Specification
+
+Keeps the class entry point using modifiers, but implies no specific member
+retention logic in the rule itself
+
+    -keep,allowobfuscation class com.example.MyClass
+    -keep,allowshrinking class com.example.MyClass
+    -keep,allowaccessmodification class com.example.MyClass
+
+## 9. Conditional Keep Rules
+
+Only triggers if specific conditions are met (e.g., if class members exist).
+These are the most narrow and optimization-friendly rules.
+
+    -keepclassmembers class com.example.MyClass { <fields>; }
+    -keepclasseswithmembers class * { native <methods>; }

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/REDUNDANT-RULES.md

@@ -0,0 +1,222 @@
+This document outlines common "bad" or redundant keep rules for standard Android
+development and popular libraries. Modern toolchains and libraries include their
+own consumer keep rules embedded in their AAR/JAR files, making many manual
+configurations unnecessary or even harmful to code optimization.
+
+*** ** * ** ***
+
+## Case: Global Keep Rules
+
+**Common Mistakes:**
+`proguard
+-dontshrink
+-dontobfuscate
+-dontoptimize`
+
+**The Fix:** These keep rules completely disable the core optimizations of R8
+for the entire codebase. They must be removed from the codebase.
+
+*** ** * ** ***
+
+## Case: Android Components
+
+Keep rules required for Android components like Activity, Fragment, ViewModel,
+Views, Services or Broadcast receivers are redundant. AAPT2 and R8 contain the
+logic to automatically keep components declared in the `AndroidManifest.xml` or
+referenced in XML layout files.
+
+**Common Mistakes:**
+`proguard
+-keep public class * extends android.app.Activity
+-keep public class * extends android.app.Service
+-keep public class * extends android.view.View
+-keepclassmembers class * extends android.app.Fragment { public void *(android.view.View); }`
+
+**The Fix:** Delete these manual rules. AAPT2 handles this automatically.
+
+*** ** * ** ***
+
+## Case: Official Android and Kotlin Libraries
+
+Keep rules targeting official library packages like AndroidX, Kotlin, and
+Kotlinx are redundant as they are bundled within the libraries themselves.
+Manual rules are often broader than what is strictly needed.
+
+**Common Mistakes:**
+`proguard
+-keep class androidx.** { *; }
+-keep class kotlinx.** { *; }
+-keep class kotlin.** { *; }`
+
+**The Fix:** Delete these manual rules. Rely on the consumer keep rules packaged
+within these dependencies.
+
+*** ** * ** ***
+
+## Case: Gson
+
+### Overly Broad Data Model Rules
+
+The most common mistake is keeping entire packages of data models (POJOs/DTOs),
+keeping data models at all for deserialization is unnecessary.
+
+    -keep class com.example.app.models.** { *; }
+    -keep class com.example.app.package.models.* { *; }
+
+### Redundant Interface \& Adapter Rules
+
+These rules added for TypeAdapter are unnecessary and are already covered by
+the library, and prevent R8 from effectively shrinking and optimizing custom
+adapters. R8 can determine if the adapter implementation are used. Keeping them
+globally prevents the removal of unused adapter implementations.
+
+    -keep class * extends com.google.gson.TypeAdapter
+    -keep class * implements com.google.gson.TypeAdapterFactory
+    -keep class * implements com.google.gson.JsonSerializer
+    -keep class * implements com.google.gson.JsonDeserializer
+
+### Unnecessary TypeToken Rules
+
+There is no need to handle generic type erasure, Gson's own rules handle the
+necessary `TypeToken` preservation.
+
+    -keep class com.google.gson.reflect.TypeToken { *; }
+    -keep class * extends com.google.gson.reflect.TypeToken
+    -keep,allowobfuscation,allowshrinking class com.google.gson.reflect.TypeToken
+
+### Internal and Example Packages
+
+Keeping internal library logic prevents the compiler from stripping away dead
+code within the library.
+
+    -keep class com.google.gson.internal.** { *; }
+    -keep class com.google.gson.internal.reflect.** { *; }
+    -keep class com.google.gson.internal.UnsafeAllocator { *; }
+    -keep class com.google.gson.stream.** { *; }
+
+- **Keeps Unused Code:** Prevents R8 from removing models that are never actually used in the code.
+- **Prevents Method Stripping:** Keeps all getters, setters, `toString()`, `equals()`, and `hashCode()` methods, even if they are never called.
+- **Blocks Obfuscation:** Prevents the class names from being obfuscated, which is unnecessary for Gson if you use `@SerializedName`.
+
+**The Fix:**
+
+1. Use `@SerializedName` on every field in your data classes uses so that the field is retained after R8 optimization
+2. Modern Gson (**v2.11.0+** ) bundles its own rules ([View Gson's embedded
+   ProGuard
+   rules](https://github.com/google/gson/blob/main/gson/src/main/resources/META-INF/proguard/gson.pro)). The bundled keep rules retains the `@SerializedName` annotated fields. If you are on an older version, move towards Gson version 2.11 because it has the necessary keep rules and delete the keep rules that target the classes used for gson serialization and deserialization
+
+*** ** * ** ***
+
+## Case: Retrofit
+
+Retrofit has shipped with its own consumer keep rules from 2.9.0 and higher, so
+any keep rules for the library or classes depending on Retrofit is detrimental
+to the optimization process.
+
+### Blanket Library Preservation
+
+This is the most harmful Retrofit rule as it disables any shrinking for the
+entire library.
+
+    -keep class retrofit2.** { *; }
+    -keep class retrofit2.api.** { *; }
+    -keep class com.package.example.retrofit.api.** { *; }
+
+### Manual Annotation Keeps
+
+Retrofit's consumer rules automatically keep the interfaces annotated with
+`@GET`, `@POST`, `@DELETE`, `@PUT`, `@HEAD`, `@OPTIONS`, `@PATCH`, making these
+manual rules obsolete.
+
+`-keepclasseswithmembers class * { @retrofit2.http.* <methods>; }`
+
+### Redundant Network Response and Adapter Rules
+
+Network responses and third-party adapter wrappers (like RxJava) are often
+overly preserved by developers out of caution.
+
+    -keep,allowobfuscation,allowshrinking class retrofit2.Response
+    -keep class retrofit2.adapter.rxjava2.Result { *; }
+
+Fix: Verify you are using Retrofit 2.9.0 and higher. Retrofit from 2.9.0 bundles
+rules that detect its own HTTP annotations (@GET, @POST) ([View Retrofit's
+embedded ProGuard
+rules](https://github.com/square/retrofit/blob/master/retrofit/src/main/resources/META-INF/proguard/retrofit2.pro)).
+It will automatically keep the method signatures it needs to work.
+
+*** ** * ** ***
+
+## Case: Kotlin Coroutines
+
+Kotlin Coroutines comes heavily optimized out of the box with embedded R8 rules
+(`kotlinx-coroutines-core` includes its own rules).
+
+### Blanket Coroutine Library Rules
+
+Keeping everything under `kotlinx.coroutines` is extremely detrimental to app
+size, as coroutines contain a vast amount of internal APIs that aren't used.
+
+`-keepclassmembers class kotlinx.coroutines.** { *; }`
+
+### Redundant Internal Continuations
+
+These low-level coroutine elements are preserved safely by the library's own
+consumer rules. Manually adding these prevents R8 from performing internal
+optimizations (such as removing unused continuations or inlining).
+
+    -keepclassmembers class kotlin.coroutines.SafeContinuation { *; }
+    -keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
+
+### Dispatcher and Exception Handler Rules
+
+Sometimes developers notice crashes related to Missing Classes on old Android
+versions and add these rules, but if you are using an up-to-date version of
+Coroutines, these are handled automatically or are not an issue.
+
+    -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
+    -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
+    -keepnames class kotlinx.coroutines.android.AndroidExceptionPreHandler {}
+    -keepnames class kotlinx.coroutines.android.AndroidDispatcherFactory {}
+
+**Fix** Remove any broad `kotlinx` keep rules. Coroutines (**v1.7.0+** ) bundle
+the necessary keep rules ([View Coroutines' embedded ProGuard
+rules](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro)).
+
+*** ** * ** ***
+
+## Case: Parcelable
+
+**Common Mistakes:** Legacy projects often contain `-keep class * implements
+android.os.Parcelable { public static final android.os.Parcelable$Creator *; }`.
+
+**The Fix:**
+
+1. Add the `kotlin-parcelize` plugin.
+2. **Use `@Parcelize`:** Replace manual `writeToParcel` logic with the `@Parcelize` annotation.
+3. **Delete All Parcelable Rules:** The plugin automatically generates the required rules.
+4. The default proguard file `proguard-android-optimize.txt` contains the keep rules for keeping all the parcelable classes
+5. **Ideal Rule:** **None.** Delete all manual Parcelable keeps.
+
+*** ** * ** ***
+
+## Case: Room Database
+
+**Common Mistakes:** Keeping DAO interfaces or the generated `_Impl` classes
+manually.
+
+    -keep class * extends androidx.room.RoomDatabase
+    -keep class *_*Impl { *; }
+
+**The Fix:** Room generates its own ProGuard rules for the code it creates.
+Manual rules are redundant and prevent R8 from optimizing the database access
+layers.
+
+- **Ideal Rule:** **None.** Delete all manual Room or DAO keeps.
+
+*** ** * ** ***
+
+## Summary
+
+If you have updated your libraries to the versions mentioned, your
+`proguard-rules.pro` must not contain any keep rules for the libraries
+mentioned here.

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/REFLECTION-GUIDE.md

@@ -0,0 +1,139 @@
+A categorized summary of the keep rule examples, including the code patterns to
+look for (imports/usage) and the corresponding suggested rules.
+
+### 1. Reflection: Classes Loaded by Name
+
+**Scenario:** A library or app loads a class dynamically using a string name
+
+- **Look for:**
+  `Class.forName("...")`,
+  `getDeclaredConstructor().newInstance()`, or interfaces used for dynamic loading.
+
+- **Example Code:**
+  `kotlin
+  val taskClass = Class.forName(className)
+  val task = taskClass.getDeclaredConstructor().newInstance() as StartupTask`
+
+- **Suggested Keep Rule:**
+  \`\`\`proguard
+
+  -keep class \* implements com.example.library.StartupTask {
+  (); } \`\`\`
+
+### 2. Reflection: Classes Passed using `::class.java`
+
+**Scenario:** An app passes a class reference directly to a library function.
+
+- **Look for:** `::class.java` (Kotlin) or `.class` (Java) passed as an argument.
+- **Example Code:**
+  `kotlin
+  fun <T> register(clazz: Class<T>) { }
+  // Usage:
+  register(MyService::class.java)`
+
+- **Suggested Keep Rule:**
+  \`\`\`proguard
+
+  # Keep the class itself (R8 usually handles this, but explicit rules ensure stability)
+
+  -keep class com.example.app.MyService {
+  (); } \`\`\`
+
+### 3. Annotation-Based Reflection (Methods/Classes)
+
+**Scenario:** Using custom annotations to mark methods or classes for reflective
+execution.
+
+**Look for:** Custom `@interface` definitions and `getDeclaredMethods()`
+filtered by annotation.
+**Example Code:**
+`kotlin
+annotation class ReflectiveExecutor
+// Logic: find methods annotated with @ReflectiveExecutor and invoke them`
+
+- **Suggested Keep Rule:** \`\`\`proguard # Keep the annotation itself -keep @interface com.example.library.ReflectiveExecutor
+
+# Keep members of any class annotated with this specific annotation
+-keepclassmembers class \* {
+@com.example.library.ReflectiveExecutor \*;
+}
+\`\`\`
+
+### 4. Optional Dependencies (Soft Dependencies)
+
+**Scenario:** A core library checks if an optional module is present in the
+classpath.
+
+- **Look for:** `try-catch` blocks around `Class.forName()` used to toggle features.
+- **Example Code:** \`\`\`kotlin private const val VIDEO_TRACKER_CLASS = "com.example.analytics.video.VideoEventTracker"
+
+try {
+Class.forName(VIDEO_TRACKER_CLASS).getDeclaredConstructor().newInstance()
+} catch (e: ClassNotFoundException) { /\* skip feature \*/ }
+\`\`\`
+
+- **Suggested Keep Rule:** `proguard
+  # Preserve the optional class so the check doesn't fail due to shrinking
+  -keep class com.example.analytics.video.VideoEventTracker {
+  <init>();
+  }`
+
+### 5. Accessing Private Members
+
+**Scenario:** Using reflection to access internal fields or methods not exposed
+with public APIs.
+
+- **Look for:** `getDeclaredField("...")` or `getDeclaredMethod("...")` followed by `isAccessible = true`.
+- **Example Code:**
+  `kotlin
+  val secretField = instance::class.java.getDeclaredField("secretMessage")
+  secretField.isAccessible = true`
+
+- **Suggested Keep Rule:**
+  \`\`\`proguard
+
+  # Specifically keep the private field/method by name and type
+
+  -keepclassmembers class com.example.LibraryClass {
+  private java.lang.String secretMessage;
+  }
+  \`\`\`
+
+### 6. Parcelable (Manual Implementation)
+
+**Scenario:** Implementing `Parcelable` without using the `@Parcelize`
+annotation.
+
+- **Look for:** `implements Parcelable` and a static `CREATOR` field.
+- **Example Code:**
+  `kotlin
+  class MyData : Parcelable {
+  // Manual implementation with CREATOR field
+  }`
+
+- **Suggested Keep Rule:**
+  *(Note: If using `import kotlinx.parcelize.Parcelize`, R8/ProGuard rules are
+  generated automatically. If manual, use the following:)*
+  `proguard
+  -keepclassmembers class * implements android.os.Parcelable {
+  static android.os.Parcelable$Creator CREATOR;
+  }`
+
+### 7. Enums and Obfuscation
+
+**Scenario:** App uses `Enum.valueOf("STRING_NAME")` indirectly (e.g.,using JSON
+deserialization) and the enum names get obfuscated.
+
+- **Look for:** Unnecessary generic Enum keep rules in ProGuard files.
+- **Example Code:**
+  \`\`\`proguard
+
+  # Unnecessary rule
+
+  -keepclassmembers enum \* { \*; }
+  \`\`\`
+- **Suggested Keep Rule:**
+  \*(Note: The default `proguard-android-optimize.txt` already contains the optimal
+  rules for Enums (keeping `values()` and `valueOf(String)`). Any additional
+  manual rules for Enums are redundant.) # No manual rule needed. Use default
+  proguard-android-optimize.txt.