35 lines
3.7 KiB
Markdown
35 lines
3.7 KiB
Markdown
# 安卓通用原生控制能力
|
||
|
||
状态：已实现并完成本次验收。沿用 main，不创建开发分支；结果见 [验证记录](2026-11-02-native-actions-validation.md)。正式版本发布单独履行发布门槛。
|
||
|
||
## 完整范围
|
||
|
||
1. 同步双指缩放/旋转；单次本机调用完成，两指同时接触。
|
||
2. 有界条件等待：出现/消失、可用/选中、文本/数值及持续稳定；观测失败不等于目标消失。
|
||
3. 原生控件范围、当前值、支持动作的只读查询与严格设值。
|
||
4. 唯一实时原生节点动作，保留过期目标、歧义、未支持与拒绝回执。
|
||
5. 指定容器内有界滚动到目标，记录中间动作，停止于找到、边界、无进展、取消或超时。
|
||
6. 保持按压的多段触摸轨迹，包括按住后移动；支持多个同时触点。
|
||
7. 精细文本选择、替换选区、指定输入框设值及 IME 提交；Android UTF-16 索引严格校验。
|
||
8. 修复最终验收证据分级：可信常驻当前选时读数与稳定/暂停及固定指针一致时提供秒级证据，保留真实冲突和非选中时间保护。
|
||
|
||
## 共享接口与边界
|
||
|
||
复用已有 Android 助手、driver/controller、action_specs、Flash/Pro 和资源锁。新增 pinch、touch_gesture、read_control、control_action、wait_until、scroll_to；pinch、touch_gesture、control_action 与 wait_until 按明确声明进入 action_sequence。只读工具与写动作分别声明，不开放第二套任务调度或任意系统命令。
|
||
|
||
- read_control/control_action 使用精确 AND selector，至少包含一项语义属性；实时查询唯一节点，返回范围、支持动作、选择区与身份 token。写入可绑定已读 token；拒绝缺失、歧义、过期、越界、非有限值和不支持动作，不隐式退回坐标或重发。
|
||
- touch_gesture 以有界时间关键帧描述一个或多个同步手指，跨段保持同一次接触，整个操作有界；pinch 为该基础的可配置便捷入口。
|
||
- 写请求不经观测 fallback 重放。取消期间已派发动作须有界收尾再释放资源；未知结果保留 possible side effect，不能报告成功。
|
||
- 动作受理、派发完成、APP 值变化和业务验收分别表达；动作回执必须进入模型下一轮、步骤记录和报告。
|
||
- 自绘控件没有原生 range 时明确不支持设值，继续使用双指放大、刻度校准、平移和残差修正。两指距离比例不直接当作 APP 比例尺变化。
|
||
- 保留现有配置、队列、历史和插件授权；不停止用户任务。设备验证固定使用已确认且空闲的模拟器。
|
||
|
||
## 验证与交付门槛
|
||
|
||
- 确定性测试覆盖所有参数边界、身份/动作能力、无输入拒绝、部分回执、取消/超时、写入不重发、UTF-16、条件等待/滚动停止、Flash/Pro 共享入口及参数流保护。
|
||
- 独立原生测试 Activity 验证真实 SeekBar、选择区、多指触点、连续按压、条件变化、列表滚动；使用设备锁，清理自身临时连接，不清空或重置用户 APP。
|
||
- 目标 APP 先观察实际路径，重复验证时间轴缩放、定位与暂停；记录每次误差和成功率，失败样本保留，不以单次成功代替稳定性。
|
||
- 指定历史任务的最终验收使用新规则做只读验证，正反样本覆盖选时读数、事件卡片、浮层冲突及证据不足；不改写历史为人工结论。
|
||
- Python 默认全套、Ruff 两项、质量基线、核心 Pyright；若前端输入发生变化则完成其局部检查。助手重建 APK、版本/协议和 SHA256 必须一致。
|
||
- 交付记录列出全部实际验证与未验证范围；正式发布另须履行最终 ZIP 的双 registry 空缓存构建、标签和公开附件核验。
|