harmony-next

HarmonyOS NEXT Agent Guide

Use this skill to answer HarmonyOS NEXT questions with the bundled offline references. Keep context small: route the request first, then open only the specific Markdown files needed for the answer or action.

Paths like references/... and scripts/... are relative to this skill directory: the directory that contains this SKILL.md. Resolve that directory once as HARMONY_NEXT_SKILL_DIR. Do not assume harmony-next/ exists at the current repository root. Official scan locations include $REPO_ROOT/.agents/skills/harmony-next, $HOME/.agents/skills/harmony-next, and /etc/codex/skills/harmony-next.

# Directory containing this SKILL.md (the file you loaded).
HARMONY_NEXT_SKILL_DIR="<skill-dir>"

Use $HARMONY_NEXT_SKILL_DIR from any working directory, including a normal application repository root. Bundled playbooks must use this variable for executable paths; treat any hard-coded repository-root skill prefix in a bundled playbook as a portability bug.

Version

Current local skill version: v1.3.37.

Reference snapshot: bundled references/ are an offline HarmonyOS API 12-23 snapshot, not live web docs. HarmonyOS SDK 26.0.0 (API 26.0.0) reached Release on 2026-08-29; API 26 declaration pages are bundled under references/JsEtsAPIReference/api26/; full guides and examples remain pending.

For "latest", "current", new API, or online-doc parity questions, compare this local version with GitHub Releases or nightly, and verify API behavior against Huawei online docs when precision matters.

API 26 release tracking and adaptation notes: references/harmonyos-releases/api-26-release.md.

Install/update entrypoints:

Vercel Labs skills CLI: npx skills add linhay/harmony-next.skills --skill harmony-next; add -a claude-code -g -y --copy for a non-interactive global Claude Code install, or -a codex -g -y --copy for Codex.
Gemini CLI: gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user
Claude Code: use npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy; Claude.ai can still use the release harmony-next.skill.zip upload flow.
Codex: use npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy, or put/symlink harmony-next/ into an official Codex scan location such as $REPO_ROOT/.agents/skills/harmony-next, $HOME/.agents/skills/harmony-next, or /etc/codex/skills/harmony-next; for reusable installable distribution, package it as a Codex plugin.

Routing

Classify the user request
- API, component, error, or code example: use KITS.md, TASK_MAP.md, and INDEX.md; do not read the DevEco playbooks.
- Minimal project fixture, Empty Ability scaffold, HDC/uitest smoke app, or copyable HarmonyOS test project: use references/quickStart/ets/minimal-project-scaffold.md and references/templates/empty-ability-app/.
- DevEco Studio IDE, plugins, local services, CodeGenie, MCP, LanceDB, devecostudio://, UxTestService, or offline UI/UX audit: read the IDE playbook.
- HarmonyOS Command Line Tools download, archive install, PATH setup, or codelinter -v validation: read references/ideGuides/独立命令行工具配置手册.md and use scripts/commandline_tools_manager.py.
- HarmonyOS Emulator, HVD, hdc, uitest, aa, bm, hilog, or hidumper automation: read the Emulator playbook.
- ArkWeb/WebView DevTools forwarding, CDP Runtime.evaluate, or H5 bridge field-arrival proof: read references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md.
- Unknown domain: start with references/TASK_MAP.md, then refine through references/INDEX.md.
Choose the smallest index
- Kit navigation:references/KITS.md
- Task-oriented:references/TASK_MAP.md
Find the target file
- Full repository path inventory:references/INDEX.md
- JS/ETS API bucket inventory:references/JsEtsAPIReference/INDEX.md
Open only target references references/JsEtsAPIReference/ Currently mainly modules/、topics/、types/、errors/、guides/ .
- guides/ contains offline guide pages that replace common official online guide links.

Lookup Commands

After resolving HARMONY_NEXT_SKILL_DIR from this SKILL.md:

