@dtt_siye/atool 1.3.0 → 1.4.0

package/skills/project-analyze/rules/harmony.md

@@ -1,257 +1,84 @@
 # HarmonyOS / ArkTS 项目分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `harmony-conventions` skill 作为规范约束。
 
-按 Entry/Feature/Common 模块和 ArkUI 组件层次进行分析。
+## 模块发现策略
 
-```
-EntryAbility（应用入口）
-    ↓
-Pages（页面）
-    ↓
-@Components（自定义组件）
-    ↓
-@ViewModel / @Observed（状态管理）
-    ↓
-Service / Utils（服务/工具）
-    ↓
-Model（数据模型）
-    ↓
-Resources（资源文件）
-```
-
-## 目录扫描策略
-
-### 1. 识别项目结构
-
-**信号文件检测：**
-- `build-profile.json5` → 构建配置
-- `oh-package.json5` → 包管理
-- `AppScope/` → 应用级配置
-- `entry/` → 主模块
-- `feature/` → 功能模块
-- `common/` → 公共模块
-
-### 2. 依赖提取
+从 HarmonyOS 构建文件识别模块边界：
 
-从 `oh-package.json5` 提取：
+- `build-profile.json5` → `modules` 数组，列出所有 hap/hsp 模块及其 `srcPath`
+- `oh-package.json5` → `dependencies` 识别三方库，`devDependencies` 识别工具链
+- `AppScope/` → 应用级配置（`app.json5`），提取 bundleName / versionCode
+- 典型模块类型：`entry`（主入口 HAP）/ `feature`（功能 HAP）/ `common`（HSP 公共库）
+- 每个模块目录下有独立的 `oh-package.json5` 和 `src/main/module.json5`
 
-| 类别 | 常见依赖 |
-|------|----------|
-| UI | @ohos.arkui.UIContext |
-| 网络 | @ohos.net.http |
-| 数据存储 | @ohos.data.preferences, @ohos.data.relationalStore |
-| 路由 | @ohos.router (router) |
-| 多媒体 | @ohos.multimedia.image |
-| 设备信息 | @ohos.device.info |
+**不视为独立模块**：`EntryAbility.ts` / `Index.ets`（入口文件）、`utils/` / `common/` 工具目录合并为一个模块、`.preview/` / `oh_modules/` 跳过。
 
-### 3. 按层扫描路径
+## 入口识别
 
-- **Pages**: `*/pages/*.ets`
-- **Components**: `*/components/*.ets`
-- **ViewModel**: `*/viewmodel/*.ets`, `*/viewmodels/*.ets`
-- **Model**: `*/model/*.ets`, `*/models/*.ets`
-- **Service**: `*/service/*.ets`, `*/services/*.ets`
-- **Utils**: `*/utils/*.ets`, `*/common/*.ets`
+- **UIAbility（页面入口）**：`module.json5` 中 `abilities` 数组，`exported: true` 且含 `ACTION_MAIN` 的 UIAbility
+- **ServiceAbility（后台服务）**：`module.json5` 中 `extensionAbilities` 数组，`type: "service"`
+- **页面入口**：`src/main/ets/pages/Index.ets`（默认首页）→ `@Entry @Component struct Index`
+- **路由入口**：`router.pushUrl({ url: 'pages/XXX' })` 或 `Navigation` 组件 + `NavPathStack`
 
-## 各层提取规则
+## 架构模式识别
 
