摘要：DeepSeek Harness（DSH）是 DeepSeek 开源的 AI Agent 编排框架，核心解决"让大模型从只会说到真正会做"的问题。它通过插件化架构为模型提供文件操作、终端执行、任务编排等实际能力，支持一键部署、四种运行模式（标准/代码/极简/创造），并具备完整的可追溯性。本文详细介绍 DSH 的核心特性、快速部署方法、五大应用场景、运行模式选择以及使用技巧，帮助读者快速上手这一 AI Agent 开发利器。

一、DeepSeek Harness 是什么

1.1 你是不是也遇到过这些问题

如果你用过 DeepSeek 或 ChatGPT 的网页版，大概率遇到过下面这些情况：

痛点	你可能说过的话	影响
AI 只能聊天，不能操作本地文件	“帮我整理一下这个文件夹里的文档” → AI 回复了一大段文字，但啥也没动	干活还得自己来
没法批量处理任务	“帮我把这 50 个文件都总结一下” → 只能一个一个复制粘贴	效率极低
模型只会说，不会做	“帮我跑一下这段代码看看结果” → AI 写了代码让你自己去跑	来回切换累人
复杂任务无法自动拆解	“帮我分析这个项目并写个报告” → AI 只能给你一个大纲	还得自己填肉
多步骤工作流没法串联	“先搜索资料，再写代码，再测试” → 每步都要手动衔接	手动当胶水

根本原因：大模型本身只负责"思考与推理"，它没有"手脚"——不能直接操作你的文件系统、不能执行终端命令、不能自动串联多步骤任务。

1.2 Harness 到底是什么

小白理解：把大模型想象成一个超级聪明的"大脑"，它什么都知道，但被关在一个玻璃房间里——能说话，但不能碰外面的任何东西。Harness 就是给这个大脑装上"手脚和工作台"的那套设备，让它能真正走出玻璃房帮你干活。

DeepSeek 之前只发布了模型本体（大脑），现在终于把 Harness（驾驭）补上了。英文直译为"驾驭"，意思是你能驾驭、控制模型去实际干活。

DeepSeek Harness（圈内简称 DSH）是 DeepSeek 同步开源的 AI Agent 编排底座。它解决了一个最朴素的问题：让大模型从"只会说"变成"真正会做"。

一句话总结：Agent = Model + Harness（智能体 = 大脑 + 驾驭框架）

对比维度	普通 AI 对话（网页版）	传统自动化脚本	DeepSeek Harness
能否操作本地文件	不能	能，但需手写代码	能，AI 自动操作
能否执行终端命令	不能	能，但需手写代码	能，AI 自动执行
复杂任务拆解	只能给建议	完全靠自己写逻辑	AI 自动拆解子任务
多模型切换	不支持	需改代码	配置即可切换
上手门槛	零门槛	需编程基础	一行命令启动
可扩展性	不可扩展	可扩展但成本高	插件化，随装随用

1.3 核心特性一览

DSH 的官网写着一句核心标语：Everything is a plugin（一切皆插件）。以下是三大核心特性：

① 一切皆插件

小白理解：就像搭积木一样——读文件是一块积木、跑命令是一块积木、搜索网页也是一块积木。你需要哪个能力就装哪个，不需要就卸掉，完全按需组合。

所有能力（模型、工具、技能、会话、沙箱、存储、循环、调度、UI）都是可插拔的插件，基于 Cordis 内核管理插件的挂载、卸载和依赖关系。开发者可以在配置中选择、替换或扩展任何能力，无需修改 DSH 源码。

② 每次运行皆可追溯

小白理解：就像飞机的黑匣子——AI 做的每一步操作（看到了什么、想了什么、调用了什么工具、结果是什么）都记录在案，随时可以回放、搜索、分叉和重放。

所有模型可见的内容都记录在只追加的会话日志中：系统提示、推理过程、工具调用与结果、子 Agent 调度、每次上下文注入。在 Trajectory 视图中可以按来源检查这些记录。

③ 多种运行模式

DSH 提供四种预设模式，适应不同场景需求，后续章节会详细介绍。

参考文档：DeepSeek Harness 官网 · 开发者快速入门文档

---

二、快速部署

2.1 环境准备

在部署之前，先确认你的设备满足以下条件：

