DeepSeek Harness 安装使用教程（新手村）

一句话：DeepSeek Harness（简称 dsh）是 DeepSeek 官方开源的"智能体框架"——你可以把它理解成一块乐高底盘，上面所有东西（对话界面、模型、工具、技能、工作区……）都是可以拼装、替换的插件。

⚠️ 官方明确说了：现在是开发者预览版，迭代很快，将来会有破坏兼容性的改动。玩得开心，但也别拿它上生产哈。

1. 它是干嘛的

看名字就知道它跟 DeepSeek 有关系——这是 DeepSeek AI 官方开源的一个 agent harness（智能体框架）。跟 Claude Code 那类工具是"同行"，但主打一个自由组合：

• 底层由 Cordis 驱动，架构理念是"一切皆插件"
• 你可以只用一个命令跑起来（web 界面），也可以一口气跑完就退出（headless），还能当 SDK 被别的程序调用
• 插件生态是社区化的，装插件就像 npm install 一样简单

2. 准备两样东西

① Node.js（必须）

• 去 nodejs.org 装 LTS（长期支持版） 即可；装完在终端里验证：

node --version   # 比如 v24.19.0

② DeepSeek API Key（必须，除非你用别的模型）

• 到 DeepSeek 开放平台 platform.deepseek.com 注册并创建一个 API Key（以 sk- 开头的那种）
• 这一步只是"拿到钥匙"，钥匙不用填到命令行里，等会直接在网页界面上粘

💡 想用别的模型（比如 OpenAI、Claude 或任何 OpenAI 兼容端点）？也行，见第 8 节，但第一次建议先用 DeepSeek 官方，省事。

3. 安装 & 启动

方案 A：npm 一条命令（推荐新手）

装好 Node.js 后，随便找个目录打开终端，敲：

npx @deepseek-ai/dsh web

会发生什么：

1. npx 会先帮你把 @deepseek-ai/dsh 下载好（之后会缓存，不用重复下）
2. 启动 web 服务器，默认地址 http://127.0.0.1:3080
3. 本机运行时会自动用默认浏览器打开这个页面（通过 SSH 跑的话只打印地址，不会乱开浏览器）

不想让它自动开浏览器？加 --no-open：

npx @deepseek-ai/dsh web --no-open

想换端口（注意 --port 是 web 应用自己的参数，不是 dsh 的）：

npx @deepseek-ai/dsh web --port 8080

方案 B：从源码运行（开发党）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build      # 准备仓库产物
pnpm dsh web        # 用已构建产物启动，不会重新构建

🔑 小知识：第一次在某台机器上直接访问 127.0.0.1:3080 可能看到一行字 dsh web authentication required; reopen the URL printed by dsh web.。这是因为 dsh web 启动时打印的 URL 里带了授权 token——本机启动会自动打开那个 URL，所以通常你不用管；如果手贱关了标签页，重启一次 dsh web 就又能拿到。换个浏览器/无痕窗口直接输地址是没用的，必须通过启动时打印的 URL 进入。

4. 首次配置：填 API Key

进入界面后，打开 设置 → 模型（左下角齿轮 ⚙️ 图标），你会看到这个页面：

把第 2 节拿到的 DeepSeek API Key 粘到 DeepSeek（deepseek-official） 卡片的"API 密钥"输入框里，点 保存。

注意几个点：

• 保存后模型路由立即可用，不需要重启服务器，很贴心
• 界面上还有"添加提供方"和"添加自定义提供方"两个按钮，想用别家模型就看第 8 节
• 万一不想在界面上配，也可以点右上角 打开配置文件 直接改配置（高级玩法）

5. 选工作区，跑第一条指令

1. 点击界面上的 选择工作区，添加一个项目目录（默认是启动 dsh 时所在的那个目录）
2. 选中工作区之前，会话输入框是灰的——这是正常现象，别以为卡了
3. 选中后，新建一个会话，发一条随便什么的指令，比如：

Summarize this repository and identify its main packages.

之后会发生什么（你会亲眼看它"干活"）：

• agent 会读文件、改文件、执行命令、查搜索，甚至委派子任务
• 需要按权限策略征求你意见的操作，界面会弹出来问你（审批）
• 整个过程在界面上能看到计划、轨迹、工具调用，透明度拉满

💬 我写这篇教程的时候，自己就正在被一个 dsh web 界面里的 agent 帮忙干活——就是你看到的这个对话。

6. 命令行全家桶

web 只是入口之一。dsh 的各种模式长这样：

几个实用细节：

• 当前目录就是默认 workspace 根目录——在哪运行命令，agent 就默认在哪干活
• dsh --dump-config 可以在不启动的情况下查看 profile 组合完的配置树
• 启动器只认自己的 flag，后面的参数都传给 app：dsh --profile web --port 8080 里的 --port 是 web 的
• web、headless、sdk、sdk-minimal、acp 这些 profile 首次使用时自动从模板初始化，不用你操心

一个真实例子

dsh web                              # 启动 Web 界面
dsh --profile headless "summarize this repo"   # 跑完直接输出答案退出

