agent_admin/AGENTS.md

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. 验证

默认从仓库根目录执行：

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

根据改动范围选择验证：

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

APK 默认输出：

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

11. 完成条件

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

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

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