环境要求	说明	必须？
Node.js ≥ 22.19	推荐安装 22 LTS 稳定版，版本太低会启动报错	是
pnpm 包管理工具	仅源码部署时需要，npx 方式可跳过	否
Git	仅源码部署时需要	否
Chrome / Edge 浏览器	用来打开 DSH 可视化界面	是
大模型 API Key	DeepSeek 全系或 OpenAI 兼容接口均可	是

安装 Node.js：

访问 Node.js 官网下载页面，选择 LTS 版本一键安装即可。

Node.js — 下载 Node.js®

这步在做什么：安装 Node.js 运行环境，DSH 依赖它来启动。

新手提示：安装时确保勾选"Add to PATH"选项，否则后续命令会找不到。安装完成后打开终端输入 node -v，看到 v22.x.x 或更高版本就说明成功了。

2.2 一键启动（npx 方式）

小白理解：这是最简单的启动方式——不用下载源码、不用配置环境，复制一条命令粘贴到终端回车就行。就像用外卖 App 点餐，不用自己买菜做饭，三分钟送到。

第一步：打开命令窗口

按 Win + R，输入 cmd 回车。

第二步：输入启动命令

npx @deepseek-ai/dsh web

耐心等待下载完成。如果下载卡住，请更换网络环境，或改用源码部署方式。

这步在做什么：npx 会自动下载 DSH 最新预览版并启动 Web 服务。

新手提示：首次运行会下载较多依赖包，请耐心等待。如果卡在某一步超过 5 分钟，大概率是网络问题——尝试切换网络或使用代理。启动成功后，浏览器打开 http://127.0.0.1:3080 即可访问。

第三步：打开网页界面

新手提示：如果浏览器没有自动打开，手动在地址栏输入 http://127.0.0.1:3080 即可。

2.3 源码部署（可选）

小白理解：如果你想研究 DSH 底层原理、自己写插件、做二次开发，就选这条路。就像从"吃外卖"升级到"自己做饭"——能完全掌控，但要多花十几分钟。

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

启动后同样访问 http://127.0.0.1:3080。

这步在做什么：从 GitHub 克隆完整源码，安装依赖并编译，然后启动服务。

新手提示：确保已安装 Git 和 pnpm。如果 pnpm 命令找不到，先运行 npm install -g pnpm 安装。

2.4 首次配置四步走

第一次进入网页控制台，DSH 是"空"的——任何能力都没开。下面四步只做一次，做完就能正常用。

① 配置模型 API Key

首先创建一个 API Key 并填入。左侧菜单进入 设置 → 模型，填入你的 DeepSeek API Key 并保存。

这步在做什么：把大模型接入 DSH，让它有"大脑"可以用。

新手提示：API Key 是只写存储的——保存后页面只显示脱敏描述，不会泄露你的密钥。密钥存储在 $DSH_HOME/.credentials.yaml 中。

整体布局很像 Codex，左侧是会话列表，右侧是交互区域。

② 选择工作区

首页点击 Choose workspace，添加你启动 dsh 的项目目录并选中。

新手提示：DSH 默认把所有文件读写、终端执行都锁死，必须手动指定一个文件夹作为"工作区"才会放行。不选工作区，所有工具能力都用不了。这是出于安全考虑——AI 不会越权碰你电脑里的其他文件。

③ 查看插件能力

进入 设置 → 插件配置，可以看到所有内置能力：本地文件读写、Bash 终端、网页搜索、长期记忆、多子 Agent 调度等。预览版默认全开，可按需关闭以节省 Token。

④ 选择会话模式

新建会话时选择预设模式。四种模式详见第四章。

参考文档：快速入门指南 · 模型配置指南

---

三、应用场景

小白理解：下面五个场景是 DSH 最典型的用法，新手可以直接照着试。每个场景都包含"痛点 → 怎么做 → 对话示例"三部分。

3.1 让 AI 帮你审查和重构代码

痛点：拿到一个陌生项目，不知道代码质量如何，手动审查太耗时。

怎么做：把项目文件夹设为工作区，选 Standard 模式，给 AI 一句完整指令，它会自己读代码、诊断、生成新文件。

对话示例：

你：读我的项目，找出潜在 bug 和代码异味，重构关键模块，把新版本放到工作区下"重构输出"文件夹里。

DSH：好的，我先浏览项目结构……
    [读取 src/ 目录下的所有文件]
    [分析 main.ts 中的类型安全问题]
    [分析 utils.ts 中的重复代码]
    发现 3 个潜在 bug 和 5 处代码异味。
    正在生成重构版本……
    [创建 重构输出/main.ts]
    [创建 重构输出/utils.ts]
    重构完成，主要改动：
    1. 修复了 main.ts 第 42 行的空指针风险
    2. 提取了 utils.ts 中的重复逻辑为公共函数
    3. 增加了类型注解

