1azybug/dsh-real-time-computer-use

dsh-computer-use

Windows 上用于 DeepSeek Harness 的 Computer Use：智能体可以像人一样看到 Windows 桌面并操作它——
全屏捕获、按时间戳回看最近约 20 分钟内任意一帧，以及鼠标/键盘注入。

架构

两半通过 stdio 通信，每行一个 JSON 请求：

| 一半 | 位置 | 作用 |
|---|---|---|
| 插件（lib/index.js） | WSL，位于 DSH 宿主进程内 | 注册模型可见的工具，持有辅助进程，将帧交给模型 |
| 辅助程序（helper/CuHelper.exe） | Windows | 桌面捕获（DXGI，GDI 回退）、H.264 分段环形缓冲区、键盘/鼠标注入、窗口枚举 |

插件启动辅助程序一次并使其常驻（每帧都新建进程会导致每次都要付出数十毫秒的
GDI/DXGI 初始化开销）。帧文件落在 Windows 临时目录中，并通过
/mnt//... 读回。

要求

- DSH 运行在 WSL 中；Windows 辅助程序通过 WSL 互操作启动。纯 Windows 的 DSH 安装
按现有写法无法工作，因为 Windows 路径被映射为 /mnt//...。
- 带有 .NET Framework 4 的 Windows（所有受支持的 Windows 上都存在）。无需 SDK、无需 ffmpeg、无需第三方二进制文件。
- 屏幕分辨率决定分块几何：分块大小经过调整以适配 harness 图像预算，因此 2560×1440
桌面会得到 2×3 个 1280×480 的分块（每块 614,400 像素，按原始比例交付）。

安装

1. 将仓库克隆到某个永久位置，然后将其链接到 profile 中
git clone https://github.com/1azybug/dsh-real-time-computer-use.git
pnpm dsh plugin --profile web add link:"$PWD/dsh-real-time-computer-use"
2. 重启 dsh web —— 宿主层插件仅在启动时读取

将操作规范安装为技能（该包附带英文 SKILL.md；不会自动为你安装任何内容）：

cp -r skills/computer-use ~/.dsh/skills/      # 或 $DSH_HOME/skills/

工具

捕获与检查：screen_grid（一次捕获 → 缩略图 + 1:1 分块，可选 atSeconds 以从
缓冲区获取某一帧）、screen_frames（从录制缓冲区中拉取一个时间范围；每张图像都带有其捕获时间）、
screen_watch（连续捕获的启动/停止/统计）、screen_windows（某点下的窗口、前台
窗口，或完整枚举）、cursor_state。

操作：mouse_move_to、mouse_move_by、click、mouse_button、drag、scroll、type_text、press_key、
key_state、hotkey、wait。

可选工具除非在配置中启用，否则保持未注册状态：wait_for_change / act_when（triggerTools）、
screen_observe / region_observe（singleImageTools）、screen_diff（diffTool）。

配置

每个可调项都在 cordis.patch.yml 中，并且随附的默认值并非中性基线：它们是
某个 GUI 评估环境所使用的配置。开箱即用时你会得到 16 个工具的界面；切换这四个
可选的组会将其扩展到 21 个工具，并重新启用普通的图像读取。

把这四个默认值理解为对四个问题的回答，而不是随意的标志：

| 开关 | 默认值 | 使用默认值时 | 开启后会增加 |
|---|---|---|---|
| triggerTools | false | 没有任何东西在监视屏幕以等待某个条件 | wait_for_change、act_when —— 轮询某个区域直到它发生变化，然后执行操作 |
| singleImageTools | false | 屏幕读取只会以同帧缩略图 + 瓦片形式到达 | screen_observe、region_observe —— 返回单张图像 |
| denyReadImage | true | 工具守卫会拒绝每一次 read_image 调用——无论是否带 region，对所有会话都是如此，而不仅仅是屏幕截图 | 普通图像读取重新可用 |
| diffTool | false | 没有帧差分 | screen_diff —— 报告哪些网格单元发生了变化 |

为什么采用这些默认值：在 2560×1440 的桌面上，单张全屏图像要么被缩小到无法辨认（一个 46 px 的控件变成 19 px），要么只覆盖一个角落，因此该插件统一采用一种全视图形式——screen_grid，将一次捕获转换为同帧缩略图加 1:1 瓦片。让 read_image 重新可用会为任何图像恢复单图像路径，而不仅仅是屏幕截图。triggerTools 条目是一项评估约束（监视视觉条件然后执行操作在该设置中算作作弊），而不是技术限制。文件中的注释记录了每一项决定。

