2025 年以来，Agent（智能体）赛道卷出新高度：各家都在卷模型，但真正让模型"落地干活"的，是一个被反复提及的新概念——Harness（运行时框架）。DeepSeek 官方在开发者预览阶段直接开源了自家的答案：DeepSeek Harness（命令行名 dsh），目前 GitHub 已斩获 11.8 万 Star，MIT 协议，源码全开放。

如果你还没听说过它，或者听说过但不知道怎么上手，这篇指南会从背景讲起，带你用一条命令跑起来自己的智能体。

项目地址：https://github.com/deepseek-ai/deepseek-harness
官网：https://deepseek.com/harness/

一、背景：AGENT = MODEL + HARNESS

DeepSeek 官网首页挂着一个非常直白的公式：

AGENT = MODEL + HARNESS

翻译过来就是：一个真正能干活的智能体 = 大模型（灵魂）+ 运行框架（身体）。

  • 模型再聪明，它也只是一个"会思考的大脑"，没有手（工具调用）、没有眼睛（环境感知）、没有记忆本子（会话与存储），干两步就断了；
  • Harness 就是给这个大脑装上身体：让它能读文件、跑命令、调用工具、规划任务、持续工作几小时不掉链子。

过去一年，Claude Code、Codex CLI 这类产品的爆火让大家意识到：拉开 Agent 体验差距的，往往不是模型本身，而是外面的这层 Harness。于是 DeepSeek 把自己的 Harness 直接开源了，而且做得非常彻底——一切皆插件。

二、DeepSeek Harness 是什么？

一句话定义：DeepSeek Harness（dsh）是 DeepSeek AI 官方开发的开源 Agent 运行框架，采用"一切皆插件"架构，由 Cordis 内核驱动。

2.1 什么是一切皆插件？

传统 Agent 框架（比如早期的 LangChain 应用）都是"焊死"的：模型接入方式、工具列表、会话存储写死在代码里，想换个模型、加个工具，得改源码。

而 dsh 里，所有 Agent 能力统统是插件：

能力在 dsh 中的形态
模型（DeepSeek/OpenAI/自定义端点）插件，可替换
工具（Shell、文件编辑、检索）插件，可增删
技能（Skills）插件
会话管理插件
沙箱（安全隔离）插件
存储插件
任务循环与调度插件
甚至是 Web UI 本身也是插件

内核 Cordis 只干一件事：管理插件的加载、卸载和依赖关系，完全不承载任何 Agent 具体能力。它的设计出自论文《A Programming Paradigm for Spatiotemporal Composability》，对时空可组合性有严格定义。

架构长这样：

配置层（不改源码自由组合）

能力插件层（全部可替换、可重组）

Cordis 内核

服务与事件

服务与事件

插件加载 / 卸载 / 依赖管理

模型接入

工具：Shell/文件/检索

技能 Skills

会话与日志

沙箱与存储

循环与调度

Web UI

preset / 配置文件

对普通使用者的意义：你不用改一行源码，就能在配置层把默认模型换成 OpenAI 兼容的中转端点，或者把整个 Web UI 换成自己的前端——这就是官方口号"Everything is a Plugin"的分量。

2.2 运行有迹可循（Trajectory）

另一个很打动人的设计：模型看到的一切，都会写入"仅追加"（append-only）的会话日志，包括：

  • 系统提示词
  • 思维链（CoT）
  • 每一次工具调用与返回结果
  • 子 Agent 调度过程
  • 每一次上下文注入

在 Web UI 的 Trajectory 视图里可以按来源逐条查看。更重要的是，恢复、分叉、检索、回放共享同一份事件流——相当于给 Agent 装了"黑匣子 + 时光机"，出了问题能完整复盘，跑得好的会话还能 fork 出来继续用。

三、它解决了什么痛点？

传统痛点dsh 的解法
想换模型/加工具要改框架源码一切皆插件，配置层自由组合
Agent 跑飞了不知道它干了什么append-only 会话日志 + Trajectory 视图，全程可回放
框架越来越重，用不上也卸不掉Cordis 内核零业务能力，按需挂插件
想做基准测试，环境被工具污染极简模式只留 shell + 文件编辑双工具
会话断了只能从头再来事件流支持恢复与分叉

简单说：它同时照顾了想开箱即用的普通用户和想深度定制的框架开发者——前者直接用标准模式，后者把 dsh 当乐高玩。

四、快速上手：三步跑起来

4.0 前置要求

  • 已安装 Node.js（npx 需要它）
  • 一个 DeepSeek API Key（在 DeepSeek 开放平台申请，充值即可用）
  • 想让 Agent 干活的项目目录（工作区）

4.1 第一步：一条命令启动

npx @deepseek-ai/dsh web

命令会启动 Web UI，默认地址是 http://127.0.0.1:3080，浏览器打开即可。

小细节：dsh 会把你启动命令时所在的目录作为默认文件系统位置，所以建议先 cd 到你的项目目录再启动。

4.2 第二步：配置模型

打开 Settings → Models：

  1. 在 DeepSeek 卡片的 API Key 输入框里填入你的 Key，保存；
  2. 即时生效，无需重启服务。

安全设计也到位：密钥是 write-only 的，保存后页面只显示打码描述符，真实密钥存放在 $DSH_HOME/.credentials.yaml，配置里只保留引用。

4.3 第三步：选择工作区并发任务

  1. 点击 Choose workspace，把你的项目目录添加进来并选中（不选工作区时，会话输入框是不可用的）；
  2. 新建会话，直接发任务，比如官方示例：

