# AgentAdmin 开发规则

本仓库采用需求驱动的轻量开发流程。当前项目是内部系统，不设置额外的敏感数据规则、安全审批门禁、工单门禁、原型门禁或 Wiki 同步门禁。

## 1. 基本原则

- 以用户当前确认的需求为实施依据。
- 收到需求后，先分析目标、现状、范围、约束和验收方式。
- 存在多种实现路径或关键事实不明确时，先与用户讨论方案，不直接猜测。
- 方案确认后按确认方案实施；需求或方案发生变化时，先重新确认再继续。
- 只修改当前需求涉及的内容，不主动扩展无关功能或重构。
- 保留与当前需求无关的工作区改动，不重置、不覆盖。
- 测试结果必须真实；未执行或无法覆盖的验证必须明确说明。

## 2. 标准流程

1. **理解需求**：整理目标、输入、输出、范围、非目标和验收标准。
2. **检查现状**：读取相关代码、配置和文档，确认当前实现，不凭假设修改。
3. **分析方案**：说明模块边界、数据流、接口、持久化、异常处理和测试方式。
4. **讨论确认**：方案存在重要取舍、接口不明确或可能改变既有行为时，等待用户确认。
5. **实施改动**：按照确认方案进行最小且完整的实现。
6. **执行验证**：运行受影响范围的单元测试、构建或其他必要检查。
7. **交付说明**：列出改动文件、实现结果、验证结果和未完成或未验证事项。

对于范围清楚、实现方式唯一、容易回退的小改动，可以在完成分析后直接实施，不必重复请求确认。

## 3. 项目标识

- 仓库 / 项目名：`AgentAdmin`
- 当前 Android 子项目 Gradle 名：`AutoAgent`
- Android 包名 / Application ID：`cn.auto.agent`
- Kotlin namespace：`cn.auto.agent`
- 应用显示名：`Auto Agent`
- 无障碍服务显示名：`autoagent`

`AgentAdmin` 是仓库级项目名；其余为当前 Android 子项目的既有标识。未经用户明确要求，不修改 Android 标识。

## 4. 系统、Java 与依赖版本

### 开发环境基线

以下版本已在当前开发机实际核验：

| 项目 | 版本 / 路径 |
|---|---|
| 操作系统 | Windows 10，版本 `10.0.19045.3803`，amd64 |
| PowerShell 7 | `7.3.12`，有条件时优先使用 |
| Windows PowerShell | `5.1.19041.3803` |
| Java / JDK | Eclipse Temurin OpenJDK `17.0.13+11`，64 位 |
| Git | `2.49.0.windows.1` |
| Android SDK | `C:\Users\ila20\AppData\Local\Android\Sdk` |

开发和构建使用 Java 17；除非依赖升级明确要求，不自行切换 Java 主版本。Android SDK 的本机绝对路径只描述当前开发环境，不写入可提交的 `local.properties` 或业务代码。

### 构建工具版本

| 项目 | 版本 |
|---|---|
| Gradle Wrapper | `8.2` |
| Android Gradle Plugin | `8.2.0` |
| Kotlin Android Plugin | `1.9.22` |
| Java source compatibility | `17` |
| Java target compatibility | `17` |
| Kotlin JVM target | `17` |

`gradlew --version` 显示的 Kotlin `1.8.20` 是 Gradle 自身内嵌的 Kotlin 版本；项目 Kotlin 源码编译版本以 `build.gradle.kts` 声明的 Kotlin Android Plugin `1.9.22` 为准。

### Android SDK 与应用版本

| 项目 | 当前值 |
|---|---:|
| `compileSdk` | `34` |
| `targetSdk` | `34` |
| `minSdk` | `23` |
| `versionCode` | `1` |
| `versionName` | `0.1.0` |

### 生产依赖

| 依赖 | 版本 | 用途 |
|---|---:|---|
| `androidx.appcompat:appcompat` | `1.7.0` | Android 兼容 UI 和 `AppCompatActivity` |
| `com.google.android.material:material` | `1.12.0` | Material Components 主题和控件 |

### 测试依赖

| 依赖 | 版本 | 用途 |
|---|---:|---|
| `junit:junit` | `4.13.2` | JVM 单元测试 |
| `org.json:json` | `20240303` | JVM 测试中的 JSON 实现 |

版本的可执行事实来源依次为 `gradle/wrapper/gradle-wrapper.properties`、根目录 `build.gradle.kts` 和 `app/build.gradle.kts`；本节用于开发约束和快速查阅。升级系统基线、Java、Gradle、AGP、Kotlin、Android SDK 级别或依赖时，必须先分析兼容性，按需求确认方案，然后同步修改构建文件、本节和受影响测试。不得只修改本文档来宣称升级完成。

