DeepSeek Harness 入门教程

2026年8月13日，DeepSeek 正式推出其首款 Agent 产品 ——

，并同步以 MIT 协议在 GitHub 开源。

官方给出了一个简洁的定义：

。模型负责理解与推理，Harness 负责将模型能力落地到真实环境中，完成从理解需求到交付结果的完整闭环。

一、核心定位与产品形态

Harness 并非一个开箱即用的终端应用，而是一套面向开发者的

。它内置了项目管理、长周期任务协作、多智能体编排、上下文管理、联网检索与外部技能调用等能力。

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

从竞争格局来看，Harness 直接对上的，是 OpenAI Codex 和 Anthropic Claude Cowork。不过，和这类更偏“拿来即用”的产品相比，Harness 真正拉开差距的地方，在于底层架构足够开放——它的思路不是把 Agent 封装成一个整体，而是把每个环节都拆开，做成可以灵活替换的模块。

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

Harness 最核心的设计原则是

。

该框架基于

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

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

1. 唯一的修改入口
   ：所有对系统状态的修改都必须经由 ctx 上下文对象完成，而 ctx 上的每个操作内部都是副作用追踪的封装。这确保了任何注册行为都会被框架追踪，不存在绕过追踪的路径。

2. 生命周期状态机
   ：每个插件实例带有状态管理。在已卸载的插件上创建副作用会直接抛出异常，从时间上杜绝了资源泄漏。

3. 服务查找机制
   ：访问 ctx 上的服务（如 ctx.tools、ctx.llm）时，通过 Proxy 代&理拦截 访问，沿当前插件层级向上查找服务提供者。作用域隔离由此自然实现：子层可见父层服务，反之则不行。

这套机制的价值，放在模型适配这件事上会显得格外直观：Harness 先定义了一套通用的 llm 服务接口，系统内部则可以并行存在多个实现这一接口的插件——比如，一个对接 DeepSeek 自有模型，另一个负责适配第三方模型厂商。这样一来，上层 Agent 循环本身不需要做任何调整，只要替换对应插件，就能完成模型提供商的切换。

三、运行模式

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

模式	适用场景
标准模式	功能完整的通用开发场景
PTC 模式 （程序化工具调用）	模型生成代码来编排多轮工具调用，适合复杂自动化任务
极简模式	仅保留 Shell 与文件编辑工具，用于模型基准测试与最小化复现
创造模式	运行时检查、内存内调试插件，用于自定义新的运行模式

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

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

Harness 提供了名为

的功能，用于解决 Agent 运行过程“黑盒化”的问题。

Agent 运行过程中，模型看到的系统提示词、思维链、工具调用与结果、子 Agent 调度等信息，均以

的格式写入会话日志，而非经过润色的摘要。这些原始事件级记录支持回放与检索，可用于排查任务失败原因与追踪 Token 消耗。

五、使用方式

环境要求

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

快速启动

npx @deepseek-ai/dsh web

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

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

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

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

可能的原因和解决方法：

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

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

2. Node.js 版本不匹配
   • 检查版本是否符合要求（v22.19+）：

     node -v

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

3. npx 缓存问题
   • 如果多次重试仍卡住，可以清理 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版本，还是很看好它的！

六、现状与适用人群

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

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

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