OpenHarmony HDC Skill

This skill provides capabilities for OpenHarmony ecosystem devices via HDC (the hdc host tool: the standard device bridge for OHOS in the OpenHarmony / DevEco SDK): list installed HAP apps, uninstall HAP, install HAP, install-project (install main + test HAP with two hdc install commands), deploy-test (部署运行 HAP 测试用例：卸载后以 hdc install -r 安装主包与测试包，再在设备 shell 执行应用测试流水线), replace-install HAP, display screenshot (snapshotdisplay + hdc file recv，默认保存到技能目录 screenshot/), app-scoped screenshot (screenshot-app / snap-app: 设备侧拉起应用别名后执行 snapshotdisplay; 预设别名见 ohhdc.py 中 SCREENSHOTAPPALIASES), UI layout JSON (uitest dumpLayout + hdc file recv，默认保存到 layout/), Wi‑Fi via wificommand (wifi-kaihong: enable Wi‑Fi and connect default KaiHong / env OHHDCWIFIPSK or custom --wifi-ssid / --wifi-password), control LEDs (/sys/class/leds/{red,green,blue}/brightness), view device logs (hilog), view error/fault logs (data/log/faultlog), view foreground/running applications, force-stop applications, start applications, and run tests.

应用示例与提示词（中文）

在 napi_generator 仓库根 执行；需 hdc 在 PATH、设备已连接。

Query Installed Apps

Feature Description

List device-installed HAP applications. The skill runs hdc shell "bm dump -a" to get all installed bundle names (HAP apps) from the connected device, then formats the output as Markdown for easy reading.

When to Use

• User asks: "查看设备上安装的 HAP" / "查看设备安装的 app" / "设备上装了多少 hap"
• User asks: "List installed apps on device" / "Show device HAP apps" / "How many apps are installed"
• User needs to inspect or count installed applications on an OpenHarmony-compatible device

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell 'bm dump -a'" (so hdc is in PATH from bashrc)
2. Parse output: skip ID: lines, strip leading tabs/spaces, extract bundle names (lines containing . or starting with ohos.)
3. Deduplicate and format as Markdown: table + bullet list

Usage in Conversation

Natural language examples:

• "查看设备上安装的 HAP"
• "查看设备安装的 app"
• "设备上装了多少 hap"
• "List installed apps on the device"
• "Show me the installed HAP apps"

The assistant uses this skill to run the script and show the result in Markdown.

Quick Start – Using the Script

# From project root; ensure hdc is available (e.g. source ~/.bashrc in your shell first)

# List installed apps, Markdown format (default)
python3 src/skills/ohhdc/ohhdc.py apps

# Same, explicit format
python3 src/skills/ohhdc/ohhdc.py list-apps --format markdown

# Plain text list
python3 src/skills/ohhdc/ohhdc.py apps --format plain

Available commands:

• apps / list-apps – List installed HAP apps (bundle names).
• --format markdown or --format md – Output as Markdown (default).
• --format plain or --format list – Output as plain text list.

Uninstall HAP

Feature Description

Uninstall a HAP from the device by bundle name. Uses: hdc shell "bm uninstall -n <bundleName>".

When to Use

• User says: "卸载设备上的 xxx 应用" / "卸载 com.example.p7zipTest" / "uninstall HAP com.xxx.xxx"
• User needs to remove a specific app by its bundle name.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell \"bm uninstall -n <bundleName>\""
2. Print success or error.

Usage in Conversation

• "卸载 com.example.p7zipTest"
• "Uninstall the app com.example.p7zipTest from the device"

Quick Start – Script

# Uninstall by bundle name (required)
python3 src/skills/ohhdc/ohhdc.py uninstall com.example.p7zipTest

Parameter: target = bundle name (e.g. com.example.p7zipTest).

Install HAP

Feature Description

Install a HAP file onto the device. Uses: hdc install <hap_path>.

When to Use

• User says: "安装这个 HAP 到设备" / "把 xxx.hap 装到设备" / "install HAP /path/to/app.hap"
• User provides a HAP file path and wants to install it.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc install <hap_path>"
2. Path is quoted so spaces are safe.
3. Print success or error.

Usage in Conversation

• "安装 src/skills/ohhap/NativeProj46R/autosign/app1-signed.hap"（假定当前目录为 napi_generator 仓库根）
• "Install the HAP at .../app1-signed.hap to the device"

Quick Start – Script

# Install HAP（在 napi_generator 仓库根下；也可用 .hap 的完整路径）
python3 src/skills/ohhdc/ohhdc.py install src/skills/ohhap/NativeProj46R/autosign/app1-signed.hap

Parameter: target = absolute or relative path to the .hap file.

Install Project (主 HAP + 测试 HAP，推荐)

Feature Description

按项目安装两个 HAP：先安装主 HAP，再安装测试 HAP，均使用 hdc install（不用 -r）。 等价于依次执行：

• hdc install <project_dir>/entry/build/default/outputs/default/entry-default-signed.hap
• hdc install <project_dir>/entry/build/default/outputs/ohosTest/entry-ohosTest-signed.hap

