# 模块分解与知识点规划

## 1. 模块分解表

| # | 模块名称 | 源码目录 | 关键文件 | 复杂度 | 优先级 |
|---|----------|----------|----------|--------|--------|
| 1 | standard | `standard/` | appspawn_service.c, appspawn_main.c, appspawn_msgmgr.c, appspawn_appmgr.c, appspawn_manager.h, appspawn_fd_manager.c | High | P0 |
| 2 | sandbox | `modules/sandbox/` | sandbox_core.cpp, sandbox_common.cpp, sandbox_shared_mount.cpp, sandbox_unlock_mount.cpp, sandbox_dec.c, appspawn_permission.c | High | P0 |
| 3 | spm | `modules/spm/` | spm.c, spm_permission.c, tlv_builder.c | High | P0 |
| 4 | common_modules | `modules/common/` | appspawn_common.c, appspawn_cgroup.c, appspawn_namespace.c, appspawn_isolate.c, appspawn_adapter.cpp, appspawn_encaps.c | Medium | P1 |
| 5 | ace_adapter | `modules/ace_adapter/` | ace_adapter.cpp, appspawn_checkpoint.c, command_lexer.cpp, dfx_preload.cpp | Medium | P1 |
| 6 | client_api | `interfaces/innerkits/` | appspawn_client.c, appspawn_msg.c, appspawn.h, appspawn_client.h | Medium | P0 |
| 7 | modulemgr_engine | `modules/modulemgr/`, `modules/module_engine/` | appspawn_modulemgr.c, appspawn_hook.h, appspawn_msg.h | Medium | P1 |
| 8 | util | `util/` | appspawn_utils.c, appspawndf_utils.cpp, appspawn_error.h | Low | P2 |
| 9 | server_common | `common/` | appspawn_server.c, appspawn_server.h, appspawn_trace.cpp | Low | P2 |
| 10 | hnp | `service/hnp/` | hnp_main.c, hnp_installer.c, hnp_pack.c, hnp_base.h | Medium | P2 |
| 11 | lite | `lite/` | main.c, appspawn_service.c, appspawn_message.c, appspawn_process.c | Low | P2 |
| 12 | adapters | `modules/native_adapter/`, `modules/nweb_adapter/`, `modules/sysevent/`, `modules/asan/` | native_adapter.cpp, nwebspawn_adapter.cpp, appspawn_hisysevent.cpp, asan_detector.c | Low | P2 |

---

## 2. 知识点规划

### Module: standard

**KP-1 [P0]**: 进程孵化主流程 (appspawn_main.c → StartSpawnService → runAppSpawn)
- 待探索: main() 函数如何解析参数、选择模式、启动服务并进入事件循环
- 预期证据: `appspawn_main.c:101-162` 的 main 函数、模式选择逻辑
- 相关文件: `standard/appspawn_main.c`, `standard/appspawn_service.c`

**KP-2 [P0]**: fork 与子进程管理 (appspawn_service.c)
- 待探索: fork 流程、prefork 机制、子进程通过 pipe 通信、AppSpawningCtx 生命周期
- 预期证据: `appspawn_service.c` 中的 AppSpawnProcessMsg、AppSpawnChild 函数
- 相关文件: `standard/appspawn_service.c`, `standard/appspawn_manager.h`

**KP-3 [P0]**: 消息接收与 TLV 解析 (appspawn_msgmgr.c)
- 待探索: socket 消息接收、分片重组、TLV 格式解析、消息验证
- 预期证据: `appspawn_msgmgr.c` 中的 OnReceiveRequest、ProcessRecvMsg
- 相关文件: `standard/appspawn_msgmgr.c`, `modules/module_engine/include/appspawn_msg.h`

**KP-4 [P0]**: AppSpawnMgr 核心数据结构 (appspawn_manager.h)
- 待探索: AppSpawnMgr、AppSpawningCtx、AppSpawnedProcess 的关系和使用方式
- 预期证据: `appspawn_manager.h:161-181` 结构体定义
- 相关文件: `standard/appspawn_manager.h`

**KP-5 [P1]**: 已孵化进程管理 (appspawn_appmgr.c)
- 待探索: 进程注册、查找、终止、遍历操作
- 预期证据: `appspawn_appmgr.c` 中的 AddSpawnedProcess、GetSpawnedProcess
- 相关文件: `standard/appspawn_appmgr.c`

**KP-6 [P1]**: FD 管理与传递 (appspawn_fd_manager.c)
- 待探索: 文件描述符在父子进程间的传递机制
- 预期证据: `appspawn_fd_manager.c` 中的 FD 管理函数
- 相关文件: `standard/appspawn_fd_manager.c`, `standard/appspawn_fd_manager.h`

