# Computer Use API 对齐计划

目标：逐步完善统一原生应用与浏览器 API，保持官方 DSH Desktop 免补丁，不新增 Electron 运行时。这里的完成状态指源码和测试，发布版本以 README 为准。每阶段独立提交 PR，通过验收后再推进下一阶段；不以方法名相同代替行为一致。

## 阶段与验收

| 阶段 | 范围 | 验收标准 | 状态 |
| --- | --- | --- | --- |
| 1 | 原生 AX 展示差分、完整输出开关 | 返回值保持完整；只对已展示、完整的同一窗口状态比较；当前可操作元素保持完整；错误、关闭、重置、静默观察清除基线；旧 token 仍被拒绝 | 已实现，待合并与发布 |
| 2 | 原生观察 API：`getAXState`、`getScreenshot`、`getAXStateAndScreenshot` | 明确文字与图片返回值；联合观察只调用一次驱动；截图单独读取清除差分基线；保留新鲜观察约束 | 待实施 |
| 3 | 浏览器 API 参数和返回语义 | 建立逐项契约测试；补齐 `timeoutMs` 别名、操作选项、导航等待；明确 `url()`、`selectOption()` 等语义；未知参数显式报错 | 待实施 |
| 4 | 浏览器观察：增强快照、`elementInfo` | 支持元素引用、可访问 iframe 内容、坐标到定位器提示；跨域 iframe、shadow DOM、截断、导航失效均有真实 Chrome 测试；省略敏感输入值 | 待实施 |
| 5 | 只读 `evaluate` / `evaluateAll` | 独立执行环境读取有界 DOM 快照；不能接触页面网络、存储或修改 DOM；测试超时、资源限制、敏感字段、frame 隔离与无副作用 | 待实施 |
| 6 | 文件上传、下载、文件选择器 | `setInputFiles`、`expectDownload`、`expectFileChooser`；文件读取服从 DSH sandbox，下载限于任务目录；动作只执行一次；验证大小限制、取消、清理、iframe 和弹出页 | 待实施 |
| 7 | 生命周期与综合验收 | 评估 reset 保留页面及重新绑定；覆盖多任务隔离、关闭与取消、混合原生/浏览器任务；文档与打包产物一致，发布可复现 alpha | 待实施 |

浏览器提供方扩展（已有 Chrome 接管、内嵌浏览器、浏览器 PiP）另行评估宿主能力，不作为以上 API 实现的隐含前提。完整 Playwright Page、任意 CDP、页面任意脚本执行不属于目标。

## 第一阶段设计

- 差分只改变模型看到的自动文字输出；`app.getState()` 继续返回本次完整结构化状态。`{disableDiffing:true}` 请求完整文字。
- 基线按当前 REPL 和原生 target 隔离，记录上一份实际展示的完整状态。非完整、降级、过大或缺乏完整性标记的观察不建立基线。
- 仅压缩明确没有 AX actions 且展示属性相同的行；保留当前索引和 token。发生插入、删除或重排时按当前位置比较，差分不是持久元素身份。
- 可操作行始终完整显示；每次仍向驱动获取新状态，操作权限由 Host 使用新 token 校验。差分不延长 token 寿命。
- 差分不比完整输出短时回退；完整输出超过展示上限时明确标注截断，程序返回值不受影响。
- 回归覆盖新增/修改/移除/重排、token 更新、目标隔离、静默观察、完整输出、错误恢复及 REPL 持续状态。

## 推进记录

- 2026-10-10：建立范围与分阶段验收；开始第一阶段。已有核心 Playwright locator/action 封装及真实 Chrome 集成测试；增强快照、求值及文件传输尚未实现。
- 2026-10-10：第一阶段本地类型检查、构建、51 项测试及真实 Chrome 集成测试通过。新增真实 REPL 子进程 → NativeSurface 测试，使用模拟原生驱动验证完整返回值、差分输出和旧 token 拒绝；尚未在 Desktop 中安装验收。本阶段不新增原生截图专用 API，相关基线清理在第二阶段实现。