First match paths by keyword:rg -n "UIAbility|AbilityStage|Want" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | head
Look up a certain @ohos.* module:rg -n "@ohos\\.app\\.ability\\.|@ohos\\.ability\\." "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "JsEtsAPIReference/" | head
Look up NDK/C API header files:rg -n "JsEtsAPIReference/topics/.*/.*\\.h\\.md$" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "(napi|arkui|window|ability)" | head

Tooling Script Skills

Use these script-backed skill entries before hand-writing DevEco setup commands. They are intentionally small wrappers around unstable local tooling and should return structured status when the environment is missing.

User intent	Script skill	Agent first command	User handoff
Download, install, configure, or validate HarmonyOS Command Line Tools	`commandline_tools_manager.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/commandline_tools_manager.py" doctor --tools-root <dir> --json`	If the user gives a Huawei download center page URL, return the script's blocked result and ask the user to log in, copy the direct archive URL, or provide a local archive.
List, clone, delete, diagnose, or launch local DevEco HVD instances	`hvd_manager.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/hvd_manager.py" doctor --json`	If HVD root, Emulator, SDK/image root, or trace startup data is missing, report the `issues`, `recommendations`, and `missingConfig` fields and ask the user to pass `--root`, `--emulator`, `--sdk-root` / `--image-root`, or matching env vars.
Collect bounded HDC device evidence or diagnose WebView DevTools forwarding	`device_evidence_bundle.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_evidence_bundle.py" doctor --deveco-app <DevEco-Studio.app> --json`	Use `capture ... --artifact-dir <dir>` only when raw local screenshots, layout trees, app state, and bounded logs may be stored locally. Use `webview-devtools ... --artifact-dir <dir>` for socket/fport/HTTP discovery classification.
Perform one bounded UI action with before/after evidence	`device_ui_action.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_ui_action.py" tap --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --text "<visible-text>" --json`	Require exactly one target selector or raw device coordinate. Treat returned screenshot dimensions as the coordinate space; never reuse scaled preview coordinates.
Capture a running HarmonyOS page and run an offline UI/UX audit report	`ux_audit_pipeline.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" doctor --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --json`	Use `python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" capture-audit --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --target <target> --artifact-dir .hvigor/outputs/<run> --json` for the one-shot path. If Python image-processing modules are missing, report `missingConfig=["uxPythonDependencies"]` instead of treating UxTestService as broken.
Convert offline DevEco Profiler trace files into SQLite evidence summaries	`profiler_trace_audit.py`	`python3 "$HARMONY_NEXT_SKILL_DIR/scripts/profiler_trace_audit.py" doctor --deveco-app <DevEco-Studio.app> --json`	If `trace_streamer` or the input trace is missing, report the machine-readable `blocked` payload. Use `audit --input <trace> --output-dir .hvigor/outputs/<run> --json` only for existing `.ftrace` / `.htrace` / bytrace / rawtrace artifacts.

Boundaries:

