DeepSeek Harness 国内部署完全指南：从官方工具到社区生态

时效性声明：本文基于 2026 年 8 月 25 日前后公开资料整理。DeepSeek Harness 目前处于开发者预览版，命令、插件与功能可能随时变化，请以官方仓库为准。

一、DeepSeek Harness 是什么？

DeepSeek Harness（简称 dsh）是由深度求索（DeepSeek AI）官方开发的开源智能体运行时（Agent Runtime / Harness），可理解为智能体编排与执行框架。它的核心设计理念是 “万物皆插件” ，整个系统基于 Cordis 插件架构构建，从模型接入、工具调用到界面呈现，所有功能模块均可通过插件灵活组合与替换。

重要提示：DeepSeek Harness 目前处于开发者预览版，官方明确表示会存在破坏性变更，生产环境使用需谨慎。

二、国内环境安装与配置指南

1. 前置准备：Node.js 环境

DeepSeek Harness 基于 Node.js 运行，官方要求 Node.js ^22.19.0 || >=24.0.0。Node 23 不被支持。建议使用 nvm 管理版本，并设置国内镜像加速：

1
2
3
4

# 设置 nvm 国内镜像
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install 22.19.0
nvm use 22.19.0

2. 设置国内 npm 镜像源（关键）

国内访问 npm 官方源速度极慢，务必配置国内镜像源以加速依赖下载：

1
2
3
4
5

# 设置 npm 为淘宝镜像源
npm config set registry https://registry.npmmirror.com
 
# 验证是否生效
npm config get registry

3. 获取 API Key（前置准备）

国内用户需在 DeepSeek Platform 创建 API Key，后续配置 Agent 时需要填入。建议提前准备好。

4. 官方四种运行模式详解

DeepSeek Harness 提供了四种会话级预设（Preset），可在 Web UI 的设置中随时切换。日常使用只需关注 Preset（预设）——标准/PTC/极简/创造四种模式，在 Web UI 顶部即可切换。启动命令保持 dsh web 即可，无需关心 Profile 细节。

标准模式（Standard Preset）

• 特点：功能最全面的模式，包含文件系统操作、Shell 命令执行、网页检索、代码编辑等全套工具。
• 工具调用方式：多轮对话式——调工具 → 看结果 → 再决定下一步，每一步都清晰可干预。
• 适用场景：日常通用开发，写功能、改 Bug、看代码、小范围重构、需要随时看中间结果并调整的任务——标准更合适，反馈清楚，也更稳定。

PTC 模式（Programmatic Tool Calling Preset）

• 定位：PTC（程序化工具调用）模式不是"更省 Token 的通用升级版"，而是特定场景下的专项工具。
• 核心机制：让模型直接生成一段 TypeScript 程序代码，通过 run_code 一次性编排并执行多步工具调用，而非多轮逐步调用。
• 核心价值：减少模型与工具之间反复沟通的轮次，在合适的任务上可明显减少往返，节省 Token；同时提升复杂任务处理效率。

• 适用场景：批处理、固定流程、需要动态组合大量工具调用的任务，如：

  • 一次性处理很多同类文件/日志（批量重命名、日志过滤统计、多文件同类修改）
  • 工具调用链很长、反复"调工具→看结果→再调"很浪费的场景
  • 流程相对固定、可以用一段程序表达的任务

• 使用建议：

  • 默认用标准模式，明确遇到批处理/长链路任务时再切 PTC
  • 同一会话里按任务切换：日常对话用标准，明确批处理任务再开 PTC
  • 若某次 PTC 感觉"程序写得很长/结果不好控"，直接切回标准即可

• 关于"PTC 更省 Token"：社区和实测中常见说法是，在批处理、长调用链任务上 PTC 能减少反复通信，有时能省不少 Token。但公开资料里没有统一、官方的"日常一律省 70%+"数据，效果高度依赖任务：

  • 适合 PTC 时：步骤机械、可程序化（批量重命名、日志过滤统计、多文件同类修改等）→ 往返少，往往更省。
  • 不适合时：探索性强、需要看中间结果再决策（调试复杂 Bug、架构讨论、边写边试）→ 模型可能写出更长程序/更多思考，Token 不一定更少，有时还会更高。
• 省 Token 的长期建议：选合适模型档位（Flash 做简单事）、控制工作区与上下文、善用压缩/计划模式，而不是盲目依赖 PTC。

极简模式（Minimal Preset）

