DeepSeek Harness 深度解读：一切皆插件的 Agent 运行时

2026 年 8 月 13 日，DeepSeek 正式公开了 DeepSeek Harness。官方把它描述为一个开源 Agent Harness，并用一句很醒目的话概括它的设计：Everything is a plugin，一切皆插件。

这句话很容易被理解成“又一个支持插件的 AI 编程工具”，但读完代码和架构文档后，我认为它真正值得关注的地方不是多了几个插件接口，而是把通常写死在 Agent 产品内部的部分都变成了可组合组件：

模型、工具、Skill、Session、沙箱、文件系统
Agent Loop、子 Agent、工作流、后台任务，甚至 Web UI

换句话说，DeepSeek Harness 想开放的不是某个工具栏，而是 Agent 的运行时结构本身。

名称提醒

GitHub 上存在其他同名或近似项目。本文讨论的是 deepseek-ai/deepseek-harness，也就是 DeepSeek 官方账号在 2026 年 8 月 13 日宣布开放 Developer Preview 的仓库。

一分钟概览

1. DeepSeek Harness 不是新模型，而是负责组织模型、工具、上下文、状态、权限和执行环境的 Agent 运行时。
2. 它同时提供可运行的 dsh 应用和可用于构建新 Agent 产品的底层组件，不能简单等同于“DeepSeek 版 Codex”。
3. “一切皆插件”的基础是 Cordis：插件向共享 Context 注册服务和事件，并用可撤销副作用管理生命周期。
4. 一个运行中的 dsh 不是固定程序，而是由 Profile、Bundle、用户 Patch 和临时 Overlay 叠出的插件树。
5. 它把持久事实与实时控制分开：Session Event 负责回放，agent/* 事件负责正在发生的协调。
6. Agent Loop 只是一项可替换服务。一次 Turn 可以包含多个 Step，每个 Step 是一次模型请求及其工具调用。
7. 文件系统、Shell、沙箱、持久化和子 Agent 都按照“定义、提供方、消费方”的能力接缝组织。
8. 这套架构的优势是可替换、可观察和可实验；代价是概念多、组合复杂，而且当前版本没有兼容性承诺。
9. 对多数只想使用 AI 编程工具的人，Codex 或 Claude Code 仍然更直接；DeepSeek Harness 更值得 Agent 基础设施开发者研究。

图 1：DeepSeek Harness 把模型、工具、Session、沙箱、循环和界面组装成可替换的 Agent 运行时

图 1：DeepSeek Harness 的核心信号不是“又多了一个聊天界面”，而是 Agent 运行时的各个组成部分都进入同一套插件生命周期。

1. 先分清模型、Agent 和 Harness

理解这个项目，第一步是把三个经常混在一起的概念分开。

1.1 模型负责生成下一步

大语言模型接收消息和工具描述，然后生成文本或工具调用。它可以提出：

读取 package.json
运行测试
修改某个文件
继续分析失败日志

但模型本身并不拥有你的文件系统，也不会天然保存 Session、限制命令权限或保证失败后能够恢复。

1.2 Agent 把模型接入行动循环

Agent 通常会重复下面的过程：

组装上下文
  -> 请求模型
  -> 解析工具调用
  -> 执行工具
  -> 把结果送回模型
  -> 判断是否继续

有了这个循环，模型才从“回答问题”变成“连续完成任务”。

1.3 Harness 管理循环周围的现实

真正进入工程环境后，只有循环还不够。系统还要回答：

• 模型可以看见哪些文件和说明？
• 哪些命令可以直接运行，哪些动作必须审批？
• 工具调用怎样限时、取消和记录？
• 上下文过长时怎样压缩？
• Session 中断后从哪里恢复？
• 多个子 Agent 怎样创建、隔离和停止？
• Web UI、CLI 和 SDK 如何观察同一段执行？

负责这些问题的，就是 Harness。

图 2：模型、Agent Loop 与 Harness 三层关系

图 2：模型决定候选动作，Agent Loop 驱动动作与反馈，Harness 则管理状态、权限、生命周期和外部执行环境。

这也是为什么我不太认同把 DeepSeek Harness 简化成“DeepSeek 版 Claude Code”或“DeepSeek 版 Codex”。仓库确实带有 Web UI、Headless Profile、工具和编程 Agent 能力，但它同时暴露了比普通终端产品更低的一层：开发者可以替换 Loop、文件系统、持久化和子 Agent Provider，再组装自己的应用。

2. “一切皆插件”到底是什么意思

很多软件都说自己支持插件，通常指的是：主程序固定，第三方可以增加命令、主题或工具。

DeepSeek Harness 的范围更彻底。它的架构文档明确写道，模型适配器、工具注册表、Session 日志和 Agent Loop 本身都是插件。代码库中还能看到：

• packages/llm：模型适配器与 Token 计量；
• packages/core：Session、系统提示词、工具和 Agent Loop；
• packages/fs、shell、subprocess：文件与进程能力；
• packages/sandbox、interaction：执行隔离、权限和审批；
• packages/skill、mcp、hooks：能力扩展与外部兼容；
• packages/subagent、workflow、jobs：委派、工作流和后台任务；
• packages/web、host、client：界面和远程调用。

这里的关键不是包多，而是这些包遵守同一种组合方式。一个工具插件不需要导入“默认 Agent Loop”的具体实现；它只依赖工具注册服务。一个 Shell 工具也不必知道命令最终在本机、沙箱还是远程环境执行。

这会产生一种很重要的工程效果：

替换能力提供方时，尽量不修改它的消费方。

例如，文件系统和子进程如果共同切换到远程沙箱，Bash、持久终端和 LSP 可以继续消费原来的接口，而不必各自维护一套 E2B 专用分支。

不过，“一切皆插件”不等于“系统没有核心”。Cordis 运行时、共享 Context、服务名称、事件语义、Session Event 词汇和包约定仍然构成稳定地基。更准确的理解是：

DeepSeek Harness 把产品行为从一个难以替换的中心类，迁移到一组受统一生命周期约束的插件之中。

3. Cordis：插件树下面的元框架

DeepSeek Harness 由 Cordis 驱动。官方把 Cordis 称为“时空可组合”的元框架，并提供了对应的设计论文仓库。如果不理解 Cordis，dsh 的大量目录会显得像过度拆包；理解之后，会发现这些包在重复表达五个概念。

3.1 Plugin：一段可挂载行为

插件可以提供服务、注册事件监听器、增加工具或挂载其他插件。它不是静态模块清单，而是一个有加载、等待、重载和卸载过程的运行单元。

3.2 Context：服务容器和作用域

服务通过稳定键进入共享 Context，例如：

ctx.llm
ctx.tools
ctx.sessions
ctx.agents
ctx.shell
ctx.subagents

插件依赖服务键，而不是依赖某个具体类。这让同一个消费方可以面对不同 Provider。

3.3 Inject：用依赖声明启动顺序

插件通过 inject 声明自己需要哪些服务。所需服务没有准备好时，插件保持等待；服务就绪后再启动。

因此，配置文件中的排列顺序并不等于运行时启动顺序。真正的顺序来自依赖关系。这比手工在一个大入口文件里安排“先初始化 A，再初始化 B”更适合频繁替换的插件树。

3.4 Typed Event：在不知道对方实现时协作

Cordis 提供四种事件分发模式：

其中 waterfall 对 Agent 特别重要。agent/pre-step、agent/request、tools/pre-execute 和 tools/post-execute 都可以被策略插件包裹：有的只记录，有的改写输入，有的拒绝继续。

3.5 Effect：注册必须能够撤销

工具、服务、监听器和提示词片段都被视为副作用。插件卸载时，这些注册需要一并撤销。服务被替换后，依赖它的插件可以停止，再基于新服务重启。

图 3：Cordis 用 Context、Inject、Event 和可逆 Effect 组成插件生命周期

图 3：插件并非一次性执行脚本，而是带作用域和清理语义的运行单元。可撤销副作用是热替换不留下残余注册的前提。

所谓“时空可组合”，可以先用一个不那么抽象的方式理解：

• 空间上，Context 决定一个插件能看到哪些服务，以及能力属于全局还是某个 Agent；
• 时间上，Fiber 和 Effect 决定插件什么时候生效、依赖变化时如何重启、卸载时怎样清理。

这也是 Cordis 比普通依赖注入容器多出来的部分：它管理的不是一张静态对象图，而是一棵会变化的运行时插件树。

4. dsh 是一棵组装出来的插件树

DeepSeek Harness 没有把 Web、CLI 和 Headless 的所有能力硬编码在一个启动流程里。一个实际运行的 dsh 由三类配置叠加而成。

4.1 Profile：一个具名应用

Profile 表示用户实际启动的组装，例如 Web 或 Headless。它保存所使用的 Bundle、Profile 自己的插件和 Patch。

4.2 Bundle：一组可分发能力

dsh-base 提供模型适配器、工具、持久化、沙箱、审批、设置、凭据和遥测等基础能力；dsh-web-app 在它上面加入浏览器应用；dsh-headless 则加入一次性任务运行器，不启动 Web 服务。

4.3 Patch 与 Overlay：最后决定实际树

各层按顺序叠加：

Profile 指定的 Bundle
  -> Profile 的 cordis.patch.yml
  -> Harness Home 的 cordis.patch.yml
  -> 命令行 --patch Overlay

Patch 通过稳定 id 找到配置项，替换它的完整配置，或者插入新插件。这意味着“换一个 Provider”并不是进入主程序打补丁，而是改变插件树的一条装配记录。

图 4：Profile、Bundle 和 Patch 叠加成运行时插件树

图 4：Profile 是应用配方，Bundle 是能力组合包，Patch 是部署和用户对配方的覆盖；最终产物才是运行中的插件树。

这种结构带来很强的可定制性，也带来第一个明显代价：配置不再只是几个开关，而是在描述一棵具有依赖、作用域和生命周期的程序。对于插件作者，这是能力；对于普通用户，则可能是额外认知成本。

5. 它最值得学习的地方：持久事实与实时控制分离

很多 Agent 框架把“发生过什么”和“现在该做什么”都塞进同一个内存状态对象。程序运行时看起来简单，一旦需要恢复、Fork、回放或多界面同步，状态含义就会变得含混。

DeepSeek Harness 明确区分三类事件。

5.1 Session Event：可以回放的持久事实

turn/start、step/start、user/message、assistant/chunk、assistant/message、tool/call、tool/result 和 turn/end 会进入仅追加的 Session 日志。

这些事件回答：

过去到底发生了什么？
重新加载后应该恢复出什么历史？
UI 怎样重建当时的流式输出？
Fork 应该从哪个边界开始？

5.2 Agent Event：只负责活跃运行时协调

agent/pre-step、agent/request、agent/status、agent/turn-stopping 等事件携带正在运行的 Agent、Inbox、取消信号和控制决策。

这些事件回答：

下一步是否允许开始？
模型请求是否需要改写？
当前 Agent 是 idle 还是 running？
自然停止前还有没有插件要求继续？

它们不是历史事实的替代品。需要重建 transcript 的客户端应该消费 Session Event，而不是假设实时 Agent Event 能够重放。

5.3 Capability Event：对某项能力附加策略

tools/pre-execute、tools/post-execute、fs/* 等事件让策略靠近对应能力，不必让所有扩展都导入 Agent Loop。

这一分层背后有一句很硬的仓库不变量：

模型可见，当且仅当已经记录。

任何真正进入模型请求的内容，都必须可以从 Session 日志重建。新增一项模型可见上下文，不能只在请求发送前临时拼接，还需要定义相应的持久事件。

这条规则看起来繁琐，却直接服务于上下文审计、Session 恢复和结果复现。对于 Agent 系统，它比“我们记录了大部分日志”严格得多。

6. Turn、Step 与 Agent Loop

在 DeepSeek Harness 中：

• Step：一次模型请求，加上这次请求产生的工具调用；
• Turn：从领取用户输入开始，到系统不再欠下后续工作为止，可以包含多个 Step。

简化后的生命周期如下：

领取 Inbox 输入
  -> turn/start
  -> agent/pre-step
  -> step/start
  -> 组装提示词与工具 Schema
  -> agent/request -> llm/stream
  -> assistant/message
  -> tools/pre-execute
  -> tools/execute
  -> tools/post-execute
  -> tool/result
  -> step/end
  -> 仍有工具结果或 steering？继续下一 Step
  -> agent/turn-stopping
  -> turn/end

图 5：DeepSeek Harness 的 Turn、Step、模型请求、工具调用与持久事件关系

图 5：控制钩子可以阻止或改写下一步；真正抵达模型和工具的事实则写入 Session Event，供 UI、恢复和回放使用。

这里有几个不太显眼、但很成熟的设计判断。

6.1 Inbox 不只有普通追问

输入可以进入 next-turn 或 next-step：

• followup 等待一个新的 Turn；
• steer 在当前运行的下一个安全 Step 介入；
• inject 只加入上下文，不主动唤醒 Agent。

这比“运行中再发一句话”更精确，因为系统需要明确消息什么时候能够被模型看到，以及取消后它是否还应保留。

6.2 停止输出不等于任务完成

模型不再调用工具，只能说明本轮自然停止。agent/turn-stopping 仍可以让目标驱动器、验证器或 Hook 决定是否继续。

6.3 Loop 不是不可替换内核

ctx.agentLoop 是一项服务，默认 Loop 实现公开的 Agent 接口。外部插件依赖 agent 服务，而不是直接依赖默认 agent-loop 包。理论上可以更换驱动策略，同时保留 Session、工具和 UI 等其他组件。

7. Capability Seam：比“接口抽象”多一步

DeepSeek Harness 用 Capability Seam 描述可替换能力。一个完整 Seam 包含三个角色：

Service Definition：声明稳定接口
Service Provider：实现本地、远程或其他版本
Consumer：把能力暴露给 Agent 或其他组件

只声明一个 TypeScript 接口，还不能算完整接缝；系统必须同时知道谁提供它、谁消费它，以及替换 Provider 后哪些组件会重新绑定。

以 Shell 为例：

ctx.shell
  定义：shell 能力
  Provider：bash-local / bash-sandbox / pwsh-local
  Consumer：Bash 工具 / PowerShell 工具 / Hook Bridge

再看 Subagent：

ctx.subagents
  Provider：进程内新 Agent、Session Fork、ACP、Codex、Claude Code、dsh SDK
  Consumer：subagent 工具、控制工具、工作流工具

这说明 DeepSeek Harness 的目标并不只是“让 DeepSeek 模型调用几个子 Agent”。它甚至可以把 Codex 或 Claude Code 放到统一 Subagent 接口之后，由上层编排选择 Provider。

图 6：能力接缝把稳定定义、可替换提供方和消费方分离

图 6：插件化的重点不是每个包都很小，而是替换 Provider 时，Consumer 继续面对同一个能力定义。

这也是项目最有研究价值的部分：它没有把“本地文件系统”“DeepSeek 模型”“进程内子 Agent”当作永远成立的产品事实，而是把它们当作某个部署下的 Provider 选择。

8. 它不是只服务 DeepSeek 模型

虽然项目名是 DeepSeek Harness，官方模型配置文档已经包含 DeepSeek、Anthropic、OpenAI 和自定义 OpenAI 兼容端点。

这与插件架构是吻合的：DeepSeek 提供默认模型体验，但 ctx.llm 是适配器注册表，模型 Provider 不是整个 Harness 的身份边界。

同样，仓库提供 Web UI、Headless Bundle、TypeScript SDK、ACP 以及 Python SDK。它既想成为一个可以直接运行的 Agent，也想成为其他 Agent 产品的组件库。

这两种目标可以互相促进：可运行产品会逼迫底层抽象面对真实问题。但它们也可能产生张力：普通用户希望默认值稳定简单，框架开发者则希望每一层都可以替换。未来版本能否同时守住两类体验，是我认为最值得观察的地方之一。

9. 自修改能力很吸引人，也最需要克制

仓库里有一组 tool-cordis 工具，允许 Agent 检查运行时服务和事件，并动态定义、运行或停止新的 Cordis Package。它展示了一个很有想象力的方向：

Agent 发现缺少能力
  -> 检查当前运行时
  -> 编写一个插件
  -> 挂载插件
  -> 获得新的模型可见工具

但官方工具目录也明确说明，这组工具不会默认进入发行版的插件树，必须主动启用，因为动态 Package 可以访问真实运行时。

这是正确的边界。插件化会降低扩展成本，却不会自动降低扩展风险。第三方插件可能接触：

• 模型请求和会话内容；
• 文件系统与子进程；
• API 密钥和凭据引用；
• 工具调用与审批流程；
• UI 和持久化数据。

因此，“一切皆插件”的安全含义不是“可以放心安装更多插件”，而是：

插件本身已经成为 Agent 的软件供应链，需要来源审查、最小权限、明确配置和可追踪的生命周期。

10. 和 Codex、Claude Code 应该怎样比较

比较三者时，最容易犯的错误是列一个功能表，然后数谁的勾更多。DeepSeek Harness 仍处于预览期，Codex 与 Claude Code 也在快速变化，这种比较很快失效。

更稳定的比较方式是看它们优先开放哪一层。

Codex 的 App Server 让开发者把线程、轮次、审批和流式事件嵌入自己的客户端；Anthropic 则持续公开长任务 Harness和动态工作流的实践。

DeepSeek Harness 的差异不在于“首次发明 Harness”，而在于它选择把 Agent 产品的大部分内部构件纳入同一套插件元框架，并以 MIT 许可证公开完整代码。

这也意味着三者并不一定是互斥关系。DeepSeek Harness 已经包含 Codex 与 Claude Code 的 Subagent Provider 和 Hook Bridge；Codex、Claude Code 也都能通过 CLI、SDK 或协议与外部编排器协作。未来 Agent 工具链更可能出现“一个 Harness 调用另一个 Harness”，而不是每个人只生活在单一产品里。

11. 这套架构解决了什么

11.1 让实验不必不断 Fork 主循环

新的压缩策略、工具策略、模型 Provider 或子 Agent 实现可以挂到明确接缝，而不是持续修改一个越来越大的 Loop。

11.2 让运行时状态更容易解释

持久 Session Event 和实时控制事件分离后，UI、SDK、回放与 Agent 协调各自消费适合自己的数据。

11.3 让能力替换成为装配问题

本地与远程文件系统、不同持久化后端、不同模型和不同 Subagent 传输都可以通过 Provider 选择完成。

11.4 让卸载和重载具有正式语义

注册是 Effect，依赖由 Inject 声明，插件卸载时撤销自己的贡献。这比“动态 import 一个模块，然后希望它没有留下全局状态”更可控。

12. 它没有自动解决什么

12.1 插件多不代表默认组合就正确

框架提供替换能力，但一个实际 Agent 是否可靠，仍取决于默认 Prompt、工具描述、权限、验证、模型和任务环境。

12.2 事件完整不代表任务已经验收

日志可以证明系统执行过什么，却不能单独证明结果满足业务目标。独立验证器、确定性测试和人工判断仍然需要存在。

12.3 可组合不代表低复杂度

服务作用域、事件顺序、Waterfall 短路、配置 Patch、Effect 清理和 Provider 生命周期都需要严格约定。项目自己的开发文档和测试门禁非常密集，也从侧面说明维护这类架构并不轻松。

12.4 开源不等于已经适合生产

官方 README 明确写着 Developer Preview，并警告未来会出现破坏兼容性的变更。npm 在公开当天已经连续发布多个 RC，也说明接口仍在快速收敛。npm 当前版本应当在实际采用前重新核对。

12.5 SDK 示例的安全边界不能忽略

官方 Python SDK 最小组合目前使用 danger-full-access，文档要求放在可丢弃 Checkout 或容器里，并说明持久 PTY 组合不支持 Windows Agent。这是示例的明确边界，不应被改写成“安装后即可安全接管本机工程”。

13. 谁应该现在关注它

值得深入阅读

• 正在设计 Agent Runtime、工具执行层或多 Agent 编排器；
• 需要在同一产品中切换本地、沙箱与远程执行环境；
• 正在研究 Session 回放、Fork、Steering 和上下文可审计性；
• 希望把 Codex、Claude Code 或其他 Agent 放到统一委派接口之后；
• 想理解插件生命周期怎样超越普通依赖注入。

暂时不必迁移

• 只是需要一个成熟的 AI 编程助手；
• 项目没有替换 Agent Loop、文件系统或持久化层的真实需求；
• 团队需要稳定 API 和长期兼容承诺；
• 没有能力审计第三方插件及其文件、网络和凭据权限。

对第一类读者，DeepSeek Harness 是一份很少见的完整架构样本。对第二类读者，现在更适合观察，而不是因为“官方开源”就立刻迁移工作流。

14. 源码阅读地图：六个切口就够了

DeepSeek Harness 的 Monorepo 很大，不适合从 packages/ 目录逐个点开。若想验证本文的核心判断，可以按问题阅读，而不是按包名阅读。

这六处读完后，再沿服务名反向搜索 Provider，通常比顺序阅读整个仓库更有效。尤其要留意 README.zh.md、cordis.patch.yml 和测试文件：这个项目把许多不变量写在包级说明与组合测试里，公开 API 文件反而只是其中一部分。

15. 我的判断

DeepSeek Harness 当前最重要的价值，不是给 Agent 用户增加一个新的选择按钮，而是把一个长期隐藏在产品内部的问题摆到代码层面：

当模型能力越来越接近时，Agent 产品的差异会越来越多地来自运行时怎样组织上下文、状态、工具、权限、恢复和扩展。

OpenAI 把这个方向称为 Harness Engineering；Anthropic 通过长任务、Hooks 和动态工作流不断展示 Harness 的影响；DeepSeek 这次给出的回答，则是一个以 Cordis 为底座的、接近“Agent 操作系统装配层”的开源实现。

我最认可它的三个决定：

1. 模型可见内容必须可由日志重建。 这让上下文不再是请求发送前的一段魔法拼接。
2. Loop 之外的能力也必须可替换。 文件系统、进程、持久化和 Subagent Provider 与模型同样重要。
3. 注册必须能够撤销。 插件生命周期如果没有清理语义，热重载最终只会变成状态泄漏。

我目前最大的保留也有三个：

1. “一切皆插件”会把很多简单修改提升为框架级装配问题；
2. 同时服务最终用户和框架开发者，可能让默认体验与开放性互相拉扯；
3. Developer Preview 阶段的快速变化，使现在写出的插件和配置都需要承担迁移成本。

所以现阶段最合理的态度不是急着给它贴上“Codex 替代品”的标签，而是把它当成一份公开的 Agent Runtime 设计提案：读它怎样定义状态，怎样组织扩展，怎样把实时控制与持久事实分开，再决定这些思想中哪些值得带回自己的系统。

收藏清单

• 模型、Agent Loop 和 Harness 是三个不同层次。
• DeepSeek Harness 的插件范围包含 Loop、Session、沙箱和 UI。
• Cordis 用 Context、Inject、Typed Event 和 Effect 管理插件树。
• Profile、Bundle 与 Patch 共同决定运行中的 dsh。
• Session Event 保存可回放事实，agent/* 处理实时协调。
• 一次 Turn 可以有多个 Step；停止生成不自动等于验收完成。
• Capability Seam 必须同时考虑定义、Provider 和 Consumer。
• Codex 与 Claude Code 可以成为 DeepSeek Harness 的 Subagent Provider。
• 动态插件和自修改能力属于高权限软件供应链。
• 当前是 Developer Preview，架构值得研究，生产采用需要等待和验证。

参考资料

• DeepSeek Harness 官方仓库
• DeepSeek 官方发布推文
• DeepSeek Harness 架构文档
• Cordis 入门
• Agent 生命周期
• 能力接缝目录
• DeepSeek Harness 模型 Provider
• DeepSeek Harness Python SDK
• Cordis：A Programming Paradigm for Spatiotemporal Composability
• OpenAI：Harness Engineering
• OpenAI：Codex App Server
• Anthropic：Harness design for long-running application development
• Anthropic：A harness for every task