0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
ryanclawryanclawadd agent_a2h_resources_convert
f7be819a创建于 3月20日历史提交
文件最后提交记录最后更新时间
README.md
add agent_a2h_resources_convert 2 个月前
llm_client.py
add agent_a2h_resources_convert 2 个月前
main.py
add agent_a2h_resources_convert 2 个月前
models.py
add agent_a2h_resources_convert 2 个月前
step1_init.py
add agent_a2h_resources_convert 2 个月前
step2_discover.py
add agent_a2h_resources_convert 2 个月前
step3_convert.py
add agent_a2h_resources_convert 2 个月前
step4_deps.py
add agent_a2h_resources_convert 2 个月前
step5_resolve.py
add agent_a2h_resources_convert 2 个月前
step6_verify.py
add agent_a2h_resources_convert 2 个月前
step7_report.py
add agent_a2h_resources_convert 2 个月前
README.md

Android → HarmonyOS 资源转换 Agent

将 Android 项目的资源文件自动转换为 HarmonyOS 项目资源格式的智能 Agent。

功能概述

本 Agent 完整覆盖 Android 到 HarmonyOS 的资源迁移流程，包括：

  • 初始化 HarmonyOS 项目（模板复制或目录骨架生成）
  • 多来源资源发现（源码目录、构建产物、多 flavor）
  • 按资源类型分类转换（图片、XML drawable、values、raw、font 等）
  • 资源依赖关系分析（含 layout/menu 文件的引用追踪）
  • 通过 APK 反编译补全库依赖资源
  • 完整性验证
  • 生成详细的 Markdown 转换报告

当前状态（POC 框架）：Step 1、Step 2、Step 7 已完整实现；Step 3～Step 6 的函数签名和文档已定义，具体逻辑待实现。

目录结构

agent_a2h_resources_convert/
├── main.py              # CLI 入口 + 七步流程编排器
├── models.py            # 共享数据模型（AgentState、ResourceItem 等）
├── llm_client.py        # OpenAI 兼容 API 封装（XML→SVG、adaptive-icon 转换）
├── step1_init.py        # Step 1：初始化 HarmonyOS 项目结构
├── step2_discover.py    # Step 2：发现并清点 Android 资源
├── step3_convert.py     # Step 3：资源格式转换（Stub）
├── step4_deps.py        # Step 4：资源依赖分析（Stub）
├── step5_resolve.py     # Step 5：APK 反编译补全缺失依赖（Stub）
├── step6_verify.py      # Step 6：完整性验证（Stub）
├── step7_report.py      # Step 7：生成 Markdown 转换报告
├── tools/
│   └── apktool_3.0.1.jar   # 用于 APK 反编译（Step 5）
└── README.md

环境要求

  • Python 3.8+
  • Java（用于 Step 5 的 apktool 调用，需在系统 PATH 中）
  • OpenAI 兼容 API Key（用于 XML drawable → SVG 等需要 LLM 推理的转换）

无第三方 Python 依赖，仅使用标准库。

快速开始

基本用法

python main.py <android_项目路径> <HarmonyOS_输出路径>

完整参数示例

python main.py \
  /path/to/MyAndroidApp \
  /path/to/MyHarmonyApp \
  --template /path/to/HarmonyAppTemplate \
  --api-key sk-xxxxxxxx \
  --api-base-url https://api.openai.com/v1 \
  --model gpt-4o \
  --log-level INFO

参数说明

参数 默认值 说明
android_path （必填） Android 项目根目录（含 app/src/main/res/）
hmos_output_path （必填） HarmonyOS 项目输出路径
--template D:\cc_workspace\HarmonyAppTemplate HarmonyOS 项目模板目录
--api-key $OPENAI_API_KEY 环境变量 LLM API Key
--api-base-url https://api.openai.com/v1 OpenAI 兼容 API 地址
--model gpt-4o 使用的 LLM 模型名称
--log-level INFO 日志级别：DEBUG / INFO / WARNING / ERROR

也可以通过环境变量传入 API Key：

export OPENAI_API_KEY=sk-xxxxxxxx
python main.py /path/to/android /path/to/hmos

七步转换流程

Step 1  初始化 HarmonyOS 项目
   └─ 复制模板 或 创建标准目录骨架
        (AppScope/, entry/src/main/resources/, hvigor/ ...)

Step 2  发现 Android 资源
   ├─ app/src/main/res/              ← 主资源（最高优先级）
   ├─ app/src/debug|release|<flavor>/res/  ← 额外 source set
   └─ app/build/intermediates/merged_res/  ← 构建产物（补充库资源）

