DeepSeek Harness 架构解析：不是又一个 Coding Agent，而是重新定义 Agent Runtime 的边界

注：本文基于 2026 年 8 月 15 日公开的 DeepSeek Harness 仓库进行分析。DSH 当前仍处于 Developer Preview，官方明确提示后续会出现兼容性破坏，因此本文更关注其架构思想，而不是把当前实现视为已经稳定的产品规格。

2026 年 8 月 13 日，DeepSeek 开源了 DeepSeek Harness（简称 DSH），一个全新的 Agent 框架。它引起了广泛关注——Flask 作者、目前主导 Pi 开发的 Armin Ronacher 公开表示，虽然 DSH 并不完美，但这是他第一次在这个领域看到新东西，并觉得有必要回头重新审视自己团队的一些选择。

DSH 真正有意思的地方，不只是又提供了一个 Coding Agent，而是重新问了一个更基础的问题：

一个 Agent 真正运行起来，至少需要哪些基本能力？这些能力里，哪些必须由框架固定，哪些其实都可以替换？

这是理解 DSH 整套架构的起点。

一、不是又一个 Coding Agent，而是 Agent Runtime Framework

Claude Code、Codex、OpenCode 等产品，通常先定义好一个相对完整的 Agent Runtime：怎样组织 Context、调用模型、执行 Tool、保存 Session，再通过 Tool、MCP、Plugin 等机制向外扩展。

DSH 则试图再往下一层。它不急着规定“一个 Agent 最终应该长什么样”，而是把模型、Session、Tool、Agent Loop、Sandbox、Subagent 等 Runtime 基础能力拆开，再通过不同组合形成不同类型的 Agent。

换句话说，传统 Agent 框架更像是“先造好一个 Agent，再让你扩展它”；DSH 更像是先提供一组 Agent Runtime 的积木，再由这些积木组合出 Agent。

Coding Agent 只是其中一种组合结果。

二、Everything is a Plugin：插件化的是 Agent Runtime 本身

“一切皆插件”很容易被误解。Claude Code、OpenCode、Pi 都有 Plugin 或 Extension，如果 DSH 只是允许增加 Tool、Hook 或 MCP，并没有什么特别。

真正的区别在于：其他产品大多先有一个相对固定的 Agent Core，再让插件扩展这个 Core；DSH 则把传统上属于 Agent Core 的很多能力本身也做成了 Plugin。

官方用了一句很强的表述：“There is no privileged core to patch.”

它并不是说 DSH 没有 Core，而是说不存在一个“只有修改框架核心源码，才能改变其行为”的特殊 Agent Core。替换 Session、文件系统、模型 Provider，甚至 Agent 的运行方式，都希望通过 Plugin 和 Capability 完成，而不是 Fork 上游代码。

Agent Loop 就是典型例子。它负责准备上下文 → 调用 LLM → 调用 Tool → 返回结果 → 继续下一轮，通常被认为是 Agent 最核心的逻辑。但 DSH 把“Agent 是什么”和“Agent 怎么运行”进一步拆开：core/agent 定义 Agent 的状态和契约，core/agent-loop 更像一个默认 Driver，因此 Loop 本身也可以成为可替换能力。

DSH 的 Code Mode 则展示了另一种组合方式。模型主要通过 run_code 写程序，在程序内部连续调用 Tool，而不是每一步都经历一次 LLM → Tool → LLM。它本质上是在把部分程序控制流从 LLM 重新交还给代码执行。

minimal Preset 则只保留少量基础工具，这和 Pi 的设计有些相似：模型越强，一个 Agent 真正不可缺少的基础能力可能反而越少。

三、模型看到的内容，必须能够从日志中还原

DSH 第二个值得关注的设计是 Session。

普通 Agent 系统往往同时维护 Conversation History、Tool History、Trace 和运行日志，再在调用模型前临时拼出真正的 Request。这样很容易出现一个问题：日志中记录的内容，不一定等于模型当时真正看到的内容。

例如某个插件临时向 Prompt 注入了一段 Context，却没有同步进入 Conversation History。那么事后即使保存了聊天记录，也未必能回答：

“当时这个模型到底看到了什么？”

DSH 为此做了两层约束。

第一，Session 使用 append-only Event Log。 已经发生的事件不直接修改，而是通过追加新的 Event 表达变化，使 Session Log 成为会话的事实来源。

第二，模型看到的内容必须能够由 Session Log 重建。

