harmony-next

name harmony-next description Use for HarmonyOS NEXT development help and local DevEco automation. Covers ArkTS/ArkUI/NDK API lookup, offline guide navigation, DevEco Studio and HarmonyOS Emulator tasks, hdc/uitest/aa/bm/hilog/hidumper diagnostics, ArkWeb/WebView DevTools and CDP evidence, and private DevEco interfaces such as CodeGenie, MCP, LanceDB, devecostudio://, ArkUI Inspector, Previewer, Profiler, Doctor, and UxTestService offline UI/UX audits. metadata {"version":"1.3.35"} 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 --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 导航： references/KITS.md 任务导向： references/TASK_MAP.md 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.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. 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: 优先使用只读探测： 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-readable blocked 结果，包含 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-readable blocked ，原因是 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