DeepSeek Harness 入门操作步骤

2026年8月13日，DeepSeek 正式推出其首款 Agent 产品 —— DeepSeek Harness v0.1 开发者预览版，并同步以 MIT 协议在 GitHub 开源。

官方给出了一个简洁的定义：Model + Harness = Agent。模型负责理解与推理，Harness 负责将模型能力落地到真实环境中，完成从理解需求到交付结果的完整闭环。

一、核心定位与产品形态

Harness 并非一个开箱即用的终端应用，而是一套面向开发者的 Agent 运行基础设施。它内置了项目管理、长周期任务协作、多智能体编排、上下文管理、联网检索与外部技能调用等能力。

目前 v0.1 仍是开发者预览版，启动后通过浏览器访问 http://127.0.0.1:3080 使用，暂无桌面应用。官方在启动时会提示：核心插件和基础接口在未来几个月会快速演化。发布后 12 小时内，其 GitHub 仓库已获得超过 5 万 Star。

在竞争格局上，Harness 的直接对标产品是 OpenAI Codex 与 Anthropic Claude Cowork。但与这些更侧重于“即用型工具”的产品不同，Harness 的差异化在于其底层架构的开放程度——它试图将 Agent 的每一个环节都拆解为可替换的模块。

二、架构设计：“一切皆插件”

Harness 最核心的设计原则是 “一切皆插件”（Everything is a plugin）。

该框架基于 Cordis 插件元框架构建。Cordis 仅负责插件的加载、卸载与依赖关系管理，不承载任何 Agent 的具体能力。模型适配器、工具注册表、会话管理、沙箱实现、Agent 循环乃至用户界面，全部以独立插件形式存在。开发者无需修改 Harness 源码，即可在配置层替换或扩展任一能力。

Cordis 的设计思想源自一篇由北京大学与 DeepSeek 联合署名的论文，其核心概念是“时空可组合性”。“时间”维度指插件卸载后其注册的服务、事件与副作用能够自动撤销；“空间”维度指插件可以声明依赖，并在其他组件变化时重新建立协作关系。根据对公开技术资料的分析，这套机制在工程层面主要通过以下方式实现：

1. 唯一的修改入口：所有对系统状态的修改都必须经由 ctx 上下文对象完成，而 ctx 上的每个操作内部都是副作用追踪的封装。这确保了任何注册行为都会被框架追踪，不存在绕过追踪的路径。
2. 生命周期状态机：每个插件实例带有状态管理。在已卸载的插件上创建副作用会直接抛出异常，从时间上杜绝了资源泄漏。
3. 服务查找机制：访问 ctx 上的服务（如 ctx.tools、ctx.llm）时，通过 Proxy 代&理拦截 访问，沿当前插件层级向上查找服务提供者。作用域隔离由此自然实现：子层可见父层服务，反之则不行。

这套机制的价值在模型适配场景中体现得比较直接：Harness 定义了一份通用的 llm 服务接口，系统内可同时存在多个实现该接口的插件——一个适配 DeepSeek 自家模型，另一个适配第三方模型厂商。上层 Agent 循环无需改动，替换插件即可切换模型提供商。

三、运行模式

Harness 预置了四种运行模式，每种模式默认加载不同的插件集合：

其中，极简模式已被 DeepSeek 用于 Terminal Bench 等基准测试场景。

四、关键机制：轨迹（Trajectory）

Harness 提供了名为 “轨迹”（Trajectory） 的功能，用于解决 Agent 运行过程“黑盒化”的问题。

Agent 运行过程中，模型看到的系统提示词、思维链、工具调用与结果、子 Agent 调度等信息，均以仅追加（append-only） 的格式写入会话日志，而非经过润色的摘要。这些原始事件级记录支持回放与检索，可用于排查任务失败原因与追踪 Token 消耗。

五、使用方式

环境要求

1. Node.js：v22.19 及以上，或 v24 系列
2. 包管理器：源码安装需要 pnpm

快速启动

npx @deepseek-ai/dsh web

命令执行后，浏览器打开 http://127.0.0.1:3080，在设置中配置 API Key 即可使用。

源码安装（适用于二次开发）

git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harnesspnpm installpnpm run buildpnpm dsh web

如果输入 y 后仍然卡住怎么办？

可能的原因和解决方法：

1. 网络问题导致下载慢

   1. npm 默认从国外源下载，如果网络不稳定，下载可能会卡住。
   2. 可以先按 Ctrl + C 终止当前命令，然后切换到国内镜像源重试：

      npm config set registry https://registry.npmmirror.comnpx @deepseek-ai/dsh web

2. Node.js 版本不匹配

   1. 检查版本是否符合要求（v22.19+）：

      node -v

   2. 如果版本过低，使用 nvm 切换到更高版本后重试。

3. npx 缓存问题

   1. 如果多次重试仍卡住，可以清理 npx 缓存后重新执行：

      npx clear-npx-cache# 或手动删除缓存目录：# Windows: rm -rf %LOCALAPPDATA%npx-cache# Mac/Linux: rm -rf ~/.npm/_npx

如果确认后下载成功，但启动后仍然无法使用

检查是否在浏览器中打开了 http://127.0.0.1:3080（部分用户反映会自动弹窗，但有时需要手动打开）。如果端口被占用，可以尝试指定其他端口（如果支持的话）。

亲测：我用 http://127.0.0.1:3080 部分功能有问题，用 http://localhost:3080 才正常！

最省事的做法：在提示处直接输入 y 回车，等待下载完成。通常下载完成后会自动启动服务，终端会显示“Server running at http://127.0.0.1:3080”之类的提示。

Python SDK

Harness 同时提供了 Python SDK，支持在程序中调用和编排 Agent 能力。

设置完模型和密钥后就可以用了，我这里搭配的模型是 GLM5.2

很快就分析完了

在下方可以看到任务消耗的 Tokens、当前的上下文占用、以及整个对话的 Tokens 消耗信息。

暂时还没用它来完成编码工作，这个评测等后面再介绍吧！

这才是v0.1版本，还是很看好它的！

六、现状与适用人群

v0.1 是开发者预览版，生产环境使用需谨慎评估。其界面与交互对非开发者不够友好，目前更适合以下人群：

1. 需要深度定制 Agent 运行时的开发者
2. 希望对比不同模型在相同工具环境下表现的评测者
3. 有意参与插件生态建设的社区贡献者

对于寻找“开箱即用”型产品的普通用户，目前的 Harness 可能尚未达到理想状态。