Dduansizhaoadd upms claude.md

8d703a41创建于 3月21日历史提交

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) 作为构建系统。

构建命令

# 构建整个 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

清理构建

./build.sh --product-name <product> --build-target ability_runtime --clean

测试

单元测试

单元测试位于 test/unittest/ 并按组件组织。

# 运行所有单元测试
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 为例：

run -t UT -ts ability_caller_fw_module_test

Fuzz 测试

位于 test/fuzztest/, 以 AbilityAppDebugInfoFuzzTest 为例：

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

在 interfaces/kits/native/ 中定义扩展类型
在 frameworks/native/ability/native/ 中实现
在 frameworks/ets/ani/ 中添加 ANI 绑定
在 frameworks/js/napi/ 中添加 NAPI 绑定
在 services/abilitymgr/ 中添加服务端管理
更新 BUILD.gn 文件
在 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文件中。

#include "hilog_tag_wrapper.h"

// LABEL定义在AAFwkLogTag， 如AAFwkLogTag::ABILITY
TAG_LOGI(LABEL, "Message: %{public}d", value);

aa 命令

aa 工具（tools/aa/）是 Ability 管理命令行工具，用于调试和管理 Ability 组件。

常用命令

# 启动 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 框架