svharness 0.8.0

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/android/topic/performance/app-optimization/enable-app-optimization.md

@@ -0,0 +1,176 @@
+For the best user experience, you should optimize your app to make it as small
+and fast as possible. Our app optimizer, called R8, streamlines your app by
+removing unused code and resources, rewriting code to optimize runtime
+performance, and more. To your users, this means:
+
+- Faster startup time
+- Reduced memory usage
+- Improved rendering and runtime performance
+- Fewer [ANRs](https://developer.android.com/topic/performance/anrs/keep-your-app-responsive)
+
+> [!IMPORTANT]
+> **Important:** You should always enable optimization for your app's release build; however, you probably don't want to enable it for tests or libraries. For more information about using R8 with tests, see [Test and troubleshoot the
+> optimization](https://developer.android.com/topic/performance/app-optimization/test-and-troubleshoot-the-optimization). For more information about enabling R8 from libraries, see [Optimization for library authors](https://developer.android.com/topic/performance/app-optimization/library-optimization).
+
+> [!IMPORTANT]
+> **Important:** We released an agent skill that you can use to improve your app performance with R8. Try out the skill from the [Android skills repository](https://github.com/android/skills).
+
+## R8 optimization overview
+
+R8 uses a multi-phase process to optimize your app for size and speed. Key
+operations include the following:
+
+- **Code shrinking (also known as tree shaking)** : R8 identifies and removes
+  unreachable code from your application and its library dependencies. By
+  analyzing the entry points of your app (such as `Activities` or `Services`
+  defined in the manifest), R8 builds a graph of referenced code and removes
+  anything that remains unreferenced.
+
+- **Logical optimizations**: R8 rewrites your code to improve execution
+  efficiency and reduce overhead. Key techniques include:
+
+  - **Method inlining**: R8 replaces a method call site with the actual body
+    of the called method. This eliminates the overhead of a function call
+    and lets R8 conduct further optimizations.
+
+  - **Class merging**: R8 combines sets of classes and interfaces into a
+    single class. This reduces the number of classes in the app, lowering
+    memory pressure and improving startup speed.
+
+- **Obfuscation (also known as minification)** : To reduce the size of the DEX
+  file, R8 shortens the names of classes, fields, and methods (for example,
+  `com.example.MyActivity` could become `a.b.a`).
+
+Since 8.12.0 version of Android Gradle Plugin (AGP), R8 also optimizes resources
+as part of its optimization phases. For more information, see [Optimized
+resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking).
+
+## Enable optimization
+
+To enable app optimization, set `isMinifyEnabled = true` (for code optimization)
+and `isShrinkResources = true` (for resource optimization) in your [release
+build's](https://developer.android.com/studio/publish/preparing#turn-off-debugging) app-level build script as shown in the following code. We recommend
+that you always enable both settings. We also recommend enabling app
+optimization only in the final version of your app that you test before
+publishing---usually your release build---because the optimizations increase the
+build time of your project and can make debugging harder due to the way it
+modifies code.
+
+### Kotlin
+
+```kotlin
+android {
+    buildTypes {
+        release {
+
+            // Enables code-related app optimization.
+            isMinifyEnabled = true
+
+            // Enables resource shrinking.
+            isShrinkResources = true
+
+            proguardFiles(
+                // Default file with automatically generated optimization rules.
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+
+                ...
+            )
+            ...
+        }
+    }
+    ...
+}
+```
+
+### Groovy
+
+```groovy
+android {
+    buildTypes {
+        release {
+
+            // Enables code-related app optimization.
+            minifyEnabled = true
+
+            // Enables resource shrinking.
+            shrinkResources = true
+
+            // Default file with automatically generated optimization rules.
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
+
+            ...
+        }
+    }
+}
+```
+
+## Optimize resource shrinking for even smaller apps
+
+The 8.12.0 version of Android Gradle Plugin (AGP) introduces optimized resource
+shrinking, which aims to integrate resource and code optimization to create even
+smaller and faster apps.
+
+Before optimized resource shrinking, Android Asset Packaging Tool (AAPT2)
+generated keep rules that effectively treating resource shrinking separately
+from code, often retaining inaccessible code or resources that referenced each
+other.
+
+With optimized resource shrinking, resources are considered like a part of
+program code, forming the reference graph. When a collection of code or
+resources is not referenced, it is not protected by a keep rule, and can be
+removed.
+
+### Enable optimized resource shrinking
+
+To enable the new optimized resource shrinking pipeline for AGP 8.12 or 8.13,
+add the following to your project's `gradle.properties` file:
+
+    android.r8.optimizedResourceShrinking=true
+
+If you are using AGP 9.0.0 or a newer version, you don't need to set
+`android.r8.optimizedResourceShrinking=true`. Optimized resource shrinking is
+automatically applied when `isShrinkResources = true` is enabled in your build
+configuration.
+
+## Verify and configure R8 optimization settings
+
+To enable R8 to use its [full optimization capabilities](https://developer.android.com/topic/performance/app-optimization/full-mode), remove the
+following line from your project's `gradle.properties` file, if it exists:
+
+    android.enableR8.fullMode=false # Remove this line from your codebase.
+
+Note that enabling app optimization makes stack traces difficult to understand,
+especially if R8 renames class or method names. To get stack traces that
+correctly correspond to your source code, see [Recover the original stack
+trace](https://developer.android.com/topic/performance/app-optimization/test-and-troubleshoot-the-optimization#recover-original-stack-trace).
+
+If R8 is enabled, you should also [create Startup Profiles](https://developer.android.com/topic/performance/baselineprofiles/dex-layout-optimizations) for even better
+startup performance.
+
+If you enable app optimization and it causes errors, here are some strategies to
+fix them:
+
+- [Add keep rules](https://developer.android.com/topic/performance/app-optimization/add-keep-rules) to keep some code untouched.
+- [Adopt optimizations incrementally](https://developer.android.com/topic/performance/app-optimization/adopt-optimizations-incrementally).
+- Update your code to [use libraries that are better suited for
+  optimization](https://developer.android.com/topic/performance/app-optimization/choose-libraries-wisely).
+
+> [!CAUTION]
+> **Caution:** Tools that replace or modify R8's output can negatively impact runtime performance. R8 is careful about including and testing many optimizations at the code level, in [DEX layout](https://developer.android.com/topic/performance/baselineprofiles/dex-layout-optimizations), and in correctly producing Baseline Profiles - other tools producing or modifying DEX files can break these optimizations, or otherwise regress performance.
+
+If you are interested in optimizing your build speed, see [Configure how R8
+runs](https://developer.android.com/build/r8-execution-profiles) for information on how to configure R8 based on your environment.
+
+## AGP and R8 version behavior changes
+
+The following table outlines the key features introduced in various versions of
+the Android Gradle Plugin (AGP) and the R8 compiler.
+
+| AGP version | Features introduced |
+|---|---|
+| 9.1 | **Classes repackaged by default:** R8 repackages classes (moving them to the unnamed package, at the top level) to compact DEX further, eliminating the need to specify `-repackageclasses` option. For information about how this works and how to opt out, see [global options](https://developer.android.com/topic/performance/app-optimization/global-options#global-options). |
+| 9.0 | **Optimized resource shrinking:** Enabled by default (controlled using `android.r8.optimizedResourceShrinking`). [Optimized resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking) helps integrate resource shrinking with the code optimization pipeline, leading to smaller, faster apps. By optimizing both code and resource references simultaneously, it identifies and removes resources referenced exclusively from unused code. This is a significant improvement over the previous separate optimization processes. This is especially useful for apps that share substantial resources and code across different form factor verticals, with measured improvements of over 50% in app size. The resulting size reduction leads to smaller downloads, faster installations, and a better user experience with faster startup, improved rendering, and fewer ANRs. **Library rule filtering:** Support for global options (for example, `-dontobfuscate`) in library consumer rules has been dropped, and apps will filter them out. For more information, see [Add global options](https://developer.android.com/topic/performance/app-optimization/global-options). **Kotlin null checks:** Optimized by default (controlled using `-processkotlinnullchecks`). This version also introduced significant improvements in build speed. For more information, see [Global options for additional optimization](https://developer.android.com/topic/performance/app-optimization/global-options#global-options). **Optimize specific packages:** You can use `packageScope` to optimize specific packages. This is in experimental support. For more information, see [Optimize specified packages with `packageScope`](https://developer.android.com/topic/performance/app-optimization/optimize-specified-packages). **Optimized by default:** Support for `getDefaultProguardFile("proguard-android.txt")` has been dropped, because it includes `-dontoptimize`, which should be avoided. Instead, use `"proguard-android-optimize.txt"`. If you need to globally disable optimization in your app, [add the flag manually to a proguard file](https://developer.android.com/topic/performance/app-optimization/global-options#global-options-2). |
+| 8.12 | **Optimized resource shrinking:** Initial support added (controlled using `android.r8.optimizedResourceShrinking`). [Optimized resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking) helps integrate resource shrinking with the code optimization pipeline. You must manually enable it in this version of AGP. **Logcat retracing:** Support for automatic retracing in the Android Studio [Logcat window](https://developer.android.com/studio/debug/logcat). |
+| 8.6 | **Improved retracing:** Includes filename and line number retracing by default for all `minSdk` levels (previously required `minSdk` 26+ in version 8.2). Updating R8 helps ensure that stack traces from obfuscated builds are readily and clearly readable. This version improves how line numbers and source files are mapped, making it easier for tools like the Android Studio Logcat to automatically retrace crashes to the original source code. |
+| 8.0 | **Full mode by default:** [R8 full mode](https://developer.android.com/topic/performance/app-optimization/full-mode) provides significantly more powerful optimization. It is enabled by default. You can opt out using `android.enableR8.fullMode=false`. |
+| 7.0 | **Full mode available:** Introduced as an opt-in feature using `android.enableR8.fullMode=true`. Full mode applies more powerful optimizations by making stricter assumptions about how your code uses reflection and other dynamic features. While it reduces app size and improves performance, it might require additional keep rules to prevent necessary code from being stripped. |

package/templates/android-compose/skeleton/agent-env/skills/harness-r8-analyzer/references/android/training/testing/other-components/ui-automator.md

@@ -0,0 +1,312 @@
+The UI Automator testing framework provides a set of APIs to build UI tests that
+interact with user apps and system apps.
+
+> [!NOTE]
+> **Note:** This documentation covers the modern approach to writing UI Automator tests, introduced with [UI Automator 2.4](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.0). This approach makes your tests more concise, readable, and robust. The API is under development, and we strongly recommend using it for any new development with UI Automator. The [legacy API guidance](https://developer.android.com/training/testing/other-components/ui-automator-legacy) is also available.
+
+## Introduction to modern UI Automator testing
+
+UI Automator 2.4 introduces a streamlined, Kotlin-friendly Domain Specific
+Language (DSL) that simplifies writing UI tests for Android. This new API
+surface focuses on predicate-based element finding and explicit control over app
+states. Use it to create more maintainable and reliable automated tests.
+
+UI Automator lets you test an app from outside of the app's process. This
+lets you test release versions with minification applied. UI Automator also
+helps when writing macrobenchmark tests.
+
+Key features of the modern approach include:
+
+- A dedicated `uiAutomator` test scope for cleaner and more expressive test code.
+- Methods like `onElement`, `onElements`, and `onElementOrNull` for finding UI elements with clear predicates.
+- Built-in waiting mechanism for conditional elements `onElement*(timeoutMs:
+  Long = 10000)`
+- Explicit app state management such as `waitForStable` and `waitForAppToBeVisible`.
+- Direct interaction with accessibility window nodes for multi-window testing scenarios.
+- Built-in screenshot capabilities and a `ResultsReporter` for visual testing and debugging.
+
+## Set up your project
+
+To begin using the modern UI Automator APIs, update your project's
+`build.gradle.kts` file to include the [latest dependency](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.0):
+
+### Kotlin
+
+    dependencies {
+      ...
+      androidTestImplementation("androidx.test.uiautomator:uiautomator:2.4.0-alpha05")
+    }
+
+### Groovy
+
+    dependencies {
+      ...
+      androidTestImplementation "androidx.test.uiautomator:uiautomator:2.4.0-alpha05"
+    }
+
+## Core API concepts
+
+The following sections describe core concepts of the modern UI Automator API.
+
+### The uiAutomator test scope
+
+Access all new UI Automator APIs within the **`uiAutomator { ... }`**
+block. This function creates a `UiAutomatorTestScope` that provides a concise
+and type-safe environment for your test operations.
+
+    uiAutomator {
+      // All your UI Automator actions go here
+      startApp("com.example.targetapp")
+      onElement { textAsString() == "Hello, World!" }.click()
+    }
+
+### Find UI elements
+
+Use UI Automator APIs with predicates to locate UI elements. These predicates
+let you define conditions for properties such as text, selected or focused
+state, and content description.
+
+- `onElement { predicate }`: Returns the first UI element that matches the
+  predicate within a default timeout. The function throws an exception if it
+  doesn't locate a matching element.
+
+      // Find a button with the text "Submit" and click it
+      onElement { textAsString() == "Submit" }.click()
+
+      // Find a UI element by its resource ID
+      onElement { viewIdResourceName == "my_button_id" }.click()
+
+      // Allow a permission request
+      watchFor(PermissionDialog) {
+        clickAllow()
+      }
+
+- `onElementOrNull { predicate }`: Similar to `onElement`, but returns
+  `null` if the function finds no matching element within the timeout. It
+  doesn't throw an exception. Use this method for optional elements.
+
+      val optionalButton = onElementOrNull { textAsString() == "Skip" }
+      optionalButton?.click() // Click only if the button exists
+
+- `onElements { predicate }`: Waits until at least one UI element matches
+  the given predicate, then returns a list of all matching UI elements.
+
+      // Get all items in a list Ui element
+      val listItems = onElements { className == "android.widget.TextView" && isClickable }
+      listItems.forEach { it.click() }
+
+Here are some tips for using `onElement` calls:
+
+- Chain `onElement` calls for nested elements: You can chain `onElement`
+  calls to find elements within other elements, following a parent-child
+  hierarchy.
+
+      // Find a parent Ui element with ID "first", then its child with ID "second",
+      // then its grandchild with ID "third", and click it.
+      onElement { viewIdResourceName == "first" }
+        .onElement { viewIdResourceName == "second" }
+        .onElement { viewIdResourceName == "third" }
+        .click()
+
+- Specify a timeout for `onElement*` functions by passing a value representing
+  milliseconds.
+
+      // Find a Ui element with a zero timeout (instant check)
+      onElement(0) { viewIdResourceName == "something" }.click()
+
+      // Find a Ui element with a custom timeout of 10 seconds
+      onElement(10_000) { textAsString() == "Long loading text" }.click()
+
+### Interact with UI elements
+
+Interact with UI elements by simulating clicks or setting text in editable
+fields.
+
+    // Click a Ui element
+    onElement { textAsString() == "Tap Me" }.click()
+
+    // Set text in an editable field
+    onElement { className == "android.widget.EditText" }.setText("My input text")
+
+    // Perform a long click
+    onElement { contentDescription == "Context Menu" }.longClick()
+
+## Handle app states and watchers
+
+Manage the lifecycle of your app and handle unexpected UI elements that might
+appear during your tests.
+
+### App lifecycle management
+
+The APIs provide ways to control the state of the app under test:
+
+    // Start a specific app by package name. Used for benchmarking and other
+    // self-instrumenting tests.
+    startApp("com.example.targetapp")
+
+    // Start a specific activity within the target app
+    startActivity(SomeActivity::class.java)
+
+    // Start an intent
+    startIntent(myIntent)
+
+    // Clear the app's data (resets it to a fresh state)
+    clearAppData("com.example.targetapp")
+
+### Handle unexpected UI
+
+The `watchFor` API lets you define handlers for unexpected UI elements,
+such as permission dialogs, that might appear during your test flow. This
+uses the internal watcher mechanism but offers more flexibility.
+
+    import androidx.test.uiautomator.PermissionDialog
+
+    @Test
+    fun myTestWithPermissionHandling() = uiAutomator {
+      startActivity(MainActivity::class.java)
+
+      // Register a watcher to click "Allow" if a permission dialog appears
+      watchFor(PermissionDialog) { clickAllow() }
+
+      // Your test steps that might trigger a permission dialog
+      onElement { textAsString() == "Request Permissions" }.click()
+
+      // Example: You can register a different watcher later if needed
+      clearAppData("com.example.targetapp")
+
+      // Now deny permissions
+      startApp("com.example.targetapp")
+      watchFor(PermissionDialog) { clickDeny() }
+      onElement { textAsString() == "Request Permissions" }.click()
+    }
+
+`PermissionDialog` is an example of a `ScopedWatcher<T>`, where `T` is the
+object passed as a scope to the block in `watchFor`. You can create custom
+watchers based on this pattern.
+
+### Wait for app visibility and stability
+
+Sometimes tests need to wait for elements to become visible or stable.
+UI Automator offers several APIs to help with this.
+
+The `waitForAppToBeVisible("com.example.targetapp")` waits for a UI element with
+the given package name to appear on the screen within a customizable timeout.
+
+    // Wait for the app to be visible after launching it
+    startApp("com.example.targetapp")
+    waitForAppToBeVisible("com.example.targetapp")
+
+Use the `waitForStable()` API to verify that the app's UI is considered stable
+before interacting with it.
+
+    // Wait for the entire active window to become stable
+    activeWindow().waitForStable()
+
+    // Wait for a specific Ui element to become stable (e.g., after a loading animation)
+    onElement { viewIdResourceName == "my_loading_indicator" }.waitForStable()
+
+> [!NOTE]
+> **Note:** In most cases, `waitForStable()` isn't strictly necessary when using `onElement { ... }` because `onElement` already includes a timeout. Use `waitForStable()` primarily in combination with `onElements { ... }` to verify that all UI elements are visible, when you know that the UI is in an unstable state, or for specific screenshot testing scenarios where you need the UI to completely settle before capturing. `waitForStable()` works by waiting until no changes are detected in the accessibility tree for a set period. Note that this UI stability check doesn't guarantee that the app is fully idle, as background tasks might still be running.
+
+## Use UI Automator for Macrobenchmarks and Baseline Profiles
+
+Use UI Automator for performance testing with [Jetpack Macrobenchmark](https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview)
+and for generating [Baseline Profiles](https://developer.android.com/topic/performance/baselineprofiles/overview), as it provides a reliable way to
+interact with your app and measure performance from an end-user perspective.
+
+Macrobenchmark uses UI Automator APIs to drive the UI and measure interactions.
+For example, in startup benchmarks, you can use `onElement` to detect when UI
+content is fully loaded, enabling you to measure [Time to Full Display
+(TTFD)](https://developer.android.com/topic/performance/vitals/launch-time#time-full). In jank benchmarks, UI Automator APIs are used to scroll lists or
+run animations to measure frame timings. Functions like `startActivity()` or
+`startIntent()` are useful for getting the app into the correct state before
+measurement begins.
+
+When [generating Baseline Profiles](https://developer.android.com/topic/performance/baselineprofiles/create-baselineprofile), you automate your app's critical user
+journeys (CUJs) to record which classes and methods require pre-compilation. UI
+Automator is an ideal tool for writing these automation scripts. The modern
+DSL's predicate-based element finding and built-in wait mechanisms (`onElement`)
+lead to more robust and deterministic test execution compared to other methods.
+This stability reduces flakiness and ensures that the generated Baseline Profile
+accurately reflects the code paths executed during your most important user
+flows.
+
+## Advanced features
+
+The following features are useful for more complex testing scenarios.
+
+### Interact with multiple windows
+
+The UI Automator APIs let you directly interact with and inspect UI
+elements. This is particularly useful for scenarios involving multiple windows,
+such as Picture-in-Picture (PiP) mode or split-screen layouts.
+
+    // Find the first window that is in Picture-in-Picture mode
+    val pipWindow = windows()
+      .first { it.isInPictureInPictureMode == true }
+
+    // Now you can interact with elements within that specific window
+    pipWindow.onElement { textAsString() == "Play" }.click()
+
+### Screenshots and visual assertions
+
+Capture screenshots of the entire screen, specific windows, or
+individual UI elements directly within your tests. This is helpful for visual
+regression testing and debugging.
+
+    uiautomator {
+      // Take a screenshot of the entire active window
+      val fullScreenBitmap: Bitmap = activeWindow().takeScreenshot()
+      fullScreenBitmap.saveToFile(File("/sdcard/Download/full_screen.png"))
+
+      // Take a screenshot of a specific UI element (e.g., a button)
+      val buttonBitmap: Bitmap = onElement { viewIdResourceName == "my_button" }.takeScreenshot()
+      buttonBitmap.saveToFile(File("/sdcard/Download/my_button_screenshot.png"))
+
+      // Example: Take a screenshot of a PiP window
+      val pipWindowScreenshot = windows()
+        .first { it.isInPictureInPictureMode == true }
+        .takeScreenshot()
+      pipWindowScreenshot.saveToFile(File("/sdcard/Download/pip_screenshot.png"))
+    }
+
+The `saveToFile` extension function for Bitmap simplifies saving the captured
+image to a specified path.
+
+### Use ResultsReporter for debugging
+
+The `ResultsReporter` helps you associate test artifacts, like screenshots,
+directly with your test results in Android Studio for easier inspection and
+debugging.
+
+    uiAutomator {
+      startApp("com.example.targetapp")
+
+      val reporter = ResultsReporter("MyTestArtifacts") // Name for this set of results
+      val file = reporter.addNewFile(
+        filename = "my_screenshot",
+        title = "Accessible button image" // Title that appears in Android Studio test results
+      )
+
+      // Take a screenshot of an element and save it using the reporter
+      onElement { textAsString() == "Accessible button" }
+        .takeScreenshot()
+        .saveToFile(file)
+
+      // Report the artifacts to instrumentation, making them visible in Android Studio
+      reporter.reportToInstrumentation()
+    }
+
+## Migrate from older UI Automator versions
+
+If you have existing UI Automator tests written with older API surfaces, use the
+following table as a reference to migrate to the modern approach:
+
+| Action type | Old UI Automator method | New UI Automator method |
+|---|---|---|
+| Entry point | `UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())` | Wrap test logic in the `uiAutomator { ... }` scope. |
+| Find UI elements | `device.findObject(By.res("com.example.app:id/my_button"))` | `onElement { viewIdResourceName == "my\_button" }` |
+| Find UI elements | `device.findObject(By.text("Click Me"))` | `onElement { textAsString() == "Click Me" }` |
+| Wait for idle UI | `device.waitForIdle()` | Prefer `onElement`'s built-in timeout mechanism; otherwise, `activeWindow().waitForStable()` |
+| Find child elements | Manually nested `findObject` calls | `onElement().onElement()` chaining |
+| Handle permission dialogs | `UiAutomator.registerWatcher()` | `watchFor(PermissionDialog)` |

package/templates/android-compose/skeleton/agent-env/skills/harness-xml-to-compose/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: harness-xml-to-compose
+description: 提供结构化的 Android XML View 迁移到 Jetpack Compose 的工作流。详细说明从规划、依赖设置、主题和布局迁移、验证到 XML 清理的分步过程。当需要在 Android 项目中将 XML View 迁移到 Jetpack Compose 时使用。
+license: Complete terms in LICENSE.txt
+metadata:
+  author: Google LLC
+  keywords:
+  - Jetpack Compose
+  - 迁移
+  - XML
+  - Views
+  - 互操作性
+  - 渐进式采用
+  - UI 开发
+---
+
+本技能引导完成将现有 Android XML View 迁移到 Jetpack Compose 的过程。它遵循结构化的 10 步方法论，执行稳定、安全且视觉一致的过渡。本技能仅迁移 UI（XML → Jetpack Compose）。
+
+## 目标
+
+系统地将单个传统 XML 布局转换为现代声明式 Jetpack Compose UI，同时保持像素级视觉一致性和功能完整性。
+
+## 10 步迁移流程概览
+
+1. **识别最佳 XML 迁移候选**
+2. **分析项目与布局**
+3. **制定计划**
+4. **捕获 XML View UI 截图**
+5. **设置 Compose 依赖和编译器**
+6. **设置 Compose 主题**
+7. **将 XML 布局迁移到 Compose**
+8. **验证迁移结果**
+9. **替换使用处**
+10. **清理 XML 代码**
+
+## 详细步骤
+
+### 步骤 1：识别最佳 XML 迁移候选
+
+如果用户已明确指定目标 XML 布局，直接进入步骤 2。否则，按照 [references/identify-optimal-xml-candidate.md](references/identify-optimal-xml-candidate.md) 识别最佳迁移候选。
+
+### 步骤 2：分析项目与布局
+
+使用 [references/analysis-of-the-project-and-layout.md](references/analysis-of-the-project-and-layout.md) 指导对布局和项目上下文的技术审计。
+
+### 步骤 3：制定计划
+
+利用步骤 1 和 2 的输出和分析，生成迁移的分步计划。向用户展示计划并在继续前请求确认。
+
+### 步骤 4：捕获 XML View UI 截图
+
+请用户上传 XML View UI 的截图或提供文件绝对路径。将此截图作为步骤 7 布局迁移的视觉参考。
+
+### 步骤 5：设置 Compose 依赖和编译器
+
+检查 `build.gradle` 或 `libs.versions.toml` 中的 Compose 依赖和编译器配置。如缺失，参考 [设置 Compose 依赖和编译器](references/android/develop/ui/compose/setup-compose-dependencies-and-compiler.md)。
+
+### 步骤 6：设置 Compose 主题
+
+如果缺少 Compose 主题，进行初始化。对于基于 Material 的项目，遵循 [Material 3 迁移指南](references/android/develop/ui/compose/designsystems/migrate-xml-theme-to-compose.md)。
+
+**约束：** 不要迁移整个主题。仅实现特定 XML 候选所需的最小主题。保留原始 XML 主题以保持互操作性。
+
+### 步骤 7：将 XML View 迁移到 Compose
+
+将 XML 候选转换为 Jetpack Compose 代码，参考 [references/xml-layout-migration.md](references/xml-layout-migration.md) 和步骤 4 的截图。必须为新创建的可组合函数包含 **Compose Preview** 以便视觉验证。
+
+### 步骤 8：替换使用处
+
+将已迁移 XML 布局的使用替换为新的 Compose 组件。
+
+### 步骤 9：验证迁移结果
+
+将基线截图与新建可组合函数的 Compose Preview 渲染结果进行对比。迭代修改直到视觉一致。验证通过后，为新可组合函数编写 Compose UI 测试。
+
+### 步骤 10：清理 XML 代码
+
+删除已迁移的 XML 文件及其关联的旧测试。**注意：** 仅删除项目中其他部分未引用的代码和资源。
+
+---
+
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+- harness-compose-mandatory
+- harness-mvi-layering

package/templates/android-compose/skeleton/agent-env/skills/harness-xml-to-compose/references/analysis-of-the-project-and-layout.md

@@ -0,0 +1,42 @@
+## 1. Project health \& build validation
+
+Before performing any analysis, you must confirm the project is in a functional state.
+\* **Integrity check:** Verify the project syncs (Gradle) and builds successfully.
+\* **Error resolution:** If there are pre-existing build errors or sync failures, you must report these immediately and attempt to fix. **Do not proceed** with migration until a stable baseline is established.
+
+## 2. Compose pattern \& consistency analysis
+
+If Jetpack Compose is already present, you must align with the established implementation style.
+\* **Pattern identification:** Scan the codebase for `@Composable` functions. Identify the project's "Best Practices" regarding state hoisting, composable construction and naming conventions, and file organization.
+\* **Theming review:** Determine how `MaterialTheme` or custom theme systems are implemented.
+\* Identify if the project uses a custom design system theme.
+\* Map how attributes, styles, and other theme components are accessed in Compose.
+
+## 3. Design system \& infrastructure audit
+
+Understand the design system classification (e.g. Material 2, Material 3, or custom design system).
+\* **Resource mapping:** Locate central XML definitions:
+\* `colors.xml` (Light/Dark variants)
+\* `dimens.xml`
+\* `styles.xml` / `themes.xml`
+\* **Hybrid analysis:** Determine if the project is **XML-only** , **Compose-only** , or **Hybrid** .
+\* **Reuse constraint:** If a Compose theming layer (e.g., `AppTheme.kt`) already exists, **DO NOT** generate a new one. You must reuse the existing infrastructure and contribute to it by following its existing implementation pattern.
+
+## 4. Candidate layout decomposition
+
+Analyze the specific XML layout targeted for migration. You must extract and document the following requirements for the new composable:
+\* **Inputs:** UI State objects, primitive parameters, and click listeners.
+\* **Styling:** Specific color constants, typography styles, and shape definitions referenced in the XML.
+\* **Resources:** Identifying string resources, drawables, and dimensions.
+\* **Layout logic:** Modifiers required to replicate the XML constraints (padding, alignment, weight).
+
+## 5. Architectural \& non-UI analysis
+
+Understand the environment in which the UI resides to ensure proper integration.
+\* **State management:** Identify the usage of `ViewModel`, `Flow`, or `LiveData`.
+\* **Dependency Injection:** Check for Hilt, Koin, or manual DI to understand how dependencies are provided to the UI layer.
+\* **Testing \& architecture:** Note the architectural pattern (MVI, MVVM, or custom architecture setup.) and existing UI testing frameworks to ensure the migrated code remains testable. Unless the user explicitly requests, **DO NOT** make any changes to any non-UI code that aren't strictly required for the migration of the XML View.
+
+*** ** * ** ***
+
+> **Pro-tip:** Always prioritize the "Existing infrastructure" over "Default templates." If the project has a custom way of handling spacing or colors, composable code, or any other project layer, your generated Compose code must reflect that specific implementation.