Back to Details

hmos-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HarmonyOS ArkTS 开发助手

HarmonyOS ArkTS Development Assistant

目的

Purpose

为 HarmonyOS NEXT 应用开发提供全面支持，使用 ArkTS 和 @ComponentV2 架构。本 skill 结合了：
  1. 开发指导：官方 HarmonyOS 开发标准，涵盖 MVVM 架构、@ComponentV2 组件模式、Navigation 路由、状态管理和代码组织
  2. 智能错误调试：分类错误日志系统，通过搜索已知解决方案实现快速错误解决
  3. 知识积累：自动记录新遇到的错误及其解决方案，供未来参考
Provides comprehensive support for HarmonyOS NEXT application development using ArkTS and @ComponentV2 architecture. This skill combines:
  1. Development Guidance: Official HarmonyOS development standards covering MVVM architecture, @ComponentV2 component patterns, Navigation routing, state management, and code organization
  2. Intelligent Error Debugging: Categorized error log system for quick error resolution by searching known solutions
  3. Knowledge Accumulation: Automatically records newly encountered errors and their solutions for future reference

何时使用本 Skill

When to Use This Skill

本 skill 在以下场景自动触发：
  1. 文件操作：读取、写入或编辑 
    .ets
    文件（HarmonyOS ArkTS 源文件）时
  2. 明确的 HarmonyOS 开发：用户提到 "HarmonyOS"、"ArkTS"、"@ComponentV2" 或相关开发关键词时
  3. 错误调试：用户请求调试帮助、错误调查或 HarmonyOS 上下文中的故障排查时
This skill triggers automatically in the following scenarios:
  1. File Operations: When reading, writing, or editing 
    .ets
    files (HarmonyOS ArkTS source files)
  2. Explicit HarmonyOS Development: When users mention "HarmonyOS", "ArkTS", "@ComponentV2" or related development keywords
  3. Error Debugging: When users request debugging help, error investigation, or troubleshooting in a HarmonyOS context

开发工作流程

Development Workflow

1. 开发指导

1. Development Guidance

实现 HarmonyOS 功能或组件时：
步骤 1：查阅开发指南
加载并参考 
references/development-guide.md
以获取：
  • 项目结构和文件组织（第 1-2 节）
  • @ComponentV2 组件模式和装饰器（第 3 节）
  • MVVM 架构设计（第 4 节）
  • 数据模型和服务层设计（第 5-7 节）
  • Navigation API 路由管理（第 10 节）
  • 状态管理最佳实践（第 11 节）
  • 性能优化（第 12 节）
  • 错误处理和日志标准（第 13-14 节）
步骤 2：遵循架构原则
遵守指南中的核心原则：
  • 组件组织：遵循"就近原则"放置组件（页面专属 → 模块共享 → 全局共享）
  • MVVM 分离：业务逻辑在 ViewModel，UI 渲染在 Page 组件
  • V2 装饰器系统：使用 @ComponentV2 配合 @Param/@Local，避免混用 V1 装饰器（@State/@Observed）
  • 资源管理：使用 
    $r('app.xxx')
    引用资源，使用 ThemeSizeTokens 常量定义尺寸
步骤 3：应用命名规范
遵循命名标准：
  • 文件：PascalCase（如 
    ProductListPage.ets
    ）
  • 类/结构体：PascalCase
  • 方法/变量：camelCase
  • 常量：SCREAMING_SNAKE_CASE
  • 组件 Props 接口：以 
    Props
    结尾
步骤 4：代码审查
完成前，根据代码审查清单验证（development-guide.md 第 15 节）。
When implementing HarmonyOS features or components:
Step 1: Consult the Development Guide
Load and reference 
references/development-guide.md
for:
  • Project structure and file organization (Sections 1-2)
  • @ComponentV2 component patterns and decorators (Section 3)
  • MVVM architecture design (Section 4)
  • Data model and service layer design (Sections 5-7)
  • Navigation API routing management (Section 10)
  • State management best practices (Section 11)
  • Performance optimization (Section 12)
  • Error handling and logging standards (Sections 13-14)
