DeepSeek Harness 入门：从「一切皆插件」到第一个 Agent 任务

让 AI 解释一段代码，和让它读懂一个项目、修改文件、运行检查，是两种不同的体验。模型决定它如何理解问题，围绕模型构建的运行环境，则决定它能接触什么、怎样行动，以及如何把任务继续做下去。

DeepSeek Harness 把后面这部分做成了一个可组合的开源项目。 这篇文章从概念出发，带你完成启动、配置和第一个任务，并用博客维护场景说明如何判断结果是否可靠。

DEEPSEEK HARNESS · 入门指南

先理解运行环境，再让 Agent 动手

01 理解 Harness 与插件　／　02 启动与配置模型
03 完成一个小任务　／　04 检查结果与排查问题

资料核对：2026-09-14 · 面向开发者预览版 · 本文为官方资料整理与实践建议，非性能实测

01 · DeepSeek Harness 是什么？

DeepSeek Harness，命令简称 dsh，是 DeepSeek 官方开发的开源 Agent Harness，采用 MIT 许可证。截至本文资料核对日期，它仍处于开发者预览阶段，官方明确提示后续可能出现破坏兼容性的变更。官方仓库

可以把 Harness 理解为 Agent 的运行与协作环境。例如，你提出“修复网站里的一张失效图片”：模型需要判断问题，运行环境则提供读取文章、编辑路径、执行构建和记录过程的能力。两者配合，任务才有机会从一句回答变成一个可检查的改动。

这也解释了为什么“换一个更强的模型”并不总能解决所有问题。文件能否被正确找到、工具结果是否完整、上下文是否清晰，都可能影响任务的最终结果。这是本文对开发流程的理解，并非对某个模型的性能结论。

02 · 为什么强调「一切皆插件」？

DeepSeek Harness 以 Cordis 为底层框架。模型适配、工具注册、会话记录，甚至 Agent 循环本身都由插件提供；插件通过服务、事件等机制协作，开发者可以从配置层替换这些组件。架构说明

从使用者角度，可以把它分成三层来看：

层次	负责什么	你关心的问题
Cordis 内核	管理插件生命周期与依赖关系	能力能否正确装配起来？
能力插件	提供模型、工具、会话、存储等功能	当前任务需要哪些能力？
配置与模式	组合当前运行时的能力	这次任务该使用哪种组合？

官方还提供 Trajectory（运行轨迹）：通过追加式会话日志查看工具调用、返回结果及上下文注入等记录。排查问题时，除了看最终回答，还可以追问“它读了哪个文件”“哪一步返回了错误”。产品介绍

四种模式怎么选？

模式	特点	本文建议的起点
Standard	完整的编程 Agent 工具集合	首次体验、读项目和常规修改
Code	通过代码组织多步工具调用	理解基本流程后，探索工具编排
Minimal	主要保留 shell 与文件编辑工具	研究简化工具环境下的表现
Creator	运行时检查、插件实验与预设创建	希望开发插件或定制模式时

模式能力依据官方说明，右侧为使用建议。第一次体验从 Standard 开始就足够；增加插件前，先让一个小任务完整跑通。

03 · Windows 上手：从启动到工作区

官方当前将该项目标记为实验性软件，尚未经过安全审计。首次体验建议使用测试项目副本或专用环境，避免直接授予整个磁盘的访问权限。审批和沙箱能降低风险，但不等于完全隔离。官方安全说明

第一步：确认 Node.js 环境

在 VS Code 终端中检查：

node --version
npm.cmd --version

下面以 Windows PowerShell 为例，使用 .cmd 启动文件，避免部分电脑的脚本执行策略拦截 npm.ps1 或 npx.ps1。其他平台通常直接使用 npm、npx。

第二步：在测试项目目录启动

先用 VS Code 打开你准备好的测试项目，在该项目终端执行：

npx.cmd @deepseek-ai/dsh web

首次运行需要下载 npm 包；如出现安装提示，核对包名为 @deepseek-ai/dsh。官方 README 给出的默认 Web UI 地址是 http://127.0.0.1:3080，实际访问地址以终端输出为准。启动说明

这里安装的是 npm 发布包。只有准备研究 Harness 源码或开发插件时，才需要克隆 Harness 自身仓库；普通体验不必同时走两套安装流程。

第三步：配置模型

打开 Settings → Models，填写并保存 DeepSeek API Key。模型配置页面也支持添加其他内置提供商，以及使用自定义端点接入模型。模型配置文档