安装前如设备上已有同包名应用且签名不一致，需先卸载再执行本安装。

When to Use

• User says: "安装这个项目的两个 HAP" / "按项目安装 NativeProj46R" / "install project"
• 签名、编译完成后，需要将主 HAP 与测试 HAP 部署到设备。

Quick Start – Script

# 按项目安装（target = 项目根目录；示例为仓库内 examples/NativeProj46R）
python3 src/skills/ohhdc/ohhdc.py install-project examples/NativeProj46R

或手动执行两个命令：

hdc install examples/NativeProj46R/entry/build/default/outputs/default/entry-default-signed.hap
hdc install examples/NativeProj46R/entry/build/default/outputs/ohosTest/entry-ohosTest-signed.hap

Parameter: target = 项目根目录（含 entry/build/... 的上级目录）。

部署运行 HAP 测试用例（deploy-test）

Feature Description

部署并运行 HAP 测试用例：依次执行「卸载同包名应用 → 使用 hdc install -r 安装主 HAP → 使用 hdc install -r 安装测试 HAP → 经 hdc shell 在设备上执行 应用测试 子流程（与 OpenHarmony 设备侧命令行工具一致，由本仓库 ohhdc.py 拼出参数）。 等价于历史记录中的完整流程：先卸载，再两条 hdc install -r，最后在设备 shell 内对主/测包执行带 -s class、-s timeout、-m entry_test、-s unittest 等参数的应用测试命令。

• 包名（bundleName）未指定时，从项目 AppScope/app.json5 解析。
• 主 HAP、测试 HAP 路径约定与 install-project 相同。
• 测试套件自动发现：未通过 --suite 指定时，从项目 entry/src/ohosTest/ets/test/List.test.ets 解析调用的测试函数（如 abilityTest()、indexUitestTest()），再在各对应 .test.ets 文件中读取 describe('SuiteName', ...) 的 SuiteName，按 List 中的顺序拼成 -s class ActsAbilityTest,IndexUitestTest,IndexdtsTest 等形式；解析失败时回退为 ActsAbilityTest,IndexUitestTest。

When to Use

• User says: "部署运行 HAP 测试用例" / "卸载后安装两个 HAP 再跑测试" / "deploy and run HAP tests"
• 需要一键完成：卸载 → 安装主 HAP + 测试 HAP → 运行测试。

Quick Start – Script

# 部署运行测试（target = 项目根目录；测试套件从 List.test.ets 自动发现，默认 -m entry_test -t 15000）
python3 src/skills/ohhdc/ohhdc.py deploy-test examples/NativeProj46R

# 指定测试套件与超时（覆盖自动发现）
python3 src/skills/ohhdc/ohhdc.py deploy-test /path/to/NativeProj46R --suite "ActsAbilityTest,IndexUitestTest" --timeout 20000

Parameters: target = 项目根目录；--module / -m = 测试模块名（默认 entry_test）；--suite / -s = -s class 的取值，多个套件逗号分隔（不指定时从 List.test.ets 及各 .test.ets 的 describe 名自动发现）；--timeout / -t = 超时毫秒（默认 15000）。

工程整测硬门禁（Agent 必遵；动态 / 静态 / CAPI 共用）

允许：-s A,B,C 时本脚本内部分次 设备 unittest（避免多 class 拼参挂起）——仍属一次装包连跑。 禁止：Agent 外层循环多次调用本命令（每次重装）再拼绿。详见 ohos-gate-compliance「设备整测硬门禁」与「改码后强制重编」。

装包：hdc install / -r（勿对 release 包加 -g，否则 9568450）。受限权限靠签名 profile ACL。 deploy 前自动：wakeup / setmode 602 / timeout -o 999999 / 上滑解锁 / killall uitest。

装包错误码速查

特权 Extension 白名单（9568344 / allowAppUsePrivilegeExtension）

BMS 对 ServiceExtension / DataExtension 等特权能力，不能只靠签名证书特权字段；须在设备 /system/etc/app/installlistcapability.json（部分机型也可能在 /system/variant/phone/base/etc/app/）为该 bundleName 配置：

{
  "bundleName": "com.acts.accountauthenticator",
  "app_signature": ["D729F438E1EF2E154994E2B077F6C0CD592BA9F9C938BB428FCDA564FF805EE4"],
  "allowAppUsePrivilegeExtension": true,
  "keepAlive": true
}

指纹必须用对（高频踩坑）：

• app_signature 比对的是签名 profile 内 bundle-info.distribution-certificate 的 SHA256（去冒号、大写），与 bm dump -n <bundle> 里已装应用的 fingerprint 一致。
• 不要用每次 generate-app-cert 产生的 叶子 app 证书指纹，也不要误以为只有 Root CA（9AED2A79…）即可；指纹不对时 hilog 常见：appSignature of signature is empty / signature verify failed in capability list，仍报 9568344。
• 取指纹示例：从工程 autosign/UnsgnedReleasedProfileTemplate.json（或等价 profile 模板）抽出 distribution-certificate → PEM →

openssl x509 -in dist.pem -noout -fingerprint -sha256 → 去掉 :。

改白名单步骤（服务器网联 hdc）：

