一句话认识 DSH：DeepSeek Harness（简称 DSH）是 DeepSeek 开源的微内核 Agent 框架，核心理念是「一切皆插件」。它支持网页 UI、API 模型、Ollama 本地模型，并通过插件扩展联网、识图、文件读写、代码执行等能力，非常适合在本地搭建自己的 Agent 工作台。

💡 阅读提示：本文按「装环境 → 装本体 → 接模型 → 装插件 → 排错」的顺序展开，跟着做即可。命令都可以直接复制粘贴。

0. 先看全局：一张图搞懂安装流程

一、前置环境准备

DSH 依赖 Node.js，要求版本 ≥ 18，Windows / Mac / Linux 全平台通用。

步骤	操作	说明
1	安装 Node.js（≥18）	官网下载安装包，一路下一步即可
2	打开终端，执行 node -v	能输出版本号（如 v20.x.x）就说明环境 OK
3	切换 npm 国内镜像	国内用户强烈建议，避免装插件超时

# 校验 Node.js 版本
node -v

# 切换 npm 国内镜像（可选但推荐）
npm config set registry https://registry.npmmirror.com

⚠️ 小白提醒：如果 node -v 提示「不是内部或外部命令」，说明 Node 没装好或没加入环境变量，重装一次并勾选「Add to PATH」。

二、三种安装方式

三种方式各有适用场景，先看对比再动手：

方式	适合谁	命令	特点
npx 临时启动	只想快速体验	npx @deepseek-ai/dsh web	无需全局安装，关掉终端服务就停
npm 全局安装	长期使用（推荐）	npm install -g @deepseek-ai/dsh	任意目录都能用 dsh 指令
源码编译	二次开发、改内核	见下方代码块	步骤多，适合开发者
桌面版安装包	不想碰命令行的小白	下载 .exe / .dmg 双击安装	独立窗口，详见第三节

方式一：npx 临时启动（最快体验）

npx @deepseek-ai/dsh web

关闭终端后服务即停止，适合先看看长什么样。

方式二：npm 全局安装（推荐长期使用）

# 1. 全局安装
npm install -g @deepseek-ai/dsh

# 2. 校验是否成功（输出版本号即成功）
dsh --version

# 3. 启动网页端
dsh web

启动后浏览器访问：http://127.0.0.1:3080

方式三：源码编译安装（开发者）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web

三、桌面版 vs 网页版 vs 终端版：到底有什么区别

很多人第一次接触 DSH 会疑惑：「不是还有桌面版吗？我该装哪个？」先说结论：它们跑的是同一个 DSH 内核，区别只在「外壳」——也就是你用什么界面去操作它。

3.1 一张表看懂三者区别

对比项	网页版（Web UI）	桌面版（Desktop）	终端版（dsh-TUI）
界面形态	浏览器标签页	独立窗口 App，可固定到任务栏/程序坞	终端里的字符界面
启动方式	终端执行 dsh web，再打开浏览器	双击图标启动，无需终端	终端执行 dsh tui（需先装 dsh-TUI 插件）
是否要装 Node.js	要	一般随安装包内置运行时，通常不用单独装	要
关闭终端后	服务停止，页面失效	不受影响，窗口独立运行	服务停止
插件能力	全部插件可用	全部插件可用（同一套配置集）	全部插件可用
模型配置	设置面板里填 API Key / Ollama	同网页版，设置面板一致	配置文件或命令
适合谁	大多数人、想边看文档边操作	不想碰命令行的小白、日常长期使用	习惯终端、远程服务器、低配机器

💡 关键认知：桌面版不是「另一个 DSH」，它只是把网页版那套界面打包进了一个独立窗口。所以你在网页版里装的插件、配的模型，桌面版里同样生效（前提是使用同一个配置集）。

3.2 桌面版怎么装

桌面版走的是「下载安装包」路线，不需要敲命令：

步骤	操作	说明
1	打开 DSH 官方发布页	在 GitHub Releases 或官网下载页找到 Desktop 版本
2	按系统选安装包	Windows 选 .exe，macOS 选 .dmg（Apple 芯片选 arm64），Linux 选 .AppImage 或 .deb
3	双击安装并启动	首次启动会引导你填 API Key 或选择 Ollama
4	在设置里装插件	装好 dshmarket 后，插件市场直接在窗口内打开

⚠️ 小白提醒：macOS 首次打开若提示「无法验证开发者」，去「系统设置 → 隐私与安全性」点「仍要打开」即可；Windows 若被 SmartScreen 拦截，点「更多信息 → 仍要运行」。

