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
19 changed files with 4732 additions and 2325 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,18 @@
+# Temp files
+*.tmp
+*.bak
+*~
+
+# OS files
+Thumbs.db
+Desktop.ini
+.DS_Store
+
+# Editor files
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,65 +1,69 @@
 # AGENTS.md - OpenCode Skills Repository

-This repository contains AI coding agent skills for HarmonyOS/ArkTS development. Skills teach AI assistants how to build, deploy, and develop HarmonyOS applications.
+AI coding agent skills for HarmonyOS/ArkTS development. This is a **documentation-only** repo -- no build system for the repo itself. The skills teach agents how to build, deploy, and develop HarmonyOS apps.

 ## Repository Structure

 ```
-skills/
-├── arkts-development/          # ArkTS/ArkUI development skill
-│   ├── SKILL.md               # Main skill definition
-│   ├── assets/                # Code templates (.ets files)
-│   └── references/            # API docs, migration guide, patterns
-└── harmonyos-build-deploy/    # Build & deploy skill
-    ├── SKILL.md               # Main skill definition
-    └── references/            # Device installation guide
+arkts-development/              # ArkTS/ArkUI development skill
+├── SKILL.md                   # Main skill definition (loaded by agent)
+├── assets/*.ets               # Code templates
+└── references/*.md            # API docs, migration guide, patterns
+harmonyos-build-deploy/         # Build & deploy skill
+├── SKILL.md                   # Main skill definition (loaded by agent)
+└── references/*.md            # Device installation guide
 ```

-## Build/Lint/Test Commands
+## Build / Lint / Test Commands

-This is a documentation repository - no build system for the repo itself. However, the skills document these HarmonyOS CLI tools:
+These commands apply to **HarmonyOS projects** that the skills describe, not this repo.

-### Build Commands (hvigorw)
+### Build (hvigorw)

 ```bash
-# Incremental build (default for development)
-hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
-
-# Clean build
-hvigorw clean --no-daemon
-hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
-
-# Build single module (faster iteration)
-hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon
-
-# Run tests
-hvigorw onDeviceTest -p module=entry -p coverage=true    # On-device test
-hvigorw test -p module=entry                              # Local test
+hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon  # Full app
+hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon  # Single module (faster)
+hvigorw clean --no-daemon                                                                # Clean artifacts
+hvigorw --sync -p product=default -p buildMode=release --no-daemon                       # Sync after config change
 ```

-### Package Manager (ohpm)
+### Test

 ```bash
-ohpm install --all              # Install all dependencies
+# Run all tests for a module (on-device)
+hvigorw onDeviceTest -p module=entry -p coverage=true --no-daemon
+
+# Run all tests for a module (local / host-side)
+hvigorw test -p module=entry --no-daemon
+
+# Run a single test suite or single test (on-device) -- use -p testParam
+hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName\"}" --no-daemon
+hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName#testMethodName\"}" --no-daemon
+```
+
+### Dependencies (ohpm)
+
+```bash
+ohpm install --all                           # Install all deps
 ohpm clean && ohpm cache clean               # Deep clean
 ```

-### Code Linter (codelinter)
+### Lint (codelinter)

 ```bash
-codelinter                      # Check current project
-codelinter --fix                # Check and auto-fix
-codelinter -f json -o report.json  # JSON output
-codelinter -i                   # Incremental (Git changes only)
-codelinter --exit-on error,warn # CI/CD with exit codes
+codelinter                                   # Check project
+codelinter --fix                             # Auto-fix
+codelinter -i                                # Incremental (git changes only)
+codelinter --exit-on error,warn              # CI mode (non-zero exit on issues)
+codelinter -f json -o report.json            # JSON report
 ```

-### Device Commands (hdc)
+### Device (hdc)

 ```bash
 hdc list targets                                        # List devices (returns UDID)
-hdc -t <UDID> file send <local> <remote>  # Push files
-hdc -t <UDID> shell "bm install -p <path>" # Install app
+hdc -t <UDID> file send <local_path> <device_path>     # Push files
+hdc -t <UDID> shell "bm install -p <dir>"              # Install app
 hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"  # Launch app
 ```

@@ -67,49 +71,56 @@ hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>" # Launch app

 ### ArkTS Language Constraints

-ArkTS is stricter than TypeScript. These are prohibited:
+ArkTS is stricter than TypeScript. These features are **prohibited**:

 | Prohibited              | Use Instead                        |
-|------------|-------------|
+|-------------------------|------------------------------------|
 | `any`, `unknown`        | Explicit types, interfaces         |
 | `var`                   | `let`, `const`                     |
-| Dynamic property `obj['key']` | Fixed object structure |
-| `for...in`, `delete`, `with` | `for...of`, array methods |
+| `obj['key']` (dynamic)  | Fixed object structure             |
+| `for...in`              | `for...of`, array methods          |
+| `delete`, `with`        | Optional properties, explicit refs |
 | `#privateField`         | `private` keyword                  |
-| Structural typing | Explicit `implements`/`extends` |
+| Structural typing       | Explicit `implements` / `extends`  |
+| `eval()`, `Function()`  | Arrow functions, static code       |

 ### Naming Conventions

 | Element               | Convention      | Example                     |
-|---------|------------|---------|
+|-----------------------|-----------------|-----------------------------|
 | Components (struct)   | PascalCase      | `HomePage`, `UserCard`      |
-| Methods | camelCase | `loadData()`, `handleClick()` |
-| Properties/Variables | camelCase | `isLoading`, `userName` |
 | Interfaces            | PascalCase      | `UserInfo`, `ApiResponse`   |
+| Methods / Functions   | camelCase       | `loadData()`, `handleClick` |
+| Properties / Variables| camelCase       | `isLoading`, `userName`     |
 | Constants             | camelCase or UPPER_SNAKE | `maxRetries`, `API_URL` |
-| Files (skill docs) | kebab-case | `api-reference.md` |
 | Skill directories     | kebab-case      | `arkts-development`         |
+| Filenames (docs)      | kebab-case      | `api-reference.md`          |

 ### Type Annotations

-Always use explicit type annotations:
+Always use **explicit** type annotations on declarations, parameters, and return types:

 ```typescript
-// Required: Explicit types on declarations
@State isLoading: boolean = false;
@State items: ItemType[] = [];
-
-// Required: Return types on methods
 async loadData(): Promise<void> { }
 navigateToDetail(item: ItemType): void { }
-
-// Required: Parameter types
 ForEach(this.items, (item: ItemType) => { ... }, (item: ItemType) => item.id)
 ```

+### Imports
+
+Use HarmonyOS Kit-style imports:
+
+```typescript
+import { router } from '@kit.ArkUI';
+import { http } from '@kit.NetworkKit';
+import { preferences } from '@kit.ArkData';
+```
+
 ### Component Structure

-Follow this standard component layout:
+Follow this ordering inside every `@Component` struct:

 ```typescript
@Entry
@@ -118,23 +129,21 @@ struct ComponentName {
  // 1. State decorators
  @State isLoading: boolean = false;
  @State errorMessage: string = '';
-
-  // 2. Lifecycle methods
+  // 2. Lifecycle
  aboutToAppear(): void { this.loadData(); }
  aboutToDisappear(): void { /* cleanup */ }
-
  // 3. Business methods
  async loadData(): Promise<void> { }
-
-  // 4. Builder methods (reusable UI blocks)
+  // 4. @Builder methods (reusable UI blocks)
  @Builder ItemCard(item: ItemType) { }
-
-  // 5. Build method (always last)
+  // 5. build() -- always last
  build() { }
 }
 ```

-### Error Handling Pattern
+### Error Handling
+
+Wrap async work in try/catch/finally with loading state:

 ```typescript
 async loadData(): Promise<void> {
@@ -149,81 +158,71 @@ async loadData(): Promise<void> {
 }
 ```