**KP-7 [P1]**: 信号处理与看门狗 (appspawn_kickdog.c, pid_ns_init.c)
- 待探索: SIGCHLD 处理、看门狗机制、PID namespace 初始化
- 预期证据: `appspawn_kickdog.c`、`pid_ns_init.c`
- 相关文件: `standard/appspawn_kickdog.c`, `standard/pid_ns_init.c`

**KP-8 [P0]**: 多种孵化模式（appspawn/nwebspawn/nativespawn/hybridspawn/cold run）
- 待探索: 不同模式（spawn vs cold run）的启动差异、RunMode 枚举的使用
- 预期证据: `appspawn_main.c:31-45` 的模式模板定义、`appspawn_service.h:65-71`
- 相关文件: `standard/appspawn_main.c`, `common/appspawn_server.h`

### Module: sandbox

**KP-1 [P0]**: 沙箱核心架构 (sandbox_core.h/cpp)
- 待探索: SandboxCore 类的设计、SetAppSandboxProperty 主入口、各阶段处理
- 预期证据: `sandbox_core.h:32-80` 的类定义、SetSandboxProperty 方法
- 相关文件: `modules/sandbox/normal/sandbox_core.cpp`, `modules/sandbox/normal/sandbox_core.h`

**KP-2 [P0]**: 沙箱挂载点管理 (DoAllMntPointsMount)
- 待探索: 如何从 JSON 配置读取挂载点、变量替换、mount 系统调用
- 预期证据: `sandbox_core.cpp` 中 DoAllMntPointsMount 实现
- 相关文件: `modules/sandbox/normal/sandbox_core.cpp`, `appdata-sandbox*.json`

**KP-3 [P0]**: 沙箱配置系统 (appdata-sandbox-*.json)
- 待探索: 多种沙箱配置文件（app/isolated/render/gpu/debug）的加载和差异
- 预期证据: 根目录下的 JSON 配置文件、`sandbox_core.cpp` 中的加载逻辑
- 相关文件: `appdata-sandbox.json`, `appdata-sandbox-isolated.json`, `appdata-sandbox-render.json`

**KP-4 [P1]**: 共享挂载管理 (sandbox_shared_mount.cpp)
- 待探索: 共享挂载的创建、解锁挂载机制
- 预期证据: `sandbox_shared_mount.cpp`、`sandbox_unlock_mount.cpp`
- 相关文件: `modules/sandbox/normal/sandbox_shared_mount.cpp`

**KP-5 [P1]**: DEC（分布式加密）策略 (sandbox_dec.c)
- 待探索: DEC 策略设置、目录加密、fscrypt 配置
- 预期证据: `sandbox_dec.c` 中的策略设置函数
- 相关文件: `modules/sandbox/sandbox_dec.c`, `modules/sandbox/sandbox_dec.h`

**KP-6 [P1]**: 沙箱权限控制 (appspawn_permission.c)
- 待探索: 沙箱内的权限检查和挂载权限
- 预期证据: `appspawn_permission.c` 中的权限函数
- 相关文件: `modules/sandbox/appspawn_permission.c`

### Module: spm

**KP-1 [P0]**: SPM 核心架构 (spm.h/spm.c)
- 待探索: SPM 权限管理的整体设计、与内核的交互、spawnId 机制
- 预期证据: `spm.c` 中的核心函数、`spm.h:74-83` 的接口定义
- 相关文件: `modules/spm/spm.c`, `modules/spm/spm.h`

**KP-2 [P0]**: 权限消息重建 (OnMessageRebuildFromSPM)
- 待探索: 从内核获取 SPM 数据并重建 TLV 消息的流程
- 预期证据: `spm.c` 中 OnMessageRebuildFromSPM 函数
- 相关文件: `modules/spm/spm.c`

**KP-3 [P1]**: 引用计数管理 (OnSpawnAbortUpdateRefCount, OnAppExitUpdateRefCount)
- 待探索: tokenid 和 uid 的引用计数管理、spawn abort 时的资源回收
- 预期证据: `spm.c` 中引用计数相关函数、`spm.h:37-39` 的标志位定义
- 相关文件: `modules/spm/spm.c`

**KP-4 [P1]**: TLV 构建器 (tlv_builder.c)
- 待探索: SPM 权限数据如何构建为 TLV 格式
- 预期证据: `tlv_builder.c` 中的构建函数
- 相关文件: `modules/spm/tlv_builder.c`, `modules/spm/tlv_builder.h`

**KP-5 [P1]**: APL 等级与权限映射 (spm_permission.c)
- 待探索: APL（Ability Privilege Level）等级如何映射到具体权限
- 预期证据: `spm_permission.c`、`spm.h:67-72` 的 AplLevel 枚举
- 相关文件: `modules/spm/spm_permission.c`