hdc shell "mount -o rw,remount /"
# 拉改推（路径以设备实际为准）
hdc file recv /system/etc/app/install_list_capability.json ./
# 编辑后：
hdc file send ./install_list_capability.json /system/etc/app/install_list_capability.json
hdc shell "chmod 644 /system/etc/app/install_list_capability.json; sync"
hdc shell reboot
# 重启后必须亮屏保活（见下节），再 hdc install

备选（无法改板端白名单时）：XTS 可将 bundleName 改为以 com.acts. 开头，并在签名 profile 中申请对应特权；仍失败则回到白名单方案。

重启后亮屏保活（Agent 必遵）

凡 hdc shell reboot（或等价重启）之后、装包 / 设备 unittest / 截屏之前，设备重新 tconn 可达后立刻执行：

hdc shell "power-shell wakeup"
hdc shell "power-shell setmode 602"
hdc shell "power-shell timeout -o 999999"

仅 setmode 602 不够：部分镜像（已在 API26 / OH 7.0 上复现）powermodeconfig.xml 里 602 的息屏虽为 -1，但 hidumper 仍显示 ScreenOffTime: Timeout=30000ms，屏幕约 30s 仍灭。必须再 power-shell timeout -o 999999，使 OverrideTimeout=999999ms。timeout -o -1 在部分机上会失败，优先用 999999。

校验：hdc shell "hidumper -s PowerManagerService -a '-a'" 中应见 OverrideTimeout=999999ms。

deploy-test / static-deploy-test 已含上述三连；手工 reboot 后不会自动执行，Agent 必须补跑。恢复默认息屏：power-shell timeout -r。

静态 XTS：仅主包 + unittest TestRunner（static-deploy-test）

Feature Description

ArkTS use static + Hypium 一体工程常见形态：无独立 ohosTest HAP，测试入口为 主模块 内的 OpenHarmonyTestRunner。设备侧推荐与文档一致：

设备侧完整命令与上游文档一致：-s timeout 写在 -s unittest（Runner 多为类名 OpenHarmonyTestRunner）之前。

（Runner 优先用类名；仅在设备要求时使用 /ets/testrunner/... 路径形式。）

本动作依次：卸载同包名 → hdc install -r 仅主包 entry-default-signed.hap → 执行上述形态的应用测试命令。与 deploy-test（双 HAP + -s class）互斥，请按工程类型选用。

工程整测同样遵守上文 「工程整测硬门禁」：全部 Suite 一次 static-deploy-test 连跑，禁止多次重装拼绿。

Quick Start – Script

python3 src/skills/ohhdc/ohhdc.py static-deploy-test /path/to/static_xts_project
export OHOS_A​A_TEST_TIMEOUT_MS=600000
python3 src/skills/ohhdc/ohhdc.py static-deploy-test /path/to/project --timeout 600000 -m entry --unittest-runner OpenHarmonyTestRunner
# 本机等待设备应用测试结束的墙钟（秒）：默认至少约 30 分钟；套件很大时可增大
export OHOS_A​A_TEST_WALL_SEC=7200
python3 src/skills/ohhdc/ohhdc.py static-deploy-test /path/to/project

说明：--timeout 传给设备的 -s timeout（毫秒）；子进程最长等待由 OHOSA​ATESTWALLSEC 控制（未设时默认 ≥1800s），与设备参数不是同一含义。框架单测超时还可设 OHOSA​ATESTTIMEOUTMS（覆盖 -s timeout 毫秒值，整包 Hypium 建议 ≥ 300000）。

「测试没跑起来」常见原因（非等待时间）：

1. -s unittest 取值：官方文档要求多为 类名 OpenHarmonyTestRunner，不是路径 /ets/testrunner/...；脚本默认已改为类名，路径可通过 OHOSA​ATESTUNITTESTRUNNER 或 --unittest-runner 指定。
2. 参数顺序：文档示例为 -s timeout <ms> -s unittest <runner>，顺序与部分环境解析有关，脚本已按此排列。
3. Release 签名：部分设备上 release 签名的 HAP 无法执行应用测试子命令（错误码 10106002），需使用 debug 包 或符合设备策略的签名。

日志为何常「看不到」：Hypium 大量输出在设备 hilog，应用测试子进程回传到本机终端的 stdout 可能很少；超时场景下旧实现还曾丢弃子进程已有片段。现支持：合并 stderr、超时保留已捕获片段、OHOSA​ATESTLOGFILE 用 tee 落盘。

应用测试执行过程中轮询 hilog：自应用测试子进程启动起，后台线程按间隔（OHOSA​ATESTHILOGPOLLSEC，默认 3s）短采 hilog（单次时长 OHOSA​ATESTHILOGSLICESEC，默认 5s），拼在 标准输出之前，便于看「跑的过程中」哪一步出错。OHOSA​ATESTSKIPHILOGDURING=1 可关；OHOSA​ATESTSKIP_HILOG=1 会同时关闭「过程中」与「结束后」两段自动 hilog。

应用测试结束后自动抓 hilog：返回前再调用 capturehilogafterapptest（约 20s 一段）。可调 OHOSA​ATESTHILOGSEC、OHOSA​ATESTHILOGGREP（与过程中共用同一 grep 变量）。

