clz/arkts-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add HarmonyOS build & deploy skill and update ArkTS skill with related skills section

Browse Source
This commit is contained in:
CHE LIANG ZHAO
2026-01-23 14:07:47 +08:00
parent 6e5c7961d4
commit 545efe99ba
3 changed files with 628 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
arkts-development/SKILL.md
View File

@@ -286,3 +286,7 @@ See [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) for
- **IDE**: DevEco Studio
- **SDK**: HarmonyOS SDK
- **Simulator**: Built-in DevEco Studio emulator
## Related Skills
- **Build & Deploy**: See `harmonyos-build-deploy` skill for building, packaging, and device installation

332
harmonyos-build-deploy/SKILL.md Normal file
View File

@@ -0,0 +1,332 @@
---
name: harmonyos-build-deploy
description: HarmonyOS application build, clean, package and device installation. Use when building HarmonyOS projects with hvigorw, cleaning build artifacts, managing ohpm dependencies, packaging HAP/HSP/APP bundles, installing to devices via hdc, or troubleshooting installation errors like "version code not same".
---
# HarmonyOS Build & Deploy
Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.
## 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
# Install to device (check actual output path in your project)
hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
hdc -t <UDID> file send <output_path>/signed /data/local/tmp/install
hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
```
**Note:** Build output path varies by project. Common paths:
- `outputs/default/signed/`
- `outputs/project/bundles/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:
### 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. 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 <UDID> shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\"
- Send files: hdc -t <UDID> file send <output_path> /data/local/tmp/install/
- Install: hdc -t <UDID> shell \"bm install -p /data/local/tmp/install/project/bundles/signed\"
- Launch: hdc -t <UDID> shell \"aa start -a EntryAbility -b <bundleName>\"
6. Report success/failure with details.", subagent_type="general")
```
### 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 <UDID>.
1. Read AppScope/app.json5 to get bundleName
2. Clean device temp: hdc -t <UDID> shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\"
3. Send build output to device: hdc -t <UDID> file send \"<output_path>/project/\" \"/data/local/tmp/install/\"
4. Install: hdc -t <UDID> shell \"bm install -p /data/local/tmp/install/project/bundles/signed\"
5. Launch: hdc -t <UDID> shell \"aa start -a EntryAbility -b <bundleName>\"
6. Report success/failure with details.", subagent_type="general")
```
### Restart App
```bash
# Launch subagent to restart the app
Task(description="Restart app", prompt="Restart the HarmonyOS app on device <UDID>.
1. Force stop: hdc -t <UDID> shell \"aa force-stop <bundleName>\"
2. Launch: hdc -t <UDID> shell \"aa start -a EntryAbility -b <bundleName>\"
3. Report success/failure.", subagent_type="general")
```
### Clean App Cache/Data
```bash
# Launch subagent to clean app data
Task(description="Clean app data", prompt="Clean app data on device <UDID>.
1. Clean cache: hdc -t <UDID> shell \"bm clean -n <bundleName> -c\"
2. Clean data: hdc -t <UDID> shell \"bm clean -n <bundleName> -d\"
3. Report success/failure.", subagent_type="general")
```
**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)
Use incremental build for normal development - only changed modules are rebuilt:
```bash
# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
```
### Single Module Build
Build only a specific module for faster iteration:
```bash
# Build single HAP module
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon
# Build single HSP module
hvigorw assembleHsp -p module=feature_module@default --mode module -p buildMode=release --no-daemon
# Build single HAR module
hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon
# Build multiple modules at once
hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p buildMode=release --no-daemon
```
**Module name format:** `{moduleName}@{targetName}`
- `moduleName`: Directory name of the module (e.g., `entry`, `feature_home`)
- `targetName`: Target defined in module's `build-profile.json5` (usually `default`)
**When to use single module build:**
- Developing/debugging a specific module
- Faster build times during iteration
- Testing changes in isolated module
**Note:** After single module build, you still need to run `assembleApp` to package the complete application for installation.
### Clean Build (When Needed)
Only perform clean build when:
- First time building the project
- Encountering unexplained build errors
- After modifying `build-profile.json5` or SDK version
- Dependency resolution issues
```bash
# Clean build artifacts
hvigorw clean --no-daemon
# Deep clean (for dependency issues)
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
```
### Install Dependencies (ohpm)
```bash
# Install all dependencies (after clean or first clone)
ohpm install --all
# With custom registry
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"
```
### Sync Project
Only needed after modifying `build-profile.json5` or `oh-package.json5`:
```bash
hvigorw --sync -p product=default -p buildMode=release --no-daemon
```
### Build Types
```bash
hvigorw assembleHap # Build HAP (Harmony Ability Package)
hvigorw assembleHsp # Build HSP (Harmony Shared Package)
hvigorw assembleHar # Build HAR (Harmony Archive)
hvigorw assembleApp # Build complete APP bundle
```
### Build Parameters
| Parameter | Description |
|-----------|-------------|
| `-p product={name}` | Target product defined in build-profile.json5 |
| `-p buildMode={debug\|release}` | Build mode |
| `-p module={name}@{target}` | Target module with `--mode module` |
| `--mode project` | Build all modules in project |
| `--mode module` | Build specific module only |
| `--no-daemon` | Disable daemon (recommended for CI) |
| `--analyze=advanced` | Enable build analysis |
## Build Outputs
Build output path varies by project configuration. Common patterns:
```
outputs/
├── default/signed/ # Pattern 1
│ ├── entry-default-signed.hap
│ └── *.hsp
└── project/bundles/signed/ # Pattern 2
├── entry-default-signed.hap
└── *.hsp
```
**Tip:** After build, check the actual output directory in your project.
### Module Types
| Type | Extension | Description |
|------|-----------|-------------|
| HAP | `.hap` | Harmony Ability Package - Application entry module |
| HSP | `.hsp` | Harmony Shared Package - Dynamic shared library |
| HAR | `.har` | Harmony Archive - Static library (compiled into HAP) |
| APP | `.app` | Complete application bundle (all HAP + HSP) |
## Unwanted Modules in Output Directory
Sometimes HSP files appear in the output directory that are **not listed in `build-profile.json5`**. These modules should not be deployed.
**Cause:** Build scripts or dependency configurations may copy precompiled HSP files to the output directory, even though they are not part of the current build.
**How to identify:**
1. Check `build-profile.json5` → `modules` array
2. If an HSP file in output is not in the modules list, it should be removed before installation
**Solution:** Remove these HSP files before installation:
```bash
# Example: Remove modules not in build-profile.json5
rm <output_path>/signed/unwanted-module-default-signed.hsp
```
**Note:** Installation will fail with "version code not same" error if these unwanted modules have a different versionCode than the main app. The root cause is that these modules shouldn't be deployed at all.
## Device Installation (hdc)
hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's adb.
### Check Device
```bash
hdc list targets # List connected devices (returns UDID)
hdc -t <UDID> shell "whoami" # Test connection
```
### Push and Install
```bash
# Clear device directory
hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
# Push signed bundles
hdc -t <UDID> file send path/to/signed /data/local/tmp/install
# Install all HAP/HSP in directory
hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
```
### Verify and Launch
```bash
# Check installation
hdc -t <UDID> shell "bm dump -n <bundleName>"
# Launch app (default ability)
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
```
### Uninstall
```bash
hdc -t <UDID> shell "bm uninstall -n <bundleName>"
```
## hdc Command Reference
| Command | Description |
|---------|-------------|
| `hdc list targets` | List connected devices |
| `hdc -t <UDID> shell "<cmd>"` | Execute shell command on device |
| `hdc -t <UDID> file send <local> <remote>` | Push file/directory to device |
| `hdc -t <UDID> file recv <remote> <local>` | Pull file/directory from device |
| `hdc kill` | Kill hdc server |
| `hdc start` | Start hdc server |
| `hdc version` | Show hdc version |
## Bundle Manager (bm)
Run via `hdc -t <UDID> shell "bm ..."`:
| Command | Description |
|---------|-------------|
| `bm install -p <path>` | Install from directory (all HAP/HSP) |
| `bm install -p <file.hap>` | Install single HAP file |
| `bm uninstall -n <bundleName>` | Uninstall application |
| `bm dump -n <bundleName>` | Show package info |
| `bm dump -a` | List all installed packages |
## Ability Assistant (aa)
Run via `hdc -t <UDID> shell "aa ..."`:
| Command | Description |
|---------|-------------|
| `aa start -a <ability> -b <bundle>` | Start specific ability |
| `aa force-stop <bundleName>` | Force stop application |
| `aa dump -a` | Dump all running abilities |
## Troubleshooting
| Error | Cause | Solution |
|-------|-------|----------|
| `version code not same` | HSP in output not in build-profile.json5 | Remove unwanted HSP files before install |
| `install parse profile prop check error` | Signature/profile mismatch | Check signing config in build-profile.json5 |
| `install failed due to older sdk version` | Device SDK < app's compatibleSdkVersion | Update device or lower compatibleSdkVersion |
| Device not found | Connection issue | Check USB, enable debugging, `hdc kill && hdc start` |
| `signature verification failed` | Invalid or expired certificate | Regenerate signing certificate |
## Key Configuration Files
| File | Description |
|------|-------------|
| `AppScope/app.json5` | App metadata (bundleName, versionCode, versionName) |
| `build-profile.json5` | Modules list, products, signing configs |
| `{module}/src/main/module.json5` | Module config (abilities, permissions) |
| `{module}/oh-package.json5` | Module dependencies |
## Reference Files
- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md)

