Vision-Pilot：让模型「看」并「等」屏幕变化的 DSH 插件

前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的理念，把扩展能力交给社区。在开发 Computer Use 类任务时，一个常见问题是：模型能看到屏幕，却很难「等」界面变化，只能反复盲猜重试。ccr-wer/dsh-copilot-vision（Vision-Pilot）是一个面向 DSH 的 Computer Use 增强插件，把视觉差分、位置编码与人机共驾授权组合在一起，让模型既能看，也能等，还能精准操作。

插件定位¶

名称：Vision-Pilot（dsh-copilot-vision）
维护者：ccr-wer
分类：工作流
定位：Computer Use 增强插件，纯 JS 实现，支持视觉差分、网格位置编码、长程任务闭环与人机共驾授权。

核心能力¶

双轨执行¶

本地轨道通过 robot-ts 直接操作 Windows 屏幕（捕获、鼠标注入、键盘注入、底层钩子）；src/vp-ssh-core.js 预留了远程轨道接口，当前发版只启用本地轨道。

动态视觉感知¶

vp_screenshot_diff：用 pixelmatch 逐像素比对历史截图，合并 4 邻域连通块，丢弃小于 100 像素的噪声，把「哪里变了」交给模型。
vp_wait_change：每 100ms 在内存里截屏比对，变化出现时才落一张正式截图，零落盘；换显示器或改缩放后会报错，不重采样硬算。
网格放大图不再固定 4 倍：按区域面积自适应倍率（≤50,000 物理像素 4x、≤200,000 2x、更大 1x 只画网格），放大后单边 ≤2,000 像素，避免细长条被放大成畸形长图。每个区域以 gridScale 字段标明实际倍数。

位置编码注入¶

每个差分区域附一张 gridPath 放大图，按区域面积与单边长度自适应倍率（4x / 2x / 1x，放大后单边 ≤2,000 像素）的最近邻放大，每 20 物理像素一条半透明红线，网格原点是区域左上角。模型只负责数格子、报百分比，vp_click_relative 完成精确换算。

人机共驾安全¶

授权采用三态：unauthorized / pending-persistent / persistent。铁律是「授权只由人的动作进入和撤销，不由时钟改变」——没有到期时间，持续授权等再久都不失效。

进入授权：按 Shift+Space 直接进入持续授权；或模型调用 vp_request_auth(mode='persistent')，在宿主问答卡片上确认一次。
急停：任何时候再按一次 Shift+Space，立即回到 unauthorized。这是物理热键，不经过模型、不依赖宿主 UI。
热键失效即收权（Fail-Closed）：EventTap 启动失败、监听线程退出、心跳（默认每 2 秒）发现钩子不再活跃，都会立刻把状态强制收回 unauthorized 并写一条 revokeAll 审计。
撤销与注入竞态：每个动作在放行时记下授权代数，真正调用 robot-ts 前再用微任务同步复核一次。人按撤销的瞬间，正在飞的这一下最多落到「已执行的移动」为止，后续注入立即中止。
等待可被打断：vp_wait_change 轮询期间一旦授权被撤销，立刻抛「授权已被撤销，等待中断」。
未授权即拦截：vp_click / vp_click_relative / vp_type / vp_key 在未授权时直接抛错并提示人类开启持续授权。
审计：JSON Lines 记录每次授权迁移，以及每次注入的放行/拒绝（actionAllowed / actionDenied），只记动作与工具名。

语义级记忆压缩（vp_summarize）¶

临时图会跨会话堆积。vp_summarize 让模型在任务周期结束、准备收工或切换任务时主动做一次收尾：

keepShotIds 里的关键截图被移进 archives/ 子目录，索引路径同步更新。
summary 连同本次保留清单追加写入 archive-summary.txt。
当前目录下其余所有临时碎片立即删除，返回各类碎片数量。

保护区：audit.log、shot-index.json、archives/ 永远不会被删除；被清理掉的 shotId 在索引里保留条目。

工具集¶

工具	功能
`vp_screenshot`	截主屏全屏，返回 `shotId`。
`vp_screenshot_diff`	与历史截图逐像素差分，输出差异区域 + 网格放大图。
`vp_wait_change`	高频轮询等待屏幕变化，变化即返回；超时不消耗 shotId。
`vp_click`	按绝对物理坐标点击（需持续授权）。
`vp_click_relative`	在差分区域的网格图内按相对百分比点击（需持续授权）。
`vp_type`	在当前焦点输入一段文本（Unicode 直注，中英文通吃；绝不自动回车；需持续授权）。
`vp_key`	发送一次按键或组合键（enter / tab / esc / ctrl+c）；回车只能由它触发；需持续授权。
`vp_request_auth`	请求人类开启持续授权（仅 `mode='persistent'`），经宿主问答卡片等待确认。
`vp_auth_status`	只读查询授权状态、热键可用性与审计日志路径。
`vp_summarize`	归档关键截图、写入总结，清空其余全部临时碎片。

长程任务工作流（OSA V Loop）¶

这段协议内嵌在全部 10 个工具的 description 里，模型每次调用都会被提醒：

观察 Observe——每步开始前，用截图或差分确认当前屏幕状态。
行动 Act——点击目标（绝对坐标或相对百分比）。
等待 Wait——点击后必须立刻 vp_wait_change。绝对禁止连续两次点击（盲点）。
验证 Verify——结合变化区域与超时判断是否达标；timeout:true 意味着可能失败或卡死，必须重新截图观察、重新规划。

安装与启用¶

从 npm 安装：

DSH_HOME=<DSH_HOME> dsh plugin --profile web add dsh-copilot-vision

从本地 tarball 安装（开发调试）：

npm pack
DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot-vision-1.3.2.tgz

宿主支持 web（问答卡片授权）、headless（无 UI 答者，只能 Shift+Space，需真人在场）、desktop（待审核后内置验证）。

限制与边界¶

输入能力边界：支持键盘输入（vp_type 文本 / vp_key 按键与组合键）；不支持拖拽、滚轮、双击。
输入法干扰：中文输入法会吞掉扫描码注入的字母键；插件对无修饰键的字符键改走 Unicode 直注，但组合串仍可能被 vp_key enter 一起提交。
聊天窗口自干扰：宿主聊天窗口的流式重绘会被当成屏幕变化；等页面加载时，先把聊天窗口移出主屏或最小化。
鼠标移动不可检测：Windows 屏幕捕获不含硬件光标，挪鼠标不产生任何像素变化。
热键无法区分真人与合成按键；真正的护栏在插件之外。
静默摘钩不可观测：Windows 若在消息循环仍在跑的情况下静默卸掉低层钩子，绑定层看不到；心跳无法判定失效。
无热键时的残余风险：EventTap 启动即不可用时，插件不会自动收权，但人仍可通过 vp_request_auth 卡片确认进入 persistent。
索引并发：截图索引整份覆盖写、不做跨进程并发保护，多进程共用 VP_SHOT_DIR 会互相覆盖。
临时目录卫生：超过 3 天的差分/网格切片会在插件启动时被自动清理；模型在收工时调用 vp_summarize 会把关键截图归档。

适用场景与注意¶

适合需要「看、等、操作」闭环的 Computer Use 任务。插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。

小结¶

Vision-Pilot 把视觉差分、网格位置编码与人机共驾授权整合进 DSH 生态，让模型既能「看」屏幕，也能「等」变化，还能「精准」操作。通过持续授权与物理热键急停，将安全与可控性前置。

插件目录页：https://www.skillhub.cn/plugins/ccr-wer/dsh-copilot-vision
GitHub：https://github.com/ccr-wer/dsh-copilot-vision