dsh-computer-use

Readme

# dsh-computer-use · 让 DeepSeek Harness 学会操作电脑

> **DSH computer_use plugin** — give your DeepSeek Harness (text-only LLM) real desktop control: screenshot / screen-record → Xiaomi MIMO vision analysis → mouse / keyboard / window / program control → autonomous loop until the task is done.

![Version](https://img.shields.io/badge/version-3.0.0-blue) ![Platform](https://img.shields.io/badge/platform-Windows%2010%2F11-lightgrey) ![Framework](https://img.shields.io/badge/framework-web_ui%20family-8A2BE2) ![Vision](https://img.shields.io/badge/vision-Xiaomi%20MIMO-orange)

> [!IMPORTANT]
> **安装本插件前，必须先安装 [@linxin666/dsh-web-ui-all](https://www.npmjs.com/package/@linxin666/dsh-web-ui-all)（dsh-web-ui 全家桶）**，本插件基于其 `defineTool` / `installSettingsSection` / `systemPrompt.section` 框架能力开发，缺少全家桶将无法加载。

纯文本模型通过「**截屏/录屏 → 视觉模型看屏幕 → 真实键鼠操作**」的闭环，获得真实的电脑操作能力：打开程序、点击界面、输入文字、拖拽滚动、操作微信，甚至**自主循环**完成一个完整任务。

## ✨ 特性

- 🖥️ **真实桌面控制** —— 不是模拟器，直接操作你的 Windows 桌面：鼠标、键盘、窗口、进程
- 👁️ **多模态视觉** —— 基于 Xiaomi MIMO 视觉模型（OpenAI 兼容端点）理解屏幕内容与元素坐标，让纯文本模型"看得见"
- 📹 **截屏 + 录屏双观察** —— 静态场景（看页面布局）用 `computer_screenshot`；动态场景（滚动、滑动、动画、加载，如微信下滑找朋友圈）用 `computer_record` 录屏抽帧一次看清，避免反复截屏浪费时间
- 🧹 **临时文件自动清理** —— 截屏分析完、录屏分析完、`computer_use` 循环结束时，自动删除过程中产生的临时截图与录屏帧，不留垃圾文件
- 🔁 **自主循环** —— `computer_use` 工具：给定任务描述，自动执行「观察（截屏或录屏）→ 视觉决策 → 操作 → 再看」直到完成，观察方式由 MIMO 按场景自动选择
- 🧩 **web_ui 家族框架** —— 与 `@linxin666/dsh-web-ui` 全家桶完全一致：`defineTool` + `installSettingsSection` + `systemPrompt.section` + `mountOnce` 单实例守卫
- 📦 **零依赖自包含** —— C# 助手源码**内嵌在 index.js 里**，首次使用自动写入工作区并用系统自带的 csc.exe 编译，无需安装任何运行时
- 🔐 **密钥不落盘** —— MIMO API Key 只从环境变量读取，绝不写入插件文件

## 🧠 工作原理

```
┌─────────────┐    computer_screenshot /     ┌──────────────────┐
│  你的 DSH    │    computer_record (录屏抽帧)  │  Windows 桌面观察  │
│  (纯文本模型) │ ───────────────────────────▶ │  截屏 PNG / 录屏帧 │
└──────┬──────┘                              └────────┬─────────┘
       │                                           │ 分析（单帧/多帧）
       │  computer_action / computer_use            ▼
       │  (真实鼠标/键盘/窗口/进程)          ┌──────────────────┐
       │                                   │  Xiaomi MIMO 视觉  │
       │                                   │  模型 (OpenAI 兼容) │
       └─────────────────────────────────── │  描述屏幕+坐标      │
          C# 助手 exe（内嵌源码自动编译）      └──────────────────┘
```

**computer_use 自主循环（观察方式自适应）：**

```
任务描述 ─▶ [截屏(静态)/录屏(动态)] ─▶ [MIMO 分析] ─▶ [决策下一步操作] ─▶ [执行]
                                      ▲                                     │
                                      └──────── 未完成，继续（自动清理临时文件）┘
```

## 📁 文件结构

```
dsh-computer-use/
├── index.js          插件本体（ESM，静态注册到宿主；含内嵌 C# 助手源码，自包含）
├── helper.cs         C# 助手源码副本（仅作参考；index.js 已内嵌，不是运行必需）
├── package.json      包元数据（dsh.bundle.patch → cordis.patch.yml）
├── cordis.patch.yml  安装用 patch 片段（参考，实际手工追加到 profile 的 cordis.patch.yml）
└── README.md
```

## 📦 安装

### 前置条件

| 依赖 | 说明 |
|---|---|
| **DSH（DeepSeek Harness）** | web 版本，运行于 Windows |
| **@linxin666/dsh-web-ui-all（web_ui 全家桶）** | 提供 `defineTool` / `installSettingsSection` 等框架能力，**必须先安装** |
| **Windows 10/11** | C# 助手依赖系统 .NET Framework（自带）与 Win32 API |
| **MIMO API Key**（可选但强烈推荐） | 视觉分析用，见下方「配置视觉」 |

### 步骤

1. 将 `dsh-computer-use/` 整个文件夹复制到 profile 的 `plugins/` 目录下：

   ```
   C:\Users\<你的用户名>\.dsh\profiles\web\plugins\dsh-computer-use\
   ```

2. 打开 profile 的补丁文件 `C:\Users\<你的用户名>\.dsh\profiles\web\cordis.patch.yml`，在 `plugins:` 列表末尾追加：

   ```yaml
   - insert:
       - id: computer-use
         name: './plugins/dsh-computer-use/index.js'
   ```

3. **重启 DSH** —— 静态插件在启动时加载，无需审批。

4. 验证：向模型发送「查看电脑操作插件状态」，应得到助手就绪信息。

### 配置视觉（MIMO）

设置 Windows 环境变量（用户级即可）：

```
MIMO_API_KEY = sk-你的密钥
```

插件每 30 秒自动重新探测密钥；没有密钥时截图类工具仍可用，只是 `analyze` 与 `computer_use` 的视觉决策不可用。

## ⚙️ 配置项

可在 DSH 设置界面的「dsh-computer-use」分区（settings card）调整：

| 配置 | 默认值 | 说明 |
|---|---|---|
| `baseURL` | `https://api.xiaomimimo.com/v1` | MIMO（OpenAI 兼容）端点 |
| `model` | 空（自动选择） | 视觉模型 id，如 `mimo-v2.5` |
| `apiKeyEnv` | `MIMO_API_KEY` | 读取密钥的环境变量名 |
| `maxOutputTokens` | `4096` | 视觉响应最大 token |
| `timeoutMs` | `120000` | 视觉请求超时 |
| `helperExe` | 空（自动编译） | 指定已编译的助手 exe 路径，跳过编译 |
| `enabled` | `true` | 总开关 |
| `announceToAgent` | `true` | 启动时向 agent 宣告本插件能力 |

## 🛠️ 工具参考

| 工具 | 作用 |
|---|---|
| `computer_status` | 查看助手与 MIMO 状态、统计、最近错误 |
| `computer_screenshot` | 截屏保存 PNG；`analyze=true` 时让 MIMO 分析屏幕内容与坐标；**静态场景（看页面布局）用这个**；可传 `model` 指定视觉模型 |
| `computer_record` | 录屏抽帧（JPEG），把整段时间的多帧画面一次交给 MIMO 观察动态过程（滚动/滑动/动画/加载）；**动态场景（微信下滑找朋友圈等）用这个，一次看清避免反复截屏**；可传 `model` 指定视觉模型 |
| `computer_action` | 单步执行一次真实桌面操作 |
| `computer_use` | 自主循环执行任务（观察 → 视觉决策 → 执行 → 再看）直到完成，观察方式由 MIMO 自动选择（静态截屏 / 动态录屏）；循环结束自动清理临时文件；可传 `model` 与 `observe` |

### 截屏 vs 录屏：什么时候用哪个？

| 场景 | 工具 | 为什么 |
|---|---|---|
| 看页面布局、确认当前界面、等待某个元素出现 | `computer_screenshot(analyze=true)` | 一帧静态图足够，快 |
| 滚动列表、滑动屏幕、动画/加载过程（如微信里下滑找朋友圈） | `computer_record(seconds=4, fps=2)` | 录 4 秒抽 8 帧一次看清动态，避免每滚一格截一次屏 |
| 复杂任务自动执行 | `computer_use(observe="auto")` | MIMO 按场景自动决定每步用截屏还是录屏 |

### computer_use / computer_screenshot / computer_record 的 model 参数

三个工具的视觉调用都支持 `model` 参数，**每次调用可指定不同的视觉模型**（如 `mimo-v2.5`、`mimo-v2.5-pro`），不传则回退到设置区 `model` 或自动选中的模型：

```
computer_screenshot(analyze=true, model="mimo-v2.5-pro")
computer_record(seconds=4, fps=2, model="mimo-v2.5")
computer_use(task="打开 PyCharm 创建 test.py", model="mimo-v2.5")
```

### computer_use 的 observe 参数

`computer_use` 支持 `observe` 控制观察方式：

- `auto`（默认）：每步由 MIMO 决定——静态界面用截屏，需要观察动态过程时输出 `next_observe: "record"` 切换录屏
- `screenshot`：强制每步截屏
- `record`：强制每步录屏

```
computer_use(task="在微信里下滑找到三天前的朋友圈并截图", observe="auto")
```

### computer_action 支持的操作

| action | 参数 | 说明 |
|---|---|---|
| `move` | `x, y` | 移动鼠标到坐标 |
| `click` | `button`(left/right/middle/double), `x, y` | 点击 |
| `drag` | `x1, y1, x2, y2` | 从 (x1,y1) 拖到 (x2,y2) |
| `scroll` | `dy`（正=向下） | 滚轮滚动 |
| `type` | `text` | 输入文本（剪贴板 + Ctrl+V） |
| `keys` | `keys` | 按键串（SendKeys 语法，见下） |
| `run` | `command` | 启动程序/命令（可带参数） |
| `activate` | `process`, `title`(可选) | 激活窗口到前台 |
| `windowrect` | `process`, `title`(可选) | 获取窗口矩形 |
| `listwindows` | — | 列出可见窗口 |
| `sendchat` | `text` | 向微信当前聊天发送消息 |

**keys 语法示例：**

```
{LWIN}{UP}       Win+↑ 最大化窗口
^{a}             Ctrl+A 全选
{ENTER}          Enter
{TAB}            Tab
{F5}             F5 刷新
{F1}-{F24}       功能键
```

## 💡 使用示例

> 「打开记事本，输入 Hello, DSH! 并保存」

1. `computer_action(action="run", command="notepad")`
2. `computer_screenshot(analyze=true)` —— 确认记事本已打开
3. `computer_action(action="type", text="Hello, DSH!")`
4. `computer_action(action="keys", keys="^{s}")` —— Ctrl+S 保存

> 「在微信里给当前聊天发送『今晚八点开会』」

1. `computer_action(action="sendchat", text="今晚八点开会")`

> 「打开 PyCharm，在项目里创建一个 test.py」—— 直接交给 `computer_use`：

```
computer_use(task="打开 PyCharm，在打开的文件夹下创建 test.py，内容为 print('hi')")
```

## 🧩 技术细节

- **C# 助手自动编译**：首次调用时，index.js 内嵌的 C# 源码写入工作区 `.ds_computeruse_helper_v9.cs`，调用系统 `csc.exe`（`C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe`）编译为 `.ds_computeruse_helper_v9.exe`，之后直接复用；也可在设置里指定 `helperExe` 跳过编译
- **截图位置**：临时写入工作区 `.dsh_computeruse_shot_*.png` / `.dsh_computeruse_loop_*.png`，分析完即删（`keep=true` 可保留）
- **录屏帧**：临时写入工作区 `.dsh_computeruse_record_*/frame_*.jpg`，分析完整目录删除（`keep=true` 可保留）
- **临时文件**：视觉请求体临时写入工作区 `.dsh_computeruse_req.json`（用后即弃）
- **密钥探测顺序**：启动环境变量 → PowerShell 分层探测（User → Machine → Process），每 30 秒重试
- **sendchat 定位**：按微信窗口宽度 62%、底边上方 55px 估算输入框位置

## ❓ 常见问题

**Q：工具报错 `unknown cmd: [object object]`？**
A：这是 v1 的 bug，已修复。请确认运行的是 v2 版本（本仓库 2.0.0）。

**Q：C# 编译失败？**
A：插件需要系统 .NET Framework 4.x 的 csc.exe（Win10/11 自带）。确认 `C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe` 存在。也可手动编译后通过 `helperExe` 配置指定。

**Q：`analyze` 报错说没密钥？**
A：设置环境变量 `MIMO_API_KEY` 后等 30 秒（插件自动重试探测），或重启 DSH。

**Q：坐标不准？**
A：视觉模型给出的坐标是估算值。复杂界面建议小步操作：先截图分析，再小范围移动点击，逐步逼近。

## 🗑️ 卸载

1. 删除 `cordis.patch.yml` 中 `- insert:` 的 `computer-use` 三行
2. 删除 `plugins/dsh-computer-use/` 文件夹
3. 重启 DSH

## ⚠️ 免责声明

- 本插件操作的是**真实桌面**、消耗真实资源，请确认意图后再让模型执行
- 视觉模型坐标可能不准，高风险操作（删除、提交、支付等）请人工确认
- `sendchat` 仅针对微信（Weixin/WeChat 进程）
- 插件在受限沙箱内运行宿主进程，请仅在可信环境使用

## 📜 更新日志

### v3.0.0 (2026-08-22)
- 📹 **新增 `computer_record` 录屏工具**：录制 N 秒屏幕按帧率抽帧为 JPEG，把整段时间的多帧画面一次交给 MIMO 观察动态过程（滚动/滑动/动画/加载），动态场景一次看清，避免反复截屏
- 🧹 **临时文件自动清理**：截屏分析完、录屏分析完、`computer_use` 循环结束时自动删除过程中产生的临时截图与录屏帧（各工具 `keep=true` 可保留）
- 🔁 **`computer_use` 观察方式自适应**：新增 `observe` 参数（auto/screenshot/record），auto 模式下 MIMO 按场景决定每步用截屏（静态）还是录屏（动态，输出 `next_observe:"record"` 切换）
- 🆕 C# 助手升级 v9：新增 `record <outDir> <seconds> <fps> [quality]` 命令

### v2.1.0 (2026-08-18)
- ✨ `computer_use` 的 `model` 参数**真正生效**（此前声明了但未传给视觉调用，实际用全局默认）
- ✨ `computer_screenshot` 新增 `model` 参数，单步视觉分析也可指定模型
- 🔧 现在可随时在调用中切换视觉模型（如 `mimo-v2.5` / `mimo-v2.5-pro`），不传则回退全局默认

### v2.0.0 (2026-08-18)
- 🐛 修复 `helperRun` 参数错位导致的 `unknown cmd: [object object]` 错误
- 🐛 C# 源码从「同目录 helper.cs」改为**内嵌进 index.js**，消除 `import.meta.url` 在 loader 下定位失败导致的编译错误
- 📦 首个公开版本

### v1.0.0 (内部)
- 初始版本：C# 助手 v8、MIMO 视觉、四个工具

## 📄 许可证

[MIT](LICENSE) © JasonWei04