Project
ohos-devloop 分发机制(Packaging & Distribution)
为 OpenHarmony DevLoop 建立独立于源码仓的打包 → 分发流程:把客户端工具(CLI + scripts + 配置模板 + examples + skills)与编译服务器部署件打成可安装的 wheel 包,通过内部 PyPI 与开源 PyPI 双源发布,让 ArkUI 开发团队(beta 10 人 → 200 人)不 clone 源码仓、pipx install 即用,客户端与服务器部署一次装好并通过 smoke 验收。
Core Value: 一名新的 ArkUI 同学在一台干净 Windows 机器上 pipx install ohos-devloop,随后用包内命令完成工作区初始化与编译服务器 worker 部署,examples/smoke.yaml 全绿——全程不接触源码仓。
Constraints
- Tech stack: Python 3.10+ / setuptools >= 64 / pipx;不引入打包框架迁移(保持 setuptools + data-files 路线) — 与 pyproject 既有决策一致,改造成本最低
- Architecture: scripts/*.py 不做包内导入改造(扁平互 import 保留,子进程按路径调用) — pyproject 既有注释决策;打包走 data-files 而非代码重构
- Compatibility: 工作区数据格式跨版本兼容(已生成的工作区不因升级失效) — 10→200 人的升级体验底线
- Security: 包内容公网可见标准(开源 PyPI 同步发) — 包内不得有内网 IP/端口/token/个人路径;这是硬边界不是建议
- Workflow: 随迭代发、版本单调递增 — beta 期间快速迭代节奏,版本号既有「包版本优先/git describe 兜底」策略沿用
Technology Stack
Languages
- Python 3.10+ - All local tooling:
scripts/*.py(scheduler, CLI, flash, collab, telemetry, ui_probe, diffcov, signing),devloop_telemetry/*.py(telemetry collector/dashboard/report,独立仓),ohos_cli.pyentry. Type hints (from __future__ import annotations) used consistently. - Bash -
scripts/agent-run-v3.sh(server-side code-worker entry, deployed to~/collab/bin/); remote one-liners invoked via ssh from Python - YAML - Job specs (
config/*.yaml), resource registry (config/inventory.yaml), case/suite registries,examples/*.yaml - Markdown - Templates:
config/task-template.md,config/report-templates/,config/templates/(workspace scaffolding) - ArkTS/ArkUI - External test apps referenced by
config/e2e-cases.yaml(projects likeC:/Project/grid_ph_verify), built headlessly via deveco-cli, not in this repo
Runtime
- Python 3.10+ (Windows, local host) - enforced by
pyproject.tomlrequires-pythonandscripts/check_env.py - Node.js >= 22 - deveco-cli runtime (checked in
scripts/check_env.py) - DevEco Studio >= 6.0 - provides OpenHarmony SDK + toolchains (hdc, hap-sign-tool, jbr java/keytool) at
C:/Program Files/Huawei/DevEco Studio(overrideDEVECO_CLI_STUDIO_PATH) - Linux build server (root@1.92.115.202:41641) - OHOS 大仓 workspaces under
/srv/workspace/openharmony_master_default_*/code, opencode at/root/.local/bin/opencode, custom-built QEMU 10.0.2 at/root/qemu-10.0.2/build/ - Dev board: rk3568 running OpenHarmony
7.1.0.25(perconfig/inventory.yamlboardsoftware_version); x86_64_virt QEMU emulator instance as second "board" resource - pipx (editable install of this repo ->
ohos-devloopCLI) + pip for PyYAML/Pillow/Flask; npm global for@deveco/deveco-cli;pip3 install gcovr(v8.8, server side, seeconfig/tdd-coverage.yaml) - Lockfile: none (pyproject.toml declares loose minimums;
ohos_cowork.egg-info/andohos_devloop.egg-info/present in repo root, gitignored)
Frameworks
- None - scripts are stdlib-first (argparse, subprocess, pathlib, http.server, urllib)
- unittest (stdlib) -
tests/test_rebrand.py; gtest (OpenHarmony TDD targets) driven remotely viaconfig/tdd-suites.yaml - gcovr (server) - coverage JSON for diffcov,
config/tdd-coverage.yaml - setuptools >= 64 (build backend,
pyproject.toml) - Flask + werkzeug - telemetry dashboard
devloop_telemetry/telemetry_web.py(installed in server venv~/telemetry/venv, NOT declared in pyproject dependencies - intentional, dashboard is a separate deployment) - PyYAML >= 6 - all config/job-spec parsing
- Pillow >= 9 -
frame_diffassertion (screenshot pixel diff); missing degrades only that assertion kind - ThreadingHTTPServer (stdlib) - telemetry collector
devloop_telemetry/telemetry_server.pyand dashboard fallbackdevloop_telemetry/telemetry_dashboard.py
Key Dependencies
- PyYAML -
config/inventory.yamlis the single source of truth for all resources (scripts/wsroot.py,scripts/apply.py,scripts/flash.py,scripts/collab.py) - ssh/scp (system OpenSSH or Git for Windows) - the only channel to the build server; every script spawns them as subprocesses with
listargs (Git Bash quote/path-conversion immune) - hdc (OpenHarmony Device Connector,
C:/Program Files/oh_toolchain/toolchains/hdc.exeperconfig/inventory.yamllocal.hdc) - all board operations (shell, file send/recv, install); exit codes unreliable, scripts verify by artifact checksum (铁律 3) - curl - firmware resume download in
scripts/flash.pydo_fetch - opencode CLI - the server-side code-worker model runner (
scripts/agent-run-v3.sh, default modelbigmodel/glm-5.3) - repo (Google git-repo) - server-side OHOS 大仓 sync to image baseline (
scripts/flash.pysync-repo) - deveco-cli (
@deveco/deveco-clinpm global) - headless hap build/install of test apps (step_hap_buildinscripts/apply.py) - hap-sign-tool + OpenHarmony.p12 + profile templates - offline hap signing (
scripts/sign_hap.py; materials underD:/rk3568/signing) - SSHFS-Win + WinFsp - optional W: emergency mount (
scripts/mount_ws.py, not a code-change path) - QEMU 10.0.2 (custom source build,
tcgprofile withcpu=Skylake-Client+ 8GB RAM) - x86_64_virt emulator for big-loop pre-validation (config/tdd-emulator.yaml)
Configuration
config/inventory.yaml- unique fact source:servers(host/port/user/ohos_root_glob/run_dir/cores),boards(product/transport/hdc_target/software_version/build_layout/device_root/remount_cmd/backup_dir/tdd_lib_path),emulators,local(hdc/download_dir/images_dir). Editing this file is the scaling path (add entries, no code change)- Job specs:
config/verify.yaml,config/e2e-hap.yaml,config/tdd-host.yaml,config/tdd-board.yaml,config/tdd-emulator.yaml,config/tdd-coverage.yaml; self-tests inexamples/(smoke, assert-smoke, diffcov-smoke, e2e-emu-smoke) - Registries (extend-by-adding-entries):
config/e2e-cases.yaml,config/tdd-suites.yaml workspace_pool.yaml- local state (gitignored), task<->workspace mapping, maintained byflash.py pool/collab.py close- Env vars (all optional overrides):
OHOS_WS,COLLAB_SERVER,COLLAB_PORT,RK3568_DOWNLOAD_DIR,RK3568_IMAGES_DIR,RK3568_OHOS_ROOT,RK3568_SYNC_SERVER,RK3568_SYNC_PORT,DEVECO_CLI_STUDIO_PATH,SIGN_DIR,KS_PASS,HDC,UI_PROBE_HDC,DEVLOOP_TELEMETRY_TOKEN,AGENT_TIMEOUT(worker),OHOS_WS - Telemetry opt-in config:
~/.ohos-devloop/telemetry/config.json(enabled/user/endpoint/token), default off - Workspace scaffolding via
ohos-devloop init(scripts/ws_init.py):ohos-workspace.yamlmarker + inventory template + user AGENTS.md + QUICKSTART pyproject.toml- package metadata,[project.scripts] ohos-devloop = "ohos_cli:main",py-modules = ["ohos_cli"](scripts stay flat-import, invoked as subprocesses by path)- No tsconfig/npm config - JS only appears as deveco-cli runtime
Platform Requirements
- Windows host: Python >= 3.10, Node.js >= 22, Git, OpenSSH client, DevEco Studio >= 6.0 (OpenHarmony SDK + hdc), rk3568 board over USB; SSHFS-Win optional (README.md "环境安装" section; full diagnostics in
scripts/check_env.py) - Server onboarding:
python scripts/server_init.py(single-SSH-readonly probe -> scp worker with md5 verification -> smoke acceptance) - Linux build server (OHOS 大仓 + build toolchain + opencode worker + QEMU emulator), rk3568 dev board, ECS telemetry collector/dashboard (beta
ecs-user@121.43.52.4, systemd unitohos-telemetry-dashboard)
Conventions
Naming Patterns
- Python scripts:
snake_casewith purpose-descriptive name (check_env.py,ws_init.py,verify_frame_diff.py). Long descriptive names preferred over abbreviations. - Shell:
agent-run-v3.sh(versioned suffix pattern for deployed worker entry). - YAML job specs:
kebab-case(tdd-host.yaml,tdd-coverage.yaml,e2e-hap.yaml); smoke/self-test specs underexamples/(assert-smoke.yaml,diffcov-smoke.yaml). - Directories:
scripts/,config/,examples/,tests/— flat, purpose-named. snake_casethroughout (dump_layout,resolve_and_click,write_results,check_job).- Step handlers in
scripts/apply.pyfollowstep_<type>naming, mirroring the YAMLtype:key:step_build↔type: build,step_tdd_host↔type: tdd_host(scripts/apply.py:1203STEPSdict). - Private helpers prefixed
_:_parse_gtest,_locate_binary,_cov_setup,_deep_merge,_unmsys,_gtest_filter_arg(scripts/apply.py,scripts/wsroot.py,scripts/diffcov.py). - Returns:
main()always returnsintexit code; step handlers returntuple[str, dict]=(status, detail)with status ∈ok | skip | warn | fail. snake_case; short locals (rc, out, errfromsh()); context dict namedctxthroughoutscripts/apply.py; run directory variable consistentlyrun_dir.PascalCaseclasses (Server,Board,Tmpl,Handler) — seescripts/apply.py:115,devloop_telemetry/telemetry_server.py:33.- Custom exceptions suffixed
Error(ApplyErrorinscripts/apply.py:71);RuntimeError/ValueError/SystemExitused in library modules (scripts/ui_probe.py,scripts/diffcov.py). - Modern type-hint syntax with
from __future__ import annotationsin newer modules (scripts/apply.py,scripts/wsroot.py,scripts/ui_probe.py,scripts/diffcov.py); PEP 604 union syntaxPath | None,tuple[int, ...] | Noneused throughout. Older scripts (scripts/flash.py,scripts/check_env.py) omit hints — new code should use hints. - UPPER_SNAKE module-level:
BASE,STAGE,TID_RE,MAX_BODY,ESSENTIAL,MIN_FREE,DAILY_API,NOISE_RE,SOURCE_EXT(scripts/flash.py,scripts/collab.py,devloop_telemetry/telemetry_server.py,scripts/diffcov.py).
Code Style
- No formatter configured (no black/ruff/isort/line-length config anywhere;
pyproject.tomldeclares only setuptools build + deps). Adopt the observed house style: - LF line endings enforced by
.gitattributes(*.py text eol=lf,*.sh text eol=lf,*.yaml text eol=lf). - No linter configured. Effective static checks used instead:
bash -nfor the worker script during deploy (scripts/server_init.py:209),check_env.pyruntime diagnostics, and smoke specs as runtime self-tests. - Test file uses
# noqa: E402comments (tests/test_rebrand.py:21-24) — keep that pattern when importing sibling modules after sys.path manipulation.
#!/usr/bin/env python3
- The stdout/stderr UTF-8 reconfigure block appears in every entry script (
scripts/apply.py:1410,scripts/check_env.py:263,scripts/collab.py:286,scripts/server_init.py:284) — Windows Chinese output correctness. Never drop it. main() -> int+sys.exit(main()); exit codes:0ok,1fail,2usage/error.- Module docstrings are mandatory and content-rich: usage lines, design rationale, dates of changes, and "坑位" (pitfall) references to
RUNBOOK.mdsections. Seescripts/apply.py:3-18,scripts/mount_ws.py:3-25.
Import Organization
- None. Scripts resolve the repo root as
Path(__file__).resolve().parent.parent(BASE,PKG,REPOconstants). Workspace/user data resolves throughwsroot.ws_root()(scripts/wsroot.py:36); package assets throughwsroot.PKG. ohos_cli.pyinvokes scripts as subprocesses withsys.executable(ohos_cli.py:110) — dual-entry equivalence, not imports.- Local commands ALWAYS go through a
sh(args: list[str], ...) -> tuple[int, str, str]helper taking a list (never a shell string):scripts/apply.py:87,scripts/collab.py:46,scripts/ui_probe.py:53,scripts/check_env.py:35(run). Comment in all: "list 参数起子进程(不做 shell 字符串拼接,绕开 Git Bash 引号/路径转换问题)". sh()mapsTimeoutExpired→(124, "", ...)andFileNotFoundError→(127, "", ...).- Remote server/board commands ARE strings (they execute in remote bash), but every remote path/argument must be wrapped in
shlex.quote(...)(scripts/apply.py:170,scripts/flash.py:425). - MSYS path mangling of
/srv/...at the bash→python argument boundary is reverted by_unmsys()/unmangle()(scripts/apply.py:235,scripts/flash.py:52).
Error Handling
- Expected failures → custom
ApplyErrorwith a Chinese message that is directly actionable: includes the fix command, expected vs actual, and file paths. E.g.scripts/apply.py:443:f"md5 不一致(hdc 退出码不可信的典型场景): {rel} local={local_md5} device={dev_md5}". ApplyErroris caught once at the top: step loop turns it intostatus="fail"with{"error": str(e)}inresults.json(scripts/apply.py:1349-1350);main()printsERROR: {e}to stderr and returns 2 (scripts/apply.py:1436-1438).- Standalone scripts use
die(msg):print(f"ERROR: {msg}", file=sys.stderr)+sys.exit(2)(scripts/flash.py:47,scripts/sign_hap.py:42);scripts/collab.py:41variant returns2so callers canreturn die(...). - Non-critical paths swallow exceptions with
except Exception: pass+ a justifying comment: telemetryemit"永不抛异常——遥测故障不得影响主流程" (scripts/telemetry.py:109-122), stdout reconfigure,tool_version()probes (ohos_cli.py:44-60). - Guard-clause style: validate early, fail fast —
if not local.exists(): raise ApplyError(...)before any side effect. - Remote/hdc output reliability: never trust exit codes from
hdc— verify by artifact presence/md5/content (scripts/apply.py:176-193Board.recv/send docstrings; RUNBOOK 铁律 3). ssh/scp verified via md5 echo-back (scripts/server_init.py:201-207).
Logging
scripts/apply.py:79log(msg, run_dir)— prints[HH:MM:SS] msgwithflush=Trueand appends the same line toruns/<id>/apply.log. All step lifecycle uses it.- Machine-readable record is
runs/<id>/results.json, written after every step (write_results,scripts/apply.py:1279) withensure_ascii=False, indent=2— this is the pollable contract for agents. - Errors to
sys.stderrviaprint(..., file=sys.stderr); user-facing status to stdout. - Telemetry:
telemetry.emit("step_done", ...)— opt-in, never raises, only shapes not content (scripts/telemetry.py).
Comments
- Chinese comments are the norm; comments explain WHY and trap knowledge, not WHAT.
- Pitfall comments ("坑位") are a first-class artifact: dated, referencing RUNBOOK sections or measured facts, e.g.
scripts/apply.py:326-328(nohup detach pitfall),scripts/ui_probe.py:91-93(hdc recv path pitfall),scripts/flash.py:52(MSYS mangle). - Section banners in long modules:
# --------------------------------------------------------------------------- 资源(scripts/apply.py:113),# ---- helpers ----(devloop_telemetry/telemetry_server.py:40). - YAML specs carry
# ====banner headers explaining purpose and usage (config/verify.yaml:1-8). - Python docstrings serve this role: first paragraph = one-line purpose; then usage (CLI lines), then conventions/pitfalls/design. Examples:
scripts/collab.py:3-21,scripts/telemetry.py:3-19,scripts/flash.py:3-20.
Function Design
Module Design
Git & Change Conventions
- Conventional commits, Chinese description:
feat:,fix:,docs:,refactor:,init:(seegit log; e.g.feat: M6 收尾——遥测层 + rebrand 回归测试 + README 精简重写). - Worker-side (server code-worker,
scripts/agent-run-v3.sh:78-85): branchfix/<短描述>based on current HEAD; stage only explicitly modified files (nevergit add -A); commit message must carrySigned-off-by:,AI[100%] ... AI Adopted[100%],Co-authored-by:, andChange-Id: I<40hex>; no git push ever — pushing fork is the local agent's step after device verification. - Tasks archived under
tasks/<tid>/(not in git); run archives underruns/<id>/(not in git);workspace_pool.yamlgitignored. - Doc discipline: changing script behavior requires syncing the matching
RUNBOOK.mdsection (AGENTS.md rule);AGENTS.mdstays map-level, no detail.
Security Conventions
- No secrets in the repo: telemetry token lives in
~/.ohos-devloop/telemetry/config.jsonorDEVLOOP_TELEMETRY_TOKENenv (scripts/telemetry.py:175-178); signing keystore password viaKS_PASSenv with a default only for the public SDK sample keystore (scripts/sign_hap.py:35). - Shell-injection defense:
TID_REwhitelist for task-ids before any path use (scripts/collab.py:38,112);shlex.quoteon every remote argument; task-id interpolation into remote JSON viajson.dumps-style quoting inscripts/collab.py:197-206. - Server-side auth: PBKDF2 password hash + CSRF nonce + IP rate-limit + 7-day signed session; token direct-pass dual channel (
devloop_telemetry/telemetry_web.py); collector validates token with constant-ish length compare (devloop_telemetry/telemetry_server.py:49-53).
Architecture
System Overview
- Local machine (Windows) — the driver: holds the rk3568 dev board, runs the main Agent, performs evidence capture / board push / board-side TDD / judgment / PR operations.
- Build server (Linux) — the code worker: hosts the OpenHarmony mega-repo workspace and the build toolchain (code and build co-located), runs the
opencodeheavy model via a one-shot worker script, never pushes to git.
Component Responsibilities
| Component | Responsibility | File |
|---|---|---|
| Unified CLI | Maps subcommands to scripts as subprocesses; version contract; command telemetry | ohos_cli.py |
| Thin scheduler | Job spec (YAML) × inventory → plan/run; step registry dispatch; per-step results.json persistence |
scripts/apply.py |
| Workspace resolver | $OHOS_WS → marker up-search → repo-shape → package fallback; registry deep-merge (workspace overrides package defaults) |
scripts/wsroot.py |
| Task contract lifecycle | new/push/run/status/log/fetch/artifacts/close/stats for remote code-worker |
scripts/collab.py |
| Server worker entry | One-shot opencode run: reads task.md/context, fixes code on fix/* branch, builds, writes report.md/status.json/artifacts.txt |
scripts/agent-run-v3.sh |
| UI evidence layer | uitest dumpLayout capture + blacklist normalization + selector query/assert/click (library + CLI) |
scripts/ui_probe.py |
| Diff coverage layer | gcovr JSON × git diff new lines → covered/uncovered list + line-level hard gate |
scripts/diffcov.py |
| HAP signing | Offline debug/release signing of test apps (materials under D:/rk3568/signing) |
scripts/sign_hap.py |
| Report assembly | task.md + status.json + runs archives → report-draft.md |
scripts/report_draft.py |
| Firmware prep / workspace pool | CI daily-build fetch, extract, sync-repo baseline alignment, pool claim/release |
scripts/flash.py |
| Server deployment | Health probe → deploy worker (md5 verify) → smoke acceptance | scripts/server_init.py |
| Environment diagnostic | PASS/WARN/FAIL checklist for toolchain/server/board readiness | scripts/check_env.py |
| Workspace scaffold | ohos-devloop init — marker, inventory template, user AGENTS.md, QUICKSTART |
scripts/ws_init.py |
| Telemetry emitter | Opt-in anonymous usage stats; local JSONL queue; batch push; never throws | scripts/telemetry.py |
| Telemetry collector | stdlib HTTP server: POST /collect, /healthz, /stats |
devloop_telemetry/telemetry_server.py |
| Telemetry dashboard | Flask login + session auth, rendering core shared with stdlib fallback | devloop_telemetry/telemetry_web.py |
| Dashboard render core | stdlib-only aggregation/render (also emergency fallback) | devloop_telemetry/telemetry_dashboard.py |
| Weekly report | Aggregates collector JSONL → beta metrics | devloop_telemetry/telemetry_report.py |
| Emergency SSHFS channel | W: mount/unmount for manual browsing only (not the code path) |
scripts/mount_ws.py |
| Server grep | Read-only recursive search on the server (lightweight localization) | scripts/sgrep.py |
| Frame diff forensics | Pixel-level frame-difference flagging for transient defects | scripts/verify_frame_diff.py |
| Agent skills | Reusable procedures: delegation decision, loop iteration, pool status, PR CI | .agents/skills/*/SKILL.md |
Pattern Overview
- Declarative specs: behavior lives in
config/*.yamljob specs and registries; code only interprets them (scripts/apply.pySTEPSregistry atscripts/apply.py:1203). - Resource-first expansion: "add an entry, don't change code" — servers/boards/emulators in
config/inventory.yaml, TDD suites inconfig/tdd-suites.yaml, e2e cases inconfig/e2e-cases.yaml. - Dual entry, one contract:
ohos-devloop <cmd>andpython scripts/<script>.pyare behaviorally identical;ohos_cli.pyonly re-dispatches. - Evidence-driven judgment: every step writes structured detail into
runs/<run-id>/results.json; outcomes are PASS/FAIL derived from artifacts (md5, gtest counts, assertions), not exit codes. - Code modification is remote-only: the local Agent never edits server code; it assembles a task contract via
scripts/collab.pyand a remoteopencodeworker writes the diff (scripts/agent-run-v3.sh). The worker never pushes; the local Agent pushes after device verification. - Crash-tolerant long tasks: builds run detached on the server (nohup) and are polled; worker runs are async and polled via
status/log.
Layers
- Purpose: stable command surface for humans and agents
- Location:
ohos_cli.py - Contains: subcommand→script map (
MAP),server init|checkspecial-casing,version(), telemetry emission per command - Depends on:
scripts/by path (subprocess), never imports scripts - Used by: humans, agent skills, CI-like automation
- Purpose: decide which directory holds user data vs package assets
- Location:
scripts/wsroot.py - Contains:
ws_root(),inventory_path(),config_path(),config_dir(),load_registry()(deep merge) - Depends on:
$OHOS_WS, marker fileohos-workspace.yaml, repo shapescripts/+config/inventory.yaml - Used by:
apply.py,collab.py,flash.py,report_draft.py,server_init.py— every script that touches user data - Purpose: execute a job spec end-to-end with structured, pollable results
- Location:
scripts/apply.py - Contains:
Server(SSH/SCP),Board(hdc wrappers),Tmpl/fmttemplating, step functions,check_jobvalidation,preview_plan,action_run - Depends on:
wsroot,ui_probe,diffcov,telemetry, YAML specs,ssh/scp/hdc/devicoclibinaries on PATH - Used by: humans, skills (
loop-iterate),server_init.py(smoke) - Purpose: reusable evidence/judgment modules with thin wiring into
apply.py - Location:
scripts/ui_probe.py,scripts/diffcov.py,scripts/sign_hap.py,scripts/report_draft.py - Contains: normalization/query/assert (ui_probe), line-intersection judging (diffcov), signing chain (sign_hap), template rendering (report_draft)
- Depends on: hdc, gcovr, DevEco toolchain (sign), YAML
- Used by:
apply.pystep functions (assert,ui_click,tdd_hostcoverage,hap_sign,diffcov), and CLI directly - Purpose: durable task contract between local driver and remote code-worker
- Location:
scripts/collab.py+scripts/agent-run-v3.sh(deployed to server~/collab/bin/byscripts/server_init.py) - Contains: task dir lifecycle under
tasks/<tid>/, async run invocation, status/log polling, fetch/artifacts, close (releases pool + assembles report) - Depends on: SSH,
opencode, server-side~/collab/layout,workspace_pool.yaml - Used by: humans,
.agents/skills/collab-delegate,.agents/skills/loop-iterate - Purpose: telemetry collection and dashboards, deployed independently of the tool repo
- Location:
devloop_telemetry仓(独立部署,Phase 8 拆出) - Contains: collector (
telemetry_server.py), Flask dashboard (telemetry_web.py), stdlib render core (telemetry_dashboard.py), weekly report (telemetry_report.py) - Depends on: Python stdlib only (collector/core/report); Flask only for
telemetry_web.py - Used by: client
scripts/telemetry.pypush; humans viewing dashboards - Purpose: single source of truth for resources and declarative job definitions
- Location:
config/,examples/,workspace_pool.yaml - Contains:
inventory.yaml(servers/boards/emulators/local), job specs (verify.yaml,e2e-hap.yaml,tdd-host.yaml,tdd-board.yaml,tdd-emulator.yaml,tdd-coverage.yaml), registries (tdd-suites.yaml,e2e-cases.yaml), templates (task-template.md,templates/,report-templates/), self-test specs (examples/) - Depends on: nothing
- Used by:
apply.py,collab.py,flash.py,report_draft.py,server_init.py
Data Flow
Primary Request Path — verify pipeline (config/verify.yaml)
Code-Modification Path — task contract (remote code-worker)
TDD Gates — small loop / big loop / emulator / coverage
e2e-hap Path (config/e2e-hap.yaml)
Telemetry Path
- Per-run state:
runs/<run-id>/results.jsonis the single progress record;statekey persists cross-process data (e.g., artifact list,ohos_root) for--run-id/--from-stepresumes (scripts/apply.py:1279). - Task state:
tasks/<tid>/files on the local side;.running/.exitmarkers +status.jsonon the server side. - Workspace pool:
workspace_pool.yaml(local, gitignored) maps workspace paths to tasks/baselines; one task per workspace. - Global caches:
wsroot._cached(process-lifetime workspace root memo);telemetryconfig file in~/.ohos-devloop/.
Key Abstractions
- Purpose: describes resources, params, and an ordered step list
- Examples:
config/verify.yaml,config/e2e-hap.yaml,config/tdd-board.yaml,examples/smoke.yaml - Pattern:
job/resources{server,board} /params/steps[].type - Purpose: type string → function dispatch; the scheduler's only extension point
- Examples:
scripts/apply.py:1203—build,detect_changed,fetch,push,capture,shell,assert,board_preflight,hap_build,hap_sign,hap_install,app_run,tdd_host,tdd_board,diffcov,ui_click - Pattern: each step returns
(status, detail)where status ∈ok|warn|skip|fail; raisingApplyErrormaps to fail - Purpose: isolate transport quirks (SSH timeouts, hdc exit-code unreliability)
- Examples:
scripts/apply.py:115,scripts/apply.py:142 - Pattern:
Server.ssh()/scp_get();Board.shell()/param()/md5()/recv()/send()/remount_rw()/wait_boot()— success judged by output/artifacts, never hdc exit codes - Purpose: one mutable dict carried through every step
- Examples:
scripts/apply.py:1306 - Pattern:
inv,job,params,run_id,run_dir,server,board,board_cfg,state,tmpl_ctx,results - Purpose: durable, file-based protocol between local driver and remote worker
- Examples:
config/task-template.md(header fieldsrepo/build_targets/tdd_targets),tasks/<tid>/report.md(first line = status),status.json(fixed schema),artifacts.txt(one deploy-relative path per line) - Pattern: worker writes structured files; local side validates id match and first-line status (
scripts/agent-run-v3.shtail) - Purpose: name → configuration mapping without code changes
- Examples:
config/tdd-suites.yaml(suites),config/e2e-cases.yaml(cases), merged bywsroot.load_registry()— package defaults deep-merged under workspace entries - Pattern: aliases like
ph-list→ target + gtest_filter + expected_tests - Purpose: M6 separation of user data from tool distribution
- Examples:
scripts/wsroot.pyheader - Pattern:
$OHOS_WS/marker → workspace forinventory/tasks/runs/pool; package repo for worker script/smoke specs/registry defaults/templates
Entry Points
- Location:
ohos_cli.py - Triggers:
ohos-devloop <subcmd>console script (editable pipx install) or direct execution - Responsibilities: subcommand map (
apply,collab,flash,init,check-env,report,sign,sgrep,ui-probe,diffcov,telemetry;server init|check), UTF-8 stdout setup, version resolution, command telemetry - Location:
scripts/apply.py main()(scripts/apply.py:1409) - Triggers: CLI / skills
- Responsibilities:
plan(no machine contact) andrun(with--from-step/--only/--run-id/--keep-going/--params); relative spec path resolution (cwd → workspace → package) - Location:
scripts/collab.py main()(scripts/collab.py:99) - Triggers: CLI /
collab-delegateskill - Responsibilities: subcommands
new/push/run/status/log/fetch/artifacts/close/stats; task-id whitelist regex against injection - Location:
scripts/agent-run-v3.sh(deployed to server~/collab/bin/) - Triggers:
collab.py runvia SSH nohup - Responsibilities: one-shot opencode execution with inlined code discipline; report validation; exit codes 2/3/4 for setup/report/status failures
- Location:
scripts/flash.py main() - Triggers: CLI /
pool-statusskill - Responsibilities:
fetch(CI daily builds, last 7 days),extract(flatten toD:/rk3568/images,.manifestcleanup),list,pool init|status|claim|release,sync-repo(align mega-repo to image baseline, auto-register) - Location:
scripts/server_init.py main() - Triggers: CLI / README setup flow
- Responsibilities: health probe (read-only SSH) → deploy worker + md5 verify + VERSION stamp → run
examples/smoke.yamlacceptance - Location:
scripts/check_env.py main() - Triggers: first action after clone;
--offlineto skip network/board - Responsibilities: PASS/WARN/FAIL items matching README install steps; exit 1 on FAIL
- Location:
scripts/ws_init.py main() - Triggers:
ohos-devloop init - Responsibilities: generates
ohos-workspace.yamlmarker, inventory template, user AGENTS.md, QUICKSTART,tasks/,runs/ - Location:
devloop_telemetry/telemetry_server.py,devloop_telemetry/telemetry_web.py,devloop_telemetry/telemetry_dashboard.py,devloop_telemetry/telemetry_report.py - Triggers: systemd units (
ohos-telemetry-dashboard) / nohup on the collection server - Responsibilities: event collection, dashboard rendering, weekly metrics
- Location:
scripts/sign_hap.py,scripts/ui_probe.py,scripts/diffcov.py,scripts/sgrep.py,scripts/report_draft.py,scripts/telemetry.py,scripts/verify_frame_diff.py,scripts/mount_ws.py - Triggers: CLI directly or library import from
apply.py - Responsibilities: each is library + CLI dual-form where consumed by the scheduler
Architectural Constraints
- Threading: Single-process, sequential step execution. Long operations are detached on the remote side (server
nohupbuilds; async worker runs) and polled — no local threads exceptdevloop_telemetry/telemetry_server.py/devloop_telemetry/telemetry_dashboard.py(ThreadingHTTPServer) andtelemetry_web.py(Flask). - Global state:
wsroot._cachedmemoizes the workspace root for process lifetime (scripts/wsroot.py:28); telemetry module-level constants (DIR,DEFAULT_ENDPOINT) inscripts/telemetry.py; dashboard login rate-limit dict_failindevloop_telemetry/telemetry_web.py. - Circular imports: None known;
server_init.pyimportsshfromcollab.py,apply.pyimportsui_probe/diffcov/telemetry/wsroot— all one-directional within flatscripts/. - Flat script module discipline:
scripts/*.pyare not a package; sibling imports work only because scripts are run by path (Python adds script dir tosys.path).pyproject.tomldeliberately keepsscripts/out of the wheel until a data-files channel exists (pyproject.toml:5). - Transport semantics: list-argument subprocess only (no shell strings) to dodge Git Bash quoting/path conversion (
scripts/apply.py:87,scripts/collab.py:46); hdc exit codes untrusted — verify by md5/file presence. - Worker path boundary: worker shell commands must stay inside the repo workspace; opencode's
external_directoryauto-rejects and terminates otherwise (scripts/agent-run-v3.shprompt; iron rule 7). - No worker git push: all pushes are a separate local-Agent step after device verification (
scripts/agent-run-v3.sh). - Baseline coupling: board
const.product.software.versionmust match the build baseline; firmware change requiresflash.py extractthensync-repo(iron rules 1/2). - Board TDD gate: any code or TDD-case change must pass the affected suites on the real board; host-green is not an exemption (iron rule 8).
Anti-Patterns
Hardcoded server endpoint outside inventory
Repo-root assumptions in newer scripts
Module-level memo without invalidation
Mixing archive and source in the repo root
Error Handling
- Step-level:
try/except ApplyError → status="fail", detail={"error": ...}; loop stops on first fail unless--keep-going(scripts/apply.py:1347). - Template safety:
Tmpl.__missing__raisesApplyErrornaming available keys (scripts/apply.py:100). - Version gate:
min_tool_versionin a spec is enforced at plan/run; unparseable local versions WARN and pass through (scripts/apply.py:1236). - Artifact-verified success: md5 compare after
hdc file send;hdc file recvconsidered successful only if the local file exists non-empty (scripts/apply.py:176,scripts/apply.py:439). - Worker reporting contract: report.md first line must be a status token; exit 3 for missing/invalid, exit 4 for missing/mismatched
status.jsonid (scripts/agent-run-v3.shtail). - Telemetry is fail-silent:
emit()never raises; push failures retain the cursor for retry (scripts/telemetry.pyheader). - CLI exit codes: 0 success, 1 step failure, 2 usage/config error (
scripts/apply.py:1436,scripts/collab.py:41).
Cross-Cutting Concerns
Project Skills
| Skill | Description | Path |
|---|---|---|
| collab-delegate | 修改服务器侧代码(OpenHarmony 大仓工作区)前的强制判定与远端 code-worker 任务派发流程——主 Agent(轻模型)不做代码修改,一律组任务契约交给服务器 code-worker(重模型,代码与构建同机)执行。当即将修改服务器代码、用户说"交给 agent / 派生 / 委派 / 定位修改代码"、或收到"违反了修改原则"类反馈时使用。 | .agents/skills/collab-delegate/SKILL.md |
| loop-iterate | Agent Loop 标准迭代驱动——把 RUNBOOK「一轮标准迭代」固化为可执行流程:改码判定 → 任务契约派发 → 轮询回收 → 小循环 tdd_host 快反馈 → 大循环推板 + tdd_board 门 + hap e2e 判定 → 失败证据自动回填 → 收敛控制。当用户要求"跑一轮迭代 / 调试这个任务 / Agent Loop / 验证修复 / 走标准迭代",或收到 collab worker FINISHED 回收后需要继续验证链时使用。 | .agents/skills/loop-iterate/SKILL.md |
| openharmony-ci | Use when investigating OpenHarmony PR CI status from openharmony_ci comments, DCP event IDs, build labels, artifact links, or CI log URLs. |
.agents/skills/openharmony-ci/SKILL.md |
| pool-status | 列举 OpenHarmony 大仓工作区池的实时状态——每个工作区被哪个工作项占用、哪些空闲可用。会 SSH 到构建服务器实时扫描现存工作区并与本机 workspace_pool.yaml 对账,感知服务器管理后台对工作区的增删(新增的自动入册,已删的标 GHOST)。当用户问"工作区状态/工作区占用/哪些工作区可用/workspace pool/pool status",或领取工作区、sync-repo、给 code-worker 任务挑工作区前使用。 | .agents/skills/pool-status/SKILL.md |
GSD Workflow Enforcement
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
/gsd-fastfor a trivial task inline, with no subagents and no PLAN.md/gsd-quickfor small fixes, doc updates, and ad-hoc tasks/gsd-debugfor investigation and bug fixing/gsd-execute-phasefor planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
Developer Profile
Profile not yet configured. Run
/gsd-profile-userto generate your developer profile. This section is managed bygenerate-claude-profile-- do not edit manually.