android-to-hmos-migration

Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。

插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。

主流程

迁移工作区固定位于安卓工程父目录下的 <工程名>-migration/.migration/，由 CLI 自动创建；下文 .migration/... 均相对该工作区根目录。

1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 模拟器是可选对照环境，缺失时只给出安装建议。
2. 运行 AppGraph，生成只读 .migration/spec/facts/ 与人工查看的 spec.html。
3. 从 facts 初始化 .migration/report/ 报告分片。
4. AI 以 Android 源码和运行行为为权威，自主规划并持续实现 HarmonyOS 应用。
5. 每完成一个可验证单元，同步填写实现映射和测试证据，并创建 Git 检查点。
6. 在 HarmonyOS 模拟器或真机上执行端到端功能验证；若 Android 模拟器可用，则同步进行双端页面对照。具备图片理解能力时全面比较视觉细节，否则比较页面内容、控件、状态与交互结果，不宣称像素级一致。发现 facts 遗漏时写入报告 discoveries。
7. 使用报告门禁检查已知 facts 覆盖；最终完成必须同时满足真实应用验收。

保留结构

android-to-hmos-migration/
├── .claude-plugin/          # Claude Code 插件清单
├── agents/                  # 报告驱动主 Agent
├── opencode/agents.json     # OpenCode Agent 权限
├── src/                     # OpenCode 插件入口、CLI 与命令实现（src/commands/）
├── schemas/                 # facts、报告与 Preflight 契约
├── skills/                  # Preflight、工程壳、报告、经验和流程复盘
└── package.json

安装

Claude Code：

/plugin marketplace add D:/code/a2h/android-to-hmos-migration
/plugin install android-to-hmos-migration@android-to-hmos-migration-local

OpenCode：

npm run install:opencode -- /path/to/android-project
# 或直接执行独立安装脚本：
./scripts/install-opencode.sh /path/to/android-project

该安装脚本生成项目级 .opencode/agent、.opencode/skill 和一个同时承载 Plugin/CLI 的 .opencode/plugin/android-to-hmos-migration.js。不会再生成 .opencode/android-to-hmos-migration 运行时目录，无需修改全局配置。首次遇到同名非托管文件时会停止；确认覆盖可使用 --force。

也可直接引用插件包：

{
  "plugin": ["D:/code/a2h/android-to-hmos-migration"]
}

重启后选择 android-to-hmos-00-orchestrator 执行完整迁移。

命令

