DeepSeek Harness 是 8 月 13 号开源的，四天涨到 13.5 万 Star（135,035 Stars / 13,591 Forks，GitHub API 实测）。

先说清楚：它不是新模型，是一套让模型"能干活"的工程框架。官方把它概括成一句话——

Model + Harness = Agent

这篇文章我按自己上手实测的顺序写：它到底是个啥 → 架构凭什么敢吹 → 四种运行模式 → 最值得说的可追溯日志 → 上手实测的坑 → 跟 Claude Code / Codex 怎么选 → 现在有哪些坑。不想看过程可以直接拉到最后看结论。

---

一、先搞清楚：Model 和 Harness 各管什么

DeepSeek 这个等式拆开就两件事：

• Model：只管思考和推理，别的都不管；
• Harness：管模型之外的一切——工具调用、任务规划、执行调度、沙箱隔离、会话管理、上下文注入。

打个比方，以前你调 DeepSeek API，拿到的是一个"大脑"；现在官方把"手脚和神经系统"也一起给你了，还开源，MIT 协议。

赛道瞄准的是代码智能体，官方定位直接对标 OpenAI Codex 和 Anthropic Claude Code。但注意，DeepSeek 说的是"开发者底层工具"，不是开箱即用的成品——说白了就是给想自己搭 Agent 技术栈的工程师用的。DeepSeek 研究员陈德里公开场合说得更直白：对标 Claude Code，做 DeepSeek Code Harness。

二、架构：一切皆插件，而且没有特权核心

"一切皆插件"要是营销话术，我也不会专门写一篇。这个是真·架构级插件化。底层跑的是 Cordis 插件内核——TypeScript 元框架，出自老牌的 Koishi 聊天机器人生态（其 Cordis 内核已独立演进多年），发布当天还同步了一篇跟北大合作的论文《A Programming Paradigm for Spatiotemporal Composability》。

2.1 什么叫"一切皆插件"

模型、工具、技能、会话、沙箱、存储、Agent 循环、任务调度、UI……全是插件，挂同一个共享上下文里。默认部署一共 159 个插件，llm、session 这种"命根子"和普通插件在设置面板里平起平坐，可以逐个开关。

Cordis 内核只干两件事：

1. 时间可组合性：插件卸载后，它产生的副作用能完整撤销；
2. 空间可组合性：插件的依赖变了，能动态重新处理依赖。

这俩是热插拔的底子。甚至允许 Agent 在运行中自我安装/卸载插件（cordis_define / cordis_run / cordis_stop / cordis_undefine 这一族工具，默认可选开启，激活前要审批）——"自进化"的雏形已经有了。

2.2 能力都走"接缝"，不写死

Harness 文档把每个能力切成三层：服务定义（接口契约）→ 服务提供者（可替换实现）→ 消费者。消费者从不直接 import 某个具体实现，只依赖稳定上下文键上的服务：

服务	上下文键	职责
Session	ctx.sessions	只追加事件日志与存储
Tools	ctx.tools	工具作用域注册与执行
Agent	ctx.agents	Agent 接口与生命周期
Agent Loop	ctx.agentLoop	默认循环驱动实现
LLM	ctx.llm	消息词汇表与适配器接缝
System Prompt	ctx.systemPrompt	提示词装配

换一个提供者，效果是全局传导的。文档里有个例子我印象很深：替换文件系统提供者，就能把 Bash、PTY、LSP 全部搬到远程沙箱上跑，一个都不用 fork。

这张架构全景图我盯着看了挺久，核心就一件事：Cordis 内核居中，6 类核心插件从两侧挂载，所有事件最终汇入只追加的会话日志。

2.3 组合发生在配置层，不在代码层

组装靠的是分层覆盖（overlay）：bundle（插件包 + 配置行）→ profile（命名组合，存 harness home 目录）→ home 层补丁 → CLI 覆盖。每一层都能按 ID 打补丁、替换整段配置或插入新配置。

dsh --profile web --dump-config   # 打印最终解析出来的完整配置树

核心 bundle 就三个：

• dsh-base：模型适配器、工具、持久化、沙箱、凭据；
• dsh-web-app：浏览器 UI；
• dsh-headless：无服务端的一次性运行器。

三、四种运行模式，从跑基准到上生产都给你备好了

Harness 不是只有一种玩法，官方内置四种模式：