292
harmonyos-build-deploy/references/device-installation.md Normal file
View File

@@ -0,0 +1,292 @@
# Device Installation Guide
Complete guide for building, packaging, and installing HarmonyOS applications to physical devices.
## Prerequisites
- **hdc**: HarmonyOS Device Connector (included in HarmonyOS SDK)
- **Device**: HarmonyOS device with USB debugging enabled
- **Build Output**: Signed HAP/HSP files
## Complete 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
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:
```bash
# Using Python (cross-platform)
python3 -c "
import zipfile, json, glob
for f in glob.glob('outputs/default/signed/*.hsp'):
z = zipfile.ZipFile(f)
data = json.loads(z.read('module.json'))
print(f\"{f.split('/')[-1]}: versionCode = {data['app']['versionCode']}\")
"
# Using unzip + grep (Linux/macOS)
for f in outputs/default/signed/*.hsp; do
echo -n "$(basename $f): "
unzip -p "$f" module.json | grep -o '"versionCode":[0-9]*'
done
```
**How to identify problematic modules:**
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
```bash
# Clear and create installation directory on device
hdc -t <UDID> shell "rm -rf /data/local/tmp/app_install && mkdir -p /data/local/tmp/app_install"
# Push signed HAP/HSP files
hdc -t <UDID> file send outputs/default/signed /data/local/tmp/app_install
```
### Step 5: Install Application
```bash
# Install all HAP/HSP from directory
hdc -t <UDID> shell "bm install -p /data/local/tmp/app_install/signed"
# Expected output: "install bundle successfully."
```
### Step 6: Verify and Launch
```bash
# Check package info
hdc -t <UDID> shell "bm dump -n <bundleName>"
# Launch application
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
```
### Uninstall Application
```bash
hdc -t <UDID> shell "bm uninstall -n <bundleName>"
```
## Quick Installation Script
Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows:
```bash
#!/bin/bash
# === Configuration ===
DEVICE_ID="${1:-$(hdc list targets | head -1)}"
SIGNED_PATH="${2:-outputs/default/signed}"
BUNDLE_NAME="${3:-}"
REMOTE_PATH="/data/local/tmp/app_install"
if [ -z "$DEVICE_ID" ]; then
echo "Error: No device found. Connect a device or specify UDID as first argument."
exit 1
fi
echo "Device: $DEVICE_ID"
echo "Source: $SIGNED_PATH"
# === Clear remote directory ===
hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH && mkdir -p $REMOTE_PATH"
# === Push signed files ===
hdc -t "$DEVICE_ID" file send "$SIGNED_PATH" "$REMOTE_PATH"
# === Install ===
hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$(basename $SIGNED_PATH)"
echo ""
echo "Installation complete!"
# === Optional: Launch app ===
if [ -n "$BUNDLE_NAME" ]; then
echo "Launching $BUNDLE_NAME..."
hdc -t "$DEVICE_ID" shell "aa start -a EntryAbility -b $BUNDLE_NAME"
fi
```
Usage:
```bash
# Auto-detect device, use default path
./install.sh
# Specify device UDID
./install.sh 1234567890ABCDEF
# Specify device and path
./install.sh 1234567890ABCDEF outputs/default/signed
# Specify device, path, and bundle name (auto-launch)
./install.sh 1234567890ABCDEF outputs/default/signed com.example.app
```
## hdc Command Reference
### Device Management
| Command | Description |
|---------|-------------|
| `hdc list targets` | List connected devices (UDID) |
| `hdc -t <UDID> shell "<cmd>"` | 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 <UDID> file send <local> <remote>` | Push file/directory to device |
| `hdc -t <UDID> file recv <remote> <local>` | Pull file/directory from device |
### Bundle Manager (bm)
Execute via `hdc -t <UDID> shell "bm ..."`:
| Command | Description |
|---------|-------------|
| `bm install -p <path>` | Install from directory (all HAP/HSP) |
| `bm install -p <file.hap>` | Install single HAP file |
| `bm uninstall -n <bundleName>` | Uninstall application |
| `bm dump -n <bundleName>` | Dump package info |
| `bm dump -a` | Dump all installed packages |
### Ability Assistant (aa)
Execute via `hdc -t <UDID> shell "aa ..."`:
| Command | Description |
|---------|-------------|
| `aa start -a <ability> -b <bundle>` | Start specific ability |
| `aa force-stop <bundleName>` | Force stop application |
| `aa dump -a` | Dump all running abilities |
## Troubleshooting
### 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
2. Remove those modules from signed directory before installation
3. Usually caused by precompiled modules not in build-profile.json5
### Error: "install parse profile prop check error"
**Cause:** Signature or profile configuration mismatch.
**Solution:**
1. Check signing config in `build-profile.json5`
2. Ensure certificate and profile match
3. Verify profile bundleName matches app.json5 bundleName
4. Check certificate is not expired
### Error: Device not found
**Cause:** Connection or hdc service issue.
**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
4. Restart hdc server: `hdc kill && hdc start`
5. Try different USB port or cable
### Error: "install failed due to older sdk version in the device"
**Cause:** Device system version is lower than app's minimum requirement.
**Solution:**
1. Update device to latest system version
2. Or lower `compatibleSdkVersion` in `build-profile.json5`
### Error: "signature verification failed"
**Cause:** Certificate issues.
**Solution:**
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 |