agent_admin/docs/05-common-changes.md

常见改动指南

本页用于快速确定修改范围。开始前仍应阅读相关实现，不把表格当作代码事实的替代品。

新增或修改任务动作

1. 在 core/model/TaskModels.kt 更新 ActionType 和必要模型。
2. 在 core/protocol/TaskParser.kt 解析并校验动作参数。
3. 在 core/executor/TaskExecutor.kt 定义执行语义、超时和失败结果。
4. 如果需要新的 UI 能力，先扩展 ActionDriver，再实现到 AutoAccessibilityService。
5. 更新 docs/agent/actions/ 中对应动作页及动作索引。
6. 补充解析、执行、异常和超时测试。
7. 运行完整单元测试；涉及无障碍实现时再构建 APK 并列出真机验证。

不要只向枚举或 JSON 示例加入动作，也不要把目标 App 业务步骤硬编码到通用执行器。

修改任务协议或选择器

主要检查：

• core/model/TaskModels.kt；
• core/protocol/TaskParser.kt；
• docs/agent/protocol.md、selector.md 和相关动作页；
• TaskParserTest 与受影响的执行器测试。

先明确字段是否必填、默认值、非法值、旧任务兼容和错误表现。协议变更应保持模型、解析器、文档和示例一致。

接入外部任务服务

新增 TaskGateway 实现，将 URL、认证、序列化和网络错误限制在适配层。保留 TaskSynchronizer 的通用职责，不在模型或执行器中直接调用服务端。

在接口明确前不要猜测：

• 请求地址和认证；
• 拉取频率和分页；
• 领取、租约或确认语义；
• 重试、退避和错误码；
• 结果提交及幂等键。

接入后需要补充适配器测试、配置说明和失败场景；若引入后台运行，还要分析 Android 生命周期与系统限制。

修改任务筛选或同步

主要位置是 core/scheduler/TaskSynchronizer.kt。同步检查：

• assignedAgentName 的匹配规则；
• 无效、忽略和保存数量的定义；
• TaskSynchronizerTest；
• 业务规则与术语。

除非需求明确改变，不把未分配给本机的任务写入 SQLite，也不将其记为执行失败。

修改 SQLite

主要位置是 core/persistence/SqliteTaskInbox.kt。修改前明确表结构、唯一键、数据库版本和升级策略。

• 新安装场景需要验证建表和读写；
• 已有发布版本时必须验证旧版本升级路径；
• 幂等规则变化时同步更新业务规则和同步测试；
• 不通过清空用户数据来代替升级实现，除非需求明确允许。

修改执行器或超时

主要位置是 core/executor/TaskExecutor.kt 和 TaskExecutionMutex.kt。检查：

• 包名与 Activity 校验顺序；
• 零个、一个和多个节点的结果；
• 可选步骤与失败传播；
• 超时边界及是否存在无限循环；
• TaskExecutorTest 和 TaskExecutorTimeoutTest。

通用重试应有明确上限；业务页面的恢复策略留给目标 App 适配层。

修改 Android UI、资源或无障碍服务

根据范围检查：

• app/MainActivity.kt；
• AndroidManifest.xml；
• res/values/；
• res/xml/accessibility_service_config.xml；
• core/accessibility/。

运行 assembleDebug。涉及真实节点操作时，补充真机验证，不能只以构建成功作为行为验证。

升级 Gradle、SDK 或依赖

先分析 JDK、Gradle、AGP、Kotlin 和 Android SDK 之间的兼容关系，再统一修改对应构建文件。同步更新 AGENTS.md 和 项目概况，运行完整测试与 Debug 构建。

不要只改文档中的版本号来宣称升级完成。

仅修改文档

确认链接、路径、命令、示例和能力状态。文档若描述构建或测试命令，至少实际执行一次；纯措辞调整无需无意义地重跑 Android 构建。