DeepSeek Harness 安装与使用保姆级教程
1. DeepSeek Harness 是什么
DeepSeek Harness（简称 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日开源的一款 Agent 运行框架，采用 MIT 协议发布。它的核心定位是充当大语言模型的“手脚”——替模型记住上下文、调用工具、在文件和终端之间执行操作，直到把一整件事情完成。DeepSeek 官方给出的公式是：Model + Harness = Agent。
Harness 采用“一切皆插件”的架构，由 Cordis 驱动。模型、工具、策略、存储、上下文管理等所有组件都可以作为插件加载、卸载和替换。官方目前已内置了一百多个插件。
目前 DeepSeek Harness 处于开发者预览阶段，正在快速迭代中，未来可能出现破坏兼容性的变更。
2. 安装前提
DeepSeek Harness 基于 Node.js 构建，安装前需要确保系统已安装 Node.js 且版本符合要求。
第一步：检查是否已安装 Node.js
在终端中执行以下命令：
node --version如果命令未找到（提示 command not found 或类似信息），说明系统尚未安装 Node.js，请先完成安装。
第二步：安装或升级 Node.js
- 推荐使用 nvm（Node Version Manager）：nvm 可以方便地安装、切换和管理多个 Node.js 版本。安装 nvm 后，执行：
nvm install 22.19.0 # 安装 22.19.x 系列 nvm use 22.19.0或者安装最新的 LTS 版本（24 及以上）：
nvm install --lts nvm use --lts - 直接下载安装包：访问 nodejs.cn 下载 LTS 版本的安装包（Windows 为 .msi，macOS 为 .pkg，Linux 有预编译二进制或包管理器方式），按照向导完成安装。
第三步：验证版本
安装完成后，再次运行 node --version，确保输出为 v22.19.x 或 v24.x 及以上版本。如果版本过低，请使用 nvm 切换或升级。
3. 安装方式
DeepSeek Harness 提供多种安装方式，用户可根据自身需求选择。
3.1 npx 一键启动（推荐快速体验）
这是最简单快捷的启动方式，适合希望快速体验的用户。在已安装 Node.js 的环境中，直接执行：
npx @deepseek-ai/dsh web该命令会自动下载并启动 Web UI，默认地址为 http://127.0.0.1:3080。
如需全局安装以便日常使用，可执行：
npm install -g @deepseek-ai/dsh && dsh web3.2 从源码运行
适合需要修改配置、进行二次开发或追踪最新提交的用户。首先克隆官方仓库：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness然后安装依赖并构建：
pnpm install
pnpm run build
pnpm dsh web3.3 Docker 部署
适合服务器部署或需要与飞书等平台集成的场景。官方提供了 Docker 镜像，支持数据持久化和健康检查。
拉取并运行原版镜像：
docker run -d --name dsh -p 3080:3080 -v dsh-data:/root/.dsh ghcr.io/huoxue1/deepseek-harness:latest如需使用自带飞书插件的版本：
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=secret
docker run -d --name dsh-web -p 3080:3080 -v dsh-data:/root/.dsh -e FEISHU_APP_ID=$FEISHU_APP_ID -e FEISHU_APP_SECRET=$FEISHU_APP_SECRET ghcr.io/huoxue1/deepseek-harness-lark:latest容器默认监听 3080 端口，所有用户数据（会话、设置、授权 token 等）存储在 /root/.dsh 目录，建议挂载命名卷以实现数据持久化。
3.4 一键安装包（Windows 用户）
对于不熟悉命令行的 Windows 用户，社区提供了一键安装包。该版本将 Node.js 和 dsh 打包在一起，无需额外安装任何东西。
下载 DeepSeekHarness-win32-x64-0.1.0-rc.5.zip（约 238 MB）后解压到任意目录，双击 DeepSeekHarness.exe 即可运行。首次启动时会弹出“选择数据存放位置”对话框，选择数据存储目录即可。
4. 首次启动与配置
无论采用哪种安装方式，首次启动后都需要完成以下配置步骤。
4.1 打开 Web UI
启动成功后，在浏览器中访问 http://127.0.0.1:3080。Web UI 默认监听本地回环地址，不对外暴露。
4.2 配置 API 密钥
打开 设置 → 模型（Settings → Models），在 DeepSeek 卡片中输入 API 密钥并保存。密钥是只写的，保存后页面仅显示脱敏描述符。
如果使用其他模型提供商（如 Anthropic 或 OpenAI），可点击“添加提供方”并输入对应的 API 密钥。
4.3 选择工作区
配置完 API 密钥后，需要选择一个工作区（Workspace）。工作区是 Agent 被允许操作的项目目录。点击“选择工作区”，添加启动 dsh 时所在的项目目录并选中它。在选中工作区之前，会话输入框不可用。
工作区支持三种权限模式：只读、工作区可写、完全访问。
5. 基本使用
5.1 Agent 预设模式
DeepSeek Harness 内置了四种 Agent 预设模式，各模式会自动加载对应的插件集：
- 标准模式：功能完整的编码 Agent，涵盖文件编辑、Shell、文件与网页检索、Skills、计划模式、目标追踪、子代理和工作流等全部能力。
- PTC 模式（程序化工具调用模式）：在标准模式全部能力之上，额外提供 Code Mode SDK，允许模型编写 TypeScript 程序来组合多步操作。
- 极简模式：仅保留 bash 和 str_replace_editor 两个工具，用于基准测试和最小化复现。
- 创造模式：在标准模式全部能力之上，额外提供运行时检查、插件实验和 preset 创作指导，用于自定义 Agent 预设。
用户也可以在现有预设基础上复制修改，或使用创造模式让 Agent 帮助创建自定义预设。
5.2 发起会话
完成工作区选择和预设模式选择后，即可在会话输入框中输入任务并发送。Agent 将根据配置的模型和工具执行任务，并在对话窗口中返回结果。
5.3 轨迹回放
DeepSeek Harness 提供了“轨迹”（Trajectory）功能，可以随时监控 Agent 的执行过程。与 Chat 视图中润色后的对话不同，Trajectory 显示的是原始事件级记录，用户可以随时回放，查看会话内部的具体执行情况。
6. 插件开发
DeepSeek Harness 的“一切皆插件”架构使得插件开发变得非常灵活。在 Harness 中，插件是一个导出 apply 函数的 TypeScript 模块，框架在加载时调用 apply 并传入上下文对象，开发者通过上下文对象注册能力。
官方文档提供了从零开始的插件开发教程，涵盖创建最小插件并将其加载到 Web UI 的完整流程。社区也提供了丰富的插件开发资源和示例。
7. 常见问题
- Node.js 版本不兼容：DSH 要求 Node.js 22.19.x 或 24 以上版本，请使用
node --version检查并升级。如果未安装，请参照“安装前提”部分先安装。 - 端口被占用：默认端口 3080 被占用时，可以更换端口启动，或检查是否有之前启动的实例未退出。
- 启动失败：可能是 profile 配置错误或缺少插件依赖，可以使用
dump命令查看配置，检查cordis.patch.yml语法。 - 工具调用超时：单次调用超出预算，可检查该工具的超时配置。
- API 密钥相关问题：密钥保存在本地数据目录中，不会被上传。如需通过环境变量传入，可设置
DEEPSEEK_API_KEY。
8. 资源链接
- 官方 GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
- 官方文档站：https://deepseek-harness.github.io/deepseek-harness/
- 官方网站：https://www.deepseek.com/harness/
- GitHub Discussions：https://github.com/deepseek-ai/deepseek-harness/discussions
9. 结语
DeepSeek Harness 将 DeepSeek 的开源边界从模型延伸到了 Agent 工程体系。它让开发者可以像搭积木一样组合 Agent 的各个组件，为 AI 应用的构建提供了极大的灵活性。目前项目仍处于开发者预览阶段，但已吸引了大量关注和社区贡献。随着版本的持续迭代，DeepSeek Harness 有望成为 Agent 开发领域的重要基础设施。