• 特点：仅保留 persistent bash（持久化 Shell）和 str_replace_editor（文件编辑器）两个核心工具，上下文窗口占用极小。（*nix 以 bash 为主，Windows 以对应 shell 为准。）
• 适用场景：模型基准测试（如 SWE-bench），或在资源受限环境下的最小化运行。

创造模式（Creative / Creator Preset）

• 特点：支持运行时检查、在内存中调试插件，用户可以基于此模式自定义全新的 Agent 配置。界面可能显示为"创造"或"Creator"，以实际界面为准。
• 适用场景：高级开发者构建、调试和保存自定义的 Agent 配置，适合探索和实验。

模式对比速览

一句话总结：日常编码优先标准模式；PTC 是"批处理/长链路编排"的专项模式，能省 Token 但不是通用更省。先标准，用到再切。

5. 多模型支持

DeepSeek Harness 的核心设计理念是"万物皆插件"，模型本身也是可插拔的组件。你可以轻松替换默认的 DeepSeek 模型，接入任意兼容的第三方 API。

接入方式

方式一：通过 Web UI 添加预置或自定义提供方

在 Web UI 的设置界面即可完成配置：

• 预置提供方：在 设置 → 模型 中，点击"添加提供方"，选择如 OpenAI、Anthropic 等，填入 API Key 即可。
• 自定义提供方：对于自建网关或未收录的厂商，选择"添加自定义提供方"。需要填写 Provider ID、API 地址、协议（如 openai-completions）、API 密钥和至少一个模型 ID。

添加完成后，回到主对话界面，你可以在对话框右下角的模型选择器中，手动选中刚刚添加的模型，当前会话就会开始使用它。

方式二：使用社区插件一键接入

社区已开发了多个 Provider 插件，实现更便捷的接入：

1
2
3
4
5
6
7
8

# 安装快速配置插件，支持智谱 GLM、MiniMax、OpenAI、Ollama 等
dsh plugin --profile web add dsh-provider-quick-config
 
# 接入 BicBot 模型
dsh plugin --profile web add @bic-ai/dsh-bicbot
 
# 高级模型配置面板，支持创建自定义端点并细粒度配置能力参数
dsh plugin --profile web add deepseek-harness-model-config

方式三：通过配置文件手动添加（高级）

直接编辑 $DSH_HOME/settings.yaml 文件来添加自定义提供方。适合进行精细调整，例如为自定义模型显式声明 input: [text, image] 以启用视觉能力。

已确认支持的模型/平台

基于官方文档和社区实践，已确认可以接入的模型和平台包括：

• 商业模型：OpenAI（GPT 系列）、Anthropic（Claude 系列）、智谱 GLM、MiniMax
• 本地部署：Ollama（支持本地开源模型）
• 国内云平台：百度千帆（通过自定义提供方接入）
• 实测案例：Kimi K3、GPT-5.6 Sol、Claude Opus 4.8 等
• 兼容协议：任何兼容 OpenAI 协议的 API 网关或服务，理论上都可以通过"自定义提供方"接入

让模型自动选择：路由与委派插件

DSH 本身默认不会自动切换模型，但社区提供了丰富的插件来实现任务驱动的自动模型选择。以下是一些主流方案：

1. 统一模型路由（dsh-model-router）

通过配置"套餐"和"档位"，实现按任务类型自动路由，并支持故障转移。

• 核心机制：一个逻辑 Model ID 对应多个供应商的候选模型，按 tier1/2/3（轻量/标准/强大）三档分级。可根据任务目的（purpose）自动选档，首 token 前失败自动切换并冷却。

• 安装命令：

  1	dsh plugin --profile web add @welsione/dsh-model-router

2. 子代理模型委派（dsh-delegation-suite / dsh-subagent-model-router）

这类插件专注于将子任务自动委派给配置了不同模型的子 Agent，实现"专业分工"。

dsh-delegation-suite：支持角色委派，可为不同角色（如"编码员"、"审查员"）分配专属模型。

安装命令：

1

dsh plugin --profile web add github:wenheguo2/dsh-delegation-suite

dsh-subagent-model-router：允许为子 Agent 的工作配置独立于父会话的模型路由，子 Agent 的可用模型和父会话可以不同，实现"不同工种用不同大脑"的精细控制。

安装命令：

1

dsh plugin --profile web add dsh-subagent-model-router

安装后重启 dsh web，在 设置 → Subagent Models 中配置，或调用 /model-subagent-setup 命令进行设置。

3. 按任务阶段切换（dsh-model-switch）

为会话中的不同阶段（主对话、子代理、计划执行）分别设置默认模型，无需手动反复切换。

安装命令：

1

dsh plugin --profile web add github:lincong1987/dsh-model-switch

