npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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

HomeTrans工具用于辅助鸿蒙开发者完成原生安卓应用迁移到鸿蒙应用,为应用迁移的各个环节提供能力支持。

License: MIT Node.js DevEco Studio Android Studio DevEco CLI

Claude Code Cursor OpenCode DevEco Code Codex CodeBuddy Trae Code Trae CLI

能力全景图

project_architecture.svg


安卓应用迁移鸿蒙指导

💡 提示:为了提升迁移效果,请尽可能选择上下文窗口大的模型。 💡 提示:若希望 UI 迁移由模型识别页面截图,请使用多模态大模型(推荐 DeepSeekV4.1-Flash、Qwen3.8-Max、Kimi-K3、Opus-5),并做相关配置,确保开启视觉/图片输入。

安装与初始化

安装依赖

  1. 安装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 规格设计实现流水线(必需,构建门禁)

  2. 安装Android Studio — 下载地址:https://developer.android.com/studio,并在 SDK Manager 中安装SDK。

    验证方式:执行 adb version 返回正常

    被依赖:步骤2 UI迁移(可选,仅自动爬取页面快照时需要)

  3. 连接设备 — 连接安卓和鸿蒙真机,或启动模拟器

    被依赖:

    • 安卓真机/模拟器 — 步骤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:

choose_editor.png

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

参数配置:

配置鸿蒙SDK:

set_sdk.png

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

set_environment.png

SDK 路径只写入机器环境变量(Windows 用 setx,macOS/Linux 写入 shell rc 中由 HomeTrans 管理的区块),技能运行时也只从环境变量读取。ht init 不再生成 ~/.hometrans/config.json。多模态模型请在所用 editor 中自行选择并开启视觉/图片输入(见上文「安卓应用迁移鸿蒙指导」);旧版本留下的 ~/.hometrans 目录不会被读取,ht uninstall 会一并清理。

离线安装与初始化

目标机器无法联网时,先在一台联网机器上打包,再拷贝过去安装:

  1. 联网机器(需已安装 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 副本 |

  2. 拷贝 <bundle-dir> 到离线机器。

  3. 离线机器(需已手动装好 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>;不指定时为全局安装,写入各智能体的用户级目录 |


迁移流程

convert_pipeline_process.svg


一键全流程迁移(/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-reviewer fix 模式修复,整轮修完统一构建一次;最后一轮只读复核)→ 语义文档增量刷新(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-resource CLI(均由 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. 架构文档是绑定的 — 步骤1的三份文档(project_design.md、database_design.md、preferences_design.md)决定模块归属、数据表结构、Preferences键,只读,后续步骤不应修改。

  2. 步骤顺序 — 按 1 → 2 → 3 → 4 执行:步骤1定义目标项目结构并搭建工程骨架;步骤3的UTG workspace由步骤2产出;步骤4依赖步骤3的specs.json。使用 /hometrans 时由编排器自动处理顺序与并行(UI迁移与Spec生成可并行)。

  3. 验证范围 — 步骤4执行设计、逻辑转换、构建与代码评审;最终人工验收(步骤5)必不可少。

  4. 断点续跑 — 步骤1(generate_state.json)、步骤2(batch_progress.json)、步骤3(specs.json)与步骤4(spec_pipeline_state.json)均持久化进度,中断后重新调用同一命令即可从断点继续;全流程编排用 profile=resume FROM_NODE=<节点id> 续跑。