### Module: common_modules

**KP-1 [P1]**: Cgroup 配置管理 (appspawn_cgroup.c)
- 待探索: cgroup 路径设置、进程 cgroup 归属
- 预期证据: `appspawn_cgroup.c` 中的 cgroup 操作函数
- 相关文件: `modules/common/appspawn_cgroup.c`

**KP-2 [P1]**: 命名空间管理 (appspawn_namespace.c)
- 待探索: mount namespace、pid namespace 的设置
- 预期证据: `appspawn_namespace.c` 中的 namespace 操作
- 相关文件: `modules/common/appspawn_namespace.c`

**KP-3 [P1]**: 进程隔离 (appspawn_isolate.c)
- 待探索: 进程隔离机制的实现
- 预期证据: `appspawn_isolate.c` 中的隔离函数
- 相关文件: `modules/common/appspawn_isolate.c`

**KP-4 [P2]**: 通用适配层 (appspawn_adapter.cpp)
- 待探索: 外部依赖适配、SELinux 上下文设置
- 预期证据: `appspawn_adapter.cpp` 中的适配函数
- 相关文件: `modules/common/appspawn_adapter.cpp`

**KP-5 [P2]**: 封装工具与 SILK 引擎 (appspawn_encaps.c, appspawn_silk.c)
- 待探索: 进程信息封装、SILK 引擎集成
- 预期证据: `appspawn_encaps.c`、`appspawn_silk.c`
- 相关文件: `modules/common/appspawn_encaps.c`, `modules/common/appspawn_silk.c`

### Module: ace_adapter

**KP-1 [P1]**: ACE 适配主流程 (ace_adapter.cpp)
- 待探索: ACE 引擎适配、模块注册、Hook 挂载
- 预期证据: `ace_adapter.cpp` 中的模块初始化和 Hook 注册
- 相关文件: `modules/ace_adapter/ace_adapter.cpp`

**KP-2 [P1]**: Checkpoint/镜像进程管理 (appspawn_checkpoint.c)
- 待探索: 镜像进程的创建和管理、checkpoint ID 机制
- 预期证据: `appspawn_checkpoint.c` 中的 checkpoint 函数
- 相关文件: `modules/ace_adapter/appspawn_checkpoint.c`

**KP-3 [P2]**: 命令解析器与 DFX 预加载
- 待探索: 命令行解析、DFX 预加载机制
- 预期证据: `command_lexer.cpp`、`dfx_preload.cpp`
- 相关文件: `modules/ace_adapter/command_lexer.cpp`, `modules/ace_adapter/dfx_preload.cpp`

### Module: client_api

**KP-1 [P0]**: 客户端 SDK 架构 (appspawn.h)
- 待探索: 公共 API 设计、AppSpawnClientHandle/AppSpawnReqMsgHandle 句柄模型
- 预期证据: `appspawn.h:39-45` 的类型定义和 API 声明
- 相关文件: `interfaces/innerkits/include/appspawn.h`

**KP-2 [P0]**: 消息构造与发送 (appspawn_msg.c, appspawn_client.c)
- 待探索: TLV 消息构建流程、socket 通信、线程安全设计
- 预期证据: `appspawn_msg.c` 中的消息构建、`appspawn_client.c` 中的发送逻辑
- 相关文件: `interfaces/innerkits/client/appspawn_msg.c`, `interfaces/innerkits/client/appspawn_client.c`

**KP-3 [P0]**: DAC/权限信息设置 API
- 待探索: AppSpawnClientSetAppDacInfo、AppSpawnClientAddPermission 等 API
- 预期证据: `appspawn.h` 中的 API 声明、`appspawn_msg.c` 中的实现
- 相关文件: `interfaces/innerkits/include/appspawn.h`, `interfaces/innerkits/client/appspawn_msg.c`

**KP-4 [P1]**: 客户端连接管理
- 待探索: 连接池、超时重试、多线程支持
- 预期证据: `appspawn_client.h:74-82` 的 AppSpawnReqMsgMgr 结构体
- 相关文件: `interfaces/innerkits/client/appspawn_client.h`, `interfaces/innerkits/client/appspawn_client.c`

### Module: modulemgr_engine

**KP-1 [P0]**: Hook 阶段定义与执行 (appspawn_hook.h)
- 待探索: AppSpawnHookStage 枚举的各阶段含义、Hook 优先级机制
- 预期证据: `appspawn_hook.h:60-87` 的阶段和优先级定义
- 相关文件: `modules/module_engine/include/appspawn_hook.h`