Replace Install HAP

Feature Description

Replace-install a HAP (overwrite existing app with same bundle name). Uses: hdc -r install <hap_path>.

When to Use

• User says: "替换安装这个 HAP" / "覆盖安装 xxx.hap" / "replace install /path/to/app.hap"
• User wants to update an already installed app by reinstalling the HAP.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc -r install <hap_path>"
2. Path is quoted so spaces are safe.
3. Print success or error.

Usage in Conversation

• "替换安装 src/skills/ohhap/NativeProj46R/autosign/app1-signed.hap"（假定当前目录为 napi_generator 仓库根）
• "Replace-install the HAP at .../app1-signed.hap"

Quick Start – Script

# Replace-install HAP（在 napi_generator 仓库根下；也可用 .hap 的完整路径）
python3 src/skills/ohhdc/ohhdc.py replace-install src/skills/ohhap/NativeProj46R/autosign/app1-signed.hap

Parameter: target = absolute or relative path to the .hap file.

View Device Logs (hilog)

Feature Description

View device hilog output from the connected device. The skill runs hdc shell hilog to stream log output. Optional behavior:

• Debug level: hdc shell hilog -b D – show debug-level logs.
• Show private info: hdc shell hilog -p off – turn off filtering of private information.
• Disable flow control: hdc shell param set hilog.flowctrl.proc.on false – run once before hilog to reduce dropped logs.
• Filter by keyword or PID: hdc shell hilog | grep <pattern> – filter on the host (e.g. grep BMS for keyword "BMS", or grep by process tag/pid). The filter can be a keyword or a PID.

Because hilog streams continuously, the skill captures output for a configurable number of seconds (default 15), then stops.

When to Use

• User asks: "查看设备日志" / "抓一下设备 hilog" / "看下 debug 级别日志" / "用 grep 过滤 BMS 相关日志"
• User asks: "View device logs" / "Show hilog from device" / "Capture debug-level hilog" / "Filter hilog by keyword"
• User needs to debug or inspect runtime logs on the device

How It Works

1. Optionally run: hdc shell "param set hilog.flowctrl.proc.on false" when --flowctrl-off is set.
2. Build hilog command: hdc shell "hilog [-b D] [-p off]" according to --level and --private-off.
3. Run with timeout <N> so capture ends after N seconds; if --grep or positional filter is given, pipe output through grep --line-buffered <pattern> on the host.
4. Print captured stdout (and stderr when relevant).

Usage in Conversation

• "查看设备日志"
• "抓 20 秒设备 hilog，用 debug 级别"
• "关闭 private 屏蔽并查看 hilog"
• "查看设备日志，只显示包含 BMS 的行"
• "View device hilog with debug level"
• "Filter device logs by keyword testTag"

Quick Start – Script

# 查看设备日志（默认采集 15 秒）
python3 src/skills/ohhdc/ohhdc.py hilog
python3 src/skills/ohhdc/ohhdc.py logs

# Debug 级别
python3 src/skills/ohhdc/ohhdc.py hilog --level D
python3 src/skills/ohhdc/ohhdc.py hilog -b D

# 关闭对 private 信息的屏蔽
python3 src/skills/ohhdc/ohhdc.py hilog --private-off
python3 src/skills/ohhdc/ohhdc.py hilog -p

# 先关闭 hilog 流量控制再抓日志
python3 src/skills/ohhdc/ohhdc.py hilog --flowctrl-off
python3 src/skills/ohhdc/ohhdc.py hilog -f

# 按关键字或 pid 过滤（BMS 为示例，可为任意关键字或 pid）
python3 src/skills/ohhdc/ohhdc.py hilog BMS
python3 src/skills/ohhdc/ohhdc.py hilog --grep testTag
python3 src/skills/ohhdc/ohhdc.py hilog -g 12345

# 组合：debug 级别 + 关闭 private 屏蔽 + 过滤 BMS + 采集 30 秒
python3 src/skills/ohhdc/ohhdc.py hilog BMS -b D -p -f --hilog-timeout 30

Parameters:

• hilog / logs – View device hilog (stream captured for a limited time).
• target (positional) – Optional filter pattern for grep (e.g. ohhdc.py hilog BMS).
• --level / -b – Log level (e.g. D for debug).
• --private-off / -p – Use hilog -p off to show private info.
• --flowctrl-off / -f – Run param set hilog.flowctrl.proc.on false before hilog.
• --grep / -g – Filter lines by keyword or pid (grep on host).
• --hilog-timeout – Capture duration in seconds (default 15).

View Error / Fault Logs (faultlog)

Feature Description

View device error/fault logs under /data/log/faultlog. The directory contains four subdirectories for analysis:

• faultlogger – fault logger 相关日志
• freeze – 卡死/冻结类日志
• hilog – 持久化 hilog 错误日志
• temp – 临时错误日志

The skill runs hdc shell "ls -la /data/log/faultlog" (or a subdir) to list files, and hdc shell "cat <path>" (or tail -n N) to read file content. Use this to analyze crash/freeze/error logs on the device.

