fix: filter .hap/.hsp files when pushing to device instead of sending entire outputs directory

fix: simplify build output path from outputs/default/bundles/signed to outputs
feat: add build output collection step to Deploy Only workflow - Check outputs/default/bundles/signed/ before deploy, collect signed artifacts from module build directories if empty
2026-02-11 13:33:12 +08:00 · 2026-02-11 13:23:23 +08:00 · 2026-02-11 13:07:34 +08:00 · 2026-02-11 12:56:08 +08:00 · 2026-02-11 12:40:24 +08:00 · 2026-02-11 11:46:38 +08:00
6 changed files with 352 additions and 353 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -195,3 +195,34 @@ description: ...          # Detailed description for agent matching
 - Use **fenced code blocks** with language specifiers (`typescript`, `bash`).
 - Structure content as: Quick Reference first, then detailed sections.
 - Cross-reference related skills and reference files by relative path.
+
+## Maintaining Documentation
+
+### When to Update README.md
+
+**ALWAYS check and update README.md after making changes to the repository.**
+
+Update README when:
+- ✅ **Adding/removing files** - Update the repository structure section
+- ✅ **Adding new features/sections** - Update the "Covers" section of relevant skills
+- ✅ **Modifying project structure** - Update the file tree diagram
+- ✅ **Adding new skill directories** - Add to the "Available Skills" section
+
+Do NOT update README for:
+- ❌ Bug fixes that don't change functionality
+- ❌ Content improvements that don't add new features
+- ❌ Wording/typo corrections
+- ❌ Internal refactoring without user-visible changes
+
+### Update Checklist
+
+When making changes, follow this checklist:
+
+1. Make your changes to skill files
+2. **Check**: Did I add/remove files? → Update file tree in README
+3. **Check**: Did I add new functionality? → Update "Covers" section in README
+4. Update README.md if needed
+5. **ALWAYS** update CHANGELOG.md with a summary of changes for every commit
+6. **ALWAYS** sync the version badge in README.md when CHANGELOG.md version changes
+
+
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,61 @@
+# Changelog
+
+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/).
+
+## [Unreleased]
+
+### 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 but marked for subagent delegation
+- **harmonyos-build-deploy**: Deduplicated content between SKILL.md and device-installation.md — reference file now focuses on version verification and install script
+- **harmonyos-build-deploy**: Fixed module type identification — now uses `module.json5` `type` field instead of heuristic based on `targets` presence
+- **harmonyos-build-deploy**: Extracted module discovery, build outputs, and unwanted modules into `references/module-discovery.md` (~138 lines moved out of SKILL.md)
+- **harmonyos-build-deploy**: Fixed unquoted variable in install.sh script
+- **harmonyos-build-deploy**: Deploy Only workflow now checks for empty output directory and collects signed artifacts from module build directories
+- **harmonyos-build-deploy**: Simplified build output path from `outputs/default/bundles/signed/` to `outputs/`
+- **harmonyos-build-deploy**: Device push now filters by `.hap`/`.hsp` extension instead of sending entire directory
+
+### Removed
+
+- **harmonyos-build-deploy**: Wireless debugging (hdc tconn) section — environment setup, not build/deploy
+- **harmonyos-build-deploy**: Restart App workflow — runtime operation, not build/deploy
+- **harmonyos-build-deploy**: `aa dump -a` command — runtime debugging, not build/deploy
+- **harmonyos-build-deploy**: Build Types section — redundant with Single Module Build and Module Types table
+- **harmonyos-build-deploy**: Duplicate installation workflow and troubleshooting from device-installation.md (consolidated into SKILL.md)
+
+### Added
+
+- **harmonyos-build-deploy**: Additional bm commands (install -r reinstall, clean cache/data)
+- **harmonyos-build-deploy**: Cross-reference to arkts-development skill
+- **harmonyos-build-deploy**: New reference file `references/module-discovery.md`
+
+## [1.0.1] - 2026-02-11
+
+### Added
+
+- **harmonyos-build-deploy**: Finding Modules section (module definitions in build-profile.json5, module type identification)
+- **harmonyos-build-deploy**: Finding Module Build Outputs section (output paths, signed/unsigned artifacts, search commands)
+
+## [1.0.0] - 2026-02-10
+
+### Added
+
+- **arkts-development** skill
+  - ArkUI declarative UI framework guide
+  - State management V1 decorators (@State, @Prop, @Link, @Provide/@Consume, @Observed/@ObjectLink)
+  - State management V2 decorators (@ComponentV2, @Local, @Param, @Event, @ObservedV2, @Trace, @Computed, @Monitor, @Provider/@Consumer)
+  - Component lifecycle and navigation (router)
+  - Network requests (http) and local storage (preferences)
+  - TypeScript to ArkTS migration guide
+  - Code templates: component-template.ets, list-page-template.ets, state-management-v2-examples.ets
+  - Reference docs: API reference, component patterns, ArkGuard obfuscation, CodeLinter, hstack, hvigorw command-line
+- **harmonyos-build-deploy** skill
+  - hvigorw build commands (assembleApp, assembleHap, assembleHsp, assembleHar)
+  - ohpm dependency management
+  - hdc device installation and management
+  - Troubleshooting common build/deploy errors
+  - Device installation reference guide
+- **AGENTS.md** with coding conventions and documentation guidelines
--- a/README.md
+++ b/README.md
@@ -1,4 +1,6 @@
-# AI Skills - HarmonyOS/ArkTS Development
+# AI Agent Skills - HarmonyOS/ArkTS Development
+
+[![Version](https://img.shields.io/badge/version-1.0.1-blue.svg)](CHANGELOG.md)

 AI coding agent skills for HarmonyOS/ArkTS application development.

@@ -18,10 +20,11 @@ ArkTS/ArkUI development for HarmonyOS applications.

 **Covers:**
 - ArkUI declarative UI framework
- State management decorators (@State, @Prop, @Link)
+- State management V1 (@State, @Prop, @Link) and V2 (@Local, @Param, @Event, @ObservedV2, @Trace)
 - Component lifecycle and navigation
 - Network requests and local storage
 - TypeScript to ArkTS migration
+- Code obfuscation, linting, and debugging tools

 ### harmonyos-build-deploy

@@ -30,7 +33,8 @@ Build, package, and deploy HarmonyOS applications.
 **Covers:**
 - hvigorw build commands
 - ohpm package manager
- hdc device installation
+- hdc device installation and wireless debugging
+- Module type identification
 - Troubleshooting common errors

 ## Quick Deploy
@@ -52,12 +56,6 @@ npx skills add https://github.com/FadingLight9291117/arkts_skills --skill harmon
 npx skills add https://github.com/FadingLight9291117/arkts_skills --skill arkts-development
 ```

-Or search for skills on [skills.sh](https://skills.sh/) and run the corresponding install command:
-
-```bash
-npx skills add <owner/repo>
-```
-
 Once installed, the skill is automatically configured for your AI agent (supports Cursor, Claude Code, Copilot, and other major agents).

 > No additional CLI installation required — `npx` downloads and runs it automatically. To disable anonymous telemetry, set the environment variable `DISABLE_TELEMETRY=1`.
@@ -75,12 +73,14 @@ These skills are automatically loaded by the AI agent when relevant tasks are de

 ```
 AGENTS.md                       # Guidelines for AI agents
+CHANGELOG.md                    # Version history
 README.md                       # This file
 arkts-development/
 ├── SKILL.md
 ├── assets/
 │   ├── component-template.ets
-│   └── list-page-template.ets
+│   ├── list-page-template.ets
+│   └── state-management-v2-examples.ets
 └── references/
    ├── api-reference.md
    ├── arkguard-obfuscation.md
@@ -88,11 +88,13 @@ arkts-development/
    ├── component-patterns.md
    ├── hstack.md
    ├── hvigor-commandline.md
-    └── migration-guide.md
+    ├── migration-guide.md
+    └── state-management-v2.md
 harmonyos-build-deploy/
 ├── SKILL.md
 └── references/
-    └── device-installation.md
+    ├── device-installation.md
+    └── module-discovery.md
 ```

 ## Contributing
--- 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,92 +27,60 @@ 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

-# 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"
+# Install to device
+# Use a random directory name to avoid conflicts with previous installations
+INSTALL_DIR="/data/local/tmp/install_$(date +%s)"
+hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
+# Only push .hap and .hsp files
+for f in outputs/*.hap outputs/*.hsp; do
+    [ -f "$f" ] && hdc -t <UDID> file send "$f" $INSTALL_DIR/
+done
+hdc -t <UDID> shell "bm install -p $INSTALL_DIR"
+hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
 ```

-**Note:** Build output path varies by project. Common paths:
- `outputs/default/signed/`
- `outputs/project/bundles/signed/`
+**Note:** Build output path is `outputs/`.

-Check your project's actual output after build.
+## Workflows

-## Workflow with Subagent
-
-For time-consuming operations (build, clean, deploy), use the **general** subagent to handle the entire workflow:
+**IMPORTANT:** Build, clean, and deploy operations are long-running (build ~30s, file transfer ~20s). Always delegate these workflows to a **subagent** to avoid timeout. This also provides better error handling and clearer progress reporting to the user.

 ### 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.
+Delegate to subagent with the following steps:

-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")
-```
+1. Clean: `hvigorw clean --no-daemon`
+2. Install dependencies: `ohpm install --all`
+3. Build: `hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon`
+4. Deploy to device (see [Push and Install](#push-and-install) below)
+5. Launch: `hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"`
+6. Report success/failure with details

 ### 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>.
+Delegate to subagent with the following steps:

-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")
-```
+1. Read `AppScope/app.json5` to get bundleName
+2. Check `outputs/` for existing build outputs. If empty or missing, collect signed HAP/HSP from each module's build directory (`{srcPath}/build/default/outputs/default/*-signed.*`) into `outputs/`. See [module-discovery.md](references/module-discovery.md) for details.
+3. Deploy to device (see [Push and Install](#push-and-install) below)
+4. Launch: `hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"`
+5. Report success/failure with details

 ### Clean App Cache/Data

-```bash
-# Launch subagent to clean app data
-Task(description="Clean app data", prompt="Clean app data on device <UDID>.
+Delegate to subagent:

-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
+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

 ## Build Commands (hvigorw)

@@ -145,7 +102,7 @@ Build only a specific module for faster iteration:
 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
+hvigorw assembleHsp -p module=my_feature@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
@@ -155,7 +112,7 @@ hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p b
 ```

 **Module name format:** `{moduleName}@{targetName}`
- `moduleName`: Directory name of the module (e.g., `entry`, `feature_home`)
+- `moduleName`: Directory name of the module (e.g., `entry`, `my_feature`)
 - `targetName`: Target defined in module's `build-profile.json5` (usually `default`)

 **When to use single module build:**
@@ -202,15 +159,6 @@ Only needed after modifying `build-profile.json5` or `oh-package.json5`:
 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 |
@@ -225,20 +173,14 @@ hvigorw assembleApp    # Build complete APP bundle

 ## Build Outputs

-Build output path varies by project configuration. Common patterns:
+Build output path: `outputs/`

 ```
 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 |
@@ -248,25 +190,19 @@ outputs/
 | HAR | `.har` | Harmony Archive - Static library (compiled into HAP) |
 | APP | `.app` | Complete application bundle (all HAP + HSP) |

-## Unwanted Modules in Output Directory
+## Finding Modules

-Sometimes HSP files appear in the output directory that are **not listed in `build-profile.json5`**. These modules should not be deployed.
+Modules are defined in `build-profile.json5` at the project root. The module type is determined by the `type` field in `{module}/src/main/module.json5`:

-**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.
+| `type` value | Module Type | Build Command |
+|--------------|-------------|---------------|
+| `"entry"` / `"feature"` | **HAP** | `assembleHap` |
+| `"shared"` | **HSP** | `assembleHsp` |
+| `"har"` | **HAR** | `assembleHar` |

-**How to identify:**
+Module build outputs: `{srcPath}/build/default/outputs/default/`

-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.
+For detailed module discovery, build output structure, and handling unwanted modules, see [references/module-discovery.md](references/module-discovery.md).

 ## Device Installation (hdc)

@@ -282,14 +218,20 @@ 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"
+# Create random temp directory on device
+INSTALL_DIR="/data/local/tmp/install_$(date +%s)"
+hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"

-# Push signed bundles
-hdc -t <UDID> file send path/to/signed /data/local/tmp/install
+# Only push .hap and .hsp files
+for f in outputs/*.hap outputs/*.hsp; do
+    [ -f "$f" ] && hdc -t <UDID> file send "$f" $INSTALL_DIR/
+done

 # Install all HAP/HSP in directory
-hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
+hdc -t <UDID> shell "bm install -p $INSTALL_DIR"
+
+# Clean up temp directory
+hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
 ```

 ### Verify and Launch
@@ -328,9 +270,12 @@ Run via `hdc -t <UDID> shell "bm ..."`:
 |---------|-------------|
 | `bm install -p <path>` | Install from directory (all HAP/HSP) |
 | `bm install -p <file.hap>` | Install single HAP file |
+| `bm install -r -p <path>` | Reinstall (replace existing, keep data) |
 | `bm uninstall -n <bundleName>` | Uninstall application |
 | `bm dump -n <bundleName>` | Show package info |
 | `bm dump -a` | List all installed packages |
+| `bm clean -n <bundleName> -c` | Clean application cache |
+| `bm clean -n <bundleName> -d` | Clean application data |

 ## Ability Assistant (aa)

@@ -340,17 +285,16 @@ Run via `hdc -t <UDID> shell "aa ..."`:
 |---------|-------------|
 | `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 |
+| `version code not same` | HSP in output not in build-profile.json5 | Remove unwanted HSP files before install (see [module-discovery.md](references/module-discovery.md)) |
+| `install parse profile prop check error` | Signature/profile mismatch | Check signing config in build-profile.json5; verify bundleName matches app.json5; check certificate not expired |
 | `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 |
+| Device not found | Connection issue | Check USB; enable Developer Options (tap build number 7x) and USB debugging; `hdc kill && hdc start`; try different USB port/cable |
+| `signature verification failed` | Invalid or expired certificate | Regenerate certificate in DevEco Studio; check validity period; ensure correct signing config for build type |

 ## Key Configuration Files

@@ -363,4 +307,9 @@ Run via `hdc -t <UDID> shell "aa ..."`:

 ## Reference Files

- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md)
+- **Module Discovery & Build Outputs**: [references/module-discovery.md](references/module-discovery.md) - Module definitions, type identification, build output paths, unwanted modules
+- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) - 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.
--- a/harmonyos-build-deploy/references/device-installation.md
+++ b/harmonyos-build-deploy/references/device-installation.md
@@ -1,116 +1,46 @@
 # Device Installation Guide

-Complete guide for building, packaging, and installing HarmonyOS applications to physical devices.
+Detailed guide for verifying build outputs and automating device installation. This supplements the main [SKILL.md](../SKILL.md) with version verification scripts 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)
 python3 -c "
 import zipfile, json, glob
-for f in glob.glob('outputs/default/signed/*.hsp'):
+for f in glob.glob('outputs/*.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
+for f in outputs/*.hsp; do
    echo -n "$(basename $f): "
    unzip -p "$f" module.json | grep -o '"versionCode":[0-9]*'
 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
-
-```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>"
+rm outputs/problematic-module-default-signed.hsp
 ```

 ## Quick Installation Script
@@ -122,9 +52,9 @@ Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows:

 # === Configuration ===
 DEVICE_ID="${1:-$(hdc list targets | head -1)}"
-SIGNED_PATH="${2:-outputs/default/signed}"
+SIGNED_PATH="${2:-outputs}"
 BUNDLE_NAME="${3:-}"
-REMOTE_PATH="/data/local/tmp/app_install"
+REMOTE_PATH="/data/local/tmp/install_$(date +%s)"

 if [ -z "$DEVICE_ID" ]; then
    echo "Error: No device found. Connect a device or specify UDID as first argument."
@@ -133,15 +63,21 @@ fi

 echo "Device: $DEVICE_ID"
 echo "Source: $SIGNED_PATH"
+echo "Remote: $REMOTE_PATH"

-# === Clear remote directory ===
-hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH && mkdir -p $REMOTE_PATH"
+# === Create remote directory ===
+hdc -t "$DEVICE_ID" shell "mkdir -p $REMOTE_PATH"

-# === Push signed files ===
-hdc -t "$DEVICE_ID" file send "$SIGNED_PATH" "$REMOTE_PATH"
+# === Push only .hap and .hsp files ===
+for f in "$SIGNED_PATH"/*.hap "$SIGNED_PATH"/*.hsp; do
+    [ -f "$f" ] && hdc -t "$DEVICE_ID" file send "$f" "$REMOTE_PATH/"
+done

 # === Install ===
-hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$(basename $SIGNED_PATH)"
+hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH"
+
+# === Clean up ===
+hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH"

 echo ""
 echo "Installation complete!"
@@ -163,130 +99,8 @@ Usage:
 ./install.sh 1234567890ABCDEF

 # Specify device and path
-./install.sh 1234567890ABCDEF outputs/default/signed
+./install.sh 1234567890ABCDEF outputs

 # Specify device, path, and bundle name (auto-launch)
-./install.sh 1234567890ABCDEF outputs/default/signed com.example.app
+./install.sh 1234567890ABCDEF outputs 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 |
--- a/harmonyos-build-deploy/references/module-discovery.md
+++ b/harmonyos-build-deploy/references/module-discovery.md
@@ -0,0 +1,142 @@
+# Module Discovery & Build Outputs
+
+Guide for finding modules in a HarmonyOS project, identifying module types, locating build outputs, and handling unwanted modules.
+
+## Finding Modules
+
+All modules are defined in `build-profile.json5` at the project root, in the `modules` array.
+
+### Module Definition Structure
+
+```json5
+{
+  "modules": [
+    {
+      "name": "entry",              // Module name (used in build commands)
+      "srcPath": "./entry",         // Module source path (relative to project root)
+      "targets": [                  // Build target config (optional)
+        {
+          "name": "default",
+          "applyToProducts": ["default", "app_store"]
+        }
+      ]
+    },
+    {
+      "name": "my_library",
+      "srcPath": "./library/my_library",
+      "targets": [...]
+    }
+  ]
+}
+```
+
+### Key Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Module name, used in build commands (e.g., `-p module=entry@default`) |
+| `srcPath` | Module source path relative to project root |
+| `targets` | Build target config, specifies which products this module applies to |
+
+### Module Type Identification
+
+The module type is defined in each module's `module.json5` file:
+
+```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 type from each module's module.json5
+# Check {srcPath}/src/main/module.json5 for each module in build-profile.json5
+```
+
+## Finding Module Build Outputs
+
+Module build outputs are located at:
+
+```
+{srcPath}/build/default/outputs/default/
+```
+
+**Note:** Debug and Release builds output to the same directory. The difference is in the signing configuration used (defined in `build-profile.json5` → `signingConfigs`).
+
+### Output Files
+
+| File | Description |
+|------|-------------|
+| `{name}-default-signed.hsp` | **Signed HSP** (ready for installation) |
+| `{name}-default-unsigned.hsp` | Unsigned HSP |
+| `{name}.har` | HAR static library |
+| `app/{name}-default.hsp` | Intermediate artifact |
+| `mapping/sourceMaps.map` | Source maps for debugging |
+
+### Example
+
+For module `my_library` with `srcPath: "./library/my_library"`:
+
+```
+library/my_library/build/default/outputs/default/
+├── my_library-default-signed.hsp    ← Signed, ready to install
+├── my_library-default-unsigned.hsp
+├── my_library.har
+├── app/
+│   └── my_library-default.hsp
+├── mapping/
+│   └── sourceMaps.map
+└── pack.info
+```
+
+### Search Commands
+
+```bash
+# Find all signed HSP/HAP outputs
+dir /s /b "*-signed.hsp" "*-signed.hap" 2>nul           # Windows
+find . -name "*-signed.hsp" -o -name "*-signed.hap"     # Linux/macOS
+
+# Find specific module's output
+dir /s /b "{srcPath}\build\default\outputs\default\*"   # Windows
+ls -la {srcPath}/build/default/outputs/default/         # Linux/macOS
+```
+
+### Notes
+
+1. **Build required**: If `build/` directory doesn't exist, run build first
+2. **Project-level outputs**: Complete app bundle is in project root `outputs/` after `assembleApp`
+3. **oh_modules outputs**: Dependency modules may have outputs in `oh_modules/@xxx/build/...` (these are resolved dependencies)
+
+## 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 outputs/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.
Author	SHA1	Message	Date
cheliangzhao	9816e5fe82	fix: filter .hap/.hsp files when pushing to device instead of sending entire outputs directory	2026-02-11 13:33:12 +08:00
cheliangzhao	f5b575c0df	fix: simplify build output path from outputs/default/bundles/signed to outputs	2026-02-11 13:23:23 +08:00
cheliangzhao	8aa8fd567e	feat: add build output collection step to Deploy Only workflow - Check outputs/default/bundles/signed/ before deploy, collect signed artifacts from module build directories if empty	2026-02-11 13:07:34 +08:00
cheliangzhao	ab3ba1e8a0	refactor: deduplicate content across SKILL.md and device-installation.md - Replace repeated install commands in workflows with anchor references - Remove Build Types section (covered by Single Module Build + Module Types) - Remove duplicate installation workflow from device-installation.md - Merge detailed troubleshooting into SKILL.md table, remove from reference file	2026-02-11 12:56:08 +08:00
cheliangzhao	306be63b7c	refactor: remove non-build/deploy content from harmonyos-build-deploy skill - Remove Wireless Debugging (hdc tconn) section — environment setup, not build/deploy - Remove Restart App workflow — runtime operation, not build/deploy - Remove aa dump -a command — runtime debugging, not build/deploy - Remove duplicate Build Output Structure from device-installation.md	2026-02-11 12:40:24 +08:00
cheliangzhao	d1d89b7225	fix: standardize build output path to outputs/default/bundles/signed	2026-02-11 11:46:38 +08:00
cheliangzhao	01da810dfa	fix: use random temp directory names for device installation paths	2026-02-11 11:43:32 +08:00
cheliangzhao	bba88755f6	fix: replace real module names with generic examples in skill docs	2026-02-11 11:40:58 +08:00
cheliangzhao	a10227e589	refactor: remove hilog device logging section from build-deploy skill	2026-02-11 11:40:15 +08:00
cheliangzhao	4717c93a8b	fix: revert version to 1.0.1, use Unreleased in CHANGELOG for develop	2026-02-11 11:38:26 +08:00
cheliangzhao	ab10765eb3	refactor: extract module discovery into separate reference file - Move Finding Modules, Build Outputs, Unwanted Modules (~138 lines) to references/module-discovery.md - Replace with summary table and cross-reference in SKILL.md - Update README file tree and CHANGELOG	2026-02-11 11:38:12 +08:00
cheliangzhao	53cdd8e1ae	fix: restore subagent delegation for long-running build/deploy workflows	2026-02-11 11:33:05 +08:00
cheliangzhao	a131ad1057	refactor: overhaul harmonyos-build-deploy skill - Translate Chinese UI strings to English and remove agent-framework coupling (question/Task tools) - Fix module type identification to use module.json5 type field instead of targets heuristic - Deduplicate SKILL.md and device-installation.md, clarify each file's role - Add device logging (hilog), wireless debugging (hdc tconn), missing bm commands - Add cross-reference to arkts-development skill - Fix unquoted variable in install.sh script	2026-02-11 11:24:09 +08:00
cheliangzhao	c0f1574e47	docs: remove generic skills search section from Quick Deploy	2026-02-11 10:21:21 +08:00
cheliangzhao	b7ebfea749	docs: rename README title to AI Agent Skills	2026-02-11 10:20:17 +08:00
cheliangzhao	172531e473	docs: add version sync rule to AGENTS.md and sync README to v1.0.1	2026-02-11 10:13:52 +08:00
cheliangzhao	0b6a0eff34	feat: add module discovery and build output path documentation	2026-02-11 10:11:59 +08:00
cheliangzhao	61fa472a88	docs: add version 1.0.0 badge, CHANGELOG, and changelog maintenance rule	2026-02-10 21:14:49 +08:00
cheliangzhao	5ee63b901a	docs: simplify AGENTS.md by removing git workflow examples	2026-02-10 21:12:49 +08:00
cheliangzhao	19125ca794	docs: add README maintenance guidelines to AGENTS.md - Add clear rules for when to update README - Add checklist for documentation updates - Include workflow for pushing to both remotes (origin + gitea) - Distinguish between changes that require README updates vs those that don't	2026-02-10 21:12:13 +08:00
cheliangzhao	87993a5a2c	docs: update README with State Management V2 and new files - Add state-management-v2.md and state-management-v2-examples.ets to file tree - Update arkts-development coverage to include V2 decorators - Add mention of code obfuscation, linting, and debugging tools	2026-02-10 21:08:52 +08:00