模式	英文名	说明	适用场景
标准模式	Standard	完整工具组合：文件编辑、Shell、检索、技能、规划、子 Agent、工作流	日常开发、生产级复杂任务
PTC 模式	Code / Programmatic Tool Calling	模型生成 TypeScript 代码，把多轮工具操作合并成一次执行	复杂多步编排、一个 turn 搞定长链路
极简模式	Minimal	只留持久化 Bash + 文件编辑器两个工具	SWE-bench 类基准测试，最大程度排除框架干扰
创造模式	Creator	检查运行时、在内存里试 Cordis 插件、组合自定义模式	框架开发者创作新预设

有个细节值得注意：DeepSeek 自家 V4-Pro-0813 模型卡上的代码智能体基准，就是用 Minimal 模式跑的。也就是说那些 headline 数字测的不只是模型本身，而是"模型 + Harness 极简环境"这套组合的表现——现在这套环境开源了，任何人都能复现。

四、最值得说的一个特性：每一次运行都可追溯

这个特性是社区讨论最多、口碑最好的，也是我自己最吃的一个设计。它不是事后补的日志，而是架构层面的设计不变量：

• 每次运行写只追加（append-only）会话日志：系统提示词、思维链、工具调用与结果、子 Agent 调度、每次上下文注入，全有迹可循；
• "模型可见即记录"是硬约束——任何新的模型可见输入，都必须对应新的日志条目；
• Trajectory 视图按来源分类展示这些记录；
• 恢复（resume）、分叉（fork）、检索（search）、回放（replay）全基于同一条事件流。

有什么用？调试失败运行（精确回放事件序列）、从任意节点分叉试新路径、跨会话查"当时为什么这么决策"、做合规审计。评测、调试、复现，全都靠这份日志兜底。

五、上手实测：一条 npx 命令，但有个坑

5.1 前置要求

• Node.js（唯一硬性依赖，建议 20+ 版本）；

5.2 最快路径

npx @deepseek-ai/dsh web

直接拉起 Web UI，默认地址 http://127.0.0.1:3080。

5.3 源码安装（网上三步法有坑）

网上流传的"克隆 → pnpm install → pnpm dsh web"版本漏了 pnpm run build，不 build 直接跑，UI 是起不来的。官方完整流程：

# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 安装依赖（pnpm 管理，monorepo 结构）
pnpm install

# 3. 构建（这一步不能省！）
pnpm run build

# 4. 启动 Web UI
pnpm dsh web

5.4 配大模型

Web UI 打开后，在 设置 → 模型 里配：

1. DeepSeek 官方模型：选 DeepSeek 卡片，填 API Key 保存即可；
2. 其他提供方：选"添加提供方"，从已安装目录选 Anthropic / OpenAI 等，填 API Key——端点、协议、模型列表目录会自动给你；
3. API Key 安全：Key 只写一次，保存后只显示脱敏描述符，密钥存在 $DSH_HOME/.credentials.yaml，settings 里只留引用；
4. 热生效：模型变更下一次请求就生效，不用重启。

Harness 是模型无关的——模型本身只是一个可插拔插件。官方默认支持 DeepSeek、Anthropic、OpenAI、Bedrock、Vertex、Azure 以及任何 OpenAI 兼容端点（社区统计原生覆盖约 40 家厂商），也可以挂本地 Ollama。

5.5 常用命令速查

npx @deepseek-ai/dsh web          # 启动 Web UI（默认 127.0.0.1:3080）
npx @deepseek-ai/dsh --profile web --dump-config   # 查看最终解析的配置树
# profile 支持 web / headless 等，headless 为无服务端的一次性运行器

六、跟竞品比：三足鼎立，路线完全不一样

6.1 商业三巨头：dsh vs Claude Code vs Codex

三款都是"Model + Harness = Agent"的实现，但底层设计哲学差得挺远：