Step 3  转换资源
   ├─ 图片 (png/jpg/webp/gif)  → base/media/  直接复制
   ├─ VectorDrawable XML       → base/media/*.svg  [LLM]
   ├─ shape / layer-list XML   → base/media/*.svg  [LLM]
   ├─ selector XML             → base/media/*.svg  [LLM]
   ├─ adaptive-icon XML        → base/media/*_layered_image.json
   ├─ values/strings.xml       → base/element/string.json
   ├─ values/colors.xml        → base/element/color.json
   ├─ values/dimens.xml        → base/element/float.json
   ├─ raw/                     → rawfile/
   ├─ font/                    → rawfile/fonts/
   ├─ xml/                     → base/profile/
   └─ layout / menu / anim ... → 标记为 Unmappable（记录报告）

Step 4  依赖分析
   ├─ Category A：已转换资源中的 @type/name 引用
   └─ Category B：layout/menu 文件中的 @type/name 引用（重建 ArkUI 时所需）

Step 5  APK 反编译补全（仅在存在未满足依赖时执行）
   ├─ ./gradlew <variant>  构建 APK
   ├─ apktool d <apk>      反编译
   └─ 从反编译产物中提取缺失资源，支持最多 2 级传递依赖解析

Step 6  完整性验证
   ├─ 所有资源均有处理结果
   ├─ 已转换目标文件在磁盘上存在
   ├─ values/ 条目均写入对应 JSON
   ├─ Category A 依赖全部满足
   └─ Category B 依赖全部满足

Step 7  生成报告
   └─ <hmos_output_path>/conversion_report.md

输出报告结构

报告文件为 conversion_report.md，包含以下章节：

  1. Summary — 资源总数、转换数、未映射数、依赖满足情况
  2. Successfully Converted Resources — 成功转换的资源列表
  3. Qualifier Mappings Applied — Android → HarmonyOS 限定符目录映射
  4. Resource Dependency Map — Category A（已转换资源）和 Category B（layout/menu）的依赖关系表
  5. Resources Recovered from APK — 通过 APK 反编译补全的资源
  6. Unmappable Resources — 无 HarmonyOS 等价物的资源（layout、anim 等）
  7. Unmapped Resources (Unsupported Qualifiers) — 因不支持的限定符（如 sw600dp）被跳过的资源
  8. Unsatisfied Dependencies — Step 5 后仍未满足的依赖
  9. Failed Conversions — 转换过程中发生错误的资源
  10. Verification Results — Step 6 各项检查的通过情况

资源类型映射速查

Android 资源目录 HarmonyOS 目标 转换方式
drawable/ (png/jpg/webp) base/media/ 直接复制
drawable/ (<vector>) base/media/*.svg LLM 转换
drawable/ (<shape>) base/media/*.svg LLM 转换
drawable/ (<layer-list>) base/media/*.svg LLM 转换
drawable/ (<selector>) base/media/*.svg 提取默认状态，LLM 转换
mipmap/ (png/webp) base/media/ 直接复制
mipmap/ (<adaptive-icon>) base/media/*_layered_image.json JSON 转换
values/strings.xml base/element/string.json XML → JSON
values/colors.xml base/element/color.json XML → JSON，颜色格式补全
values/dimens.xml base/element/float.json XML → JSON，单位转换（dp→vp，sp→fp）
raw/ rawfile/ 直接复制
font/ rawfile/fonts/ 直接复制
xml/ base/profile/ 配置文件复制
layout/、menu/、anim/ — 标记 Unmappable

DPI 限定符映射

Android HarmonyOS
ldpi sdpi
mdpi mdpi
hdpi ldpi
xhdpi xldpi
xxhdpi xxldpi
xxxhdpi xxxldpi
nodpi / anydpi base

核心数据模型

AgentState                   贯穿七步的中央状态对象
  ├── resource_inventory     List[ResourceItem]       Step 2 产出
  ├── conversion_results     List[ConversionResult]   Step 3 产出
  ├── qualifier_mappings     List[QualifierMapping]   Step 3 产出
  ├── dependency_map         List[DependencyInfo]     Step 4 产出
  ├── recovered_resources    List[RecoveredResource]  Step 5 产出
  ├── verification_result    VerificationResult       Step 6 产出
  └── report_path            str                      Step 7 产出

DependencyInfo.category
  ├── CONVERTED    Category A：已转换资源的依赖（缺失会导致 HarmonyOS 运行时错误）
  └── LAYOUT_MENU  Category B：layout/menu 文件的依赖（重建 ArkUI 时所需）

LLM 调用说明

以下转换操作需要 LLM 推理，通过 llm_client.py 以 OpenAI Chat Completions 格式发起调用：

转换场景 调用接口
VectorDrawable / shape / layer-list / selector → SVG LLMClient.convert_xml_drawable_to_svg()
adaptive-icon XML → layered-image JSON LLMClient.build_layered_image_json()

--api-base-url 支持任何 OpenAI 兼容后端（Azure OpenAI、本地代理等），替换地址即可。

开发说明

实现 Stub 函数

Step 3～Step 6 的函数均已定义签名和完整 docstring，按以下顺序实现即可：

  1. step3_convert.py — 从 convert_color_value / convert_dimension_value / convert_string_value 等基础工具函数开始，再实现 map_qualifier_dir，最后实现各资源类型的 converter
  2. step4_deps.py — 实现 extract_dependencies（基于已定义的 _REF_PATTERN），再实现 check_dependency_satisfaction
  3. step5_resolve.py — 实现 build_apk → decompile_apk → extract_missing_from_apk → resolve_transitive_dependencies
  4. step6_verify.py — 五个独立的 verify 函数，orchestrator 已完成聚合逻辑

参考文档

详细转换规则请参阅 SKILL.md 同级的 references/ 目录：

  • references/conversion-rules.md — 完整资源类型转换规则
  • references/xml-drawable-to-svg-rules.md — XML drawable → SVG 详细规则
  • references/dependency-analysis-rules.md — 依赖提取模式和引用格式