# DSH Computer MCP

让 DeepSeek Harness 通过 MCP 操作另一台电脑上的文件，并按需执行命令。

Harness 可以运行在服务器、NAS 或另一台电脑上。目标电脑运行连接器，选择允许访问的目录后，Harness 即可通过内网或 Tailscale 读写文件、搜索内容、移动文件和执行开发任务。连接器使用标准 Streamable HTTP MCP 协议，通过官方 MCP 客户端接入 Harness。

目标电脑无需安装 Node.js、Python 或完整 Harness；执行命令需要的 Git、编译器等工具仍需自行安装。

## 主要功能

- **远程文件操作**：浏览目录、按名查找、分段读取、片段编辑、整体写入、移动与重命名。
- **可恢复删除**：将普通文件移入系统废纸篓或回收站，提醒用户确认后自行清空。
- **按需执行命令**：默认关闭，开启后返回命令输出、退出码和超时状态。
- **目录授权**：支持多个目录，文件工具拒绝越界路径和子路径符号链接。
- **本地配置页**：启动后自动打开，查看通信状态、当前权限和日志位置。
- **每日日志**：记录连接、工具操作、执行结果及错误，便于排查问题。
- **跨平台连接**：支持 Windows、Intel Mac 和 Apple Silicon Mac，通过内网 IP 或 Tailscale 连接。

## 支持平台

| 发布包 | 系统 |
|---|---|
| `windows-amd64` | Windows 10/11，64 位 Intel/AMD |
| `macos-amd64` | Intel Mac，macOS 10.15 及以上 |
| `macos-arm64` | Apple Silicon Mac，macOS 11 及以上 |

另提供 Linux amd64 程序和源码。Windows ARM 和 32 位 Windows 暂不支持。Windows 与 macOS 10.15 的完整行为仍待实机验证。

## 快速开始

### 1. 在要操作的电脑上运行连接器

1. 从本仓库的 Releases 页面下载对应系统的 ZIP，解压到固定目录。
2. Windows 运行 `启动.cmd`；Mac 运行 `启动.command`，或在终端运行 `./dsh-computer-mcp`。
3. 程序默认打开本地配置页。未打开时，复制终端显示的完整配置页地址到浏览器；保留地址中 `#` 后的管理令牌。
4. 选择允许访问的目录并保存，可以添加多个目录。
5. 如需执行命令，开启“允许 AI 在此电脑执行命令”；默认关闭。
6. 根据网络选择内网或 Tailscale 地址，复制连接配置，或下载配对文件。

保持程序运行。关闭程序或电脑休眠后，Harness 将无法访问这台电脑。按 `Ctrl+C` 退出。当前不提供开机自启、后台服务安装或设备自动发现。

Mac 程序使用 ad-hoc 签名，未经过 Apple 公证；Windows 程序未使用商业代码签名，首次启动可能出现系统提示。

### 2. 安装 DSH 插件并配置 MCP

本仓库同时提供可安装的 DeepSeek Harness Profile Bundle（`dsh-plugin`）。电脑端程序运行在要操作的电脑上，配置型 bundle 安装在运行 Harness 的环境中；安装插件不会自动安装或启动电脑端程序。

已验证的组合为 Node.js 24 和 DSH `0.2.0-rc.2`，使用 DSH 自带的官方 `@deepseek-ai/dsh-mcp-client`。在已安装 `dsh` 命令的环境中执行：

```sh
dsh plugin --profile web add github:cander0815/dsh-computer-mcp
```

这是 GitHub 源码安装，当前未发布同名 npm 注册表包。该 bundle 不含 `prepare` 或其他安装时构建脚本，不需要授权构建。若使用不同 profile，请将 `web` 换为实际 profile 名称。

随后将电脑配置页下载的配对文件中的 `url` 和 `token` 设置为 Harness 进程的环境变量。以下为 POSIX Shell 示例，只使用占位符：

```sh
export DSH_COMPUTER_MCP_URL='http://<目标电脑地址>:18790/mcp'
export DSH_COMPUTER_MCP_TOKEN='<连接令牌>'
dsh --profile web
```

