zzy6-a/vision-use

English | 中文

仓库：vision-use · 包名：dsh-vision

让 DeepSeek Harness 的 Agent 真正看见你的屏幕、并动手操作 Windows 桌面 —— 带 Codex 风格的蓝色操作覆盖层（按 Esc 随时中止）。

---

它能做什么

能力	工具	说明
👁 看	view_screen	截 Windows 全屏 → 直接进入模型视觉通道（不是 OCR，是真·看图）
👁 看	view_image	把任意图片文件送进视觉通道（Linux / Windows 路径都行）
🖱 动	computer_move	光标平滑滑行到 (x,y)
🖱 动	computer_click	左/右/双击，带点击涟漪
⌨️ 动	computer_type	输入文字（默认 VK 真实按键逐键注入，零剪贴板；中文走输入法：computer_key 发拼音 → space/数字上屏）
⌨️ 动	computer_key	组合键（ctrl+t / enter / alt+f4 …）
🎛 控	computer_overlay	启停操作覆盖层（start/stop/status，可设空闲自动关）
📊 控	computer_status	覆盖层状态 / ESC 标志 / 当前模式 / 光标位置

视觉反馈（Codex 风格）

┌───────────────────────────────────────────────┐
│  ╔═════════════════════════════════════════╗  │ ← 蓝色柔光边框（逐像素 Alpha）
│  ║   ● DeepSeek Harness 正在操作  [Esc] 取消 ║  │ ← 顶部状态徽章
│  ║                                         ║  │
│  ║         打字 → 蓝色光环 + 竖线           ║  │
│  ║         点击 → 0.7s 涟漪（钉在点击处）    ║  │
│  ║         移动 → 光环淡入跟随；静置 1s 淡出 ║  │
│  ╚═════════════════════════════════════════╝  │
└───────────────────────────────────────────────┘

• 整套光标（箭头 / I 形 / 手指）都是统一的蓝白渐变风格，且保留 Windows 原生语境切换
• 强制覆盖层：所有 hands 操作（move/click/type/key）都会先强制拉起覆盖层，不存在“静默操作”
• ESC 中止：按下即写取消标志 → 覆盖层退出 → 后续所有动作被拒绝
• 任务级保活：只要本回合 agent 还在工作（思考 / 执行其他工具），覆盖层就不会收；回合结束后约 4 秒收起。覆盖层自身仍有空闲兜底（idle_seconds，默认 30，0 = 关闭兜底）
• 输入框下方的状态胶囊：彩色圆点 + CU 待命/移动/输入/点击 + 「停止」按钮

---

安装

方式一：GitHub Release（推荐）

dsh plugin --profile web add https://github.com/zzy6-a/vision-use/releases/download/v0.2.0/dsh-vision-0.2.0.tgz

方式二：git 源

dsh plugin --profile web add github:zzy6-a/vision-use

装完重启 DSH（client.js 半边需要启动时注册），浏览器刷新后输入框下方会出现状态胶囊。

---

快速开始

对 Agent 说：

看一下我的屏幕

帮我在必应搜索 DeepSeek 官网并打开

打开记事本打一段字

Agent 会自动：起覆盖层 → view_screen 看 → computer_* 动手 → 再看验证。你随时可以按 Esc 喊停。

---

系统要求

项	要求
宿主（自动识别）	Windows 原生 或 Windows + WSL2；插件自动识别 DSH 所在环境并选择对应路径/子进程方案
WSL 时的互操作	WSL interop 开启（/proc/sys/fs/binfmt_misc/WSLInterop = enabled）；插件自动走 \\wsl.localhost\<distro> UNC 路径
Windows 侧	PowerShell 5.1（系统自带）+ .NET Framework（System.Drawing/WinForms）
DSH	>= 0.1.5-rc.1
Node	插件本身零运行时依赖（纯 ESM + 子进程调 PowerShell）
Linux / macOS	不支持桌面控制；view_screen 与 hands 工具会明确报错，view_image 仍可用

---

架构