7. 一切皆插件：加装插件和技能

DSH 的世界是怎么组织的

• 每个"可用启动方式"是一个 profile，住在 $DSH_HOME/profiles/<名字>/（Windows 上 $DSH_HOME 默认是 C:\Users\<你>\.dsh）
• profile 的 package.json 里有 dsh.profile.bundles，按顺序列出要叠加的插件组合包
• 你自己的补丁写在 profile 的 cordis.patch.yml 里
• 你的 API Key、凭据、会话记录等等也都在 $DSH_HOME 下统一管理

C:\Users\<你>\.dsh\
├── profiles\
│   └── web\
│       ├── package.json        # 记录依赖 + dsh.profile.bundles（插件清单）
│       ├── cordis.patch.yml    # 你自己的配置补丁层
│       └── node_modules\       # 装在这里的插件
├── settings.yaml               # 全局设置
├── .credentials.yaml           # API 密钥等凭据
└── sessions\                   # 会话记录

装插件：以社区插件市场为例

官方内置的是基础件，想玩花活就装社区插件。我拿最有名的插件市场 dshmarket 演示：

dsh plugin --profile web add dshmarket

装完你会看到输出类似：

dependencies:
+ dshmarket ^1.44.0
Done in 2.2s using pnpm v11.5.2

注意：dsh plugin add 帮你做两件事——把包装进 profile 的 node_modules，然后自动把它追加到 package.json 的 bundles 列表里。之后重启 dsh web，打开 设置 → Plugin Market，就能像逛应用商店一样浏览、搜索、一键安装几百个社区插件了（dsh-market/dsh-market）。

⚠️ 装插件后没出现？九成是没重启 dsh web。另外要求宿主版本够新（dshmarket 要求 web rc.6+）。

装技能（skill）

DSH 支持开源 agent skills 生态：技能就是一个个带 SKILL.md 的文件夹，装在用户级目录 C:\Users\<你>\.agents\skills\<技能名>\，重启（或新会话）后就能在界面上看到、随时调用。

• 用 npx skills find <关键词> 搜索、npx skills add <owner/repo@skill> 安装
• 也可以手动把某个仓库里的 skills/<名字>/ 文件夹拷进去（本机就是这么装的）

8. 换个模型 / 自定义接口

回到 设置 → 模型，点 + 添加提供方 可以直接接第三方提供方；点 + 添加自定义提供方，则弹出这个表单：

对着填就行：

保存之后即可在模型选择器里切换，也有官方的模型配置指南。

9. 常见问题（都是真实踩过的坑）

Q：终端打印了地址但我直接访问得到 authentication required？ A：见第 3 节的小知识——要用启动日志里那个带 token 的完整 URL 打开；进程重启后会打印新 URL。

Q：git clone 报错 schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS？ A：Windows 的 git 默认用 schannel 走 TLS，有些网络/证书环境会抽风。临时绕过（对已知可信仓库）：

git -c http.sslVerify=false clone https://github.com/xxx/yyy.git

或者彻底点：git config --global http.sslBackend openssl（需要你的 git 带了 openssl 后端，Windows 版 Git 一般有）。

Q：npm install、npx 慢 / 超时？ A：国内用户换镜像，一秒钟的事：

npm config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

Q：插件装了但界面里没有？ A：先重启 dsh web；还不行就检查宿主版本（dsh --version）是否满足插件的版本要求；个别社区插件体量大，安装要等它跑完构建再重启。

Q：dsh: pnpm failed in profile directory ...？ A：dsh plugin 背后是 pnpm，这种报错通常是（a）网络问题连不上 registry，（b）对 profile 目录没有写权限，或（c）pnpm 与 Node 版本不匹配。先看报错里的具体异常，多半是网络；换镜像再试。

Q：Node 版本太高/太低装不上？ A：官方要 ^22.19.0 || >=24.0.0。用 nvm-windows 或 fnm 安装符合版本的 Node 即可。

Q：想回看以前的对话？ A：会话记录存在 $DSH_HOME/sessions\，界面里一般也能在会话列表找到；headless 模式每次都是全新会话。

10. 资料 & 安全

• 官方仓库（中文 README）：github.com/deepseek-ai/deepseek-harness
• 文档站：https://deepseek-harness.github.io/deepseek-harness/
• 使用 Web UI 指南（中文）：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.zh.md
• 社区插件市场：github.com/dsh-market/dsh-market（逛的页面 dshmarket.com）
• 插件目录：awesome-dsh-plugin
• 反馈 & bug：GitHub Discussions（搜 "deepseek-harness discussions"）

安全三连：

1. 跑之前务必读一遍官方安全说明 SAFETY.zh.md——agent 能执行命令，权限策略、敏感目录都要心里有数
2. API Key 不要贴到公开渠道；.credentials.yaml 别提交进 git
3. 第三方插件 = 第三方代码，装之前看看来源（dshmarket 只收录 curated 注册表的条目，但仍然"列表 ≠ 背书"）