Step 2: Follow Architecture Principles
Adhere to the core principles in the guide:
  • Component Organization: Place components following the "proximity principle" (page-specific → module-shared → global-shared)
  • MVVM Separation: Business logic in ViewModel, UI rendering in Page components
  • V2 Decorator System: Use @ComponentV2 with @Param/@Local, avoid mixing V1 decorators (@State/@Observed)
  • Resource Management: Reference resources using 
    $r('app.xxx')
    , define sizes using ThemeSizeTokens constants
Step 3: Apply Naming Conventions
Follow naming standards:
  • Files: PascalCase (e.g., 
    ProductListPage.ets
    )
  • Classes/Structs: PascalCase
  • Methods/Variables: camelCase
  • Constants: SCREAMING_SNAKE_CASE
  • Component Props interfaces: End with 
    Props
Step 4: Code Review
Before completion, validate against the code review checklist (Section 15 of development-guide.md).

2. 错误调试工作流程

2. Error Debugging Workflow

主动运行编译指令发现错误：参考 development-guide.md 中的完整编译命令章节 遇到错误或调试问题时：
步骤 1：优先搜索错误日志
尝试解决错误之前：
typescript
// 使用 Grep 工具在 error-log.md 中搜索类似错误模式
Grep(pattern="[错误关键词]", path="references/error-log.md", output_mode="content")
搜索内容：
  • 精确的错误信息（如 "Cannot find name"）
  • 错误代码
  • 问题描述（如 "Navigation push failed"、"List performance"）
步骤 2：应用已有解决方案
如果在日志中找到匹配的错误：
  1. 仔细阅读记录的解决方案
  2. 应用推荐的修复方法
  3. 如有提及，参考 development-guide.md 中的相关章节
  4. 验证修复是否解决了问题
步骤 3：调查新错误
如果日志中不存在匹配的错误：
  1. 分析错误信息和堆栈跟踪
  2. 查阅 development-guide.md 中的相关章节
  3. 应用调试技术：
    • 检查装饰器使用（@ComponentV2、@Param、@Local）
    • 验证导入语句
    • 审查 MVVM 架构分离
    • 验证 Navigation 路由配置
    • 检查资源引用
步骤 4：记录新解决方案
成功解决新错误后：
  1. 确定错误类别：
    • 编译错误
    • 运行时错误
    • 性能问题
    • 架构问题
    • 其他常见问题
  2. 添加错误条目到 
    references/error-log.md
    ：
使用 Edit 工具在适当类别下追加新的错误记录：
markdown
undefined
Proactively run compilation commands to detect errors: Refer to the Complete Compilation Commands section in development-guide.md When encountering errors or debugging issues:
Step 1: Prioritize Searching Error Logs
Before attempting to resolve errors:
typescript
// Use Grep tool to search for similar error patterns in error-log.md
Grep(pattern="[error keywords]", path="references/error-log.md", output_mode="content")
Search for:
  • Exact error messages (e.g., "Cannot find name")
  • Error codes
  • Problem descriptions (e.g., "Navigation push failed", "List performance")
Step 2: Apply Existing Solutions
If a matching error is found in the logs:
  1. Carefully read the documented solution
  2. Apply the recommended fix
  3. Refer to relevant sections in development-guide.md if mentioned
  4. Verify if the fix resolves the issue
Step 3: Investigate New Errors
If no matching error exists in the logs:
  1. Analyze the error message and stack trace
  2. Consult relevant sections in development-guide.md
  3. Apply debugging techniques:
    • Check decorator usage (@ComponentV2, @Param, @Local)
    • Validate import statements
    • Review MVVM architecture separation
    • Verify Navigation routing configuration
    • Check resource references
Step 4: Record New Solutions
After successfully resolving a new error:
  1. Determine Error Category:
    • Compilation errors
    • Runtime errors
    • Performance issues
    • Architecture issues
    • Other common issues
  2. Add Error Entry to 
    references/error-log.md
    :
Use the Edit tool to append a new error record under the appropriate category:
markdown
undefined

错误：[简短描述]

Error: [Brief Description]