vision-use/
├── lib/index.js        host 半边：8 个工具 + 2 条 API 路由 + systemPrompt 能力宣告
├── lib/client.js       browser 半边：composer-dock 状态胶囊
├── cordis.patch.yml    bundle 层：把插件行插入 profile 树
├── dsh.plugin.json     插件清单（dsh-market / 插件管理 UI 用）
└── scripts/            Windows 侧工具链（自包含，随包发布）
    ├── cu.ps1          鼠标/键盘执行器 + ESC 守卫
    ├── overlay-v2.ps1  覆盖层：边框/徽章/光环/涟漪 + C# 60fps 动画引擎
    ├── wocr.ps1        Windows 原生 OCR（零 API 成本兜底，可选）
    └── TOOLKIT.md      工具链详细文档 + 10 条实战纪律

环境自动识别

插件启动时检测 process.platform、WSL_DISTRO_NAME / WSL_INTEROP 与 /proc/version：

检测结果	行为
Windows 原生	直接调 powershell.exe；flag/state/heartbeat 写 %TEMP%
WSL + Windows	调 powershell.exe interop；flag/state/heartbeat 写 /tmp，并自动转成 \\wsl.localhost\<distro>\tmp 供 PowerShell 读写
Linux / macOS	桌面工具给出明确不支持错误；view_image 不受影响

子进程统一通过 DSH_VISION_FLAG_DIR 环境变量获知跨端 flag 目录（WSL 下会自动加入 WSLENV 透传）。

视觉原理：图片以 content: [{type:'image', attachment}] 形式返回，宿主 collectImageRefs() 递归收集后随下一次请求发给模型 —— 这是 DSH 官方的图片通道，因此截图会正常计入模型视觉 token（DeepSeek 官方路由对单图约 369 tokens，上限 384）。

动画原理：覆盖层用 UpdateLayeredWindow 逐像素 Alpha 实现真正的柔光；热路径全部在编译好的 C# 里跑（PowerShell 只敲节拍），单核占用约 8.8%。

---

配置

参数	默认	说明
computer_overlay start idle_seconds	30	覆盖层自身的空闲兜底秒数；任务进行中插件会持续续心跳，不会在思考时消失（0 = 关闭兜底）
-MaxSeconds	0	覆盖层最长存活时间（0 = 不限）
-NoCursorChange	关	不安装蓝色光标套装（保留系统默认光标）

隐私相关：截屏会作为图片附件进入当前会话上下文（与手动粘贴图片等价）；如不想让截图进入模型，可用本仓库的 scripts/wocr.ps1 走本地 OCR（零 API 消耗，但只能拿文字）。

---

计费与隐私

• 插件本身零网络请求：不调用任何 API，只把截图存进本地附件库并把图片块交给宿主
• 图片最终发给当前会话选中的模型路由（DSH 的模型适配器负责发请求）
• 完全跟随你选择的模型：插件不选路由、不改路由，截图始终随会话发给当前模型选择器里选中的模型 （选 opencode-go 就走 opencode-go，选官方就走官方）
• 识图能力检查：若选中的模型未声明图片输入能力，view_screen / view_image 会明确报错并提示切换模型
• 走官方路由时单图视觉计费约 369 tokens（DSH 上限 384）；走自建/订阅路由则按该路由口径
• 不想让截图进入模型时，可用 scripts/wocr.ps1（Windows 本地 OCR，零 API 成本，但只能拿文字）

已知限制

• Chromium 忽略 KEYEVENTF_UNICODE 注入：往 Edge/Chrome/微信打字用 typevk（真实 VK 按键，跨应用通用）
• 中文/非 ASCII 走输入法：computer_key 依次发拼音字母（如 n,i,h,a,o）→ computer_key space（或数字键选候选）上屏；computer_type 的默认路径会明确拒绝非 ASCII 而不是偷偷回退剪贴板
• 剪贴板模式默认关闭：仅在显式 method: 'clipboard' 时启用（注意：它会覆盖用户剪贴板内容）
• WinUI（记事本等）不认注入的 Ctrl 组合键：computer_key 对这类应用可能无效
• 自绘 UI 的 UIA 坐标不可信（Edge 标签栏、Win11 记事本标签页会返回 ∞ 或错位）：请先 view_screen 肉眼定位再点
• 带自绘光标的软件（游戏、部分 Electron 应用）无法被系统级光标替换覆盖
• Linux / macOS 宿主：当前只支持 Windows 原生与 WSL + Windows；其他系统下 view_image 可用，桌面工具会明确报错