Windows PowerShell 示例：

```powershell
$env:DSH_COMPUTER_MCP_URL = 'http://<目标电脑地址>:18790/mcp'
$env:DSH_COMPUTER_MCP_TOKEN = '<连接令牌>'
dsh --profile web
```

两个变量未完整填写时插件保持禁用，不尝试连接。必须设置在 **Harness 进程的启动环境**中，不要放进项目 `.env` 文件。后台服务或容器部署需将环境变量写入相应的私有启动配置，并安装到同一个持久 profile。令牌不要提交到公共仓库或发在投稿内容中。

如果此前已手工加载配置页生成的 `local-computer` patch，请先停用旧 patch，再使用 bundle，避免重复注册相同服务器名称。也可以继续使用原有手工 patch 接入方式；两种方式选一种即可。

修改配置或升级后，让 Harness 重新连接 MCP，刷新工具列表；必要时重启相应的 Harness 实例。

### 3. 告诉 AI 使用目标电脑的工具

可以在新会话中这样说明：

> 请使用 localcomputer MCP 操作连接的电脑。先调用 list_roots，确认设备、授权目录和当前权限，再使用对应的文件或命令工具。不要用 Harness 自带的服务器工具代替；找不到 MCP 工具时请明确告诉我。

Harness 原有工作区选择器仍显示 Harness 所在环境的目录。目标电脑文件通过 MCP 工具访问，不会自动出现在原工作区选择器中。

## MCP 工具

- list_roots：授权目录和 id。
- list_directory：目录清单，最多 1000 项。
- find_files：按文件名通配符查找文件（如 *.go），最多返回 200 个，路径相对授权目录。只匹配文件名，不支持 {a,b} 和含 / 的模式，会直接报错而不是返回空结果。
- read_file：UTF-8 文本和整个文件的 SHA-256，最大 1 MiB；可用 offset、limit 按行分段读取。
- edit_file：把文件中唯一出现的一段原文替换为新内容，改一处不必重写整个文件；原文找不到或出现多次都会拒绝。Windows 的 CRLF 文件可用 \n 原文匹配，换行风格保持不变。
- write_file：新建或整体重写；覆盖必须提供最近读取的哈希，新建使用 new。缺少的上级目录自动创建。
- create_directory：创建目录，缺少的上级目录一并创建。
- move_file：在同一授权目录内移动或重命名文件、文件夹；目标已存在时拒绝，不覆盖。
- delete_file：把授权目录内的一个普通文件移入系统废纸篓/回收站，不支持目录或永久删除；成功后提醒用户确认不再需要，再自行清空。
- search_text：默认原样搜索，可选正则（regex）和文件名过滤（include）；最多读取 1000 个文本文件、返回 100 结果，结果路径相对授权目录。跳过 .git、node_modules、.venv、venv、__pycache__、dist、target、.next，实际跳过的目录会列在结果的 skipped_dirs 中，把 path 指进这些目录时仍会搜索。find_files 同样跳过这些目录。
- run_command：开启后才提供，程序和参数数组直接执行，不自动解析 Shell。默认 30 秒，最多 120 秒，输出最多 64 KiB。

文件工具拒绝越界和子路径符号链接，删除仅移入系统废纸篓/回收站。二进制、GBK 文本和大文件需要另行处理。命令使用当前电脑用户的系统权限，工作目录限制不等于操作系统沙箱；文件系统限制也不能抵御同用户的恶意进程竞争。

仅用于短任务，不托管后台服务。macOS/Linux 会清理命令进程组；Windows 超时用 taskkill 尽力清理进程树，脱离父进程的后台任务可能继续运行。旧版 Windows 非 UTF-8 命令输出可能需要设置编码。

不提供桌面鼠标键盘、远程浏览器或屏幕控制。文件保存在电脑上，但 AI 读取的内容会发送到服务器和所选模型。

## 日志与通信状态

操作日志默认保存在程序和启动脚本同目录，每天一个文件，名称为 `YYYY-MM-DD.log`。每条 JSON 记录包含本机时间（精确到秒）、工具名称、目录与路径、成功或失败；命令日志还包含参数、输出、退出码和超时状态。

