DeepSeek Harness 开源 45 小时 14 万 Star：一句 npx 跑起你的第一个 Agent

2026 年 8 月 13 日，DeepSeek 在发布 V4-Pro 正式版的同时，一并开源了自己的第一款 Agent 运行框架 —— DeepSeek Harness（dsh）。上线 45 小时 GitHub Star 突破 10.5 万，几天内逼近 14 万。这不是又一个大模型，而是一套让模型「长出双手双脚」的运行时。本文带你从零上手，用一句命令跑起属于你自己的 Agent。

---

一、先说清楚：Harness 到底是什么

很多人第一眼会把它当成「DeepSeek 版的 Claude Code」或者「DeepSeek 版的 Codex」。这个类比对了一半，错了一半。

DeepSeek Harness 官方给出的定位，浓缩成一句话就是：

Model + Harness = Agent

模型负责「理解」和「推理」，Harness 负责把能力落到真实环境里——调用工具、操作终端、读写文件、管理上下文、调度任务、分配子智能体，最终把活干完、交付。换句话说，模型是「大脑」，Harness 是「神经系统 + 手脚」。

它和 Claude Code、Codex 最本质的区别在于开放程度：

• Claude Code / Codex：把模型、工具、沙箱锁死在黑盒里，你拿到的是一个开箱即用的成品。
• DeepSeek Harness：把模型、工具、会话、沙箱、循环、调度、UI 全部做成可插拔的插件，你拿到的是一个可以任意组装的 SDK + 框架。

官方给它的口号叫 「Everything is a Plugin（一切皆插件）」，这个我们下一篇会深入拆解。今天先把它跑起来。

关键信息速览：

项目	说明
仓库	github.com/deepseek-ai/deepseek-harness
协议	MIT（完全开源，可自由二次分发）
语言	TypeScript 为主，附带 Python SDK
底层框架	Cordis（插件元框架）
默认模型	DeepSeek 自家模型，但模型无关，可接 OpenAI / Anthropic / Google 等
状态	开发者预览版（v0.1），官方明确「会有破坏性变更」
入口形态	Web UI / TUI / Headless / ACP / JSON-RPC

---

二、环境准备：你只需要一个 Node.js

DeepSeek Harness 是基于 Node.js 的，所以第一步是确认你的机器上有 Node.js（建议 LTS 版本）。

node -v   # 确认 Node 版本
npm -v

如果还没有，去 nodejs.org 下载安装即可。除此之外不需要任何额外依赖——连模型 API Key 都可以用 DeepSeek 官方的。

---

三、最快上手：一句 npx 拉起 Web UI

官方提供了最省事的启动方式，直接通过 npx 运行：

npx @deepseek-ai/dsh web

这条命令会做三件事：

1. 自动下载 @deepseek-ai/dsh 包；
2. 拉起一个本地 Web UI；
3. 默认监听 127.0.0.1:3080。

启动后，浏览器打开 http://127.0.0.1:3080，你会看到一个光秃秃的对话框——别惊讶，这就是开发者预览版的真实面貌：一个输入框 + 左侧会话历史栏，没有任何花哨的面板。那些让 V4 Flash「变快变强」的智能体工具，全被藏进了内置插件里，需要你自己去调用、去组装。

第一次跑，你需要填一个模型 API Key。默认接的是 DeepSeek 官方模型，配置好 Key 后，在对话框里输入一个任务试试：

帮我看看当前目录下有哪些文件，并统计每个文件的代码行数。

Agent 会调用 shell 工具执行 ls、wc，读文件、跑命令，最后把结果返回给你。这就是一个最小可用的 Agent 循环。

---

四、从源码安装：拿到完整的「洞洞板」

如果只是体验，npx 就够了。但如果你想真正理解它、改造它，还是从源码安装：

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

克隆下来后你会发现一个惊人的事实：这个仓库包含超过 230 个 workspace 成员，代码分布在 packages/、apps/、examples/、python/、native/、vendor/、website/ 等区域。

如果把普通 Agent 项目比作一台「已经装好的电脑」，那么 DeepSeek Harness 更像一块尺寸惊人的洞洞板：

• 文件系统
• 终端
• 子进程
• PTY
• 语言服务器
• 网页访问
• 技能（Skills）
• 子智能体（Subagent）
• 工作流（Workflow）
• 计划模式
• 会话持久化
• 设置
• 凭据
• 遥测

……几乎每一项能力都有一个独立的包。它们都可以插上去，也都可以拔下来。

---

五、四大模式：同一套代码，四种完全不同的形态

这是「一切皆插件」最直观的产品化表达。DeepSeek Harness 预设了四种模式（profile），每种默认加载不同的插件集合：

1. 标准模式（Standard）

提供完整的工具组合，覆盖日常开发场景。读文件、写代码、跑命令、上网搜索、派子智能体分头干活，应有尽有。这是最全的一档，适合「把 Agent 当开发搭子」的日常使用。

2. PTC 模式（Programmatic Tool Calling，程序化工具调用）

这个模式比较有特色：它让模型生成一段代码，用这段代码来组合多轮工具调用。传统 Agent 是一轮一轮地「模型出调用 → 执行 → 回填 → 再出调用」，慢吞吞且费 Token；PTC 模式把多次工具调用打包成一段程序一次跑完，省 Token、速度快。这是 DeepSeek 在工程上很聪明的一处设计。

3. 极简模式（Minimal）

只保留一个 shell 工具 + 一个文件编辑工具，用于最小环境下的模型基准测试。官方 V4 Flash、V4 Pro 公布的 Agent 基准成绩，就是在 Harness 的极简模式下测出来的——这也意味着那些跑分是可复现的。

4. 创造模式（Creator）