其余键是普通的捕获设置：

| 键 | 默认值 | 含义 |
|---|---|---|
| backend | dxgi | 捕获后端：dxgi（GPU 复制，约 0.42 ms/帧）或 gdi（约 28.9 ms/帧） |
| frameIntervalMs | 16 | 捕获间隔 ≈ 62.5 fps —— 这是决定捕获速率的唯一位置（screen_watch 没有 fps 参数）。故意远低于每帧 33.333 ms 的界限：在 25 ms 时只剩 8.3 ms 的余量，而每段一次的编码器预构建（10–15 ms 的并发工作）会越过该界限；在 16 ms 时余量为 17.3 ms，同样的抖动仍保持在界限内。在全屏负载下用第二个辅助程序录制进行测量：25 ms 时为 4/2408 次未命中，而 16 ms 时为 1/11217 次。代价约为一个核心的 79%（相比 52%）以及 1.5 倍的录制大小。 |
| frameCapacity | 1800 | 环形缓冲区保留的帧数；只有 jpeg 编解码器使用它——h264 窗口受 retain_s 和字节预算限制 |
| jpegQuality | 70 | JPEG 质量 |
| codec | h264 | 帧存储：h264（内存段，每 20 分钟约 445 MB）或 jpeg（逐帧文件，6–11 GB） |
| captureDir | '' | 帧输出目录；为空表示辅助程序自己的临时目录 |
| recordDir | '' | 录制目录（Windows 路径）。设置后，每次 screen_watch start 还会将捕获的帧直接编码为该目录中的 mp4 文件——一个连续的编码器，时间戳取自真实捕获时刻，因此波动的捕获速率不会压缩播放。在 2560×1440 下实测：每 5 秒约 1.1 MB，而同样时长按逐帧 JPEG 写入约为 631 MB。录制意味着启用 h264。空值表示不录制。 |
| helperPath | '' | 辅助可执行文件；空值表示使用捆绑的 helper/CuHelper.exe |

插件自身代码的默认值在 frameIntervalMs（33）、backend（gdi）和 codec（jpeg）上有所不同：补丁
文件是部署声明其选择的地方，而代码为未挂载该补丁的部署保留保守值。denyReadImage 在两者中均为 true。

使用的宿主 API

该插件针对 harness ToolService（ctx.tools.register、ctx.tools.guard、ctx.tools.restrict）
以及用于所有权管理的 Cordis ctx.effect 进行注册。

通过在干净安装上的实际运行验证：harness @deepseek-ai/dsh@0.1.7-rc.1（撰写时最新发布的版本）在全新的 DSH_HOME 中，此仓库从 GitHub 克隆并链接到配置文件中——插件加载成功，全部 16 个工具均完成注册。相同的符号也存在于 @deepseek-ai/dsh-tools@0.1.5-rc.3 中。

限制

- 桌面是单一共享资源。 键盘和鼠标是全局的：同一台机器上的两个 DSH 实例不得同时操作，否则它们的操作会相互交错。
- 捕获以 frameIntervalMs 固定的速率运行（随附补丁中为 40 fps），活动时大约消耗四分之一个核心。该速率是部署选择，而非工具参数：screen_watch 没有 fps 参数。
- 在随附速率下满足逐帧间隔上限，但有罕见例外。 目标是任何帧间隔都不超过 33.333 ms；随附的 frameIntervalMs: 16（62.5 fps）留有 17.3 ms 的余量，因此每段一次的编码器预构建（约 220 ms 的 Media Foundation 工作，与捕获并发启动，使捕获线程耗费 10–15 ms）不再越过该上限。在全屏动画负载下、同时有第二个辅助程序录制时实测：16 ms 下 11217 帧中有 1 帧，而 25 ms 下 2408 帧中有 4 帧；那一次未达标是系统级尖峰（64.7 ms），而非预构建所致。封存（Finish+Dispose，负载下 176 ms）在独立线程上运行。不保证零未达标——系统级停顿在任何速率下仍可能超过上限。一个经过测试的替代方案（常驻预构建线程，捕获以 AboveNormal / 后台以 BelowNormal）只是将同样的停顿移到另一帧，并使最坏情况更糟，因此未被采用。数字/条件：
helper/README.md。
- H.264 分段是有损的（PSNR 44.8–50 dB）；它不影响阅读小号文字，但并非无损。
- 如果更改了 helper/*.cs，则必须使用 Windows 自带的 csc.exe 重新编译该助手；构建命令见
helper/README.md。