错误信息： [完整的错误信息或关键代码片段]
原因： [错误产生的根本原因]
解决方案： [具体的解决步骤和代码示例]
相关规范： [引用 development-guide.md 中的相关章节]
记录时间：YYYY-MM-DD

3. **通知用户**：告知用户错误和解决方案已记录，供将来参考。
Error Message: [Full error message or key code snippet]
Root Cause: [Fundamental cause of the error]
Solution: [Specific resolution steps and code examples]
Related Specifications: [Reference relevant sections in development-guide.md]
Recorded Date: YYYY-MM-DD

3. **Notify User**: Inform the user that the error and solution have been recorded for future reference.

3. 参考文件加载策略

3. Reference File Loading Strategy

开发指南（
references/development-guide.md
）：
  • 大小：大型综合文档（约 2000 行）
  • 加载策略：
    • 根据需要使用 offset/limit 参数读取特定章节
    • 对于一般性问题，先使用 Grep 查找相关章节
    • 对于架构设计，读取第 1-4 节
    • 对于特定功能，读取目标章节（如路由查看第 10 节）
错误日志（
references/error-log.md
）：
  • 大小：不断增长的文档，初始为中等大小
  • 加载策略：
    • 始终先使用 Grep 搜索错误模式
    • 仅在找到匹配错误时读取完整上下文
    • 使用 Edit 工具追加新错误
Development Guide (
references/development-guide.md
):
  • Size: Large comprehensive document (approx. 2000 lines)
  • Loading Strategy:
    • Read specific sections using offset/limit parameters as needed
    • For general questions, first use Grep to find relevant sections
    • For architecture design, read Sections 1-4
    • For specific features, read target sections (e.g., Section 10 for routing)
Error Log (
references/error-log.md
):
  • Size: Growing document, initially medium-sized
  • Loading Strategy:
    • Always use Grep to search for error patterns first
    • Read full context only when a matching error is found
    • Use the Edit tool to append new errors

重要指导原则

Important Guiding Principles

代码质量标准

Code Quality Standards

  • 避免过度工程：只实现请求的内容，避免添加不必要的功能或抽象
  • 安全优先：绝不引入漏洞（XSS、SQL 注入、命令注入等）
  • 性能意识：对长列表使用 LazyForEach，优化图片加载，避免频繁重渲染
  • 类型安全：使用适当的 TypeScript 类型，避免 
    any
  • Avoid Over-Engineering: Only implement requested content, avoid unnecessary features or abstractions
  • Security First: Never introduce vulnerabilities (XSS, SQL injection, command injection, etc.)
  • Performance Awareness: Use LazyForEach for long lists, optimize image loading, avoid frequent re-renders
  • Type Safety: Use appropriate TypeScript types, avoid 
    any

Skill 专用规则

Skill-Specific Rules

  1. 解决前先搜索：绝不在未搜索 error-log.md 的情况下尝试解决错误
  2. 始终记录新方案：解决新错误后，始终记录到 error-log.md
  3. 引用指南：解释解决方案时，引用 development-guide.md 中的相关章节
  4. 保持日志有序：确保新条目添加到正确的类别下
  5. 提供上下文：记录错误时，包含足够的上下文供将来参考（错误信息、原因、解决方案、相关规范）
  1. Search Before Solving: Never attempt to resolve an error without first searching error-log.md
  2. Always Record New Solutions: After resolving a new error, always record it in error-log.md
  3. Reference the Guide: When explaining solutions, reference relevant sections in development-guide.md
  4. Keep Logs Organized: Ensure new entries are added under the correct category
  5. Provide Context: When recording errors, include sufficient context for future reference (error message, cause, solution, related specifications)

沟通风格

Communication Style

  • 所有面向用户的内容使用中文（基于 CLAUDE.md 偏好）
  • 简明实用，专注于可执行信息
  • 在相关时解释架构决策背后的"原因"
  • 适当时提供多种方法及其权衡
  • All user-facing content in Chinese (based on CLAUDE.md preferences)
  • Concise and practical, focused on actionable information
  • Explain the "why" behind architectural decisions when relevant
  • Provide multiple approaches and their trade-offs when appropriate

Skill 维护

