AGENTS.md
1. Code map
本 AGENTS.md 适用于 ability_runtime 仓库根目录。子目录 services/abilitymgr/ 和 services/uripermmgr/ 各有独立的 CLAUDE.md，提供更细粒度的架构和开发指引。
本仓库实现 OpenHarmony 元能力运行时（ability_runtime），核心职责是管理应用生命周期、组件调度、Extension 扩展组件管理、URI 权限管理和意图框架。最重要的架构边界是 服务层（services/）与公共 SDK 接口层（interfaces/kits/）之间的双向解耦——服务不可直接暴露内部实现到 SDK，SDK 不可反向依赖服务内部细节。
目录职责
| 目录 | 职责 | 高风险标记 |
|---|---|---|
services/abilitymgr/ |
AbilityManagerService（SA 180）：组件生命周期、启动/停止、连接、任务栈、拦截器、InsightIntent | 🔴 修改影响全局组件调度 |
services/appmgr/ |
AppManagerService（SA 501）：应用进程生命周期、AppSpawn 协调、进程状态、子进程 | 🔴 修改影响所有应用进程 |
services/uripermmgr/ |
UriPermissionManagerService（SA 183）：跨应用 URI 权限授予/撤销/校验 | 🔴 修改影响安全边界 |
services/quickfixmgr/ |
QuickFixManagerService（SA 184）：应用热修复补丁管理 | 🟡 修改影响应用更新流程 |
services/appdfr/ |
应用 DFR：AppFreeze 管理、ANR 监听、崩溃收集 | 🟡 修改影响故障归因 |
services/common/ |
服务侧工具封装：权限校验、日志封装、事件上报、HiSysEvent、XCollie | 🔴 包含 PermissionVerification 全局安全入口 |
interfaces/kits/native/ |
公共 SDK 接口：Ability、Context、Extension、Caller/Callee、AppStartup | 🔴 公共 API 兼容性边界 |
interfaces/kits/c/ |
C 语言公共 API | 🔴 公共 API 兼容性边界 |
interfaces/inner_api/ |
内部组件接口：IPC 客户端/代理/桩、错误码工具 | 🟡 内部接口，但仍需注意 IPC 兼容性 |
frameworks/native/ability/native/ |
原生框架实现：UIAbility、各 Extension、Context、InsightIntent 执行器 | 🟢 客户端侧实现，可随 SDK 接口联动修改 |
frameworks/native/appkit/ |
应用框架：Application、AbilityStage、TestRunner | 🟢 |
frameworks/js/napi/ |
JavaScript NAPI 绑定 | 🟡 NAPI 签名是公共 API |
frameworks/ets/ani/ |
ArkTS ANI 绑定 | 🟡 ANI 签名是公共 API |
frameworks/cj/ffi/ |
CJ FFI 绑定 | 🟡 |
frameworks/c/ |
C API 框架实现 | 🟡 |
agent_runtime_framework/ |
Agent 组件框架：AgentManagerService（SA 185）、AgentExtensinoAbility与AgentUIExtensionAbility | 🟢 |
tools/aa/ |
aa 命令行工具：Ability 调试管理 | 🟢 |
js_environment/ / ets_environment/ / cj_environment/ |
JS/ETS/CJ 运行时环境 | 🟢 |
Where to look
| 任务类型 | 先看 |
|---|---|
| Ability 生命周期（启动/停止/前台/后台） | services/abilitymgr/ → services/abilitymgr/CLAUDE.md |
| 应用进程管理（启动/杀死/预加载/ANR） | services/appmgr/ → app_mgr_service.cpp、app_running_manager.cpp |
| URI 权限（授予/撤销/校验） | services/uripermmgr/ → services/uripermmgr/CLAUDE.md |
| 拦截器相关（启动被拦截/生态规则/Kiosk） | services/abilitymgr/src/interceptor/ |
| 任务栈/Mission 管理 | services/abilitymgr/src/mission/ → mission_list_manager.cpp |
| InsightIntent（意图识别/分发/执行） | services/abilitymgr/src/insight_intent/ + frameworks/native/ability/native/insight_intent_executor/ |
| 新增 Extension 类型 | interfaces/kits/native/ → frameworks/native/ability/native/ → frameworks/ets/ani/ → frameworks/js/napi/ → services/abilitymgr/ |
| 修改公共 SDK API 签名 | interfaces/kits/native/ + interfaces/kits/c/ → 需兼容性评估 |
| NAPI 绑定修改 | frameworks/js/napi/<module>/ → 对应 nativecommon 共享组件 |
| ANI 绑定修改 | frameworks/ets/ani/<module>/ → 对应 ani_common/ 共享组件 |
| 子进程相关 | frameworks/native/child_process/ + services/appmgr/src/child_process_record.cpp |
| 日志/DFX 修改 | services/common/include/hilog_tag_wrapper.h + hisysevent.yaml |
| 错误码修改 | interfaces/inner_api/error_utils/include/ability_runtime_error_util.h + interfaces/kits/native/ability/native/ability_business_error/ability_business_error.h |
| 权限校验逻辑 | services/common/include/permission_verification.h |
| QuickFix 热修复 | services/quickfixmgr/src/quick_fix_manager_service.cpp |
| AppFreeze/崩溃收集 | services/appdfr/src/appfreeze_manager.cpp + application_anr_listener.cpp |
| Agent 组件框架 | agent_runtime_framework/services/agentmgr/ |
| 构建配置/特性开关 | ability_runtime.gni |
| 系统能力注册 | services/sa_profile/ |
2. Knowledge routing
遇到问题先定位场景，再读对应文档。以下文档包含完整领域概念和操作指引，不是可选背景阅读。
Task-based routing
| 任务类别 | 先读 |
|---|---|
| 公共 API 或 SDK 行为变更 | interfaces/kits/native/ability/native/ability_business_error/ability_business_error.h（错误码兼容性边界）+ interfaces/inner_api/error_utils/include/ability_runtime_error_util.h |
| AbilityManagerService 架构或子管理器变更 | services/abilitymgr/CLAUDE.md |
| URI 权限/安全/认证变更 | services/uripermmgr/CLAUDE.md + services/common/include/permission_verification.h |
| DFX/日志/故障归因变更 | services/common/include/hilog_tag_wrapper.h + hisysevent.yaml |
| 构建特性开关变更 | ability_runtime.gni |
| 应用进程管理/AppSpawn 协调变更 | services/appmgr/ → app_mgr_service.h、app_spawn_client.h |
| 拦截器新增或修改 | services/abilitymgr/CLAUDE.md 中的 Interceptor Framework 章节 |
| InsightIntent 意图框架变更 | services/abilitymgr/src/insight_intent/ 目录结构 + 核心功能特性总结.md 意图框架章节 |
Path-based routing
| 修改路径 | 先读 |
|---|---|
services/abilitymgr/ |
services/abilitymgr/CLAUDE.md |
services/uripermmgr/ |
services/uripermmgr/CLAUDE.md |
services/common/ |
services/common/include/permission_verification.h + services/common/include/hilog_tag_wrapper.h |
interfaces/kits/ |
interfaces/kits/native/ability/native/ability_business_error/ability_business_error.h（公共 API 兼容性） |
interfaces/inner_api/error_utils/ |
interfaces/inner_api/error_utils/include/ability_runtime_error_util.h |
frameworks/js/napi/ |
对应模块目录的 native_module.cpp（NAPI 模块注册入口） |
frameworks/ets/ani/ |
对应模块目录的 ANI 注册入口 + ani_common/ 共享工具 |
services/appdfr/ |
services/appmgr/CLAUDE.md（如存在）或 services/appdfr/ 目录头文件 |
Vocabulary-based routing
当任务、issue、日志、API 名称或变更文件包含以下术语时，在规划前先读对应文档：
| 术语 | 风险提示 | 先读 |
|---|---|---|
| UIAbility / Ability | 不是通用"能力"，而是 OpenHarmony 有界面的应用组件核心抽象，有严格生命周期状态机 | services/abilitymgr/CLAUDE.md |
| Extension / ExtensionAbility | 不是通用"扩展"，而是 OpenHarmony 特定的无界面服务组件体系（10+ 类型各有独立生命周期） | services/abilitymgr/CLAUDE.md |
| Want / WantAgent | 不是通用"意图"，而是 OpenHarmony 组件间调度的结构化描述对象，包含 bundle/module/ability 元数据 | interfaces/inner_api/wantagent/ |
| Mission / 任务栈 | 不是通用"任务"，而是 OpenHarmony 管理多 Ability 实例的栈结构，有持久化和跨设备同步 | services/abilitymgr/CLAUDE.md 中 Mission 章节 |
| AppSpawn / 应用孵化 | 不是通用"进程创建"，而是 OpenHarmony 专属的应用进程孵化服务，有安全沙箱和参数注入机制 | services/appmgr/ → app_spawn_client.h |
| URI Permission / UriPerm | 不是通用"文件权限"，而是跨应用临时 URI 访问授权，涉及 Media/Docs/Sandbox 三种分发策略 | services/uripermmgr/CLAUDE.md |
| InsightIntent / 意图框架 | 不是通用"AI 意图"，而是 OpenHarmony 系统级意图标准体系，连接应用内业务功能 | 意图框架章节 |
| Kiosk / 展台模式 | 不是通用"锁定"，而是系统级设备锁定运行模式，涉及拦截器链和启动控制 | services/abilitymgr/CLAUDE.md |
| Interceptor / 拦截器 | 不是通用"中间件"，而是 AbilityManagerService 的启动拦截链，10+ 拦截器按顺序执行 | services/abilitymgr/CLAUDE.md 中 Interceptor 章节 |
| DFX / HiLog / HiSysEvent / XCollie | 不是通用"日志"，而是 OpenHarmony 故障归因体系，事件定义在 hisysevent.yaml 是硬性约束 | hisysevent.yaml + hilog_tag_wrapper.h |
| FreeInstall / 免安装 | 不是通用"按需加载"，而是 OpenHarmony 原子化服务免安装机制，涉及 Bundle 和分发协调 | services/abilitymgr/src/free_install_manager.cpp |
| KeepAlive / 保活 | 不是通用"后台运行"，而是系统级关键进程保活机制，有独立数据管理 | services/abilitymgr/src/keep_alive/ |
| SA / SystemAbility / 系统能力 | 不是通用"微服务"，而是 OpenHarmony 通过 samgr 注册的系统能力，有 SA ID、进程绑定和按需启动配置 | services/sa_profile/ |
| NAPI / ANI / CJ FFI | 三种多语言绑定机制，共享 nativecommon/ani_common 组件，签名变更都是公共 API 变更 | frameworks/js/napi/ + frameworks/ets/ani/ani_common/ |
| PermissionVerification | 不是通用"权限检查"，而是 ability_runtime 的全局安全入口，所有组件操作都经过此单例 | services/common/include/permission_verification.h |
| QuickFix / 热修复 | 不是通用"热更新"，而是 OpenHarmony 应用级补丁机制，有 Apply/Revert 和版本管理 | services/quickfixmgr/ |
| AutoFill / 自动填充 | 不是通用"表单填充"，而是跨应用隐私保护的自动填充扩展，有独立的 Extension 和 Manager | ability_runtime.gni 中 ability_runtime_auto_fill |
在规划中声明：
- 任务类别
- 已读知识文档
- 发现的约束
- 是否需要使用 Skill 或子目录 CLAUDE.md
3. Constraints and boundaries
Architecture/domain invariants
- 公共 SDK 接口（
interfaces/kits/）表达稳定的能力意图，不暴露服务内部实现细节。 - 权限校验必须在能力入口点执行：所有 Ability/Extension 的启动、连接、数据操作均经过
PermissionVerification单例。 - 服务层（
services/）与框架层（frameworks/）通过interfaces/inner_api/的 IPC 接口解耦，不直接引用对方内部头文件。 services/common/是服务层共享基础设施，不依赖特定子服务业务逻辑。- DFX 事件定义（
hisysevent.yaml）是故障归因的硬性合约，事件名、参数类型、级别不可随意修改。 ability_runtime.gni中的特性标志控制编译时行为，默认值变更影响所有下游产品。- FA 模型和 Stage 模型共存：修改任一模型的行为时，必须确认不影响另一模型。
- Mission 持久化数据格式（RDB）是跨版本兼容性约束，不可破坏已写入的数据结构。
Do not
- 不要在
interfaces/kits/中修改公共 API 签名、错误码值、生命周期语义，除非任务明确要求且有兼容性评估。 - 不要在
services/abilitymgr/或services/appmgr/中绕过PermissionVerification的权限校验。 - 不要修改 IPC Stub/Proxy 的序列化格式——它影响跨版本和跨进程兼容性。
- 不要修改
hisysevent.yaml中已发布事件的参数类型或删除参数——影响线上故障归因。 - 不要修改
ability_runtime_error_util.h和ability_business_error.h中已发布的错误码数值——它们是公共合约。 - 不要为通过测试而删除日志、HiSysEvent 事件、错误码或诊断信息。
- 不要在
services/abilitymgr/中直接调用 AppManagerService 内部方法——应通过interfaces/inner_api/app_manager/的 IPC 接口。 - 不要在
frameworks/native/中直接调用services/的内部头文件——应通过interfaces/inner_api/的客户端接口。 - 不要跳过 BUILD.gn 更新——添加源文件后必须更新对应 BUILD.gn 和
.gni源文件列表。 - 不要新增第三方依赖——必须先在
bundle.json中声明并通过 License 审查。
Ask before
- 修改
interfaces/kits/中任何已有 API 的签名或语义。 - 涉及安全/权限/信任的行为变更（特别是 URI 权限、AppSpawn 安全参数、PermissionVerification 规则）。
- 涉及 IPC 协议兼容性或序列化格式变更。
- 涉及 Mission 持久化数据格式变更——影响跨版本数据兼容性。
- 新增或修改第三方依赖、License。
- 删除或重命名公共 API。
- 修改
ability_runtime.gni中特性标志的默认值。 - 修改
services/sa_profile/中 SA 注册配置（SA ID、进程名、库路径）。 - 修改
hisysevent.yaml中已发布事件的定义。 - 修改 FA 模型相关代码（API 8 及更早版本的兼容性约束）。
- 修改 AppSpawn 协调逻辑（影响应用进程安全沙箱）。
- 修改 AppFreeze 或 ANR 检测逻辑（影响线上故障归因）。
反模式（不要这样做）
- ❌ 在
services/abilitymgr/中直接调用 AppMgrService 内部方法（应通过 IPC 接口） - ❌ 在
frameworks/中直接引用services/内部头文件（应通过interfaces/inner_api/） - ❌ 不经兼容性评估修改公共 API 签名或错误码值（应先评估影响范围）
- ❌ 为通过测试删除 HiSysEvent 事件或日志（应修复根因）
- ❌ 绕过 PermissionVerification 权限校验（应确认权限规则）
- ❌ 修改 IPC Stub/Proxy 序列化格式但不更新版本协商（应同时更新兼容性处理）
- ❌ 添加源文件但不更新 BUILD.gn（应同步更新构建定义）
- ❌ 修改特性标志默认值但不通知产品配置团队（应先协调）
4. Verification
构建命令从 OpenHarmony 源码根目录执行，不在本子目录执行。
Minimum checks
- 编译验证：
./build.sh --product-name <product> --build-target ability_runtime - 编译特定服务：
./build.sh --product-name <product> --build-target abilityms（AMS）或libappms（AppMS） - 单元测试：
run -t UT -tp ability_runtime - 模块测试：
run -t UT -ts ability_caller_fw_module_test - Fuzz 测试：
run -t UT -ts AbilityAppDebugInfoFuzzTest
Task-specific checks
| 变更类型 | 最小验证 |
|---|---|
| 修改 AbilityManagerService 内部实现 | 编译通过 + ability_manager_service_first_test 及后续编号单测 |
| 修改 AppManagerService 内部实现 | 编译通过 + app_manager_service_test 相关单测 |
| 修改 URI 权限逻辑 | 编译通过 + uri_permission_manager_test + uri_permission_impl_test |
| 修改拦截器 | 编译通过 + ability_connect_manager_test + 相关拦截器单测 |
| 新增/修改公共 API（interfaces/kits/） | 编译通过 + 全量单测 + NAPI/ANI/CJ 各语言绑定编译 + 兼容性评估 + ability_business_error.h 错误码一致性检查 |
| 新增/修改 NAPI 绑定 | 编译通过 + 对应 NAPI 模块单测 |
| 新增/修改 ANI 绑定 | 编译通过 + 对应 ANI 模块单测 |
| 修改 DFX/日志 | 编译通过 + hisysevent.yaml 事件定义未被破坏 + 相关 DFR 单测 |
| 修改特性标志 | 编译通过 + 受影响模块单测 + 检查 ability_runtime.gni 与 bundle.json features 一致性 |
| 新增 Extension 类型 | 编译通过 + 按步骤清单（7 步）全部完成 + 各层绑定编译 + 服务端管理单测 |
| 仅测试变更 | 运行变更的测试 + 至少一个相邻相关测试 |
Done definition
任务完成仅当：
- 请求的行为已实现。
- 相关编译/测试/lint/兼容性检查已运行，或已说明无法运行的原因。
- 最终回复包含：变更摘要、变更文件列表、验证命令和结果、兼容性/权限/DFX 影响评估（如相关）。
- 不包含无关的格式化、重构或附带变更。
- 如涉及公共 API 变更，已标注兼容性影响。
Final response format
完成任务时，回复应包含：
- 变更摘要
- 变更文件列表
- 验证命令和结果
- 兼容性、权限、DFX 或跨设备影响（如相关）
- 遗留风险或后续项
5. 代码检视
当用户表达"检视一下代码""帮我审一下""做一次 code review""深度扫描""安全审计""查高危 bug""接口审计"等检视意图时，不要凭记忆审查——从代码检视工作台出发：
该 README 是检视的导航与编排中枢，按以下顺序使用：
- 先读 README：了解每个子 skill 的检视维度、触发场景、输出格式，以及按场景选择的 skill 组合表。
- 界定范围：明确目标路径或 Kit、检视重点（通用/安全/高危 bug/API/外部输入）。未明确时向用户确认。
- 调用子 skill：读对应子目录的
SKILL.md按其工作流执行。通用检视默认走deep-scan {path}（一次拿 bug+logic+security 三维度）；接口/SDK 变更补api-audit；服务侧 IPC/持久化密集区补external-input-audit。 - 合并报告：把各 skill 产出汇总为一份
codecheck_report_<scope>_<YYYYMMDD>.md，跨维度去重后按 P0/P1/P1 排序。报告结构见 README 的 Step 4。
检视维度速查
| 维度 | 子 skill | 何时用 |
|---|---|---|
| 高影响缺陷（崩溃/挂死/OOM/UAF/死锁/泄漏） | high-impact-bug-audit |
通用检视、合入前排查 |
| 逻辑影响与一致性 | logic_analyzer |
变更影响评估、状态机/边界 |
| 安全/商用前审查 | security_review |
安全专项、商用前 |
| 外部输入→持久化健壮性 | external-input-audit |
服务侧、IPC/DB/文件密集区 |
| 对外 API 一致性 | api-audit |
接口/SDK 变更、Kit 级审计 |
| 三层编排（bug+logic+security） | deep-scan |
通用深度扫描的默认入口 |
检视约束
- 静态语言实现默认排除（
frameworks/ets/ani/、frameworks/ets/ets/、frameworks/cj/ffi/、ets_*.cpp、cj_*.cpp），除非用户明确要求包含。 - 证据要求：每条发现可追溯到
file:line+ 触发路径，不收无证据的代码气味项。 - 检视阶段不改源码：只产出报告与建议；修复由用户确认后另起任务，并回到本 AGENTS.md 的 Constraints/Verification 章节执行。