@harmonyos-arkts/d2h 0.0.0-stage → 0.1.1

package/skills/arkts-mvvm-architecture/SKILL.md

@@ -0,0 +1,613 @@
+---
+name: arkts-mvvm-architecture
+description: >-
+  HarmonyOS/ArkTS 工程架构规范与落地指南（MVVM + 状态管理 V2 + ArkTS 严格类型 + 导航/生命周期/模块化/并发/工程治理）。当用户需要新建鸿蒙工程、搭建或重构目录分层、设计 Model/ViewModel/View/Repository、使用 @ComponentV2、@Local、@Param、@Event、@ObservedV2、@Trace、@Monitor、@Computed、AppStorageV2、PersistenceV2，或使用 Navigation/NavPathStack、设计 UIAbility 生命周期、拆分 HAR/HSP、TaskPool/Worker 并发，或询问「ArkTS 怎么写」「MVVM 怎么分层」「V2 状态管理怎么用」「工程目录怎么放」「状态不刷新怎么办」「页面怎么跳转」「怎么拆包」时触发。也适用于代码评审与规范检查。Use for HarmonyOS ArkTS project architecture, MVVM layering, state management V2, navigation, lifecycle, modularization and concurrency. 不处理 Android→鸿蒙迁移（另见迁移类 skill）、i18n、图片资源转换。
+type: domain
+domain: engineering
+tags: [arkts, mvvm, state-management-v2, navigation, architecture, harmonyos]
+---
+
+# HarmonyOS 工程架构规范（MVVM + V2 + ArkTS）
+
+本 skill 是鸿蒙应用**架构与编码规范**的事实来源。生成或评审 ArkTS 代码时严格遵守下列规范。
+核心三原则：**MVVM 分层**、**状态管理一律用 V2**、**ArkTS 严格类型**。
+
+目录：1 目录结构 · 2 MVVM 分层 · 3 状态管理 V2 · 4 ArkTS 编码规范 · 5 组件规范 · 6 导航与路由 ·
+7 Ability 与生命周期 · 8 模块化与打包 · 9 数据层与网络 · 10 并发规范 · 11 错误与日志 ·
+12 性能与安全 · 13 多设备适配 · 14 自检清单 · 15 错误对照 · 16 交付格式
+
+---
+
+## 1. 目录结构规范
+
+按「功能 + 分层」组织。`core/` 放跨模块共享资产，业务按 feature 内聚。
+
+```
+entry/src/main/ets/
+├── entryability/
+│   └── EntryAbility.ets
+├── pages/                      # 页面入口（Navigation 容器 / 页面）
+│   ├── Index.ets
+│   └── DetailPage.ets
+├── view/                       # 视图层：可复用 UI 组件
+│   └── components/
+│       ├── UserCard.ets
+│       └── EmptyView.ets
+├── viewmodel/                  # 视图模型层：每个页面一个 VM
+│   ├── IndexViewModel.ets
+│   └── DetailViewModel.ets
+├── model/                      # 数据模型层：实体、DTO、枚举
+│   ├── UserModel.ets
+│   └── ApiResponse.ets
+├── repository/                 # 仓储层：聚合数据源，对 VM 暴露接口
+│   ├── UserRepository.ets          # 接口 + 默认实现
+│   └── impl/
+│       └── UserRepositoryImpl.ets
+├── datasource/                 # 数据源层：远程 / 本地
+│   ├── remote/
+│   │   └── UserRemoteSource.ets
+│   └── local/
+│       └── UserLocalSource.ets
+├── core/                       # 跨模块公共资产（或独立 HAR/HSP）
+│   ├── constants/
+│   │   ├── AppConstants.ets
+│   │   ├── RouteConstants.ets
+│   │   └── ErrorCode.ets
+│   ├── utils/
+│   │   ├── Logger.ets
+│   │   └── DateUtil.ets
+│   ├── network/
+│   │   └── HttpClient.ets
+│   ├── storage/
+│   │   └── PreferencesUtil.ets
+│   └── theme/
+│       └── AppTheme.ets
+└── router/
+    └── RouterManager.ets
+```
+
+规则：
+- **model/ 集中定义数据模型**，所有层从这里导入，禁止在 View 内就地定义业务实体。
+- 一个页面/组件对应一个 ViewModel，命名 `<名称>ViewModel`。
+- 可复用 UI 放 `view/components/`，不写业务请求逻辑。
+- 工具、网络、存储、常量统一进 `core/`。
+- 分层依赖**单向向下**：`view → viewmodel → repository → datasource → core`。禁止反向依赖与跨 feature 直接引用内部 VM。
+- 单模块工程用本结构；多模块工程把 `core/` 提升为独立 HAR（见 §8）。
+
+---
+
+## 2. MVVM 分层职责
+
+| 层 | 位置 | 职责 | 禁止 |
+| --- | --- | --- | --- |
+| Model | `model/` | 数据结构、DTO、枚举、纯数据转换 | 引用 UI、持有页面状态、发请求 |
+| ViewModel | `viewmodel/` | 持有状态、组织用例、调 Repository、暴露只读数据与事件 | 直接操作 UI、import ArkUI 组件、直连三方库 |
+| View | `pages/`、`view/` | 渲染、绑定 VM、转发用户事件 | 写网络/复杂逻辑、跨层直连 Model 做业务 |
+| Repository | `repository/` | 对 VM 暴露稳定接口，聚合/编排数据源、缓存策略 | 写 UI、持有页面状态 |
+| DataSource | `datasource/` | 具体远程/本地读写（HTTP、RDB、KV、Preferences） | 写业务规则、跨源编排 |
+
+数据流单向：**View(事件) → ViewModel(改状态/调 Repository) → 状态变更 → View 自动刷新**。
+
+示例：VM 依赖 Repository 接口，而非具体实现（便于替换与测试）：
+
+```typescript
+// repository/UserRepository.ets
+import { UserModel } from '../model/UserModel';
+
+export interface UserRepository {
+  fetchUsers(keyword: string): Promise<UserModel[]>;
+}
+```
+
+```typescript
+// viewmodel/IndexViewModel.ets
+import { BusinessError } from '@kit.BasicServicesKit';
+import { UserModel } from '../model/UserModel';
+import { UserRepository } from '../repository/UserRepository';
+import { UserRepositoryImpl } from '../repository/impl/UserRepositoryImpl';
+import { Logger } from '../core/utils/Logger';
+
+@ObservedV2
+export class IndexViewModel {
+  private repo: UserRepository = new UserRepositoryImpl();
+
+  @Trace userList: UserModel[] = [];
+  @Trace isLoading: boolean = false;
+  @Trace keyword: string = '';
+
+  @Computed
+  get hasData(): boolean {
+    return this.userList.length > 0;
+  }
+
+  async loadUsers(): Promise<void> {
+    this.isLoading = true;
+    try {
+      this.userList = await this.repo.fetchUsers(this.keyword);
+    } catch (err) {
+      const e = err as BusinessError;
+      Logger.error('IndexViewModel', `loadUsers failed: ${e.code} ${e.message}`);
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  toggleFollow(user: UserModel): void {
+    user.isFollowed = !user.isFollowed;
+  }
+}
+```
+
+---
+
+## 3. 状态管理：一律用 V2
+
+V2 装饰器是内置的，**无需 import**。旧版 `@Component/@State/@Prop/@Link/@Observed/@ObjectLink` 在新增代码中**禁止使用**。
+
+### 3.1 装饰器速查
+
+| 装饰器 | 作用对象 | 用途 |
+| --- | --- | --- |
+| `@ComponentV2` | struct | 声明 V2 组件 |
+| `@ObservedV2` | class | 声明可深度观测的类（Model/ViewModel） |
+| `@Trace` | class 属性 | 使属性参与 V2 观测（**刷新关键**） |
+| `@Local` | 组件成员 | 组件内部状态 |
+| `@Param` | 组件成员 | 父→子入参（只读，可带默认值） |
+| `@Once` | 配合 @Param | 入参只初始化一次，之后父变更不再同步 |
+| `@Event` | 组件成员 | 子→父回调 |
+| `@Provider` / `@Consumer` | 组件成员 | 组件树内跨层级共享（避免逐层透传） |
+| `@Monitor` | 组件/VM 成员 | 监听指定属性变化，回调响应 |
+| `@Computed` | getter | 派生状态，自动缓存 |
+
+### 3.2 响应式刷新铁律
+
+**所有参与界面刷新的 Model / ViewModel 必须用 `@ObservedV2` 修饰，且需被观测的字段必须逐个加 `@Trace`。**
+
+- 未加 `@Trace` 的属性即使所属类标了 `@ObservedV2` 也不会触发刷新。
+- 嵌套对象（对象数组、子对象）的深层字段同样需要各自 `@ObservedV2 + @Trace`。
+- **取舍**：纯 DTO（仅传输、从不直接绑定 UI）可保持为普通 class/interface，避免领域模型耦合 ArkUI；一旦要直接驱动刷新，就必须加 `@ObservedV2 + @Trace`（或用 VM 包装）。
+- 类替换 / 数组整体赋值会触发刷新；只改普通字段不会，需该字段带 `@Trace`。
+
+### 3.3 全局状态与持久化（AppStorageV2 / PersistenceV2）
+
+页面内状态放 VM；**只有真正跨页面/全局共享**（登录会话、主题、用户设置）才用全局存储。
+
+```typescript
+// core/store/AppStore.ets
+import { AppStorageV2, PersistenceV2 } from '@kit.ArkUI';
+
+@ObservedV2
+export class SessionModel {
+  @Trace userId: string = '';
+  @Trace token: string = '';
+  @Trace isLogin: boolean = false;
+}
+
+// 内存级全局（进程存活期）；此处 `!` 是存储边界的受控断言（§4.7 例外），connect 必返回实例
+const session: SessionModel = AppStorageV2.connect(SessionModel, 'session', () => new SessionModel())!;
+
+// 持久化全局（重启仍在），键名与类型必须稳定
+@ObservedV2
+export class SettingsModel {
+  @Trace theme: string = 'light';
+  @Trace language: string = 'zh-CN';
+}
+const settings: SettingsModel = PersistenceV2.connect(SettingsModel, 'settings', () => new SettingsModel())!;
+```
+
+规则：
+- V2 全局存储的类同样需 `@ObservedV2`，需刷新的字段需 `@Trace`。
+- 仅对可序列化字段持久化；敏感 token 存 [加密存储/KeyStore]，不要进 PersistenceV2。
+- 关闭/变更时调用 `AppStorageV2.remove(key)` / 更新，避免脏数据。
+- 组件子树内共享优先用 `@Provider/@Consumer`；跨页面才用 AppStorageV2。
+
+### 3.4 完整示例
+
+```typescript
+// model/UserModel.ets
+@ObservedV2
+export class UserModel {
+  @Trace id: string = '';
+  @Trace name: string = '';
+  @Trace avatar: string = '';
+  @Trace isFollowed: boolean = false;
+}
+```
+
+```typescript
+// pages/Index.ets
+import { IndexViewModel } from '../viewmodel/IndexViewModel';
+import { UserModel } from '../model/UserModel';
+import { UserCard } from '../view/components/UserCard';
+
+@Entry
+@ComponentV2
+struct Index {
+  private viewModel: IndexViewModel = new IndexViewModel();
+
+  aboutToAppear(): void {
+    this.viewModel.loadUsers();
+  }
+
+  build() {
+    Column({ space: 12 }) {
+      Search({ value: this.viewModel.keyword })
+        .onChange((value: string) => {
+          this.viewModel.keyword = value;
+        })
+
+      if (this.viewModel.hasData) {
+        List() {
+          ForEach(this.viewModel.userList, (user: UserModel) => {
+            ListItem() {
+              UserCard({
+                user: user,
+                cardOnFollow: (u: UserModel): void => this.viewModel.toggleFollow(u)
+              })
+            }
+          }, (user: UserModel) => user.id)
+        }
+      } else {
+        Text('暂无数据')
+      }
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+```typescript
+// view/components/UserCard.ets
+import { UserModel } from '../../model/UserModel';
+
+@ComponentV2
+export struct UserCard {
+  @Require @Param user: UserModel;
+  @Event cardOnFollow: (user: UserModel) => void = (user: UserModel): void => {};
+
+  build() {
+    Row({ space: 8 }) {
+      Image(this.user.avatar)
+        .width(40)
+        .height(40)
+        .borderRadius(20)
+      Text(this.user.name).fontSize(16).layoutWeight(1)
+      Button(this.user.isFollowed ? '已关注' : '关注')
+        .onClick(() => this.cardOnFollow(this.user))
+    }
+    .width('100%')
+  }
+}
+```
+
+---
+
+## 4. ArkTS 编码规范
+
+ArkTS 比 TypeScript 更严格，以下为硬性约束：
+
+1. **禁止 `any` / `unknown`**：用具体类型或自定义 `interface`/`class`。
+2. **`as` 仅在「类型收窄边界」允许**：路由参数、JSON 反序列化、`catch (err)`。其余场景用类型守卫/泛型/重构数据流。边界处必须紧跟校验，例如 `catch (err) { const e = err as BusinessError; }`。
+3. **禁止 `for...in`**：遍历一律用 `for...of`，或 `Array.forEach/map/filter`。
+4. **禁止动态属性访问**：`obj[key]`、`Reflect`、`delete` 不可用；键值不固定的场景用 `Map<string, T>`，不要用 `Record` 做动态下标。
+5. **所有类型显式声明**：变量、参数、返回值不依赖推断得出 `any`。
+6. **对象字面量必须有明确类型**：赋给已声明类型的变量，或作为具名形参，不可直接传未定型字面量。
+7. **禁止滥用 `!` 非空断言**；用 `??` 提供默认值。
+8. **`build()` 方法约束**：
+   - 禁止 `return`（提前返回）；
+   - 禁止声明局部变量；
+   - 禁止传入无类型对象字面量；
+   - 条件渲染用 `if/else`，循环用 `ForEach/LazyForEach`。
+9. **`@Param`/`@Event` 属性名不得与 ArkUI 内置属性同名**（`onClick`、`borderColor`、`width`、`height`、`enabled`、`visibility` 等），必须加业务前缀，如 `cardOnClick`、`cardOnFollow`、`cardWidth`。
+10. **常见替代**：
+    - `Fsys.symbol` → 用 Emoji 或本地资源图片；
+    - `for...in` → `for...of`；
+    - `any` → `interface` / 泛型；
+    - 动态字典 → `Map<string, T>`；
+    - 多态分支 → 判别联合类型（`type` 字段）+ `switch`。
+11. **导入必须完整**：每个被使用的类型/类都显式 `import`，禁止隐式全局。
+12. **每个文件一个主导出**，文件名与主类/struct 名一致。
+13. **命名**：类/struct `PascalCase`，方法/变量 `camelCase`，常量 `UPPER_SNAKE_CASE`，私有成员加 `private`。
+14. **字符串拼接与日志**用模板串；统一经 `Logger`，禁止裸 `console.log` 进主干。
+
+---
+
+## 5. 组件规范
+
+- 组件一律 `@ComponentV2`，入口页面再加 `@Entry`。
+- 入参用 `@Param`：需要父必传加 `@Require`（无需再给默认值）；否则给出默认值。
+- 回调用 `@Event`；组件自身状态用 `@Local`（不要 `@State`）。
+- 组件只做渲染与事件转发，业务逻辑放 ViewModel。
+- 组件树内跨层共享用 `@Provider/@Consumer`，超过两层不再手动透传。
+- 列表项必须提供稳定 `keyGenerator`（如 `id`），禁止用索引。
+- 长列表用 `LazyForEach` + `IDataSource`，配合 `@Reusable` 复用组件。
+- 组件间通过接口/数据类传参，避免直接依赖具体 ViewModel 实现。
+- 弹窗/半模态用 `@Builder` + `bindSheet/bindContentCover/customDialog`，统一封装在 `view/`。
+
+---
+
+## 6. 导航与路由规范
+
+**统一采用 `Navigation` + `NavPathStack`（系统路由/组件导航），不使用已过时的 `router`。**
+
+```typescript
+// core/constants/RouteConstants.ets
+export class RouteNames {
+  static readonly DETAIL: string = 'DetailPage';
+  static readonly SETTINGS: string = 'SettingsPage';
+}
+```
+
+```typescript
+// pages/Index.ets（导航容器）
+import { RouteNames } from '../core/constants/RouteConstants';
+
+@Entry
+@ComponentV2
+struct Index {
+  @Provider() pathStack: NavPathStack = new NavPathStack();
+
+  @Builder
+  pageMap(name: string, param: object) {
+    if (name === RouteNames.DETAIL) {
+      DetailPage()
+    } else if (name === RouteNames.SETTINGS) {
+      SettingsPage()
+    }
+  }
+
+  build() {
+    Navigation(this.pathStack) {
+      // 首页内容
+      Button('去详情')
+        .onClick(() => this.pathStack.pushPathByName(RouteNames.DETAIL, new DetailParam('1001')))
+    }
+    .navDestination(this.pageMap)
+    .mode(NavigationMode.Stack)
+    .title('首页')
+  }
+}
+```
+
+```typescript
+// pages/DetailPage.ets
+import { DetailParam } from '../model/DetailParam';
+
+@ComponentV2
+struct DetailPage {
+  private param: DetailParam = new DetailParam('');
+  @Consumer() pathStack: NavPathStack = new NavPathStack();
+
+  build() {
+    NavDestination() {
+      Column() {
+        Text(`id=${this.param.id}`)
+        Button('返回').onClick(() => this.pathStack.pop())
+      }
+    }
+    .onReady((ctx: NavDestinationContext) => {
+      const p = ctx.pathInfo.param;
+      if (p instanceof DetailParam) {
+        this.param = p;
+      }
+    })
+  }
+}
+```
+
+规则：
+- 路由名集中放 `RouteConstants`，禁止散落字符串。
+- 参数必须是可序列化对象（推荐数据类），在 `onReady` 通过 `instanceof`/类型守卫收窄，避免裸 `as`。
+- 路由表可抽到 `resources/base/profile/router_map.json` + `module.json5` 的 `routerMap` 以支持按需/跨模块路由；跨模块页面走该路由表，避免 HB 间直接 import 页面。
+- 返回拦截用 `NavDestination.onBackPressed`；埋点/登录守卫在 `RouterManager` 统一收口。
+- 跨模块路由封装在 `router/RouterManager.ets`，暴露 `navigateTo/pop/replace`，禁止各处直接 `pushPath`。
+
+---
+
+## 7. Ability 与生命周期
+
+**UIAbility 生命周期**（`entryability/EntryAbility.ets`）：
+
+| 阶段 | 时机 | 典型用途 |
+| --- | --- | --- |
+| `onCreate` | 实例创建 | 初始化全局资源、注册监听 |
+| `onWindowStageCreate` | 窗口创建 | `loadContent` 加载首页、设置窗口 |
+| `onForeground` | 切前台 | 刷新/恢复 |
+| `onBackground` | 切后台 | 保存状态、暂停任务 |
+| `onWindowStageDestroy` | 窗口销毁 | 释放 UI 资源 |
+| `onDestroy` | 实例销毁 | 注销监听、释放资源 |
+
+```typescript
+// entryability/EntryAbility.ets
+import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
+import { window } from '@kit.ArkUI';
+import { Logger } from '../core/utils/Logger';
+
+export default class EntryAbility extends UIAbility {
+  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
+    Logger.info('EntryAbility', 'onCreate');
+  }
+
+  onWindowStageCreate(windowStage: window.WindowStage): void {
+    windowStage.loadContent('pages/Index');
+  }
+
+  onDestroy(): void {
+    Logger.info('EntryAbility', 'onDestroy');
+  }
+}
+```
+
+**页面/组件生命周期**（V2 组件）：
+- `aboutToAppear`：入参就绪后、首次 build 前，做数据加载；
+- `aboutToDisappear`：销毁前，做清理（取消订阅、定时器）；
+- `onPageShow/onPageHide`：仅 `@Entry` 页面生效，处理可见性刷新；
+- `onBackPress`：返回键拦截，返回 `true` 表示已消费。
+
+规则：
+- 启动模式在 `module.json5` 的 `abilities[].launchType` 指定：`singleton`（默认）/`multiton`/`specified`。多实例场景显式选 `multiton`。
+- 冷启动只做必要初始化，重活异步化（见 §10）；避免在 `onCreate`/`aboutToAppear` 同步阻塞。
+- 订阅/定时器在 `aboutToDisappear`/`onDestroy` 成对释放。
+- 页面刷新与 VM 加载解耦：可见性刷新走 `onPageShow`，一次性加载走 `aboutToAppear`。
+
+---
+
+## 8. 模块化与打包
+
+- **单 HAP 只承载入口与少量页面**；业务按 feature 拆分为 **HSP（动态共享包，运行时共享单例）** 或 **HAR（静态共享包，编译期内联）**。
+- 推荐三层：`entry`（HAP，壳） → `features`（HAR/HSP，业务） → `commons/core`（HAR，基础设施）。
+- **依赖方向单向**：feature 依赖 core，core 不反向；feature 之间禁止直接依赖，需通信则下沉 core 或走路由表。
+- HAR 的页面通过 §6 的系统路由表暴露，调用方不直接 import 页面。
+- 三方库统一在 core 或各 HAR 声明，注意 HSP 单例语义（全局状态不要跨 HSP 重复创建）。
+- 常量、主题、网络、存储等基础设施放 core HAR，供所有 feature 复用。
+
+```
+root/
+├── entry/                 # HAP：入口 Ability + 首页
+├── features/
+│   ├── home/              # HSP
+│   └── profile/           # HSP
+├── commons/
+│   └── core/              # HAR：网络/存储/工具/主题/UI 基座
+└── build-profile.json5
+```
+
+---
+
+## 9. 数据层与网络规范
+
+原则：**统一出口、按需选型**。网络实现允许使用系统 API，也允许使用三方库（如 `@ohos/axios`、`@ohos/retrofit`、okhttp 移植版等），不强制只用某一种。
+
+- 网络能力收敛在 `datasource/remote/`，经 `repository/` 对 VM 暴露接口；VM **不直接**调用三方库。
+- 三方库选型自由，但必须限定在 datasource 内，替换实现不影响 VM。
+- 每个请求返回 `Promise<T>`，`T` 优先使用 `model/` 中定义的 DTO。
+- 统一处理：拦截器/重试/超时/鉴权/错误码映射放在 `core/network/HttpClient.ets` 或 repository 基类。
+- 错误统一 `try/catch` + `Logger`，不允许静默吞异常。
+- 持久化集中在 `datasource/local/`（Preferences、KV、RDB 或三方库均可），避免散落调用。
+- 常量/路由名集中放 `core/constants/`，禁止魔法字符串与魔法数字。
+
+---
+
+## 10. 并发规范
+
+- **UI 线程只做渲染与状态更新**，耗时计算/IO 不得阻塞主线程。
+- **短时并行任务**用 `TaskPool`：`@Concurrent` 函数必须是顶层（或 `static`）函数，不能捕获闭包变量。
+- **长时/有状态任务**（需常驻、双向通信）用 `Worker`。
+- 大对象（`ArrayBuffer`）跨线程传输用 `task.setTransferList` 转移所有权，避免拷贝。
+- 并发数受控：`TaskPool` 自动调度，不要无节制 `execute`；`Worker` 实例数要有限。
+- 任务内**禁止访问 UI**、禁止直接改 `@Trace` 状态；结果通过 `Promise` 回主线程后再更新状态。
+- 取消/超时：使用 `task.cancel` 或 `Promise.race` + 超时，页面销毁时取消在途任务（`aboutToDisappear`）。
+
+```typescript
+import { taskpool } from '@kit.ArkTS';
+
+// @Concurrent 函数必须是顶层函数，参数/返回值须为可序列化类型
+@Concurrent
+function parseLargeJson(raw: string): ParsedData { /* ... */ }
+
+// 调用侧（主线程）
+async function run(): Promise<void> {
+  const result: ParsedData = await taskpool.execute(parseLargeJson, raw) as ParsedData;
+}
+```
+
+---
+
+## 11. 错误与日志
+
+- 统一错误类型 `BusinessError`，错误码集中在 `core/constants/ErrorCode.ets`（枚举/常量），禁止魔法码。
+- `catch` 必须处理或上报，**禁止空 catch**；UI 层对失败给出可读提示，不外泄堆栈。
+- `Logger` 分级：`DEBUG / INFO / WARN / ERROR`；Release 构建关闭 DEBUG。日志带 `TAG` 与上下文，禁止打印隐私与密钥。
+- 关键链路（登录、支付、启动）失败需可追踪，必要时接 `HiAppEvent`/faultLogger 上报。
+
+```typescript
+// core/constants/ErrorCode.ets
+export enum ErrorCode {
+  NETWORK_TIMEOUT = 10001,
+  UNAUTHORIZED = 10002,
+  SERVER_ERROR = 10500
+}
+```
+
+---
+
+## 12. 性能与安全
+
+**性能**
+- 启动：冷启动只做必要初始化，非首屏任务延迟/异步；避免 `aboutToAppear` 同步重活。
+- 列表：长列表用 `LazyForEach` + `IDataSource`，组件 `@Reusable`。
+- 渲染：减少无效状态导致的全量刷新，合理拆分 `@Trace` 粒度。
+- 图片：按需解码/降采样，列表图用缓存；避免超大图直出。
+- 包体：按 feature 拆 HSP/HAR，移除未用资源与依赖。
+
+**安全**
+- 密钥/token 不得硬编码，敏感数据用 [KeyStore/加密存储]，不要写进 PersistenceV2。
+- 权限最小化，运行时权限按需申请并说明用途；隐私弹窗合规。
+- 网络默认 HTTPS，证书校验不可关闭；日志脱敏。
+
+---
+
+## 13. 多设备适配
+
+- 用断点（`sm/md/lg`，如 320/600/840vp）与栅格 `GridRow/GridCol` 做响应式，而非写死尺寸。
+- 优先百分比/`layoutWeight`/`Flex`，关键页适配手机、平板、折叠屏。
+- 一多部署：一套代码多设备，用资源限定符与 `mediaquery` 区分布局，不复制工程。
+- 主题/字号/间距用 `core/theme` 的 token，禁止散落魔法值。
+
+---
+
+## 14. 自检清单（生成代码后逐条核对）
+
+- [ ] 是否使用 `@ComponentV2`，且未出现 `@Component/@State/@Prop/@Link`？
+- [ ] 参与刷新的 Model/ViewModel 是否 `@ObservedV2`，需刷新字段是否逐个 `@Trace`？
+- [ ] 全局共享是否用 `AppStorageV2/PersistenceV2`，且仅限真正跨页面状态？
+- [ ] 页面/组件是否有对应 `viewmodel/`，逻辑是否已下沉？
+- [ ] VM 是否依赖 Repository 接口而非具体数据源/三方库？
+- [ ] Model 是否集中在 `model/` 且被完整 import？
+- [ ] 是否出现 `any`/`unknown`/滥用 `as`/`for...in`/`obj[key]`/`Record` 动态下标？
+- [ ] `build()` 内有 `return`、局部变量或无类型字面量吗？
+- [ ] `@Param`/`@Event` 名是否与 ArkUI 内置属性冲突（已加业务前缀）？
+- [ ] 长列表是否用 `LazyForEach` + 稳定 key，必要时 `@Reusable`？
+- [ ] 页面跳转是否走 `Navigation/NavPathStack` + 集中路由名，未用旧 `router`？
+- [ ] 订阅/定时器/在途任务是否在 `aboutToDisappear/onDestroy` 释放？
+- [ ] 耗时任务是否移出主线程（TaskPool/Worker）？
+- [ ] 网络请求是否收敛在数据层（datasource/repository），未散落在 View？
+- [ ] 错误是否统一 `BusinessError` + 错误码 + `Logger`，无空 catch？
+
+任何一项不通过 → 先修正再交付。
+
+---
+
+## 15. 常见错误对照表
+
+| 错误写法 | 正确写法 |
+| --- | --- |
+| `@Component struct A {}` | `@ComponentV2 struct A {}` |
+| `@State count: number = 0` | `@Local count: number = 0` |
+| `@Prop` / `@Link` | `@Param`（只读）/ `@Event` + VM 方法 |
+| 类标 `@ObservedV2` 但字段无 `@Trace` | 每个需刷新的字段加 `@Trace` |
+| `@Observed class M {}` | `@ObservedV2 class M { @Trace x }` |
+| `let list: any[]` | `let list: UserModel[]` |
+| `for (const k in obj)` | `for (const k of Object.keys(obj))` |
+| `obj['name']` | `obj.name` 或 `map.get('name')` |
+| `Record<string, T>` 动态下标 | `Map<string, T>` |
+| `build() { if (x) return ...; ... }` | `build() { if (x) { ... } else { ... } }` |
+| `@Param onClick: () => void` | `@Event cardOnClick: () => void` |
+| `router.pushUrl({ url: 'pages/Detail' })` | `pathStack.pushPathByName(RouteNames.DETAIL, param)` |
+| VM 里 `new Axios(...)` | VM 依赖 `Repository`，三方库在 datasource |
+| `catch (e) {}` 空捕获 | 上报 `BusinessError` + 错误码 + `Logger` |
+
+---
+
+## 16. 交付格式
+
+生成页面/组件代码时，按此顺序输出：
+1. `model/` 中的实体（若新增）；
+2. `repository/` + `datasource/` 中的数据访问（若新增）；
+3. `viewmodel/` 中的 VM；
+4. `pages/` 或 `view/components/` 中的视图；
+5. 涉及的 `core/`（网络/常量/日志）与路由注册；
+6. 末尾附「自检清单」核对结果。
+
+改动多个文件时，每个文件标注完整路径，import 路径与实际目录一致。

package/skills/harmonyos-migration-playbook/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: harmonyos-migration-playbook
+description: Diagnose and reuse verified Android-to-HarmonyOS migration lessons for ArkTS compilation, HarmonyOS runtime, UI automation, protocol E2E, and Windows toolchains. Use during migration implementation, failure recovery, validation, or post-commit retrospectives; do not treat project-specific observations as universal platform rules.
+---
+
+# HarmonyOS migration playbook
+
+Use verified experience to shorten diagnosis without replacing current-project evidence.
+
+## Required operating loop
+
+1. Identify the current symptom and task boundary.
+2. Read only the relevant reference below.
+3. Check that the recorded applicability conditions match the current SDK, UI stack, runtime and code path.
+4. Reproduce or inspect evidence before applying a fix. Historical experience is a hypothesis until confirmed in the current project.
+5. Apply the smallest in-scope fix and run the stated verification.
+6. After validation, create an explicit Git checkpoint with `droid2hmos checkpoint create`; record a reusable lesson only when the root cause and fix are proven.
+
+## Reference routing
+
+- ArkTS compiler errors or language restrictions: read [references/arkts-compile.md](references/arkts-compile.md).
+- Socket, TLS, IME, asynchronous execution, component state or theme problems: read [references/harmony-runtime.md](references/harmony-runtime.md).
+- Emulator interaction, screenshots, `dumpLayout`, input or scrolling failures: read [references/ui-automation.md](references/ui-automation.md).
+- IMAP/SMTP or other protocol-level end-to-end verification: read [references/protocol-e2e.md](references/protocol-e2e.md).
+- Windows, Gradle, SDK, proxy, encoding or background-service process hangs: read [references/windows-environment.md](references/windows-environment.md).
+- DevEco CLI login callback refused (`localhost 拒绝了连接`) or auth gate retries: read [references/windows-environment.md](references/windows-environment.md).
+- Recording or promoting migration experience: read [references/lesson-lifecycle.md](references/lesson-lifecycle.md).
+
+## Evidence levels
+
+- **Platform rule**: supported by the active SDK/compiler behavior or repeatable minimal reproduction.
+- **Reusable pattern**: reproduced in more than one relevant project or independent environment.
+- **Project-validated**: fully proven in one project and useful beyond that project. It may enter the public playbook immediately, but every new project must revalidate it before relying on it.
+- **Candidate observation**: plausible but not yet proven; never use as a completion claim.
+
+Prefer narrower classifications. Public does not mean universal: a project-validated lesson is visible for reuse but remains a hypothesis outside its source project. Record SDK/tool versions when behavior could change.
+
+## Non-negotiable boundaries
+
+- Android source and observable behavior remain authoritative.
+- Do not bypass AppGraph, compilation, tests or device validation merely because an earlier project was slow or unreliable. Diagnose the current failure; any explicit degradation must preserve a visible coverage gap.
+- Do not convert implementation defects into platform limitations or external blockers.
+- Do not claim a lesson is verified from a report, comment, code existence or compile success alone when runtime behavior is relevant.
+- Do not modify the public playbook from every task. First record the lesson in the current project; a reviewed, non-obvious and well-verified single-project lesson may be promoted as `project-validated` under `lesson-lifecycle.md` instead of waiting invisibly for another project.
+
+## Quick triage
+
+```text
+Compile failure       -> ArkTS error code and exact source construct
+Button does nothing   -> reachability, UI tree, callback log, async context
+Socket failure        -> bind/connect/TLS stage and network logs
+Login callback refused-> login process lifecycle (windows-environment.md)
+Input corruption      -> focus, IME state, input command and current value
+Visual mismatch       -> element-by-element layout/style/content comparison
+Repeated task failure -> read project lessons, then verify applicability
+```

package/skills/harmonyos-migration-playbook/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "HarmonyOS Migration Playbook"
+  short_description: "复用经验证的鸿蒙迁移诊断与测试经验"
+  default_prompt: "Use $harmonyos-migration-playbook to diagnose this migration issue and verify that the historical lesson applies here."
+
+policy:
+  allow_implicit_invocation: true