linhay 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.35.
Reference snapshot: bundled references/ are an offline HarmonyOS API 12-23 snapshot, not live web docs.
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.
Install/update entrypoints:
- Vercel Labs skills CLI:
npx skills add linhay/harmony-next.skills --skill harmony-next; add-a claude-code -g -y --copyfor a non-interactive global Claude Code install, or-a codex -g -y --copyfor 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 releaseharmony-next.skill.zipupload flow. - Codex: use
npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy, or put/symlinkharmony-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, andINDEX.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.mdandreferences/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 -vvalidation: readreferences/ideGuides/独立命令行工具配置手册.mdand usescripts/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: readreferences/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md. - Unknown domain: start with
references/TASK_MAP.md, then refine throughreferences/INDEX.md.
- API, component, error, or code example: use
Choose the smallest index
- Kit 导航：
references/KITS.md - 任务导向：
references/TASK_MAP.md
- Kit 导航：
Find the target file
- 全库路径清单：
references/INDEX.md - JS/ETS API 分桶清单：
references/JsEtsAPIReference/INDEX.md
- 全库路径清单：
Open only target references
references/JsEtsAPIReference/目前以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:
- 先按关键词命中路径：
rg -n "UIAbility|AbilityStage|Want" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | head - 查某个
@ohos.*模块：rg -n "@ohos\\.app\\.ability\\.|@ohos\\.ability\\." "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "JsEtsAPIReference/" | head - 查 NDK/C API 头文件：
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.pymay download only a direct archive URL; a download center page URL is a login-gated page, not an archive.hvd_manager.py launch-preflightprints a guarded Emulator command plan when an external trace helper is already ready.hvd_manager.py launchcurrently 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-targetis passed.device_evidence_bundle.pyis 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-devtoolsmay create one boundedfport; 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.pyperforms exactly oneuitest uiInputtap, 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.pycomposesdevice_evidence_bundle.pywith DevEcoUxTestService: it copiestools/UxTestServiceinto the artifact directory before import so the DevEco.appbundle 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 boundedhilog. - If a wrapper is blocked, misleading, or missing a useful workflow, use the scenario-specific GitHub issue form from the script's
feedbackJSON field orISSUE_GUIDE.md; when GitHub access and enough context are available, create or comment on the issue directly withgh, preserving structured fields and following the redaction rules. profiler_trace_audit.pyis offline only: it runs DevEcotrace_streamer, writes SQLite/JSON artifacts outside the DevEco.appbundle, 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-imagereports HVD image download as machine-readableblocked; current verified path is DevEco Studio SDK Manager UI, not a stable non-UI CLI.- For cross-machine support, prefer
doctor --jsonoutput over hard-coded macOS paths in answers and docs.
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, moduleentry, abilityEntryAbility, Compatible SDK5.0.0(12), target SDK5.0.0(12). - Route/component split:
pages/Index.etsis only the@Entryroute page and mountsSmokeCounter();components/SmokeCounter.etsowns the smoke UI state and node IDs. - Validation entrypoints:
ohpm install,hvigorw --mode module -p module=entry@default assembleHap, HDC install/start,uitest dumpLayout, anduitest screenCap. - SDK override validation: for a target SDK such as HarmonyOS 6.0.2 / API 22, set the copied fixture's
compatibleSdkVersionandtargetSdkVersionto6.0.2(22)and setDEVECO_SDK_HOMEto the SDK root, for exampleDEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk, notsdk/default. - API 22 schema compatibility depends on app and Ability icons: keep
AppScope/resources/base/media/app_icon.png, appicon, Abilityicon, andstartWindowIconin the template. - Stable smoke UI signals:
Harmony Smoke Ready,smoke-title,smoke-counter,smoke-increment. - Interactive smoke: after launch, use
uitest uiInput clickon thesmoke-incrementbounds and verifytapCount=1/Harmony Smoke Tappedfrom a freshdumpLayout.
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/bininPATH. - This skill provides
scripts/commandline_tools_manager.pyfor 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, anddoctor --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
blockedinstead 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:
- 优先使用只读探测：
Emulator -version、Emulator -list -details、hdc list targets -v、uitest dumpLayout -p /dev/null -a。 - UI 操作优先走
hdc -t <target> shell uitest uiInput；do not use blind desktop-coordinate clicks. - 用户问“模拟器本机沙盒/应用沙盒在哪里”时，先区分 HVD 本机目录与应用沙箱：HVD 默认在
~/.Huawei/Emulator/deployed；应用沙箱在模拟器系统内，优先用aa dump -l找前台 bundle，再用Context.filesDir/cacheDir/databaseDir或/data/app/el2/<USERID>/base/<bundleName>这类物理映射定位。shell -b <bundleName> pwd可能只返回 debug_hap 工作目录，不能当数据沙箱路径。 - 直接 CLI 启动 Emulator 不能把
Emulator -hvd ... -path ... -imageRoot ...当成完整命令；必须先通过已验证 helper 准备并持有-t <trace-name>对应的 trace pipe。缺少该前置条件时可能弹出“模拟器启动失败 / 请在DevEco Studio中登录华为账号，并从设备管理中启动模拟器”，应归类为不完整 CLI 启动路径，而不是先要求用户登录。 - 区分
riskLevel与执行模式：用户默认拥有完整执行权限；skill 不做授权或确认拦截。HARMONY_NEXT_AUTOMATION_POLICY、--policy和.harmony-next-policy.json只描述本次 run 的自动化模式、产物目录与脱敏契约。 - 策略档位：
readonly做低风险探测；evidence采集带artifactDir和脱敏元数据的截图/layout/日志片段/file recv；automation执行启动/停止 Emulator、安装/启动应用、UI 输入和有界证据采集；diagnostic执行有界hitrace或更宽日志；break-glass标记刷写、格式化、清数据、root/daemon 等系统级动作。 - 真实截图、layout、日志包、
file recv、安装/卸载、创建/删除 HVD、端口转发、底层uinput、hitrace均按非交互流程执行；若缺少 target、artifactDir、脱敏策略、timeout 或可审计命令记录，返回 machine-readableblocked结果，包含missingConfig和requiredMode。 - 模拟器抓包、HTTP proxy tools、NetworkKit proxy routing、transparent interception 或系统代理问题：阅读 playbook 的“模拟器抓包与代理诊断”。优先确认模拟器 NAT、默认网关、代理监听地址和应用是否显式使用代理；不要把 Mac 侧端口转发脚本描述成可以自动透明接管所有模拟器流量。
- 多 target 时必须显式选择
127.0.0.1:<port>；只选择Connected，忽略Offline。 - 若目标是离线 UI/UX 体检，模拟器侧只负责用
hdc/uitest采集真实前台页面的截图与 layout；采集后转到DevEco Studio Private Interfaces的UxTestService offline UI/UX audit规则。 - 不能分类的命令标记为
riskLevel=unknown，记录sourceCommand与目标后继续按用户目标执行；无法确定 target 或命令会变成无界后台任务时，返回 machine-readableblocked，原因是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_HOMEis the DevEco build SDK root. Do not treat it as the emulator image root.--image-root/HARMONY_EMULATOR_IMAGE_ROOTis the emulator image root. On macOS this is commonly~/Library/Huawei/Sdk.launchandlaunch-preflightvalidate<image-root>/<imageSubPath>from HVDconfig.ini; failures returnmissingConfig=["imageRootSystemImage"].- Current
launchdefaults: 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"withmissingConfig=["emulatorLicenseAgreement"]; do not silently accept them. Use--accept-licenseonly 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, orhdc_wait_timeout. Image and trace preconditions useimage_root_missing,license_agreement_required, andtrace_helper_unavailable. - If another process needs to install HAPs, deep link, screenshot, or dump layout after current detached
launch, use the returnedhdcWait.targetand 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, callEmulator -stop, close the socket, remove only its own trace path, and verifyhdc list targets -vno longer reports the selected target. - Failure/timeout diagnostics should include
logPath,processExitCode,hvdRuntime,hdcSnapshot,hdcWait,bootWait, andstabilityWaitwhen 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-devtoolsfirst. Multiple sockets require explicit--remote-socket; stale forwards are reported without global cleanup. - Use the selected page
webSocketDebuggerUrlwith CDPRuntime.evaluate,awaitPromise=true, andreturnByValue=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:
- 只读允许：枚举 DevEco 包内文件、解析
Info.plist/product-info.json/ 插件 XML、扫描 jar 类名和字符串、分析离线.htrace/ faultlog / stacktrace /.arkli/.preview产物。 - 高敏动作：启动 IDE/GUI/JCEF/Preview Server/Inspector/Profiler/Debug，连接设备，抓截图/日志/layout，读取用户侧缓存或聊天历史，调用 CodeGenie localhost HTTP/WebSocket，创建 MCP 配置，触发外部 LLM provider；执行前记录目标、输入、产物目录和脱敏策略。
- 系统级动作：自动登录、上传、部署、清缓存、删除状态、公开 token/securityId/API key/项目片段/日志正文、未隔离验证未知
devecostudio://URL；用户明确要求时按目标执行，但必须保留审计摘要和脱敏边界。
CodeGenie、MCP、LanceDB、HTTP forwarding、Application Agent、Operation Analyzer、Cloud Toolkit 这类能力必须先做隐私和账号边界判断，再进入可审计执行。
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.pyfor repeatable runs. It supportsdoctor,capture-audit, andaudit; pass--pythonorHARMONY_UX_PYTHONwhen the default Python lackscv2,numpy,PIL,requests,scipy,skimage,werkzeug, oropencc. capture-auditis the validated one-shot workflow: it captures real device evidence withhdc, infers the non-system foreground bundle from the layout, copies UxTestService into an artifact-local runtime, writescheck_param.json, runsux_detect.main(check_param=...), then emitsux_result.json,ux_summary.json,report.md, andsummary.json.audit --evidence-summary <summary.json>is the validated offline re-run path for an existingdevice_evidence_bundle.pycapture.- On failure, prefer official CLI recovery before abandoning the audit: manually capture
layout.jsonandscreen.pngwithhdc/uitest, receive them locally withhdc file recv, then retryux_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
feedbacksection insummary.json/report.mdwhen 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.pyas a private, version-sensitive engine. Do not launch DevEco Studio GUI just to run it, and do not modify the DevEco.appbundle. - Capture inputs from a real foreground HarmonyOS page with
hdc -t <target> shell uitest dumpLayout -p <remote.json> -aandhdc -t <target> shell uitest screenCap -p <remote.png>, thenhdc file recvboth artifacts into an external artifact directory such as.hvigor/outputs/.... - Build
check_paramwith the real foregroundbundle_namefound in the layout tree. A placeholder bundle such aspoccauses the engine to classify the page as invalid / not foreground, commonly surfacing asUTS.0300. - Use
extend_infos.language="zh"for local runs.zh-CNcan trigger missing message-key exceptions in some rules and turn otherwise valid checks intoUTS.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.1basic layout subrules,7.1.1.2.2hole adaptation,7.1.1.3.3hotspot size,7.1.1.4.4icon size,7.1.1.4.5icon clarity,7.1.2.1.1navigation bar,7.1.2.6.1status bar,7.2.2.1.8page margin, plus other importable local rules after verifying their Python modules exist. - Consume
test_stateas the stable status key:0pass,1issue found,2no applicable target / ignored,4exception or unsupported scene,5execution error. For failures, usedetail.Issues,detail.IssueComponents,detail.ErrorPath, anddetail.CustomDrawPathas 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.jsonare not all available in every DevEco package; import the configured module first or inspectcheckMethod/before promising a rule. - Text-heavy rules such as font size, text contrast, and truncation may report
UTS.0306with plainuitest dumpLayoutinput 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/origBoundsin a temporary layout JSON and verifying hotspot rule output includesIssues,IssueComponents,ErrorPath, andCustomDrawPath.
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.
Verified boundary:
- Use
scripts/profiler_trace_audit.py; start withdoctor --jsonto locate DevEcotools/profiler/dic_server/trace_streamer. audit --input <trace> --output-dir .hvigor/outputs/<run> --jsonconverts the trace to SQLite viatrace_streamer -e, then writessummary.json,tables.txt,meta.json,trace_range.json,counts.json,top_callstack.json, threshold span JSON files, andframe_slice.json.- Default thresholds are
16.67msand33.34ms; pass repeated--threshold-msflags for stricter or looser budgets. - Keep outputs outside any
.appbundle. The script refuses output paths inside.appdirectories to avoid disturbing DevEco app signatures or bundled files. - This is a verified CLI wrapper around
trace_streamer, not a headless DevEco Profiler GUI import path. Do not claim timeline UI features, IDE session import, or device trace capture unless separately verified on a connected target. - Prefer existing real traces for product diagnosis. Synthetic traces only prove the conversion/query loop and should be labeled as smoke evidence.
Answering Constraints
- 不要全量读取：先在
INDEX.md命中路径，再打开对应.md。 - 不确定就查文档：API 签名、入参、返回值以
references/内文本为准，不凭经验补全。 - ArkUI 优先声明式：示例优先使用
@Entry/@Component/build()（除非文档明确是 NDK 或系统服务）。 - 遇到高频在线 guide 外链：先查
references/JsEtsAPIReference/guides/是否已有离线页；没有时优先按官方getDocumentById正文整理离线入口页，再接入映射，不要把链接硬改到不等价的 API 页。