deepseek-computer-use 0.2.5 → 0.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/README.en.md +43 -21
- package/README.md +54 -367
- package/assets/plugin-icon.webp +0 -0
- package/docs/REFERENCE.en.md +51 -0
- package/docs/REFERENCE.zh.md +402 -0
- package/docs/assets/intro/workflow-en-dark.svg +1 -0
- package/docs/assets/intro/workflow-en-light.svg +1 -0
- package/docs/assets/intro/workflow-en-mobile-dark.svg +1 -0
- package/docs/assets/intro/workflow-en-mobile-light.svg +1 -0
- package/docs/assets/intro/workflow-zh-dark.svg +1 -0
- package/docs/assets/intro/workflow-zh-light.svg +1 -0
- package/docs/assets/intro/workflow-zh-mobile-dark.svg +1 -0
- package/docs/assets/intro/workflow-zh-mobile-light.svg +1 -0
- package/lib/update-client.js +1 -1
- package/package.json +9 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# 更新记录
|
|
2
2
|
|
|
3
|
+
## 0.2.7 (2026-10-30)
|
|
4
|
+
|
|
5
|
+
- 重整中英文首页:用途、三步流程图、安装入口与操作示例;详细配置与边界集中到完整说明。
|
|
6
|
+
- 保留下载统计、独立更新选择、问题反馈和贡献入口;原封面与运行功能保留。
|
|
7
|
+
- Refresh bilingual landing pages, workflow artwork, quick starts and reference navigation.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## 0.2.6 (2026-10-30)
|
|
11
|
+
|
|
12
|
+
- 原生插件列表与详情新增专门生成的鲸鱼娘图标:大头像、独立功能符号、透明留白,适合 30 / 36 px 显示;原封面保留。
|
|
13
|
+
- Add purpose-made whale-girl artwork with a distinct function emblem, transparent padding and small-size readability; preserve the original cover.
|
|
14
|
+
|
|
15
|
+
|
|
3
16
|
## 0.2.5 (2026-10-29)
|
|
4
17
|
|
|
5
18
|
- 补齐中英文使用流程:准备、入口、具体操作与结果核对;新增累计 npm 下载徽章并保留月统计。
|
package/README.en.md
CHANGED
|
@@ -1,14 +1,35 @@
|
|
|
1
|
-
|
|
1
|
+
[简体中文](README.md) · **English**
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Computer Use
|
|
4
|
+
|
|
5
|
+
**Let DSH work with Windows apps within your approval.**
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/deepseek-computer-use) [](https://www.npmjs.com/package/deepseek-computer-use)
|
|
6
8
|
|
|
7
|
-
[
|
|
9
|
+
**[Install](#install) · [Workflow](#start-using-it) · [Full guide](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.en.md)**
|
|
10
|
+
|
|
11
|
+
<picture>
|
|
12
|
+
<source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-en-mobile-dark.svg">
|
|
13
|
+
<source media="(max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-en-mobile-light.svg">
|
|
14
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-en-dark.svg">
|
|
15
|
+
<img src="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-en-light.svg" alt="Let DSH work with Windows apps within your approval. · workflow illustration" width="100%">
|
|
16
|
+
</picture>
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
- Inspect a screenshot or UI controls before the next step.
|
|
21
|
+
- Limit actions through session-level application approval.
|
|
22
|
+
- Check the result and keep audit and cancellation controls.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
Open **Plugins** in the DSH desktop app and install `deepseek-computer-use`. If the CLI is available:
|
|
8
27
|
|
|
9
|
-
|
|
28
|
+
```bash
|
|
29
|
+
dsh plugin --profile desktop add deepseek-computer-use
|
|
30
|
+
```
|
|
10
31
|
|
|
11
|
-
|
|
32
|
+
For the web profile, replace `desktop` with `web`. Restart that DSH profile after installation. The package’s DSH requirement is `>=0.2.1-rc.3`.
|
|
12
33
|
|
|
13
34
|
## Start using it
|
|
14
35
|
|
|
@@ -18,32 +39,33 @@ Community plugin, not an official DeepSeek product.
|
|
|
18
39
|
4. Review approval details for sensitive actions; re-observe after failures or uncertain results instead of submitting twice.
|
|
19
40
|
5. Check the result in the application. Cancel the task to stop its native helper when needed.
|
|
20
41
|
|
|
21
|
-
|
|
42
|
+
Example request:
|
|
22
43
|
|
|
23
|
-
|
|
44
|
+
> Inspect the target app window and controls, then explain the next step without clicking or typing.
|
|
24
45
|
|
|
25
|
-
|
|
26
|
-
dsh plugin --profile web add deepseek-computer-use
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Restart the host after installation. This package operates the Windows computer running DSH; a remote browser does not move execution to the viewer's computer.
|
|
46
|
+
## Before you start
|
|
30
47
|
|
|
31
|
-
|
|
48
|
+
For Windows 10/11. Permissions, control support and the desktop environment affect what can be automated.
|
|
32
49
|
|
|
33
|
-
|
|
50
|
+
Configuration, detailed tools and troubleshooting: [full reference](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.en.md).
|
|
34
51
|
|
|
35
|
-
|
|
52
|
+
## Plugin updates
|
|
36
53
|
|
|
37
|
-
|
|
54
|
+
Check updates at the bottom of the workbench or native plugin details. Automatic checks are on by default; **automatic installation is off**. You choose whether to install and when to restart. Suite-managed components update with their bundle. [Update behavior](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.en.md).
|
|
38
55
|
|
|
39
|
-
|
|
56
|
+
## Documentation
|
|
40
57
|
|
|
41
|
-
|
|
58
|
+
- [Full usage, configuration and limits](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.en.md)
|
|
59
|
+
- [Release notes](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/CHANGELOG.md)
|
|
42
60
|
|
|
43
|
-
|
|
61
|
+
## Feedback and contributions
|
|
44
62
|
|
|
45
|
-
|
|
63
|
+
If the plugin helps, a Star makes it easier for others to discover. Report problems or suggest improvements in [Issues](https://github.com/STARDUSTLC666/deepseek-computer-use/issues); code and documentation [PRs](https://github.com/STARDUSTLC666/deepseek-computer-use/pulls) are welcome. Include versions and reproduction steps, and remove credentials from reports.
|
|
46
64
|
|
|
47
65
|
## License
|
|
48
66
|
|
|
49
|
-
[MIT](LICENSE)
|
|
67
|
+
[MIT](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/LICENSE)
|
|
68
|
+
|
|
69
|
+
<a id="use"></a>
|
|
70
|
+
<a id="updates"></a>
|
|
71
|
+
<a id="documentation-and-feedback"></a>
|
package/README.md
CHANGED
|
@@ -1,33 +1,36 @@
|
|
|
1
|
-
|
|
1
|
+
**简体中文** · [English](README.en.md)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Computer Use
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**让 DSH 在授权范围内操作 Windows 应用。**
|
|
6
6
|
|
|
7
|
-
[
|
|
7
|
+
[](https://www.npmjs.com/package/deepseek-computer-use) [](https://www.npmjs.com/package/deepseek-computer-use)
|
|
8
|
+
[](https://www.npmjs.com/package/deepseek-computer-use)
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
**[安装使用](#安装) · [使用流程](#开始使用) · [完整说明](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.zh.md)**
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
<picture>
|
|
13
|
+
<source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-zh-mobile-dark.svg">
|
|
14
|
+
<source media="(max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-zh-mobile-light.svg">
|
|
15
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-zh-dark.svg">
|
|
16
|
+
<img src="https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/docs/assets/intro/workflow-zh-light.svg" alt="让 DSH 在授权范围内操作 Windows 应用。 · 流程示意" width="100%">
|
|
17
|
+
</picture>
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
## 功能
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
- 先查看窗口截图或界面控件,再决定下一步。
|
|
22
|
+
- 通过会话应用授权限制操作范围。
|
|
23
|
+
- 检查实际结果,保留操作审计与中断能力。
|
|
19
24
|
|
|
20
|
-
|
|
21
|
-
支持会话独立授权、敏感操作审批与审计;取消或回合结束时停止原生助手,
|
|
22
|
-
操作失败后要求重新观察,减少结果不明时的重复操作。
|
|
25
|
+
## 安装
|
|
23
26
|
|
|
24
|
-
|
|
25
|
-
工具语义参考 Codex window2,并针对 DSH 的会话、审批和截图附件机制适配。
|
|
27
|
+
在 DSH 桌面版「插件」面板安装 `deepseek-computer-use`。已配置命令行时也可使用:
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
```bash
|
|
30
|
+
dsh plugin --profile desktop add deepseek-computer-use
|
|
31
|
+
```
|
|
28
32
|
|
|
29
|
-
|
|
30
|
-
抓屏(WGC)和录音(WASAPI)是 net48 程序,Windows 10/11 自带运行时。
|
|
33
|
+
网页版把 `desktop` 改为 `web`;安装后重启对应的 DSH。宿主要求以包声明 `>=0.2.1-rc.3` 为准。
|
|
31
34
|
|
|
32
35
|
## 开始使用
|
|
33
36
|
|
|
@@ -37,364 +40,48 @@
|
|
|
37
40
|
4. 敏感操作先核对审批内容;失败或结果不明确时重新观察,避免重复提交。
|
|
38
41
|
5. 检查软件中的实际结果;需要中断时取消当前任务,插件会停止本次原生助手。
|
|
39
42
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
要求 Windows 10/11、Node.js 22.19+ / 24+。推荐从 DSH 原生插件管理按 `deepseek-computer-use` 安装,或运行:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
dsh plugin --profile desktop add deepseek-computer-use
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
网页版把 `desktop` 改为 `web`。完成后重启实际使用的 profile,再新建会话。下面的手动配置用于源码开发,普通安装无需重复修改配置。
|
|
49
|
-
|
|
50
|
-
<details>
|
|
51
|
-
<summary>源码开发与可选抓屏 / 录音组件</summary>
|
|
52
|
-
|
|
53
|
-
要求:**Windows 10/11**、**Node.js 22.19+ / 24+**。其余都是系统组件(.NET Framework 4.8、
|
|
54
|
-
UI Automation、WGC)。
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
npm install deepseek-computer-use
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
[npmjs.com/package/deepseek-computer-use](https://www.npmjs.com/package/deepseek-computer-use)
|
|
61
|
-
|
|
62
|
-
然后在本机 profile 的 `cordis.patch.yml` 里启用(详见本文件末尾的配置示例):
|
|
63
|
-
|
|
64
|
-
```yaml
|
|
65
|
-
- insert:
|
|
66
|
-
- id: deepseek-computer-use
|
|
67
|
-
name: 'deepseek-computer-use'
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
首次调用任意 Computer Use 工具时会自动编译 helper 与覆盖层(约 1 秒)。
|
|
71
|
-
想要抓屏/录音这两项可选能力,再跑一次:
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
npm run build # helper + overlay(csc),再尝试 dotnet 编 capture/audio
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
没有 .NET SDK 也能用:抓屏自动退回 PrintWindow,录音会明确报 `audio_missing`。
|
|
78
|
-
|
|
79
|
-
</details>
|
|
80
|
-
|
|
81
|
-
## 自检
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
npm test # DSH 参数/策略回归 + 原生 WinForms 集成验证
|
|
85
|
-
npm run test:contracts # 只运行参数与策略测试,不操作桌面
|
|
86
|
-
npm run test:harness -- --dsh-root /path/to/node_modules/@deepseek-ai/dsh
|
|
87
|
-
# test:harness 启动隔离的真实 DSH CLI/profile,验证附件、审批和原生操作。
|
|
88
|
-
# npm run test:all 另含真实系统音频录制测试,按需运行。
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## DeepSeek Harness 接入
|
|
92
|
-
|
|
93
|
-
这是通过 DSH 的 `apply(ctx)` / `inject` / bundle patch 接入的独立插件。
|
|
94
|
-
工具注册使用标准 JSON Schema,截图通过 `attachments` 保存并输出模型可见的 image block,
|
|
95
|
-
应用授权与危险动作通过 `approval.request` 审批并写入会话审计。
|
|
96
|
-
每个会话独立保存授权、helper、截图与元素快照;同一桌面的工具调用串行执行。
|
|
97
|
-
DSH 附件存储缩小截图时,坐标会自动换算回原始抓屏像素。
|
|
98
|
-
|
|
99
|
-
在需要使用的 DSH profile 中安装,例如 Git Bash 下:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
dsh plugin --profile web add deepseek-computer-use
|
|
103
|
-
dsh web --no-open
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
开发时可将包名换成 `file:E:/deepseek/dsh-computer-use` 来加载本地源码。
|
|
107
|
-
以下宿主适配和失败恢复改进包含在 0.1.2 及后续版本中,详见 [更新记录](CHANGELOG.md)。
|
|
108
|
-
`test:harness` 不调用模型、不录音,只操作自己创建的测试窗口,结束后移除隔离 profile。
|
|
109
|
-
|
|
110
|
-
中止与失败恢复:
|
|
111
|
-
|
|
112
|
-
- 超时或取消会先通知当前原生请求停止;输入循环检查取消标记,并在 `finally` 释放按键/鼠标按钮。
|
|
113
|
-
helper 未在 500ms 内退出时会被终止;调用失败返回前确认旧进程已经退出。
|
|
114
|
-
- DSH 的 `session/event` 出现 `turn/end` 时主动停止该会话的 helper 和覆盖层,不依赖下一次工具调用。
|
|
115
|
-
- 输入或抓屏失败会清除已缓存的快照。后续输入返回 `fresh_observation_required`,
|
|
116
|
-
必须成功调用 `get_window_state` 后再决定动作;不会自动重复结果不明的输入。
|
|
117
|
-
- 新 helper 使用不同的截图 id,防止重启前的截图编号误命中新缓存。
|
|
118
|
-
原生协议已升级为 2,自定义 `helperPath` 也需要匹配版本。
|
|
119
|
-
|
|
120
|
-
## 它解决什么问题
|
|
121
|
-
|
|
122
|
-
DSH 官方已有需要显式启用的实验性 Computer Use 方案,包括 Cua Driver MCP 与原生
|
|
123
|
-
提供方;其上游 Cua Driver 也支持 Windows。详见 [官方计算机操作文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/computer-use.zh.md)
|
|
124
|
-
和 [Cua Driver 平台支持](https://github.com/trycua/cua/blob/main/docs/content/docs/reference/cua-driver/contracts.mdx)。
|
|
125
|
-
|
|
126
|
-
本插件是另一套独立的 Windows 社区实现,提供 UI Automation、窗口截图、鼠标键盘、
|
|
127
|
-
会话授权、审批审计和中断恢复,用于点击按钮、填写表单或操作没有 API 的桌面软件。
|
|
128
|
-
它与官方方案有功能重合;本项目的验收结果不代表已与官方驱动做过效果或性能对比。
|
|
129
|
-
|
|
130
|
-
## 架构
|
|
131
|
-
|
|
132
|
-
```text
|
|
133
|
-
DSH 宿主
|
|
134
|
-
└─ lib/index.js apply(ctx) → 注册 16 个工具;图片走 attachments;审批走 approval
|
|
135
|
-
├─ lib/tools.js 工具定义(Codex window2 语义)
|
|
136
|
-
├─ lib/safety.js 白名单/黑名单 + 危险动作审批门
|
|
137
|
-
└─ lib/bridge.js 常驻进程 + 串行 JSON-lines RPC + 超时/取消
|
|
138
|
-
└─ native/bin/dsh-computer-use-helper.exe (用系统 csc.exe 现编)
|
|
139
|
-
├─ native/Driver.cs IPlatformDriver 契约 + WindowsDriver(UIA / SendInput / PrintWindow)
|
|
140
|
-
├─ native/Json.cs 零依赖 JSON 解析与序列化
|
|
141
|
-
└─ native/Program.cs stdio 分发
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
驱动层是接口(`IPlatformDriver`),今天是 `windows` 一个实现;macOS(AX + CGEvent)
|
|
145
|
-
和 Linux(AT-SPI)可以照着补,插件层不用改。
|
|
146
|
-
|
|
147
|
-
每个会话的 helper 常驻的原因:元素编号必须和"那一次观测"绑在同一个进程里,否则
|
|
148
|
-
`click(element_index)` 无从解析。因此插件串行发请求、按 id 配对响应。
|
|
149
|
-
|
|
150
|
-
## 工具
|
|
151
|
-
|
|
152
|
-
| 工具 | 作用 |
|
|
153
|
-
|---|---|
|
|
154
|
-
| `list_apps` | 列出当前有可操作窗口的应用及其窗口 |
|
|
155
|
-
| `list_windows` | 列出可见窗口:id / 标题 / 所属应用 / z 序 / 边框 |
|
|
156
|
-
| `get_window` | 按 id 重新读取窗口(换绑、刷新边框) |
|
|
157
|
-
| `launch_app` | 启动应用(可带参数),默认需要审批 |
|
|
158
|
-
| `get_window_state` | 观测:带编号的无障碍树 +(可选)窗口截图 |
|
|
159
|
-
| `click` | 按元素编号(优先走 Invoke,抗遮挡)或窗口相对坐标点击 |
|
|
160
|
-
| `press_key` | 单键或组合键,X keysym 风格:`Control_L+s`、`Return` |
|
|
161
|
-
| `type_text` | 注入 Unicode 文本(与键盘布局无关,中文安全) |
|
|
162
|
-
| `scroll` | 在坐标或元素处滚动 |
|
|
163
|
-
| `drag` | 窗口内拖拽 |
|
|
164
|
-
| `set_value` | 用 Value 模式直接改值,比"点击+全选+输入"更稳更省 |
|
|
165
|
-
| `perform_secondary_action` | Invoke / Expand / Collapse / Toggle / Select / Scroll Up… |
|
|
166
|
-
| `activate_window` | 把窗口提到前台 |
|
|
167
|
-
| `start_audio_recording` | 开始录制系统音频(WASAPI 环回),需 `audio: true` |
|
|
168
|
-
| `stop_audio_recording` | 停止录音并返回 WAV 路径与字节数 |
|
|
169
|
-
| `computer_use_health` | 自检:helper、编译器、策略、窗口数 |
|
|
170
|
-
|
|
171
|
-
## 使用中指示器(对齐 Codex 的两个 overlay)
|
|
172
|
-
|
|
173
|
-
Codex 用两层覆盖层告诉用户"AI 正在动你的电脑",这里做的是同一套:
|
|
174
|
-
|
|
175
|
-
**Display Overlay — 呼吸细边**
|
|
176
|
-
- 一圈 **1.4px 的强调色细线** + 3 层递减光环,圆角 18px;只占屏幕最外圈,不压内容
|
|
177
|
-
- 亮度按约 3.2 秒周期呼吸(内线 alpha 170→240、光环 26→46)
|
|
178
|
-
- 4 条边 + 4 个圆角 = 8 个细长分层窗口,每帧位图几 KB
|
|
179
|
-
- 底部居中一枚自动宽度玻璃胶囊:脉冲圆点 + `DSH 正在使用您的电脑` +
|
|
180
|
-
`Esc` 键帽 + `取消`,停在任务栏上方留白
|
|
181
|
-
|
|
182
|
-
**Cursor Overlay — 虚拟光标 + 系统光标抑制**
|
|
183
|
-
- 覆盖层存在期间常驻一个带描边和投影的白色指针,启动时落在真实指针位置,
|
|
184
|
-
之后 0.35 缓动滑向每个动作点;背后一层极淡的强调色光晕
|
|
185
|
-
- 默认抑制真实系统光标(`SetSystemCursor` 换成透明图标),五层恢复保障:
|
|
186
|
-
1. 正常退出 / Esc / 超时 → 退出钩子里 `SPI_SETCURSORS`
|
|
187
|
-
2. **独立守卫进程**(`--cursor-guard <ownerPid>`)盯着覆盖层,覆盖层被强杀后
|
|
188
|
-
它负责还原——和 Codex 的 `system-cursor-manager` 同一思路
|
|
189
|
-
3. helper 的 **500ms 看门狗**:标记里的 PID 失效就还原,不需要任何请求
|
|
190
|
-
4. helper **启动即自检**:上次会话残留的标记会被清掉
|
|
191
|
-
5. 插件 dispose 时发 `restore_cursor` RPC
|
|
192
|
-
- 抑制期间 `%LOCALAPPDATA%\dsh-computer-use\cursor-hidden.flag` 记录自己的 PID,
|
|
193
|
-
守卫只清理属于自己 owner 的标记,不会误伤新一代覆盖层
|
|
194
|
-
- Windows 在休眠恢复 / 换分辨率后会重置光标,覆盖层每约 1.8 秒**重新抑制**一次
|
|
195
|
-
- 完全不想抑制:`DSH_CU_KEEP_CURSOR=1`
|
|
196
|
-
helper 强杀覆盖层时也会兜底恢复一次
|
|
197
|
-
|
|
198
|
-
**DPI 关键点**:覆盖层进程必须 Per-Monitor-V2 感知,否则在 150% 缩放屏上
|
|
199
|
-
系统会把 1707×1067 的逻辑画面放大到 2560×1600,描边变糊、位置偏移 1.5 倍。
|
|
200
|
-
|
|
201
|
-
**Esc 是按 turn 生效的**:首次触发报 `cancelled_by_user`,同一 turn 内后续调用直接
|
|
202
|
-
`turn_stopped`,新 turn 才恢复。
|
|
203
|
-
|
|
204
|
-
## 安全模型
|
|
205
|
-
|
|
206
|
-
1. **可达性**:`allowApps` / `denyApps` 决定这个插件能不能碰某个应用;空数组 = 不限制。
|
|
207
|
-
2. **确认**:`approval` 三档
|
|
208
|
-
- `never`:从不询问(自担风险)
|
|
209
|
-
- `sensitive`(默认):目标元素标签命中危险词(delete/删除/卸载/支付/提交/安装…)才问;
|
|
210
|
-
`launch_app` 总是问
|
|
211
|
-
- `always`:每次动作都问
|
|
212
|
-
审批走 DSH 自己的 approval seam;**没有审批服务时直接拒绝**,绝不静默降级。
|
|
213
|
-
DSH 宿主的 `approval` 策略 `never` 表示拒绝需要审批的请求,与本插件配置项的
|
|
214
|
-
`approval: never`(跳过动作级询问)含义不同。应用授权仍由 `appConsent` 单独控制。
|
|
215
|
-
3. **前台证明**:打字、按键、坐标点击、滚动必须先证明目标窗口真的拿到了前台,
|
|
216
|
-
否则抛 `focus_failed` 并告诉你当前是谁占着前台。SendInput 会打到有焦点的窗口,
|
|
217
|
-
这一步省不得。
|
|
218
|
-
4. **快照 TTL**:元素编号默认 120 秒过期,过期必须重新观测,避免"拿旧编号点新界面"。
|
|
219
|
-
5. **`dryRun`**:只回放动作不注入,用于集成演练。
|
|
220
|
-
|
|
221
|
-
## 安装
|
|
222
|
-
|
|
223
|
-
```powershell
|
|
224
|
-
# 1. 放进 DSH 的 profile
|
|
225
|
-
cd "E:\path\to\dsh-computer-use"
|
|
226
|
-
# 方式 A:本地目录挂载(把本目录链进 profile 的 node_modules)
|
|
227
|
-
# 方式 B:npm pack 后用宿主插件管理器安装
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
插件通过 `package.json` 的 `dsh.bundle.patch` 声明自己:
|
|
231
|
-
|
|
232
|
-
```json
|
|
233
|
-
{ "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
`cordis.patch.yml` 负责往宿主配置里插插件行。装好后重启宿主,让模型调
|
|
237
|
-
`computer_use_health` 自检;第一次调用会自动编译 helper(约 1-2 秒)。
|
|
238
|
-
|
|
239
|
-
## 配置
|
|
240
|
-
|
|
241
|
-
```yaml
|
|
242
|
-
- id: deepseek-computer-use
|
|
243
|
-
config:
|
|
244
|
-
approval: sensitive # never | sensitive | always
|
|
245
|
-
allowApps: ["notepad", "chrome"] # 空 = 不限制
|
|
246
|
-
denyApps: []
|
|
247
|
-
defaultIncludeScreenshot: true # 默认抓图;false 可显式关闭
|
|
248
|
-
maxElements: 260
|
|
249
|
-
snapshotTtlMs: 120000
|
|
250
|
-
dryRun: false
|
|
251
|
-
toolPrefix: '' # 填 'cu_' 可避免与其他插件的 click 重名
|
|
252
|
-
timeoutMs: 10000
|
|
253
|
-
```
|
|
43
|
+
可以这样说:
|
|
254
44
|
|
|
255
|
-
|
|
45
|
+
> 先查看目标应用的窗口和控件,说明下一步计划,暂不点击或输入。
|
|
256
46
|
|
|
257
|
-
|
|
258
|
-
它是 DSH 的独立实现,不能据此认为具有相同的模型能力、成功率或全部运行时行为。
|
|
47
|
+
## 开始前要知道
|
|
259
48
|
|
|
260
|
-
|
|
261
|
-
`{ apps, count }`;`window.app` 返回应用元数据对象,输入也接受字符串 app id 或只提供窗口 id;
|
|
262
|
-
`get_window` 接收 `{ window: { id } }`;截图返回 DSH 附件引用和 image block,Codex 使用图片 URL。
|
|
49
|
+
面向 Windows 10/11;应用权限、控件支持和桌面环境会影响可操作范围。
|
|
263
50
|
|
|
264
|
-
|
|
265
|
-
|---|---|---|
|
|
266
|
-
| `get_window_state` 默认 | 截图 ON、accessibility `null` | 一致(`include_text:true` 才出树) |
|
|
267
|
-
| 返回形态 | `{ window, screenshots[], accessibility }` | 一致;`screenshots` 是数组,含窗口 + 关联瞬态 UI(菜单/tooltip),每项带 `id`/`zIndex`/`originX`/`originY`/尺寸 |
|
|
268
|
-
| 坐标寻址 | `click`/`scroll`/`drag` 收 `screenshotId` | 一致;坐标系绑定那张截图,过期报 `stale_screenshot` |
|
|
269
|
-
| `scroll` | `x`,`y` 必填,无 `element_index` | 一致(缺 x/y 直接拒) |
|
|
270
|
-
| accessibility 结构化字段 | `tree`/`focused_element`/`selected_text`/`selected_elements`/`document_text` | 全部实现 |
|
|
271
|
-
| 观测节奏 | 动作后自动等约 1s 再抓 | 一致(`settleMs`,默认 1000) |
|
|
272
|
-
| 元素失效 | 编号只对产生它的观测有效 | 一致(TTL + helper 进程内缓存) |
|
|
273
|
-
| 最小化窗口 | 不该给出无意义画面 | 本插件直接报 `window_minimized`(实测旧版会吐出 334×48 的假图) |
|
|
274
|
-
| 键名 | X keysym + `Numpad_*` 别名 | 一致(`KP_0`/`Numpad_Add`/…) |
|
|
275
|
-
| `list_apps` | `lastUsedDate`、`useCount` | `lastUsedDate` 用进程启动时间近似,并非用户最近使用时间;`useCount` 留空 |
|
|
276
|
-
| `launch_app` | app id / `.exe` 路径(含 UWP) | exe 路径、AUMID(`shell:AppsFolder\\…`)、shell URI |
|
|
277
|
-
| Win/Meta 键 | 硬拒绝 | 硬拒绝(插件层 + helper 层双保险) |
|
|
278
|
-
| 终端/Run/密码管理器/安全软件/认证对话框/宿主自身 | 硬拒绝 | 硬拒绝(不可被审批覆盖) |
|
|
279
|
-
| 按应用授权 | "Computer Use was not approved to use <app>" | 每会话每应用一次审批(`appConsent: session`),批准后下发 `approve_app`,**由 helper 强制**:未批准的应用直接 `app_not_approved` |
|
|
280
|
-
| 回合边界 | 回合与 helper 生命周期关联 | DSH 回合结束事件主动停止旧 helper;新回合创建新 helper,并重新下发已获应用授权 |
|
|
281
|
-
| 请求预算 | 普通 10s、`launch_app` 15s | 一致(`timeoutMs` / `launchTimeoutMs`) |
|
|
282
|
-
| 回合结束停止输入 | `turn_ended` 钩子 | 主动停止正在执行的请求,排队中的旧回合请求也被拒绝 |
|
|
51
|
+
配置、完整工具与排错见[详细使用说明](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.zh.md)。
|
|
283
52
|
|
|
284
|
-
##
|
|
285
|
-
|
|
286
|
-
- **`paste` / `select_text`**:属于 macOS 的 window 客户端(`target: "mac"`),Windows 上不存在。
|
|
287
|
-
- **系统音频录制**(`start_audio_recording`):已实现 WASAPI 环回录音,默认关闭,需要构建 audio helper 并单独授权。
|
|
288
|
-
- **full-desktop 面**(`clipboard_read/write`、`key_down/up`、`move`、`drag_handle`、`get_screenshot`):那是 `target: "linux"` 的 API。
|
|
289
|
-
- **区域裁剪截图**:当前抓整窗(长边封顶 2560),不能认为与 Codex 的 bounded screenshot 完全等价。
|
|
290
|
-
- **Windows.Graphics.Capture**:构建 capture helper 后优先使用 WGC;不可用时回退到 PrintWindow / BitBlt,GPU 窗口的兼容性取决于实际使用的抓屏后端。
|
|
291
|
-
|
|
292
|
-
## 抓屏链路(对齐 Codex 的 WGC)
|
|
293
|
-
|
|
294
|
-
按顺序尝试,前一级成功就不走下一级:
|
|
295
|
-
|
|
296
|
-
1. **Windows.Graphics.Capture**(`native/bin/capture/dsh-cu-capture.exe`,**.NET Framework 4.8** + SharpDX)
|
|
297
|
-
—— 抓窗口的合成层,遮挡可用、GPU/直合成界面正常、无 DPI 黑边。
|
|
298
|
-
**不依赖 .NET 8 运行时**(Framework 4.8 是 Windows 自带组件),载荷仅 0.68MB
|
|
299
|
-
2. **PrintWindow(PW_RENDERFULLCONTENT)** —— 无 .NET 8 运行时的机器上的兜底
|
|
300
|
-
3. **屏幕 BitBlt** —— 前两者失败或返回黑图时
|
|
301
|
-
|
|
302
|
-
WGC 走 .NET Framework 4.8(Windows 10/11 自带),**用户不需要安装任何运行时**。
|
|
303
|
-
万一抓取失败仍会自动降级到第 2 级。
|
|
304
|
-
覆盖层是独立窗口,WGC 按窗口抓取时天然不会被拍进去——和 Codex 的
|
|
305
|
-
"exclude display overlay from captures" 等效。
|
|
306
|
-
|
|
307
|
-
## 已知限制
|
|
308
|
-
|
|
309
|
-
- **只有 Windows 驱动**。macOS / Linux 只有接口(`IPlatformDriver`),没有实现。
|
|
310
|
-
- **前台焦点是硬约束**。前台被置顶工具(如 Process Lasso)或提权窗口占住时,
|
|
311
|
-
`type_text`/`press_key`/坐标点击/`scroll` 会被拒绝并报出占用者。
|
|
312
|
-
语义动作(`set_value`、Invoke 点击、Expand)不需要前台,照常工作。
|
|
313
|
-
- **Electron/Chromium 无障碍树很薄**,网页内容要走截图 + 坐标。
|
|
314
|
-
- **不绕过 UIPI**:目标窗口权限更高时注入会被系统拦。
|
|
315
|
-
- **DPI 虚拟化已处理**:老式/无 DPI 感知的程序按 96 DPI 渲染,窗口物理尺寸被 DWM 放大,
|
|
316
|
-
`PrintWindow` 返回的是未缩放画面(此前会带黑边)。现在抓屏会裁掉黑边,并记录
|
|
317
|
-
「物理像素 / 截图像素」比例(实测某 WinForms 程序为 1.46×),坐标动作按该比例换算,
|
|
318
|
-
所以**截图坐标点哪就点哪**。
|
|
319
|
-
- **`useCount`、应用使用历史**没有可靠本机数据源,宁缺不编。
|
|
320
|
-
|
|
321
|
-
## 测试
|
|
322
|
-
|
|
323
|
-
```powershell
|
|
324
|
-
node test/integration.mjs
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
固定装置是一个独立的 WinForms 可执行文件(`test/bin/dsh-cu-fixture.exe`,一个文本框 +
|
|
328
|
-
一个名为 "Delete all" 的按钮;特意不用 shell 托管——shell 窗口本身被硬拒绝)。覆盖:
|
|
329
|
-
16 个工具注册、截图数组与 origin/zIndex、`accessibility:null` 语义、`set_value`、
|
|
330
|
-
`type_text`、危险按钮触发审批、`dryRun` 不落地、`denyApps` 拒绝、Win 键硬拒绝、
|
|
331
|
-
`scroll` 契约。
|
|
332
|
-
|
|
333
|
-
## 许可
|
|
334
|
-
|
|
335
|
-
MIT。第三方商用前请自行做安全评审:这个插件能让模型操作你的桌面。
|
|
336
|
-
|
|
337
|
-
## 原生载荷(native/bin)
|
|
338
|
-
|
|
339
|
-
| 文件 | 用途 | 大小 |
|
|
340
|
-
|---|---|---|
|
|
341
|
-
| `dsh-computer-use-helper.exe` | UIA / SendInput / 抓屏调度 / 音频调度 | ~50KB |
|
|
342
|
-
| `dsh-cu-overlay.exe` | 呼吸光边 + 虚拟光标覆盖层 | ~30KB |
|
|
343
|
-
| `capture/` | WGC 抓屏(.NET Framework 4.8 + SharpDX) | 0.68MB |
|
|
344
|
-
| `audio/` | WASAPI 环回录音(NAudio) | 0.60MB |
|
|
345
|
-
| **合计** | | **~1.4MB** |
|
|
346
|
-
|
|
347
|
-
全部基于 Windows 自带的 .NET Framework 4.8,**用户零安装**。
|
|
348
|
-
|
|
349
|
-
## 与 Codex window2 的细节对齐(第二轮)
|
|
350
|
-
|
|
351
|
-
| 能力 | 实现 |
|
|
352
|
-
|---|---|
|
|
353
|
-
| 协议握手 | helper 提供 `hello` → `{ protocolVersion: 2, capabilities: [...] }`;bridge 首次连接校验,不匹配直接报 `protocol_mismatch` |
|
|
354
|
-
| 每请求预算 | 客户端把预算随请求下发(`__budgetMs`,对应 Codex 的 `x-oai-cua-request-budget-ms`),helper 用它收缩抓屏等待 |
|
|
355
|
-
| 坐标越界 | `point_outside_screenshot`,文案同 Codex("is outside screenshot bounds … Take a fresh screenshot before retrying") |
|
|
356
|
-
| 截图失效 | `stale_screenshot` 带同一句 "Take a fresh screenshot before retrying" |
|
|
357
|
-
| 优雅关闭 | `close` RPC → helper 落盘后退出 0;插件 dispose 时先发 close 再兜底 kill |
|
|
358
|
-
| Esc 语义 | 覆盖层退出码 **130** → helper 写入 `%LOCALAPPDATA%\dsh-computer-use\interrupts\<会话>-<turn>.flag` 并自身退出 130;同 turn 后续调用 `turn_stopped`,新 turn 放行 |
|
|
359
|
-
| 音频授权 | 独立于应用授权的一次性确认(Codex: `computer-audio` / "Allow Computer Use to record computer audio?") |
|
|
360
|
-
| 音频返回 | `{ filepath, bytes: base64 WAV, data_url }`,统一 **24 kHz 立体声 16-bit** |
|
|
361
|
-
| 音频上限 | 单次录音 ≤ 300 000 ms(Codex 同值),不足 500 ms 自动抬到 500 |
|
|
362
|
-
| App 字段 | `isRunning` + `lastUsedDate`(进程启动时间);`useCount` 无数据来源,按 Codex 的可选字段处理,不伪造 |
|
|
363
|
-
|
|
364
|
-
marker 文件按 **会话 + turn** 命名,避免旧会话的 Esc 标记误伤新会话。
|
|
365
|
-
|
|
366
|
-
## 配置示例
|
|
367
|
-
|
|
368
|
-
```yaml
|
|
369
|
-
- insert:
|
|
370
|
-
- id: deepseek-computer-use
|
|
371
|
-
name: 'deepseek-computer-use'
|
|
372
|
-
config:
|
|
373
|
-
approval: sensitive # never | sensitive | always
|
|
374
|
-
appConsent: session # 每个应用问一次;never 表示不问
|
|
375
|
-
audio: false # 开启 WASAPI 环回录音(start/stop_audio_recording)
|
|
376
|
-
redactApps: [] # 这些应用的截图永不出机器,例如 ["1password", "银行"]
|
|
377
|
-
defaultIncludeScreenshot: true
|
|
378
|
-
timeoutMs: 10000 # 单次 RPC 超时(launch_app 用 launchTimeoutMs)
|
|
379
|
-
helperPath: null # 覆盖 helper 路径(仅信任场景)
|
|
380
|
-
riskyPattern: '' # 自定义「危险动作」正则,命中走审批
|
|
381
|
-
toolPrefix: '' # 例如 cu_ 可避免和其他插件的 click 重名
|
|
382
|
-
```
|
|
53
|
+
## 插件更新
|
|
383
54
|
|
|
384
|
-
|
|
55
|
+
在工作台或原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。[查看更新规则](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.zh.md)。
|
|
385
56
|
|
|
386
|
-
|
|
387
|
-
- Codex window2 没有的接口(`paste` / `clipboard_*` / `key_down` / `move`)这里也没有。
|
|
388
|
-
- `App.useCount` 没有数据来源,按可选字段留空,不伪造。
|
|
389
|
-
- `redactApps` 在**插件层**执行:直接调用 helper 的 RPC 不受它约束,别把 helper 单独暴露给非受信调用方。
|
|
390
|
-
- 抢焦点类工具(如 ProcessLasso)会让 `type_text` 返回 `focus_failed`,这是设计行为——宁可不输入,也不打到别的窗口。
|
|
57
|
+
## 文档
|
|
391
58
|
|
|
392
|
-
|
|
59
|
+
- [详细使用、配置与边界](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/docs/REFERENCE.zh.md)
|
|
60
|
+
- [更新记录](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/CHANGELOG.md)
|
|
393
61
|
|
|
394
|
-
|
|
62
|
+
## 反馈与贡献
|
|
395
63
|
|
|
396
|
-
|
|
64
|
+
如果插件帮到了你,欢迎 Star,让更多人发现它。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/deepseek-computer-use/issues),也欢迎代码与文档 [PR](https://github.com/STARDUSTLC666/deepseek-computer-use/pulls)。反馈时附上版本与复现步骤,并移除凭据。
|
|
397
65
|
|
|
398
66
|
## License
|
|
399
67
|
|
|
400
|
-
MIT
|
|
68
|
+
[MIT](https://github.com/STARDUSTLC666/deepseek-computer-use/blob/main/LICENSE)
|
|
69
|
+
|
|
70
|
+
<a id="自检"></a>
|
|
71
|
+
<a id="deepseek-harness-接入"></a>
|
|
72
|
+
<a id="它解决什么问题"></a>
|
|
73
|
+
<a id="架构"></a>
|
|
74
|
+
<a id="工具"></a>
|
|
75
|
+
<a id="使用中指示器对齐-codex-的两个-overlay"></a>
|
|
76
|
+
<a id="安全模型"></a>
|
|
77
|
+
<a id="配置"></a>
|
|
78
|
+
<a id="与-codex-windows-window2-的关系"></a>
|
|
79
|
+
<a id="能力边界"></a>
|
|
80
|
+
<a id="抓屏链路对齐-codex-的-wgc"></a>
|
|
81
|
+
<a id="已知限制"></a>
|
|
82
|
+
<a id="测试"></a>
|
|
83
|
+
<a id="许可"></a>
|
|
84
|
+
<a id="原生载荷nativebin"></a>
|
|
85
|
+
<a id="与-codex-window2-的细节对齐第二轮"></a>
|
|
86
|
+
<a id="配置示例"></a>
|
|
87
|
+
<a id="已知边界"></a>
|
|
Binary file
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
> Full usage reference. The landing page focuses on outcomes, installation and workflows; detailed parameters, limits, update rules and historical validation links remain here.
|
|
2
|
+
|
|
3
|
+
# deepseek-computer-use
|
|
4
|
+
|
|
5
|
+
[中文](../README.md)
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/deepseek-computer-use) [](https://www.npmjs.com/package/deepseek-computer-use)
|
|
8
|
+
|
|
9
|
+
[Download statistics](https://github.com/STARDUSTLC666/dsh-suite/blob/npm-downloads/README.md)
|
|
10
|
+
|
|
11
|
+
Let DeepSeek Harness operate Windows desktop apps: discover windows, inspect screenshots and UI controls, then use mouse and keyboard actions. Designed for GUI tasks without a suitable API, with per-session app consent, sensitive-action confirmation and audit records.
|
|
12
|
+
|
|
13
|
+
Community plugin, not an official DeepSeek product.
|
|
14
|
+
|
|
15
|
+
## Start using it
|
|
16
|
+
|
|
17
|
+
1. Install deepseek-computer-use in your Windows 10/11 DSH profile, then start a new session.
|
|
18
|
+
2. Open the target application and describe the app, goal and allowed scope in the conversation.
|
|
19
|
+
3. Approve the session application access when prompted; inspect the window or controls before clicking and typing.
|
|
20
|
+
4. Review approval details for sensitive actions; re-observe after failures or uncertain results instead of submitting twice.
|
|
21
|
+
5. Check the result in the application. Cancel the task to stop its native helper when needed.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
Requires Windows 10/11, Node.js 22.19+ (22.x) or 24+, and DSH 0.2.1-rc.3 or newer. In Desktop, install the package below from the native Plugins panel. For Web:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
dsh plugin --profile web add deepseek-computer-use
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Restart the host after installation. This package operates the Windows computer running DSH; a remote browser does not move execution to the viewer's computer.
|
|
32
|
+
|
|
33
|
+
## Use
|
|
34
|
+
|
|
35
|
+
Start a task that needs a desktop app. Observe the window and controls before acting, and grant access to the intended app for the session. The 16 tools cover window discovery, screenshots, mouse and keyboard, UI Automation controls and optional system audio recording.
|
|
36
|
+
|
|
37
|
+
The native helper uses Windows UI Automation, SendInput and Windows.Graphics.Capture. Cancellation or the end of a turn stops its helper; failed actions require a fresh observation before retrying. Approval-required operations refuse when the host cannot ask. This is not an operating-system sandbox for untrusted applications.
|
|
38
|
+
|
|
39
|
+
## Updates
|
|
40
|
+
|
|
41
|
+
Version controls are at the bottom of native plugin details. Automatic checks are on; automatic installation is off by default. Installation, deferral and update preferences remain user choices. The plugin does not force a DSH restart.
|
|
42
|
+
|
|
43
|
+
## Documentation and feedback
|
|
44
|
+
|
|
45
|
+
See the [Chinese guide](../README.md) for the complete tool list, configuration, native payload requirements and platform limitations, and the [changelog](../CHANGELOG.md) for releases.
|
|
46
|
+
|
|
47
|
+
Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/deepseek-computer-use/issues) or submit [pull requests](https://github.com/STARDUSTLC666/deepseek-computer-use/pulls). Include versions, expected and actual behavior, and redact private screenshots or credentials.
|
|
48
|
+
|
|
49
|
+
## License
|
|
50
|
+
|
|
51
|
+
[MIT](../LICENSE).
|