初次使用建议先把官方 DeepSeek 路线配置成功。使用第三方网关时，地址、模型 ID 和 API 协议必须互相匹配；仅仅拥有一个 Key，并不能保证请求能被网关正确识别。

第四步：明确选择工作区

点击 Choose workspace，添加并选择测试项目目录。启动命令所在目录不等于已经在界面中选好了工作区；新界面在选定工作区之前，无法正常开始会话任务。Web UI 指南

04 · 第一个任务：用博客练习完整流程

相比一开始就让 Agent 重写整站，我建议从“读懂项目 → 改一个点 → 验证结果”开始。下面是针对 Hexo 博客设计的练习，属于本文给出的任务示例。

先让它理解项目

请阅读这个 Hexo 项目并说明：
1. 文章、固定页面、主题配置分别在哪里；
2. 本地预览和构建命令是什么；
3. 你还需要确认哪些信息。
这一步只阅读和解释，不修改文件。

这一步的价值是校准上下文。如果连文章目录都识别错了，就应先补充信息，再进入编辑阶段。

再给一个范围清楚的小改动

请把我提供的正文整理为一篇 Hexo Markdown 草稿。
保存到 source/_drafts/harness-notes.md。
保留原意，补全标题、摘要、分类和标签。
不要改主题，不要提交 Git，不要发布。
完成后列出新建文件，并说明如何预览草稿。

好的任务描述至少包含四件事：目标、输入、修改范围、验收方式。与其只说“帮我优化”，不如明确到“整理这一篇文章、保持原意、使用现有主题、列出修改点”。

最后由实际结果验收

对于本站这类 Hexo 项目，可以先检查改动，再构建：

git status --short
git diff
npm.cmd run build

git diff 不会展示尚未加入版本控制的新文件正文，因此新建草稿还要在编辑器里打开检查。构建成功也不代表草稿已经显示在普通首页；要预览草稿，可按 Hexo 的草稿机制运行：

npx.cmd hexo server --draft

只有在你决定正式发布时，才把草稿转换为文章，检查分支改动和预览结果后发布。草稿机制可参照 Hexo 写作说明。这个练习的终点是一个可验证的小成果，而不是一次看起来很长的聊天。

05 · 常见卡点，按顺序排查

现象	优先检查
npx 提示禁止运行脚本	Windows PowerShell 下尝试 npx.cmd
网页能打开，但无法开始任务	是否添加并选中了工作区？
提示 MISSING_CREDENTIAL	是否在 Models 页面保存了对应提供商的 Key？
提示 UNKNOWN_MODEL	是否选中了已配置的模型，模型 ID 是否正确？
出现 EADDRINUSE	是否已运行了另一个服务？先检查原来的终端
回答看似完成，却没有正确文件	检查工作区路径、工具返回结果以及实际差异

模型错误名称及处理方向可参照官方排错文档。终端错误优先看第一条明确报错，不必被后面长长的调用栈吓住。

06 · 本地运行意味着什么？

官方数据处理声明将 DeepSeek Harness 描述为本地优先的环境：会话、工具记录和配置等数据默认在本机处理和存储。但连接外部模型、网络工具、MCP 或其他插件时，相关数据可能被发送给相应服务商；声明也提到可关闭或修改上报地址的匿名配置与项目列表上报。数据处理声明

因此，我建议把“是否适合这个项目”拆成两个具体问题：Agent 能访问哪些文件？这些内容会交给哪个服务处理？ 对公开教程和测试仓库，这通常容易判断；涉及客户资料或生产凭据时，就要先厘清数据流向与访问范围。

07 · 怎样判断它对你有没有帮助？

如果你想学习 Agent 如何调用工具、观察执行过程，或尝试组合自己的运行环境，DeepSeek Harness 值得用一个小项目探索。如果当前目标只是写完一篇文章，也可以先沿用熟悉的编辑器流程，把 Harness 当作辅助工具逐步加入。

一次有意义的体验，可以记录这三个结果：

1. 完成度：目标文件是否真的生成，内容是否符合要求？
2. 可检查性：能否说明改了什么、为什么改、怎样验证？
3. 维护成本：下次还能否复现，出错时是否知道去哪里找原因？

当这三个问题都有明确答案时，你才真正了解了这个工具能在自己的工作中承担哪一部分。

---

延伸阅读

• DeepSeek Harness 官方介绍
• 官方源码与启动说明
• Web UI 入门
• 模型配置
• 架构文档
• 安全说明
• 数据处理声明

本文不包含性能排名或未经实测的效率承诺。开发者预览版更新较快，界面、命令与能力请以当前官方文档为准。