From ed7ab751eb168b2842769015a9c6cc747b75d878 Mon Sep 17 00:00:00 2001 From: CHE LIANG ZHAO Date: Mon, 26 Jan 2026 10:50:52 +0800 Subject: [PATCH] Add AGENTS.md documentation for AI coding agents --- AGENTS.md | 229 ++++++++++++++++++++++++++++++++ harmonyos-build-deploy/SKILL.md | 34 +++++ 2 files changed, 263 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3449947 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,229 @@ +# 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. + +## 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 +``` + +## Build/Lint/Test Commands + +This is a documentation repository - no build system for the repo itself. However, the skills document these HarmonyOS CLI tools: + +### Build Commands (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 +``` + +### Package Manager (ohpm) + +```bash +ohpm install --all # Install all dependencies +ohpm clean && ohpm cache clean # Deep clean +``` + +### Code Linter (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 +``` + +### Device Commands (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: + +| 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` | + +### 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` | + +### Type Annotations + +Always use explicit type annotations: + +```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) +``` + +### Component Structure + +Follow this standard component layout: + +```typescript +@Entry +@Component +struct ComponentName { + // 1. State decorators + @State isLoading: boolean = false; + @State errorMessage: string = ''; + + // 2. Lifecycle methods + aboutToAppear(): void { this.loadData(); } + aboutToDisappear(): void { /* cleanup */ } + + // 3. Business methods + async loadData(): Promise { } + + // 4. Builder methods (reusable UI blocks) + @Builder ItemCard(item: ItemType) { } + + // 5. Build method (always last) + build() { } +} +``` + +### Error Handling Pattern + +```typescript +async loadData(): Promise { + this.isLoading = true; + try { + // async operation + } catch (error) { + this.errorMessage = 'Failed to load data'; + } finally { + this.isLoading = false; + } +} +``` + +### 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: + +```typescript +ForEach(this.items, (item: ItemType) => { + ListItem() { Text(item.title) } +}, (item: ItemType) => item.id) // Key generator for efficient updates +``` diff --git a/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md index e7759b6..8aea1e2 100644 --- a/harmonyos-build-deploy/SKILL.md +++ b/harmonyos-build-deploy/SKILL.md @@ -7,6 +7,40 @@ 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 + +**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. + +Use the following question configuration: + +```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:** +- Different scenarios require different operations (e.g., incremental build vs clean build) +- Avoid unnecessary time-consuming operations +- Give user control over the workflow +- Prevent accidental device installation + +**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