维度	DeepSeek Harness (dsh)	Claude Code (Anthropic)	OpenAI Codex
定位	可重组的 Agent 运行时/插件底座	开箱即用的高度集成终端 Agent	IDE 插件 + 云端 Workflow
开源	✅ 完全开源（MIT）	❌ 商业闭源 CLI	❌ 核心闭源，CLI 部分开源
架构	Everything is a Plugin（Cordis 内核）	垂直一体化 + 可编程钩子（Hooks）	内核级沙箱 + 多端矩阵
模型绑定	完全解耦，可插拔（约 40 家厂商/Ollama）	强绑定 Claude 系列	强绑定 GPT/Codex 系列
主要界面	本地 Web UI（:3080）、Headless、Python SDK	终端、VS Code / JetBrains、桌面、浏览器	CLI、IDE 扩展、桌面、云端
托管后台 Agent	不提供	✅ 提供	✅ 提供（Cloud）
GitHub PR 工作流	尚未文档化	✅ Actions + issue-to-PR	✅ 云任务 + PR 修复
扩展能力	极高，所有组件（UI/调度/工具/沙箱）可替换	中等，Skills / Hooks / MCP	中等，依赖插件机制
状态追溯	原生只追加日志，可 Replay/Fork/Search	依赖内部上下文压缩策略	依赖 IDE 会话面板
私有部署	✅ 完全本地化运行与模型挂载	❌ 不支持	❌ 不支持
沙箱	可配置（含 Linux Landlock 沙箱）	成熟内置权限系统	内核级 Seatbelt 沙箱
成熟度	开发者预览版，预期有破坏性变更	成熟商业产品	成熟商业产品
成本	V4-Flash 单任务约 ¥0.2 量级	订阅制 + Claude API 成本	订阅制 + GPT API 成本

注：V4-Flash 单任务成本为社区实测量级数据，实际随任务复杂度浮动。

6.2 开源框架阵营：打包式 vs 插件化

把视角放宽到开源 Agent 框架，路线差异更明显：

框架	出品方	架构路线	换模型/换沙箱
DeepSeek Harness	DeepSeek	插件内核，一切皆可换	配置层替换，不改源码
LangChain / LangGraph	LangChain	库 + 图编排	通常要改胶水代码
Microsoft AutoGen	微软	多 Agent 对话框架	中等，需适配
CrewAI	社区	角色/任务编排	中等
OpenHands（原 OpenDevin）	社区	一体化代码 Agent 平台	低，紧耦合

LangChain、CrewAI、AutoGen 基本是"能力打包进单体包"的路子——换个模型可能得重写工具定义，换沙箱更麻烦。Harness 把这些全拆成独立可组合的插件，改配置就行，不用动源码。这俩是结构性的差别，不是优化上的差别。

我把上面这些产品放进「开源 vs 闭源 × 开箱即用 vs 可组合」两个维度里，看下相对站位：

6.3 一句话选型建议

• 要开箱即用、要托管后台、要企业级保障 → Claude Code / Codex；
• 要审计可追溯、多模型混用、深度定制、私有化部署 → DeepSeek Harness（但要接受它还很年轻）；
• 三家的收费模式各不相同，别拿单任务成本直接对标。选型关键看三件事：安全边界需求、模型绑定接受度、要不要二次开发插件系统。

七、客观说：现在有哪些坑

Harness 目前的状态，一句话：架构超前，工程上还嫩。

1. 开发者预览版，破坏性变更预警：README 明说"会有兼容性破坏的变更"，仓库版本 0.1.0-rc.5，连正式 release/tag 都没有。生产环境慎上；
2. 上手门槛不低：profile、bundle、patch 层这些概念得先弄明白，比 Claude Code 的"即装即用"陡峭不少；
3. Token 消耗：部分早期测试者反馈单任务 token 用量偏重。好在 DeepSeek 官方模型缓存命中率很高（有社区实测 V4-Flash 在 dsh 内 99% 缓存命中），实际成本可控；
4. 生态待验证：Cordis 的时空可组合性模型是跟着预览版一起亮相的，大规模插件生态下是不是始终可理解，得时间检验；
5. 基准口径：V4-Pro 的部分代码 Agent 分数是在 Harness 环境内测的（具体见第三节），别拿这些数字和裸模型分数直接比。

八、我的结论

说点我真正在意的：这一手把"谁控制 Agent 架构"这个事挑明了。

开发者这边，你终于不用被某家生态绑死——模型、工具、沙箱、会话日志，全是可替换的。模型厂商那边，以后光比模型强不够了，还得看你把外围执行系统开放到什么程度。DeepSeek 这一手，等于把"框架"也变成了可以开源竞争的武器。

至于插件化的终局是什么，我懒得下结论。反正以现在这个涨势，先跑起来再说。

你要是也装了试了，评论区聊聊你最想换掉哪个插件——我先说，我想把 Web UI 换掉。