AGENTS.md

OpenHarmony DevLoop(简称 DevLoop)是面向 OpenHarmony 的 Agent 驱动设备开发与验证闭环:本机(Windows,主 Agent,驱动方,持有 rk3568 开发板)⇄ 服务器(code-worker:opencode 重模型 + OHOS 大仓 + 编译工具链,代码与构建同机)。RUNBOOK.md 是权威手册,动任何东西前先读它;本文件只做地图与铁律索引。

工具脚本全部为 Python(Windows Python 3.10+,无需 Git Bash;ssh/scp 用系统 OpenSSH 或 Git for Windows 自带均可)。

仓库地图

文件 角色
RUNBOOK.md 权威手册:协作协议、标准迭代、踩坑记录、组织迁移(personal→org 纯 transfer 手工配方)
ROADMAP.md 演进路标:北极星(任务输入→Agent Loop→交付)/ 里程碑 M1-M3 状态与验收判据
README.md 项目介绍 + 新开发者环境安装指导(人看的入口)
ohos_devloop/scripts/check_env.py 环境诊断:clone 后第一件事,逐项 PASS/WARN/FAIL
ohos_devloop/ohos_cli.py + pyproject.toml 统一 CLI 入口(M6,CLI 即契约):ohos-devloop apply/collab/flash/server/init/check-env/... 子命令映射既有脚本(MAP 共 13 条,release 为第 13 条;双入口等价);pipx install --editable <仓路径> 即装,ohos-devloop version 包版本优先/git describe 兜底
ohos_devloop/scripts/wsroot.py 工作区解析层(M6,双模):$OHOS_WS → cwd 向上找 marker → 仓形(包形+仓根签名并存,site-packages 不认)→ 兜底:源码仓态回落仓根、安装态回落 None → require_ws() 引导 ohos-devloop init;用户数据只落工作区(inventory/tasks/runs/pool 归工作区、绝不写包目录/site-packages)、包资产归正本仓;注册表深合并(工作区覆写包缺省)
ohos_devloop/scripts/ws_init.py ohos-devloop init 底层:生成用户工作区(marker + inventory 占位模板 + 用户版 AGENTS.md + QUICKSTART)+ 技能展开到 ~/.agents/skills/(用户级,D-01 例外;--no-skills 可关);模板正本在 ohos_devloop/config/templates/
ohos_devloop/scripts/collab.py 远端 code-worker 任务契约生命周期:new/push/run(异步)/status/log/fetch/artifacts/close(close 自动释放工作区 + 汇编报告 draft)/stats(收敛遥测)
ohos_devloop/scripts/agent-run-v3.sh 服务器 worker 入口(改码纪律正本,部署到服务器 ~/collab/bin/;改后用 server_init.py 重部署)
ohos_devloop/scripts/server_init.py 服务器部署与验收(M6):体检(单次 SSH 只读探测)→ 部署 worker(md5 回验 + VERSION 戳)→ smoke 验收;--check 只读、--server 选 inventory 条目
ohos_devloop/scripts/report_draft.py 交付报告 draft 自动汇编(task.md + status.json + runs 档案 → report-draft.md;模板在 ohos_devloop/config/report-templates/)
ohos_devloop/scripts/ui_probe.py UI 树证据层(M4):dumpLayout 采集 + 黑名单标准化(raw→~10KB 标准形)+ 选择器查询/断言 + 选择器点击;库+CLI 双形态,apply.py 只薄布线(node 断言/ui_click 步骤)
ohos_devloop/scripts/diffcov.py TDD 差分覆盖率证据层:gcovr JSON × git diff 新增行 → 覆盖/未覆盖清单与行级阈值判据(分支方向级仅参考);库+CLI 双形态,apply.py 只薄布线(tdd_host coverage 模式 / diffcov 步骤)
ohos_devloop/scripts/release_audit.py 制品审计门(REL-02):twine check --strict + wheel 允许清单对账 + 敏感值黑名单扫描 + 旧命名空间 URL 断言 + METADATA 断言,五步 fail-closed(ohos-devloop release-audit <wheel>;安装态报「需源码仓检出态」);细节见 RUNBOOK「发布前审计门」
ohos_devloop/scripts/release.py 维护者发布流水线(Phase 5,ohos-devloop release 四形式 = 裸预检/test 演练/all 双源发布/resume 恢复):归档一次全程同一 wheel(runs/release-<version>/artifact 正本)、A1/A2 决策门、approval 消费、D-20 公开历史门(scan_public_history 当前树+全 refs 值驱动扫描 / verify_public_readiness 实时对账);凭据只经 TWINE_*/GITCODE_TOKEN env
ohos_devloop/scripts/release_metadata.py + release_smoke.py 发布配套层:release_metadata 校验 CHANGELOG/pyproject 契约与匿名资产链接(A1 判据);release_smoke 给定归档 wheel 的真实 venv strict smoke(发布环境缺项 FAIL 非 skip)——均被 release.py 复用
packaging/audit-blacklist.yaml 审计黑名单数据源(七键固定串 + generic 密钥正则 + 三键例外表)——仓根维护者资产,绝不进 wheel(进包即自指恒红 + 真实值二次分发);wheel 审计与公开历史扫描共用同一数据源
packaging/public-readiness-schema.json 公开历史证明形态正本(D-20,tracked):16 必填键的布尔/时间/SHA/digest 形态与 release_inventory_supplied 供给状态——不含任何 HEAD/tag 实值;证明实例只写 runs/release-<version>/public-readiness.json
ohos_devloop/scripts/apply.py 薄调度器(Python3 + PyYAML):verify/e2e-hap/tdd-host/tdd-board 等 job spec 的 plan/run;步骤类型含推板保护链、hap e2e 链、assert 判定、TDD 双通道
ohos_devloop/scripts/mount_ws.py W: SSHFS 挂载/卸载(应急人工通道,2026-11-09 降级,非改码路径)
ohos_devloop/scripts/sgrep.py 服务器端递归搜索:python ohos_devloop/scripts/sgrep.py <pattern> [path](主 Agent 定点搜索备用)
ohos_devloop/scripts/flash.py 固件准备:fetch(CI 每日构建下载)/ extract / list / sync-repo / pool(工作区池占用登记,一任务一工作区,映射在本机 workspace_pool.yaml 不上库;换固件先 extract 再 sync-repo)
ohos_devloop/scripts/sign_hap.py 测试应用离线签名(hap_sign 步骤底层调用;`--mode debug
ohos_devloop/scripts/verify_frame_diff.py 取证帧差异比对(前后两帧截图的像素级 diff 取证)
ohos_devloop/scripts/telemetry.py + devloop_telemetry/telemetry_server.py + devloop_telemetry/telemetry_report.py 遥测层(M6,opt-in 默认关):客户端埋点出口 telemetry.py 留 core;collector/周报服务端归 devloop_telemetry 仓(终态),beta: 121.43.52.4:8080;只收形状不收内容,协议与运维见 RUNBOOK「遥测」;协议正本见该仓 PROTOCOL.md
devloop_telemetry/telemetry_web.py + telemetry_dashboard.py 遥测看板(5001):Flask 登录版(密码 PBKDF2+CSRF+限速+session 7 天,token 直达双通道)+ stdlib 渲染层单一来源(dashboard 亦为 venv 故障应急 fallback);服务器 venv + systemd 单元 ohos-telemetry-dashboard
ohos_devloop/config/inventory.yaml 服务器/板卡/模拟器/本机参数唯一事实来源;扩容 = 加条目,不改代码(--params board=<条目> 同 spec 换板)
ohos_devloop/config/verify.yaml 缺省 job spec:build → detect-changed → fetch → push → capture 取证
ohos_devloop/config/e2e-hap.yaml / e2e-cases.yaml hap 应用 e2e 全链 job + 用例注册表(bundle/ability 自动派生;新用例 = 加条目)
ohos_devloop/config/tdd-host.yaml / tdd-board.yaml / tdd-suites.yaml TDD 双通道 job + 套件注册表(别名如 ph-list → target+filter+钉数;新套件 = 加条目)
ohos_devloop/config/tdd-emulator.yaml 大循环(模拟器通道):x86_64_virt 设备版 TDD 推服务器 QEMU 模拟器直跑(板端门前快速预验;配方见 RUNBOOK「x86 模拟器大循环」)
ohos_devloop/config/tdd-coverage.yaml 小循环差分覆盖率 job(tdd_host coverage 模式常开包装:插桩构建 → 套件 → gcovr → 新增行差分判据;worker 改码分支覆盖可见性)
ohos_devloop/config/task-template.md 任务契约模板(collab.py new 的底稿;头字段含 build_targets/tdd_targets)
ohos_devloop/examples/smoke.yaml / assert-smoke.yaml 调度器自测 / assert 判定自测(均不碰构建/板子);ohos_devloop/examples/e2e-emu-smoke.yaml = 模拟器 e2e 证据链自测(预装应用启动→断言;模拟器 hap install 已由 code_sign 降级修复打通 2026-11-17,坑位与部署配方见 RUNBOOK 坑位 7/8)
~/.agents/skills//SKILL.md 可复用 agent skill(用户级副本,本机发现用;正本在 ohos_devloop/agents/skills/,随包分发);现有 collab-delegate:改码前强制判定与任务派发;pool-status:工作区池实时对账;loop-iterate:标准迭代 Agent Loop 驱动
tasks// 任务留档(本机留档,不进 git):task.md/context(上推)/ report/status/artifacts(回收)
runs// 调度器执行档案(本机留档,不进 git):results.json(每步落盘可轮询)+ build.log + fetch/ + backup/ + evidence/

协作模式(一句话)

本机主 Agent 驱动设备侧执行;代码定位/修改经 ~/.agents/skills/collab-delegate 判定后组任务契约(collab.py)交服务器 code-worker(重模型 opencode,直接读写大仓 + git commit + 触发构建,禁 push);本机负责取证/推板/板端 TDD/判定/PR 操作;纯执行(构建/推板/校时/取证)走 apply.py 直连 SSH/hdc。W: SSHFS 为应急人工通道,不是改码路径。

调度器速查

python ohos_devloop/scripts/apply.py config/verify.yaml plan                                  # 离线看计划
python ohos_devloop/scripts/apply.py config/verify.yaml run                                   # 全流程(长任务后台跑 + 轮询 runs/<id>/results.json)
python ohos_devloop/scripts/apply.py config/verify.yaml run --from-step push --run-id <id>    # 断点续跑
python ohos_devloop/scripts/apply.py config/verify.yaml run --params artifacts=<清单txt>      # 跳过构建直接推产物
python ohos_devloop/scripts/apply.py config/e2e-hap.yaml run --params case=grid-ph marker=<埋点>   # hap 应用 e2e 全链(构建→签名→装板→启动→取证→判定)
python ohos_devloop/scripts/apply.py config/tdd-host.yaml run --params tdd_targets=<targets>  # 小循环:host TDD 快反馈
python ohos_devloop/scripts/apply.py config/tdd-board.yaml run --params tdd_targets=<targets> # 大循环:板端 TDD 门(铁律 8)
python ohos_devloop/scripts/apply.py config/tdd-emulator.yaml run --params tdd_targets=<targets> # 大循环模拟器通道(先起隧道;RUNBOOK「x86 模拟器大循环」)
python ohos_devloop/scripts/apply.py config/tdd-coverage.yaml run --params tdd_targets=<别名> ohos_root=<WS> [diff_base=<sha>]  # 差分覆盖率:worker 改码新增分支是否被用例踏到
python ohos_devloop/scripts/apply.py examples/smoke.yaml run                                  # 自测/新环境连通性验证
python ohos_devloop/scripts/apply.py examples/assert-smoke.yaml run                           # assert 判定自测(纯本地)
python ohos_devloop/scripts/apply.py examples/diffcov-smoke.yaml run                         # 差分覆盖判定自测(纯本地)
python ohos_devloop/scripts/server_init.py [--check|--no-smoke|--server <名>]                 # 服务器体检/worker 部署/smoke 验收(新服务器 onboarding 与重部署)
python ohos_devloop/scripts/release_audit.py <wheel>                                            # 发布前审计门:任何上传前必跑(twine --strict + 清单对账 + 黑名单扫描,fail-closed)
python ohos_devloop/scripts/release.py            # 裸预检:构建/归档→审计→strict smoke→只读双面预检,打印后停止(零上传)
python ohos_devloop/scripts/release.py test       # TestPyPI 演练(同一归档 wheel;A1 写入门 + 占用/凭据前门)
python ohos_devloop/scripts/release.py all --yes  # 正式双源发布(A1/A2 门→审批→确认→公开 PyPI verified→GitCode Release→脱敏回执)
python ohos_devloop/scripts/release.py resume --yes  # 崩溃恢复(只从归档+state;先远端对账,404/缺失才重试)——四形式与 `ohos-devloop release ...` 等价

铁律(细节见 RUNBOOK 对应节,违反出过事故)

  1. 推库先备份:板上目标文件(.so 和 .abc 都算)推送前必须备份;push 步骤已固化,手工操作自行备份到 D:\rk3568\board_backup\<版本>\。
  2. 不混基线:板上 const.product.software.version 必须与构建基线一致(换固件后先 python ohos_devloop/scripts/flash.py extract 再 sync-repo);const.product.name 会谎报,不要信。
  3. hdc 退出码不可信(失败常返回 0):以产物校验为准(md5/文件存在)。本仓脚本用 list 参数起子进程,天然免疫 Git Bash 引号/路径转换问题;手工在 Git Bash 调 hdc 仍需 export MSYS_NO_PATHCONV=1 且本地路径用 cygpath -w。
  4. 板上无 RTC:重启后时钟回 2017(或漂移),需 date -s @<epoch> 校时;推库后重启验证系统健康;时钟漂移会导致 profile validity 判定失败(装 hap 报 grant request permissions failed)。
  5. ArkUI 部署面两层:动态库层 + 组件 abc 层(/system/etc/abc/arkui/components/);只推 .so 不推 abc,新属性在应用侧是 undefined。
  6. 板载 toybox 缺 tr/awk,板端 grep 大文件不可靠:md5 对字节才可信。
  7. 改码单一通道 = 远端 code-worker(2026-11-09 起):一切代码修改(含 ≤2 文件微修补)组任务契约经 collab.py 派发,worker 落笔(分支/commit 纪律内联在 agent-run-v3.sh);worker 禁一切 git push,推 fork 是设备验证通过后主 Agent 的独立步骤;W: 挂载(rw)仅应急人工浏览,不做裸改。worker 执行的命令不得引用项目外路径(opencode external_directory 自动拒绝即终止)。
  8. 改码/改 TDD 必过板端 TDD 门(2026-11-06 起):凡新增/修改代码或 TDD 用例,受影响套件必须推开发板直跑全过(宿主机跑绿不豁免)——产物取 stripped 版、md5 校验、--gtest_output 给可写绝对路径;配方与判据见 RUNBOOK「TDD 板端验证」节。

演进约定

  • 当前形态:单人单桌面 + 单服务器 + 单板。多服务器/多板时在 ohos_devloop/config/inventory.yaml 加条目,新机器先过 ohos_devloop/examples/smoke.yaml 连通性验证。
  • 框架升级触发器(不到不换):板卡需远程电源控制 → labgrid;多用户共享板池 → LAVA;多构建机统一调度 → Buildkite。
  • 改脚本行为须同步 RUNBOOK 对应节;本文件保持地图定位,不堆细节。