稀饭

DeepSeek Harness 深入浅出：官方智能体执行层为什么「一切皆插件」

DeepSeek 官方开源的 agent harness（dsh）全解析：Model + Harness = Agent 公式、Cordis 驱动的「一切皆插件」架构、Profile 与 Agent Preset 两层组合系统、先记录意图再执行副作用的 Agent Loop、「模型可见即已记录」的硬规则与压缩不删历史的上下文管理，以及四个预设、两条运行命令和开发者预览的现状。

  • AI
  • DeepSeek
  • Agent
  • Harness
  • 开源项目
  • Cordis
  • dsh

2026 年 8 月 12 日，DeepSeek 在 GitHub 上开源了 DeepSeek Harness（仓库：deepseek-ai/deepseek-harness，命令简称为dsh）。这是 DeepSeek 官方自研的开源 agent harness（智能体执行框架）。在开源之前， DeepSeek 已经在 V4-Flash 正式版的官方基准里，以「Harness 极简模式」跑 Agent 能力， 又内测过近百位开发者的子集，社区的激情几乎盖过了这次 GitHub 首发本身。这一篇，就从零开始，把 DeepSeek Harness 到底是个什么东西、它凭什么「一切皆插件」、怎么跑起来讲透。

一、先回答：Harness 是什么

老读者可能记得，我们写过 LangChain 那篇里反复出现的一个公式：Agent = Model + Harness。用大白话讲，大模型本身是一颗「大脑」——它负责理解、推理、生成 token； 但大脑要干成事，还需要一副「身体」和一套「神经系统」去感知环境、动手、验证、纠错。这副身体， 就是 Harness。

DeepSeek 官方对 Harness 的定义也很明确：它是围绕大模型构建的完整控制与编排系统， 负责调度工具、管理任务状态和执行闭环。用「人和大脑」的类比来说，写代码的是模型， 执行神经系统的是 Harness——它承接大脑和真实环境的衔接：怎么把任务拆成一步步、每一步该调用哪个工具、 中间结果放哪里、失败了怎么回滚、上下文太长怎么压缩、要不要派子 Agent 干活、以及给用户看什么界面。

一句话记住：Model 是智商，Harness 是身手。没有 Harness 的模型只能「嘴上输出」，有了 Harness 它才能真的「动手做」。

所以 DeepSeek Harness（简称 DSH）就是 DeepSeek 自己造的这一整套「神经系统」。 有意思的是，它不依赖某个被大家抄滥的既有框架，而是选择自己从地基开始搭，并且用一种很「硬核」的哲学来搭。

二、「一切皆插件」：没有特权内核

DSH 架构的第一句话就是：「一切皆插件」。这可能是整份文档里最被频繁引用的一句。

什么叫「一切皆插件」？意思是：产品的每一部分——模型适配器、工具注册表、会话日志、记忆、 甚至是 agent loop 本身——都是插件，都挂在同一个框架上，因此都可以通过配置替换，而不存在一个 「需要打补丁的特权内核」。

驱动这套机制的是下层框架 Cordis，它的插件模型有几个核心概念：

  • 插件是实现某个服务（Service）的对象，生命周期由 Cordis 管理；
  • 上下文是服务的容器，每个服务占一个稳定的 ctx.xxx 键（比如ctx.tools、ctx.llm、ctx.sessions），其他插件通过键找服务，而不是 import 具体实现；
  • 服务依赖通过 inject 声明，加载顺序由依赖推导，而不是手写启动序列；
  • 类型化事件用于通信，有 emit / waterfall / parallel / serial 四种分发模式；
  • 注册是可逆的副作用，插件卸载时，它挂的东西也会一并撤销。

Cordis 的设计论文叫 《A Programming Paradigm for Spatiotemporal Composability》（时空可组合性编程范式）， 强调的是：一个复杂系统可以被拆成无数个彼此独立的插件，按时空维度（进程、会话、步骤）安全地组装在一起。 翻译成工程直觉：你要加能力，不是去改内核，而是在内核旁边再挂一个插件；要删，拔掉就是。

这套哲学有一个直接红利：每一层都是可 patch 的配置。插件之间通过「patch」叠加， 后加的上层可以按 id 定位并替换某个条目的整个 config，也可以插入新条目。所以你甚至不必 fork 源码， 用一份 YAML 就能改掉产品的任意一部分。

三、两层组合系统：Profile 与 Agent Preset

DSH 把「组装」分成了清晰的两层，别混淆：Profile 决定进程怎么跑，Agent Preset 决定会话里 Agent 看到什么。

1. Profile：进程这一层

运行中的 dsh 是一棵插件树，由启动时按序叠加的若干层拼出来。一个 Profile是放在 Harness home 里的具名组装，它列出自己叠放的「组合包（Bundle）」、存放自己安装的树外插件， 并保存用户自己的 cordis.patch.yml。发行版默认带两个模板：

