这东西到底是什么

DeepSeek Harness（简称 dsh）不是一个普通的 AI 聊天界面。它是一个 Agent 运行时框架，核心设计理念是"一切皆插件"（Everything is a Plugin）——模型调用是插件，文件操作是插件，界面也是插件。

这意味着你可以把它拆到骨架，再按自己的需求重新组装。它用的底层架构叫 Cordis，只负责插件的加载、卸载和依赖管理，其他什么都不管。

值得一提的是，DeepSeek Harness 开源后成为了 GitHub 上 star 增长极快的项目，截至目前已突破 15 万 star。

说白了：它不是要做一个更好的 ChatGPT 界面，而是要做 AI Agent 时代的操作系统。

---

安装部署

环境要求

只有一个硬性前提：Node.js ≥ 22.19.0（22.x 线），或 24.x 及以上。

node -v
# 需要看到 v22.19.x 或更高

如果版本不够，去 nodejs.org 下载 LTS 版本，或者用 nvm 切换：

nvm install 22
nvm use 22

⚠️ 这里有个坑：很多人系统里装的是 Node 18 或 20，直接跑会报错但错误信息不明显。先确认版本再动手。

---

方式一：npx 一键启动（推荐尝鲜）

最快的方式，不需要全局安装任何东西：

npx @deepseek-ai/dsh web

第一次运行会问你是否下载这个包，输入 y 回车。下载完成后服务自动启动，终端会打印访问地址，默认是 http://localhost:3080。

优点：零配置，一行命令即用
缺点：每次都要检查更新，不方便日常高频使用
适合：第一次体验、快速验证

---

方式二：全局安装（日常使用推荐）

如果确定要长期用，全局装一次更省心：

npm install -g @deepseek-ai/dsh

验证安装：

dsh --version

启动：

dsh web

优点：命令短，启动快，不重复下载
缺点：需要手动 npm update -g 更新
适合：日常开发、频繁使用

---

方式三：源码安装（插件开发者 / 深度定制）

想改源码、写插件、或者就是想看看里面怎么实现的：

# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 安装依赖（项目用的是 pnpm）
pnpm install

# 3. 构建（不能省略！）
pnpm run build

# 4. 启动
pnpm dsh web

⚠️ pnpm run build 必须执行，否则 Web 页面缺少构建产物，界面会异常。

优点：可以改任何东西，插件开发必备
缺点：步骤多，需要熟悉 pnpm
适合：开发者、贡献者

---

方式四：Docker 部署（服务器 / 隔离环境）

适合不想污染宿主机环境，或者部署在远程服务器上：

docker run --rm -it \
  --name deepseek-harness \
  -p 127.0.0.1:3080:3080 \
  -e DEEPSEEK_API_KEY="你的密钥" \
  -v deepseek-harness-home:/home/node/.dsh \
  -v "$PWD:/workspace" \
  alliot/deepseek-harness:latest

或者用 Docker Compose：

git clone https://github.com/xxx/deepseek-harness-docker.git
cd deepseek-harness-docker
cp .env.example .env
# 编辑 .env 填入 DEEPSEEK_API_KEY
docker compose up -d

优点：环境隔离，适合服务器部署
缺点：社区维护的镜像，更新可能滞后
适合：运维、团队共享、CI/CD 集成

---

方式选择速查

你是谁	推荐方式	一句话理由
第一次听说，想试试	npx	一行命令，不行就删
确定要用，日常开发	npm 全局安装	命令短，启动快
想写插件 / 看源码	源码安装	完整控制权
部署到服务器	Docker	隔离干净
不想碰命令行	桌面版	下载 deepseek-harness-desktop，双击即用

桌面版值得单独一提：社区做的开源项目 anywhere-labs/deepseek-harness-desktop，13k star，Win + macOS 都有现成安装包。 对不想折腾命令行的人来说这是最省心的选择。

---

首次配置（三步走）

安装完启动后，打开浏览器进入界面：

1. 配置 API Key

设置 → 模型 → 在 DeepSeek 卡片输入你的 API 密钥 → 保存。

密钥来源：https://platform.deepseek.com
密钥格式：sk-xxxxxxxxxxxxxxxxxxxxxxxx
存储位置：$DSH_HOME/.credentials.yaml（本地加密存储，界面只显示脱敏形式）

保存后模型路由立即可用，不需要重启。

💡 除了 DeepSeek 官方模型，也支持 Anthropic、OpenAI、或任何 OpenAI 兼容接口。在同一个模型设置页添加即可。

2. 选择工作区

点击「选择工作区」→ 添加你想让 Agent 操作的项目目录 → 选中。

⚠️ 不选工作区，会话输入框是灰的，无法对话。
   这是新手最常遇到的"Bug"——其实不是 Bug，是没选工作区。

3. 选模型 & 模式

模型选择：

• V4 Flash：速度快，费用低，适合日常编码
• V4 Pro：能力强，适合复杂推理和架构设计

运行模式（四种）：

标准模式     → 新手首选，安全稳定
计划模式     → Agent 会先制定计划再执行
自动模式     → 减少人工确认，适合信任度高的任务
创造模式     → 给插件开发者的高级入口，新手别碰

第一次运行建议用标准模式。 让 Agent 熟悉工作区后再逐步交付真实任务。一个好的起手任务是：Summarize this repository and identify its main packages.

---

常用命令速查

命令	用途
dsh web	启动 Web UI
dsh --profile headless "任务描述"	无头模式，跑完任务打印结果退出（适合 CI）
dsh plugin --profile web add <包名>	安装插件
dsh --profile web --dump-config	查看当前完整配置

---

插件推荐：哪些值得装

