From a984e272468b8bcbe775cbd22ee0e43c326dafc8 Mon Sep 17 00:00:00 2001 From: cheliangzhao Date: Tue, 10 Feb 2026 20:04:27 +0800 Subject: [PATCH] fix: move skill directories to repo root and update AGENTS.md structure diagram --- AGENTS.md | 258 ++++++++---------- .../SKILL.md | 0 .../assets/component-template.ets | 0 .../assets/list-page-template.ets | 0 .../references/api-reference.md | 0 .../references/arkguard-obfuscation.md | 0 .../references/codelinter.md | 0 .../references/component-patterns.md | 0 .../references/hstack.md | 0 .../references/hvigor-commandline.md | 0 .../references/migration-guide.md | 0 .../SKILL.md | 0 .../references/device-installation.md | 0 13 files changed, 113 insertions(+), 145 deletions(-) rename {skills/arkts-development => arkts-development}/SKILL.md (100%) rename {skills/arkts-development => arkts-development}/assets/component-template.ets (100%) rename {skills/arkts-development => arkts-development}/assets/list-page-template.ets (100%) rename {skills/arkts-development => arkts-development}/references/api-reference.md (100%) rename {skills/arkts-development => arkts-development}/references/arkguard-obfuscation.md (100%) rename {skills/arkts-development => arkts-development}/references/codelinter.md (100%) rename {skills/arkts-development => arkts-development}/references/component-patterns.md (100%) rename {skills/arkts-development => arkts-development}/references/hstack.md (100%) rename {skills/arkts-development => arkts-development}/references/hvigor-commandline.md (100%) rename {skills/arkts-development => arkts-development}/references/migration-guide.md (100%) rename {skills/harmonyos-build-deploy => harmonyos-build-deploy}/SKILL.md (100%) rename {skills/harmonyos-build-deploy => harmonyos-build-deploy}/references/device-installation.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 3449947..f503c55 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,115 +1,126 @@ # 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 -ohpm clean && ohpm cache clean # Deep clean +# 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 ``` -### Code Linter (codelinter) +### Dependencies (ohpm) ```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 +ohpm install --all # Install all deps +ohpm clean && ohpm cache clean # Deep clean ``` -### Device Commands (hdc) +### Lint (codelinter) ```bash -hdc list targets # List devices (returns UDID) -hdc -t file send # Push files -hdc -t shell "bm install -p " # Install app -hdc -t shell "aa start -a EntryAbility -b " # Launch app +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 (hdc) + +```bash +hdc list targets # List devices (returns UDID) +hdc -t file send # Push files +hdc -t shell "bm install -p " # Install app +hdc -t shell "aa start -a EntryAbility -b " # Launch app ``` ## Code Style Guidelines ### 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 | -| `#privateField` | `private` keyword | -| Structural typing | Explicit `implements`/`extends` | +| Prohibited | Use Instead | +|-------------------------|------------------------------------| +| `any`, `unknown` | Explicit types, interfaces | +| `var` | `let`, `const` | +| `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` | +| `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` | -| Constants | camelCase or UPPER_SNAKE | `maxRetries`, `API_URL` | -| Files (skill docs) | kebab-case | `api-reference.md` | -| Skill directories | kebab-case | `arkts-development` | +| Element | Convention | Example | +|-----------------------|-----------------|-----------------------------| +| Components (struct) | PascalCase | `HomePage`, `UserCard` | +| Interfaces | PascalCase | `UserInfo`, `ApiResponse` | +| Methods / Functions | camelCase | `loadData()`, `handleClick` | +| Properties / Variables| camelCase | `isLoading`, `userName` | +| Constants | camelCase or UPPER_SNAKE | `maxRetries`, `API_URL` | +| 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 { } 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 { } - - // 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 { @@ -149,81 +158,40 @@ async loadData(): Promise { } ``` -### 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. diff --git a/skills/arkts-development/SKILL.md b/arkts-development/SKILL.md similarity index 100% rename from skills/arkts-development/SKILL.md rename to arkts-development/SKILL.md diff --git a/skills/arkts-development/assets/component-template.ets b/arkts-development/assets/component-template.ets similarity index 100% rename from skills/arkts-development/assets/component-template.ets rename to arkts-development/assets/component-template.ets diff --git a/skills/arkts-development/assets/list-page-template.ets b/arkts-development/assets/list-page-template.ets similarity index 100% rename from skills/arkts-development/assets/list-page-template.ets rename to arkts-development/assets/list-page-template.ets diff --git a/skills/arkts-development/references/api-reference.md b/arkts-development/references/api-reference.md similarity index 100% rename from skills/arkts-development/references/api-reference.md rename to arkts-development/references/api-reference.md diff --git a/skills/arkts-development/references/arkguard-obfuscation.md b/arkts-development/references/arkguard-obfuscation.md similarity index 100% rename from skills/arkts-development/references/arkguard-obfuscation.md rename to arkts-development/references/arkguard-obfuscation.md diff --git a/skills/arkts-development/references/codelinter.md b/arkts-development/references/codelinter.md similarity index 100% rename from skills/arkts-development/references/codelinter.md rename to arkts-development/references/codelinter.md diff --git a/skills/arkts-development/references/component-patterns.md b/arkts-development/references/component-patterns.md similarity index 100% rename from skills/arkts-development/references/component-patterns.md rename to arkts-development/references/component-patterns.md diff --git a/skills/arkts-development/references/hstack.md b/arkts-development/references/hstack.md similarity index 100% rename from skills/arkts-development/references/hstack.md rename to arkts-development/references/hstack.md diff --git a/skills/arkts-development/references/hvigor-commandline.md b/arkts-development/references/hvigor-commandline.md similarity index 100% rename from skills/arkts-development/references/hvigor-commandline.md rename to arkts-development/references/hvigor-commandline.md diff --git a/skills/arkts-development/references/migration-guide.md b/arkts-development/references/migration-guide.md similarity index 100% rename from skills/arkts-development/references/migration-guide.md rename to arkts-development/references/migration-guide.md diff --git a/skills/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md similarity index 100% rename from skills/harmonyos-build-deploy/SKILL.md rename to harmonyos-build-deploy/SKILL.md diff --git a/skills/harmonyos-build-deploy/references/device-installation.md b/harmonyos-build-deploy/references/device-installation.md similarity index 100% rename from skills/harmonyos-build-deploy/references/device-installation.md rename to harmonyos-build-deploy/references/device-installation.md