Profile用途
web带着浏览器 UI 的完整应用，日常对话、审阅、交互用
headless无服务器的一次性运行器，跑完自动退出，适合脚本/CI

组合包的叠加顺序很有讲究：先按 dsh.profile.bundles 列的顺序应用每个 Bundle 的 patch， 然后 profile 自己的 cordis.patch.yml，再然后是 home 级那份，最后是命令行里传给 --patch 的任何 overlay。 最底下通常垫着 dsh-base（模型适配器、工具、持久化、沙箱与审批、设置、凭据、遥测），web 在上面再加 dsh-web-app。想看你机器上真实启动的配置树，直接：

dsh --profile web --dump-config

它打印出的任何条目，你都可以再写一个自己的 patch 去替换。

2. Agent Preset：会话这一层

如果说 Profile 管的是「一个进程长什么样」，那 Agent Preset 管的是「这个会话里的 Agent 有哪些工具、 提示词、Skill、子 Agent 和工作流」。DSH 出厂带了四个预设，彼此的定位很清晰：

预设（目录名）中文名官方描述
minimal极简模式仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent
standard标准模式功能完整的编码 Agent，支持文件编辑、Shell、检索、Skills、计划、目标、子代理和工作流
codePTC 模式具备标准模式全部能力，并用 Code Mode SDK 把工具呈现成一段 TypeScript 程序，让模型一次写、多步跑
cordis创造模式用于创建自定义 Agent preset：具备标准模式全部能力，并带运行时检查、插件实验和创作指导

极简模式很有意思——DeepSeek 在 V4-Flash 正式版跑 Agent 基准时用的就是它。它只有 bash 加一个文件编辑器两个工具， 但正是在这种「几乎裸奔」的状态下把成绩打上去，才最能说明模型本身的 agent 能力。

而 preset 的作用域解析遵循一条简单法则：agent → preset → global，最近的遮蔽最远的。 你可以同一个进程里并行跑多个不同类型的 Agent，各自看到自己 preset 的工具与提示词，互不串台； preset 的插件按 Session/Agent 区分状态，所以一个共享实例里多个会话仍然彼此隔离。

四、Agent Loop：先记录意图，再执行副作用

一个 Agent 跑起来，核心是一条「循环」。DSH 把口语里的「一次对话」拆成两个严谨的级别：

  • 步骤（Step）：一次模型请求 + 这次请求引发的工具执行；
  • 轮次（Turn）：包含零个或多个步骤，从认领首条输入打开，到不再欠任何工作关闭。

一次典型轮次是这样在事件流里展开的：打开轮次 → 认领输入 → 组装提示词段落与工具 schema → 派生模型历史 → 流式请求模型 → 分发工具调用与结果 → 关闭步骤 → 若还欠工作就再来下一步 → 关闭轮次。 关键点在于：驱动这个循环的每个环节都是可拦截的事件（agent/pre-step、agent/request、 llm/stream、tools/execute 等等），插件想观察、改写、加策略，都挂在事件上就行。

有个设计细节值得单独强调：DSH 是「先记录意图，再执行副作用」。也就是说每当模型说要调一个工具， 先把「这次调用的意图」记下来，再去真正执行外部副作用。工具调用又共用一条执行内核，且模型可以写 TypeScript 去编排一次多工具的调用序列，中间数据就留在运行环境里（这正是「PTC 模式」的底层能力）。 这套设计让整个 loop 可审计、可回滚、可随时纠正。

五、一个硬规则：模型可见 ⇔ 已记录

DSH 有一条被官方当作运行时不变量来维护的规则：「模型可见即已记录」。

意思是：凡是能抵达模型请求的任何东西，都必须能从会话日志里重建出来。 会话日志是唯一真源（source of truth），用只追加（append-only）的 SessionEvent 事件流承载。 每新增一项模型可见的输入，就必须新增一个对应的会话事件。因此：

  • fork、恢复、转录、遥测、持久化，全都从这个事件流派生出来，底层是同一份历史；
  • 连 UI 的回放保真，都靠原始 assistant/chunk 事件来保证，而不是靠前端重新拼；
  • 任何「当前上下文里看不到但曾经发生」的信息，理论上都能从日志里翻出来。

这条规则还带来一个反直觉的好处，和上下文压缩（compaction）直接相关。绝大多数工具压缩上下文时是 真的「删掉旧内容、喂一个新摘要」。DSH 不是：它绝不删除原始历史，压缩只是往事件流里追加一个user/message 替换节点（带 replace 的 surfaceOp），把当前请求「表层」换成摘要， 而完整原始记录原封不动留在日志里。这保证了「模型当前看到的是摘要，但完整的历史永远可以取证」。

