mirror of
https://github.com/openharmony/ability_ability_runtime.git
synced 2026-08-24 22:21:36 -04:00
duansizhao
318 lines
9.4 KiB
Markdown
318 lines
9.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 概述
|
||
|
||
这是 OpenHarmony 的 **ability_runtime** 组件（元能力运行时）。它提供核心组件框架，用于管理应用生命周期、组件调度和扩展组件管理。
|
||
|
||
### 开发者框架
|
||
|
||
**UIAbility 组件**：
|
||
- 提供应用界面的核心组件
|
||
- 支持多实例、多窗口模式
|
||
- 完整的生命周期管理（onStart、onForeground、onBackground、onStop）
|
||
|
||
**Extension 扩展组件**：
|
||
- ServiceExtension：后台服务扩展
|
||
- UIExtension：UI 扩展组件
|
||
- UIServiceExtension：UI 服务扩展
|
||
- AppServiceExtension：应用服务扩展
|
||
- DataShareExtension：数据共享扩展
|
||
|
||
**Uri 授权**：
|
||
- 跨应用 URI 访问权限管理
|
||
- URI 权限授予和撤销
|
||
- 安全的跨进程数据访问
|
||
|
||
**意图框架 (InsightIntent)**：
|
||
- 系统级意图标准体系，连接应用内的业务功能
|
||
- 智能意图识别和分发，支持意图匹配和路由
|
||
- 跨应用意图调度，实现应用间智能协同
|
||
- 帮助开发者将应用内的业务功能智能化
|
||
- 支持配置和装饰器两种方式开发意图
|
||
|
||
**启动框架**：
|
||
- 应用启动流程管理
|
||
- 启动模式和启动规则控制
|
||
- 冷启动、热启动优化
|
||
|
||
**自动填充框架**：
|
||
- 表单自动填充支持
|
||
- 跨应用数据填充
|
||
|
||
**子进程**：
|
||
- 子进程创建和管理
|
||
- 父子进程通信
|
||
- 进程隔离和资源控制
|
||
|
||
**应用上下文环境**：
|
||
- 提供应用级别和组件级别的上下文
|
||
- 支持获取应用信息、资源访问、权限管理
|
||
- 提供应用级数据共享和通信能力
|
||
|
||
**系统环境变化监听**：
|
||
- 配置变化监听（系统语言、主题、方向等）
|
||
- 内存级别变化监听
|
||
- 系统状态变化监听
|
||
|
||
**组件生命周期监听**：
|
||
- UIAbility 生命周期状态变化监听
|
||
- Extension 组件生命周期状态变化监听
|
||
- 进程生命周期监听
|
||
|
||
**任务管理**：
|
||
- 任务栈管理
|
||
- 多任务切换
|
||
- 任务持久化和恢复
|
||
|
||
### 系统服务
|
||
|
||
**组件管理服务**：
|
||
- 管理 UIAbility 和 Extension 组件生命周期
|
||
- 组件启动/停止、连接管理
|
||
- 任务栈和任务列表管理
|
||
- 与应用管理服务协调进行进程管理
|
||
|
||
**应用管理**：
|
||
- 应用进程生命周期管理
|
||
- 与 AppSpawn 服务协调应用孵化
|
||
- 应用状态管理（前台、后台）
|
||
- 进程状态上报、子进程管理、进程预加载
|
||
- 应用恢复和重启
|
||
|
||
**快速修复**：
|
||
- 应用热修复能力
|
||
- 补丁管理和应用
|
||
- 无需重启的修复机制
|
||
|
||
## 构建系统
|
||
|
||
本项目使用 **GN (Generate Ninja)** 作为构建系统。
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
# 构建整个 ability_runtime 组件
|
||
./build.sh --product-name <product> --build-target ability_runtime
|
||
|
||
# 构建特定目标：以abilityms为例
|
||
./build.sh --product-name <product> --build-target abilityms
|
||
|
||
# 构建全量tdd测试用例
|
||
./build.sh --product-name <product> --build-target ability_runtime_test
|
||
|
||
# 构建特定TDD用例：以 ability_manager_service_first_test 为例
|
||
./build.sh --product-name <product> --build-target ability_manager_service_first_test
|
||
```
|
||
|
||
### 清理构建
|
||
|
||
```bash
|
||
./build.sh --product-name <product> --build-target ability_runtime --clean
|
||
```
|
||
|
||
## 测试
|
||
|
||
### 单元测试
|
||
|
||
单元测试位于 `test/unittest/` 并按组件组织。
|
||
|
||
```bash
|
||
# 运行所有单元测试
|
||
run -t UT -tp ability_runtime
|
||
|
||
# 运行特定测试（示例：ability_manager_service_first_test 测试）
|
||
run -t UT -ts ability_manager_service_first_test
|
||
```
|
||
|
||
### 模块测试
|
||
|
||
位于 `test/moduletest/`，以 ability_caller_fw_module_test 为例：
|
||
|
||
```bash
|
||
run -t UT -ts ability_caller_fw_module_test
|
||
```
|
||
|
||
### Fuzz 测试
|
||
|
||
位于 `test/fuzztest/`, 以 AbilityAppDebugInfoFuzzTest 为例：
|
||
|
||
```bash
|
||
run -t UT -ts AbilityAppDebugInfoFuzzTest
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
ability_runtime/
|
||
├── frameworks/ # 框架实现
|
||
│ ├── native/ # C++ 原生框架（ability context，extensions）
|
||
│ ├── js/napi/ # JavaScript NAPI 绑定
|
||
│ ├── ets/ # ETS/ArkTS 绑定（ani - arkts native interface）
|
||
│ ├── cj/ # CJ (C-based JSON) FFI 绑定
|
||
│ └── c/ # ability_runtime 的 C API
|
||
├── interfaces/ # 公共接口
|
||
│ ├── inner_api/ # 内部组件接口（IPC、客户端）
|
||
│ └── kits/ # 公共 SDK 接口（native、C）
|
||
├── services/ # 系统服务
|
||
│ ├── abilitymgr/ # AbilityManagerService
|
||
│ ├── appmgr/ # AppManagerService
|
||
│ ├── dataobsmgr/ # DataObserverManager
|
||
│ ├── uripermmgr/ # UriPermissionManager
|
||
│ ├── quickfixmgr/ # QuickFix 管理器
|
||
│ └── dialog_ui/ # 系统对话框 HAP
|
||
├── agent_runtime_framework/ # Agent 组件框架
|
||
├── service_router_framework/ # 服务路由框架
|
||
├── js_environment/ # JS 运行时环境
|
||
├── ets_environment/ # ETS 运行时环境
|
||
├── cj_environment/ # CJ 运行时环境
|
||
├── tools/aa/ # "aa" 命令行工具
|
||
└── test/ # 测试（unittest、moduletest、fuzztest）
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
#### AbilityManagerService
|
||
位于 `services/abilitymgr/`，这是核心系统能力，负责：
|
||
- 启动和停止组件
|
||
- 管理组件生命周期（onStart、onForeground、onBackground、onStop）
|
||
- 处理组件连接（connectAbility、disconnectAbility）
|
||
- 管理任务栈和任务列表
|
||
- 与 AppManagerService 协调进行进程管理
|
||
|
||
主要子管理器：
|
||
- `AbilityConnectManager`：Extension 扩展组件连接和生命周期管理
|
||
- `DataAbilityManager`：Data Ability 管理
|
||
- `MissionListManager`：任务/任务栈管理（需要图形支持）
|
||
- `PendingWantManager`：待定意图/Want 管理
|
||
- `FreeInstallManager`：免安装（按需）组件支持
|
||
- `KioskManager`：Kiosk 模式管理
|
||
- `AutoStartupService`：自动启动组件管理
|
||
|
||
#### AppManagerService
|
||
位于 `services/appmgr/`，负责管理：
|
||
- 应用进程生命周期
|
||
- 与 AppSpawn 服务协调应用孵化
|
||
- 应用状态（前台、后台）
|
||
- 进程状态上报、子进程管理、进程预加载
|
||
- 应用恢复和重启
|
||
|
||
#### 框架层
|
||
|
||
**Native 框架** (`frameworks/native/`)：
|
||
- `ability/native/`：Ability、AbilityContext、extensions 实现
|
||
- `appkit/`：Application、AbilityStage、TestRunner
|
||
- `child_process/`：子进程管理
|
||
|
||
**NAPI 层** (`frameworks/js/napi/`)：
|
||
- JavaScript/TypeScript 应用的绑定
|
||
- 模块：ability、abilityManager、appManager、context、wantAgent 等
|
||
|
||
**ANI 层** (`frameworks/ets/` 和 `frameworks/ets/ets/`)：
|
||
- ArkTS 原生接口绑定
|
||
- ETS 特定的性能优化实现
|
||
|
||
**CJ 层** (`frameworks/cj/`)：
|
||
- 面向云的语言 (CJ) FFI 绑定
|
||
- 与 Ark 运行时的互操作
|
||
|
||
### 两种应用模型
|
||
|
||
此代码库同时支持 FA（Feature Ability）和 Stage 模型：
|
||
|
||
**FA 模型**（API 8 及更早版本）：
|
||
- 使用 `config.json` 进行模块配置
|
||
- PageAbility、ServiceAbility、DataAbility、FormAbility
|
||
- 每个 Ability 有自己独立的 JS VM 实例
|
||
|
||
**Stage 模型**（API 9+）：
|
||
- 使用 `module.json5` 进行模块配置
|
||
- Ability (UIAbility)、ExtensionAbility 系列
|
||
- 每个进程共享 JS VM 实例
|
||
- 更好地支持复杂应用和分布式场景
|
||
|
||
## 开发说明
|
||
|
||
### 添加新的 Ability 或 Extension
|
||
|
||
1. 在 `interfaces/kits/native/` 中定义扩展类型
|
||
2. 在 `frameworks/native/ability/native/` 中实现
|
||
3. 在 `frameworks/ets/ani/` 中添加 ANI 绑定
|
||
4. 在 `frameworks/js/napi/` 中添加 NAPI 绑定
|
||
5. 在 `services/abilitymgr/` 中添加服务端管理
|
||
6. 更新 BUILD.gn 文件
|
||
7. 在 `test/unittest/` 中添加测试
|
||
|
||
### 特性标志
|
||
|
||
特性标志在 `ability_runtime.gni` 中定义：
|
||
- `ability_runtime_auto_fill`：自动填充扩展支持
|
||
- `ability_runtime_child_process`：子进程支持
|
||
- `ability_runtime_ui_service_extension`：UI 服务扩展
|
||
- `ability_runtime_photo_editor_extension`：照片编辑器扩展
|
||
- `ability_runtime_graphics`：图形依赖特性（任务栈）
|
||
- `ability_runtime_screenlock_enable`：锁屏集成
|
||
|
||
添加条件特性时请检查这些标志。
|
||
|
||
### 错误处理
|
||
|
||
- 使用在 `interfaces/inner_api/error_utils/` 中定义的 `ERR_*` 错误码
|
||
- 常见错误：`ERR_OK`、`ERR_NO_INIT`、`ERR_INVALID_VALUE`、`ERR_INVALID_CALLING`
|
||
- 业务错误在 `frameworks/native/ability/native/ability_business_error.h` 中
|
||
|
||
### 日志记录
|
||
|
||
使用 HiLog 进行日志记录，已封装在hilog_tag_wrapper.h文件中。
|
||
```cpp
|
||
#include "hilog_tag_wrapper.h"
|
||
|
||
// LABEL定义在AAFwkLogTag， 如AAFwkLogTag::ABILITY
|
||
TAG_LOGI(LABEL, "Message: %{public}d", value);
|
||
```
|
||
|
||
### aa 命令
|
||
|
||
`aa` 工具（`tools/aa/`）是 Ability 管理命令行工具，用于调试和管理 Ability 组件。
|
||
|
||
#### 常用命令
|
||
|
||
```bash
|
||
# 启动 Ability
|
||
aa start -a <ability-name> -b <bundle-name> [-D]
|
||
|
||
# 查询并输出系统信息
|
||
aa dump -a
|
||
|
||
# 强制停止应用进程
|
||
aa force-stop <bundle-name>
|
||
```
|
||
|
||
## 配置
|
||
|
||
### 应用模块配置
|
||
|
||
- FA 模型：`entry/src/main/config.json`
|
||
- Stage 模型：`entry/src/main/module.json5`
|
||
|
||
### 系统服务配置
|
||
|
||
- 系统服务配置文件：`services/sa_profile/`
|
||
|
||
## 依赖项
|
||
|
||
主要依赖项（在 `bundle.json` 中定义）：
|
||
- `ability_base`：Ability 基础工具
|
||
- `bundle_framework`：Bundle 管理
|
||
- `eventhandler`：事件处理
|
||
- `ipc`：IPC/RPC 通信
|
||
- `samgr`：系统能力管理器
|
||
- `hilog`：日志记录
|
||
- `window_manager`：窗口管理
|
||
- `ace_engine`：ArkUI 引擎
|
||
- `ets_runtime`：ETS 运行时
|
||
- `napi`：NAPI 框架
|