-### 层 1: 模块结构分析
-
-**扫描文件**: `build-profile.json5`, `oh-package.json5`
-
-**提取内容**:
-- 模块列表（Entry/Feature/Common）
-- 模块间依赖关系
-- 每个模块的入口
-
-**输出示例**:
-```
-### 模块结构
-- **文件**: `build-profile.json5`
-- **模块列表**:
-  | 模块名 | 类型 | 职责 |
-  |--------|------|------|
-  | entry | Entry | 主入口，包含 UIAbility 和主页面 |
-  | feature-home | Feature | 首页模块 |
-  | feature-user | Feature | 用户管理模块 |
-  | feature-settings | Feature | 设置模块 |
-  | common-utils | Common | 公共工具 |
-  | common-network | Common | 网络请求封装 |
-- **模块依赖**:
-  entry → feature-home, feature-user, feature-settings
-  feature-user → common-network, common-utils
-```
-
-### 层 2: @Component 组件分析
-
-**扫描文件**: `*/pages/*.ets`, `*/components/*.ets`
-
-**提取内容**:
-- 组件名 + `@Component` 装饰器
-- `build()` 方法中的 UI 结构
-- 状态变量（`@State`, `@Prop`, `@Link`, `@Provide`, `@Consume`）
-- `@Watch` 回调
-- `@Builder` 方法
-
-**输出示例**:
-```
-### UserListPage
-- **路径**: `entry/src/main/ets/pages/UserListPage.ets`
-- **装饰器**: @Entry, @Component
-- **状态变量**:
-  | 变量 | 装饰器 | 类型 | 初始值 | 说明 |
-  |------|--------|------|--------|------|
-  | userList | @State | UserVO[] | [] | 用户列表 |
-  | isLoading | @State | boolean | false | 加载状态 |
-  | searchQuery | @State | string | '' | 搜索关键词 |
-  | userService | - | UserService | new UserService() | 服务实例 |
-- **@Watch**:
-  | 变量 | 回调 | 说明 |
-  |------|------|------|
-  | searchQuery | onSearchQueryChange | 防抖搜索 |
-- **@Builder**:
-  | 名称 | 说明 |
-  |------|------|
-  | UserItemBuilder | 用户列表项 |
-  | EmptyViewBuilder | 空状态视图 |
-- **UI 结构**:
-  Column() {
-    SearchBar({ placeholder: '搜索用户' })
-      .onChange((value) => this.searchQuery = value)
-    if (this.isLoading) { Progress() }
-    else if (this.userList.length === 0) { this.EmptyViewBuilder() }
-    else { List() { ForEach(this.userList, (item) => { this.UserItemBuilder(item) }) } }
-  }
-```
-
-### 层 3: ViewModel / 状态管理分析
-
-**扫描文件**: `*/viewmodel/*.ets`
-
-**输出示例**:
-```
-### UserViewModel
-- **路径**: `feature-user/src/main/ets/viewmodel/UserViewModel.ts`
-- **状态变量**:
-  | 变量 | 装饰器 | 类型 | 说明 |
-  |------|--------|------|------|
-  | users | @Provide | UserVO[] | 用户列表 |
-  | isLoading | @Provide | boolean | 加载状态 |
-  | currentPage | @State | number | 当前页码 |
-- **方法**:
-  | 方法 | 签名 | 说明 |
-  |------|------|------|
-  | loadUsers | async () => Promise<void> | 加载用户列表 |
-  | searchUsers | (query: string) => void | 搜索用户 |
-  | deleteUser | (id: number) => Promise<void> | 删除用户 |
-- **AppStorage**: 'userToken' (全局共享)
-```
+ArkUI 组件层次结构识别：
+- `@Entry @Component` → 页面根组件（每个页面文件有且仅有一个）
+- `@Component` → 普通自定义组件（可复用）
+- `@Builder` 方法 → 轻量级 UI 构建函数（不含状态）
 
-### 层 4: 资源文件分析
+状态管理模式检测：
 
-**扫描文件**: `resources/base/element/*.json`
+| 模式 | 识别特征 | 适用范围 |
+|------|---------|---------|
+| 组件内状态 | `@State` | 组件自身 |
+| 父子通信 | `@Prop`（单向）/ `@Link`（双向） | 父子组件 |
+| 跨组件共享 | `@Provide` + `@Consume` | 祖先到后代 |
+| 全局状态 | `AppStorage.setOrCreate()` / `@StorageProp` | 整个应用 |
+| 持久化状态 | `PersistentStorage.persistProp()` | 跨会话持久化 |
 
-**输出示例**:
-```
-### 字符串资源
-| Key | 中文 | 英文 |
-|-----|------|------|
-| app_name | 用户管理 | User Management |
-| login_button | 登录 | Login |
-| search_placeholder | 搜索 | Search |
+## 数据流模式
 
-### 颜色资源
-| Key | 值 | 用途 |
-|-----|------|------|
-| primary_color | #007DFF | 主色调 |
-| text_primary | #182431 | 主文本色 |
-| background_color | #F1F3F5 | 背景色 |
+- **组件状态流**：`@State` 变量修改 → ArkUI 框架自动触发 `build()` 重绘
+- **跨组件流**：`@Provide('key') data` → `@Consume('key') data`（无需逐层传递）
+- **AppStorage 全局流**：`AppStorage.set('key', value)` → `@StorageProp('key')` 自动同步
+- **网络数据流**：`@ohos.net.http` HttpRequest → Promise.then() → `@State` 更新 → UI 重绘
 
-### 浮点数资源
-| Key | 值 | 用途 |
-|-----|------|------|
-| spacing_xs | 4vp | 极小间距 |
-| spacing_sm | 8vp | 小间距 |
-| spacing_md | 16vp | 中间距 |
-| spacing_lg | 24vp | 大间距 |
-```
+## 分析关注点
 
