95 lines
3.8 KiB
Markdown
95 lines
3.8 KiB
Markdown
# 常见改动指南
|
||
|
||
本页用于快速确定修改范围。开始前仍应阅读相关实现，不把表格当作代码事实的替代品。
|
||
|
||
## 新增或修改任务动作
|
||
|
||
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`；
|
||
- [业务规则与术语](03-business-rules-and-glossary.md)。
|
||
|
||
除非需求明确改变，不把未分配给本机的任务写入 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` 和 [项目概况](00-project-profile.md)，运行完整测试与 Debug 构建。
|
||
|
||
不要只改文档中的版本号来宣称升级完成。
|
||
|
||
## 仅修改文档
|
||
|
||
确认链接、路径、命令、示例和能力状态。文档若描述构建或测试命令，至少实际执行一次；纯措辞调整无需无意义地重跑 Android 构建。
|