---

相关项目

• dsh-upgrade-guard —— DSH 升级兼容性守卫（同作者的配套插件）

Contributors / 致谢

• zzy6-a — 作者
• DeepSeek V4.1 — 架构设计、实现、测试与发布流程

许可证

MIT © 2026 zzy6-a

---

v0.3.0 · UIA 定位能力（2026-10-27）

这一版补的是**「不用算坐标也能点」**。灵感来自生态里几个成熟实现，具体借鉴点：

借鉴来源	借鉴的东西	落到哪里
Yu-tao-Li/dsh-computer-use-win	用 UI Automation 控件树定位而不是纯坐标；Electron/Chromium 需要先唤醒无障碍层	uia_tree / uia_find + Wake-Uia（WM_GETOBJECT）
STARDUSTLC666/deepseek-computer-use	操作后要求重新观察；会话级授权与审计	uia_click 的前后指纹对比 + ~/.dsh/vision/audit-*.jsonl
sxwsc667/dsh-use-computer	「坐标不进对话」：只回以目标为中心的近景图	uia_locate
rayadesune/DSH-computer-use	截图带坐标网格标尺；干跑模式	view_screen 的 grid / marker_x / marker_y；-DryRun
原生 Win32	PrintWindow(PW_RENDERFULLCONTENT) 截被遮挡窗口	view_screen / uia_locate 的 hwnd 参数

新工具

工具	作用	是否需要鼠标
uia_windows	列顶层窗口：标题 / pid / class / rect / center / 前台标记	否
uia_tree	一个窗口的控件树：类型 / 名称 / AutomationId / 矩形 / pattern 列表	否
uia_find	按名字模糊找控件（也匹配 AutomationId / ClassName），返回候选清单	否
uia_locate	找到控件 → 回一张以它为中心的近景图，不带坐标	否
uia_click	按名字点：优先 invoke / toggle / select / expand pattern，退化才用坐标	否（pattern 命中时）

uia_click 的回执示例：

clicked: Button "加粗(Ctrl+B)" @450,112 via toggle-pattern (no mouse movement)
toggle state now: On
ui changed: NO  fingerprint 42D94E5ECD7F -> 42D94E5ECD7F
window now: "无标题 - Notepad"  focused: Button "更多选项"

view_screen 增强

view_screen({ hwnd: 1641304, region: "400,60,700,320", grid: 100, marker_x: 450, marker_y: 112 })

• hwnd：走 PrintWindow，窗口被遮挡也能截到真实内容（实测 Win11 + Chromium 156 有效）
• region：只截一块，越界自动夹到桌面边界
• grid：画坐标标尺，左上/左侧标注全局坐标
• marker_x/y：在目标点画红十字，用来确认「这是不是我要点的那个」

已知边界

• Chromium / Electron 自绘界面：UIA 树很多时候只有几个 Chrome_RenderWidgetHostHWND 节点。已加 WM_GETOBJECT 唤醒，但应用自己不开 accessibility 就拿不到控件 —— 这类目标退回 view_screen + 坐标。
• PrintWindow 黑图：部分应用（老式 OpenGL / 某类游戏）不支持，此时 view_screen 自动退回屏幕捕获。
• 坐标点击兜底会移动鼠标，uia_click 的回执里会写明 via mouse-click，据此区分。

审计日志

每次 uia_click / uia_locate / view_screen 追加一行到 ~/.dsh/vision/audit-YYYY-MM-DD.jsonl：

{"ts":1793101196129,"tool":"uia_click","name":"加粗","how":"toggle-pattern","matched":"加粗(Ctrl+B)","changed":true,"fpBefore":"42D94E5ECD7F","fpAfter":"763BB639F94C"}

开发提醒

改了这个插件的 lib/index.js 之后，不要用 dev_reload_package 热重载 —— 实测两次都把 DSH 主进程带崩（端口从 13493 → 18168 → 57914）。正确做法：

# 免重启：先卸载再注入
dev_uninject_plugin  match=dsh-vision
dev_inject_plugin    dir=C:\Users\19827\.dsh\plugins\dsh-vision
# 或者干脆重启 DSH（插件已在 profile bundles 里，重启即按磁盘加载）