3.2 批量文档摘要一键生成

痛点：几十篇 Markdown 文档需要逐一总结，手动复制粘贴到 AI 对话框效率极低。

怎么做：把文档放进工作区，选 Code 模式，让 AI 自动遍历所有文件并生成摘要。

对话示例：

你：遍历工作区中所有 .md 文档，给每篇写 200 字以内的中文摘要，全部汇总到一份 summary.md 文件中。

DSH：收到，开始遍历工作区……
    [执行 find . -name "*.md" 命令]
    找到 42 个 Markdown 文件。
    [逐一读取并生成摘要]
    进度：10/42…… 25/42…… 42/42
    [创建 summary.md]
    完成！所有摘要已汇总到 summary.md，共 42 篇。

3.3 多模型灵活切换

痛点：不同任务需要不同模型——简单任务用便宜的轻量模型省钱，复杂任务用强力模型保质量，但切换起来很麻烦。

怎么做：在模型设置中添加多个 Provider，会话中随时切换。

对话示例：

你：帮我用 V4 Flash 快速翻译这个文档，然后用 V4 Pro 润色翻译质量。

DSH：好的。
    [切换到 deepseek-v4-flash 模型]
    [读取 document.md，完成初步翻译]
    初步翻译完成。
    [切换到 deepseek-v4-pro 模型]
    [读取翻译结果，进行润色优化]
    润色完成，已保存到 document_translated.md。
    Flash 翻译消耗 Token: 3,200（约 ¥0.02）
    Pro 润色消耗 Token: 5,800（约 ¥0.12）

3.4 后台无人值守自动化

痛点：有些任务不需要盯着看，但又必须跑完——比如定期数据抓取、批量文件转换。

怎么做：DSH 支持 headless 模式，终端下一行命令，AI 在后台自动跑，文件直接落到工作区。

对话示例：

# 后台模式执行任务，不打开浏览器
npx @deepseek-ai/dsh run "读取工作区中的 sales.csv，按月份汇总销售额，生成图表并保存为 report.html"

DSH：[后台执行中]
    [读取 sales.csv]
    [按月份聚合数据]
    [生成图表]
    [创建 report.html]
    任务完成，结果已保存到 report.html。

3.5 安装社区插件扩展能力

痛点：DSH 内置能力不够用，需要 PDF 解析、表格处理、数据库对接等额外能力。

怎么做：从社区插件市场找到需要的插件，放入项目目录重新编译即可（仅源码部署支持）。

对话示例：

你：我需要解析 PDF 文件，有现成的插件吗？

DSH：社区插件市场中有 PDF 解析插件。
    安装方法：
    1. 访问 https://github.com/topics/dsh-plugin
    2. 找到 dsh-plugin-pdf-parser
    3. 克隆到项目的 plugins/ 目录
    4. 运行 pnpm run build 并重启 DSH
    安装后你就可以直接让我读取 PDF 文件了。

新手快速上手路径	做什么	预计耗时
第 1 步	安装 Node.js 22 LTS	3 分钟
第 2 步	运行 npx @deepseek-ai/dsh web	2 分钟
第 3 步	配置 API Key + 选择工作区	2 分钟
第 4 步	选 Standard 模式，发第一条指令	1 分钟
第 5 步	尝试一个应用场景	5 分钟

参考文档：社区插件市场 · 插件开发指南

---

四、运行模式详解

DSH 提供四种运行模式，新建会话时可以按需选择：

模式	定位	工具集	适用场景
标准模式 (Standard)	全能型，日常首选	文件编辑、Shell、文件/网页搜索、技能、规划、目标、子 Agent、工作流	代码开发、项目分析、日常任务
代码模式 (Code)	批量自动化	标准模式全部能力 + Code Mode SDK，用 TypeScript 程序编排多步操作	批量文件处理、数据管道、自动化脚本
极简模式 (Minimal)	省 Token 的最小环境	仅保留 Shell 工具和文件编辑器 (str_replace_editor)	模型基准测试、Token 敏感场景
创造模式 (Creator)	高阶玩家专属	标准模式全部能力 + 运行时检查、插件实验、预设编写	创建自定义 Agent 预设、开发新插件