这个模式最「元」：Agent 可以检查当前运行时、在内存中试验 Cordis 插件，并据此组合和创作新的模式。选择这个预设后，Agent 能检查当前运行时的插件树，动态挂载或卸载临时插件。换句话说，这是让 Agent「改造自己」的入口，也是通向「自进化 Agent」的关键一步。

四种模式的本质是：底层的模型路由、会话持久化、沙箱和审批仍由共享宿主提供，预设（preset）只决定一个 Agent Context 中具体装入哪些能力。所以同一个 Web UI，可以从双工具的极简 Agent，一路切换成能编排子智能体的标准模式，甚至变成能改装自身的创造模式。

---

六、不止 Web UI：四种入口形态

DeepSeek Harness 的入口远不止网页。它提供四种形态，背后共享同一套核心能力：

入口	形态	适用场景
Web UI	npx @deepseek-ai/dsh web	浏览器交互
Headless	dsh 一次性运行器，完全不带服务器	接任务 → 完成模型与工具轮次 → 打印答案退出
ACP	Agent Client Protocol 服务	被其他 Agent 客户端驱动
JSON-RPC / Python SDK	程序化接口	Python 应用启动会话、发任务、收通知

尤其值得关注的是 Python SDK：它让 Python 应用可以启动会话、发送任务、接收通知，而不必直接嵌入内核。下一篇系列会专门讲。

---

七、上手后你该知道的三件事

1. 它是毛坯房，不是精装房

开发者预览版的界面只有光秃秃的对话框，没有任何 Codex 式的功能面板。对非编程用户极不友好——但这恰恰是它的定位：面向 Harness 开发者，而不是面向普通用户。官方明说「仍在迭代，会有破坏性兼容变更」，生产环境建议等几个稳定版本。

2. 沙箱边界要清楚

Harness 把文件沙箱和操作审批分开，默认预设为「工作区可写、敏感操作询问」，并针对 Windows、macOS、Linux 提供了不同的隔离实现。但官方也明确：这套沙箱主要约束文件操作，网络访问和进程可见性不在其规则范围内。Linux 上基于 Landlock，Windows 原生支持不稳，建议走 WSL2。

3. 它不挑模型

你可以套在 DeepSeek、Anthropic、OpenAI、Google 的任何模型上。甚至本机已装好的 Claude Code、Codex，也能被它「叫过来干活」——只是这个开关默认关着。

---

八、小结与下篇预告

DeepSeek Harness 不是「另一个更好用的 Claude Code」，它回答的是另一个更底层的问题：模型之上，智能体到底该怎么被组织？

它用「一切皆插件」的极端开放，把「智能体循环的定义权」交还给开发者。成品 Agent 只是这套 SDK 的「第一位客户」，真正占据项目中心的是可替换的能力接口、事件驱动的生命周期、权威的会话日志和声明式组合。

下一篇，我会深入拆解它的底层框架 Cordis，讲清楚「一切皆插件」到底是怎么在代码层面落地的——ctx 键、服务与事件、可逆副作用，以及为什么连 Agent Loop 本身都可以被替换。

九、补充：跑通第一个真实任务（完整示例）

光启动 Web UI 还不够，这里给一个「从零到交付」的完整示例，帮你建立对 Harness 工作流的第一印象。假设你的需求是：给一个 Python 项目加一个命令行入口并补充 README。

步骤 1：准备 workspace

mkdir my-demo && cd my-demo
git init
echo "def hello(): return 'world'" > main.py

步骤 2：启动 Harness 并指向该目录

npx @deepseek-ai/dsh web --cwd .

步骤 3：在对话框下达任务

请阅读 main.py，为这个项目创建一个 cli.py 命令行入口（支持 --name 参数），
并在 README.md 里补充使用说明。完成后告诉我改了哪些文件。

步骤 4：观察 Agent 的工作轨迹

你会看到 Agent 依次：

1. 调用文件读取工具，查看 main.py 内容；
2. 调用文件写入工具，创建 cli.py（含 argparse 逻辑）；
3. 写入 README.md；
4. 用 shell 跑一遍 python cli.py --name test 验证；
5. 汇总「改了哪些文件」回报给你。

这五步就是「模型 + Harness = Agent」的完整体现：模型负责决策每一步干什么，Harness 负责把每一步落到文件系统里。没有 Harness，模型只能「说」出 cli.py 应该长什么样；有了 Harness，它真的把文件写出来了。

常见新手卡点速查

现象	原因	解决
启动后页面空白	Node 版本过低	升级到 LTS
提示缺 API Key	未配置 DeepSeek Key	在设置里填入，或设 DSF_API_KEY
模型不回复	网络到模型服务不通	检查代理 / 换模型
工具调用一直转圈	默认 300 秒 Bash 超时	任务太大时拆分

关于「毛坯房」心态的最后一段话

很多新手在第一次打开 Harness 后就关掉了，理由是「不如 Claude Code 好用」。这个判断没错，但结论下早了。Harness 的价值不在「打开那一刻」，而在你用它组装出第二个、第三个自己的 Agent之后。

打个比方：Claude Code 像叫外卖——快、省事、味道稳定，但你永远吃不到菜单之外的东西；Harness 像给了你一整个厨房——第一顿饭确实做得慢、做得丑，但从此你想吃什么都能做，还能请别人来吃你做的菜。

如果你的目标只是「让 AI 帮我写代码」，外卖够了。如果你的目标是「理解 Agent 是怎么工作的」「造一个属于自己团队的 Agent」，那就系好围裙，从第一顿饭开始。这一篇的四条命令、四种模式，就是你的第一份菜谱。

---

标签：#DeepSeek #AI Agent #Harness #开源框架 #大模型