droid2hmos init <android-project> [--target <harmony-project>]
droid2hmos status <android-project>
droid2hmos complete <android-project>
droid2hmos analyze <android|harmony|all> <android-project>
droid2hmos preflight <android-project> [--sdk-path <path>] [--no-init-harmony]
droid2hmos config init <android-project> [--harmony-project <path>] [--android-build <command>] [--android-test <command>]
droid2hmos config validate <android-project>
droid2hmos report init <android-project>
droid2hmos report validate <android-project> [--require-complete]
droid2hmos report <android-project> [--require-complete]
droid2hmos report render <android-project>
droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>] [--evidence <path>] [--difference <text>]
droid2hmos build <android|harmony|all> <android-project>
droid2hmos test android <android-project> [--task <task>]
droid2hmos test harmony <android-project> [--runner arkts] --class <class> [--case <case>] [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
droid2hmos test harmony <android-project> [--runner arkts] --all [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
droid2hmos test harmony <android-project> --runner python --hypium-project <path> --test-list <name>... [--target <serial>] [--python <path>] [--report-path <path>] [--ref <report-ref>...]
droid2hmos checkpoint status <android-project>
droid2hmos checkpoint create <android-project> --message <message> (--include <path>...|--all)
droid2hmos device check <android|harmony>
droid2hmos sign <android-project> [--target <serial>] [--force]
droid2hmos evidence capture <android|harmony> <android-project> --name <name> [--target <id>]
droid2hmos evidence compare <android-project> --name <name> --android <evidence-dir> --harmony <evidence-dir>
droid2hmos evidence flow <android|harmony> <android-project> --name <name> [--task <task>|--class <class> [--case <case>]|--all]
droid2hmos mock init <android-project> --spec <protocol-spec.json>
droid2hmos upgrade
droid2hmos service start <name> <android-project> [--health-url <url>] -- <command> [args...]
droid2hmos service status <name> <android-project>
droid2hmos service stop <name> <android-project>

• init：在 Android 工程的同级目录创建 {Android应用名称}Ohos HarmonyOS 工程，按本机 SDK 调整版本，完成受管 DevEco 登录和自动签名。
• status：只读检查现场并推导 phase、allowedActions、证据新鲜度和 completion.unmet，不写入一份可漂移的状态机文件。
• complete：最终硬门禁；只有 Preflight/设备、当前 Android 分析、完整报告、当前 HarmonyOS 全量回归和逐项受管证据都成立时返回成功。
• preflight：读取 CLI 内置的全局 config/preflight-checklist.json，按其中启用的 Android 技术栈、Git、主机工具链、DevEco CLI 登录、AppGraph、配置、Android 构建/模拟器、HarmonyOS 工程/SDK/构建/设备门禁执行，并生成 .migration/preflight-report.json。硬门禁失败后停止后续阶段；修改 enabled 会影响该 CLI 处理的所有项目。
• Preflight 的完整检查项、阻断规则和当前边界见 docs/preflight-checks.md。
• config：初始化或校验 .migration/config.json；按当前操作系统生成或修正 androidBuild 的 Gradle Wrapper 格式，允许显式配置 Android 构建与测试命令。
• analyze android：检查 Android APK 构建产物，通过 AppGraph 生成确定性 facts 和 spec.html。
• analyze harmony：分析 HarmonyOS 工程，并自动读取 config.json 中经验证的 HarmonyOS SDK 路径。
• report init：从 facts 初始化可增量维护的报告分片。
• report validate：检查报告结构与 facts 覆盖；--require-complete 用于最终门禁。
• report：缺少报告时先初始化，随后校验并生成 .migration/report/report.html；HTML 主体展示迁移结论、测试证据、差异和阻塞。
• build harmony：读取 DevEco JSON5 配置生成应用构建命令；Hvigor 命中增量缓存时允许复用不早于当前构建输入的非空 HAP，源码更新但产物过旧仍会失败。
• sign：真机自动签名。检测目标设备（默认第一个可响应设备，可用 --target 指定），读取设备 UDID，在签名材料未覆盖该设备时自动执行 devecocli signature generate --force 重新生成（devecocli 会把当前连接的设备注册进调试 profile）；模拟器自动跳过。同时读取真机系统版本判据（param get const.ohos.apiversion 声称值与 /system/etc/abc/framework/stateMgmt.abc 文件头解析出的运行时字节码上限取较小值；log 版镜像 param 可能虚报），若有效 API 低于工程 compatibleSdkVersion 则自动下调兼容版本（targetSdkVersion 保持不变，产物 abc 字节码版本由 compatibleSdkVersion 决定），保证老系统真机可安装且可启动。覆盖情况记录在 .migration/signature/devices.json，材料未变化时不重复生成；--force 强制重签。
• test harmony：支持 ArkTS 与 Python Hypium。多设备时优先真机，安装前自动检查签名和兼容版本；ArkTS 支持 --case-timeout-ms 和严格测试摘要校验，--ref 声明受管证据覆盖的报告项。
• test android：通过同一个有限命令运行器执行 commands.androidTest；可使用 {task} 模板接收 --task。
• checkpoint：检查 Git 基线，或只提交显式 --include 的文件；--all 必须由调用者明确选择，且不会提交 .migration/ 运行数据。暂存失败会回滚本次产生的暂存项。
• device 与 evidence：检查设备，采集截图、UI Tree 和有限设备日志，生成交互前后证据包，并对双端截图身份/尺寸及 UI Tree 文本做确定性比较。视觉一致性仍需图片审查。
• report update：按 ref 定位唯一报告项，只修改状态、实现文件、测试证据和差异字段，并校验项目内文件引用。
• mock init：从有 Android 源码证据的协议 JSON 生成无第三方依赖的 Node.js Mock Server、四类场景和请求 transcript；不会凭空推断接口。
• upgrade：通过 npm 将当前安装的 CLI 包全局升级到最新版本。
• service start/status/stop：启动、检查或停止 Mock Server 等长驻服务，并记录 PID 和独立日志。

HarmonyOS Hypium 测试

ArkTS/Hypium 用例位于 HarmonyOS 工程的 ohosTest target：

droid2hmos test harmony /path/to/android-project --runner arkts --class SettingsPageTest --case changeLanguage --target <serial>
droid2hmos test harmony /path/to/android-project --runner arkts --all

Python Hypium 模式执行已经存在的 Python 测试工程，不自动生成测试代码。该工程需包含 testcases/，每个 --test-list 对应其中的 <name>.json；运行环境需先安装 Hypium：

python3 -m pip install hypium -U

droid2hmos test harmony /path/to/android-project \
  --runner python \
  --hypium-project /path/to/hypium-project \
  --test-list Login \
  --test-list Settings \
  --target <serial>

可重复传入 --test-list，也可用分号连接多个名称。--python <path> 指定 Python 解释器，--report-path <path> 指定报告目录；未指定时报告写入 Android 工程同级的 <工程名>-migration/.migration/hypium-python-reports/。

命令执行日志

公开迁移命令默认在 Android 工程的 .migration/logs/ 记录结构化执行日志，无需增加参数。每天的摘要写入 daily/YYYY-MM-DD.jsonl，每次执行的完整记录写入 runs/YYYY-MM-DD/<run-id>.json，index.json 指向最近一次执行。密码、Token、Secret 和 API Key 参数会自动脱敏；日志写入失败不会改变原命令退出码。

droid2hmos logs list <android-project> [YYYY-MM-DD]
droid2hmos logs show <android-project> <run-id>
droid2hmos logs failures <android-project>
droid2hmos logs stats <android-project>

help、internal、dev 和日志查询本身不写执行日志，避免内部动作和查询行为污染迁移操作统计。

Migration Kernel

CLI 的 Kernel Interface 是 inspectMigration、guardMigrationAction 和 recordObservation，公开命令对应 status、各动作的前置 guard，以及命令结果中的 managedEvidence。Kernel 每次从项目事实重新计算，不信任 AI 手工推进的阶段标记：

• phase 只解释现场，allowedActions 提供多个安全能力，AI 仍决定实现批次和技术方案；
• Android 或 HarmonyOS 源码变化会改变内容指纹，使旧分析或旧测试证据自动失效；
• 失败收据提供 retry.kind、策略和最多自动重试次数；
• DROID2HMOS_GUARD_MODE=shadow 可用于观察非最终动作，但 complete 始终不可降级；
• HarmonyOS 测试收据记录目标设备、结构化测试结果与 coveredRefs；最终门禁逐 ref 校验覆盖关系；
• 证据产物按 SHA-256 归档到 .migration/evidence/blobs/，后续日志覆盖或归档内容被篡改都会使收据失效。

Mock Server 协议输入

mock init 要求每条路由都提供 success、empty、business-failure 和 boundary，并记录非空 sourceEvidence：

{
  "version": 1,
  "routes": [
    {
      "method": "GET",
      "path": "/notes",
      "sourceEvidence": ["app/src/main/java/example/NotesApi.kt:18"],
      "scenarios": {
        "success": { "status": 200, "body": [{ "id": "1", "title": "示例" }] },
        "empty": { "status": 200, "body": [] },
        "business-failure": { "status": 403, "body": { "error": "denied" } },
        "boundary": { "status": 200, "body": [{ "id": "max", "title": "边界数据" }] }
      }
    }
  ]
}

运行时通过请求头 x-droid2hmos-scenario 或查询参数 scenario 选择场景。

核心产物

迁移产物统一存放在安卓工程父目录下的独立工作区 <AndroidProject>-migration/ 中，不再写入安卓工程内部。创建 .migration/ 时会自动在工作区根目录生成 .gitignore（内容 .migration/），防止迁移产物被上层 Git 仓库提交到远端：

<父目录>/AndroidProject-migration/
├── .gitignore                # 忽略 .migration/，防止误提交
└── .migration/
    ├── preflight-report.json
    ├── spec/
    │   ├── index.json
    │   ├── facts/
    │   └── spec.html
    ├── report/
    │   ├── index.json
    │   ├── pages/
    │   ├── interactions/
    │   ├── discoveries.json
    │   ├── final-acceptance.json
    │   ├── summary.json
    │   ├── validation.json
    │   └── report.html
    ├── evidence/
    │   ├── index.json
    │   ├── blobs/<sha256>/
    │   └── managed/*.json
    └── experience/lessons.md

AppGraph 保持独立命令，由 npm 依赖提供并保证 appgraph 可从 PATH 执行。

Windows 下的构建与测试同样通过有限命令运行器执行，禁止把 Gradle 管道到 Select-Object、tail 等会延迟退出的命令。长驻服务必须使用 service start，避免命令运行器等待后代进程而挂死。

构建与校验

npm run build
npm run check
npm test

报告通过只证明已知 facts 有记录，不证明迁移成功。最终标准始终是：HarmonyOS 应用中的所有页面、控件、导航、Dialog 和业务功能与 Android 的外部可观察行为一致，并通过真实设备端到端验证。