## 5. 架构与解耦

- 通用任务模型、协议解析、任务同步、持久化、执行器和 Android 无障碍驱动保持分层。
- 核心执行器依赖抽象接口，不直接依赖具体服务端或目标 App 的业务逻辑。
- 外部服务端差异通过 `TaskGateway` 或后续等价适配器隔离。
- Android 无障碍实现通过 `ActionDriver` 向执行器提供能力。
- 目标 App 的包名、页面识别和业务步骤放入独立适配层，不写入通用协议和执行内核。
- 不把 GoAuto 的 PDD、采集、采购、规格、地址或订单业务逻辑带入本项目，除非用户提出明确需求。
- 优先进行满足当前需求的简单实现，不为未确认的未来需求预建复杂框架。

## 6. 当前任务规则

- Agent 从外部服务获取任务列表。
- 任务使用 `assignedAgentName` 指定设备名。
- 只有 `assignedAgentName` 与本机配置的 Agent 设备名精确一致时，任务才允许保存到 SQLite。
- 设备名比较区分大小写，不使用包含、前缀、后缀或模糊匹配。
- 不属于本设备的任务仅忽略，不写入 SQLite，也不作为本设备执行失败处理。
- 格式无效的任务不写入 SQLite，并在同步结果中计入无效任务。
- SQLite 当前以 `task_id + revision` 作为任务版本的幂等键。
- 任务是否入库与任务是否开始执行是两个独立阶段；自动执行、领取、租约和结果提交按后续需求实现。

上述规则可由用户后续需求修改；修改时同步更新实现、测试和本文件中的长期规则。

## 7. 任务执行约定

- 任务步骤使用类型化动作，不通过字符串分支散落实现。
- 新动作需要同步更新模型、协议解析、执行器和测试。
- 控件选择器和执行结果使用通用模型。
- 默认要求控件唯一；匹配多个控件时明确失败，不随意选择第一个。
- 每个步骤必须具有有限超时，任务执行不得无限等待或无限循环。
- 包名和已声明的 Activity 必须在操作前核对。
- 业务特定的页面判断、重试和恢复策略由对应适配层实现。

当前动作：

- `WAIT`
- `CLICK`
- `INPUT`
- `BACK`
- `EXTRACT_TEXT`

当前未实现的动作或能力不能仅通过修改任务 JSON 宣称可用。

## 8. 代码修改规则

- 开始修改前读取相关文件；不要只依据文件名推断实现。
- 优先修改已有抽象，避免复制相同逻辑。
- 保持包职责清晰：
  - `core/model`：通用数据模型；
  - `core/protocol`：任务协议解析和校验；
  - `core/scheduler`：任务获取与同步；
  - `core/persistence`：SQLite 和本地状态；
  - `core/executor`：任务步骤执行；
  - `core/accessibility`：Android 无障碍能力；
  - `app`：界面、生命周期和依赖装配。
- 数据库表结构、任务协议或接口发生变化时，同步更新相关测试和 README。
- 不生成无必要的备份文件、临时脚本或重复文档。

## 9. Git 规则

- 提交前查看工作区状态，确认没有混入无关文件。
- 一个提交只包含一个清晰的交付目标。
- 提交信息简洁描述实际变化。
- 未经用户要求，不自动推送、不发布 APK、不创建标签。
- 不改写用户已有提交，不重置或强制清理工作区。

## 10. 验证

默认从仓库根目录执行：

```powershell
.\android\gradlew.bat -p android test
.\android\gradlew.bat -p android assembleDebug
```

根据改动范围选择验证：

- 模型、协议、同步或执行逻辑：运行相关单元测试，交付前运行 `test`。
- Android Manifest、资源、依赖或应用代码：运行 `assembleDebug`。
- SQLite 结构变化：补充升级或读写测试，并验证旧版本升级路径（存在已发布旧版本时）。
- 无障碍真实操作变化：自动化测试和构建之外，明确列出需要真机验证的目标 App、页面和步骤。

APK 默认输出：

```text
android/app/build/outputs/apk/debug/app-debug.apk
```

## 11. 完成条件

满足以下条件后停止当前任务：

- 已实现用户确认的需求；
- 相关代码和测试保持一致；
- 必要验证已经通过；
- README 或本文件需要记录的长期事实已同步；
- 已向用户说明改动、验证结果以及未验证事项。

发现与当前需求无关的问题时只简要提示，不自动混入本次实现。