OpenHarmony DevLoop

面向 OpenHarmony 的 Agent 驱动设备开发与验证闭环。

从任务到真机验证,自动闭环。

DevLoop 把「改 OpenHarmony 代码 → 编译 → 推开发板 → 取证判定」串成一条 Agent 可驱动的闭环:你在 Windows 本机用 USB 直连开发板(rk3568 等),代码定位与编译交给你自己的 Linux 构建服务器,本机负责推板、取证与结果判定。CLI 是唯一契约——任何能执行命令行的 Coding Agent(Claude、Codex、opencode……)都能担任主 Agent,不依赖特定客户端的私有 API。

它怎么工作

OpenHarmony DevLoop 整体架构

  • 改码走任务契约:ohos-devloop collab 把任务(task.md + 证据 context)上推给构建服务器上的 code-worker——一个与大仓、构建工具链同机的重模型 Agent,负责定位、修改、fix/* 分支提交并触发构建;report 与产物清单自动回收。worker 只在本地分支提交,不 push。
  • 验证走本机:ohos-devloop apply 流水线取回构建产物、推板、截图/hilog 取证;TDD 双通道(宿主机快反馈 + 板端强制门)守住每次改码。
  • 固件与基线对齐:ohos-devloop flash 解包固件、按镜像 manifest 把服务器大仓同步到同一提交点——板上系统与大仓代码不混基线。

一轮迭代的完整旅程(init → check-env → 服务器部署 → 任务契约 → 验证链)由 ohos-devloop init 生成的 QUICKSTART.md 承载,跟着走即可。协作协议细节、踩坑实录与操作铁律在 RUNBOOK.md(维护者手册),面向 Agent 的仓库地图在 AGENTS.md。

安装

前置组件

组件 版本要求 用途 验证
Windows 10+ 本机环境(板卡宿主、工具运行处) —
Python ≥ 3.10 CLI 与全部工具脚本 python --version
pipx 最新 隔离安装 ohos-devloop pipx --version
OpenSSH 客户端 — 连构建服务器(Windows 系统内置) ssh -V
DevEco Studio ≥ 6.0 OpenHarmony SDK / hdc / 签名材料 —
开发板 rk3568 等 USB 直连本机 hdc list targets
构建服务器 自备 Linux OpenHarmony 大仓 + 构建工具链;code-worker 由工具部署 ssh 免密可达
Node.js + deveco-cli ≥ 22 可选:测试应用构建/装板 devecocli --version

安装步骤

# 1. 安装工具(独立 venv,PATH 出现 ohos-devloop 命令)
pipx install ohos-devloop
ohos-devloop version                  # 应输出包版本

# 2. 生成你的工作区(用户数据都归这里,不进安装目录)
ohos-devloop init <目录>
#    编辑 <目录>/config/inventory.yaml:构建服务器 ssh 参数、板卡序列号与基线版本、本机 hdc 路径

# 3. 环境自证:逐项 PASS/WARN/FAIL,FAIL 清零再继续
ohos-devloop check-env

# 4. 部署构建服务器侧 code-worker(体检 → 部署(md5 回验)→ smoke 验收)
ohos-devloop server init

agent 技能随 init 展开到用户级 ~/.agents/skills/(Coding Agent 框架天然发现;--no-skills 可关)。

升级

pipx upgrade ohos-devloop
# 本地 wheel 安装的形态:pipx install <新 wheel 路径> --force
  • 数据不变式:升级只换工具本体。工作区(inventory / tasks / runs / 工作区池登记)原样保留,不需要迁移,也不会被覆写。
  • 工作区兼容承诺:工作区 marker(ohos-workspace.yaml)带 schema_version 戳——旧工作区缺戳按 v1 兼容读,绝不拒绝;戳高于当前工具版本只告警、不阻断。跨大版本升级可放心先升后看。

数据位置

数据 位置 说明
工作区 你 init 的目录 config/inventory.yaml(你的机器参数)、tasks/(任务留档)、runs/(执行档案与取证)、workspace_pool.yaml(大仓工作区池登记)——卸载/升级都不碰这里
agent 技能副本 ~/.agents/skills/ init 从包内展开(collab-delegate / loop-iterate / openharmony-ci / pool-status);正本在包里,已改过的副本不会被覆盖
遥测 ~/.ohos-devloop/telemetry/ opt-in,默认关;开启后只收事件形状不收内容(协议见 RUNBOOK「遥测」)

安装目录(pipx venv)里只有工具本体,没有你的数据——出问题时删掉重装即可,工作区无损。

排障

第一条命令永远是环境自证:

ohos-devloop check-env          # 逐项 PASS/WARN/FAIL,按提示修 FAIL;--offline 只查本机

常见的新用户坑(均有记录与解法,见 RUNBOOK.md「常见问题」与各节坑位实录):

  • 装测试应用报 grant request permissions failed:板上无 RTC,重启后时钟回退导致 profile 判定失败——先校时再装(RUNBOOK)。
  • 板上行为与预期不符:先核对板上系统版本与构建基线是否一致(不混基线;flash extract + sync-repo 对齐)。
  • hdc 手工操作退出码不可信:以产物校验(md5/文件存在)为准——工具脚本已内置,手工操作注意(RUNBOOK)。

深入问题(协作协议、服务器部署配方、TDD 板端门、模拟器大循环等)全部在 RUNBOOK.md。离线/内网环境可用本地 wheel 安装:pipx install <wheel 路径>。

许可证

Apache-2.0