DeepSeek Harness 源码部署笔记

适用对象：想从 GitHub 源码安装、运行、更新、卸载 DeepSeek Harness 的人。
本文只讲源码方式，不讲 npm 包方式。所有命令在 Windows 11 + PowerShell 7 实测通过，Linux/macOS 除注明外命令相同。
版本基准：0.1.0-rc.5（开发者预览版）。

0. 项目是什么

DeepSeek Harness（dsh）是 DeepSeek 开源的 agent harness，MIT 协议。核心特征是"一切皆插件"：运行时基于 vendored 的 Cordis 框架（源码在仓库 vendor/ 目录下），业务能力全部以插件形式挂载。仓库是 pnpm workspaces 单仓（monorepo），CLI 入口在 apps/cli。

当前是开发者预览版，官方明确声明会有破坏性兼容变更。磁盘上的会话/存储格式没有向后兼容承诺，升级后旧格式可能被拒绝（见第 6 节）。

1. 环境要求

依赖	版本	出处
Node.js	^22.19.0 或 >=24.0.0	根 package.json 的 engines 字段
pnpm	11.7.0（仓库锁定）	根 package.json 的 packageManager 字段

安装、构建、启动都不需要 DEEPSEEK_API_KEY。API key 只在 Web UI 里配置后、真正跑任务时才需要。

2. 从 GitHub 拉取源码

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

仓库结构（只列部署相关的）：

vendor/       vendored Cordis 源码（不要动）
packages/     pnpm 工作区包（@deepseek-ai/dsh-*）
apps/cli/     dsh 命令行入口
examples/     可运行的 cordis.yml 示例

3. 安装

3.1 安装 pnpm（未装时）

Windows 上直接走 npm 全局安装：

npm install -g pnpm@11.7.0

不要用 corepack enable：它要往 C:\Program Files\nodejs\ 写 shim，非管理员会报 EPERM（实测）。装完验证：

pnpm -v   # 应输出 11.7.0

3.2 安装依赖

pnpm install

• 实测耗时约 58 秒。
• postinstall 会自动安装 lefthook 的 git hooks（pre-commit 等）。
• Windows 上会出现两条无害警告：Failed to create bin ... dsh-acp-demo / dsh-sdk-jsonrpc-demo，是 demo 包的 bin 链接在 Windows 路径下失败，不影响主程序。

3.3 构建

pnpm run build

等价于两步：

pnpm run build:lib   # tsc 编译 + tsdown 打包 host/client 库
pnpm run build:web   # 前端 dist 构建

实测每步约 5 秒。构建产物在 lib/ 和前端 dist/ 目录。

4. 启动

pnpm dsh web

web 是 --profile web 的别名（pnpm dsh --profile web 等价）。启动后默认监听：

http://127.0.0.1:3080

启动参数（pnpm dsh web --help 可看全量）：

参数	作用
--host <host>	绑定地址，默认 127.0.0.1
--port <port>	端口，默认 3080；传 0 让 OS 随机分配
--trusted-host <authority...>	追加受信任的 API 来源（host 或 host:port，可重复）

注意：--host 0.0.0.0 会被拒绝（源码里硬编码报错，理由是避免把远程代码执行暴露到网络），只能绑回环地址。

首次使用

1. 浏览器打开 http://127.0.0.1:3080。
2. Settings → Models，填入 DeepSeek API key，保存后立即生效，不用重启服务。
3. Choose workspace，添加你启动 dsh 时所在的项目目录，选中它。不选工作区无法创建会话。
4. 新建会话，发任务即可。涉及权限策略的操作会弹窗请求批准。

相关环境变量

变量	作用
DSH_HOME	用户数据根目录，默认 ~/.dsh（Windows 为 C:\Users\<你>\\.dsh）。优先级：显式配置 > $DSH_HOME > 默认
DSH_TELEMETRY_DISABLED	任意非空值（包括 0/false）即关闭遥测上报

5. 停止

没有 dsh stop 命令。停止就是给进程发信号，信号会触发优雅关闭。

