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.py entry. 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 like C:/Project/grid_ph_verify), built headlessly via deveco-cli, not in this repo

Runtime

  • Python 3.10+ (Windows, local host) - enforced by pyproject.toml requires-python and scripts/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 (override DEVECO_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 (per config/inventory.yaml board software_version); x86_64_virt QEMU emulator instance as second "board" resource
  • pipx (editable install of this repo -> ohos-devloop CLI) + pip for PyYAML/Pillow/Flask; npm global for @deveco/deveco-cli; pip3 install gcovr (v8.8, server side, see config/tdd-coverage.yaml)
  • Lockfile: none (pyproject.toml declares loose minimums; ohos_cowork.egg-info/ and ohos_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 via config/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_diff assertion (screenshot pixel diff); missing degrades only that assertion kind
  • ThreadingHTTPServer (stdlib) - telemetry collector devloop_telemetry/telemetry_server.py and dashboard fallback devloop_telemetry/telemetry_dashboard.py

Key Dependencies

  • PyYAML - config/inventory.yaml is 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 list args (Git Bash quote/path-conversion immune)
  • hdc (OpenHarmony Device Connector, C:/Program Files/oh_toolchain/toolchains/hdc.exe per config/inventory.yaml local.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.py do_fetch
  • opencode CLI - the server-side code-worker model runner (scripts/agent-run-v3.sh, default model bigmodel/glm-5.3)
  • repo (Google git-repo) - server-side OHOS 大仓 sync to image baseline (scripts/flash.py sync-repo)
  • deveco-cli (@deveco/deveco-cli npm global) - headless hap build/install of test apps (step_hap_build in scripts/apply.py)
  • hap-sign-tool + OpenHarmony.p12 + profile templates - offline hap signing (scripts/sign_hap.py; materials under D:/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, tcg profile with cpu=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 in examples/ (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 by flash.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.yaml marker + 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 unit ohos-telemetry-dashboard)

Conventions

Naming Patterns

  • Python scripts: snake_case with 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 under examples/ (assert-smoke.yaml, diffcov-smoke.yaml).
  • Directories: scripts/, config/, examples/, tests/ — flat, purpose-named.
  • snake_case throughout (dump_layout, resolve_and_click, write_results, check_job).
  • Step handlers in scripts/apply.py follow step_<type> naming, mirroring the YAML type: key: step_build ↔ type: build, step_tdd_host ↔ type: tdd_host (scripts/apply.py:1203 STEPS dict).
  • 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 returns int exit code; step handlers return tuple[str, dict] = (status, detail) with status ∈ ok | skip | warn | fail.
  • snake_case; short locals (rc, out, err from sh()); context dict named ctx throughout scripts/apply.py; run directory variable consistently run_dir.
  • PascalCase classes (Server, Board, Tmpl, Handler) — see scripts/apply.py:115, devloop_telemetry/telemetry_server.py:33.
  • Custom exceptions suffixed Error (ApplyError in scripts/apply.py:71); RuntimeError/ValueError/SystemExit used in library modules (scripts/ui_probe.py, scripts/diffcov.py).
  • Modern type-hint syntax with from __future__ import annotations in newer modules (scripts/apply.py, scripts/wsroot.py, scripts/ui_probe.py, scripts/diffcov.py); PEP 604 union syntax Path | None, tuple[int, ...] | None used 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.toml declares 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 -n for the worker script during deploy (scripts/server_init.py:209), check_env.py runtime diagnostics, and smoke specs as runtime self-tests.
  • Test file uses # noqa: E402 comments (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: 0 ok, 1 fail, 2 usage/error.
  • Module docstrings are mandatory and content-rich: usage lines, design rationale, dates of changes, and "坑位" (pitfall) references to RUNBOOK.md sections. See scripts/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, REPO constants). Workspace/user data resolves through wsroot.ws_root() (scripts/wsroot.py:36); package assets through wsroot.PKG.
  • ohos_cli.py invokes scripts as subprocesses with sys.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() maps TimeoutExpired → (124, "", ...) and FileNotFoundError → (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 ApplyError with 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}".
  • ApplyError is caught once at the top: step loop turns it into status="fail" with {"error": str(e)} in results.json (scripts/apply.py:1349-1350); main() prints ERROR: {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:41 variant returns 2 so callers can return die(...).
  • Non-critical paths swallow exceptions with except Exception: pass + a justifying comment: telemetry emit "永不抛异常——遥测故障不得影响主流程" (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-193 Board.recv/send docstrings; RUNBOOK 铁律 3). ssh/scp verified via md5 echo-back (scripts/server_init.py:201-207).

Logging

  • scripts/apply.py:79 log(msg, run_dir) — prints [HH:MM:SS] msg with flush=True and appends the same line to runs/<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) with ensure_ascii=False, indent=2 — this is the pollable contract for agents.
  • Errors to sys.stderr via print(..., 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: (see git log; e.g. feat: M6 收尾——遥测层 + rebrand 回归测试 + README 精简重写).
  • Worker-side (server code-worker, scripts/agent-run-v3.sh:78-85): branch fix/<短描述> based on current HEAD; stage only explicitly modified files (never git add -A); commit message must carry Signed-off-by:, AI[100%] ... AI Adopted[100%], Co-authored-by:, and Change-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 under runs/<id>/ (not in git); workspace_pool.yaml gitignored.
  • Doc discipline: changing script behavior requires syncing the matching RUNBOOK.md section (AGENTS.md rule); AGENTS.md stays map-level, no detail.

Security Conventions

  • No secrets in the repo: telemetry token lives in ~/.ohos-devloop/telemetry/config.json or DEVLOOP_TELEMETRY_TOKEN env (scripts/telemetry.py:175-178); signing keystore password via KS_PASS env with a default only for the public SDK sample keystore (scripts/sign_hap.py:35).
  • Shell-injection defense: TID_RE whitelist for task-ids before any path use (scripts/collab.py:38,112); shlex.quote on every remote argument; task-id interpolation into remote JSON via json.dumps-style quoting in scripts/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 opencode heavy 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/*.yaml job specs and registries; code only interprets them (scripts/apply.py STEPS registry at scripts/apply.py:1203).
  • Resource-first expansion: "add an entry, don't change code" — servers/boards/emulators in config/inventory.yaml, TDD suites in config/tdd-suites.yaml, e2e cases in config/e2e-cases.yaml.
  • Dual entry, one contract: ohos-devloop <cmd> and python scripts/<script>.py are behaviorally identical; ohos_cli.py only 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.py and a remote opencode worker 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|check special-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 file ohos-workspace.yaml, repo shape scripts/ + 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/fmt templating, step functions, check_job validation, preview_plan, action_run
  • Depends on: wsroot, ui_probe, diffcov, telemetry, YAML specs, ssh/scp/hdc/devicocli binaries 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.py step functions (assert, ui_click, tdd_host coverage, 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/ by scripts/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.py push; 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.json is the single progress record; state key persists cross-process data (e.g., artifact list, ohos_root) for --run-id/--from-step resumes (scripts/apply.py:1279).
  • Task state: tasks/<tid>/ files on the local side; .running/.exit markers + status.json on 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); telemetry config 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; raising ApplyError maps 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 fields repo/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.sh tail)
  • Purpose: name → configuration mapping without code changes
  • Examples: config/tdd-suites.yaml (suites), config/e2e-cases.yaml (cases), merged by wsroot.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.py header
  • Pattern: $OHOS_WS/marker → workspace for inventory/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) and run (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-delegate skill
  • 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 run via 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-status skill
  • Responsibilities: fetch (CI daily builds, last 7 days), extract (flatten to D:/rk3568/images, .manifest cleanup), 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.yaml acceptance
  • Location: scripts/check_env.py main()
  • Triggers: first action after clone; --offline to 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.yaml marker, 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 nohup builds; async worker runs) and polled — no local threads except devloop_telemetry/telemetry_server.py/devloop_telemetry/telemetry_dashboard.py (ThreadingHTTPServer) and telemetry_web.py (Flask).
  • Global state: wsroot._cached memoizes the workspace root for process lifetime (scripts/wsroot.py:28); telemetry module-level constants (DIR, DEFAULT_ENDPOINT) in scripts/telemetry.py; dashboard login rate-limit dict _fail in devloop_telemetry/telemetry_web.py.
  • Circular imports: None known; server_init.py imports sh from collab.py, apply.py imports ui_probe/diffcov/telemetry/wsroot — all one-directional within flat scripts/.
  • Flat script module discipline: scripts/*.py are not a package; sibling imports work only because scripts are run by path (Python adds script dir to sys.path). pyproject.toml deliberately keeps scripts/ 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_directory auto-rejects and terminates otherwise (scripts/agent-run-v3.sh prompt; 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.version must match the build baseline; firmware change requires flash.py extract then sync-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__ raises ApplyError naming available keys (scripts/apply.py:100).
  • Version gate: min_tool_version in 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 recv considered 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.json id (scripts/agent-run-v3.sh tail).
  • Telemetry is fail-silent: emit() never raises; push failures retain the cursor for retry (scripts/telemetry.py header).
  • 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-fast for a trivial task inline, with no subagents and no PLAN.md
  • /gsd-quick for small fixes, doc updates, and ad-hoc tasks
  • /gsd-debug for investigation and bug fixing
  • /gsd-execute-phase for 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-user to generate your developer profile. This section is managed by generate-claude-profile -- do not edit manually.