diff --git a/CHANGELOG.md b/CHANGELOG.md index 146c040..da396ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [1.1.0] - 2026-02-11 + +### Changed + +- **harmonyos-build-deploy**: Translated Chinese UI strings to English in SKILL.md +- **harmonyos-build-deploy**: Removed agent-framework coupling (question() tool, Task() subagent references) — workflows are now framework-agnostic +- **harmonyos-build-deploy**: Deduplicated content between SKILL.md and device-installation.md — reference file now focuses on version verification, install script, and detailed troubleshooting +- **harmonyos-build-deploy**: Fixed module type identification — now uses `module.json5` `type` field instead of heuristic based on `targets` presence +- **harmonyos-build-deploy**: Fixed unquoted variable in install.sh script + +### Added + +- **harmonyos-build-deploy**: Device logging section (hilog commands, filtering options, ArkTS logging example) +- **harmonyos-build-deploy**: Wireless debugging documentation (hdc tconn) +- **harmonyos-build-deploy**: Additional bm commands (install -r reinstall, clean cache/data) +- **harmonyos-build-deploy**: Cross-reference to arkts-development skill + ## [1.0.1] - 2026-02-11 ### Added diff --git a/README.md b/README.md index 7efcdf6..24a31ce 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AI Agent Skills - HarmonyOS/ArkTS Development -[![Version](https://img.shields.io/badge/version-1.0.1-blue.svg)](CHANGELOG.md) +[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](CHANGELOG.md) AI coding agent skills for HarmonyOS/ArkTS application development. @@ -33,7 +33,9 @@ Build, package, and deploy HarmonyOS applications. **Covers:** - hvigorw build commands - ohpm package manager -- hdc device installation +- hdc device installation and wireless debugging +- Device logging (hilog) +- Module type identification - Troubleshooting common errors ## Quick Deploy diff --git a/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md index b9eb2c3..8a50e81 100644 --- a/harmonyos-build-deploy/SKILL.md +++ b/harmonyos-build-deploy/SKILL.md @@ -7,30 +7,19 @@ description: HarmonyOS application build, clean, package and device installation Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications. -## First Step: Ask User for Operation +## First Step: Confirm Operation with User -**IMPORTANT:** Before executing any build or deploy operation, you MUST first ask the user which specific operation(s) they want to perform using the `question` tool. +**IMPORTANT:** Before executing any build or deploy operation, confirm which specific operation(s) the user wants to perform. Ask the user to choose from: -Use the following question configuration: +| Operation | Description | +|-----------|-------------| +| Clean build artifacts | Remove previous build cache and outputs | +| Install dependencies | Use ohpm to install project dependencies | +| Build project | Use hvigorw to build HAP/APP packages | +| Install to device | Use hdc to install the app on a device | +| Full pipeline | Clean → install deps → build → deploy to device | -```javascript -question({ - questions: [{ - header: "选择操作", - multiple: true, - question: "您想要执行哪些构建部署操作?", - options: [ - { label: "清理构建产物", description: "清理之前的构建缓存和产物" }, - { label: "安装依赖", description: "使用 ohpm 安装项目依赖" }, - { label: "构建项目", description: "使用 hvigorw 构建 HAP/APP 包" }, - { label: "安装到设备", description: "使用 hdc 将应用安装到设备" }, - { label: "完整流程", description: "依次执行清理、安装依赖、构建、部署到设备" } - ] - }] -}) -``` - -**Why ask first:** +**Why confirm first:** - Different scenarios require different operations (e.g., incremental build vs clean build) - Avoid unnecessary time-consuming operations - Give user control over the workflow @@ -38,15 +27,11 @@ question({ **After user responds:** - Execute only the selected operations -- Use the subagent Task tool for time-consuming operations (build, deploy) - Report progress and results clearly ## Quick Reference ```bash -# For time-consuming operations (build, deploy), use subagent Task tool -# See "Workflow with Subagent" section below for details - # Build complete app (incremental) hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon @@ -62,69 +47,59 @@ hdc -t shell "bm install -p /data/local/tmp/install/signed" Check your project's actual output after build. -## Workflow with Subagent - -For time-consuming operations (build, clean, deploy), use the **general** subagent to handle the entire workflow: +## Workflows ### Clean Build & Deploy ```bash -# Launch subagent to clean, build, and deploy to device -Task(description="Clean build and deploy", prompt="Clean build and deploy the HarmonyOS app to device. +# 1. Clean +hvigorw clean --no-daemon -1. Run: hvigorw clean --no-daemon -2. Run: ohpm install --all -3. Run: hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon -4. Find the build output directory (outputs/project/ or outputs/default/) -5. Deploy to device using hdc commands: - - Clean device temp: hdc -t shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\" - - Send files: hdc -t file send /data/local/tmp/install/ - - Install: hdc -t shell \"bm install -p /data/local/tmp/install/project/bundles/signed\" - - Launch: hdc -t shell \"aa start -a EntryAbility -b \" -6. Report success/failure with details.", subagent_type="general") +# 2. Install dependencies +ohpm install --all + +# 3. Build +hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon + +# 4. Find build output (check outputs/default/signed/ or outputs/project/bundles/signed/) + +# 5. Deploy to device +hdc -t shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install" +hdc -t file send /signed /data/local/tmp/install +hdc -t shell "bm install -p /data/local/tmp/install/signed" + +# 6. Launch +hdc -t shell "aa start -a EntryAbility -b " ``` ### Deploy Only (No Rebuild) ```bash -# Launch subagent to deploy existing build to device -Task(description="Deploy app to device", prompt="Deploy the HarmonyOS application to device . +# 1. Read AppScope/app.json5 to get bundleName -1. Read AppScope/app.json5 to get bundleName -2. Clean device temp: hdc -t shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\" -3. Send build output to device: hdc -t file send \"/project/\" \"/data/local/tmp/install/\" -4. Install: hdc -t shell \"bm install -p /data/local/tmp/install/project/bundles/signed\" -5. Launch: hdc -t shell \"aa start -a EntryAbility -b \" -6. Report success/failure with details.", subagent_type="general") +# 2. Push existing build output to device +hdc -t shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install" +hdc -t file send /signed /data/local/tmp/install +hdc -t shell "bm install -p /data/local/tmp/install/signed" + +# 3. Launch +hdc -t shell "aa start -a EntryAbility -b " ``` ### Restart App ```bash -# Launch subagent to restart the app -Task(description="Restart app", prompt="Restart the HarmonyOS app on device . - -1. Force stop: hdc -t shell \"aa force-stop \" -2. Launch: hdc -t shell \"aa start -a EntryAbility -b \" -3. Report success/failure.", subagent_type="general") +hdc -t shell "aa force-stop " +hdc -t shell "aa start -a EntryAbility -b " ``` ### Clean App Cache/Data ```bash -# Launch subagent to clean app data -Task(description="Clean app data", prompt="Clean app data on device . - -1. Clean cache: hdc -t shell \"bm clean -n -c\" -2. Clean data: hdc -t shell \"bm clean -n -d\" -3. Report success/failure.", subagent_type="general") +hdc -t shell "bm clean -n -c" # Clean cache +hdc -t shell "bm clean -n -d" # Clean data ``` -**Why use subagent?** -- Long-running operations (build ~30s, file transfer ~20s) don't timeout -- Better error handling and reporting -- User gets clear progress updates - ## Build Commands (hvigorw) ### Incremental Build (Default) @@ -286,20 +261,31 @@ All modules are defined in `build-profile.json5` at the project root, in the `mo ### Module Type Identification -| Characteristic | Module Type | -|----------------|-------------| -| Has `targets` and `name` is `entry` | **HAP** (Application entry) | -| Has `targets` config | **HSP** (Dynamic shared package) | -| No `targets` config | **HAR** (Static library, compiled into other modules) | +The module type is defined in each module's `module.json5` file: -### Quick Commands +```json5 +// {module}/src/main/module.json5 +{ + "module": { + "name": "entry", + "type": "entry", // "entry" = HAP, "shared" = HSP, "har" = HAR + ... + } +} +``` + +| `type` field value | Module Type | Description | +|--------------------|-------------|-------------| +| `"entry"` | **HAP** | Application entry point | +| `"feature"` | **HAP** | Feature module (also a HAP) | +| `"shared"` | **HSP** | Dynamic shared package | +| `"har"` | **HAR** | Static library (compiled into other modules) | + +**To identify all module types in a project:** ```bash -# Read build-profile.json5 to find all modules -cat build-profile.json5 - -# Extract module names and paths (grep) -grep -E '"name"|"srcPath"' build-profile.json5 +# Read type from each module's module.json5 +# Check {srcPath}/src/main/module.json5 for each module in build-profile.json5 ``` ## Finding Module Build Outputs @@ -424,10 +410,32 @@ hdc -t shell "bm uninstall -n " | `hdc -t shell ""` | Execute shell command on device | | `hdc -t file send ` | Push file/directory to device | | `hdc -t file recv ` | Pull file/directory from device | +| `hdc tconn :` | Connect to device over Wi-Fi | | `hdc kill` | Kill hdc server | | `hdc start` | Start hdc server | | `hdc version` | Show hdc version | +### Wireless Debugging (Wi-Fi) + +Connect to a device over the network instead of USB: + +```bash +# 1. Connect device via USB first and get its IP address +hdc -t shell "ifconfig" # Find wlan0 IP + +# 2. Enable TCP port on device (if supported) +hdc -t shell "param set persist.hdc.port 5555" + +# 3. Connect wirelessly +hdc tconn :5555 + +# 4. Verify connection +hdc list targets +# Should show the IP-based target alongside or instead of USB target +``` + +**Note:** Wireless debugging may require the device and host to be on the same network. Not all devices support `hdc tconn`. + ## Bundle Manager (bm) Run via `hdc -t shell "bm ..."`: @@ -436,9 +444,12 @@ Run via `hdc -t shell "bm ..."`: |---------|-------------| | `bm install -p ` | Install from directory (all HAP/HSP) | | `bm install -p ` | Install single HAP file | +| `bm install -r -p ` | Reinstall (replace existing, keep data) | | `bm uninstall -n ` | Uninstall application | | `bm dump -n ` | Show package info | | `bm dump -a` | List all installed packages | +| `bm clean -n -c` | Clean application cache | +| `bm clean -n -d` | Clean application data | ## Ability Assistant (aa) @@ -450,6 +461,55 @@ Run via `hdc -t shell "aa ..."`: | `aa force-stop ` | Force stop application | | `aa dump -a` | Dump all running abilities | +## Device Logging (hilog) + +Use hilog to view device logs for debugging. Run via `hdc -t shell "hilog ..."`: + +```bash +# Stream all logs (like adb logcat) +hdc -t shell "hilog" + +# Filter by tag +hdc -t shell "hilog -T " + +# Filter by log level (DEBUG, INFO, WARN, ERROR, FATAL) +hdc -t shell "hilog -L ERROR" + +# Combine tag and level filters +hdc -t shell "hilog -T MyApp -L WARN" + +# Clear log buffer +hdc -t shell "hilog -r" + +# Show only recent logs (last N lines) +hdc -t shell "hilog -t 100" +``` + +### Common hilog Options + +| Option | Description | +|--------|-------------| +| `-T ` | Filter by log tag | +| `-L ` | Minimum log level: DEBUG, INFO, WARN, ERROR, FATAL | +| `-D ` | Filter by domain (hex, e.g., `0x0001`) | +| `-r` | Clear log buffer | +| `-t ` | Show only last N log entries | +| `-x` | Exit after printing existing logs (no streaming) | + +### Logging in ArkTS Code + +```typescript +import { hilog } from '@kit.PerformanceAnalysisKit'; + +const DOMAIN: number = 0x0000; +const TAG: string = 'MyApp'; + +hilog.info(DOMAIN, TAG, 'Application started'); +hilog.error(DOMAIN, TAG, 'Failed to load data: %{public}s', error.message); +``` + +**Note:** Use `%{public}s` for string parameters that should be visible in logs. Without `{public}`, parameters are masked as `` in release builds. + ## Troubleshooting | Error | Cause | Solution | @@ -471,4 +531,8 @@ Run via `hdc -t shell "aa ..."`: ## Reference Files -- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) +- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) - Detailed troubleshooting, version verification scripts, and installation script + +## Related Skills + +- **arkts-development**: ArkTS/ArkUI development patterns, state management, component lifecycle, and API usage. Use alongside this skill when developing HarmonyOS application code. diff --git a/harmonyos-build-deploy/references/device-installation.md b/harmonyos-build-deploy/references/device-installation.md index 46b53ed..4aa9a62 100644 --- a/harmonyos-build-deploy/references/device-installation.md +++ b/harmonyos-build-deploy/references/device-installation.md @@ -1,53 +1,18 @@ # Device Installation Guide -Complete guide for building, packaging, and installing HarmonyOS applications to physical devices. +Detailed guide for packaging and installing HarmonyOS applications to physical devices. This supplements the main [SKILL.md](../SKILL.md) with deeper troubleshooting, version verification, and an installation script. ## Prerequisites - **hdc**: HarmonyOS Device Connector (included in HarmonyOS SDK) - **Device**: HarmonyOS device with USB debugging enabled -- **Build Output**: Signed HAP/HSP files +- **Build Output**: Signed HAP/HSP files from `hvigorw assembleApp` -## Complete Workflow +## Verifying Build Outputs Before Installation -### Step 1: Check Device Connection +All HAP/HSP modules must have the **same versionCode**. Mismatched versions cause `"version code not same"` errors during installation. -```bash -hdc list targets -# Output: device UDID (e.g., 1234567890ABCDEF) -``` - -If no device found: -1. Check USB connection -2. Enable Developer Options on device -3. Enable USB debugging -4. Run `hdc kill && hdc start` to restart hdc server - -### Step 2: Build Project - -```bash -# Incremental build (default, use for normal development) -hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon -``` - -Only perform clean build when encountering issues or first time setup: - -```bash -# Clean build (only when needed) -hvigorw clean --no-daemon -ohpm clean && ohpm cache clean -ohpm install --all -hvigorw --sync -p product=default -p buildMode=release --no-daemon -hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon -``` - -Build outputs location: -- APP bundle: `outputs/{product}/{project}-{product}-signed.app` -- Signed modules: `outputs/{product}/signed/` - -### Step 3: Verify Build Outputs - -All HAP/HSP modules must have the **same versionCode**. Check for mismatches: +### Check versionCode of All Modules ```bash # Using Python (cross-platform) @@ -66,19 +31,34 @@ for f in outputs/default/signed/*.hsp; do done ``` -**How to identify problematic modules:** +### Identifying Problematic Modules + +A module should be removed from the output before installation if: 1. Module directory has no `src/` folder (precompiled binary only) 2. Module not listed in `build-profile.json5` modules array 3. Module versionCode differs from `AppScope/app.json5` -If any module has a different versionCode, remove it before installation: - ```bash rm outputs/default/signed/problematic-module-default-signed.hsp ``` -### Step 4: Push Files to Device +## Complete Installation Workflow + +### Step 1: Check Device Connection + +```bash +hdc list targets +# Output: device UDID (e.g., 1234567890ABCDEF) +``` + +If no device found: +1. Check USB connection +2. Enable Developer Options on device: Settings > About > Tap build number 7 times +3. Enable USB debugging: Settings > Developer options > USB debugging +4. Run `hdc kill && hdc start` to restart hdc server + +### Step 2: Push Files to Device ```bash # Clear and create installation directory on device @@ -88,7 +68,7 @@ hdc -t shell "rm -rf /data/local/tmp/app_install && mkdir -p /data/local/ hdc -t file send outputs/default/signed /data/local/tmp/app_install ``` -### Step 5: Install Application +### Step 3: Install Application ```bash # Install all HAP/HSP from directory @@ -97,7 +77,7 @@ hdc -t shell "bm install -p /data/local/tmp/app_install/signed" # Expected output: "install bundle successfully." ``` -### Step 6: Verify and Launch +### Step 4: Verify and Launch ```bash # Check package info @@ -107,12 +87,6 @@ hdc -t shell "bm dump -n " hdc -t shell "aa start -a EntryAbility -b " ``` -### Uninstall Application - -```bash -hdc -t shell "bm uninstall -n " -``` - ## Quick Installation Script Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows: @@ -141,7 +115,8 @@ hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH && mkdir -p $REMOTE_PATH" hdc -t "$DEVICE_ID" file send "$SIGNED_PATH" "$REMOTE_PATH" # === Install === -hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$(basename $SIGNED_PATH)" +BASENAME="$(basename "$SIGNED_PATH")" +hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$BASENAME" echo "" echo "Installation complete!" @@ -169,55 +144,28 @@ Usage: ./install.sh 1234567890ABCDEF outputs/default/signed com.example.app ``` -## hdc Command Reference +## Build Output Structure -### Device Management +``` +outputs/ +└── {product}/ # e.g., default/ + ├── {project}-{product}-signed.app # Complete APP bundle + ├── signed/ + │ ├── entry-{product}-signed.hap # Main entry HAP + │ ├── feature-{product}-signed.hap # Feature HAP (if any) + │ └── *.hsp # Shared library modules + └── unsigned/ + └── ... # Unsigned versions +``` -| Command | Description | -|---------|-------------| -| `hdc list targets` | List connected devices (UDID) | -| `hdc -t shell ""` | Execute shell command on device | -| `hdc kill` | Kill hdc server | -| `hdc start` | Start hdc server | -| `hdc version` | Show hdc version | - -### File Transfer - -| Command | Description | -|---------|-------------| -| `hdc -t file send ` | Push file/directory to device | -| `hdc -t file recv ` | Pull file/directory from device | - -### Bundle Manager (bm) - -Execute via `hdc -t shell "bm ..."`: - -| Command | Description | -|---------|-------------| -| `bm install -p ` | Install from directory (all HAP/HSP) | -| `bm install -p ` | Install single HAP file | -| `bm uninstall -n ` | Uninstall application | -| `bm dump -n ` | Dump package info | -| `bm dump -a` | Dump all installed packages | - -### Ability Assistant (aa) - -Execute via `hdc -t shell "aa ..."`: - -| Command | Description | -|---------|-------------| -| `aa start -a -b ` | Start specific ability | -| `aa force-stop ` | Force stop application | -| `aa dump -a` | Dump all running abilities | - -## Troubleshooting +## Troubleshooting Details ### Error: "version code not same" **Cause:** Some HAP/HSP modules have different versionCode than others. **Solution:** -1. Use the version check commands to find modules with different versionCode +1. Use the version check commands above to find modules with different versionCode 2. Remove those modules from signed directory before installation 3. Usually caused by precompiled modules not in build-profile.json5 @@ -237,8 +185,8 @@ Execute via `hdc -t shell "aa ..."`: **Solution:** 1. Check USB cable connection -2. Enable Developer Options: Settings → About → Tap build number 7 times -3. Enable USB debugging: Settings → Developer options → USB debugging +2. Enable Developer Options: Settings > About > Tap build number 7 times +3. Enable USB debugging: Settings > Developer options > USB debugging 4. Restart hdc server: `hdc kill && hdc start` 5. Try different USB port or cable @@ -258,35 +206,3 @@ Execute via `hdc -t shell "aa ..."`: 1. Regenerate debug/release certificate in DevEco Studio 2. Check certificate validity period 3. Ensure using correct signing config for build type - -## Build Output Structure - -``` -outputs/ -└── {product}/ # e.g., default/ - ├── {project}-{product}-signed.app # Complete APP bundle - ├── signed/ - │ ├── entry-{product}-signed.hap # Main entry HAP - │ ├── feature-{product}-signed.hap # Feature HAP (if any) - │ └── *.hsp # Shared library modules - └── unsigned/ - └── ... # Unsigned versions -``` - -## Key Configuration Files - -| File | Description | -|------|-------------| -| `AppScope/app.json5` | App metadata: bundleName, versionCode, versionName, icon, label | -| `build-profile.json5` | Build config: modules list, products, signing configs | -| `{module}/src/main/module.json5` | Module config: abilities, permissions, pages | -| `{module}/oh-package.json5` | Module dependencies | - -## Module Types - -| Type | Extension | Description | -|------|-----------|-------------| -| HAP | `.hap` | Harmony Ability Package - Application entry point | -| HSP | `.hsp` | Harmony Shared Package - Dynamic shared library | -| HAR | `.har` | Harmony Archive - Static library (compiled into HAP) | -| APP | `.app` | Complete bundle containing all HAP + HSP |