Add AGENTS.md documentation for AI coding agents

2026-01-26 10:50:52 +08:00
parent 545efe99ba
commit ed7ab751eb
2 changed files with 263 additions and 0 deletions
--- a/AGENTS.md
+++ 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 <UDID> file send <local> <remote>  # Push files
+hdc -t <UDID> shell "bm install -p <path>" # Install app
+hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>" # 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<void> { }
+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<void> { }
+
+  // 4. Builder methods (reusable UI blocks)
+  @Builder ItemCard(item: ItemType) { }
+
+  // 5. Build method (always last)
+  build() { }
+}
+```
+
+### Error Handling Pattern
+
+```typescript
+async loadData(): Promise<void> {
+  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
+```
--- 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