换句话说：「看到的是被压缩的表面，档案里留着完整的历史」——这让压缩变成了一种「可逆的省钱操作」， 而不是丢数据。

六、前端也是第二棵插件树

DSH 的「一切皆插件」不止焊在后端。连界面本身也是一棵插件树，而不是「固定前端 + 后端插件」。

浏览器这个 surface 通过 ConversationNodeDefinition + 注册的 renderer 来挂 UI 插件， 挂载位分布在侧边栏、对话区、输入区、设置区。塞它的 .astro 或 React/Vue 组件就是你自己的「UI 插件」。 这意味着：你想给这个 Agent 做一套专属界面，不需要 Fork 前端，插一个 UI 插件就够了。

而且 DeepSeek 明确支持接第三方模型。在「设置 → 模型」里填入 DeepSeek API Key 就能用，也可以配其他提供方 （默认支持约近 40 个厂商，包括 Kimi、OpenAI、Anthropic、Google 等），甚至自定义 OpenAI 兼容端点， 推理等级还有 Off / High / Max 三档可选。模型路由改完立即生效，不用重启服务器。

七、插件的深度：记忆、子 Agent、插件生态系统

因为一切都是插件，很多「听起来要专门造一个系统」的能力，在 DSH 里就是一组插件组合。举几个例子：

  • 跨会话长期记忆 + 后台自我进化：社区内测期间就有人用纯插件实现了——本地文件持久化 + 分层上下文注入 + LLM 自己整理归档，而不是常见的「向量库 + RAG」。因为注入上下文的接口（agent.inject）是公开的，记忆就成了一堆插件的事。
  • 子 Agent 编排：subagent 是一个能力 seam（可替换能力）。同一个接口后面差异极大—— 可以新建一个子 Agent，也可以把一个轮次委派给另一个产品。这正是 Multi-Agent 编排变得灵活的原因。
  • 工具、LLM 适配器、能力、UI 都能换：加模型适配器注册到 ctx.llm，加能力注册到 ctx.tools， 加 shell 后端注册 ctx.shell……官方有一张「扩展实操手册」把每个功能映射到具体机制。

生态侧面印证了这套设计的威力：内测几天，社区就开发了约 300 个插件，而去重仓库约 712 个、Stars 累计 120 万+、 横跨 18 个赛道。开源的同一夜，你在 GitHub 上已经能搜到相当一批 dsh-plugin 话题的插件仓库。

八、怎么跑起来

开箱跑，只需要 Node.js，然后一行命令：

npx @deepseek-ai/dsh web

默认会在 http://127.0.0.1:3080 起一个 Web UI。

想从源码折腾，就：

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

启动后：去「设置 → 模型」配好 API Key → 选择工作区目录 → 开一个会话，比如让它 「Summarize this repository and identify its main packages」。Agent 就能读改文件、跑命令、委派工作、维护计划； 遇到当前权限策略下要审批的操作，Web UI 会先问你。想跑一次性的任务，用dsh --profile headless "job" 打印答案后自动退出。

一点背景：一晚上的很多巧合

放在一起看时间线，DSH 的开源几乎是踩着节奏来的：2026 年 7 月 31 日，V4-Flash 正式版公测， 官方预告「DeepSeek Harness 极简模式即将发布」；8 月 1 日，团队负责人（郑大 CS 出身、 曾在 Jane Street 做量化交易多年的工程师）发出内测招募帖；8 月 11 日，「黑鲸」公众号上线；8 月 12 日，仓库正式开源，进入开发者预览。开源那晚，仓库的 tags 与 forks 迅速累积到数百。

注意：DSH 目前是「开发者预览」阶段。官方明确警告：它在快速迭代，未来会有破坏兼容性的变更。想拿来稳定生产，建议盯 release 节奏，别急着锁版本。

小结

DeepSeek Harness 是最能代表「DeepSeek 式工程气质」的一个开源项目：不追逐别人封装好的范式， 而是用「一切皆插件」的极致解耦，让模型、工具、策略、存储、上下文、甚至 UI 全部成为可组合、可替换的插件， 由 Cordis 把这些插件按时空维度安全拼起来。

它有几句值得反复咀嚼的设计信条：Model 是智商、Harness 是身手；没有特权内核，只靠插件叠加；先记录意图再执行副作用；模型可见即已记录、压缩不删历史；前端也是插件树。

对小团队和个人开发者，DSH 最大的价值可能在于：既然连 Agent 本身都是插件，那么「自定义一个 Agent」 就从「改框架源码」降级成了「写一份配置、挑几个插件」，再往下走还能自己造 preset、造插件、造专属 UI。 虽然它还很年轻、还在预览期，但一个把整条 Agent 技术栈都做成积木的开源项目， 本身就足够让造 Agent 这件事，变得真正可组合。