-### Import Style
-
-Use HarmonyOS Kit imports:
-
-```typescript
-import { router } from '@kit.ArkUI';
-import { http } from '@kit.NetworkKit';
-import { preferences } from '@kit.ArkData';
-```
-
-## Skill File Format
-
-Each skill follows this structure:
-
-```markdown
---
-name: skill-name
-description: Detailed description for AI agent matching
---
-
-# Skill Title
-
-## Quick Start / Quick Reference
-## Main Content Sections
-## Troubleshooting
-## Reference Files
-```
-
-### YAML Frontmatter
-
-Required fields:
- `name`: kebab-case identifier matching directory name
- `description`: Detailed description for AI agent matching (trigger keywords)
-
-## Documentation Conventions
-
- Use tables for command references and parameters
- Include code blocks with language specifiers (`typescript`, `bash`)
- Cross-reference related skills and reference files
- Use bilingual content (Chinese/English) for HarmonyOS context
- Structure: Quick Reference first, then detailed sections
-
-## File Organization
-
- Main skill definition: `SKILL.md` (uppercase)
- Code templates: `assets/*.ets`
- Reference documentation: `references/*.md`
- All filenames: kebab-case
-
-## Common Patterns
-
-### State Management Decorators
-
-| Decorator | Direction | Usage |
-|-----------|-----------|-------|
-| `@State` | Internal | Component's own mutable state |
-| `@Prop` | Parent → Child | One-way binding (child copy) |
-| `@Link` | Parent ↔ Child | Two-way binding (pass with `$var`) |
-| `@Provide/@Consume` | Ancestor → Descendant | Cross-level state sharing |
-
-### Layout Components
-
-```typescript
-Column({ space: 10 }) { }  // Vertical layout
-Row({ space: 10 }) { }     // Horizontal layout
-Stack() { }                 // Overlay layout
-List({ space: 10 }) { }    // Scrollable list
-```
-
-### ForEach Pattern
-
-Always provide explicit types and key generator:
+### ForEach -- always provide types and a key generator

 ```typescript
 ForEach(this.items, (item: ItemType) => {
  ListItem() { Text(item.title) }
-}, (item: ItemType) => item.id)  // Key generator for efficient updates
+}, (item: ItemType) => item.id)
 ```