文件读写日志不记录文件正文，也不记录连接令牌。命令输出和 Shell 字符串可能包含敏感内容，日志应保存在本机，不要上传公共仓库。

配置页每三秒更新通信状态，显示最近通信时间、客户端、进行中的请求、当前权限和日志位置。绿色表示近期有通信或正在操作；超过 90 秒无通信显示空闲。由于 MCP 不依赖持续心跳，空闲不等于断线。

## 权限与管理员模式

Mac 提供两种启动脚本：

- `启动.command`：以普通用户权限运行。
- `启动-sudo.command`：在本机终端输入系统密码，以管理员权限运行。

先关闭正在运行的连接器，再切换启动方式。两种方式共用原用户配置与连接令牌，无需重新配对。编辑文件保留原所有者，新建文件和目录继承父目录所有者。

MCP 向模型说明当前权限；权限不足时，模型应提示用户在本机切换启动方式，不能自行提权或索取系统密码。sudo 不会自动绕过 macOS 隐私权限或系统完整性保护。

Windows 权限取决于启动程序的用户，当前不提供独立管理员启动脚本。

## 文件回收

`delete_file` 仅接受授权目录内的普通文件，也可用于普通二进制文件；不删除文件夹，不提供永久删除或自动清空功能。

成功后，工具要求模型提醒用户：确认不再需要，再自行清空废纸篓或回收站以释放空间；清空前可尝试恢复。回收失败时，不应改用 `rm`、`Remove-Item` 等永久删除命令作为替代。

Mac 使用系统废纸篓，sudo 模式仍使用原用户的废纸篓。Windows 需要 PowerShell 和本地固定磁盘上的可用回收站；回收前保留保护副本，系统未确认回收时尝试恢复。意外退出或清理失败可能留下 `.dsh-trash-recovery-*` 文件，请检查原文件与回收站后处理。此过程需要额外磁盘空间。Linux 需要 `gio` 和可用的系统回收站。

## 网络与配置

默认 MCP 端口为 `18790`，本地配置页端口为 `18791`。Harness 所在环境必须能访问目标电脑的 MCP 端口；防火墙、路由器客户端隔离和网络路由可能影响连接。使用 Tailscale 时，两端必须在线并允许互访。

HTTP 仅适用于可信内网；跨网络可通过 Tailscale 建立加密链路。不要将 MCP 工具端口直接映射到公网。

默认配置位置：

| 系统 | 配置文件 |
|---|---|
| macOS | `~/Library/Application Support/DSHComputerAgent/config.json` |
| Windows | `%APPDATA%/DSHComputerAgent/config.json` |
| Linux | `~/.config/DSHComputerAgent/config.json` |

配置保存设备名称、授权目录、命令开关和连接令牌。移走配置后重新启动会生成新令牌，需要重新配对。

可用参数：

| 参数 | 用途 |
|---|---|
| `-config <路径>` | 指定独立配置文件 |
| `-listen <监听地址>` | 指定 MCP 监听地址与端口 |
| `-admin <本机监听地址>` | 指定本地配置页地址，必须使用本机回环地址 |
| `-log-dir <目录>` | 指定日志目录 |
| `-no-browser` | 禁用自动打开配置页 |

在同一台电脑运行多个独立连接器时，应使用不同配置文件、连接令牌、MCP 端口和管理端口。

## 构建与验证

Go 程序无第三方 Go 依赖。当前兼容构建使用 Go 1.22.12；该工具链已停止官方维护，此版本面向可信网络内的预览使用。

```sh
go test -race -ldflags=-linkmode=external ./...
go vet ./...
GO_BIN=/path/to/go1.22.12/bin/go sh build.sh
python3 package-release.py
```

`build.sh` 在 macOS 运行，构建各平台程序，并为 Mac 产物补齐 Mach-O UUID、标注最低系统版本与重新签名。`package-release.py` 生成 ZIP、启动脚本和 SHA256 校验文件。

测试范围和已知限制见 [VERIFICATION.md](VERIFICATION.md)。

## 开源许可证

本项目使用 [MIT License](LICENSE)。