Summarize this repository and identify its main packages.
（总结这个仓库，指出主要包结构）

Agent 会自主读文件、改代码、跑命令、拆解任务、维护计划。涉及危险操作时，Web UI 会按当前权限策略先弹窗征求你的批准，不会闷头乱删。

整条链路走下来不到 5 分钟：

安装 Node.js

npx @deepseek-ai/dsh web

打开 127.0.0.1:3080

Settings 填 API Key

Choose workspace 选项目

会话发任务

Trajectory 复盘

4.4 源码安装（可选）

想改源码或跟进最新提交的开发者：

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

五、四种运行模式：从全副武装到最小核弹

dsh 预设了四种模式（preset），对应不同场景：

模式定位工具配置
标准模式功能完整的编码 Agent文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理、工作流全套
PTC 模式“程序化完成任务”标准模式全能力 + Code Mode SDK，让模型写一段 TypeScript 程序来编排多轮工具调用，长任务更稳
极简模式模型基准测试仅保留持久 bash + str_replace_editor 双工具，环境干扰最小化
创造模式造你自己的 Agent检查当前运行时、内存中试验 Cordis 插件、创作新的 preset

怎么理解？标准模式给日常用，PTC 给复杂长任务，极简给跑分，创造给框架玩家造轮子。四种模式本质上是不同的插件组合 preset，这也再次印证了"一切皆插件"——连运行模式本身都是拼出来的。

六、Python SDK：把 dsh 装进你的程序

不想开 Web UI，想在自己的 Python 程序里调用？官方提供了同版本 SDK：

前置要求：Python 3.10+、Git；系统支持 Linux x64 / Linux arm64 / macOS 14+（arm64）。SDK 自带打包的运行时，不需要系统里装 Node.js（Windows 用户建议先用 WSL 跑）。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

凭证通过环境变量注入；如果模型跑在 OpenAI 兼容代理后面，额外设置 DEEPSEEK_BASE_URL 即可：

export DEEPSEEK_API_KEY=sk-xxxx
export DEEPSEEK_BASE_URL=https://your-proxy.example.com/v1   # 可选

之后就能在代码里调用与 Web UI 同一套 Agent API，把"读仓库、改代码、跑测试"编排进你自己的流水线。

七、不止 DeepSeek：多模型接入

dsh 虽是 DeepSeek 出品，但模型层是插件，天然多厂商：

  • 目录厂商：Settings → Models → Add provider，选 Anthropic、OpenAI 等填 Key 即用；
  • 自定义端点：任何 OpenAI 兼容接口（中转站、本地 vLLM/Ollama 服务等）都能作为 custom provider 接入。

换模型不用重启，下一次请求直接生效——对比某些框架改个 endpoint 要重启全家桶，体验好不少。

八、插件生态与社区

官方明确欢迎第三方插件，约定了 dsh-plugin GitHub topic 便于检索，配套资源包括：

  • GitHub Discussions：提问与交流
  • Discord 社区： https://discord.gg/Ycq5dCaS4
  • 微信公众号：DeepSeek Harness 团队（扫码进群，见仓库 README）
  • 开发者文档：仓库 docs/ 目录，含开发指南与架构文档
  • 社区插件导航： 官网与仓库提供的社区插件入口

想自己写插件的话，从 docs/user/develop/basic/ 的插件开发教程入手即可。

九、注意事项

  1. 开发者预览阶段：官方明说"THERE WILL BE COMPATIBILITY-BREAKING CHANGES"，生产环境慎用，跟进版本要看 changelog；
  2. 密钥安全：Key 只写进 $DSH_HOME/.credentials.yaml，别把它提交进 git；工作区交给 Agent 前最好先 git init，方便随时回滚；
  3. 权限策略：默认会对危险操作弹窗确认，别图省事关掉；
  4. 平台支持：Python SDK 官方当前列明 Linux/macOS；Web UI 方式以官方文档为准，Windows 建议走 WSL；
  5. API 计费：走的是 DeepSeek 开放平台计费，价格以官网实时页面为准。

十、总结

DeepSeek Harness 的开源，把"Agent = 模型 + 框架"这个公式变成了人人可拆解的实物：

  • 对使用者：npx @deepseek-ai/dsh web 一条命令，5 分钟拥有可回溯、可分叉的本地编码 Agent；
  • 对开发者：Cordis 内核 + 一切皆插件，模型、工具、UI 全部可在配置层重组，是研究 Agent 架构的优秀范本；
  • 对生态：MIT 协议 + dsh-plugin topic + 社区运营，起跑姿势相当标准。

11.8 万 Star 不是偶然。与其观望，不如现在就花 5 分钟把它跑起来——毕竟，见过"一切皆插件"的 Agent 之后，你对这个赛道的理解会完全不一样。

仓库：https://github.com/deepseek-ai/deepseek-harness
官网：https://deepseek.com/harness/
Cordis 论文：https://github.com/cordiverse/paper

如果这篇指南帮到了你，欢迎点赞收藏，评论区交流你的 dsh 玩法。

# github # 开源 # DeepSeek
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

状态丢失排障：Claude 持久记忆的跨会话局限与知芽 Notebook Skill 单元记忆如何沉淀可复用知识资产

avatar DeepSeek技术社区
cover

不加一个参数，能力反超旗舰：大模型的“另一半功夫“

avatar DeepSeek技术社区
cover

基于AI agent的智能图书馆

avatar DeepSeek技术社区