Skill Maintenance

随着项目发展：
  • 更新 error-log.md：持续添加新遇到的错误
  • 更新 development-guide.md：如果出现与标准指南不同的项目特定模式
  • 审查和整合：定期审查 error-log.md 以查找重复条目或应提升到 development-guide.md 的模式
As the project evolves:
  • Update error-log.md: Continuously add newly encountered errors
  • Update development-guide.md: If project-specific patterns emerge that differ from standard guidelines
  • Review and Integrate: Regularly review error-log.md to find duplicate entries or patterns that should be elevated to development-guide.md

使用场景示例

Usage Scenario Examples

场景 1：创建新页面
用户："帮我创建一个产品列表页面"
助手：
1. 加载 development-guide.md 第 2 节（项目结构）和第 4 节（MVVM）
2. 按照标准结构创建页面：
   - pages/product/list/ProductListPage.ets
   - pages/product/list/viewmodel/ProductListViewModel.ets
   - pages/product/list/components/ProductCard.ets
3. 遵循第 3 节使用 @ComponentV2、@Param、@Local 实现
4. 参考第 10 节设置路由
场景 2：调试编译错误
用户："编译报错：Cannot use @State with @ComponentV2"
助手：
1. 在 error-log.md 中 Grep 搜索 "Mixing V1 and V2 decorators"
2. 找到已记录的解决方案
3. 应用修复：将 @State 替换为 @Local
4. 解释 V1/V2 装饰器分离原则
场景 3：解决新错误
用户："Navigation 跳转时报错：[NEW_ERROR_MESSAGE]"
助手：
1. Grep 搜索 error-log.md 但未找到匹配
2. 分析错误并查阅 development-guide.md 第 10 节（Navigation）
3. 识别根本原因并应用修复
4. 将新错误记录到 error-log.md 的"运行时错误"类别下
5. 通知用户："已将此错误和解决方案记录到错误日志中"
Scenario 1: Creating a New Page
User: "Help me create a product list page"
Assistant:
1. Load Sections 2 (Project Structure) and 4 (MVVM) of development-guide.md
2. Create pages following the standard structure:
   - pages/product/list/ProductListPage.ets
   - pages/product/list/viewmodel/ProductListViewModel.ets
   - pages/product/list/components/ProductCard.ets
3. Implement using @ComponentV2, @Param, @Local following Section 3
4. Set up routing referencing Section 10
Scenario 2: Debugging Compilation Errors
User: "Compilation error: Cannot use @State with @ComponentV2"
Assistant:
1. Grep error-log.md for "Mixing V1 and V2 decorators"
2. Locate the documented solution
3. Apply the fix: Replace @State with @Local
4. Explain the V1/V2 decorator separation principle
Scenario 3: Resolving New Errors
User: "Navigation jump error: [NEW_ERROR_MESSAGE]"
Assistant:
1. Grep error-log.md but find no matches
2. Analyze the error and consult Section 10 (Navigation) of development-guide.md
3. Identify the root cause and apply the fix
4. Record the new error under the "Runtime Errors" category in error-log.md
5. Notify user: "This error and its solution have been recorded in the error log"

快速参考

Quick Reference

任务参考文件章节
项目结构development-guide.md1-2
@ComponentV2 使用development-guide.md3
MVVM 架构development-guide.md4
Navigation 路由development-guide.md10
状态管理development-guide.md11
性能优化development-guide.md12
已知错误error-log.md全部
记住：本 skill 在将 development-guide.md 中的结构化知识与 error-log.md 中的实践经验积累相结合时最为有效。始终先搜索后解决，始终记录新方案。
TaskReference FileSection
Project Structuredevelopment-guide.md1-2
@ComponentV2 Usagedevelopment-guide.md3
MVVM Architecturedevelopment-guide.md4
Navigation Routingdevelopment-guide.md10
State Managementdevelopment-guide.md11
Performance Optimizationdevelopment-guide.md12
Known Errorserror-log.mdAll
Remember: This skill is most effective when combining structured knowledge from development-guide.md with practical experience accumulated in error-log.md. Always search before solving, and always record new solutions.