AGENTS.md — HarmonyOS 开发宪法

Target: HarmonyOS NEXT (API 21+) | ArkTS | ArkUI (Stage Model)

---

I. 禁止事项

• Android/Java/Kotlin API（Activity, Intent, findViewById）
• Web DOM/BOM（window, document, localStorage）
• ArkTS 禁止：any、Spread {...obj}、动态属性 obj[key]、typeof
• Main Thread 阻塞（同步 I/O、长循环、重计算）
• 硬编码资源（字符串/颜色/尺寸必须用 $r() 引用）
• FA Model 旧 API（已废弃）
• 猜测 HarmonyOS API（必须先用 hmos-api-lookup 离线验证，详见 Section V）

---

II. MVVM 架构

Layer	路径	职责
View	pages/, components/	UI 渲染、用户交互
ViewModel	@State/@Link/@Prop	状态管理、响应式绑定
Model	models/, data/	数据模型、持久化
Service	services/	业务逻辑、跨模块协调
Platform	platform/	系统能力封装、权限管理

命名规范： XxxPage.ets, XxxComponent.ets, XxxService.ets, XxxModel.ets

---

III. 状态装饰器

Scope	Decorator
ViewModel (私有)	@State
View → ViewModel	@Prop
View ↔ ViewModel	@Link
跨层级	@Provide/@Consume
嵌套对象	@Observed/@ObjectLink
列表项复用	@Reusable

规则： @State 必须初始化；ForEach 必须有 keyGenerator；build() 禁止 return。

---

IV. 并发

任务	方案
< 10ms	主线程
Async I/O	async/await
> 100ms CPU	TaskPool + @Concurrent
长后台	Worker

---

V. API 规范

• 使用 API 21+ Kit imports
• 使用陌生鸿蒙 API 前，必须按以下顺序验证：
  1. hmos-api check <symbol> — 离线验证存在性（权威，来自 DevEco SDK .d.ts）
  2. 需要补充说明/示例时，再用 deepwiki-ask 查询官方文档
  3. 禁止跳过步骤 1 直接将未验证 API 写入 plan / code / architecture 文档
• hmos-api 可用子命令： check | lookup | method | component | attrs | decorator | search | verify-file

---

VI. Android → HarmonyOS 映射

Android	HarmonyOS
Activity	UIAbility
Intent	Want
Fragment	@Component
ViewModel	@State + Service
Layout XML	build()
SharedPreferences	preferences
SQLite	RelationalStore
RecyclerView	LazyForEach
Gradle	hvigor

---

VII. 决策框架

文件位置： Page pages/、Component components/、Service services/、Model models/、Platform platform/

状态选择： 私有 @State、父子 @Prop/@Link、跨层 @Provide/@Consume

导航选择： 同 Ability 用 navPathStack、跨 Ability 用 startAbility(Want)

---

Version: 3.2