4. 自然语言切换（dsh-nl-model-switch）

无需离开对话界面，直接用自然语言指令切换模型，例如在对话框中发送"切换到 deepseek-v4-flash 模型"。

安装命令：

1

dsh plugin add dsh-nl-model-switch

6. 如何设置 0.0.0.0 实现局域网访问

官方版本出于安全考虑，禁止使用 --host 0.0.0.0 参数——因为 Agent 具备本地代码执行能力，直接绑定到所有网络接口会显著扩大攻击面，且当前版本无内置认证层。

如需在局域网内其他设备访问，有以下几种方案：

方案一：社区解锁插件

社区有多个插件/补丁可以解锁 0.0.0.0 限制，例如：

• dsh-web-startup-auth：替换启动器，放行 --host 0.0.0.0 的同时提供用户名/密码认证功能，相对更安全。
• dsh-lan、dsh-relay 等社区方案也可实现类似效果。

安装示例（以 dsh-web-startup-auth 为例）：

1
2
3

dsh plugin --profile web add dsh-web-startup-auth@latest
dsh web --host 0.0.0.0
# 首次访问需要设置管理员账号密码

注意：具体包名以该插件仓库 README 为准，安装后按说明启动。

方案二：反向代理 + 认证（推荐）

通过 Nginx、Caddy 等反向代理工具，在转发请求前增加 HTTPS、IP 白名单或基础认证，避免直接将 Harness 暴露在网络中。

方案三：内网穿透 / VPN 工具

使用 Tailscale、ZeroTier、SSH 隧道等工具建立安全的点对点连接，无需将服务绑定到 0.0.0.0。

安全警告：上述所有"解锁 0.0.0.0"的方案都会扩大攻击面（Agent 可执行命令、读写文件）。强烈建议优先使用 SSH 隧道、VPN 或反向代理 + 认证方案，而非直接绑定 0.0.0.0。

插件安全提醒：社区插件质量参差不齐，安装前应检查仓库活跃度、Stars、是否有恶意代码风险。桌面客户端均为非官方，请认准 GitHub 官方仓库或官网，避免使用第三方镜像源。

7. 源码构建方式（适合开发者）

如需从源码构建或进行二次开发，可按照以下步骤操作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 使用 gh-proxy 加速克隆（可选加速方式，非官方保证）
git clone https://gh-proxy.com/https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
 
# 安装 pnpm 并设置镜像源
npm install -g pnpm
pnpm config set registry https://registry.npmmirror.com
 
# 安装依赖并构建
pnpm install
pnpm run build
 
# 运行（使用已构建的产物，无需重新构建）
pnpm dsh web

8. 启动方式补充

对于新用户，更常见的启动方式是直接通过 npx（无需全局安装）：

1

npx @deepseek-ai/dsh web

也可以全局安装后使用 dsh web：

1
2

npm install -g @deepseek-ai/dsh
dsh web

升级方法：

两种方式均可，Web UI 默认在 http://127.0.0.1:3080 启动。

如需在局域网内访问，可在全局安装后添加社区插件解锁 0.0.0.0 限制（以 dsh-web-startup-auth 为例）：

1
2
3

dsh plugin --profile web add dsh-web-startup-auth@latest
dsh web --host 0.0.0.0
# 首次访问需要设置管理员账号密码

具体插件安装方式请以对应仓库 README 为准，详见本文"如何设置 0.0.0.0 实现局域网访问"章节的安全提醒。

9. 主目录、启动目录与工作区目录

使用 DeepSeek Harness 前，建议先区分三个概念：主目录、启动目录和工作区目录。

主目录（数据目录）

主目录是 DSH 存储个人配置、会话记录和凭据的位置，默认是 ~/.dsh（可通过 $DSH_HOME 环境变量自定义）。

~/.dsh/ 下存放的内容包括：

1
2
3
4
5
6

~/.dsh/
├── profiles/          # 各 profile 的配置
├── sessions/          # 会话日志
├── storages/          # 插件数据
├── settings.yaml      # 用户设置
└── .credentials.yaml  # API Key 等凭据

关键点：主目录是 DSH 内部使用的，和你的项目代码无关。程序本体随时可以删掉重装，主目录里的数据不受影响。

启动目录

启动目录是执行 dsh web 或 npx @deepseek-ai/dsh web 命令时所在的终端目录。

当你打开 Web UI 后，DSH 的目录选择器默认打开的起始位置是操作系统用户主目录（~ 或 /root），而不是你的启动目录。这是当前版本的已知设计限制——目录选择器硬编码了默认起始位置为 os.homedir()。

