# 架构与代码地图

## 分层原则

AgentAdmin 当前的 Android Agent 子项目将通用任务能力与 Android 实现分开：

```text
外部任务源
    │
    ▼
TaskGateway → TaskSynchronizer → TaskParser → TaskInbox / SQLite
                                      │
                                      ▼
                                  AgentTask
                                      │
                                      ▼
                              TaskExecutor → ActionDriver
                                                  │
                                                  ▼
                                    AutoAccessibilityService
```

- 核心模型不依赖外部服务或目标 App。
- 执行器只依赖 `ActionDriver`，不直接调用 Android 无障碍 API。
- 服务端差异由 `TaskGateway` 或等价适配器隔离。
- 目标 App 的页面识别和业务步骤应进入独立适配层，不写入通用协议与执行内核。

## 代码地图

所有 Kotlin 源码位于 `android/app/src/`。

| 路径 | 职责 | 主要类型 |
|---|---|---|
| `main/java/cn/auto/agent/core/model/` | 通用任务、步骤、选择器和结果模型 | `AgentTask`、`TaskStep`、`NodeSelector`、`ActionType`、`ResultCode` |
| `main/java/cn/auto/agent/core/protocol/` | JSON 协议解析与校验 | `TaskParser`、`TaskProtocolException` |
| `main/java/cn/auto/agent/core/scheduler/` | 获取、筛选并同步任务 | `TaskGateway`、`TaskSynchronizer`、`TaskSyncSummary` |
| `main/java/cn/auto/agent/core/persistence/` | 任务收件箱抽象与 SQLite 实现 | `TaskInbox`、`SqliteTaskInbox` |
| `main/java/cn/auto/agent/core/executor/` | 步骤执行、超时和进程内互斥 | `TaskExecutor`、`ActionDriver`、`TaskExecutionMutex` |
| `main/java/cn/auto/agent/core/accessibility/` | Android 无障碍驱动与 Activity 跟踪 | `AutoAccessibilityService`、`ActivityTracker` |
| `main/java/cn/auto/agent/app/` | UI、生命周期和依赖装配入口 | `MainActivity` |
| `main/res/` | 字符串、主题和无障碍服务配置 | `strings.xml`、`accessibility_service_config.xml` |
| `test/java/cn/auto/agent/` | JVM 单元测试 | 解析、同步、执行和超时测试 |

## 任务同步流程

1. `TaskGateway.fetchTaskPayloads()` 返回外部任务的原始 JSON 列表。
2. `TaskSynchronizer` 逐条调用 `TaskParser`。
3. 格式无效的任务计入无效数量，不写入数据库。
4. `assignedAgentName` 与本机设备名做区分大小写的精确比较。
5. 不属于本机的任务被忽略，不算本机执行失败。
6. 属于本机的有效任务交给 `TaskInbox.save()`。
7. `SqliteTaskInbox` 以 `task_id + revision` 作为幂等键保存。

同步只负责获取、校验、归属判断和入库，不代表任务已经领取或开始执行。

## 任务执行流程

1. 调用方将一个已解析的 `AgentTask` 交给 `TaskExecutor`。
2. 执行器依次处理步骤，并在每步操作前检查包名和已声明 Activity。
3. 需要控件的动作通过 `ActionDriver.find()` 查找节点。
4. 默认要求唯一匹配：零个匹配为未找到，多个匹配为歧义失败。
5. 执行器调用驱动完成点击、输入、返回或文本读取。
6. 每个步骤都有有限超时，最终返回类型化 `TaskExecutionResult`。

`AutoAccessibilityService` 是当前 Android 驱动实现。它负责把通用驱动调用转换为无障碍节点查询和操作，不应承担服务端协议或目标 App 业务编排。

## 应用入口

`MainActivity` 当前只展示无障碍服务状态并提供打开系统无障碍设置的入口。后台轮询、任务自动启动、结果 Outbox 和服务端提交尚未实现。

## 修改影响

| 需要修改的行为 | 首要代码位置 | 通常还需检查 |
|---|---|---|
| 新增动作 | `TaskModels.kt`、`TaskParser.kt`、`TaskExecutor.kt` | `ActionDriver`、无障碍实现、动作文档和测试 |
| 修改 JSON 字段或校验 | `TaskParser.kt`、模型 | 协议文档、解析测试、兼容性 |
| 修改设备任务筛选 | `TaskSynchronizer.kt` | 业务规则、同步测试 |
| 修改幂等或表结构 | `SqliteTaskInbox.kt` | 数据库版本、升级路径、持久化测试 |
| 接入外部服务 | 新的 `TaskGateway` 实现 | 配置、错误处理、调度测试；不污染核心模型 |
| 修改节点操作 | `AutoAccessibilityService.kt` | 执行器契约、真机验证 |
| 增加目标 App 流程 | 独立适配层 | 包名/Activity、页面状态、恢复策略和真机用例 |

更具体的操作步骤见 [常见改动指南](05-common-changes.md)。