commandline_tools_manager.py may download only a direct archive URL; a download center page URL is a login-gated page, not an archive.
hvd_manager.py launch-preflight prints a guarded Emulator command plan when an external trace helper is already ready.
hvd_manager.py launch currently creates a startup trace socket, detaches Emulator and a trace holder, starts Emulator with -t <trace-name>, and waits for HDC/boot/stability unless --no-wait-target is passed.
device_evidence_bundle.py is evidence capture, not app lifecycle control: it may save real UI/layout/log artifacts to an explicit artifact directory, but it does not install, uninstall, start, stop, or mutate apps.
device_evidence_bundle.py webview-devtools may create one bounded fport; by default it removes only the forward created by that run. It emits socket, stale-forward, HTTP reset/refusal/timeout, and invalid-JSON failure codes.
device_ui_action.py performs exactly one uitest uiInput tap, swipe, or key event between before/after layout, screenshot, and bounded log capture. Coordinates must be raw device pixels from layout bounds or explicit device-space input.
ux_audit_pipeline.py composes device_evidence_bundle.py with DevEco UxTestService: it copies tools/UxTestService into the artifact directory before import so the DevEco .app bundle is not modified.
If either wrapper returns blocked, agents should try official HarmonyOS CLI evidence commands before giving up: hdc list targets -v, hdc -t <target> shell uitest dumpLayout ..., screenCap, file recv, bm dump, aa dump, and bounded hilog.
If a wrapper is blocked, misleading, or missing a useful workflow, use the scenario-specific GitHub issue form from the script's feedback JSON field or ISSUE_GUIDE.md; when GitHub access and enough context are available, create or comment on the issue directly with gh, preserving structured fields and following the redaction rules.
profiler_trace_audit.py is offline only: it runs DevEco trace_streamer, writes SQLite/JSON artifacts outside the DevEco .app bundle, and does not launch DevEco Studio, connect devices, or claim GUI Profiler headless import.
Lifecycle direction: prefer an attached terminal-scoped launch mode for future CLI work, where the foreground runner owns the trace socket, waits for readiness, and calls Emulator -stop <hvd-name> -path <hvd-root> when the terminal session ends; keep detached mode only as an explicit compatibility path.
hvd_manager.py download-image reports HVD image download as machine-readable blocked; current verified path is DevEco Studio SDK Manager UI, not a stable non-UI CLI.
For cross-machine support, prefer doctor --json output over hard-coded macOS paths in answers and docs.

API 26 declaration snapshot sync: run python3 "$HARMONY_NEXT_SKILL_DIR/scripts/sync_api26_snapshot.py" --deveco-app <DevEco-Studio.app>, then rebuild indexes with python3 "$HARMONY_NEXT_SKILL_DIR/scripts/reference_compat.py" generate.

Minimal Empty Ability Scaffold

Use when an agent needs a copyable HarmonyOS NEXT smoke fixture without opening DevEco Studio:

Scaffold guide: references/quickStart/ets/minimal-project-scaffold.md
Copyable template: references/templates/empty-ability-app/
Defaults: bundleName com.example.emptyability, module entry, ability EntryAbility, Compatible SDK 5.0.0(12), target SDK 5.0.0(12).
Route/component split: pages/Index.ets is only the @Entry route page and mounts SmokeCounter(); components/SmokeCounter.ets owns the smoke UI state and node IDs.
Validation entrypoints: ohpm install, hvigorw --mode module -p module=entry@default assembleHap, HDC install/start, uitest dumpLayout, and uitest screenCap.
SDK override validation: for a target SDK such as HarmonyOS 6.0.2 / API 22, set the copied fixture's compatibleSdkVersion and targetSdkVersion to 6.0.2(22) and set DEVECO_SDK_HOME to the SDK root, for example DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk, not sdk/default.
API 22 schema compatibility depends on app and Ability icons: keep AppScope/resources/base/media/app_icon.png, app icon, Ability icon, and startWindowIcon in the template.
Stable smoke UI signals: Harmony Smoke Ready, smoke-title, smoke-counter, smoke-increment.
Interactive smoke: after launch, use uitest uiInput click on the smoke-increment bounds and verify tapCount=1 / Harmony Smoke Tapped from a fresh dumpLayout.

Command Line Tools Setup

Use when the user asks to download or configure HarmonyOS Command Line Tools without DevEco Studio.

Official boundary: Huawei's "获取命令行工具" page points agents to the Command Line Tools download center, says HarmonyOS SDK is embedded in the package, and configures ${Command Line Tools解压路径}/command-line-tools/bin in PATH.
This skill provides scripts/commandline_tools_manager.py for a controlled local flow: download --url <direct-archive-url>, install --archive <zip> --dest <dir> --profile auto, bootstrap --url <direct-archive-url> ..., configure --tools-root <dir> --profile auto, and doctor --tools-root <dir>.
The script requires a direct archive URL copied from Huawei's download center or a local archive path. If given the download center page URL, it returns machine-readable blocked instead of pretending to resolve the current package.
Use --sha256 <digest> when Huawei's integrity value is available.

