原始记录：2026-04-10；设备实践补记：2026-04-16。
这是私人笔记的公开脱敏整理版。真实设备地址、序列号、主机名、账号和内部路径已移除。历史结论不代表上游项目当前状态；实际执行以 SKILL.md 为准。
DroidClaw 探索让 AI 根据自然语言目标操作 Android：读屏、判断、点击或输入，再观察结果。
本项目把这一方法整理成已有 Agent 可以加载的技能，不另建服务端、MCP Server 或执行引擎。最初面向 Claude Code，现提供 Pi、Codex、Claude Code 和 OpenCode 的接入说明。
原始应用场景之一是经授权的联系人资料整理。这个背景不意味着技能可以默认读取或导出所有联系人。
现行循环：
观察 → 选择单个动作 → 执行 → 有限等待 → 再观察并验证
原笔记将等待放在验证之后；现行技能调整顺序，避免把尚未完成的页面跳转误判为失败。
| 项目 | 原始建议 | 现行处理 |
|---|---|---|
| 卡住 | 连续 3 步画面不变 | 结合预期效果、焦点和控件状态判断进展 |
| 重复 | 最近 8 步同一动作至少 3 次 | 同时考虑目标与界面状态；有效滚动不算无效重复 |
| 漂移 | 最近 5 步中至少 4 步为导航 | 仅在导航没有带来目标进展时复核 |
| 最大步数 | 30 | 默认 30 个状态变更动作，包含重试与设置变更 |
| 等待 | 0.5–2 秒 | 按点击、页面切换和网络响应分层等待 |
| 总时限 | 未明确 | 默认 5 分钟，为恢复预留预算 |
| 视觉模式 | fallback | XML 不足时使用截图，要求真实图像读取能力 |
这些是启发式参数，不是跨设备实验得出的最优值。长任务应预先约定有限预算与检查点。
程序化操作和 Intent 可以更可靠，但不能绕过授权。打开草稿和直接发送、打开拨号器和立即呼叫，是不同的副作用。
| 方式 | 当时笔记的记录 | 本仓库 |
|---|---|---|
| 手动目标 | REST API POST /goals |
用户向 Agent 提出任务，不提供该 API |
| 定时执行 | QStash 调度回调 | 不提供调度器 |
| 通知触发 | 当时记为 v2 设计，未实现 | 不监听通知，不运行后台服务 |
这些记录没有绑定可核验的上游 commit，不能当作当前功能清单。原笔记对早期通知方案的复盘也未经本次逐项复核；可保留的设计原则是：用户显式定义工作流、限定 App 和数据范围、确认外部动作、记录必要结果并限制频率。
任何通知自动化都应单独设计权限、留存、幂等性与停止机制，不直接扩展本技能去读取全部通知。
当时在一台 Redmi 测试手机上尝试过 Google 服务、USB、局域网和 Tailscale 连接。以下是可迁移的教训，而非所有 ROM 的通用配置：
- Google 服务：当时直接启用包因权限不足失败，需要先检查系统界面的总开关。这不是 ADB 的前提；现行技能不批量启用系统包。
- 多条连接路径：历史记录有远程打开 App 的成功尝试，但不能作为修订版全流程已测试的证据。
- VPN 冲突：Android 通常在同一用户／配置文件中只允许一个活动 VPN 服务。切换前必须确认当前 ADB 是否依赖它，并保留 USB 或人工恢复路径。
- 重启恢复：传统 TCP 调试常需重新启用；配对式无线调试应另行检查当前端口与状态。
- OEM 开关：基础 USB 调试、触摸注入安全设置、USB 安装可能分开。命令退出码为 0 不证明点击已生效。
现行文档不保存真实连接地址，不把 VPN 当作所有 ADB 接口的保护，也不未经批准停止 VPN。
| 旧问题 | 现行规则 |
|---|---|
| 命令成功就假定操作成功 | 区分确认成功、确认失败和结果未知 |
| 连续扫描坐标、串联点击和输入 | 每次一个交互，再观察 |
| 清空字段的组合键不可靠 | 使用可见操作或经验证的输入法能力 |
| 原始 Unicode 直接嵌入 Shell | 经授权的 UTF-8 base64 输入，随后验证 |
| 同名项目就去重或判定结束 | 使用标识、视口变化、加载与终点证据 |
| 默认改休眠时间和输入法 | 默认不改；必要时授权、记录原值并恢复 |
| 只限定设备，不明确用户 | 用户相关设置与安装显式限定 Android 用户 |
| 泛泛提示辅助输入法风险 | 说明广播接收器暴露及临时使用边界 |
| 界面变化后一律要求截图 | 刷新有效观察；XML 足够时不强制视觉 |
| 用完预算才考虑恢复 | 预留恢复预算，停止任务后有限收尾 |
下一步应优先完成真机验收，而不是继续增加后台自动化或跨平台功能。