+
+## Skill File Format
+
+Every skill directory contains a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: skill-name          # kebab-case, matches directory name
+description: ...          # Detailed description for agent matching
+---
+# Skill Title
+## Quick Start / Quick Reference
+## Detailed Sections
+## Troubleshooting
+## Reference Files
+```
+
+### File Organization Rules
+
+- Main definition: `SKILL.md` (uppercase)
+- Code templates: `assets/*.ets`
+- Reference docs: `references/*.md`
+- All filenames: **kebab-case**
+
+## Documentation Conventions
+
+- Use **tables** for command references and parameter lists.
+- 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,10 +1,12 @@
-# OpenCode Skills - HarmonyOS 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.

 ## What are Skills?

-Skills are structured documentation that teach AI coding assistants (like OpenCode) how to perform specific development tasks. Each skill contains:
+Skills are structured documentation that teach AI coding assistants how to perform specific development tasks. Each skill contains:

 - **SKILL.md** - Main skill definition with quick reference and detailed guides
 - **assets/** - Code templates and examples
@@ -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,12 +33,36 @@ 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
+
+Use [skills.sh](https://skills.sh/) to deploy skills to your project with a single command.
+
+### Install all skills
+
+```bash
+npx skills add FadingLight9291117/arkts_skills
+```
+
+### Install a single skill
+
+You can install a specific skill from this repo using the `--skill` flag:
+
+```bash
+npx skills add https://github.com/FadingLight9291117/arkts_skills --skill harmonyos-build-deploy
+npx skills add https://github.com/FadingLight9291117/arkts_skills --skill arkts-development
+```
+
+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`.
+
 ## Usage

-These skills are automatically loaded by OpenCode when relevant tasks are detected. The AI agent uses the skill documentation to:
+These skills are automatically loaded by the AI agent when relevant tasks are detected. The agent uses the skill documentation to:

 1. Follow correct build/deploy procedures
 2. Write code following ArkTS conventions
@@ -45,25 +72,29 @@ These skills are automatically loaded by OpenCode when relevant tasks are detect
 ## Repository Structure

 ```
-skills/
-├── AGENTS.md                   # Guidelines for AI agents
-├── README.md                   # This file
-├── arkts-development/
-│   ├── SKILL.md
-│   ├── assets/
-│   │   ├── component-template.ets
-│   │   └── list-page-template.ets
-│   └── references/
-│       ├── api-reference.md
-│       ├── codelinter.md
-│       ├── component-patterns.md
-│       ├── hstack.md
-│       ├── hvigor-commandline.md
-│       └── migration-guide.md
-└── harmonyos-build-deploy/
-    ├── SKILL.md
-    └── references/
-        └── device-installation.md
+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
+│   └── state-management-v2-examples.ets
+└── references/
+    ├── api-reference.md
+    ├── arkguard-obfuscation.md
+    ├── codelinter.md
+    ├── component-patterns.md
+    ├── hstack.md
+    ├── hvigor-commandline.md
+    ├── migration-guide.md
+    └── state-management-v2.md
+harmonyos-build-deploy/
+├── SKILL.md
+└── references/
+    ├── device-installation.md
+    └── module-discovery.md
 ```

 ## Contributing
--- a/arkts-development/SKILL.md
+++ b/arkts-development/SKILL.md
@@ -34,6 +34,8 @@ struct HelloWorld {

 ## State Management Decorators

+### V1 (Traditional)
+
 | Decorator | Usage | Description |
 |-----------|-------|-------------|
 | `@State` | `@State count: number = 0` | Component internal state |
@@ -42,6 +44,22 @@ struct HelloWorld {
 | `@Provide/@Consume` | Cross-level | Ancestor → Descendant |
 | `@Observed/@ObjectLink` | Nested objects | Deep object observation |

+### V2 (Recommended - API 12+)
+
+| Decorator | Usage | Description |
+|-----------|-------|-------------|
+| `@ComponentV2` | `@ComponentV2 struct MyComp` | Enable V2 state management |
+| `@Local` | `@Local count: number = 0` | Internal state (no external init) |
+| `@Param` | `@Param title: string = ""` | Parent → Child (one-way, efficient) |
+| `@Event` | `@Event onChange: () => void` | Child → Parent (callback) |
+| `@ObservedV2` | `@ObservedV2 class Data` | Class observation |
+| `@Trace` | `@Trace name: string` | Property-level tracking |
+| `@Computed` | `@Computed get value()` | Cached computed properties |
+| `@Monitor` | `@Monitor('prop') onFn()` | Watch changes with before/after |
+| `@Provider/@Consumer` | Cross-level | Two-way sync across tree |
+
+**See [references/state-management-v2.md](references/state-management-v2.md) for complete V2 guide.**
+
 ## Common Layouts

 ```typescript
@@ -96,7 +114,11 @@ router.replaceUrl({ url: 'pages/New' });
 router.back();

 // Get params
-const params = router.getParams() as Record<string, Object>;
+interface RouteParams {
+  id: number;
+  title?: string;
+}
+const params = router.getParams() as RouteParams;
 ```

 ## Network Request
@@ -273,6 +295,7 @@ See [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) for

 ## Reference Files

+- **State Management V2**: [references/state-management-v2.md](references/state-management-v2.md) - Complete guide to V2 state management (@ComponentV2, @Local, @Param, @Event, @ObservedV2, @Trace, @Computed, @Monitor, @Provider, @Consumer)
 - **Migration Guide**: [references/migration-guide.md](references/migration-guide.md) - Complete TypeScript to ArkTS migration rules and examples
 - **Component Patterns**: [references/component-patterns.md](references/component-patterns.md) - Advanced component patterns and best practices
 - **API Reference**: [references/api-reference.md](references/api-reference.md) - Common HarmonyOS APIs
--- a/arkts-development/assets/list-page-template.ets
+++ b/arkts-development/assets/list-page-template.ets
@@ -28,6 +28,9 @@ struct {{PageName}} {
        { id: '1', title: 'Item 1', description: 'Description 1' },
        { id: '2', title: 'Item 2', description: 'Description 2' },
      ];
+    } catch (error) {
+      console.error('Failed to load items:', error);
+      // TODO: Show error message to user
    } finally {
      this.isLoading = false;
    }
--- a/arkts-development/assets/state-management-v2-examples.ets
+++ b/arkts-development/assets/state-management-v2-examples.ets
@@ -0,0 +1,523 @@
+// State Management V2 - Quick Reference Examples
+
+// ============================================
+// 1. BASIC COMPONENT WITH @Local STATE
+// ============================================
+@Entry
+@ComponentV2
+struct CounterApp {
+  @Local count: number = 0;
+  @Local step: number = 1;
+  
+  build() {
+    Column({ space: 10 }) {
+      Text(`Count: ${this.count}`)
+        .fontSize(30)
+      Button(`+${this.step}`)
+        .onClick(() => this.count += this.step)
+      Button(`-${this.step}`)
+        .onClick(() => this.count -= this.step)
+    }
+  }
+}
+
+// ============================================
+// 2. NESTED OBJECTS WITH @ObservedV2/@Trace
+// ============================================
+@ObservedV2
+class Address {
+  @Trace city: string;
+  @Trace street: string;
+  
+  constructor(city: string, street: string) {
+    this.city = city;
+    this.street = street;
+  }
+}
+
+@ObservedV2
+class Person {
+  @Trace name: string;
+  @Trace age: number;
+  @Trace address: Address;
+  
+  constructor(name: string, age: number, address: Address) {
+    this.name = name;
+    this.age = age;
+    this.address = address;
+  }
+}
+
+@Entry
+@ComponentV2
+struct PersonProfile {
+  person: Person = new Person(
+    "Tom", 
+    25, 
+    new Address("Beijing", "Main St")
+  );
+  
+  build() {
+    Column({ space: 10 }) {
+      Text(`${this.person.name}, ${this.person.age}`)
+      Text(`${this.person.address.city}`)
+      Button('Birthday').onClick(() => {
+        this.person.age++;  // Observable
+      })
+      Button('Move').onClick(() => {
+        this.person.address.city = "Shanghai";  // Observable
+      })
+    }
+  }
+}
+
+// ============================================
+// 3. PARENT-CHILD WITH @Param/@Event
+// ============================================
+@ComponentV2
+struct Counter {
+  @Param count: number = 0;
+  @Event onIncrement: () => void = () => {};
+  @Event onDecrement: () => void = () => {};
+  
+  build() {
+    Row({ space: 10 }) {
+      Button('-').onClick(() => this.onDecrement())
+      Text(`${this.count}`).fontSize(30)
+      Button('+').onClick(() => this.onIncrement())
+    }
+  }
+}
+
+@Entry
+@ComponentV2
+struct ParentApp {
+  @Local count: number = 0;
+  
+  build() {
+    Column({ space: 20 }) {
+      Text('Parent Count: ' + this.count)
+      Counter({
+        count: this.count,
+        onIncrement: () => this.count++,
+        onDecrement: () => this.count--
+      })
+    }
+  }
+}
+
+// ============================================
+// 4. COMPUTED PROPERTIES
+// ============================================
+@ObservedV2
+class CartItem {
+  @Trace name: string;
+  @Trace price: number;
+  @Trace quantity: number;
+  
+  constructor(name: string, price: number, quantity: number) {
+    this.name = name;
+    this.price = price;
+    this.quantity = quantity;
+  }
+}
+
+@Entry
+@ComponentV2
+struct ShoppingCart {
+  @Local items: CartItem[] = [
+    new CartItem("Apple", 5, 3),
+    new CartItem("Banana", 3, 5)
+  ];
+  @Local taxRate: number = 0.1;
+  
+  @Computed
+  get subtotal(): number {
+    console.log("Computing subtotal");  // Only logs when items change
+    return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  }
+  
+  @Computed
+  get tax(): number {
+    return this.subtotal * this.taxRate;
+  }
+  
+  @Computed
+  get total(): number {
+    return this.subtotal + this.tax;
+  }
+  
+  build() {
+    Column({ space: 10 }) {
+      ForEach(this.items, (item: CartItem) => {
+        Row() {
+          Text(`${item.name}: $${item.price} × ${item.quantity}`)
+          Button('+').onClick(() => item.quantity++)
+        }
+      }, (item: CartItem, idx: number) => item.name + idx)
+      
+      Divider()
+      Text(`Subtotal: $${this.subtotal.toFixed(2)}`)
+      Text(`Tax (${this.taxRate * 100}%): $${this.tax.toFixed(2)}`)
+      Text(`Total: $${this.total.toFixed(2)}`).fontWeight(FontWeight.Bold)
+    }
+  }
+}
+
+// ============================================
+// 5. MONITOR CHANGES
+// ============================================
+@ObservedV2
+class Product {
+  @Trace name: string = "Laptop";
+  @Trace price: number = 1000;
+  @Trace stock: number = 10;
+  
+  @Monitor('price')
+  onPriceChange(monitor: IMonitor) {
+    const change = monitor.value();
+    console.log(`Price changed from ${change?.before} to ${change?.now}`);
+    if (change && change.now > change.before) {
+      console.log(`Price increased by ${change.now - change.before}`);
+    }
+  }
+  
+  @Monitor('stock')
+  onStockChange(monitor: IMonitor) {
+    const change = monitor.value();
+    if (change && change.now < 5) {
+      console.warn(`Low stock alert: ${change.now} items`);
+    }
+  }
+}
+
+@Entry
+@ComponentV2
+struct ProductManager {
+  product: Product = new Product();
+  
+  @Monitor('product.price', 'product.stock')
+  onProductChange(monitor: IMonitor) {
+    console.log('Product properties changed:', monitor.dirty);
+  }
+  
+  build() {
+    Column({ space: 10 }) {
+      Text(`${this.product.name}`)
+      Text(`Price: $${this.product.price}`)
+      Text(`Stock: ${this.product.stock}`)
+      
+      Button('Increase Price').onClick(() => {
+        this.product.price += 100;
+      })
+      Button('Decrease Stock').onClick(() => {
+        this.product.stock--;
+      })
+    }
+  }
+}
+
+// ============================================
+// 6. PROVIDER/CONSUMER (CROSS-LEVEL)
+// ============================================
+@Entry
+@ComponentV2
+struct AppRoot {
+  @Provider('app-theme') theme: string = 'light';
+  @Provider('user-name') userName: string = 'Alice';
+  
+  build() {
+    Column({ space: 20 }) {
+      Text(`App Theme: ${this.theme}`)
+      Button('Toggle Theme').onClick(() => {
+        this.theme = this.theme === 'light' ? 'dark' : 'light';
+      })
+      
+      MiddleComponent()
+    }
+  }
+}
+
+@ComponentV2
+struct MiddleComponent {
+  build() {
+    Column({ space: 10 }) {
+      Text('Middle Component')
+      DeepNestedComponent()
+    }
+  }
+}
+
+@ComponentV2
+struct DeepNestedComponent {
+  @Consumer('app-theme') theme: string = 'default';
+  @Consumer('user-name') userName: string = 'Guest';
+  
+  build() {
+    Column({ space: 10 }) {
+      Text(`User: ${this.userName}`)
+      Text(`Theme: ${this.theme}`)
+        .backgroundColor(this.theme === 'dark' ? Color.Black : Color.White)
+        .fontColor(this.theme === 'dark' ? Color.White : Color.Black)
+      
+      Button('Change from Deep Component').onClick(() => {
+        this.theme = 'custom';  // Updates provider in AppRoot
+      })
+    }
+  }
+}
+
+// ============================================
+// 7. FORM INPUT PATTERN
+// ============================================
+@ObservedV2
+class FormData {
+  @Trace username: string = "";
+  @Trace email: string = "";
+  @Trace password: string = "";
+}
+
+@ComponentV2
+struct FormField {
+  @Param label: string = "";
+  @Param value: string = "";
+  @Param type: InputType = InputType.Normal;
+  @Event onChange: (text: string) => void = () => {};
+  
+  build() {
+    Column({ space: 5 }) {
+      Text(this.label).fontSize(14)
+      TextInput({ text: this.value })
+        .type(this.type)
+        .onChange((text: string) => this.onChange(text))
+    }
+  }
+}
+
+@Entry
+@ComponentV2
+struct RegistrationForm {
+  @Local formData: FormData = new FormData();
+  @Local isValid: boolean = false;
+  
+  @Monitor('formData.username', 'formData.email', 'formData.password')
+  validateForm(monitor: IMonitor) {
+    this.isValid = 
+      this.formData.username.length >= 3 &&
+      this.formData.email.includes('@') &&
+      this.formData.password.length >= 8;
+  }
+  
+  build() {
+    Column({ space: 15 }) {
+      Text('Registration').fontSize(24).fontWeight(FontWeight.Bold)
+      
+      FormField({
+        label: 'Username',
+        value: this.formData.username,
+        onChange: (text: string) => {
+          this.formData.username = text;
+        }
+      })
+      
+      FormField({
+        label: 'Email',
+        value: this.formData.email,
+        type: InputType.Email,
+        onChange: (text: string) => {
+          this.formData.email = text;
+        }
+      })
+      
+      FormField({
+        label: 'Password',
+        value: this.formData.password,
+        type: InputType.Password,
+        onChange: (text: string) => {
+          this.formData.password = text;
+        }
+      })
+      
+      Button('Submit')
+        .enabled(this.isValid)
+        .backgroundColor(this.isValid ? Color.Blue : Color.Gray)
+        .onClick(() => {
+          console.log('Form submitted:', this.formData);
+        })
+    }
+    .padding(20)
+  }
+}
+
+// ============================================
+// 8. TODO LIST EXAMPLE
+// ============================================
+@ObservedV2
+class TodoItem {
+  @Trace id: string;
+  @Trace title: string;
+  @Trace completed: boolean;
+  
+  constructor(title: string) {
+    this.id = Date.now().toString() + Math.random();
+    this.title = title;
+    this.completed = false;
+  }
+}
+
+@ObservedV2
+class TodoStore {
+  @Trace items: TodoItem[] = [];
+  
+  addItem(title: string): void {
+    this.items.push(new TodoItem(title));
+  }
+  
+  removeItem(id: string): void {
+    const index = this.items.findIndex(item => item.id === id);
+    if (index !== -1) {
+      this.items.splice(index, 1);
+    }
+  }
+  
+  toggleItem(id: string): void {
+    const item = this.items.find(item => item.id === id);
+    if (item) {
+      item.completed = !item.completed;
+    }
+  }
+}
+
+@ComponentV2
+struct TodoItemView {
+  @Param item: TodoItem = new TodoItem("");
+  @Event onToggle: () => void = () => {};
+  @Event onDelete: () => void = () => {};
+  
+  build() {
+    Row({ space: 10 }) {
+      Checkbox({ select: this.item.completed })
+        .onChange(() => this.onToggle())
+      
+      Text(this.item.title)
+        .decoration({ type: this.item.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
+        .opacity(this.item.completed ? 0.5 : 1)
+        .layoutWeight(1)
+      
+      Button('Delete')
+        .onClick(() => this.onDelete())
+    }
+    .padding(10)
+    .width('100%')
+  }
+}
+
+@Entry
+@ComponentV2
+struct TodoApp {
+  @Local store: TodoStore = new TodoStore();
+  @Local inputText: string = "";
+  
+  @Computed
+  get completedCount(): number {
+    return this.store.items.filter(item => item.completed).length;
+  }
+  
+  @Computed
+  get totalCount(): number {
+    return this.store.items.length;
+  }
+  
+  build() {
+    Column({ space: 15 }) {
+      Text('Todo List').fontSize(30).fontWeight(FontWeight.Bold)
+      
+      Text(`${this.completedCount} / ${this.totalCount} completed`)
+      
+      Row({ space: 10 }) {
+        TextInput({ text: this.inputText, placeholder: 'New task...' })
+          .layoutWeight(1)
+          .onChange((text: string) => {
+            this.inputText = text;
+          })
+        
+        Button('Add')
+          .enabled(this.inputText.trim().length > 0)
+          .onClick(() => {
+            if (this.inputText.trim()) {
+              this.store.addItem(this.inputText.trim());
+              this.inputText = "";
+            }
+          })
+      }
+      
+      List({ space: 5 }) {
+        ForEach(this.store.items, (item: TodoItem) => {
+          ListItem() {
+            TodoItemView({
+              item: item,
+              onToggle: () => this.store.toggleItem(item.id),
+              onDelete: () => this.store.removeItem(item.id)
+            })
+          }
+        }, (item: TodoItem) => item.id)
+      }
+      .layoutWeight(1)
+    }
+    .padding(20)
+    .height('100%')
+  }
+}
+
+// ============================================
+// 9. COLLECTION TYPES (Array, Map, Set)
+// ============================================
+@ObservedV2
+class CollectionDemo {
+  @Trace numbers: number[] = [1, 2, 3];
+  @Trace userMap: Map<string, string> = new Map([['id1', 'Alice'], ['id2', 'Bob']]);
+  @Trace tags: Set<string> = new Set(['typescript', 'arkts', 'harmonyos']);
+}
+
+@Entry
+@ComponentV2
+struct CollectionsExample {
+  demo: CollectionDemo = new CollectionDemo();
+  
+  build() {
+    Column({ space: 15 }) {
+      // Array
+      Text('Array:').fontWeight(FontWeight.Bold)
+      ForEach(this.demo.numbers, (num: number, idx: number) => {
+        Text(`[${idx}] = ${num}`)
+      }, (num: number, idx: number) => num.toString() + idx)
+      Button('Array.push').onClick(() => {
+        this.demo.numbers.push(Math.floor(Math.random() * 100));
+      })
+      
+      Divider()
+      
+      // Map
+      Text('Map:').fontWeight(FontWeight.Bold)
+      ForEach(Array.from(this.demo.userMap.entries()), (entry: [string, string]) => {
+        Text(`${entry[0]}: ${entry[1]}`)
+      }, (entry: [string, string]) => entry[0])
+      Button('Map.set').onClick(() => {
+        const id = 'id' + Date.now();
+        this.demo.userMap.set(id, 'New User');
+      })
+      
+      Divider()
+      
+      // Set
+      Text('Set:').fontWeight(FontWeight.Bold)
+      ForEach(Array.from(this.demo.tags.values()), (tag: string) => {
+        Text(`• ${tag}`)
+      }, (tag: string) => tag)
+      Button('Set.add').onClick(() => {
+        this.demo.tags.add('tag' + Date.now());
+      })
+    }
+    .padding(20)
+  }
+}
--- a/arkts-development/references/api-reference.md
+++ b/arkts-development/references/api-reference.md
@@ -70,17 +70,24 @@ router.back({
  url: 'pages/HomePage',
  params: { result: 'success' }
 });
+// Note: Previous page receives params via router.getParams()
 ```

 ### Get Parameters

 ```typescript
+// Define expected params interface
+interface PageParams {
+  id: number;
+  title?: string;
+}
+
 // In target page
 aboutToAppear(): void {
-  const params = router.getParams() as Record<string, Object>;
+  const params = router.getParams() as PageParams;
  if (params) {
-    const id = params['id'] as number;
-    const title = params['title'] as string;
+    const id = params.id;
+    const title = params.title;
  }
 }
 ```
--- a/arkts-development/references/arkguard-obfuscation.md
+++ b/arkts-development/references/arkguard-obfuscation.md
@@ -0,0 +1,126 @@
+# ArkGuard Code Obfuscation Guide
+
+ArkGuard is the officially recommended code obfuscation tool for HarmonyOS, designed to enhance application security and prevent reverse engineering.
+
+## Requirements
+
+- **DevEco Studio**: Version 5.0.3.600 or above
+- **Project Model**: Stage model only
+- **Effective Mode**: Only active in Release mode
+
+## Enabling Obfuscation
+
+Configure in the module's `build-profile.json5`:
+
+```json
+{
+  "arkOptions": {
+    "obfuscation": {
+      "ruleOptions": {
+        "enable": true,
+        "files": ["./obfuscation-rules.txt"]
+      },
+      "consumerFiles": ["./consumer-rules.txt"]
+    }
+  }
+}
+```
+
+## Obfuscation Rules Configuration
+
+Create `obfuscation-rules.txt` in the project root directory:
+
+```text
+# Enable property obfuscation
+-enable-property-obfuscation
+
+# Enable top-level scope name obfuscation
+-enable-toplevel-obfuscation
+
+# Enable filename obfuscation
+-enable-filename-obfuscation
+
+# Enable import/export name obfuscation
+-enable-export-obfuscation
+```
+
+## Whitelist Configuration
+
+Certain names must not be obfuscated (e.g., dynamic property names, API fields, database fields):
+
+```text
+# Keep property names
+-keep-property-name apiKey
+-keep-property-name userId
+-keep-property-name responseData
+
+# Keep global names
+-keep-global-name AppConfig
+
+# Keep file names
+-keep-file-name MainPage
+-keep-file-name LoginPage
+```
+
+## Configuration Files
+
+| Config File | Purpose | Editable | Scope |
+|-------------|---------|:--------:|-------|
+| `obfuscation-rules.txt` | Obfuscation rules applied when building this module | ✓ | Current module |
+| `consumer-rules.txt` | Obfuscation rules applied when this module is used as a dependency (recommended: keep rules only) | ✓ | Modules depending on this module |
+| `obfuscation.txt` | HAR/HSP build artifact, auto-generated | ✗ | Dependent modules |
+
+## Common Obfuscation Options
+
+| Option | Description |
+|--------|-------------|
+| `-enable-property-obfuscation` | Obfuscate object property names |
+| `-enable-toplevel-obfuscation` | Obfuscate top-level scope variable and function names |
+| `-enable-filename-obfuscation` | Obfuscate file names |
+| `-enable-export-obfuscation` | Obfuscate import/export names |
+| `-disable-obfuscation` | Temporarily disable obfuscation (for debugging) |
+
+## Whitelist Options
+
+| Option | Description |
+|--------|-------------|
+| `-keep-property-name <name>` | Preserve specified property name from obfuscation |
+| `-keep-global-name <name>` | Preserve specified global name from obfuscation |
+| `-keep-file-name <name>` | Preserve specified file name from obfuscation |
+
+## Troubleshooting
+
+### Diagnostic Steps
+
+1. **Confirm obfuscation is the cause**: Temporarily add `-disable-obfuscation` and check if the issue disappears
+2. **Locate the problematic field**: Identify the obfuscated field from crash logs
+3. **Add to whitelist**: Add the problematic field to the `-keep-property-name` whitelist
+
+### Common Scenarios Requiring Whitelisting
+
+- **Network requests**: Request parameter field names, response data field names
+- **Database operations**: Table field names
+- **System APIs**: System callback parameters
+- **Third-party library interfaces**: Field names required by third-party libraries
+
+### Example: Preserving Network Request Fields
+
+```text
+# API request/response fields
+-keep-property-name code
+-keep-property-name message
+-keep-property-name data
+-keep-property-name token
+-keep-property-name userId
+```
+
+## Verifying Obfuscation Results
+
+1. Switch to **Release** mode and build
+2. Inspect the build artifacts
+3. Use decompilation tools to verify that class/method/property names are obfuscated
+4. Test that the application functions correctly
+
+## References
+
+- [Huawei Official Documentation - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard)
--- a/arkts-development/references/codelinter.md
+++ b/arkts-development/references/codelinter.md
@@ -1,103 +1,103 @@
-# CodeLinter 代码检查工具
+# CodeLinter Code Analysis Tool

-codelinter 是 HarmonyOS 的代码检查与修复工具，可集成到门禁或 CI/CD 环境中。
+codelinter is a code analysis and auto-fix tool for HarmonyOS, suitable for integration into gating checks or CI/CD pipelines.

-## 命令格式
+## Command Format

 ```bash
 codelinter [options] [dir]
 ```

- `options`: 可选配置参数
- `dir`: 待检查的工程根目录（可选，默认为当前目录）
+- `options`: Optional configuration parameters
+- `dir`: Project root directory to check (optional, defaults to current directory)

-## 命令参数
+## Command Parameters

-| 参数 | 说明 |
-|------|------|
-| `--config, -c <filepath>` | 指定规则配置文件 (code-linter.json5) |
-| `--fix` | 检查同时执行自动修复 |
-| `--format, -f <format>` | 输出格式: `default`/`json`/`xml`/`html` |
-| `--output, -o <filepath>` | 指定结果保存位置（不在命令行显示） |
-| `--version, -v` | 查看版本 |
-| `--product, -p <productName>` | 指定生效的 product |
-| `--incremental, -i` | 仅检查 Git 增量文件（新增/修改/重命名） |
-| `--help, -h` | 查询帮助 |
-| `--exit-on, -e <levels>` | 指定返回非零退出码的告警级别 |
+| Parameter | Description |
+|-----------|-------------|
+| `--config, -c <filepath>` | Specify rule configuration file (code-linter.json5) |
+| `--fix` | Check and apply auto-fixes simultaneously |
+| `--format, -f <format>` | Output format: `default`/`json`/`xml`/`html` |
+| `--output, -o <filepath>` | Specify output file path (suppresses console output) |
+| `--version, -v` | Show version |
+| `--product, -p <productName>` | Specify the active product |
+| `--incremental, -i` | Check only Git incremental files (added/modified/renamed) |
+| `--help, -h` | Show help |
+| `--exit-on, -e <levels>` | Specify warning levels that trigger a non-zero exit code |

-## 基本用法
+## Basic Usage

-### 在工程根目录下执行
+### Run in the Project Root Directory

 ```bash
-# 使用默认规则检查当前工程
+# Check current project with default rules
 codelinter

-# 指定规则配置文件
+# Specify a rule configuration file
 codelinter -c ./code-linter.json5

-# 检查并自动修复
+# Check and apply auto-fixes
 codelinter -c ./code-linter.json5 --fix
 ```

-### 在非工程目录下执行
+### Run Outside the Project Directory

 ```bash
-# 检查指定工程目录
+# Check a specific project directory
 codelinter /path/to/project

-# 检查多个目录或文件
+# Check multiple directories or files
 codelinter dir1 dir2 file1.ets

-# 指定规则文件和工程目录
+# Specify rule file and project directory
 codelinter -c /path/to/code-linter.json5 /path/to/project

-# 检查并修复指定工程
+# Check and fix a specific project
 codelinter -c ./code-linter.json5 /path/to/project --fix
 ```

-## 输出格式
+## Output Formats

 ```bash
-# 默认文本格式输出到命令行
+# Default text format to console
 codelinter /path/to/project

-# JSON 格式输出
+# JSON format output
 codelinter /path/to/project -f json

-# HTML 格式保存到文件
+# HTML format saved to file
 codelinter /path/to/project -f html -o ./report.html

-# XML 格式保存到文件
+# XML format saved to file
 codelinter /path/to/project -f xml -o ./report.xml
 ```

-## 增量检查
+## Incremental Checking

-对 Git 工程中的增量文件执行检查（仅检查新增、修改、重命名的文件）：
+Check only incremental files in a Git project (only added, modified, or renamed files):

 ```bash
 codelinter -i
 codelinter --incremental
 ```

-## 指定 Product
+## Specifying a Product

-当工程存在多个 product 时，指定生效的 product：
+When the project has multiple products, specify the active product:

 ```bash
 codelinter -p free /path/to/project
 codelinter --product default
 ```

-## 退出码 (--exit-on)
+## Exit Codes (--exit-on)

-用于 CI/CD 中根据告警级别控制流程。告警级别：`error`、`warn`、`suggestion`
+Used in CI/CD to control the pipeline based on warning levels. Warning levels: `error`, `warn`, `suggestion`

-退出码计算方式（3位二进制数，从高到低表示 error, warn, suggestion）：
+Exit code calculation (3-bit binary number, from high to low representing error, warn, suggestion):

-| 配置 | 检查结果包含 | 二进制 | 退出码 |
-|------|-------------|--------|--------|
+| Configuration | Check Results Include | Binary | Exit Code |
+|---------------|---------------------|--------|-----------|
 | `--exit-on error` | error, warn, suggestion | 100 | 4 |
 | `--exit-on error` | warn, suggestion | 000 | 0 |
 | `--exit-on error,warn` | error, warn | 110 | 6 |
@@ -105,40 +105,40 @@ codelinter --product default
 | `--exit-on error,warn,suggestion` | error, warn, suggestion | 111 | 7 |

 ```bash
-# 仅 error 级别返回非零退出码
+# Non-zero exit code only for error level
 codelinter --exit-on error

-# error 和 warn 级别返回非零退出码
+# Non-zero exit code for error and warn levels
 codelinter --exit-on error,warn

-# 所有级别都返回非零退出码
+# Non-zero exit code for all levels
 codelinter --exit-on error,warn,suggestion
 ```

-## CI/CD 集成示例
+## CI/CD Integration Examples

 ```bash
-# 完整的 CI 检查流程
+# Full CI check pipeline
 codelinter -c ./code-linter.json5 \
  -f json \
  -o ./codelinter-report.json \
  --exit-on error,warn

-# 增量检查（仅检查变更文件）
+# Incremental check (changed files only)
 codelinter -i -c ./code-linter.json5 --exit-on error

-# 检查并自动修复，生成 HTML 报告
+# Check with auto-fix, generate HTML report
 codelinter -c ./code-linter.json5 \
  --fix \
  -f html \
  -o ./codelinter-report.html
 ```

-## 规则配置文件 (code-linter.json5)
+## Rule Configuration File (code-linter.json5)

-默认规则清单可在检查完成后，根据命令行提示查看生成的 `code-linter.json5` 文件。
+The default rule list can be viewed in the generated `code-linter.json5` file, as indicated by the console output after a check completes.

-示例配置：
+Example configuration:

 ```json5
 {
--- a/arkts-development/references/hstack.md
+++ b/arkts-development/references/hstack.md
@@ -1,92 +1,92 @@
-# 堆栈解析工具 (hstack)
+# Stack Trace Analysis Tool (hstack)

-hstack 是用于将 Release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台。
+hstack is a tool for resolving obfuscated crash stack traces from Release builds back to their original source code locations. It supports Windows, Mac, and Linux.

-## 命令格式
+## Command Format

 ```bash
 hstack [options]
 ```

-## 命令参数
+## Command Parameters

-| 参数 | 说明 |
-|------|------|
-| `-i, --input` | 指定 crash 文件归档目录 |
-| `-c, --crash` | 指定一条 crash 堆栈 |
-| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） |
-| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 |
-| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 |
-| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 |
-| `-v, --version` | 查看版本 |
-| `-h, --help` | 查询帮助 |
+| Parameter | Description |
+|-----------|-------------|
+| `-i, --input` | Specify the crash file archive directory |
+| `-c, --crash` | Specify a single crash stack trace |
+| `-o, --output` | Specify the output directory for parsed results (output file when using `-c`) |
+| `-s, --sourcemapDir` | Specify the sourcemap file archive directory |
+| `--so, --soDir` | Specify the shared object (.so) file archive directory |
+| `-n, --nameObfuscation` | Specify the nameCache file archive directory |
+| `-v, --version` | Show version |
+| `-h, --help` | Show help |

-## 参数约束
+## Parameter Constraints

- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项**
- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项**
- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件
- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? ``
+- Crash file directory (`-i`) and crash stack trace (`-c`) **must provide exactly one**
+- Sourcemap (`-s`) and shared object (`--so`) directories **must provide at least one**
+- To restore obfuscated method names, **both** sourcemap and nameCache files must be provided
+- Path parameters do not support special characters: `` `~!@#$^&*=|{};,\s\[\]<>? ``

-## 环境配置
+## Environment Setup

-1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量
-2. 配置 Node.js 到环境变量
-3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH`
+1. Add the Command Line Tools `bin` directory to the PATH environment variable
+2. Add Node.js to the environment variables
+3. To parse C++ exceptions, add the SDK's `native\llvm\bin` directory to the `ADDR2LINE_PATH` environment variable

-## 使用示例
+## Usage Examples

-### 解析 crash 文件目录
+### Parse Crash File Directory

 ```bash
-# 完整解析命令
+# Full parse command
 hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir

-# 仅使用 sourcemap 解析 (ArkTS)
+# Parse using sourcemap only (ArkTS)
 hstack -i crashDir -o outputDir -s sourcemapDir

-# 仅使用 so 文件解析 (C++)
+# Parse using .so files only (C++)
 hstack -i crashDir -o outputDir --so soDir

-# 包含方法名还原
+# Include method name restoration
 hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
 ```

-### 解析单条堆栈
+### Parse a Single Stack Trace

 ```bash
-# 输出到控制台
+# Output to console
 hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir

-# 输出到文件
+# Output to file
 hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt
 ```

-## 输出说明
+## Output

- 解析结果输出到 `-o` 指定目录，文件以原始 crash 文件名加 `_` 前缀命名
- 不指定 `-o` 时：
-  - 使用 `-i` 输入：输出到 crashDir 目录
-  - 使用 `-c` 输入：直接输出到控制台
+- Parsed results are written to the directory specified by `-o`, with filenames prefixed by `_` followed by the original crash filename
+- When `-o` is not specified:
+  - With `-i` input: output to the crashDir directory
+  - With `-c` input: output directly to console

-## 文件获取
+## File Sources

-### Sourcemap 文件
+### Sourcemap Files

-构建产物中的 sourcemap 文件，包含：
- 路径信息映射
- 行列号映射 (mappings 字段)
- package-info 信息
+Sourcemap files from build artifacts, containing:
+- Path information mapping
+- Line/column number mapping (mappings field)
+- package-info information

-### NameCache 文件
+### NameCache Files

-构建产物中的 nameCache 文件，包含：
- `IdentifierCache`: 标识符混淆映射
- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"`
+NameCache files from build artifacts, containing:
+- `IdentifierCache`: Identifier obfuscation mapping
+- `MemberMethodCache`: Member method obfuscation mapping, format: `"sourceMethodName:startLine:endLine": "obfuscatedMethodName"`

-### Shared Object (.so) 文件
+### Shared Object (.so) Files

-构建 Release 应用时，默认 so 文件不包含符号表。如需生成包含符号表的 so 文件，在模块 `build-profile.json5` 中配置：
+When building Release applications, .so files do not include symbol tables by default. To generate .so files with symbol tables, configure in the module's `build-profile.json5`:

 ```json5
 {
@@ -98,46 +98,46 @@ hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s source
 }
 ```

-## 堆栈解析原理
+## Stack Trace Resolution Principles

-### Crash 堆栈格式
+### Crash Stack Format

 ```
 at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58)
 at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
 ```

-路径格式：`引用方packageName|被引用方packageName|version|源码相对路径`
+Path format: `referrerPackageName|referredPackageName|version|sourceRelativePath`

-### 解析步骤
+### Resolution Steps

-1. **根据路径信息找到 sourcemap**
-   - 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段
+1. **Find the sourcemap based on path information**
+   - From the path `entry|har|1.0.0|src/main/ets/...`, look up the corresponding field in the entry module's sourcemap

-2. **利用 sourcemap 还原路径和行列号**
-   - 根据 `sources` 和 `mappings` 字段解析
-   - 如包含 `package-info`，可进行二次解析获取更准确的源码位置
+2. **Restore path and line/column numbers using sourcemap**
+   - Parse using the `sources` and `mappings` fields
+   - If `package-info` is included, perform a secondary parse for more accurate source locations

-3. **利用 nameCache 还原方法名**
-   - 查找混淆后方法名对应的所有条目
-   - 根据还原后的行号范围匹配正确的源码方法名
+3. **Restore method names using nameCache**
+   - Find all entries matching the obfuscated method name
+   - Match the correct source method name based on the restored line number range

-### 解析示例
+### Resolution Example

-原始堆栈：
+Original stack trace:
 ```
 at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
 ```

-还原后：
+After resolution:
 ```
 at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)
 ```

-## CI/CD 集成
+## CI/CD Integration

 ```bash
-# 自动化解析脚本示例
+# Automated parsing script example
 hstack \
  -i ./crash-logs \
  -o ./parsed-logs \
@@ -146,8 +146,8 @@ hstack \
  -n ./build/nameCache
 ```

-## 常见问题
+## FAQ

-1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数
-2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置
-3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项
+1. **Method names not restored**: Ensure both `-s` and `-n` parameters are provided
+2. **C++ stack traces not parsed**: Check the `ADDR2LINE_PATH` environment variable configuration
+3. **No symbol table in .so files**: Configure the `RelWithDebInfo` build option
--- a/arkts-development/references/hvigor-commandline.md
+++ b/arkts-development/references/hvigor-commandline.md
@@ -1,179 +1,179 @@
-# Hvigor 命令行构建工具 (hvigorw)
+# Hvigor Command-Line Build Tool (hvigorw)

-hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。
+hvigorw is the Hvigor wrapper tool that supports automatic installation of the Hvigor build tool and its plugin dependencies, as well as executing Hvigor build commands.

-## 命令格式
+## Command Format

 ```bash
 hvigorw [taskNames...] <options>
 ```

-## 编译构建任务
+## Build Tasks

-| 任务 | 说明 |
-|------|------|
-| `clean` | 清理构建产物 build 目录 |
-| `assembleHap` | 构建 Hap 应用 |
-| `assembleApp` | 构建 App 应用 |
-| `assembleHsp` | 构建 Hsp 包 |
-| `assembleHar` | 构建 Har 包 |
-| `collectCoverage` | 基于打点数据生成覆盖率统计报表 |
+| Task | Description |
+|------|-------------|
+| `clean` | Clean build artifacts in the build directory |
+| `assembleHap` | Build HAP application |
+| `assembleApp` | Build APP application |
+| `assembleHsp` | Build HSP package |
+| `assembleHar` | Build HAR package |
+| `collectCoverage` | Generate coverage statistics report from instrumented data |

-## 常用构建参数
+## Common Build Parameters

-| 参数 | 说明 |
-|------|------|
-| `-p buildMode={debug\|release}` | 指定构建模式。默认：Hap/Hsp/Har 为 debug，App 为 release |
-| `-p debuggable=true/false` | 覆盖 buildOption 中的 debuggable 配置 |
-| `-p product={ProductName}` | 指定 product 进行编译，默认为 default |
-| `-p module={ModuleName}@{TargetName}` | 指定模块及 target 编译（需配合 `--mode module`） |
-| `-p ohos-test-coverage={true\|false}` | 执行测试框架代码覆盖率插桩编译 |
-| `-p parameterFile=param.json` | 设置 oh-package.json5 的参数配置文件 |
+| Parameter | Description |
+|-----------|-------------|
+| `-p buildMode={debug\|release}` | Specify build mode. Default: debug for Hap/Hsp/Har, release for App |
+| `-p debuggable=true/false` | Override the debuggable setting in buildOption |
+| `-p product={ProductName}` | Specify product for compilation, defaults to default |
+| `-p module={ModuleName}@{TargetName}` | Specify module and target for compilation (requires `--mode module`) |
+| `-p ohos-test-coverage={true\|false}` | Enable test framework code coverage instrumentation |
+| `-p parameterFile=param.json` | Set parameter configuration file for oh-package.json5 |

-## 构建示例
+## Build Examples

 ```bash
-# 清理构建产物
+# Clean build artifacts
 hvigorw clean

-# Debug 模式构建 Hap
+# Build HAP in debug mode
 hvigorw assembleHap -p buildMode=debug

-# Release 模式构建 App
+# Build APP in release mode
 hvigorw assembleApp -p buildMode=release

-# 构建指定 product
+# Build a specific product
 hvigorw assembleHap -p product=free

-# 构建指定模块
+# Build a specific module
 hvigorw assembleHap -p module=entry@default --mode module

-# 构建多个模块
+# Build multiple modules
 hvigorw assembleHar -p module=library1@default,library2@default --mode module
 ```

-## 测试命令
+## Test Commands

-### Instrument Test (设备测试)
+### Instrument Test (On-Device Test)

 ```bash
 hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
 ```

- `module`: 执行测试的模块，缺省执行所有模块
- `coverage`: 是否生成覆盖率报告，默认 true
- `scope`: 测试范围，格式 `{suiteName}#{methodName}` 或 `{suiteName}`
- `ohos-debug-asan`: 是否启用 ASan 检测，默认 false (5.19.0+)
+- `module`: Module to test; omit to test all modules
+- `coverage`: Whether to generate coverage report, defaults to true
+- `scope`: Test scope, format `{suiteName}#{methodName}` or `{suiteName}`
+- `ohos-debug-asan`: Whether to enable ASan detection, defaults to false (5.19.0+)

-**输出路径:**
- 覆盖率报告: `<module-path>/.test/default/outputs/ohosTest/reports`
- 测试结果: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt`
+**Output paths:**
+- Coverage report: `<module-path>/.test/default/outputs/ohosTest/reports`
+- Test results: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt`

-### Local Test (本地测试)
+### Local Test

 ```bash
 hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
 ```

-**输出路径:**
- 覆盖率报告: `<module-path>/.test/default/outputs/test/reports`
- 测试结果: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt`
+**Output paths:**
+- Coverage report: `<module-path>/.test/default/outputs/test/reports`
+- Test results: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt`

-## 日志级别
+## Log Levels

-| 参数 | 说明 |
-|------|------|
-| `-e, --error` | 设置日志级别为 error |
-| `-w, --warn` | 设置日志级别为 warn |
-| `-i, --info` | 设置日志级别为 info |
-| `-d, --debug` | 设置日志级别为 debug |
-| `--stacktrace` | 开启打印异常堆栈信息 |
+| Parameter | Description |
+|-----------|-------------|
+| `-e, --error` | Set log level to error |
+| `-w, --warn` | Set log level to warn |
+| `-i, --info` | Set log level to info |
+| `-d, --debug` | Set log level to debug |
+| `--stacktrace` | Enable exception stack trace printing |

-## 构建分析 (Build Analyzer)
+## Build Analyzer

-| 参数 | 说明 |
-|------|------|
-| `--analyze=normal` | 普通模式分析 |
-| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 |
-| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) |
-| `--analyze=false` | 不启用构建分析 |
-| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` |
+| Parameter | Description |
+|-----------|-------------|
+| `--analyze=normal` | Normal mode analysis |
+| `--analyze=advanced` | Advanced mode with detailed task timing data |
+| `--analyze=ultrafine` | Ultra-fine mode with detailed ArkTS compilation instrumentation (6.0.0+) |
+| `--analyze=false` | Disable build analysis |
+| `--config properties.hvigor.analyzeHtml=true` | Generate HTML visual report to `.hvigor/report` |

-## 守护进程 (Daemon)
+## Daemon

-| 参数 | 说明 |
-|------|------|
-| `--daemon` | 启用守护进程 |
-| `--no-daemon` | 关闭守护进程（命令行模式推荐） |
-| `--stop-daemon` | 关闭当前工程的守护进程 |
-| `--stop-daemon-all` | 关闭所有工程的守护进程 |
-| `--status-daemon` | 查询所有 Hvigor 守护进程信息 |
-| `--max-old-space-size=12345` | 设置老生代内存大小 (MB) |
-| `--max-semi-space-size=32` | 设置新生代半空间大小 (MB, 5.18.4+) |
+| Parameter | Description |
+|-----------|-------------|
+| `--daemon` | Enable daemon process |
+| `--no-daemon` | Disable daemon process (recommended for CLI mode) |
+| `--stop-daemon` | Stop the daemon for the current project |
+| `--stop-daemon-all` | Stop all project daemons |
+| `--status-daemon` | Query all Hvigor daemon process information |
+| `--max-old-space-size=12345` | Set old generation memory size (MB) |
+| `--max-semi-space-size=32` | Set new generation semi-space size (MB, 5.18.4+) |

-## 性能与内存优化
+## Performance and Memory Optimization

-| 参数 | 说明 |
-|------|------|
-| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） |
-| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） |
-| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) |
-| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) |
+| Parameter | Description |
+|-----------|-------------|
+| `--parallel` / `--no-parallel` | Enable/disable parallel builds (enabled by default) |
+| `--incremental` / `--no-incremental` | Enable/disable incremental builds (enabled by default) |
+| `--optimization-strategy=performance` | Performance-first mode, faster builds but higher memory usage (5.19.2+) |
+| `--optimization-strategy=memory` | Memory-first mode (default) (5.19.2+) |

-## 公共命令
+## Utility Commands

-| 任务 | 说明 |
-|------|------|
-| `tasks` | 打印工程各模块包含的任务信息 |
-| `taskTree` | 打印工程各模块的任务依赖关系 |
-| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 |
-| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) |
+| Task | Description |
+|------|-------------|
+| `tasks` | Print task information for all project modules |
+| `taskTree` | Print task dependency graph for all project modules |
+| `prune` | Clean caches unused for 30 days and remove unreferenced pnpm packages |
+| `buildInfo` | Print build-profile.json5 configuration information (5.18.4+) |

-### buildInfo 扩展参数
+### buildInfo Extended Parameters

 ```bash
-# 打印工程级配置
+# Print project-level configuration
 hvigorw buildInfo

-# 打印指定模块配置
+# Print configuration for a specific module
 hvigorw buildInfo -p module=entry

-# 包含 buildOption 配置
+# Include buildOption configuration
 hvigorw buildInfo -p buildOption

-# JSON 格式输出
+# JSON format output
 hvigorw buildInfo -p json
 ```

-## 其他参数
+## Other Parameters

-| 参数 | 说明 |
-|------|------|
-| `-h, --help` | 打印帮助信息 |
-| `-v, --version` | 打印版本信息 |
-| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` |
-| `-m, --mode` | 指定执行目录级别 (如 `-m project`) |
-| `--type-check` | 开启 hvigorfile.ts 类型检查 |
-| `--watch` | 观察模式，用于预览和热加载 |
-| `--node-home <string>` | 指定 Node.js 路径 |
-| `--config, -c` | 指定 hvigor-config.json5 参数 |
+| Parameter | Description |
+|-----------|-------------|
+| `-h, --help` | Print help information |
+| `-v, --version` | Print version information |
+| `-s, --sync` | Sync project information to `./hvigor/outputs/sync/output.json` |
+| `-m, --mode` | Specify execution directory level (e.g., `-m project`) |
+| `--type-check` | Enable type checking for hvigorfile.ts |
+| `--watch` | Watch mode for preview and hot reload |
+| `--node-home <string>` | Specify Node.js path |
+| `--config, -c` | Specify hvigor-config.json5 parameters |

-## CI/CD 常用命令组合
+## CI/CD Common Command Combinations

 ```bash
-# 完整的 Release 构建流程
+# Full release build pipeline
 hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon

-# 带构建分析的 Debug 构建
+# Debug build with build analysis
 hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon

-# 运行测试并生成覆盖率报告
+# Run tests and generate coverage report
 hvigorw onDeviceTest -p coverage=true --no-daemon

-# 内存受限环境构建
+# Build in memory-constrained environment
 hvigorw assembleHap --optimization-strategy=memory --no-daemon

-# 清理缓存
+# Clean caches
 hvigorw prune
 hvigorw --stop-daemon-all
 ```
--- a/arkts-development/references/state-management-v2.md
+++ b/arkts-development/references/state-management-v2.md
--- 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
+├── 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
cheliangzhao	7f1ff2df6b	feat: add comprehensive State Management V2 documentation - Add complete V2 decorators guide (state-management-v2.md, 38KB) - @ComponentV2, @Local, @Param, @Event - @ObservedV2, @Trace, @Computed, @Monitor - @Provider/@Consumer for cross-level sync - V1 vs V2 comparison and migration guide - Best practices and troubleshooting - Add 9 practical V2 code examples (state-management-v2-examples.ets, 13KB) - Basic components, nested objects, parent-child communication - Computed properties, monitors, providers/consumers - Real-world patterns: forms, todo lists, collections - Update SKILL.md with V2 decorators reference table - Source: Official OpenHarmony documentation (API 12+)	2026-02-10 21:00:52 +08:00
cheliangzhao	9d902b1074	fix: improve type safety and error handling in arkts-development - Replace Record<string, Object> with specific interface types for router params - Add error handling catch block to list-page-template.ets - Add clarification note for router.back() with params - Improve type safety following ArkTS best practices	2026-02-10 20:52:17 +08:00
cheliangzhao	81b3c82d16	docs: translate reference documentation from Chinese to English - Translate arkguard-obfuscation.md (ArkGuard code obfuscation guide) - Translate hstack.md (stack trace analysis tool) - Translate codelinter.md (code linting tool) - Translate hvigor-commandline.md (Hvigor build tool) - Fix capitalization: ArkTs -> ArkTS in README title	2026-02-10 20:38:13 +08:00
cheliangzhao	a68f3d1a7d	fix: remove platform-specific references from README	2026-02-10 20:29:39 +08:00
cheliangzhao	4565396825	fix: clean up README and add .gitignore - Translate Quick Deploy section from Chinese to English - Fix repo slug from my-skills to arkts_skills - Add --skill flag usage examples for single skill install - Update directory tree to match actual repo structure - Add .gitignore for temp files, OS files, and editor files - Remove junk temp files from working tree	2026-02-10 20:16:13 +08:00
cheliangzhao	a984e27246	fix: move skill directories to repo root and update AGENTS.md structure diagram	2026-02-10 20:04:27 +08:00
cheliangzhao	2378b310a5	Reorganize skill files into skills/ subdirectory	2026-02-10 16:59:56 +08:00