dsh-win-computer-use
> Windows-first Computer Use for DeepSeek Harness。
> 深度 Win32 / WinUI / UIA 工程 + 零审批投递升级：
> 后台优先，失败自动前台，结束恢复原焦点。
> 默认 2 个稳定入口，22 个桌面工具按需调度。
> 源自 988hj7tczd-oss/dsh-computer-use（MIT）@07477f4，现为独立维护的个人项目；2026-11-10 更名为 dsh-win-computer-use，安全姿态与投递管线均按自有路线演进。出处与借鉴见文末「出处与致谢」。
这是什么
给 DeepSeek Harness 加一套 Windows 深度实测、可观察、可验证的 Computer Use 桌面操作层：默认 2 个稳定入口（computer_do + screen_observe）/ 完整 22 个工具经 dispatcher 路由，底层通过 cua-driver 驱动本地桌面（独立虚拟光标，不抢真实鼠标）。Windows 深度实测——前台锁、XAML/WinUI 输入、观测几何这些硬墙都在本机踩过并解决。
三个核心机制：
- 先观察，再操作：动作必须基于新鲜观察快照（
element编号或窗口本地截图像素坐标），过期即拒绝； - 所见即所点：观察输出与动作坐标共用同一"窗口本地截图像素"空间，零换算；
- 自动升级投递：后台优先，后台不可用自动升级前台、绕前台锁，完成后恢复用户原焦点。
设计立场：无感自治
不追求极致安全，方向相反。在"后台优先 + 升级链 + 恢复原前台 + 审计注记"底座上执行四原则：
| 原则 | 行为 |
|---|---|
| 易用无感 | 动作零审批、零打断；归因靠全量投递注记 + harness 会话日志 |
| 自动提权 | 投递链自动升级（恢复原前台）；观测失败自动降级桌面级采集；观测/投递能力默认全开，无模式开关 |
| 极危敏感警告 | extremePatterns 命中元素标签 → 结果附警告注记，不阻断；默认空 = 零差异 |
| 仅作基本兜底 | 凭据硬保护（密码框拒绝自动输入，唯一硬拒绝）、快照 TTL、无快照拒绝、allowedApps 白名单（默认关） |
能力一览
| 能力 | 说明 |
|---|---|
| 屏幕观察 | 目标窗口 AX/UIA 编号树 + 坐标；native 主模型直读截图；vision 观察者描述 |
| 区域放大 | screen_zoom 裁剪窗口局部为 ≤500px JPEG 直读 |
| 独立虚拟光标 | 点击/拖拽展示操作过程，不抢用户真实鼠标 |
| 文本与快捷键 | computer_type 走 UIA ValuePattern 后台写入（XAML/WinUI 必需）；组合键走 hotkey 通道（UIA AcceleratorKey 匹配） |
| 三级投递链 | background → foreground → bring_to_front 绕锁，完成后恢复原前台 |
| 观测几何根治 | 1:1 窗口截图（max_image_dimension 配置化），点击零标定命中 |
| 应用管理 | 列出运行中应用、后台启动、按需前置 |
| 确定性验证 | computer_verify / computer_wait_for：UIA 谓词断言与轮询（unknown 永不视为成功） |
| 剪贴板与菜单 | 剪贴板读写（粘贴流）；菜单路径直调（fail-closed） |
| 强杀开关 | computer_stop 锁存全部桌面操作，computer_resume 唯一解锁 |
| 子 agent 委派 | computer_task：多步/噪声大的操作交给一次性子 agent，必须以 {ok,summary,evidence} 收尾，主上下文只吃一条 ≤400 字符回执。工具范围能否限制取决于宿主能力：能限制时只给桌面工具；宿主拒绝该约束时插件照常委派并在回执里如实写明（含拒绝原因）——见〈委派的能力边界〉 |
| 上下文成本控制 | 重复观察降噪（未变窗口回极简回执，实测大树 1586→250 字符）、成本阶梯写入工具描述（ax < zoom < native）、紧凑动作回执（verboseReceipts 排障时才附明细） |
工具面模式（默认 dispatcher）
22 个工具的 schema 常驻会持续占用模型的注意力（不是 token 成本问题）。默认只暴露 2 个稳定入口，其余工具经 computer_do 路由；不再使用 enter/exit 动态注册（旧的 dynamic 模式已废弃并移除）。
| 模式 | 直接可见 | 其它工具怎么调用 |
|---|---|---|
dispatcher（默认） |
computer_do + screen_observe |
computer_do({action:'call', tool, args}) |
hybrid |
computer_do + screen_observe + computer_click/type/key/scroll/verify |
长尾工具经 dispatcher |
computer_do({action:'catalog'}) 返回隐藏工具的紧凑签名，action:'call' 路由到隐藏实现（隐藏工具不注册、不可直接调用）。隐藏工具仍走原来的 guard/快照/stop 锁存/参数校验/回执；screen_zoom 的图片也会经 dispatcher 透传。
- id: dsh-win-computer-use
config:
surfaceMode: dispatcher # dispatcher（默认）| hybrid
真实渠道实测（2026-11-09，opencode / deepseek-v4.1-flash）：dispatcher 的稳定 tools 在重复请求命中 99.5%，首次 tool_call 后 92.1%，第二次后 85.4%；而旧的动态 enter / lazy search 每次 tools 变化的首击只有 0%–18%。因此：
- cache 优先：保持
dispatcher，或选hybrid（5 个热工具 + 长尾 dispatcher）； catalog的签名是文本，复杂工具（如computer_verify的 expect JSON、computer_task）请先 catalog 看签名；必要时在 system prompt 里给一个示例；hybrid的实验性在于“热工具数量/选择”可能随任务调整；dispatcher是默认稳定面。
工具清单（完整 22 个 = 2 个常驻 + 20 个经 dispatcher）
在默认 dispatcher 模式下，下表中除 screen_observe/computer_do 外的工具都通过 computer_do({action:'call', tool, args}) 调用；hybrid 下 click/type/key/scroll/verify 可直接调用。
| 工具 | 作用 | 主要参数 |
|---|---|---|
screen_observe |
观察窗口：编号树 / 截图直读 / 视觉描述（未变时回极简回执，force=true 强制全量） |
window, mode, query, maxElements, force |
screen_zoom |
区域放大细看 / 树空目标定位原语 | window_id, pid, x1, y1, x2, y2 |
computer_click |
点击元素或坐标 | element 或 x,y；可选 count、foreground |
computer_double_click |
双击 | 同上 |
computer_right_click |
右键 | 同上 |
computer_type |
输入文本（指定 element 时可走 UIA ValuePattern；未指定则输入到快照窗口当前焦点） | text, element, foreground |
computer_set_value |
直接设值（UIA ValuePattern；文本框/滑块/下拉优先，Web/自绘控件可能忽略） | element, value |
computer_key |
按键 / 快捷键（组合键走 hotkey 通道；绑定快照窗口） | key, foreground |
computer_scroll |
滚动 | direction, amount, element, foreground |
computer_drag |
截图坐标拖拽 | from_x/from_y → to_x/to_y, duration_ms, foreground |
computer_wait |
等待加载/动画 | ms（1-60000） |
computer_verify |
确定性验证：1-8 条谓词求值（satisfied/unsatisfied/unknown） | pid, window_id, expect |
computer_wait_for |
谓词轮询等待：满足即返回，超时结构化失败 | expect, timeoutMs, pollMs |
computer_clipboard |
剪贴板读写（write+ctrl+v = 可靠粘贴流） | action, text |
computer_menu |
菜单路径直调（fail-closed，不回退像素） | pid, window_id, path |
computer_hover |
悬停（实验性：覆盖层 / real=真实指针） | pid, window_id, x, y, real |
computer_stop |
强杀开关：结束会话并锁存全部桌面操作 | 无 |
computer_resume |
解锁 stop 并预热会话（唯一解锁路径） | 无 |
app_list |
列出运行中的应用（紧凑：一行一应用，超 20 条截断） | 无 |
app_launch |
启动应用（后台，可选前置）。注意：驱动需管理员权限，故启动的应用继承高完整性级别、非提权客户端无法关闭它 | name / bundle_id, bring_to_front |
computer_task |
委派：把一段桌面操作交给一次性子 agent（以 {ok,summary,evidence} 收尾），主上下文只吃一条 ≤400 字符回执；宿主无子 agent 能力时返回委派配方。工具范围限制见〈委派的能力边界〉 | goal, success_criteria, constraints, timeout_min, model, model_effort |
快速开始
前置：cua-driver
安装 trycua/cua 的驱动（macOS/Linux curl 安装器，Windows PowerShell 安装器），或手动指定：
export CUA_DRIVER_BIN=/path/to/cua-driver
缺失时所有工具返回结构化错误与自救指引，不静默。
安装插件
git clone https://github.com/orangeofcarl0-sys/dsh-win-computer-use.git
cd dsh-win-computer-use
./install.sh --dry-run # 预演，不写配置
./install.sh # 链接进 profile + 注册 bundle patch
Windows/Linux 先 export DSH_HOME=/path/to/dsh-home。或按 docs/store-evidence.md 手动安装。装完重启宿主，用 app_list / screen_observe 验证。
观察模式
| 模式 | 原理 | 成本 | 适用 |
|---|---|---|---|
ax（默认） |
AX/UIA 树 → 编号 + 坐标 | 零视觉 token | 原生应用 |
native |
截图经 attachments 持久化为图片块，主模型直读 | 图片 token | Canvas/游戏/Electron、树为空 |
vision |
ctx.llm 视觉观察者结构化描述（默认 deepseek-v4-flash-vision-exp，可回退 GLM） |
一次视觉调用 | 主模型不支持图片输入时 |
自动降级链：AX 树为空 → native（模型支持图）→ vision（有观察模型）→ ax。窗口级观测被权限/引擎拒绝时自动降级桌面级采集（视觉仅读，坐标系变为桌面像素，不可直接用于动作坐标），结果标注 visualOnly 并附 driverAccess 权限面探测。
坐标语义
所有坐标 = 窗口本地截图像素（v0.2.0 起）：
- 原点 = 目标窗口左上角；
screen_observe的@(x,y)与computer_click(x=,y=)同一空间； - 不乘 2、不加窗口偏移；
screen_zoom返回局部图，但点击坐标仍指整窗截图空间。
树空目标的定位环（zoom 定位原语）
主模型的整窗裸定位误差大（实测 median>300px，且为先验驱动的布局重建而非像素测量），像素路径一律走定位环：
screen_observe（AX 树失败/树空）
→ screen_zoom(x1,y1,x2,y2) # 取目标主导的小裁剪
→ 本图内语义确认目标 + 读出图内坐标
→ 图内坐标 × crop.scale + crop.x/y = 整窗截图像素
→ computer_click(x=,y=)（必要时 AX/视觉复核命中）
screen_zoom 结果附 crop 元数据（原点/尺寸/换算比例）并给出换算公式。裁剪务必让目标占画面主导——实测目标主导小裁剪误差 13-80px。
委派的能力边界（诚实说明）
computer_task 想给子 agent 施加三条约束：限定工具范围（只用桌面工具）、要求结构化输出、禁止再派生。它们是独立的宿主能力，能否生效取决于宿主提供方：
- 三者都支持 → 子 agent 只拿到桌面工具，结构化结果经宿主校验；
- 宿主拒绝工具范围约束时（实测形态：
tools.restrict() names unknown global tools——默认 dispatcher 下桌面工具不注册为全局工具，宿主对toolFilter的名字校验只认全局层）→ 插件丢掉这一条、保住结构化输出，并在回执里写明"子 agent 拥有与父会话同级的能力"及拒绝原因； - 宿主连结构化也不支持 → 再降一级，回执标注"结果未结构化"。
也就是说：在宿主不支持工具范围约束的部署上，子 agent 与父会话能力同级（可能具备 shell/文件工具）。插件不会把这条约束当作已生效来上报；需要严格限制时，请用宿主自己的子 agent 机制并在其配置里限定工具。
前后台投递
两条通道：后台（UIA Invoke / PostMessage，不抢焦点，后台/最小化窗口可操作）与前台（短暂焦点交换 + SendInput，完成后恢复原前台）。会静默丢弃后台事件的目标（Chromium/Electron 内容、GTK、VCL 等），驱动返回结构化 background_unavailable 而非假装成功。
deliveryMode |
行为 |
|---|---|
auto（默认） |
后台优先；background_unavailable → 自动前台重试；前台锁拦截 → bring_to_front（AttachThreadInput）绕锁重试，完成后恢复原前台窗口；全过程注记进结果 |
background |
全程后台；不可用时返回结构化错误 + foreground=true 升级指引 |
foreground |
始终前台 |
单次动作可用 foreground: true 覆盖。Windows 前台锁（ForegroundLockTimeout）、UIPI、XAML CoreInput 不吃 PostMessage 这些坑均已实测绕过——详见提交历史与 WINDOWS_TEST.md。
所有输入/动作类工具（computer_click / computer_double_click / computer_right_click / computer_type / computer_key / computer_scroll / computer_drag / computer_set_value）都要求先 screen_observe：type/key 绑定快照窗口的 pid + window_id，不再支持无观察的 scope:'desktop' 盲发；type 未指定 element 时输入到该窗口当前焦点，密码保护无法预判焦点控件，回执会附注记。
配置
- id: dsh-win-computer-use
config:
ttlMs: 60000
maxElements: 120
observeDedup: summary
surfaceMode: dispatcher
verboseReceipts: false
taskTimeoutMin: 5
maxTaskCalls: 3
supersession: note
allowedApps: []
cursorTheme: com.dsh.computeruse.rainbow
nativeImage: auto
visionProvider: deepseek-official
visionModel: deepseek-v4-flash-vision-exp
passwordScan: auto
extremePatterns: []
deliveryMode: auto
| 配置项 | 默认 | 说明 |
|---|---|---|
ttlMs |
60000 |
观察快照有效期（毫秒） |
maxElements |
120 |
单次观察最多返回的编号元素数（实测常见任务 30-70 个） |
observeDedup |
summary |
重复观察降噪：同一未变窗口回极简回执——summary（含编号摘要）/ brief（单行）/ off（每次全量）；需要完整清单时传 force=true |
surfaceMode |
dispatcher |
工具面模式：dispatcher（2 个常驻；其余经 dispatcher）/ hybrid（2 + 5 个热工具；长尾经 dispatcher）。tools 列表稳定以保 prompt cache |
verboseReceipts |
false |
动作回执详略：false = 只回一行要点；true = 附原始 JSON 明细（排障用） |
taskTimeoutMin |
5 |
computer_task 默认超时分钟数（可用 timeout_min 覆盖，1-60）。实测设太长会在子 agent 无法收敛时纯浪费 |
maxTaskCalls |
3 |
每会话允许的 computer_task 次数上限（防委托风暴与反复超时重复劳动） |
supersession |
note |
同快照连击语义：note 附一致性注记 / enforce 第二次动作直接拒绝（每动作一观察）/ off 全关 |
passwordScan |
auto |
Windows 结构性密码扫描（UIA sidecar 读 IsPassword ∨ ES_PASSWORD 结构位）；off = 零 spawn，凭据保护退回启发式。macOS/Linux 不适用 |
allowedApps |
[] |
作用域白名单；空 = 不限制 |
cursorTheme |
com.dsh.computeruse.rainbow |
虚拟光标主题；空 = 引擎默认 |
nativeImage |
auto |
auto 超限额自动降级 / full 原图 / compact 始终小图 |
visionProvider / visionModel |
deepseek-official / deepseek-v4-flash-vision-exp |
vision 观察者路由 |
extremePatterns |
[] |
极危清单（正则源数组）：命中元素标签 → 警告注记，不阻断 |
deliveryMode |
auto |
投递策略，见上节 |
平台支持
| 平台 | 状态 | 说明 |
|---|---|---|
| Windows | ✅ 深度实测 | 三级链 / XAML hotkey / 1:1 观测均在本机闭环；管理员窗口属系统边界（UIPI） |
| macOS | ✅ 已测试 | 需 Accessibility / Screen Recording 授权 |
| Linux | ✅ 已测试 | 桌面环境与 accessibility 栈影响元素识别 |
故障排查
| 现象 | 常见原因 | 处理 |
|---|---|---|
cua-driver not found |
驱动不在 PATH | 安装驱动或设 CUA_DRIVER_BIN |
| 没有可见窗口 | 图形会话/窗口权限 | 确认目标在运行并重观察 |
| 快照已过期 | 超过 ttlMs |
重新 screen_observe |
| 元素编号点击失败 | 界面已变化 | 重观察取新编号 |
| AX/UIA 树为空 | Canvas/游戏/Electron | 用 native / vision |
| native 被拒 | 主模型无 image 能力 | 换视觉模型或用 vision |
| 动作被守卫拒绝 | 无快照/过期/白名单/凭据保护 | 按拒绝原因处理，守卫拒绝均有明确原因文本 |
| Windows 管理员窗口不可操作 | UIPI 完整性级别更高 | 使用普通用户窗口 |
开发与验证
npm install
npm run check # 语法 + 安装脚本检查
npm test # 十套离线测试、231 个 ✅：
# posture（无感自治姿态/凭据硬保护/快照新鲜度）
# tools · delivery-chain（直接执行真实 cuaDeliver）
# schema.conformance 22 工具 × 44 场景（按声明 schema 严格校验每种返回形态，
# 含结构化拒绝/驱动错误/观测降级——dsh 严格输出校验类 bug 的守门测试）
# observe.dedup（含 value/enabled/selected/actions 变化）
# task.tool · config.plumbing
# action-bounds（P0 无快照/窗口绑定/suspected_noop）
# dispatcher.test（surfaceMode dispatcher/hybrid：隐藏路由/guard/stop/图片透传/固定工具面）
# package-manifest（peer/dev/兼容下限/发布清单）
node verify-runtime.mjs # 运行时验证（dispatcher 默认 16/16；需真实 harness + cua-driver）
node tests/live-action.e2e.mjs 3 # 真桌面动作闭环 + 稳定性循环（真记事本 3 轮）
node evals/verify-oracles.mjs # S4 评测 oracle 双向验证（setup 必 ok → 空跑必失败 → simulate 必过）
License
MIT。个人项目，与 DeepSeek 无关。
English (brief)
Windows-first Computer Use plugin for the DeepSeek Harness: 2 stable tools by default (computer_do dispatcher + observe), with all 22 tools reachable through the dispatcher, driving local desktops through cua-driver with an isolated virtual cursor. Deep Win32/WinUI/UIA engineering; Windows-deep-tested.
surfaceMode (default dispatcher; hybrid = 2 + 5 hot native tools, long tail routed) keeps the visible tool list stable so tool-layer changes do not break prompt caching. The old dynamic enter/exit surface has been removed.
Stance — zero-friction autonomy: no approval prompts, no interruptions; capabilities always on (auto desktop-level observation fallback, three-tier delivery escalation that restores the previous foreground). The only hard refusal is automated typing into password fields. extremePatterns adds non-blocking warning notes.
Loop: screen_observe (AX/UIA index tree, native screenshot read, or vision observer) → act via element index or window-local screenshot pixels → auto-escalated delivery → observe again to verify.
Install: install cua-driver, then git clone https://github.com/orangeofcarl0-sys/dsh-win-computer-use.git && ./install.sh (set DSH_HOME on Windows/Linux). Config defaults: ttlMs: 60000, deliveryMode: auto, extremePatterns: [] — see the Chinese section above for the full table.
Derived from 988hj7tczd-oss/dsh-computer-use (MIT); see Acknowledgements.
出处与致谢
原仓库（代码基座）
- 988hj7tczd-oss/dsh-computer-use @
07477f4（MIT）——本项目的直接前身。按 MIT 派生后独立演进：安全姿态、投递管线、观测几何均与本仓库自有路线重写，与上游互不合并；原始问题反馈（#7 resolveBin、#8 hotkey 通道）已提回上游跟踪。
运行时底座
- trycua/cua（MIT）——cua-driver 是本插件消费的跨平台驱动。"后台优先、升级梯子、foreground 是对观测失败的响应"的投递哲学与之同源；Windows 侧的三级链、
bring_to_front恢复语义、XAML hotkey 通道为本仓库在本机实测的自有实现。
设计思想借鉴（方法与验收，不含代码）
- Microsoft UFO² —— UIA∪视觉混合控制检测、GUI-API 混合执行的路线图输入；
- Agent-S（Simular，ICLR 2025）—— ACI（辅助功能树 + set-of-marks）的 grounding 兜底思路，列入后续 roadmap；
- OSWorld / Windows Agent Arena —— 执行式 oracle 回归验证方法论；
- Anthropic / OpenAI CUA / Gemini computer use —— 截图循环与原子动作空间的参照系；
- ZCode 官方 computer-use 插件 —— action receipt / 观察版本化契约的重放安全设计参照。
除原仓库派生部分外，本项目不含上述项目的代码；借鉴限于思想与验收方法层面。