When to Use

• User asks: "查看设备错误日志" / "data/log/faultlog 下有什么" / "看下 faultlogger 目录" / "读取 hilog 错误日志文件"
• User asks: "View device fault log" / "List error log directory" / "Analyze faultlog content"
• User needs to debug crashes, freezes, or errors using faultlog/faultlogger/freeze/hilog/temp

How It Works

1. List: Run hdc shell "ls -la /data/log/faultlog" or ls -la /data/log/faultlog/<subdir> (subdir: faultlogger, freeze, hilog, temp).
2. Read: Run hdc shell "cat /data/log/faultlog/<relpath>" (or tail -n N when --tail is set). relpath is relative to faultlog (e.g. hilog/xxx.log).
3. Print output for user to analyze.

Usage in Conversation

• "查看设备错误日志目录"
• "列出 data/log/faultlog 下的 faultlogger"
• "读取 faultlog 里 hilog 目录下的某个日志文件"
• "View faultlog directory" / "Show last 100 lines of faultlogger log file"

Quick Start – Script

# 列出 /data/log/faultlog 根目录
python3 src/skills/ohhdc/ohhdc.py faultlog
python3 src/skills/ohhdc/ohhdc.py error-log

# 列出子目录（faultlogger / freeze / hilog / temp）
python3 src/skills/ohhdc/ohhdc.py faultlog faultlogger
python3 src/skills/ohhdc/ohhdc.py faultlog hilog
python3 src/skills/ohhdc/ohhdc.py faultlog freeze
python3 src/skills/ohhdc/ohhdc.py faultlog temp

# 读取某文件内容（相对 data/log/faultlog 的路径）
python3 src/skills/ohhdc/ohhdc.py faultlog --cat hilog/2024-01-01-12.log
python3 src/skills/ohhdc/ohhdc.py faultlog --cat faultlogger/xxx

# 只读最后 N 行
python3 src/skills/ohhdc/ohhdc.py faultlog --cat hilog/xxx.log --tail 100

Parameters:

• faultlog / error-log – List or read error/fault logs under /data/log/faultlog.
• target (positional) – Optional subdir: faultlogger, freeze, hilog, or temp (list that subdir).
• --cat – Read file content; path is relative to /data/log/faultlog (e.g. hilog/xxx.log).
• --tail – When used with --cat, output only the last N lines of the file.

View Foreground/Running Apps

Feature Description

View foreground applications and running app processes on the device. Uses:

• hdc shell "a​a dump -a" - View all abilities (foreground and background)
• hdc shell "a​a dump -r" - View running abilities (app processes)

Extracts key information: bundle name, ability name, ability type, app state (FOREGROUND/BACKGROUND), start time, AbilityRecord ID, and running app processes (process name, PID, UID, state).

When to Use

• User says: "查看前台应用" / "查看正在运行的应用" / "查看设备上的前台应用"
• User says: "Show foreground apps" / "View running applications" / "What apps are running"
• User needs to inspect which apps are currently active on the device

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell \"a​a dump -a\"" (or a​a dump -r for running only)
2. Parse output: extract AbilityRecord info (bundle name, ability type, app state, etc.) and AppRunningRecords (process info)
3. Format as Markdown: show foreground apps table and running app processes table

Usage in Conversation

• "查看前台应用"
• "查看正在运行的应用"
• "设备上哪些应用在前台"
• "Show foreground apps on the device"
• "View running applications"

Quick Start – Script

# View foreground apps (default: shows foreground + running processes)
python3 src/skills/ohhdc/ohhdc.py foreground

# Same, short form
python3 src/skills/ohhdc/ohhdc.py fg

# View all abilities (including background)
python3 src/skills/ohhdc/ohhdc.py dump-all

# View running abilities only
python3 src/skills/ohhdc/ohhdc.py running
python3 src/skills/ohhdc/ohhdc.py dump-running

Available commands:

• foreground / fg – View foreground apps and running processes (default view)
• dump-all – View all abilities including background ones
• running / dump-running – View running abilities/app processes only

Output includes:

• Foreground Apps Table: Bundle Name, Ability Name, Type, State, AbilityRecord ID, Start Time
• Running App Processes Table: Process Name, PID, UID, State

Force Stop Application

Feature Description

Force-stop an application by bundle name. Uses: hdc shell "a​a force-stop <bundleName>".

When to Use

• User says: "强制关闭 xxx 应用" / "关闭 com.ohos.settings" / "force stop app com.xxx.xxx"
• User needs to forcefully terminate a running application on the device.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell \"a​a force-stop <bundleName>\""
2. Print success or error.

Usage in Conversation

• "强制关闭 com.ohos.settings"
• "关闭设置应用"
• "Force stop the app com.ohos.settings"

Quick Start – Script

# Force-stop by bundle name (required)
python3 src/skills/ohhdc/ohhdc.py force-stop com.ohos.settings

# Same, short form
python3 src/skills/ohhdc/ohhdc.py stop com.ohos.settings

Parameter: target = bundle name (e.g. com.ohos.settings).

Start Application

Feature Description