小白理解：

• 标准模式 = 全套工具箱，啥都能干，新手直接选这个
• 代码模式 = 给 AI 一个编程环境，让它自己写代码来编排复杂操作
• 极简模式 = 只给 AI 一把螺丝刀和一个记事本，最省资源
• 创造模式 = AI 实验室，可以调参数、试插件、造新模式

参考文档：开发者文档 - 运行模式 · GitHub 仓库

---

五、使用技巧与最佳实践

5.1 用户痛点速查表

痛点	典型表现	影响程度
Node 版本太低	启动直接报错，提示版本不兼容	高 — 无法启动
API Key 填错	模型请求一直转圈，无响应	高 — 无法使用
工作区未选择	文件读写没反应，工具能力不可用	高 — 功能受限
网络不稳定	npx 下载卡住，依赖安装超时	中 — 部署受阻
源码改了不生效	修改代码后行为没有变化	中 — 调试困惑
升级后旧任务报错	升级 DSH 后之前的会话无法恢复	中 — 数据丢失风险

5.2 常见报错速查表

报错信息	根因	快速修复
Node version too low / 启动失败	Node.js 版本低于 22.19	升级到 22 LTS 或更高版本
MISSING_CREDENTIAL	模型 API Key 未配置或环境变量缺失	在 设置 → 模型 中重新填入 Key 并保存
UNKNOWN_MODEL	选择了未配置的模型	选择已配置的模型，或在自定义 Provider 中添加该模型
模型请求一直转圈	API Key 或 BaseURL 错误、网络不通	检查 Key 和 URL，先用轻量模型（如 Flash）测试
文件读写无反应	工作区未授权	回到首页重新选择工作区目录
Fetching available models returns 401	API Key 无效或无权限	检查 Key 是否正确，手动输入模型列表
图片被拒绝发送	模型未声明图片输入能力	在 settings.yaml 中为模型添加 input: [text, image]
源码修改不生效	未重新编译	运行 pnpm run build 并重启 DSH

5.3 通用排查命令

遇到问题时，按以下顺序排查：

# 1. 检查 Node.js 版本（需 ≥ 22.19）
node -v

# 2. 检查 DSH 是否正常运行
# 查看 http://127.0.0.1:3080 是否可以访问

# 3. 检查 API Key 是否有效
# 进入 设置 → 模型，确认 Key 已保存且显示脱敏描述

# 4. 检查工作区是否已选择
# 首页应显示当前工作区路径，否则点击 Choose workspace 重新选择

# 5. 源码部署：重新编译
pnpm run build

# 6. 查看凭据存储位置
# 密钥存储在 $DSH_HOME/.credentials.yaml
# 设置存储在 $DSH_HOME/settings.yaml

5.4 使用注意事项

重要提醒：DSH 当前为开发者预览版（Developer Preview），以下事项务必注意：

1. 不要用于生产环境 — 接口随时可能变更，存在破坏性更新，仅适用于技术学习、功能探索和 Agent 预研实验
2. 工作区不要放敏感数据 — DSH 有终端执行能力，存在操作风险
3. 升级前看更新日志 — 预览版迭代快，避免踩到接口变更的坑
4. 实验项目建议锁版本 — 不要每次都追最新，避免已有任务因升级而报错
5. 开源协议为 MIT — 可自由体验、学习及实验性商用探索

参考文档：模型配置排障 · 插件配置目录

---

六、总结

DeepSeek Harness 把"给大模型装上手脚"这件事做成了一个开箱即用的底座——以前要写一堆胶水代码才能让 AI 真正去跑事，现在一行 npx @deepseek-ai/dsh web 命令三分钟就能跑起来。

部署方式	适合人群	上手时间	能力
npx 一键启动	零基础体验	3 分钟	全部内置能力，不可改源码
源码部署	开发者/折腾党	30 分钟	可改源码、写插件、深度定制

适配人群：Agent 开发者、前线部署工程师、后端开发者、AI 技术爱好者、大模型落地实践者。

不管你是开发者、爱好者、还是单纯好奇，DSH 都值得花一晚上玩一下——它是少有的能让你零门槛、零风险、零成本体验真实 AI Agent 的工具。

相关资源：

• GitHub 仓库：deepseek-ai/deepseek-harness
• 开发者文档：deepseek-harness.github.io
• 社区插件：github.com/topics/dsh-plugin
• 官网：deepseek.com/harness