所以如果直接点"选择工作区目录"，看到的是 ~/ 下的内容，而不是启动目录。

工作区目录（项目目录）

工作区目录是 Agent 真正读写文件、执行命令的地方——也就是你的项目代码所在目录。

如何正确选择工作区目录：

在 Web UI 中点击"选择工作区目录"后：

1. 默认弹窗打开的是 ~/ 或 /root/，不会自动定位到启动目录
2. 解决方法一：在目录选择器顶部的路径输入框中，直接输入你想要的工作区目录的绝对路径（如 /home/yourname/my-project/），按回车跳转并选中
3. 解决方法二（推荐）：安装社区插件 dsh-wsl-workspace-picker，它会替换默认的目录选择器，提供完整的路径输入框和从根目录 / 开始的面包屑导航，可以自由选择任意目录

安装命令：

1

dsh plugin --profile web add dsh-wsl-workspace-picker

然后重启 dsh web，重新打开目录选择器即可生效。

重要：不要把主目录（~/.dsh/）选为工作区目录。工作区目录应该指向你的项目文件夹（如 ~/my-project/），而不是 DSH 自己的数据目录。

三者关系总结

关键：启动目录只是你执行命令的位置，但 Agent 的读写权限边界由你在 UI 里选的工作区目录决定。目录选择器默认打开的是用户主目录，需要手动输入绝对路径或安装插件才能选到其他位置。

10. 后台运行与开机自启

dsh web 本身是前台进程，如果希望它在后台长期运行、开机自启或崩溃后自动恢复，推荐使用社区插件 dsh-daemon。

dsh-daemon

将 dsh web 注册为系统后台服务，支持以下平台：

• macOS：LaunchAgent（~/Library/LaunchAgents/com.deepseek-ai.dsh-watchdog.plist）
• Linux：systemd 用户单元（~/.config/systemd/user/dsh-watchdog.service），systemd 不可用时回退为 cron @reboot
• Windows：计划任务（DshWatchdog），通过 VBS 启动器以隐藏窗口方式运行

安装后，dsh web 将具备以下能力：

• 登录时自动启动
• 睡眠唤醒后自动重启
• 自愈：watchdog 每 30 秒健康检查一次 http://127.0.0.1:<port>/health，连续 3 次失败后重启服务
• 不依赖当前会话：watchdog 是独立生成的脚本，而非内存中的插件

安装方法：

1

dsh plugin --profile web add @chenkai114/dsh-daemon

前置要求：需要 pnpm 在 PATH 中（执行 corepack enable 一次性启用）。

注册为后台服务：

安装完成后，需要重启 dsh web 使插件生效，然后在 Web UI 中通过 Agent 完成注册。

由于 dsh-daemon 插件不提供独立的 dsh-daemon 命令行工具，它的注册过程需要由 Agent（智能体）调用内置的 dsh_daemon_install 工具来完成。

操作步骤：

1. 安装插件后，重启 dsh web（保持你习惯的启动方式）

2. 在 Web UI 的对话界面中，向 Agent 发送指令，例如：

   • "执行 dsh_daemon_install"
   • "帮我把 DSH 注册为后台服务"
3. Agent 会自动调用 dsh_daemon_install 工具，生成 watchdog 脚本并注册到系统服务中

注册成功后，watchdog 会记录你当前的启动参数，后续由它负责拉起和管理 dsh web 进程。

日常管理命令：

注册成功后，可以通过以下方式控制 daemon：

⚠️ 重要注意事项：

1. 不要手动修改配置文件：不要往 ~/.dsh/profiles/web/cordis.patch.yml 里手动添加 - insert: dsh-daemon，否则会触发 duplicate loader entry id: dsh-daemon 启动失败。
2. 权限说明：插件需要 danger-full-access 权限来管理用户级系统服务文件。
3. 启动参数记忆：注册时会记录当前的启动命令和参数，之后由 watchdog 自动拉起时会沿用这些参数。如果需要修改启动参数，请先通过 Agent 调用 dsh_daemon_stop 停止服务，然后用新的参数手动启动 dsh web，再调用 dsh_daemon_reinstall 重新注册。

与 dsh-web-startup-auth 的兼容性说明：

dsh-daemon 与 dsh-web-startup-auth 存在已知兼容性问题：后者会保护所有路由（包括 /health），而前者的健康检查不携带认证信息，导致 watchdog 持续收到 401 错误。目前 dsh-web-startup-auth 的配置文件中没有提供放行 /health 的配置字段。

因此，不建议同时安装这两个插件。请根据需求二选一：