Start an application by bundle name and ability name. Uses: hdc shell "a​a start -a <abilityName> -b <bundleName>".

When to Use

• User says: "启动 xxx 应用" / "打开 com.ohos.settings" / "start app com.xxx.xxx"
• User needs to launch an application on the device.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell \"a​a start -a <abilityName> -b <bundleName>\""
2. Print success or error.

Usage in Conversation

• "启动 com.ohos.settings 应用"
• "打开设置应用，使用 EntryAbility"
• "Start the app com.ohos.settings with EntryAbility"

Quick Start – Script

# Start app (requires bundleName and ability name)
python3 src/skills/ohhdc/ohhdc.py start com.ohos.settings --ability EntryAbility

# Same, using short form
python3 src/skills/ohhdc/ohhdc.py start com.ohos.settings -a EntryAbility

Parameters:

• target = bundle name (e.g. com.ohos.settings)
• --ability / -a = ability name (e.g. EntryAbility)

Note: Common ability names include:

• EntryAbility - Main entry ability
• com.ohos.settings.MainAbility - Settings main ability
• Check installed apps or use a​a dump -a to find ability names

Run Tests

Feature Description

Run test cases for an application. Uses: hdc shell "a​a test -b <bundleName> -m <moduleName> -s unittest OpenHarmonyTestRunner -s class <suiteName>[#<caseName>] -s timeout <timeout>".

Supports:

• Run specific test case: Provide suite name and case name (e.g., ActsAbilityTest#assertContain)
• Run full test suite: Provide only suite name (e.g., ActsAbilityTest)

When to Use

• User says: "运行测试" / "执行测试用例" / "运行 ohos.test.nativeproj46r 的测试"
• User says: "Run tests for app" / "Execute test case" / "Run ActsAbilityTest#assertContain"
• User needs to run unit tests or specific test cases on the device.

How It Works

1. Execute: bash -c "source ~/.bashrc && hdc shell \"a​a test -b <bundleName> -m <moduleName> -s unittest OpenHarmonyTestRunner -s class <suiteName>[#<caseName>] -s timeout <timeout>\""
2. If caseName is provided, runs specific test case: suiteName#caseName
3. If caseName is not provided, runs full test suite: suiteName
4. Print test execution results.

Usage in Conversation

• "运行 ohos.test.nativeproj46r 的测试"
• "执行 ActsAbilityTest#assertContain 测试用例"
• "运行 entry_test 模块的全量测试"
• "Run tests for ohos.test.nativeproj46r"
• "Execute test case ActsAbilityTest#assertContain"

Quick Start – Script

# Run specific test case
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  --module entry_test \
  --suite ActsAbilityTest \
  --case assertContain \
  --timeout 15000

# Run full test suite (omit --case)
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  --module entry_test \
  --suite ActsAbilityTest \
  --timeout 15000

# Using short form
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  -m entry_test \
  -s ActsAbilityTest \
  -c assertContain \
  -t 15000

Parameters:

• target = bundle name (e.g. ohos.test.nativeproj46r) - required
• --module / -m = module name (e.g. entry_test) - required
• --suite / -s = test suite name (e.g. ActsAbilityTest) - required
• --case / -c = test case name (e.g. assertContain) - optional, if provided runs specific case, otherwise runs full suite
• --timeout / -t = timeout in milliseconds (default: 15000) - optional

Examples:

# Run specific test case
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  -m entry_test -s ActsAbilityTest -c assertContain

# Run full test suite
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  -m entry_test -s ActsAbilityTest

# With custom timeout (30 seconds)
python3 src/skills/ohhdc/ohhdc.py test ohos.test.nativeproj46r \
  -m entry_test -s ActsAbilityTest -t 30000

屏幕截图（snapshot_display + file recv）

Feature Description

1. 在设备上执行 snapshotdisplay，通过 -f 将图片写到固定路径（默认 /data/local/tmp/ohhdcscreenshot.jpeg，须在 /data/local/tmp 下且扩展名为 .jpeg / .png，与系统工具校验一致）。
2. 使用 hdc file recv <设备路径> <本机路径> 将文件拉到本地。
3. 本机默认目录：src/skills/ohhdc/screenshot/（仅文件名或省略路径时自动写入该目录；写完整路径则按指定位置保存）。

注意：snapshot_display 在源码中要求设备处于开发者模式，否则会提示 not developer mode 并退出。

实现与 windowId 说明：-i / --display-id 为 DisplayId（整屏/某块屏），不是 windowId；按窗口截图需见设计文档 [docs/snapshotdisplaydesign.md](docs/snapshotdisplaydesign.md)（含 layout bounds + 裁剪等可行路径）。

Quick Start – Script

# 默认：src/skills/ohhdc/screenshot/ohhdc_screenshot_YYYYMMDD_HHMMSS.jpeg
python3 src/skills/ohhdc/ohhdc.py screenshot

# 与 screenshot 等价
python3 src/skills/ohhdc/ohhdc.py snapshot

# 仅指定文件名 → 仍保存在 screenshot/ 下
python3 src/skills/ohhdc/ohhdc.py screenshot my.jpeg

# 任意本机完整路径
python3 src/skills/ohhdc/ohhdc.py screenshot /tmp/screen.jpeg

# 指定显示 ID（多屏）
python3 src/skills/ohhdc/ohhdc.py screenshot --display-id 0

# 指定设备端路径（需仍满足 snapshot 路径/后缀规则）
python3 src/skills/ohhdc/ohhdc.py snapshot --device-file /data/local/tmp/my.jpeg

Usage in Conversation

• “截个图保存到桌面” → ohhdc.py screenshot ~/Desktop/screen.jpeg
• “用 hdc 抓屏” → ohhdc.py snapshot

指定应用截图（screenshot-app / snap-app）

Feature Description

1. 根据 别名（ohhdc.py 中 SCREENSHOTAPPALIASES）或 完整包名 + --ability，在设备上执行 a​a start，等待界面就绪后执行 snapshot_display，再 hdc file recv 拉到本机。
2. 与 整屏截图 一致：仍是 Display 位图，不是按 windowId 单独出图；多窗同屏时其它窗口可能入镜。仅裁某一窗口需 layout bounds + 本机裁剪（见 [docs/snapshotdisplaydesign.md](docs/snapshotdisplaydesign.md)）。
3. 预设别名（可在 ohhdc.py 中扩展）：

非别名：ohhdc.py screenshot-app <bundleName> --ability <AbilityName>。

Quick Start – Script

# 预设别名：先启动 etsclock，约 2s 后整屏截图 → ohhdc/screenshot/screenshot_app_etsclock_*.jpeg
python3 src/skills/ohhdc/ohhdc.py screenshot-app etsclock

# 等价
python3 src/skills/ohhdc/ohhdc.py snap-app etsclock

# 指定本机保存路径（第二参数仅 screenshot-app 使用）
python3 src/skills/ohhdc/ohhdc.py screenshot-app etsclock ./clock.jpeg

# 完整包名 + Ability
python3 src/skills/ohhdc/ohhdc.py screenshot-app ohos.samples.etsclock -a MainAbility

# 多屏、启动后等待更久再截
python3 src/skills/ohhdc/ohhdc.py screenshot-app etsclock --display-id 0 --app-delay 3.5

Usage in Conversation

• “截一张 etsclock 的图” → ohhdc.py screenshot-app etsclock
• “先打开应用再截图” → ohhdc.py snap-app <别名> 或包名 + -a

扩展预设别名

编辑 src/skills/ohhdc/ohhdc.py 中 SCREENSHOTAPPALIASES，增加 "短名": ("完整包名", "默认主Ability")。

当前页面 layout（uitest dumpLayout + file recv）

Feature Description

1. 在设备上执行 hdc shell uitest dumpLayout -p <设备端路径>（与 arkxtest uitest 命令行一致），将当前界面控件树导出为 JSON。
2. 使用 hdc file recv 将 JSON 拉到本机；若内容为合法 JSON，脚本会缩进格式化后写回。
3. 本机默认目录：src/skills/ohhdc/layout/（默认文件名 uitestlayoutYYYYMMDD_HHMMSS.json）。

设备端默认路径：/data/local/tmp/ohhdcuitestlayout.json（可用 --device-file 修改）。

可选参数与 uitest dumpLayout 对应：--display-id（-d）、--bundle（-b）、--window-id（-w）、--layout-merge true|false（-m）、--layout-font（-a）、--layout-independent（-i）、--layout-extend（-e）。

Quick Start – Script

# 默认写入 src/skills/ohhdc/layout/uitest_layout_*.json
python3 src/skills/ohhdc/ohhdc.py layout

# 等价
python3 src/skills/ohhdc/ohhdc.py dump-layout

# 指定本机文件名（仍在 layout/ 目录）
python3 src/skills/ohhdc/ohhdc.py layout ui.json

# 指定包名窗口、显示 ID 等
python3 src/skills/ohhdc/ohhdc.py layout --bundle com.example.app --display-id 0

Usage in Conversation

• “导出当前页面布局 json” → ohhdc.py layout
• “把 uitest layout 存到项目里” → ohhdc.py layout /path/to/out.json

Wi‑Fi：wificommand 开网并连 KaiHong（wifi-kaihong）

Feature Description

使用 wificlitools 可执行文件 wificommand（源码 foundation/communication/wifi/wifi/test/wificlitools，GN 目标 wificommand）。通过 HDC 依次执行：

1. wifienable — 打开 Wi‑Fi
2. wificonnect ssid=<SSID> password=<口令> — 连接热点（默认 SSID KaiHong；口令默认读环境变量 OHHDCWIFIPSK，可用 --wifi-password 覆盖）
3. wifigetstatus — 打印状态（可用 --no-wifi-status 跳过）

设备侧整条命令经 shlex.quote 传给 hdc shell，避免主机对 @ 等字符误解析。

镜像里是否自带 wificommand？ wificlitools/BUILD.gn 中 ohosexecutable("wificommand") 未设置 installenable，且目标挂在 test/BUILD.gn 的 unittest 组，默认不会打进 system 分区。因此多数产品镜像 没有 /system/bin/wificommand。

处理方式：

1. 检查：ohhdc.py wifi-check-wificommand（设备 PATH、/system/bin、临时路径 + 本机 out/<product> 是否已有产物）。
2. 单独编译（在源码根）：./build.sh --product-name <产品> --build-target wificommand

产物常见路径：out/<产品>/communication/wifi/wificommand 或 out/<产品>/exe.unstripped/communication/wifi/wificommand。

1. 推送到设备：ohhdc.py wifi-push-wificommand（按 out 自动查找，或第一个参数传本机二进制完整路径），默认推到 /data/local/tmp/wificommand 并 chmod 755。
2. 一键推送并连 KaiHong：ohhdc.py wifi-kaihong --push-wificommand --ohos-src <源码根>（或设置 OHOS_SRC）。
3. 已手动推送时可用 --wifi-device-bin /data/local/tmp/wificommand 指定设备侧路径。

Quick Start – Script

# 先看设备上有没有、本机 out 里有没有编过
python3 src/skills/ohhdc/ohhdc.py wifi-check-wificommand --ohos-src /path/to/openharmony/src

# 仅推送 wificommand（从 out/<wifi-product> 自动查找）
python3 src/skills/ohhdc/ohhdc.py wifi-push-wificommand --ohos-src /path/to/src --wifi-product rk3568

# 指定本机二进制路径推送（第二个参数为可选 positional target）
python3 src/skills/ohhdc/ohhdc.py wifi-push-wificommand /path/to/out/rk3568/communication/wifi/wificommand

# 镜像无 wificommand 时：先推送再连 KaiHong（口令见 OHHDC_WIFI_PSK）
export OHOS_SRC=/path/to/src
export OHHDC_WIFI_PSK=your_psk_here
python3 src/skills/ohhdc/ohhdc.py wifi-kaihong --push-wificommand

# 已推到默认路径时，也可显式指定设备侧二进制
python3 src/skills/ohhdc/ohhdc.py wifi-kaihong --wifi-device-bin /data/local/tmp/wificommand

# 覆盖 SSID / 密码
python3 src/skills/ohhdc/ohhdc.py wifi-kaihong --wifi-ssid MyAP --wifi-password 'secret123'

python3 src/skills/ohhdc/ohhdc.py wifi-kaihong --no-wifi-status

Usage in Conversation

• “用 wificlitools 打开 WiFi 并连 KaiHong” → 先 wifi-check-wificommand；若无则 wifi-push-wificommand 或 wifi-kaihong --push-wificommand
• “连公司热点 MySSID 密码 xxx” → ohhdc.py wifi-kaihong --wifi-ssid MySSID --wifi-password xxx

与 wificlitools 文档

命令语义与 wificlitools/DESIGN.md、clitools.cpp 中 wifienable / wificonnect 一致；开放热点可不传密码（--wifi-password ''），对应框架 KEYMGMTNONE。

控制 LED（sysfs brightness）

Feature Description

通过 hdc shell 向设备写入 /sys/class/leds/<节点名>/brightness，0 为关、1 为开（与常见 GPIO LED 驱动一致）：

说明：Linux 下 LED 的 sysfs 目录名（red/green/blue）由设备树/驱动决定，可能与外壳丝印颜色不一致；脚本使用 节点名 red / green / blue，请按你的硬件实际路径选用。

Quick Start – Script

# 红灯开 / 关（等价于 hdc shell "echo 1 > /sys/class/leds/red/brightness"）
python3 src/skills/ohhdc/ohhdc.py led red on
python3 src/skills/ohhdc/ohhdc.py led red off

# sysfs 为 green 的灯（文档中常称蓝灯）
python3 src/skills/ohhdc/ohhdc.py led green on
python3 src/skills/ohhdc/ohhdc.py led green off

# sysfs 为 blue 的灯（文档中常称绿灯）
python3 src/skills/ohhdc/ohhdc.py led blue on
python3 src/skills/ohhdc/ohhdc.py led blue off

参数：led <red|green|blue> <on|off>。

底层命令示例：hdc shell "echo 1 > /sys/class/leds/blue/brightness" 为打开 sysfs 名为 blue 的灯。

Usage in Conversation

• “把设备红灯打开” → ohhdc.py led red on
• “关掉 green 节点的 LED” → ohhdc.py led green off

环境与通用说明

Environment Requirements（适用于所有操作）

• hdc: OpenHarmony HDC 需在 PATH 中。若通过 source ~/.bashrc 配置，脚本会执行 bash -c "source ~/.bashrc && hdc ..." 以保证能找到 hdc。
• Device: 设备或模拟器需已连接并被 hdc 识别。

Example Output（仅“查看已安装应用”）

## 已安装应用

共找到 **48** 个已安装应用：

| 序号 | Bundle Name |
|------|-------------|
| 1 | `com.OpenHarmony.app.test` |
| 2 | `com.example.kikakeyboard` |
...

### 应用列表（纯文本）

- `com.OpenHarmony.app.test`
- `com.example.kikakeyboard`
...

Script Location

• Skill: src/skills/ohhdc/SKILL.md
• Script: src/skills/ohhdc/ohhdc.py

Summary