**KP-2 [P1]**: 模块加载与管理 (appspawn_modulemgr.c)
- 待探索: 模块动态加载（dlopen）、MODULE_CONSTRUCTOR 宏、模块类型过滤
- 预期证据: `appspawn_modulemgr.c` 中的加载函数
- 相关文件: `modules/modulemgr/appspawn_modulemgr.c`, `modules/modulemgr/appspawn_modulemgr.h`

**KP-3 [P1]**: TLV 消息类型系统 (appspawn_msg.h)
- 待探索: TLV 消息结构体、AppSpawnMsg 格式、magic 验证
- 预期证据: `appspawn_msg.h:54-66` 的类型枚举、`:135-142` 的消息头
- 相关文件: `modules/module_engine/include/appspawn_msg.h`

### Module: util

**KP-1 [P2]**: 通用工具函数 (appspawn_utils.c)
- 待探索: 字符串处理、路径操作、日志宏
- 预期证据: `appspawn_utils.c` 中的工具函数
- 相关文件: `util/src/appspawn_utils.c`, `util/include/appspawn_utils.h`

**KP-2 [P2]**: 错误码体系 (appspawn_error.h)
- 待探索: 错误码分类和定义
- 预期证据: `appspawn_error.h` 中的错误码枚举
- 相关文件: `util/include/appspawn_error.h`

### Module: server_common

**KP-1 [P2]**: AppSpawnContent 与服务创建 (appspawn_server.c/h)
- 待探索: AppSpawnContent 结构体的设计、socket 服务创建流程
- 预期证据: `appspawn_server.h:98-120` 的 AppSpawnContent 定义
- 相关文件: `common/appspawn_server.c`, `common/appspawn_server.h`

**KP-2 [P2]**: 性能追踪 (appspawn_trace.cpp)
- 待探索: HiTrace 集成、性能埋点
- 预期证据: `appspawn_trace.cpp` 中的 trace 函数
- 相关文件: `common/appspawn_trace.cpp`, `common/appspawn_trace.h`

### Module: hnp

**KP-1 [P2]**: HNP 服务架构
- 待探索: 原生包安装服务的主流程
- 预期证据: `hnp_main.c` 中的服务入口
- 相关文件: `service/hnp/hnp_main.c`, `service/hnp/installer/src/hnp_installer.c`

### Module: lite

**KP-1 [P2]**: 小型系统 appspawn 实现
- 待探索: 轻量级 appspawn 的简化实现
- 预期证据: `lite/main.c`、`lite/appspawn_service.c`
- 相关文件: `lite/main.c`, `lite/appspawn_service.c`

### Module: adapters

**KP-1 [P2]**: 原生适配器与 NWeb 适配器
- 待探索: nativespawn 和 nwebspawn 的适配逻辑
- 预期证据: `native_adapter.cpp`、`nwebspawn_adapter.cpp`
- 相关文件: `modules/native_adapter/native_adapter.cpp`, `modules/nweb_adapter/nwebspawn_adapter.cpp`

**KP-2 [P2]**: 系统事件与 ASAN 检测
- 待探索: HiSysEvent 上报、ASAN 检测器
- 预期证据: `appspawn_hisysevent.cpp`、`asan_detector.c`
- 相关文件: `modules/sysevent/appspawn_hisysevent.cpp`, `modules/asan/asan_detector.c`

---

## 3. 模块依赖图

```mermaid
graph LR
    standard --> modulemgr_engine
    standard --> server_common
    standard --> util
    standard --> client_api
    sandbox --> modulemgr_engine
    sandbox --> util
    spm --> modulemgr_engine
    spm --> util
    common_modules --> modulemgr_engine
    ace_adapter --> modulemgr_engine
    modulemgr_engine --> client_api
    server_common --> util
    client_api --> util
    adapters --> modulemgr_engine
    hnp --> util
    lite --> client_api
```

---

## 4. 探索顺序建议

1. **modulemgr_engine** — 无外部依赖（仅依赖 client_api 的头文件），是所有 Hook 模块的基础
2. **client_api** — 定义了消息格式和公共 API，是理解所有通信的基础
3. **util** — 工具层，被所有模块依赖
4. **standard** — 核心服务，依赖前三者
5. **server_common** — 通用服务层
6. **sandbox** — 沙箱模块，依赖 modulemgr_engine
7. **spm** — 权限管理，依赖 modulemgr_engine
8. **common_modules** — 通用功能模块
9. **ace_adapter** — ACE 适配
10. **adapters** — 各类适配器
11. **hnp** — 独立服务
12. **lite** — 小型系统实现

---

## 5. 并行化机会

```
并行组 1: modulemgr_engine, client_api, util（无相互依赖）
并行组 2: standard, server_common（依赖组 1）
并行组 3: sandbox, spm, common_modules, ace_adapter, adapters（依赖组 1，彼此独立）
并行组 4: hnp, lite（独立服务，可随时探索）
```