# Android Agent 文档中心

本目录集中维护 Android Agent 的任务协议、通用动作和实现建议。根目录的 [`agent_common_action.md`](../agent_common_action.md) 是兼容入口。

## 文档状态

| 标记 | 含义 |
|---|---|
| **[已实现]** | 当前协议和代码已支持 |
| **[部分实现]** | 动作可用，但部分检查或扩展尚未实现 |
| **[提案]** | 后续设计，当前任务不要使用 |

当前解析器会拒绝未知动作，但仍会忽略部分未知字段。任务编写应只使用“已实现”字段，解析器后续应补充未知字段校验，避免参数被静默忽略。

## 文档目录

| 文档 | 内容 |
|---|---|
| [任务协议](protocol.md) | v1 任务结构、步骤字段和当前差距 |
| [动作目录](actions/README.md) | 动作状态、统一规则和各动作入口 |
| [统一选择器](selector.md) | 控件定位、状态和候选数量 |
| [值与输出](values-and-outputs.md) | 输入值、简单引用和步骤输出 |
| [执行与结果](execution.md) | 执行顺序、结果码、重试和幂等 |
| [流程控制](flow-control.md) | 条件执行、有限分支和失败处理 |
| [基本运行约定](security.md) | 包名核对、日志和截图的基本边界 |
| [后续工作建议](roadmap.md) | 推荐实施顺序和测试方式 |
| [参考文档](references.md) | Android API 与能力边界 |

## 事实来源

当前能力以 [`ActionType`](../../android/app/src/main/java/cn/auto/agent/core/model/TaskModels.kt)、[`TaskParser`](../../android/app/src/main/java/cn/auto/agent/core/protocol/TaskParser.kt)、[`TaskExecutor`](../../android/app/src/main/java/cn/auto/agent/core/executor/TaskExecutor.kt) 和 `ActionDriver` 的实际代码为准。

- 编写任务：先读任务协议，再读对应动作的“当前行为”。
- 扩展动作：同时更新模型、解析器、执行器、驱动、测试和文档。
- 共享语义只在共享文档定义，动作文件直接引用，不重复设计。

文档修改后检查相对链接、JSON 示例和动作状态即可，不设置额外审批或文档门禁。