HMBot for DevEco Code

以 Android 源码为依据，用动态并行工作流推进 HarmonyOS 迁移。

项目仓库 · npm 包 · 问题反馈

HMBot 是运行于 DevEco Code 的 Android → HarmonyOS 迁移套件。它把源码探索、轻量规格、并发实现和实际验收组织为一个持续推进的任务：主 agent 掌握全局范围和依赖，worker 承担可并发的工作，主 agent 集中集成、验收与修复。

迁移以用户明确的目标和约束为准，未约定部分按源码完整迁移，覆盖应用名称与图标、页面与状态、功能与数据行为。PRD 和验收用例用于明确要求，未列入用例不自动等于排除范围。

当前版本支持 Android → HarmonyOS 迁移；iOS 与跨平台框架迁移是后续扩展方向。

工作方式

1. 盘点与探索：识别页面、入口、功能、数据和平台集成，按业务域分批读取源码，保留源依据与未知项。
2. 规格与计划：在普通 Markdown 中组织覆盖范围、接口、当前任务和验收场景，复用已有需求、测试与证据。
3. 并发实现：workflow 派发可并发的探索、开发和按需只读审查；按真实依赖和写入范围协调任务。
4. 集成与验收：尽早运行可交付增量，检查功能、状态变化与 UI，再修复问题并推进剩余范围。

能力	对迁移的帮助
动态并行	根据接口、依赖与写入范围安排就绪任务，共享业务链上的任务也可以并发
全量范围跟踪	将页面、条件功能、资源和平台能力纳入计划，避免首条路径通过后遗漏其它功能
UI 还原	追查源布局、主题、默认控件样式和原始资源，对照目标实际呈现
多种验证方式	按可用能力使用真机、模拟器、截图、视觉工具、控件树、坐标与日志
局部故障容错	记录具体阻塞及恢复条件，继续不依赖该条件的实现与验证
按需知识	复用源码、SDK、官方文档和知识 MCP；只为当前问题读取相关资料

图中的工具和知识由宿主或开发环境提供，按任务取用。更详细的目标架构图包含后续能力包等规划，不能视为全部能力均已接入。

历史迁移示例

Cofi 咖啡配方应用的双端英文首页，使用浅色咖啡主题。两端配方、图标与主要布局可直接对照；标题栏、卡片间距与同屏可见条目数仍有差异。

Android	HarmonyOS

AntennaPod 的深色订阅页，两端均订阅 The Daily，迷你播放器显示同一集节目并处于暂停状态。封面边距、按钮颜色与导航选中样式仍有差异。

Android	HarmonyOS

截图用于展示迁移案例，不代表本次版本的完整回归结果。应用名称、图标与节目封面属于各自权利人。

开始之前

• Node.js 22 或更高版本。
• 已安装 DevEco Code，并配置可用模型。
• 可读取的 Android 源工程，以及用于迁移的工作目录。
• 构建与运行时需要对应的 HarmonyOS SDK、工具链，以及适用的模拟器或真机。

模型、设备与开发工具由宿主和开发环境提供。多模态能力可增强 UI 外观验证；没有视觉能力时，仍可检查功能、控件结构和相对布局，无法确认的绘制效果会保留为未验。

安装

通过 devecocli 管理

在目标工作区安装：

devecocli plugin install hmbot --agent deveco --project "/path/to/workspace"

需要使用包含 plugin 管理及 hmbot 白名单的 devecocli 版本；可用 devecocli plugin list 检查。若当前版本没有该命令，使用下面的独立安装方式即可。

省略 --project 时安装到 DevEco Code 的全局配置目录；--agent deveco 指定目标宿主。

从 npm 独立安装

不通过 devecocli，也可以直接调用同一个安装器：

npx --yes @hmbot/hmbot@latest install --project "/path/to/workspace"

将 --project "/path/to/workspace" 换成 --global 可全局安装。需要固定版本时，将 @latest 换成 @0.1.5。

已有发行包或离线安装

拿到完整发行包后，直接运行包内脚本，无需再次从 npm 下载：

node /path/to/hmbot/install.mjs install --project "/path/to/workspace"

工作目录需要预先存在。一个工作区选用一种安装范围，并用原安装方式管理后续更新和卸载，避免同时加载项目级和全局安装。安装后重新加载 DevEco Code。

发起迁移

在 DevEco Code 中打开上述工作区，使用 /hmbot 提供源工程、目标位置和要求。例如：

