架构与代码地图

分层原则

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

外部任务源
    │
    ▼
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 单元测试	解析、同步、执行和超时测试

任务同步流程

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

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

任务执行流程

调用方将一个已解析的 AgentTask 交给 TaskExecutor。
执行器依次处理步骤，并在每步操作前检查包名和已声明 Activity。
需要控件的动作通过 ActionDriver.find() 查找节点。
默认要求唯一匹配：零个匹配为未找到，多个匹配为歧义失败。
执行器调用驱动完成点击、输入、返回或文本读取。
每个步骤都有有限超时，最终返回类型化 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、页面状态、恢复策略和真机用例

更具体的操作步骤见常见改动指南。

4.5 KiB Raw Permalink Blame History