-### 层 5: 网络请求分析
+- **Ability 发现（UIAbility/ServiceAbility）**：`module.json5` 是权威来源，需枚举所有 `abilities` 和 `extensionAbilities`，识别入口和后台服务
+- **ArkUI 组件树**：`@Entry` 组件的 `build()` 方法是页面 UI 结构的起点，需提取 1-2 层子组件
+- **hap/hsp 模块结构**：HAP（可独立安装）vs HSP（共享包），区分模块类型影响分包策略分析
+- **`oh-package.json5` 依赖**：三方库均通过此文件管理，需完整提取，识别 `@ohos.*` 系统能力调用
+- **Navigation 组件**：API 9+ 推荐使用 `Navigation` + `NavPathStack` 替代旧版 `router`，需识别路由方案
+- **资源文件**：`resources/base/element/*.json` 包含字符串/颜色/尺寸，影响国际化分析
 
-**扫描文件**: `*/service/*Http*.ets`, `*/network/*.ets`
+## 输出示例
 
-**输出示例**:
 ```
-### 网络配置
-- **文件**: `common-network/src/main/ets/utils/HttpUtil.ets`
-- **baseURL**: `https://api.example.com`
-- **超时**: 15000ms
-- **Header**: `Content-Type: application/json`, `Authorization: Bearer {token}`
-- **拦截器**:
-  | 拦截器 | 说明 |
-  |--------|------|
-  | AuthInterceptor | 注入 token |
-  | ErrorHandler | 统一错误处理 |
+### 模块结构（build-profile.json5）
+| 模块名 | 类型 | 入口 Ability | 职责 |
+|--------|------|-------------|------|
+| entry | HAP (Entry) | EntryAbility | 主入口，首页 + 导航 |
+| feature-user | HAP (Feature) | - | 用户管理功能 |
+| feature-settings | HAP (Feature) | - | 设置功能 |
+| common-network | HSP | - | 网络请求公共库 |
+| common-utils | HSP | - | 工具函数公共库 |
+
+模块依赖: entry → feature-user, feature-settings
+feature-* → common-network, common-utils
+
+### 技术栈检测
+- ArkUI 版本: API 11 (HarmonyOS 4.1)
+- 路由方案: Navigation + NavPathStack（新版）
+- 状态管理: @State / @Provide-@Consume / AppStorage
+- 网络: @ohos.net.http + 自封装 HttpUtil
+- 持久化: @ohos.data.preferences + relationalStore (RDB)
+
+### Ability 清单
+| Ability | 类型 | exported | 说明 |
+|---------|------|---------|------|
+| EntryAbility | UIAbility | true | 应用主入口 |
+| BackgroundTaskAbility | ServiceExtensionAbility | false | 后台任务 |
 ```
-
-## 输出模板
-
-### README.md 章节结构
-
-```markdown
-# {应用名}
-
-## 项目概述
-应用功能描述
-
-## 技术栈
-| 技术 | 版本 | 用途 |
-|------|------|------|
-
-## 架构设计
-### 架构图（ASCII）
-### 模块依赖图
-
-## 模块说明
-Entry/Feature/Common 各模块职责
-
-## 页面结构
-页面列表 + 路由关系
-
-## 组件文档
-@Component 列表
-
-## 资源文件
-字符串/颜色/尺寸资源
-
-## 构建 & 部署
-DevEco Studio + hvigor 命令
-```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面层 | `entry/src/main/ets/pages/` | 每个子目录或文件 | 名称 kebab-case |
-| 服务层 | `entry/src/main/ets/services/` | 每个子目录 | 目录名 kebab-case |
-| 状态管理层 | `AppStorage`, `LocalStorage` | 按业务域分组 | 业务域 kebab-case |
-| 组件层 | `entry/src/main/ets/components/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| Feature 模块 | 每个 feature 目录 | 独立模块 | 目录名 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `EntryAbility.ts`, `Index.ets`）
-- 纯导出桶文件（仅有 re-export）
-- 工具函数目录（`utils/`, `common/`）— 合并为一个模块
-- `.preview/`, `oh_modules/` 跳过
-
-## Token 管理
-
-- 大模块（>15 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- 资源文件（JSON）单独分析
-- `build-profile.json5` 和 `oh-package.json5` 单独分析
-- `.preview/` 目录跳过
-- `oh_modules/` 目录跳过