@harmonyos-arkts/d2h 0.1.10 → 0.1.12

package/skills/android2hmos_resources_convert/SKILL.md

@@ -1,180 +1,180 @@
----
-name: android2hmos_resources_convert
-description: >-
-  Android 图片资源迁移到 HarmonyOS：位图（png/jpg/webp/gif/bmp）、nine-patch（.9.png）、mipmap 启动图标、
-  自适应图标（adaptive-icon → layered_image.json）以及 XML drawable（vector/shape/layer-list/selector → SVG）。
-  当用户要求把 Android 项目的图标、图片、drawable 资产迁移/转换到鸿蒙工程（res/ → resources/…/media/），
-  处理限定符目录映射（drawable-hdpi、drawable-night、mipmap-anydpi-v26 等），或修复迁移后图片在鸿蒙上
-  显示空白/错误时触发。即使只说「迁移图标」「图片没迁移」「矢量图转 SVG」也应触发。
-  不处理 values 资源（strings/colors/dimens 的迁移归 arkts-i18n）、布局、Lottie 和字体。
-type: domain
-domain: migration
-tags: [migration, resources, android, images, svg, drawable]
----
-
-# Android → HarmonyOS 图片资源转换
-
-本 skill 只转换**图片类资源**：位图文件（png/jpg/webp/gif/bmp）、nine-patch 图片、启动图标（mipmap、自适应图标），
-以及作为图片渲染的 XML drawable（`<vector>`、`<shape>`、`<layer-list>`、`<selector>`）→ SVG。
-values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明确不在范围内；`values*/colors.xml` 和
-`values*/dimens.xml` 只作为解析 drawable 内 `@color:`/`@dimen:` 引用的查找来源被读取。
-
-## 参考文档
-
-| 要做什么 | 读什么 |
-|---|---|
-| 拷贝/转换位图、nine-patch、mipmap、自适应图标；限定符目录映射 | `references/image-conversion-rules.md` |
-| Android XML Drawable（vector/shape/layer-list/selector）转 SVG | `references/xml-drawable-to-svg-rules.md` |
-| 修复 SVG 显示问题（空白/不可见/尺寸错误/残留 Android 语法） | `references/svg-fix-patterns.md` |
-
-## 输入与统一领域结果
-
-1. **Android 工程路径** — Android Gradle 工程根目录（含 `build.gradle` 或 `build.gradle.kts`）。
-2. **HarmonyOS 工程路径** — 由 Preflight 创建或复用的工程（见 `preparing-migration-workspace`），通常是迁移工作区下的 `ohos/`，或 `.migration/config.json` 中 `--harmony-project` 配置的路径。图片写入 `<harmony>/entry/src/main/resources/`。本 skill 不创建工程壳；`ohos/` 尚不存在时由调用方先完成 Preflight。
-
-始终返回统一领域结果：
-
-```json
-{
-  "status": "completed | partial | failed",
-  "changedFiles": [],
-  "sourceFiles": [],
-  "evidence": [],
-  "domainChecks": [],
-  "unresolved": [],
-  "verificationRequests": [],
-  "suggestedRemediation": [],
-  "details": {
-    "convertedResources": [],
-    "qualifierMappings": [],
-    "unmappedResources": [],
-    "unresolvedReferences": []
-  }
-}
-```
-
-`status` 只表示图片资源转换和静态完整性检查的领域状态，不代表工程已构建、设备显示已验证或迁移已完成。`changedFiles`、`sourceFiles`、`unmappedResources` 和 `unresolvedReferences` 必须列出真实路径或资源标识。构建、设备显示和交互影响核对写入 `verificationRequests`，由调用方选择执行方式。
-
-## 工作流
-
-### 第 1 步：校验输入
-
-1. 确认 Android 工程路径存在且含 `build.gradle` 或 `build.gradle.kts`。
-2. 通过 `droid2hmos status <ANDROID_PROJECT>` 或 `.migration/config.json` 确认 HarmonyOS 工程位置，并确认 `entry/src/main/resources/` 存在；不存在时返回 `failed`，把缺少工程壳写入 `unresolved` 和 `suggestedRemediation`，不要猜测工程结构或自行调度 Preflight。
-
-### 第 2 步：确定资源来源
-
-使用工程源码 `res/` 目录：
-
-- 首选 `<android_project>/app/src/main/res/`
-- 多模块工程同时检查其它模块目录
-- 使用 flavor source set 时一并纳入（如 `app/src/debug/res/`、`app/src/flavor/res/`）
-
-恒定从源码 `res/` 转换：仅由库依赖（AAR）提供的图片不在源码 `res/` 中，这类引用在统一结果中记为 unresolved，不尝试回收。
-
-### 第 3 步：清点与分类
-
-扫描资源来源中的每个 `drawable*/` 和 `mipmap*/` 目录。对每个文件按**内容**分类（`.xml` 文件读根元素判断，绝不只按目录名分类）：
-
-| 分类 | 判定 | 路由 |
-|---|---|---|
-| 位图 | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp` | 直接拷贝（第 4.1 步） |
-| Nine-patch | `.9.png` | 拷贝 + 重命名（第 4.1 步） |
-| XML drawable：vector/shape/layer-list | `.xml`，根 `<vector>` / `<shape>` / `<layer-list>` | 转 SVG（第 4.2 步） |
-| XML drawable：selector | `.xml`，根 `<selector>` | 提取默认状态 → SVG（第 4.2 步） |
-| 自适应图标 | `.xml`，根 `<adaptive-icon>` | 转 layered-image JSON（第 4.3 步） |
-| ripple/animated-vector/animated-selector/transition/level-list 等 | `.xml`，对应根元素 | 不可映射 — 记入统一结果 |
-
-忽略 `values*/`、`layout*/`、`menu/`、`raw/`、`font/`、`xml/`、`anim*/`、`color/` — 超出范围。只有 `values*/colors.xml` 和 `values*/dimens.xml` 被读取，用于解析 drawable 内的 `@color:`/`@dimen:` 引用（第 4.4 步）。
-
-### 第 4 步：转换
-
-转换前先读 `references/image-conversion-rules.md`。四条路由概要：
-
-**4.1 位图与 nine-patch → `media/`**
-- 拷贝到限定符映射后的 `media/` 目录（完整限定符算法见 image-conversion-rules.md）
-- `.9.png` → 重命名为 `<name>_9.png`（HarmonyOS 禁止资源文件名中含 `.`，仅允许最后扩展名分隔符）。nine-patch 拉伸语义丢失 — 在统一结果中记录
-
-**4.2 XML drawable → `media/` 中的 `.svg`**
-- 严格按 `references/xml-drawable-to-svg-rules.md` 执行 — 尤其是强制保留 `clip-path`、三分支 `fill` 规则和渐变处理
-- 每生成一个 SVG 后，执行该文档中的自检（clip-path 数量、fill 规则、viewBox 匹配）
-
-**4.3 自适应图标 → layered-image JSON**
-- `<adaptive-icon>` → `<name>_layered_image.json`，只含 `background`/`foreground` 键
-- `@drawable/xxx`、`@mipmap/xxx` → `$media:xxx`；`@color/xxx` → 生成纯色 PNG（`<color_name>_bg.png`）— layered-image 不接受 `$color:` 引用
-- `monochrome` 不写入 JSON，但其引用的 drawable 仍按普通图片转换
-
-**4.4 解析 drawable 内引用**
-- SVG 填充/描边中的 `@color/name` → 从 `values*/colors.xml` 解析（沿引用链；兜底 `#000000` + 记录）
-- SVG 尺寸中的 `@dimen/name` → 从 `values*/dimens.xml` 解析（兜底：合理默认值 + 记录）
-- 未解析引用（库专属资源不在源码 `res/`）记入统一结果，绝不静默丢弃
-
-### 第 5 步：完整性校验
-
-1. 第 3 步发现的每个文件都有且只有一个结局：已转换，或在统一结果中列为 unmappable/unmapped
-2. 每个转换产物都实际存在于 HarmonyOS 工程
-3. 生成的 layered-image JSON 中每个 `$media:xxx` 引用都指向 `media/` 中存在的文件
-4. 每个转换后的 SVG 通过 `references/xml-drawable-to-svg-rules.md` 的自检
-5. HarmonyOS 工程已有 `.ets` 文件时，扫描 `$r('app.media.xxx')` 并核对每个引用的图片存在（已有 media 文件**不覆盖** — 合并，冲突记录）
-
-### 第 6 步：组装领域结果
-
-把转换清单和静态校验结果写入统一领域结果；如需可读审计附件，可生成以下结构并把路径列入 `evidence`：
-
-```
-# Android to HarmonyOS Image Conversion Report
-
-## Resource Source
-- Resource source: source res/ (library-only images not included)
-- Resource source path: <path>
-
-## Summary
-- Image files found (bitmap/9-patch/XML drawable/adaptive icon): <count per class>
-- Successfully converted: <count>
-- Unmappable (ripple/animated-vector/etc.): <count>
-- Unmapped (unsupported qualifiers): <count>
-- Unresolved color/dimen references: <count>
-
-## Converted Images
-| Android Source | HarmonyOS Target | Type | Notes |
-|---|---|---|---|
-
-## Qualifier Mappings Applied
-| Android Qualifier Dir | HarmonyOS Qualifier Dir | Files Converted |
-|---|---|---|---|
-
-## Unmappable Resources
-| Android Source | Reason |
-|---|---|
-
-## Unresolved References
-| Resource File | Reference | Reason | Likely Source |
-|---|---|---|---|
-
-## Verification Results
-- All image files accounted for: Yes/No
-- All $media references satisfied: Yes/No
-- SVG self-checks passed: Yes/No
-```
-
-影响行为的结论（不可映射资源、丢失的 nine-patch 语义、未解析引用）必须进入 `unresolved`，并标明 `blocking`、来源、用户影响和建议补救。需要回流报告 ref 或 discoveries 的项通过结果交给调用方，本 skill 不直接更新迁移报告。
-
-转换完成后，将实际生成或修改的 HarmonyOS 资源写入 `changedFiles`，把对应 Android 源资源写入 `sourceFiles`；不要只返回计数。静态校验写入 `domainChecks`，待构建和设备核对写入 `verificationRequests`。
-
-## 重要说明
-
-- **XML drawable 转换是关键**：vector/shape/layer-list/selector 必须转成 SVG，不能跳过。转换前务必读 `references/xml-drawable-to-svg-rules.md` — 其中的属性映射表就是规范。
-- **SVG 渲染问题**（空白、不可见、尺寸错误、残留 `android:` 语法）按 `references/svg-fix-patterns.md` 处理，不做临时猜测。
-- **限定符目录是映射，不是保留**：`drawable-hdpi` → `ldpi/media/`（两平台 DPI 标签不同）；`night` → `dark`；`land` → `horizontal`；`v<N>` 剥离；`sw<N>dp`/`w<N>dp`/屏幕尺寸限定符整目录跳过。完整算法见 `references/image-conversion-rules.md`。
-- **转换恒定从源码 `res/` 出发**：仅库依赖（AAR）提供的图片不在其中；对它们的引用按 unresolved 报告，不做恢复。
-- 资源名保持 Android 原拼写 — 它们是标识符。
-- 解析 Android XML 时正确处理命名空间、注释和 CDATA；按 local name 匹配属性。
-- 本 skill 不更新迁移报告、不暂存或提交文件、不创建 checkpoint、不调用 `complete`，也不选择仓库级构建、测试或设备命令。调用方消费统一领域结果并决定外层动作。
-
-## 与其他 skill 的关系
-
-- **preparing-migration-workspace**：⭐ 前置依赖。本 skill 需要 Preflight 已创建或复用的 HarmonyOS 工程（`ohos/`）。
-- **arkts-app-identity**：它处理 App 级身份资源（app.json5 图标字段、版本号、包名）；本 skill 负责 res/ 全量图片资产进 `media/`。启动器图标的位图/分层资产由本 skill 转换，app.json5 的接线归它。
-- **arkts-icon-sizing**：图片资产就位后，它修 `.ets` 消费侧丢失的 `.width()/.height()`；本 skill 只管资源侧。
-- **arkts-i18n**：values 资源（string.json 等）的迁移归它；本 skill 只把 colors.xml/dimens.xml 当查找源。
-- **maintaining-migration-report**：调用方可把本 skill 返回的行为影响项、源码和证据映射到报告分片；本 skill 不直接写报告。
+---
+name: android2hmos_resources_convert
+description: >-
+  Android 图片资源迁移到 HarmonyOS：位图（png/jpg/webp/gif/bmp）、nine-patch（.9.png）、mipmap 启动图标、
+  自适应图标（adaptive-icon → layered_image.json）以及 XML drawable（vector/shape/layer-list/selector → SVG）。
+  当用户要求把 Android 项目的图标、图片、drawable 资产迁移/转换到鸿蒙工程（res/ → resources/…/media/），
+  处理限定符目录映射（drawable-hdpi、drawable-night、mipmap-anydpi-v26 等），或修复迁移后图片在鸿蒙上
+  显示空白/错误时触发。即使只说「迁移图标」「图片没迁移」「矢量图转 SVG」也应触发。
+  不处理 values 资源（strings/colors/dimens 的迁移归 arkts-i18n）、布局、Lottie 和字体。
+type: domain
+domain: migration
+tags: [migration, resources, android, images, svg, drawable]
+---
+
+# Android → HarmonyOS 图片资源转换
+
+本 skill 只转换**图片类资源**：位图文件（png/jpg/webp/gif/bmp）、nine-patch 图片、启动图标（mipmap、自适应图标），
+以及作为图片渲染的 XML drawable（`<vector>`、`<shape>`、`<layer-list>`、`<selector>`）→ SVG。
+values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明确不在范围内；`values*/colors.xml` 和
+`values*/dimens.xml` 只作为解析 drawable 内 `@color:`/`@dimen:` 引用的查找来源被读取。
+
+## 参考文档
+
+| 要做什么 | 读什么 |
+|---|---|
+| 拷贝/转换位图、nine-patch、mipmap、自适应图标；限定符目录映射 | `references/image-conversion-rules.md` |
+| Android XML Drawable（vector/shape/layer-list/selector）转 SVG | `references/xml-drawable-to-svg-rules.md` |
+| 修复 SVG 显示问题（空白/不可见/尺寸错误/残留 Android 语法） | `references/svg-fix-patterns.md` |
+
+## 输入与统一领域结果
+
+1. **Android 工程路径** — Android Gradle 工程根目录（含 `build.gradle` 或 `build.gradle.kts`）。
+2. **HarmonyOS 工程路径** — 由 Preflight 创建或复用的工程（见 `preparing-migration-workspace`），通常是迁移工作区下的 `ohos/`，或 `.migration/config.json` 中 `--harmony-project` 配置的路径。图片写入 `<harmony>/entry/src/main/resources/`。本 skill 不创建工程壳；`ohos/` 尚不存在时由调用方先完成 Preflight。
+
+始终返回统一领域结果：
+
+```json
+{
+  "status": "completed | partial | failed",
+  "changedFiles": [],
+  "sourceFiles": [],
+  "evidence": [],
+  "domainChecks": [],
+  "unresolved": [],
+  "verificationRequests": [],
+  "suggestedRemediation": [],
+  "details": {
+    "convertedResources": [],
+    "qualifierMappings": [],
+    "unmappedResources": [],
+    "unresolvedReferences": []
+  }
+}
+```
+
+`status` 只表示图片资源转换和静态完整性检查的领域状态，不代表工程已构建、设备显示已验证或迁移已完成。`changedFiles`、`sourceFiles`、`unmappedResources` 和 `unresolvedReferences` 必须列出真实路径或资源标识。构建、设备显示和交互影响核对写入 `verificationRequests`，由调用方选择执行方式。
+
+## 工作流
+
+### 第 1 步：校验输入
+
+1. 确认 Android 工程路径存在且含 `build.gradle` 或 `build.gradle.kts`。
+2. 通过 `droid2hmos status <ANDROID_PROJECT>` 或 `.migration/config.json` 确认 HarmonyOS 工程位置，并确认 `entry/src/main/resources/` 存在；不存在时返回 `failed`，把缺少工程壳写入 `unresolved` 和 `suggestedRemediation`，不要猜测工程结构或自行调度 Preflight。
+
+### 第 2 步：确定资源来源
+
+使用工程源码 `res/` 目录：
+
+- 首选 `<android_project>/app/src/main/res/`
+- 多模块工程同时检查其它模块目录
+- 使用 flavor source set 时一并纳入（如 `app/src/debug/res/`、`app/src/flavor/res/`）
+
+恒定从源码 `res/` 转换：仅由库依赖（AAR）提供的图片不在源码 `res/` 中，这类引用在统一结果中记为 unresolved，不尝试回收。
+
+### 第 3 步：清点与分类
+
+扫描资源来源中的每个 `drawable*/` 和 `mipmap*/` 目录。对每个文件按**内容**分类（`.xml` 文件读根元素判断，绝不只按目录名分类）：
+
+| 分类 | 判定 | 路由 |
+|---|---|---|
+| 位图 | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp` | 直接拷贝（第 4.1 步） |
+| Nine-patch | `.9.png` | 拷贝 + 重命名（第 4.1 步） |
+| XML drawable：vector/shape/layer-list | `.xml`，根 `<vector>` / `<shape>` / `<layer-list>` | 转 SVG（第 4.2 步） |
+| XML drawable：selector | `.xml`，根 `<selector>` | 提取默认状态 → SVG（第 4.2 步） |
+| 自适应图标 | `.xml`，根 `<adaptive-icon>` | 转 layered-image JSON（第 4.3 步） |
+| ripple/animated-vector/animated-selector/transition/level-list 等 | `.xml`，对应根元素 | 不可映射 — 记入统一结果 |
+
+忽略 `values*/`、`layout*/`、`menu/`、`raw/`、`font/`、`xml/`、`anim*/`、`color/` — 超出范围。只有 `values*/colors.xml` 和 `values*/dimens.xml` 被读取，用于解析 drawable 内的 `@color:`/`@dimen:` 引用（第 4.4 步）。
+
+### 第 4 步：转换
+
+转换前先读 `references/image-conversion-rules.md`。四条路由概要：
+
+**4.1 位图与 nine-patch → `media/`**
+- 拷贝到限定符映射后的 `media/` 目录（完整限定符算法见 image-conversion-rules.md）
+- `.9.png` → 重命名为 `<name>_9.png`（HarmonyOS 禁止资源文件名中含 `.`，仅允许最后扩展名分隔符）。nine-patch 拉伸语义丢失 — 在统一结果中记录
+
+**4.2 XML drawable → `media/` 中的 `.svg`**
+- 严格按 `references/xml-drawable-to-svg-rules.md` 执行 — 尤其是强制保留 `clip-path`、三分支 `fill` 规则和渐变处理
+- 每生成一个 SVG 后，执行该文档中的自检（clip-path 数量、fill 规则、viewBox 匹配）
+
+**4.3 自适应图标 → layered-image JSON**
+- `<adaptive-icon>` → `<name>_layered_image.json`，只含 `background`/`foreground` 键
+- `@drawable/xxx`、`@mipmap/xxx` → `$media:xxx`；`@color/xxx` → 生成纯色 PNG（`<color_name>_bg.png`）— layered-image 不接受 `$color:` 引用
+- `monochrome` 不写入 JSON，但其引用的 drawable 仍按普通图片转换
+
+**4.4 解析 drawable 内引用**
+- SVG 填充/描边中的 `@color/name` → 从 `values*/colors.xml` 解析（沿引用链；兜底 `#000000` + 记录）
+- SVG 尺寸中的 `@dimen/name` → 从 `values*/dimens.xml` 解析（兜底：合理默认值 + 记录）
+- 未解析引用（库专属资源不在源码 `res/`）记入统一结果，绝不静默丢弃
+
+### 第 5 步：完整性校验
+
+1. 第 3 步发现的每个文件都有且只有一个结局：已转换，或在统一结果中列为 unmappable/unmapped
+2. 每个转换产物都实际存在于 HarmonyOS 工程
+3. 生成的 layered-image JSON 中每个 `$media:xxx` 引用都指向 `media/` 中存在的文件
+4. 每个转换后的 SVG 通过 `references/xml-drawable-to-svg-rules.md` 的自检
+5. HarmonyOS 工程已有 `.ets` 文件时，扫描 `$r('app.media.xxx')` 并核对每个引用的图片存在（已有 media 文件**不覆盖** — 合并，冲突记录）
+
+### 第 6 步：组装领域结果
+
+把转换清单和静态校验结果写入统一领域结果；如需可读审计附件，可生成以下结构并把路径列入 `evidence`：
+
+```
+# Android to HarmonyOS Image Conversion Report
+
+## Resource Source
+- Resource source: source res/ (library-only images not included)
+- Resource source path: <path>
+
+## Summary
+- Image files found (bitmap/9-patch/XML drawable/adaptive icon): <count per class>
+- Successfully converted: <count>
+- Unmappable (ripple/animated-vector/etc.): <count>
+- Unmapped (unsupported qualifiers): <count>
+- Unresolved color/dimen references: <count>
+
+## Converted Images
+| Android Source | HarmonyOS Target | Type | Notes |
+|---|---|---|---|
+
+## Qualifier Mappings Applied
+| Android Qualifier Dir | HarmonyOS Qualifier Dir | Files Converted |
+|---|---|---|---|
+
+## Unmappable Resources
+| Android Source | Reason |
+|---|---|
+
+## Unresolved References
+| Resource File | Reference | Reason | Likely Source |
+|---|---|---|---|
+
+## Verification Results
+- All image files accounted for: Yes/No
+- All $media references satisfied: Yes/No
+- SVG self-checks passed: Yes/No
+```
+
+影响行为的结论（不可映射资源、丢失的 nine-patch 语义、未解析引用）必须进入 `unresolved`，并标明 `blocking`、来源、用户影响和建议补救。需要回流报告 ref 或 discoveries 的项通过结果交给调用方，本 skill 不直接更新迁移报告。
+
+转换完成后，将实际生成或修改的 HarmonyOS 资源写入 `changedFiles`，把对应 Android 源资源写入 `sourceFiles`；不要只返回计数。静态校验写入 `domainChecks`，待构建和设备核对写入 `verificationRequests`。
+
+## 重要说明
+
+- **XML drawable 转换是关键**：vector/shape/layer-list/selector 必须转成 SVG，不能跳过。转换前务必读 `references/xml-drawable-to-svg-rules.md` — 其中的属性映射表就是规范。
+- **SVG 渲染问题**（空白、不可见、尺寸错误、残留 `android:` 语法）按 `references/svg-fix-patterns.md` 处理，不做临时猜测。
+- **限定符目录是映射，不是保留**：`drawable-hdpi` → `ldpi/media/`（两平台 DPI 标签不同）；`night` → `dark`；`land` → `horizontal`；`v<N>` 剥离；`sw<N>dp`/`w<N>dp`/屏幕尺寸限定符整目录跳过。完整算法见 `references/image-conversion-rules.md`。
+- **转换恒定从源码 `res/` 出发**：仅库依赖（AAR）提供的图片不在其中；对它们的引用按 unresolved 报告，不做恢复。
+- 资源名保持 Android 原拼写 — 它们是标识符。
+- 解析 Android XML 时正确处理命名空间、注释和 CDATA；按 local name 匹配属性。
+- 本 skill 不更新迁移报告、不暂存或提交文件、不创建 checkpoint、不调用 `complete`，也不选择仓库级构建、测试或设备命令。调用方消费统一领域结果并决定外层动作。
+
+## 与其他 skill 的关系
+
+- **preparing-migration-workspace**：⭐ 前置依赖。本 skill 需要 Preflight 已创建或复用的 HarmonyOS 工程（`ohos/`）。
+- **arkts-app-identity**：它处理 App 级身份资源（app.json5 图标字段、版本号、包名）；本 skill 负责 res/ 全量图片资产进 `media/`。启动器图标的位图/分层资产由本 skill 转换，app.json5 的接线归它。
+- **arkts-icon-sizing**：图片资产就位后，它修 `.ets` 消费侧丢失的 `.width()/.height()`；本 skill 只管资源侧。
+- **arkts-i18n**：values 资源（string.json 等）的迁移归它；本 skill 只把 colors.xml/dimens.xml 当查找源。
+- **maintaining-migration-report**：调用方可把本 skill 返回的行为影响项、源码和证据映射到报告分片；本 skill 不直接写报告。