@buaa_smat/hometrans
v26.0.3
Published
HomeTrans (Android-to-HarmonyOS) skill + agent installer. Run `ht init` to distribute conversion skills and subagents into AI editors.
Readme
HomeTrans

HomeTrans工具用于辅助鸿蒙开发者完成原生安卓应用迁移到鸿蒙应用,为应用迁移的各个环节提供能力支持。
能力全景图
安卓应用迁移鸿蒙指导
💡 提示:为了提升迁移效果,请尽可能选择上下文窗口大的模型。 💡 提示:若希望 UI 迁移由模型识别页面截图,请使用多模态大模型(推荐 DeepSeekV4.1-Flash、Qwen3.8-Max、Kimi-K3、Opus-5),并做相关配置,确保开启视觉/图片输入。
安装与初始化
安装依赖
安装DevEco Studio — 下载地址:https://developer.huawei.com/consumer/cn/download/。安装完成后,配置以下 PATH环境变量(
<DevEco安装目录>指DevEco Studio的安装根目录):| 工具 | PATH中加入的目录 | |------|------------------| | node / npm / npx |
<DevEco安装目录>\tools\node| | java |<DevEco安装目录>\jbr\bin| | hdc |<DevEco安装目录>\sdk\default\openharmony\toolchains|验证方式:执行
node -v、java -version、hdc -v均返回正常被依赖:步骤2 UI迁移、步骤4 规格设计实现流水线(必需,构建门禁)
安装Android Studio — 下载地址:https://developer.android.com/studio,并在 SDK Manager 中安装SDK。
验证方式:执行
adb version返回正常被依赖:步骤2 UI迁移(可选,仅自动爬取页面快照时需要)
连接设备 — 连接安卓和鸿蒙真机,或启动模拟器
被依赖:
- 安卓真机/模拟器 — 步骤2 UI迁移(动态爬取页面快照时需要;已有快照则不需要)
- 鸿蒙真机 — 步骤1/步骤2/步骤4 收尾的冷启动冒烟门禁(无设备自动跳过)
安装HomeTrans
方式一:从源码仓库安装 — 在本仓库根目录执行:
npm install
npm link方式二:通过 npm 包全局安装 — 无需克隆仓库,直接安装已发布的包:
npm install -g @buaa_smat/hometrans验证方式:执行 hometrans --version 或 ht --version 返回正常
命令一览(hometrans 与 ht 等价):
| 命令 | 说明 |
|------|------|
| ht init [-a\|--all] [--lang <zh\|en>] [--offline-bundle <dir>] | 选择 editor 并安装 skills / agents / commands、安装依赖、配置环境变量;-a 跳过交互选择、配置全部 editor;--lang 指定安装语言(未指定时交互选择,-a 下默认中文);--offline-bundle 从离线包安装依赖 |
| ht config | 只读展示内置 editor 表(与 DevEco CLI 插件同一份)以及技能读取的 SDK 环境变量;不再有 ~/.hometrans 配置文件 |
| ht uninstall | 从已配置的 editor 中移除全部 hometrans skills / agents |
| ht offline-bundle <dir> | 为无网机器制作离线依赖包(见离线安装与初始化) |
环境初始化
执行 hometrans init 或 ht init。
自动安装的依赖
ht init 的 Dependency Installation 阶段会自动安装以下依赖,无需手动处理(已安装的项自动跳过):
| 依赖 | 类型 | 用途 / 被依赖 |
|------|------|---------------|
| node(≥ 22.18)+ npm | 系统工具(需自行安装) | 全部技能脚本(.mjs / .ts,type stripping)与 reqgen 自检命令;npm 同时被 ht init 自身与离线包流程使用 |
| git | 系统工具 | agent precheck、git 提交流程;≥ 2.38 时启用步骤4 波末审计的 resolver 手写归责层(更低版本该层自动跳过并告警) |
| homegraph + arkanalyzer | npm 全局 | 默认代码分析引擎(arkanalyzer 解析 ArkTS .ets);步骤3、步骤4(必需) |
| homecheck | npm 全局 | 静态缺陷扫描引擎;步骤4 波循环收尾的静态缺陷检查(必需) |
| @deveco/deveco-cli | npm 全局 | 构建入口 devecocli build(需 DevEco Studio ≥ 6.1.0);步骤1 工程壳创建、步骤2、步骤4(必需) |
| a2h-resource | npm 全局 | APK 资源解码器;步骤2 UI迁移与独立skill a2h-resource-convert 使用 |
| commander、zod、web-tree-sitter、tree-sitter-wasms | npm 全局 | reqgen 运行库;由 ht init 通过 npm link 链接进各技能副本的 node_modules |
验证方式:执行 homegraph --version、homecheck --version、devecocli --version、a2h-resource 均返回正常;ht init 末尾的 Environment Check 会逐项检测并报告缺失项对各技能的影响。
选择本地editor:

若一个 editor 都不选择,
ht init不会中断:仍会执行后续全部配置流程,并把 skills / agents / commands 原样拷贝到共享目录~/.agents/skills、~/.agents/agents与~/.agents/commands(ht uninstall也会清理这些目录)。
参数配置:
配置鸿蒙SDK:

将配置信息添加到环境变量:

SDK 路径只写入机器环境变量(Windows 用
setx,macOS/Linux 写入 shell rc 中由 HomeTrans 管理的区块),技能运行时也只从环境变量读取。ht init不再生成~/.hometrans/config.json。多模态模型请在所用 editor 中自行选择并开启视觉/图片输入(见上文「安卓应用迁移鸿蒙指导」);旧版本留下的~/.hometrans目录不会被读取,ht uninstall会一并清理。
离线安装与初始化
目标机器无法联网时,先在一台联网机器上打包,再拷贝过去安装:
联网机器(需已安装 hometrans、node/npm):
ht offline-bundle <bundle-dir>产出
<bundle-dir>/(整体拷贝/压缩即可):| 内容 | 说明 | |------|------| |
install.sh/install.ps1| 离线引导脚本:自动挑选匹配本机平台的 tarball 安装,并在同一进程内执行ht init --offline-bundle| |buaa_smat-hometrans-<版本>.tgz| 本地构建的 hometrans 本体 | |npm-cache/| npm 自包含缓存:全部 npm 依赖及完整传递依赖 | |manifest.json| 版本锁定清单 | |README.md| 项目 README 副本 |拷贝
<bundle-dir>到离线机器。离线机器(需已手动装好 DevEco Studio、Android Studio、node/npm、git)运行引导脚本:
# macOS / Linux sh "<bundle-dir>/install.sh" # Windows powershell -ExecutionPolicy Bypass -File "<bundle-dir>\install.ps1"
作为 DevEco CLI 插件安装
HomeTrans 支持以 DevEco CLI 插件形态进行安装。安装后由 DevEco CLI 统一管理 HomeTrans 的 skills / agents / commands,无需再运行 ht init。
安装
devecocli plugin install hometrans [--agent <name>] [--project <project_dir>]升级 / 卸载
devecocli plugin update hometrans [--agent <name>] [--project <project_dir>]
devecocli plugin uninstall hometrans [--agent <name>] [--project <project_dir>]支持的智能体
opencode、trae、deveco、cursor、codebuddy、qoder、claude-code、codex、atomcode
参数说明
| 参数 | 说明 |
|------|------|
| --agent <name> | 目标智能体,取上述 9 个规范名;不指定时处理本机已安装的全部受支持智能体 |
| --project <project_dir> | 工程级安装,内容写入 <project_dir>/<智能体工程目录>/{skills,agents,commands},目录名默认为 .<agent>;不指定时为全局安装,写入各智能体的用户级目录 |
迁移流程
一键全流程迁移(/hometrans)
ht init 会同时安装 /hometrans 命令,它加载编排 skill a2h-app-migrate,按声明式 DAG(references/workflow.yaml)串起下文步骤1–4:参数预检 → 环境预检 → discover(架构生成 + 静态UTG)→ UTG 快照冻结 → UI迁移 ∥ Spec生成 → 逻辑转换 → 构建修复与冷启动冒烟。
/hometrans <android_project_dir> <harmony_project_dir> [apk_path=<apk>] [specs_json=<specs.json>] [app_module=<:app>] [profile=full|ui-only|resume] [INTERACTION_MODE=auto|interactive]常用参数
| 参数 | 类型 | 说明 |
|------|------|------|
| <android_project_dir> / <harmony_project_dir> | 必选 | 绝对路径;鸿蒙工程不存在时由步骤1新建(新建工程路径须纯 ASCII、不含空格,且两个工程目录不能互相嵌套) |
| apk_path | UI链路运行时必选 | APK 绝对路径(资源转换的唯一来源);缺失时在启动配置那一轮追问 |
| specs_json | 可选 | 显式提供 = 直接使用这份清单,跳过 Spec 生成 |
| app_module | 多 application 模块时必选(UI 链路 / Spec 生成) | Android application 模块(如 :app);唯一时自动检测。UI链路与 Spec 生成共用 |
| profile | 可选 | full(默认)/ ui-only / resume(配合 FROM_NODE=<节点id> 断点续跑)。|
| INTERACTION_MODE | 可选 | 人工闸门:ask(默认,启动时询问)/ auto / interactive。选了 auto 后不再询问人工检查项。interactive 时才单独问 INTERACTIVE_GATES。调度不再询问,未传入时串行 |
| ENGINE_MODE / WAVE_WIDTH / MAX_SCENARIOS_PER_CHUNK | 可选 | 透传给步骤4 |
所有产物落在鸿蒙工程目录(工作区默认
<harmony_project_dir>/.hometrans/app-migrate)。环境预检只把本轮会运行的节点所需的项判为硬性要求(APK / adb / DEVECO_HOME / Node.js+npm / 全局 homegraph / 全局 homecheck / devecocli 登录等);devecocli 登录仅在工程尚无签名配置、需要生成签名时才要求。某个节点失败会记入 ledger,下游照常调度(例如 UI 失败不会阻断逻辑链路)。
也可以按下文步骤逐个单独调用各 skill。
步骤1:架构生成(a2h-arch-generate)
📦 依赖:Node.js ≥ 22.18(必需);devecocli ≥ 1.3.3(必需,工程壳创建 + 收尾冷启动冒烟检查);鸿蒙真机/模拟器(可选,收尾冷启动冒烟门禁,无设备自动跳过);homegraph(可选,代码证据源,
ht init自动安装;建索引前会先征询用户,不可用时降级为本地分析,不中断运行)。
/a2h-arch-generate <android_project_dir> --target-project-dir <path> [--mode auto|generate|reconcile] [--scope full|backend] [--follow-source true|false] [--layered-architecture true|false]输入参数
| 参数 | 类型 | 说明 |
|------|------|------|
| <android_project_dir> | 必选 | 源码项目根目录路径(Android 或 uniapp) |
| --target-project-dir | 必选 | 目标目录:不存在或为空(仅容忍 .git)时由 devecocli 创建为鸿蒙工程壳(路径必须纯 ASCII,不能含中文/空格);已是合法鸿蒙工程时进入 reconcile 模式。同时是三份架构文档与分析产物的所在位置 |
| --mode | 可选 | auto(默认,按目标目录状态自动路由)、generate(新建工程)或reconcile(适配已有鸿蒙工程);显式指定的模式与路由结果不符时直接阻断 |
| --scope | 可选 | 范围:full(默认,含UI+业务+平台)或backend(仅逻辑/服务/数据/平台) |
| --follow-source | 可选 | true(默认,保留经确认的源码边界——跟随安卓架构)或false(先推导平台无关的logical架构) |
| --layered-architecture | 可选 | 是否生成分层架构(products/features/common);默认true,仅 generate 模式生效(reconcile 模式按现有工程推导打包结构) |
输出产物
| 产物 | 位置 | 说明 |
|------|------|------|
| project_design.md | <target-project-dir>/.hometrans/ | HarmonyOS目标架构设计:项目结构树+模块语义表 |
| database_design.md | <target-project-dir>/.hometrans/ | 数据库设计:表结构、字段、键约束(无数据库时为空状态格式) |
| preferences_design.md | <target-project-dir>/.hometrans/ | Preferences设计:键值存储的键、类型、默认值(无KV存储时为空状态格式) |
| 分析产物 | <target-project-dir>/.hometrans/arch_generate/ | Android项目分析结果、HomeGraph证据、验证报告 |
| 鸿蒙工程壳 | target-project-dir | 经 devecocli create 搭建的可DevEco打开的空工程壳(含AppScope/build-profile/hvigorfile),再按project_design.md挂载arch目录树(不含实现代码) |
架构设计是一次性工作:设计目标架构、生成三份绑定文档并搭建鸿蒙工程壳。后续步骤均以这三份文档为约束,不应修改它们。generate 模式的进度记录在
.hometrans/arch_generate/generate_state.json,建壳后中断的运行重新调用会续跑 generate,而不会把半成品工程误判为 reconcile。
步骤2:UI迁移(a2h-batch-ui-align)
📦 依赖:DevEco Studio + devecocli ≥ 1.3.3(必需,构建门禁与收尾冷启动冒烟检查,需配置
DEVECO_HOME环境变量);Node.js ≥ 22.18(必需);homegraph(必需,静态 UTG);安卓真机/模拟器 + adb(必需,a2h-utg-explorer采集页面快照),未截到图的页面按源码以 source-only 档转换;鸿蒙真机(可选,收尾冷启动冒烟门禁,无设备自动跳过)。
/a2h-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> apk_path=<APK文件路径> [ui_info_root=<页面快照目录>] [pages=<页面子集>]输入参数
| 参数 | 类型 | 说明 |
|------|------|------|
| android_project_dir | 必选 | Android项目根目录路径 |
| harmony_project_dir | 必选 | HarmonyOS目标项目路径(步骤1产出的工程) |
| apk_path | 必选 | Android APK文件完整路径(资源转换时解码以提取含库依赖的完整合并资源集) |
| ui_info_root | 可选 | 含 page_NNNN_ActivityName 格式子目录的父目录(每子目录含 meta.json + view.xml + 可选 screenshot.png);默认 <harmony_project_dir>/.hometrans/ui_info;无现成快照时自动爬取 |
| pages | 可选 | 显式列出的页面子集(不提供则处理所有页面) |
| app_module | 可选 | Android application 模块(Gradle 路径如 :app,或相对目录 app);透传给资源转换,多 application 模块工程不再中途检测/询问 |
输出产物
| 产物 | 位置 | 说明 |
|------|------|------|
| ArkTS页面文件 | HarmonyOS项目下 | Android Activity转换生成的ArkTS页面(MVVM,V1/V2范式按目标工程自动检测) |
| 资源与映射文档 | HarmonyOS项目下、.hometrans/resource_mapping.md | 内部自动触发 a2h-resource-convert 的转换产物及Android ↔ HarmonyOS资源映射 |
| UTG workspace | <harmony_project_dir>/.hometrans/utg_static/ | Android UI迁移图(utg.json + click_paths.json),供步骤3使用 |
| 页面快照与pages.json | ui_info_root 下 | 各页面快照及按拓扑排序生成的页面清单(保证被引用页面先迁移) |
| 进度与报告 | .hometrans/batch_progress.json、.hometrans/batch_report.md | 逐页进度检查点(支持断点续跑)与批量转换报告 |
流程: 资源转换(
a2h-resource-convert,以APK为源)→ 页面探索(静态UTG骨架 + 设备探索:先把APK安装到安卓设备,由a2h-utg-explorer按静态UTG逐页抓取(增量模式只抓所选范围),不需要模型key;抓不到的页面按源码转换(source-only))→ 逐页子代理并发转换为ArkTS MVVM页面(含Lottie动画绑定;main_pages.json、resources/**/element/*.json、oh-package.json5、module.json5等共享注册文件由父代理统一合并写入)→ 静态检查 +a2h-fix-build-errors统一构建至整工程编译通过 → 冷启动冒烟门禁(a2h-coldstart-smoke-gate:真机装启,检测闪退/白屏并按证据自动修复,最多5轮)。续跑:
batch_progress.json记录已完成的阶段,续跑时不会重做已完成的资源转换与页面抓取(避免覆盖已合并的资源条目、打乱已完成页面的快照编号);如需重做,明确要求“重新转换资源”/“重新抓取”,此时会作废旧进度重新开始。
步骤3:生成需求规格(a2h-spec-generate)
📦 依赖:Node.js ≥ 22.18(必需,reqgen 运行库与确定性脚本);homegraph(必需,代码分析引擎)。
前置:UTG workspace — 即步骤2产出的
<harmony_project_dir>/.hometrans/utg_static/,直接作为utg-workspace传入。
/a2h-spec-generate <android_project_dir> utg-workspace=<utg_workspace> [output=<run_directory>] [concurrency=<n>] [application-module=<module>]
输入参数
| 参数 | 类型 | 说明 |
|------|------|------|
| <android_project_dir> | 必选 | Android或UniApp源码根目录路径,保留原参数名(CLI 从源码自动识别项目类型) |
| utg-workspace | 必选 | 与源码匹配的UTG工作空间路径(包含utg.json和click_paths.json,只读) |
| output | 可选 | 运行目录;默认工作区根目录下 .hometrans/reqgen/<case-id>--<时间戳> |
| concurrency | 可选 | fused per-Area 子代理并发数(默认8) |
| application-module | 可选 | Android application 模块(Gradle 路径如 :app);提供时直接使用,不再自行判断或询问 |
输出产物
| 产物 | 位置 | 说明 |
|------|------|------|
| specs.json(idx 根) | <output>/generation/specs/ | 内部锚点清单 — 按 Area 批次顺序的确定性清单 |
| <feature>-SPEC.md(idx 根) | <output>/generation/specs/<N>/ | 每个功能的原子场景规格文档(worker 直出) |
| specs.json(页面根) | <output>/generation/pages/ | 下游消费的发布清单 — Step 5b 按页面重新分组后重新铸造(页名字典序 + 页内文件名字典序) |
| <feature>-SPEC.md(页面根) | <output>/generation/pages/<页面>/ | 与 idx 根逐字节相同的 SPEC,按用户可见页面分组(同名冲突按 -<idx> 消歧、逐字节重复去重,均记入 pages.json 警告) |
| pages.json | <output>/generation/pages/ | 分组视图:每页成员、计数、警告(无时间戳、无绝对路径,重跑逐字节复现) |
流程(单 skill,内部步骤):
prepare(冻结UTG,并给每个选中Area生成一个area-fusion任务)→ fused per-Area worker(归并 + SPEC 编写在同一会话完成)→check-fused-spec(L1 自检:check-fusion+ SPEC 校验)→finalize(L2 铸控件:<controlRef>身份、跨Area去重、发布generation/spec-bindings.json)→collect-specs(收集SPEC到发布根并注入身份)→publish-specs(发布 idx 根specs.json)→ Step 5b:regroup-by-page(按冻结拓扑把 idx 根的 SPEC 折叠进页面目录,整树重建generation/pages)→publish-specs --root .../pages(发布页面根自己的specs.json,下游a2h-spec-design-pipeline按其页面目录切组)。
合并说明: 原来的 req-gen 阶段与 specgen 阶段(两个独立 skill)、以及串联它们的 pipeline,现已合并为这一个 skill(
skills/a2h-spec-generate/,对外入口/a2h-spec-generate)。每个选中Area只有一个 fused worker(model-render-worker),在同一会话里完成归并与SPEC;candidate-review worker(model-worker)仍独立并行,按 ≤8 并发以 background 滚动派发。
specs.json 在全部页批次就绪后发布:idx 根 <output>/generation/specs/ 是内部锚点,页面根 <output>/generation/pages/ 是下游消费面(so-id 按页面顺序重新铸造——换根等于新 campaign,不要中途换);两处目录都应只包含本次运行的产物,不混入历史SPEC。发布是 fail-closed 的:finalize 只在模型语义完整时给出 run-report.json = succeeded/publishable: true(有 Area 没跑完时写 failed 并非零退出),collect-specs、两处 publish-specs 都按这份标记拒绝部分运行(regroup-by-page 无门禁参数,只从已发布的 idx 根拷贝);确要发布部分结果必须显式加 --allow-incomplete(只加在 collect-specs 与两处 publish-specs 上),此时 specs.json 会带上 completeness: "incomplete-known" 与 incomplete: { areas, failedShards },下游可据此区分"完整页集"与"部分页集"。
步骤4:规格设计实现流水线(a2h-spec-design-pipeline)
📦 依赖:DevEco Studio + devecocli ≥ 1.3.3(必需,构建与收尾冷启动冒烟检查);homegraph(必需,代码分析引擎);homecheck ≥ 2.0.0-next.0(必需,波循环收尾的静态缺陷检查);Node.js ≥ 22.18(必需,四个确定性管线脚本);鸿蒙真机(可选:
--skip-test false波内自测与收尾冷启动冒烟门禁;无设备自动跳过);git ≥ 2.38(可选:波末审计的 resolver 手写归责层使用merge-tree --write-tree,更低版本该层自动跳过并 stderr 告警,不阻塞)。
前置:步骤3生成的
specs.json;鸿蒙工程须为 git 仓库(不要求签名配置:未签名照常编译,仅真机冒烟记DEPLOY_ERROR)。首个波次前若工程尚无提交或存在未提交的上游产物,流水线会自动提交一次pre-campaign baseline,并把.hometrans/、.homegraph/加入.gitignore。
/a2h-spec-design-pipeline <specs.json> <android_project_dir> <harmony_project_dir> <design_output_dir> [--engine-mode auto|off|required] [--wave-width N] [--max-scenarios-per-chunk N] [--deveco-home <dir>]输入参数
| 参数 | 类型 | 说明 |
|------|------|------|
| <specs.json> | 必选 | 步骤3生成的规格清单({specs:[{path, ui_sequence, so-id}]};so-id可选、默认按从1开始的顺序编号;组内保持文件顺序,跨组按扫描顺序与优先级处理,不是依赖链;条目可含可选 error_count(整数≥0)——机械门残余 error 数,0=干净、缺席=旧生产者,>0 为显式质量标注而非错误) |
| <android_project_dir> | 必选 | Android项目根目录路径 |
| <harmony_project_dir> | 必选 | HarmonyOS项目根目录路径(须为git仓库) |
| <design_output_dir> | 可选 | 设计文档输出目录(存放SPEC_DESIGN_G<G>_c<k>.md chunk 设计文档);默认<harmony_project_dir>/.hometrans/spec_design/ |
| --engine-mode | 可选 | 引擎证据严格度:auto(默认,尽力而为)、off(禁用)、required(无证据即中止) |
| --wave-width | 可选 | 每波并行组数(默认10;尾波取余) |
| --max-scenarios-per-chunk | 可选 | 每编码分块最大场景数(默认32;spec原子——一个spec的场景不跨块拆分) |
| --deveco-home | 可选 | 所有构建使用的 DevEco Studio 安装根目录;默认取环境变量 DEVECO_HOME / DEVECO_SDK_HOME |
输出产物
| 产物 | 位置 | 说明 |
|------|------|------|
| SPEC_DESIGN_G<G>_c<k>.md + design_map.md | design_output_dir | 每个 chunk 一份设计文档(该 chunk 的证据锚点与数据约束)及索引表 |
| 业务逻辑代码 | HarmonyOS项目下 | ViewModels、services、repositories、数据访问、导航接线(不含ArkUI页面布局) |
| 运行状态与报告 | <harmony_project_dir>/.hometrans/ | spec_pipeline_state.json(断点续跑;收尾完成后写入 finalization 完成标记)、逐波审计/评审/构建报告、终报汇总 |
| 语义文档 | HarmonyOS项目下 | project_design.md、各模块module_design.md(每波增量刷新) |
| git提交 | HarmonyOS项目 | 每组以group G (specs so-a..so-b)标记提交收尾;另有每波wiring提交与构建修复提交 |
流程: 初始化做一次性准备(
a2h-module-semantic-docs生成语义文档基线),随后进入波循环直至无剩余组。每波:切片(S0,按组顺序做依赖感知的回填扫描,取至多--wave-width个未分配组;依赖预测会导致并发严重塌缩时退化为纯按顺序的 flat 切片)→ 并行编码与串行合并交织(B1⇄B2:每组独立git worktree、分块后台派发;共享注册文件经wiring.md只记录不编辑;组完成即合并、主树串行写入、冲突恢复阶梯)→ 波末统一应用wiring → 一次构建(B3)→ 按组评审与修复(B4,code-reviewer按组评审;第二轮起只复审仍有问题的组;每个有问题的组单独一次code-reviewerfix 模式修复,整轮修完统一构建一次;最后一轮只读复核)→ 语义文档增量刷新(B5)→ 每组标记提交(C)。波循环结束后运行冷启动冒烟门禁(a2h-coldstart-smoke-gate:真机装启检测闪退/白屏,按证据自动修复,最多5轮),随后收尾运行一次a2h-fix-build-errors兜底并输出汇总报告。组失败不中断运行(fail-soft):该组及其全部spec标记为failed,记录后继续,全部问题汇总到运行结束后的报告。
步骤5:人工验收(👤 用户介入)
通读步骤4汇总报告,结合各spec评审报告与构建产物,真机走查核心场景,处理遗留缺陷/TODO后发布。
独立skill能力
转换看板(a2h-dashboard-render)
Node.js 版本为默认入口,要求 Node.js 22.18.0 或更高版本,不依赖第三方 npm 包:
node skills/a2h-dashboard-render/scripts/dashboard.mjs <HarmonyOS项目路径>使用配置文件跟踪项目、Spec/UI 状态文件及 Android 对照工程。先复制示例并把路径 改成自己的项目路径:
Copy-Item skills/a2h-dashboard-render/references/dashboard.config.example.json dashboard.config.json
node skills/a2h-dashboard-render/scripts/dashboard.mjs --config dashboard.config.json仅生成静态 HTML:
node skills/a2h-dashboard-render/scripts/dashboard.mjs <HarmonyOS项目路径> --once --out dashboard.html --no-open看板读取 batch_progress.json、spec_pipeline_state.json、各 Spec 的
pipeline-manifest.md 及构建/评审报告;缺失的权威状态显示为“未记录”,
不会按文件存在性猜测完成。
资源转换(a2h-resource-convert)
📦 依赖:Node.js +
a2h-resourceCLI(均由ht init自动安装;解码失败时回退读取源码res/)。已执行步骤2时无需单独调用(步骤2内部已包含资源转换)。
/a2h-resource-convert android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径> apk_path=<APK路径> [app_module=<:app>]输入参数
| 参数 | 类型 | 说明 |
|------|------|------|
| android_project_dir | 必选 | Android项目根目录路径(含 build.gradle 或 build.gradle.kts) |
| harmony_project_dir | 必选 | HarmonyOS项目输出路径 |
| resource_mapping_path | 必选 | Android ↔ HarmonyOS资源映射文档的完整输出路径(.md) |
| apk_path | 必选 | Android APK文件路径(用于提取完整合并资源集) |
| app_module | 可选 | Android application 模块(:app / :apps:tv 或相对目录 app);不提供时自动检测,多个 application 模块时询问 |
输出产物
| 产物 | 位置 | 说明 |
|------|------|------|
| resources/ 目录 | HarmonyOS项目下 | 转换后的HarmonyOS资源(strings、colors、dimensions、images等) |
| 资源映射文档 | resource_mapping_path | Android ↔ HarmonyOS资源条目映射(.md) |
| 转换报告 | HarmonyOS项目下 | 资源转换过程与统计 |
冷启动冒烟门禁(a2h-coldstart-smoke-gate)
📦 依赖:devecocli ≥ 1.3.3 + 鸿蒙真机/模拟器(缺失或版本不足自动跳过,不阻塞)。步骤1/步骤2/步骤4 收尾时自动调用,也可单独调用。
/a2h-coldstart-smoke-gate harmony_project_dir=<鸿蒙项目路径>安装既有HAP并启动,执行 devecocli 内建冷启动冒烟检查(进程存活 + 非白屏)。真机目标先做签名预检:build-profile.json5 无 signingConfigs 时自动执行 devecocli signature generate 生成签名材料,未登录则提示执行 devecocli auth login 后继续。FAIL_CRASH/FAIL_BLANK 时读取证据文件(.hvigor/smoke-crash-*.log / smoke-screenshot-*.png)定位根因并直接修复、重建重测(最多5轮)。
关键约束与说明
架构文档是绑定的 — 步骤1的三份文档(
project_design.md、database_design.md、preferences_design.md)决定模块归属、数据表结构、Preferences键,只读,后续步骤不应修改。步骤顺序 — 按 1 → 2 → 3 → 4 执行:步骤1定义目标项目结构并搭建工程骨架;步骤3的UTG workspace由步骤2产出;步骤4依赖步骤3的
specs.json。使用/hometrans时由编排器自动处理顺序与并行(UI迁移与Spec生成可并行)。验证范围 — 步骤4执行设计、逻辑转换、构建与代码评审;最终人工验收(步骤5)必不可少。
断点续跑 — 步骤1(
generate_state.json)、步骤2(batch_progress.json)、步骤3(specs.json)与步骤4(spec_pipeline_state.json)均持久化进度,中断后重新调用同一命令即可从断点继续;全流程编排用profile=resume FROM_NODE=<节点id>续跑。