DevEco Emulator Automation

Use when the user asks to start or inspect HarmonyOS Emulator without the IDE, operate the emulator from command line, diagnose hdc/uitest/aa/bm/hilog/hidumper automation, or debug simulator traffic capture with HTTP proxy tools such as Charles, mitmproxy, or Proxyman.

Only read this playbook for Emulator/HVD/hdc/uitest/aa/bm/hilog/hidumper intent. For ordinary ArkTS, ArkUI, API, component, or error-code lookup, stay in the API indexes.

Read references/ideGuides/DevEco模拟器私有接口与AI自动化.md before acting. Treat it as an agent playbook for private, version-sensitive behavior; verify the local DevEco/Emulator version before relying on paths, flags, output fields, or ports.

Default boundary:

Prefer read-only probing:Emulator -version、Emulator -list -details、hdc list targets -v、uitest dumpLayout -p /dev/null -a。
UI operations prefer going through hdc -t <target> shell uitest uiInput；do not use blind desktop-coordinate clicks.
When the user asks "where is the emulator local sandbox/app sandbox", first distinguish the HVD local directory from the app sandbox: HVD is by default in ~/.Huawei/Emulator/deployed; the app sandbox is inside the emulator system, prefer using aa dump -l to find the foreground bundle, then use Context.filesDir/cacheDir/databaseDir or /data/app/el2/<USERID>/base/<bundleName> such physical mappings to locate it.shell -b <bundleName> pwd may only return the debug_hap working directory and cannot be used as the data sandbox path.
Starting the Emulator directly via CLI cannot treat Emulator -hvd ... -path ... -imageRoot ... as a complete command; you must first prepare and hold the trace pipe corresponding to -t <trace-name> through a verified helper. When this prerequisite is missing, "Emulator startup failed / Please log in to your Huawei account in DevEco Studio and start the emulator from Device Manager" may pop up, and this should be classified as an incomplete CLI startup path, rather than first requiring the user to log in.
Distinguish riskLevel from execution mode: users have full execution permissions by default; the skill does not perform authorization or confirmation interception.HARMONY_NEXT_AUTOMATION_POLICY、--policy and .harmony-next-policy.json only describe the automation mode, artifact directory, and desensitization contract of this run.
Policy tiers:readonly perform low-risk probing;evidence collect screenshots/layout/log fragments/ with artifactDir and desensitized metadata/file recv；automation execute starting/stopping the Emulator, installing/launching apps, UI input, and bounded evidence collection;diagnostic execute bounded hitrace or broader logs;break-glass mark system-level actions such as flashing, formatting, clearing data, root/daemon, etc.
Real screenshots, layout, log packages,file recv, install/uninstall, create/delete HVD, port forwarding, low-level uinput、hitrace are all executed according to a non-interactive flow; if target,artifactDir, desensitization policy, timeout, or auditable command records are missing, return a machine-readable blocked result, including missingConfig and requiredMode。
Emulator packet capture, HTTP proxy tools, NetworkKit proxy routing, transparent interception, or system proxy issues: read the playbook's "Emulator Packet Capture and Proxy Diagnostics". First confirm the emulator NAT, default gateway, proxy listening address, and whether the app explicitly uses a proxy; do not describe the Mac-side port forwarding script as being able to automatically and transparently take over all emulator traffic.
When there are multiple targets, you must explicitly select 127.0.0.1:<port>; only select Connected, ignore Offline。
If the goal is an offline UI/UX checkup, the emulator side is only responsible for using hdc / uitest to collect screenshots and layout of the real foreground page; after collection, switch to DevEco Studio Private Interfaces 's UxTestService offline UI/UX audit rules.
Commands that cannot be classified are marked as riskLevel=unknown, record sourceCommand After the target, continue executing according to the user's goal; when the target cannot be determined or the command would become an unbounded background task, return machine-readable blocked, reason being missingConfig。