安全提醒：dsh-lan-access 无内置认证，仅限家庭/公司可信内网使用。任何暴露 0.0.0.0 的方案都应叠加 Tailscale/VPN/反向代理等安全措施。

11. 最短路径（快速上手）

Node 22.19+ / 24+ → 设置 npm 镜像 → npx @deepseek-ai/dsh web → 填 API Key → 在工作区选择器中手动输入项目路径或安装插件选择 → 标准模式开写

三、社区桌面客户端对比

如果你希望零命令行、开箱即用，社区提供了多个优秀的桌面客户端方案。以下按热度排序：

1. anywhere-labs / dsh-desktop（当前最热门）

• GitHub Stars：19.7k（截至 2026 年 8 月）
• 技术栈：基于 Electron 构建，将 DeepSeek Harness 打包为原生应用
• 支持平台：Windows x64、macOS Universal

• 核心特点：

  • 内置插件市场（DSH Community Market），可视化浏览和安装插件
  • 远程相关能力：生态中包含 Agents-Anywhere 等远程控制方案
  • 完全开源免费，遵循 MIT 协议
  • 独立的社区项目，与深度求索无官方隶属关系
• 下载方式：官网 dshdesktop.cn 下载安装包

2. dsh-tauri-desk / deepseek-harness-desktop（轻量首选）

• GitHub Stars：1.1k（截至 2026 年 8 月）
• 技术栈：基于 Tauri 2 构建（Rust + WebView），安装包极小（约 5MB）
• 支持平台：Windows 10+、macOS 10.15+、Linux（AppImage/.deb）

• 核心特点：

  • 零环境依赖：无需安装 Node.js、pnpm 或 Docker
  • 内核自动更新：应用内同步上游最新 Harness 版本
  • 档案隔离：支持多份配置（档案）独立管理插件和设置
  • 预设插件：首次启动引导安装推荐插件（如 DSH Market、Better Sidebar）
  • 支持 Homebrew 一键安装：brew install dsh-tauri-desk/desktop/deepseek-harness
• 注意：项目采用 MIT 协议附加非商用条款，使用前请留意

3. 生态中其他方案

此外还有 dataelement/dsh-desktop（2.2k Stars）等多个 Electron/Tauri 封装方案，用户可按需探索。

两者对比

选择建议：

• 追求生态丰富度和社区热度 → 选择 anywhere-labs/dsh-desktop
• 追求极致轻量、跨平台（含 Linux）和零环境配置 → 选择 dsh-tauri-desk/deepseek-harness-desktop

提醒：以上桌面客户端均为非官方社区项目，下载时请认准 GitHub 官方仓库或官网，避免使用第三方镜像源。

四、DeepSeek-Reasonix：另一款终端智能体

DeepSeek-Reasonix 是独立于 DeepSeek Harness 之外的另一个开源项目，由社区团队 esengine 开发。

核心定位

• 终端优先的 AI 编程智能体：专为命令行环境设计，提供交互式编码辅助
• 单一 Go 二进制文件：CGO_ENABLED=0 静态编译，无需任何依赖
• 面向长期运行优化：围绕 DeepSeek 模型的 prefix-cache 稳定性进行工程优化，支持长时间后台运行

主要特点

• 四种入口统一引擎：可通过终端/TUI、桌面应用、浏览器或编辑器（通过 ACP 协议）使用
• 配置驱动：所有模型、工具和插件均在 reasonix.toml 中声明
• 多模型可组合：支持同时运行执行器和规划器两个模型
• 缓存感知的上下文管理：智能裁剪和压缩上下文以保持高性能
• 内置沙箱与检查点：支持计划模式、权限控制和每步检查点，便于回溯

安装方式

1
2
3
4
5
6
7
8
9

# 通过 npm 全局安装（拉取预编译二进制）
npm i -g reasonix
 
# macOS 通过 Homebrew
brew install esengine/reasonix/reasonix
 
# 快速开始
reasonix setup   # 配置提供商和模型
reasonix         # 启动交互会话

与 DeepSeek Harness 的关系

二者是独立的平行项目，并非上下级或衍生关系：

• DeepSeek Harness：官方出品，插件化 Agent 编排平台，侧重框架通用性和生态扩展
• DeepSeek-Reasonix：社区项目，终端专属 AI 编码助手，侧重单任务性能和长时间稳定性

如果你需要在终端中高效地辅助编码，Reasonix 是一个轻量而强大的选择；如果你需要构建复杂的多 Agent 工作流或自定义界面，DeepSeek Harness 及其桌面客户端更合适。

总结

AI