android-to-hmos-migration

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

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

主流程

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 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> --class <class> [--case <case>]
droid2hmos test harmony <android-project> --all
droid2hmos checkpoint status <android-project>
droid2hmos checkpoint create <android-project> --message <message> (--include <path>...|--all)
droid2hmos device check <android|harmony>
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：从受管 DevEco 模板创建 HarmonyOS 工程壳。
• preflight：按 Android 技术栈、Git、主机工具链、AppGraph、配置、Android 构建/模拟器、HarmonyOS 工程/SDK/构建/设备的顺序执行门禁，并生成 .migration/preflight-report.json。硬门禁失败后不继续执行后续阶段。
• config：初始化或校验 .migration/config.json；自动识别 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 配置生成应用构建命令，并要求本次产生新的应用 HAP；配置文件不保存 HarmonyOS 构建命令。
• test harmony：确定性构建应用与 ohosTest HAP，安装到已连接设备并运行 Hypium；配置文件不保存 HarmonyOS 测试命令。
• test android：通过同一个有限命令运行器执行 commands.androidTest；可使用 {task} 模板接收 --task。
• checkpoint：检查 Git 基线，或只提交显式 --include 的文件；--all 必须由调用者明确选择，且不会提交生成的运行日志。
• 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 和独立日志。

命令执行日志

公开迁移命令默认在 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 和日志查询本身不写执行日志，避免内部动作和查询行为污染迁移操作统计。

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/
├── 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/
└── 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 的外部可观察行为一致，并通过真实设备端到端验证。