用户消息、Assistant 消息、Tool Result 等历史消息通过 deriveMessages() 从 Session Log 生成；System Prompt、Tool Schemas、调用配置等，则通过 request/header 等 Event 记录。

因此，严格来说并不是“所有模型输入都经过 deriveMessages()”，而是：

所有最终发给模型的内容，都必须在 Session Log 中留下足够的信息，使这次模型请求能够被重新构造出来。

官方把它概括为：Model-visible means logged。 也就是：只要模型看到了，就必须有日志依据。

这样一来，Replay、Resume、Fork、调试和审计都会更容易实现，同时 append-only 的历史也更有利于保持 Prompt 前缀稳定、复用 Prefix/KV Cache。

这里真正重要的不是 Event Log 本身，而是 DSH 试图保证：模型实际看到的 Context、Session 状态和事后日志，不应该成为几份可能逐渐不一致的数据。

四、Capability Seam：把能力和具体实现解耦

如果只是把系统拆成很多 npm package，并不会自动获得真正的可组合性。关键在于模块之间有没有稳定的能力边界，DSH 把这种边界称为 Capability Seam。

以文件操作为例，模型看到的可能是 read_file、write_file 等 Tool，但底层真正执行这些操作的既可以是本地文件系统，也可以是 Sandbox 或远程环境。

因此，一个 Capability 通常拆成三个角色：

• Service Definition：定义能力和接口；
• Provider：提供具体实现；
• Consumer：决定如何向使用者暴露能力，例如模型看到的 Tool。

这样就可以保持模型看到的 Tool 不变，只替换底层 Provider；也可以保持 Provider 不变，为不同 Agent 提供不同的 Consumer。

它真正强调的是：Agent 应该依赖能力契约，而不是某一个具体实现。

Subagent 是一个很典型的例子。主 Agent 只需要知道“我可以把任务委派给另一个 Agent”，至于背后是另一个 DSH Agent、Fork Session、Codex 还是 Claude Code，都可以作为不同 Provider 挂在统一的 ctx.subagents 后面。

不同 Provider 支持的能力可能不同，因此 DSH 还通过 Capability Negotiation 明确能力边界。如果调用方要求某项能力，而 Provider 不支持，就返回 UNSUPPORTED_CAPABILITY，而不是静默忽略。

所以真正的可组合性，并不是代码拆成多少模块，而是：调用方只依赖稳定的能力接口，而不需要知道具体实现是谁。

五、自由度的价值和代价

Everything is a Plugin 最大的价值，是给开发者更大的 Runtime 控制权。

这对普通 Coding Agent 用户未必特别重要，但如果一个团队希望把 Agent Runtime 长期嵌入自己的产品，就会遇到更现实的问题：未来如果想替换 Session、改变 Context 管理、迁移 Tool 执行环境，甚至重新设计 Agent Loop，现有框架是否允许这样做？

如果这些能力写死在 Agent Core 中，通常只能在外围再包装一层，或者直接 Fork 上游代码。DSH 则试图从一开始就把这些可能变化的部分设计成正式的 Extension Seam。

但自由度也有代价。框架替你固定的东西越少，需要使用者自己管理的东西就越多。 当大量 Runtime Capability 都可以替换时，兼容性、生命周期和组件之间的组合关系就需要更严格的 Contract 来保证。

因此，DSH 并没有消除复杂度，而是在重新分配复杂度：从“如何修改固定的 Core”，转向“如何管理大量可组合的 Runtime Capability”。

现在就把 DSH 当成成熟的企业级 Agent Runtime 还为时过早，DeepSeek 自己也把它明确标记为 Developer Preview。但这并不妨碍它值得研究。

因为今天市场上已经不缺能够读文件、改代码、跑 Bash 的 Coding Agent。DSH 更有意思的地方，是它重新打开了一批逐渐被行业默认的问题：

• Agent Loop 为什么一定要属于不可替换的 Core？
• 模型真正看到的 Context，为什么要和 Runtime Log 分开维护？
• Tool Schema 为什么一定要和底层实现绑定？
• 一个 Agent Framework，到底应该替开发者固定多少东西？

这些问题现在还没有标准答案。高度可组合的 Runtime 可能带来更大的灵活性，也可能带来新的治理复杂度。

但至少 DSH 没有只是重新实现一个 Claude Code Clone。它真正值得关注的，是重新讨论了 Agent Runtime 的边界本身。