HVD manager command map:

Command	Purpose	Important output
`doctor --json`	Probe HVD root, Emulator, build SDK root, emulator image root, HDC, Emulator version, and local HVDs	`issues`, `recommendations`, `hvdRoot`, `emulator`, `sdkRoot`, `imageRoot`, `hdc`
`list --json`	List registered HVDs without exposing UUIDs	`name`, `device_type`, `api_version`, `hdc_port`, `image_sub_path`, `exists`
`launch-preflight --name <hvd> --image-root <dir> --trace-name <name> --trace-helper-ready-file <file> --json`	Validate trace helper readiness and image root without starting Emulator	`decision`, `missingConfig`, `emulatorCommand`
`launch --name <hvd> --image-root <dir> --trace-name <name> --json`	Current implementation: create trace socket, detach Emulator and trace holder, then wait for HDC, boot, and stability	`traceHolder`, `hdcWait`, `bootWait`, `stabilityWait`, `logPath`
`device_evidence_bundle.py doctor --deveco-app <DevEco-Studio.app> --json`	Locate `hdc` and summarize connected targets	`connectedTargets`, `missingConfig`, `issues`
`device_evidence_bundle.py capture --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --json`	Collect boot state, `bm` / `aa` summaries, bounded `hilog`, `uitest dumpLayout`, screenshot, and command ledger	`summary`, `artifacts`, `layoutSummary`, `commandLedger`
`device_evidence_bundle.py webview-devtools --target <target> --artifact-dir .hvigor/outputs/<run> --json`	Enumerate WebView DevTools sockets, classify stale forwards, create one bounded fport, and probe `/json` plus `/json/version`	`sockets`, `staleForwards`, `fportStatus`, `httpProbe`, `failureCode`
`device_ui_action.py tap --target <target> --artifact-dir .hvigor/outputs/<run> --text "<text>" --json`	Resolve raw bounds, execute one tap, and capture before/after evidence	`coordinateSpace`, `action`, `before`, `after`, `commandLedger`
`ux_audit_pipeline.py doctor --deveco-app <DevEco-Studio.app> --python <python> --json`	Locate `hdc`, UxTestService, connected targets, and Python UX dependencies	`uxService`, `uxPython`, `connectedTargets`, `missingConfig`
`ux_audit_pipeline.py capture-audit --deveco-app <DevEco-Studio.app> --python <python> --target <target> --artifact-dir .hvigor/outputs/<run> --json`	Capture layout/screenshot/log evidence, infer foreground bundle, run UxTestService, and write a Markdown/JSON report	`captureSummary`, `auditSummary`, `report`, `resultCounts`, `bundleName`
`ux_audit_pipeline.py audit --evidence-summary <summary.json> --artifact-dir .hvigor/outputs/<run> --json`	Re-run UxTestService against an existing evidence bundle without touching the device	`checkParam`, `uxResult`, `uxSummary`, `report`, `resultCounts`
`launch --accept-license ... --json`	Explicitly answer yes to the first-run Huawei Emulator agreement prompt after the operator has reviewed it	`result=started` or `result=license-agreement-required`

HVD launch rules:

--sdk-root / DEVECO_SDK_HOME is the DevEco build SDK root. Do not treat it as the emulator image root.
--image-root / HARMONY_EMULATOR_IMAGE_ROOT is the emulator image root. On macOS this is commonly ~/Library/Huawei/Sdk.
launch and launch-preflight validate <image-root>/<imageSubPath> from HVD config.ini; failures return missingConfig=["imageRootSystemImage"].
Current launch defaults: trace holder stays alive for 1800 seconds, and the post-boot stability check runs for 60 seconds.
First-run Emulator license/agreement prompts are classified as result="license-agreement-required" with missingConfig=["emulatorLicenseAgreement"]; do not silently accept them. Use --accept-license only as an explicit opt-in after the agreement has been reviewed.
HDC readiness failures are classified with failureCode: emulator_kernel_panic, emulator_crashed, stale_hdc_target, or hdc_wait_timeout. Image and trace preconditions use image_root_missing, license_agreement_required, and trace_helper_unavailable.
If another process needs to install HAPs, deep link, screenshot, or dump layout after current detached launch, use the returned hdcWait.target and keep the trace holder alive long enough with --trace-hold-seconds.
Attached lifecycle checklist: the runner must stay foreground, keep the trace socket in-process, trap SIGINT / SIGTERM / SIGHUP, call Emulator -stop, close the socket, remove only its own trace path, and verify hdc list targets -v no longer reports the selected target.
Failure/timeout diagnostics should include logPath, processExitCode, hvdRuntime, hdcSnapshot, hdcWait, bootWait, and stabilityWait when present.

ArkWeb / WebView CDP field-arrival evidence

Read references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md when the task is to prove that H5 code inside HarmonyOS ArkWeb received native bridge fields.

Prefer an already available TritonKit Harmony runtime; fall back to HDC/WebView CDP only when the higher-level runtime is unavailable.
Run device_evidence_bundle.py webview-devtools first. Multiple sockets require explicit --remote-socket; stale forwards are reported without global cleanup.
Use the selected page webSocketDebuggerUrl with CDP Runtime.evaluate, awaitPromise=true, and returnByValue=true.
Treat the small, redacted bridge callback JSON as primary proof. Do not block on Page.captureScreenshot.
Use aa dump, layout, and screenshot only as supporting foreground evidence. Ignore lock-screen or non-target captures.

DevEco Studio Private Interfaces

Use when the user asks about DevEco Studio internals or automation for CodeGenie, local AI/RAG/MCP, devecostudio://, Previewer, ArkUI Inspector, Profiler, Doctor, Diagnostic, FaultLog, UxTestService, plugin actions, tool windows, or services.

Only read this playbook for DevEco Studio IDE/private-interface intent. For ordinary HarmonyOS API lookup, do not load it.

Read references/ideGuides/DevEco Studio IDE私有接口与AI自动化.md before acting. Treat it as a safety-first playbook, not as a stable public API reference. Reconfirm the installed DevEco version and local paths before using any plugin ID, class name, URL scheme, port range, handler, cache path, or local service.

Default boundary:

Read-only allowed: enumerate files within the DevEco package, parse Info.plist / product-info.json / plugin XML, scan jar class names and strings, analyze offline .htrace / faultlog / stacktrace / .arkli / .preview artifacts.
High-sensitivity actions: launch IDE/GUI/JCEF/Preview Server/Inspector/Profiler/Debug, connect to a device, capture screenshots/logs/layout, read user-side cache or chat history, call CodeGenie localhost HTTP/WebSocket, create MCP configuration, trigger external LLM provider; before execution, record the target, inputs, artifact directory, and desensitization policy.
System-level actions: automatic login, upload, deployment, cache clearing, state deletion, exposing token/securityId/API key/project snippets/log body text, verifying unknown devecostudio:// URL without isolation; when the user explicitly requests it, execute according to the goal, but an audit summary and desensitization boundary must be retained.

Capabilities such as CodeGenie, MCP, LanceDB, HTTP forwarding, Application Agent, Operation Analyzer, and Cloud Toolkit must first undergo privacy and account boundary determination before entering auditable execution.

UxTestService offline UI/UX audit

Use when the user asks for offline UI/UX review, UI/UX audit, visual/layout checks, clickable hotspot checks, DevEco UxTestService, or a simulator-backed UI quality report.

Verified boundary:

Prefer scripts/ux_audit_pipeline.py for repeatable runs. It supports doctor, capture-audit, and audit; pass --python or HARMONY_UX_PYTHON when the default Python lacks cv2, numpy, PIL, requests, scipy, skimage, werkzeug, or opencc.
capture-audit is the validated one-shot workflow: it captures real device evidence with hdc, infers the non-system foreground bundle from the layout, copies UxTestService into an artifact-local runtime, writes check_param.json, runs ux_detect.main(check_param=...), then emits ux_result.json, ux_summary.json, report.md, and summary.json.
audit --evidence-summary <summary.json> is the validated offline re-run path for an existing device_evidence_bundle.py capture.
On failure, prefer official CLI recovery before abandoning the audit: manually capture layout.json and screen.png with hdc / uitest, receive them locally with hdc file recv, then retry ux_audit_pipeline.py audit --layout ... --screenshot ... --bundle ....
For blocked results, confusing rule output, or unsupported DevEco/UxTestService versions, create or comment on a repository issue using the feedback section in summary.json / report.md when GitHub access and enough context are available; ask the user to file it only when auth/network is blocked or required details are missing. Never attach raw screenshots, raw layout JSON, full logs, or marked images without verified redaction.
Treat DevEco tools/UxTestService/ux_detect.py as a private, version-sensitive engine. Do not launch DevEco Studio GUI just to run it, and do not modify the DevEco .app bundle.
Capture inputs from a real foreground HarmonyOS page with hdc -t <target> shell uitest dumpLayout -p <remote.json> -a and hdc -t <target> shell uitest screenCap -p <remote.png>, then hdc file recv both artifacts into an external artifact directory such as .hvigor/outputs/....
Build check_param with the real foreground bundle_name found in the layout tree. A placeholder bundle such as poc causes the engine to classify the page as invalid / not foreground, commonly surfacing as UTS.0300.
Use extend_infos.language="zh" for local runs. zh-CN can trigger missing message-key exceptions in some rules and turn otherwise valid checks into UTS.0201.
Write logs, result JSON, screenshots, and marked images outside the DevEco app bundle. Some DevEco app bundle copies are not writable and should not be changed because that can disturb app signing.
Start with the proven static subset: 7.1.1.2.1 basic layout subrules, 7.1.1.2.2 hole adaptation, 7.1.1.3.3 hotspot size, 7.1.1.4.4 icon size, 7.1.1.4.5 icon clarity, 7.1.2.1.1 navigation bar, 7.1.2.6.1 status bar, 7.2.2.1.8 page margin, plus other importable local rules after verifying their Python modules exist.
Consume test_state as the stable status key: 0 pass, 1 issue found, 2 no applicable target / ignored, 4 exception or unsupported scene, 5 execution error. For failures, use detail.Issues, detail.IssueComponents, detail.ErrorPath, and detail.CustomDrawPath as developer-facing evidence.
This is not a static config precheck. It analyzes actual screenshot + layout artifacts from a running page and can produce marked images for debugging.

Do not over-claim coverage:

Rules listed in config/rule_config_en.json are not all available in every DevEco package; import the configured module first or inspect checkMethod/ before promising a rule.
Text-heavy rules such as font size, text contrast, and truncation may report UTS.0306 with plain uitest dumpLayout input because ArkUI font/style metadata can be missing. Document that as "no applicable target in this capture mode", not as a product defect.
Launcher, lockscreen, loading pages, high-white-rate pages, keyboard pages, Web/Flutter pages, or bundle/layout mismatches can be intentionally rejected by the engine.
Negative-path validation should use isolated fixture artifacts or a dedicated test app, not mutated production files. A useful smoke is shrinking one copied clickable node's bounds / origBounds in a temporary layout JSON and verifying hotspot rule output includes Issues, IssueComponents, ErrorPath, and CustomDrawPath.

Profiler trace offline evidence audit

Use when the user has an existing HarmonyOS Profiler / bytrace / htrace / ftrace / rawtrace artifact and wants offline performance evidence, long-span summaries, or a machine-readable report without opening DevEco Studio.