方式	行为
前台终端按 Ctrl+C（SIGINT）	优雅关闭，退出码 130
发 SIGTERM	优雅关闭，退出码 0
强杀	跳过清理，不推荐

优雅关闭做的事（源码路径）：SIGINT/SIGTERM 处理器触发根上下文 fiber.dispose()，WebServer 服务的清理钩子执行 server.close() + closeAllConnections() + 销毁所有升级的 WebSocket 连接，然后进程退出。

Windows 上从另一个终端优雅停止（node 会模拟信号）：

node -e "process.kill(<PID>,'SIGTERM')"

PID 怎么找：

Get-NetTCPConnection -LocalPort 3080 -State Listen   # OwningProcess 就是 PID

强杀兜底（跳过清理，仅当优雅停止失效时用）：

Stop-Process -Id <PID> -Force
# 或
taskkill /PID <PID> /F

6. 更新

git pull                 # 拉取新代码
pnpm install             # 安装新增/变更的依赖
pnpm run build           # 重新构建
pnpm dsh web             # 重启

要点：

• 更新前先停掉正在运行的服务（第 5 节）。
• 构建失败时先清一次构建产物再重试：pnpm run clean（会删除构建输出和已删除包的安全残留）。
• 预览版警告：后端会拒绝旧磁盘格式（SCHEMA_VERSION 单调递增，会话格式无兼容承诺）。升级后如果报格式错误，需要重建 ~/.dsh 下的数据（先备份再删，见第 7 节）。
• 只改前端代码的日常开发可以用热更模式：pnpm run dev:web（client 插件热重载，不用重启服务）。

7. 卸载

卸载 = 删目录 + 删全局工具，没有注册表项、没有系统服务、没有后台常驻进程，删完即净。

# 1. 停止服务（第 5 节）

# 2. 删除源码目录（含 node_modules、lib、dist）
Remove-Item -Recurse -Force E:\deepseek-harness

# 3. 删除用户数据（可选，见下）
Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh"

# 4. 卸载全局 pnpm（如果当初是 npm 全局装的）
npm uninstall -g pnpm

第 3 步说明：~/.dsh 是全部用户数据，包括会话记录、API key、设置。想保留数据就跳过这步，只删源码目录；想彻底清干净就连它一起删。

8. 用户数据目录（$DSH_HOME）

默认 ~/.dsh，可用 DSH_HOME 环境变量改到别处。内容清单：

路径	内容
$DSH_HOME/sessions/	会话日志（session.jsonl 或压缩的 session.jsonl.zstd，按 项目/会话ID 分目录）
$DSH_HOME/storages/	存储数据
$DSH_HOME/settings.yaml	用户设置（热重载，改完即生效）
$DSH_HOME/.credentials.yaml	凭据（API key 等）
$DSH_HOME/cordis.patch.yml	用户级配置补丁层，覆盖所有 profile 的配置

9. Windows 实测注意事项

• 后台启动：Start-Process 必须用 pnpm.cmd 而不是 pnpm（pnpm 是 .cmd shim，不是 Win32 可执行文件，直接传会报"不是有效的 Win32 应用程序"）。
• 端口占用检查：Get-NetTCPConnection -LocalPort 3080 -State Listen。
• 残留进程检查：Get-Process node。
• corepack 不可用：见 3.1，用 npm install -g 装 pnpm。

10. 常见问题

现象	处理
启动报端口被占	换端口：pnpm dsh web --port 8080
构建失败	pnpm run clean 后重新 pnpm run build
升级后会话/存储报格式错误	预览版预期行为，备份后删除 ~/.dsh 下对应数据重建
页面能开但任务报无模型	Settings → Models 里 API key 没填或填错
任务要求批准但没弹窗	检查权限策略设置

附：命令速查

git clone https://github.com/deepseek-ai/deepseek-harness.git   # 拉取
pnpm install                                                    # 装依赖
pnpm run build                                                  # 构建
pnpm dsh web                                                    # 启动（http://127.0.0.1:3080）
Ctrl+C                                                          # 停止（优雅）
git pull && pnpm install && pnpm run build                      # 更新
Remove-Item -Recurse -Force <仓库目录> + ~/.dsh                 # 卸载