/hmbot 将 /work/CofiAndroid 完整迁移到 /work/CofiHarmony。
保留原应用名称、图标、页面、交互与数据行为。
需求与验收约定见 /work/prd.md；未约定的部分按源码迁移。
目标 SDK 和可用设备以当前工程与环境为准。

PRD、参考截图、录屏、设计资源和已有测试均可补充，但不是开始迁移的必需项。若只需要迁移部分范围，请明确列出范围与排除项。

续接已有工程时，给出源工程、目标工程及现有计划位置。HMBot 会复用已有实现、笔记和有效证据，将未完成项接回计划。

查看进度与结果

迁移过程中可通过会话、workflow 进度面板和项目文件了解状态：

产物	内容
HarmonyOS 工程	页面、业务逻辑、资源、配置和平台适配代码
spec/migration.md	覆盖范围、任务、接口、验收场景、进度、证据与下一步
spec/areas/	按业务域保留的源码事实、风险与待确认事项
验证材料	实际生成的构建诊断、测试结果、截图、控件树和运行日志
完成说明	已实现与已验证的内容、失败项、未验项、差异及恢复条件

构建通过、工具调用成功或截图已保存，都不单独代表迁移完成。UI 验证需要核对对应页面与状态；非视觉证据能说明结构与行为，不能证明颜色、图形和实际绘制完全一致。局部设备或服务问题只影响依赖它的步骤，其余工作继续推进。

更新、卸载与检查

通过 devecocli 安装的工作区：

devecocli plugin update hmbot --agent deveco --project "/path/to/workspace"
devecocli plugin uninstall hmbot --agent deveco --project "/path/to/workspace"

通过 npm 独立安装的工作区：

npx --yes @hmbot/hmbot@latest update --project "/path/to/workspace"
npx --yes @hmbot/hmbot@latest uninstall --project "/path/to/workspace"

已有发行包时，将上述独立命令的 npx --yes @hmbot/hmbot@latest 换成 node /path/to/hmbot/install.mjs 即可。独立安装器还支持 status、selfcheck 和 doctor：

npx --yes @hmbot/hmbot@latest selfcheck --project "/path/to/workspace"

更新从 npm 的 latest 获取已发布版本；本地脚本更新使用当前发行包，不自动联网下载。日常更新直接替换已登记的套件文件并清理退役文件，无需先卸载。更新和卸载保留应用代码、spec、workflow 运行记录及其它插件文件；更新失败时尝试恢复原套件文件与安装记录。操作后重新加载 DevEco Code。

官方文档与知识服务

HMBot 按具体问题使用本地源码、原始资源、已有测试、目标 SDK 与官方资料。源码没有显式写出的尺寸、主题或默认控件外观，可通过按需参考文档追查实际生效的定义。

插件默认接入华为 HarmonyOS 知识 MCP，已有同名配置优先。服务可用于查询目标 API、平台限制和开发说明，答案仍需对照实际 SDK/API 版本与应用调用。服务不可用时继续使用本地 SDK 和其它可靠资料。

如需关闭默认知识服务，在项目 deveco.json 或 deveco.jsonc 中合并以下配置，再重新加载宿主：

{
  "mcp": {
    "harmonyos_developer_knowledge": {
      "enabled": false
    }
  }
}

官方接入说明：HarmonyOS 开发者知识 MCP。

常见问题

主模型不支持多模态，还能迁移吗？

可以。若宿主有可用的独立视觉工具，仍可使用它核对外观；否则使用设备操作、控件树、坐标和日志验证功能及结构，并明确无法确认的外观。不因主模型类型直接禁用视觉工具。

没有真机或签名，会阻塞全部迁移吗？

按实际环境判断。适用的模拟器和无需该条件的构建、实现、检查可以继续；仅能在真机或特定环境确认的能力保留待验及恢复条件。

会给日常开发任务加载整套迁移上下文吗？

迁移从 /hmbot 入口开始，插件为迁移角色提供默认权限边界，参考资料按需读取。用户可以通过宿主配置覆盖这些默认设置。

反馈与许可

欢迎通过 GitCode Issues 提交可复现的问题、迁移差异或改进建议。提供包版本、宿主版本、目标 SDK/API、源行为、实际结果和必要日志片段，有助于定位问题；提交前请移除账号凭据和业务敏感数据。

本套件使用 MIT License。workflow 引擎基于 pi-dynamic-workflows 演进，原作者署名与许可随发行包保留。