Harness 的插件生态正在快速膨胀——已经有 1900+ 个社区插件。 但质量参差不齐。以下是我按实际用途筛选的推荐，不按 star 数排序，按你真正需要的顺序排：

---

第一梯队：装完体验直接起飞

1. ModLens ⭐1274

解决的问题： DeepSeek 模型是纯文本的，不能"看"图片。ModLens 让你直接粘贴图片，它会自动提取结构化信息（OCR + 版面分析 + 语义理解）输出给模型。

没有 ModLens：截图 → 手动描述给 Agent → 信息丢失
有了 ModLens：截图 → 粘贴 → Agent 直接理解图片内容

对于前端开发、设计稿还原、文档处理场景，这是必装项。

2. dsh-web-ui ⭐1312

解决的问题： 原版界面……确实简陋。这个插件给你加上任务看板、Git 可视化、Token 实时统计、皮肤中心。

不是花哨，是真正提升信息密度——你能一眼看到 Agent 在干什么、花了多少 Token、改了哪些文件。

3. dsh-context-doctor

解决的问题： 模型上下文窗口是有限的。这个插件帮你优化上下文使用——哪些信息该塞进去，哪些该精简，避免"喂太多无关内容导致模型犯蠢"的问题。

---

第二梯队：根据工作方式选装

4. DSH-better-sidebar ⭐702

把侧边栏变成完整 IDE 工作台：文件编辑、终端、Git 面板、子代理管理。 如果你不想在 Harness 和 VSCode 之间来回切换，装这个。

5. dsh-TUI ⭐643

给 Claude Code / Cursor 用户的过渡方案。全屏终端风格，流式 Markdown、会话恢复、模型切换。 如果你更习惯命令行而不是网页，选这个替代 Web UI。

6. dsh-notification

极其简单但极其实用。 Agent 跑长任务时你不知道它什么时候结束——这个插件在任务完成、报错、阻塞时发桌面通知。

额外 Token 消耗：0
额外配置：授权浏览器通知 → 测试 → 搞定

适合把 DSH 当后台工作台常驻的人。

7. dsh-browser ⭐64

让 Agent 操控真实 Chrome——保留登录状态和 Cookie，用结构化文本控制网页。 做爬虫、自动化测试、需要登录态操作的场景必备。

---

第三梯队：特定需求

插件	Star	一句话说明
dsh-vision-toolkit ⭐267	比 ModLens 更全的视觉工具箱：长截图 OCR、UI 还原、意图问答
dsh_workflow ⭐49	多 Agent 调度保存为工作流，支持中断恢复、成本追踪
dsh-chat-import ⭐14	从 Claude Code / Cursor / ChatGPT 无损导入聊天记录，可续聊
dsh-custom-tool	在设置页里造自己的工具，最有 Harness 特色的插件
dsh-find-plugin ⭐7	会话里直接搜插件，关键词搜索 + 一键安装命令

---

我的推荐组合

最小可用组合（体验升级最大化）：
  ModLens + dsh-web-ui + dsh-notification

开发者全家桶：
  ModLens + DSH-better-sidebar + dsh-browser + dsh-custom-tool

极简终端党：
  dsh-TUI + dsh-notification + dsh-context-doctor

---

插件安装方法

统一用 dsh plugin 命令：

# 安装插件
dsh plugin --profile web add <插件包名或 GitHub 地址>

# 安装后重启生效
# Ctrl+C 停止 → dsh web 重新启动

更多社区插件可以在这些地方发现：

• GitHub Topic：github.com/topics/dsh-plugin
• 插件市场：dshget.com（1900+ 插件，支持分类浏览）
• 或者直接装 dsh-find-plugin，在对话里搜

---

安全提醒

这段话值得单独强调：

DeepSeek Harness 的插件可以接触：
  ✓ 文件系统
  ✓ 网络
  ✓ 浏览器
  ✓ 终端
  ✓ 会话内容

能力越深，权限越深。

我的习惯：

1. 先看 README 和最近提交
2. 优先固定 tag 或 commit 安装（不用 latest）
3. 新插件先拿一个单独 Profile 试装，别直接挂主力工作区
4. 浏览器类和自定义工具类插件尤其注意

---

常见坑汇总

症状	原因	解决
输入框是灰的，打不了字	没选工作区	点击「选择工作区」添加目录
对话报错	API Key 没填或余额不足	去 platform.deepseek.com 检查
npx 执行后无反应	Node 版本太低	确认 node -v ≥ 22.19.0
界面异常 / 白屏	源码安装漏了 build 步骤	执行 pnpm run build
想换模型但没效果	只改了输入框没加提供方	设置 → 模型 → 添加自定义提供方
Python SDK 在 Windows 跑不起来	官方不支持 Windows	仅支持 Linux 和 macOS (14+, Apple Silicon)

---

最后

DeepSeek Harness 目前还处在"能跑，但不够丝滑"的阶段。 界面不如 Claude Code 精致，稳定性不如 Cursor 成熟，开箱即用的体验也没有那么顺滑。

但它的价值不在于"今天就替代你现有的工具"，而在于：

它把 Agent 的每个零件都拆开给你看，并且允许你替换它们。

模型可以换、界面可以换、工具可以换、调度逻辑可以换。这种架构级的开放性，在目前的 AI 工具中是独一份的。

如果你只是想要一个好用的 AI 编程助手，今天可能 Cursor 或 Claude Code 更顺手。但如果你想理解 Agent 到底是怎么工作的，或者想在上面构建自己的东西——Harness 是目前最值得投入时间的平台。

三步复习：
1. 确认 Node.js ≥ 22.19
2. npx @deepseek-ai/dsh web
3. 配 Key → 选工作区 → 开始对话

五分钟就能跑起来。剩下的，边用边探索。