3.3 怎么选：三句话决策

• 不想碰命令行 → 桌面版，装完双击就能用。
• 想折腾插件、长期使用 → 网页版 + npm install -g，生态最全、更新最快。
• 在远程服务器 / 低配机器上 → 终端版 dsh-TUI，几乎不占图形资源。

💡 可以共存：桌面版和网页版可以同时装在一台机器上，它们共用同一份配置目录，插件装一次两边都能用；但不要同时启动两个实例，否则会抢 3080 端口（见第八节排查表）。

三、模型接入配置

打开网页 UI 的「设置」，有两种接入方案，按需二选一：

方案	需要准备	优点	适合场景
API 接入	DeepSeek 开放平台申请的 sk 开头 API Key	开箱即用、模型强	日常使用、追求效果
本地 Ollama	提前部署 Ollama 并拉取模型	离线可用、数据不出本机	隐私敏感、无网络环境

💡 API 接入要点：密钥以 sk 开头，填入密钥与接口地址后，选择 deepseek-v4、deepseek-v4-flash 等线上模型即可。

💡 Ollama 接入要点：适配器选 ollama，地址填 127.0.0.1:11434，再填入模型名称，即可实现离线本地推理。

四、插件基础管理命令

DSH 默认操作 web 配置集，常用命令如下（建议收藏）：

操作	命令
查看已安装插件	dsh plugin --profile web list
新增插件	dsh plugin --profile web add 插件名
卸载插件	dsh plugin --profile web remove 插件名
从 GitHub 安装	dsh plugin --profile web add github:用户名/仓库名
加载本地插件	dsh plugin --profile web add 本地插件路径
导出全部配置备份	dsh --profile web --dump-config > dsh_backup.json
升级 DSH 本体	npm update -g @deepseek-ai/dsh
全局卸载 DSH	npm uninstall -g @deepseek-ai/dsh

五、必装核心插件清单

🎯 安装优先级：先装 dshmarket，之后所有插件都能在网页里一键搜索、安装、更新、启停，不用再反复敲命令。

插件	作用	一句话场景
dshmarket ⭐	可视化插件市场	第一优先装，装完重启 dsh web，设置面板出现「插件市场」
dsh-at-file	文件引用	对话内 @ 本地文件/文件夹，直接读 md、txt、代码
dsh-web-shell	终端工具	授权后 Agent 可执行本地 shell 命令
dsh-web-search	联网搜索	让模型实时检索互联网最新信息
dsh-vision-router	视觉 OCR 识图	截图识别、图片问答、OCR 文字提取
dsh-code-interpreter	沙盒代码	隔离环境跑 Python，做计算、绘图、表格
dsh-context	上下文调试	查看完整上下文，排查长对话遗忘

# 第一优先：安装可视化插件市场
dsh plugin --profile web add dshmarket

⚠️ 装完 dshmarket 记得重启 dsh web，设置面板才会出现「插件市场」入口。

六、推荐可选插件

插件	作用	适合谁
dsh-TUI	终端界面，替代网页 UI	习惯终端操作的用户
session-library	会话归档，分类保存与检索历史对话	对话记录多的用户
dsh-balance	计费监控，统计 token 消耗与余额	API 模式用户
dsh-memory-notes	长期记忆，跨会话记住自定义信息	需要「记住我」的用户

七、新手推荐安装顺序

八、常见问题

现象	原因	解决办法
端口被占用	3080 端口被其他程序占用	dsh web --port 3081 更换端口
桌面版和网页版同时打不开	两个实例抢同一个 3080 端口	关掉其中一个，或给其中一个换端口
插件安装无响应	网络问题	切换 npm 镜像，重启 dsh web 重试
API 调用失败	密钥或地址有误、余额不足	核对 api-key、接口地址，确认余额充足
Ollama 连接失败	服务未启动或端口被拦	确认 Ollama 后台运行，11434 端口无防火墙拦截
权限提醒	shell、代码解释器属高权限插件	不要给陌生第三方插件开放权限
pnpm 缺失报错	未安装 pnpm	npm install -g pnpm
桌面版插件列表是空的	用了不同的配置集	确认桌面版与命令行使用同一个 --profile
`

九、使用小贴士

• 🔄 勤更新：DSH 目前处于预览版本，插件迭代快，定期在 dshmarket 里更新插件。
• 🧩 按需装：一次性大量安装插件会拖慢内核加载速度，用到再装。
• 💾 会备份：导出的 json 备份配置可直接迁移到另一台电脑，一键恢复全部模型与插件设置。