# dsh-workmate 桌面版安装教程（DeepSeek Harness Desktop）

> 适用：**DeepSeek Harness 桌面版（Windows x64）**——即从官方 `.exe` 安装程序装出来的那个 Electron 应用。
> 如果你是从源码跑 `pnpm dsh web`，请改看 [README 的安装章节](./README.md#安装)。

桌面版**不需要**你自己装 Node、pnpm，也**不需要**任何源码目录：安装包里已经带了 Node 运行时、pnpm 和 `dsh` CLI，插件用官方机制装进桌面版自己的 profile 即可，**不改任何 DSH 源码，不需要重新构建前端**。

---

## 0. 一句话流程

```
启动桌面版一次（初始化 profile） → 完全退出 → 注册 dsh 命令 → dsh plugin add → 重新打开桌面版
```

全程约 1 分钟。

---

## 1. 前置确认

- 桌面版已能正常启动，并且**至少启动过一次**——首次启动会创建保留 profile 目录 `%USERPROFILE%\.dsh\profiles\desktop`。没启动过就直接跑安装命令会报：
  `Open DeepSeek Harness Desktop once to initialize its profile, then fully quit it before running dsh plugin --profile desktop.`
- **完全退出桌面版**（见下面的说明），避免安装时和正在运行的实例抢 profile 的文件锁。
- 打开一个**终端**（Windows Terminal / PowerShell 均可）。

### 关窗口 ≠ 退出

桌面版关掉窗口后默认**继续在系统托盘运行**（正在跑的任务不会中断）。要真正退出，二选一：

- 标题栏菜单 **应用 → 退出 DeepSeek Harness**；
- 或右键**系统托盘图标 → 退出**。

> 有任务在运行时会弹确认框，按提示确认即可。

### 找到桌面版安装目录

后面要用到 `<安装目录>\resources\runtime\cli\bin\dsh.cmd`。安装时若没改路径，一般是 `%LOCALAPPDATA%\Programs\DeepSeek Harness`；不确定就跑：

```powershell
(Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*' |
  Where-Object DisplayName -like '*DeepSeek Harness*').InstallLocation
```

也可以直接：桌面快捷方式 → 右键 → **打开文件所在的位置**。

---

## 2. 让 `dsh` 命令可用（二选一）

### 方式 A：用桌面版自带的菜单注册（推荐）

桌面版窗口**左上角标题栏**有一排原生菜单（「应用」「编辑」）：

**应用 → 管理 dsh 命令…**

- 若显示「将 Desktop 命令添加到终端」→ 点 **安装**；
- 它做的是：把 `<安装目录>\resources\runtime\cli\bin` 写进**当前用户 PATH**，让终端里的 `dsh` 指向桌面版自带的 CLI；
- 官方行为说明：**现有命令会被保留**，不会改动你已有的其他 `dsh` 安装或 shell 启动文件；
- 完成后按提示**打开一个新终端**，运行：

```powershell
dsh --version
```

> 已经开着的终端读不到新的 PATH，必须**新开**一个。

### 方式 B：不改 PATH，直接用完整路径

```powershell
& "E:\app\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" --version
```

把路径换成你自己的安装目录即可。下面所有 `dsh ...` 命令都可以等价替换成这种写法。

---

## 3. 安装插件

```powershell
dsh plugin --profile desktop add github:halosb/dsh-workmate
```

两个关键点，弄错就不会生效：

| 要点 | 说明 |
|---|---|
| **必须用 `--profile desktop`** | 桌面版跑的是保留 profile `desktop`。`--profile web` 是 `dsh web`（浏览器/源码版）那套 profile，装进去在桌面版里**不会**加载 |
| **不要加 `pnpm` 前缀** | 源码环境下才写 `pnpm dsh plugin ...`；桌面版的 pnpm 由安装包提供，直接用 `dsh` 即可 |

命令做了三件事：

1. 在 `%USERPROFILE%\.dsh\profiles\desktop` 目录里执行 `pnpm add`，把插件包装进**该 profile 自己的** `node_modules`；
2. 因为这个包声明了 `dsh.bundle`，自动把 `dsh-workmate` 追加进 profile `package.json` 的 `dsh.profile.bundles` 列表；
3. 该 bundle 自带的 `cordis.patch.yml` 会在启动时插入一行 `id: workmate / name: dsh-workmate`。

装完输出大致是：

```
dependencies:
+ dsh-workmate github:halosb/dsh-workmate
Done in 5.6s using pnpm v11.7.0
```

### 从本地目录安装（可选，适合自己改代码调试）

```powershell
dsh plugin --profile desktop add D:\path\to\dsh-workmate
```

### 验证确实装进去了

```powershell
dsh plugin --profile desktop list --depth 0
```

应看到 `dsh-workmate <版本>`。再看一眼 profile 配置：

```powershell
Get-Content "$env:USERPROFILE\.dsh\profiles\desktop\package.json"
```

`dependencies` 和 `dsh.profile.bundles` 里都应出现 `dsh-workmate`。

> ⚠️ **桌面版不能用 `--dump-config` 验证**。`dsh --profile desktop --dump-config` 会被直接拒绝：
>
> ```
> error: profile "desktop" is managed exclusively by the Electron application
> ```
>
> 这是设计如此——`desktop` 是桌面版的保留 profile，**只有桌面版自带的 CLI** 才对它开放 `plugin` 子命令，其他 `dsh` 一律拒绝。所以请用上面的 `list` + 读 `package.json` 来验证。

> `%USERPROFILE%\.dsh` 是默认位置；若你设过 `DSH_HOME` 环境变量，profile 目录以 `DSH_HOME\profiles\desktop` 为准。

---

## 4. 重启桌面版（关键一步，别跳过）

插件分两半：

- **host 半边**（`index.js`）：负责监听 Agent 状态计时、知识库索引与检索、注册 `kb_search` / `web_capture` / `kb_recent` 模型工具。这部分由 loader 动态挂载，安装后很快就能用；
- **浏览器半边**（`client.js`）：设置页 UI。它由 `dsh-client-modules` 在**启动时**扫描包、把 `/plugins/dsh-workmate/client.js` 编进 `window.__DSH_BOOT__` 引导图，所以**必须重启才会出现**。

**完全退出桌面版（连托盘图标一起退）→ 重新打开。**

---

## 5. 验证安装成功

1. 打开 **设置 → 工作搭档**，能看到两个分区：「任务通知」和「私有知识库」。
2. 在任意会话里让 Agent 用一下知识库工具，例如问它：
   > 用 kb_recent 列出最近捕获的网页
   它应该能调用到 `kb_recent` 工具（知识库为空时会正常返回"还没有捕获的内容"，说明工具已注册）。
3. 任务通知：随便跑一个超过阈值（默认 60 秒）的任务，结束后应弹 Windows Toast / 播提示音。

---

## 6. 快速上手

打开 **设置 → 工作搭档** 全部可视化配置：

**任务通知**：启用开关 / 时长阈值（默认 60 秒）/ 系统通知 / Webhook URL / 失败通知 / 仅后台通知 / 音效反馈。

**私有知识库**：填「索引目录」→ 点「重新索引」即启用。之后：

| 工具 | 用途 |
|---|---|
| `kb_search(query)` | 检索本地文档，返回文件 / 片段 / 分数 |
| `web_capture(url)` | 抓一个网页正文入库 |
| `kb_recent(limit?)` | 直接列出最近捕获的网页（不必盲搜） |
| `kb_forget(target)` | 删除某条网页捕获（存错了不必重建整个索引） |

出厂默认：通知开、阈值 60s、Toast 开、仅后台开、音效开；知识库未配置。

数据文件（首次保存后生成，**在 DSH 数据目录里，不在插件目录**，更新插件不会丢）：

```
%USERPROFILE%\.dsh\plugin-data\desktop\dsh-workmate\config.json    # 你的设置
%USERPROFILE%\.dsh\plugin-data\desktop\dsh-workmate\kb-index.json  # 知识库索引
```

> 0.3.0 起从插件目录（`…\node_modules\dsh-workmate\`）迁到这里：那个目录由 pnpm 管理，
> 一次 `dsh plugin update` 就会把它重建，老版本的设置和整个知识库会一起消失。
> 首次启动会自动把老文件搬过来，无需手动操作。
> 若你设过 `DSH_HOME`，把 `%USERPROFILE%\.dsh` 换成 `%DSH_HOME%`。

> 详细配置说明见 [`使用与配置文档.md`](./使用与配置文档.md)。

---

## 7. 更新与卸载

**更新到最新版**：

```powershell
dsh plugin --profile desktop update dsh-workmate
```

然后重启桌面版。

**卸载**：

```powershell
dsh plugin --profile desktop remove dsh-workmate
```

然后重启桌面版。该命令会移除依赖和对应的组合层；你的设置与知识库在 DSH 数据目录（`…\.dsh\plugin-data\desktop\dsh-workmate\`），**不会被卸载删掉**，要彻底还原就手动删除该目录。

---

## 8. 排障

| 现象 | 原因 / 处理 |
|---|---|
| `设置` 里没有「工作搭档」 | 没重启桌面版。客户端引导图只在启动时组装——**完全退出（含托盘）**再打开 |
| `error: profile "desktop" is managed exclusively by the Electron application` | 你调用的不是桌面版自带的 `dsh`（PATH 上另一个 `dsh` 优先）。用第 2 节的**方式 B**完整路径调用，或用「应用 → 管理 dsh 命令…」修复注册 |
| `Open DeepSeek Harness Desktop once to initialize its profile…` | 桌面版从没启动过。先启动一次，再完全退出，然后重跑安装命令 |
| `error: required option '--profile <name>' not specified` | `--profile desktop` 是 `plugin` 子命令的必需参数：`dsh plugin --profile desktop add …`（`--profile` 放在 `plugin` **后面**） |
| 新终端里 `dsh` 还是旧命令 / 不是桌面版 | ① PATH 变更对**已开着**的终端无效，新开一个；② 装了多个 `dsh` 时优先级问题，应用会提示「另一个 dsh 的优先级更高。请移除或调整该安装的顺序…」——也可以直接用完整路径 |
| 安装命令卡住不动 | 桌面版正在运行时会持有 profile 的文件锁，`dsh plugin` 最多等 120 秒。完全退出桌面版后重跑 |
| 报 pnpm 阻止了构建脚本（`allowBuilds` / `prepare`） | 本插件是纯 JS、无构建步骤，正常不会触发。若确实被拦，按命令打印的提示把对应键加进 `%USERPROFILE%\.dsh\profiles\desktop\pnpm-workspace.yaml` 的 `allowBuilds`，再重跑 |
| 收不到 Windows 通知 | 系统设置 → 系统 → 通知里允许桌面版 / PowerShell 通知；并确认设置里「系统通知」开着、「仅后台通知」时浏览器窗口需要不在前台 |
| Webhook 没动静 | 用设置页里的测试或自行 `Invoke-RestMethod` 验证 URL 可达；请求体格式见 [README](./README.md#webhook-请求体) |

---

## 附：桌面版 vs 源码版对照

| | 桌面版（Windows） | 源码版 / `dsh web` |
|---|---|---|
| profile | `desktop`（保留，仅桌面版 CLI 可管理） | `web` |
| 命令前缀 | `dsh` | `dsh` 或 `pnpm dsh` |
| Node / pnpm | 安装包自带，无需自备 | 需自备 Node ≥ 22 + pnpm |
| 配置文件 | `%USERPROFILE%\.dsh\profiles\desktop\package.json` | `%USERPROFILE%\.dsh\profiles\web\package.json` |
| 生效方式 | 重启桌面版（完全退出，含托盘） | 重启 `dsh web` |
| 配置校验 | `dsh plugin --profile desktop list`（**不支持** `--dump-config`） | `pnpm dsh --profile web --dump-config` |

---

## 反馈

- 📮 **反馈邮箱**：i@halosb.com
- 作者：芝麻 (halosb)

## 许可证

[MIT](./LICENSE)