DeepSeek Harness 架构拆解:一个"一切皆插件"的 Agent 运行框架
导语:很多人第一次听到 DeepSeek Harness(命令行
dsh),会以为它是 DeepSeek 的推理引擎。其实恰恰相反——它不含任何模型算力,而是一个 Agent 运行框架。本文从架构师视角,把它拆成三层、四个核心包、两个代码模板,讲清楚它"为什么这么设计"。
一、先纠一个概念:Harness 不是推理引擎
DeepSeek Harness 的官方定位是一条公式:
Agent = Model + Harness
Model 负责推理和决策,Harness 负责模型之外的一切:记忆、工具、权限、执行循环、会话管理、沙箱。模型算力是通过"模型适配器"接入的外部服务(DeepSeek、Anthropic、OpenAI,或任意 OpenAI 兼容网关)。
所以你想学它,其实是两件事:①它的插件化架构(如何把 Agent 运行时拆成可拼装的件);②它的程序应用(怎么写插件、怎么接自己的模型)。下面分而治之。
二、架构骨架:三层模型
整个框架只有三层,别被"200+ 个包"吓到:
- Cordis 微内核
(约 2700 行,不可动部分仅 ~2%)。核心机制是"时空可组合性":每个插件的每次改动都必须附带"如何撤销"的说明,卸载时按注册顺序逆序回滚;插件声明依赖,依赖项出现/消失时自动启停。 - 一切皆插件
(其余十几万行全是插件)。工具、技能、UI、会话记录是插件,连 Agent 主循环本身也是可替换的插件。通过 profile/patch/ --patch叠加插件树,运行时热插拔。 - LLM 适配层
( packages/llm)。唯一和"推理引擎"交界的地方:LlmAdapter契约 +StreamChunk流协议 + 内容块词汇表。
一句话总结设计哲学:扩展方式不是改内核,而是把插件挂到别的插件旁边。
三、Cordis 内核:五个概念,四种分发
读任何核心包之前,先建立这五个概念——它们是整个框架的"地基":
apply 的对象、或 Service 子类 | |
ctx.,按 key 查服务,从不 import 实现 | |
inject | |
ctx.effect()ctx.on() 装的东西,卸载时自动逆序撤销 |
四种分发模式,读 agent-loop 和 tools 管道前必须懂:
emit | ||||
waterfall | 中间件/短路 | |||
parallel | ||||
serial |
Waterfall 语义是理解一切拦截的关键:监听器收到 (...args, next),调 next() 委托给下游,不调 next() 直接 return = 短路。"策略监听器有决定权就短路,观察监听器必须委托"。
四、主干四件套之一:session —— 事件溯源是唯一真源
Session 是一份由类型化 SessionEvent 组成的仅追加日志,是 agent 交互历史的唯一真源。LLM 消息历史是从日志"派生"出来的,从不单独存储;回放 = 从同一组事件重新派生。这就是 DDD 里的 Event Sourcing,只不过"聚合根"换成了一次对话。
三个设计分离,是它的精髓:
- Surface 与 Log 分离
:只有 3 种事件( user/message、assistant/message、tool/result)进入"有序 surface"。它们携带SurfaceOp:append(追加)或replace(遮蔽一个区间)。日志永远只增不减,但"模型看到的历史"可以变短——这是压缩长上下文的机制。 - 原始 chunk 与组装 message 分离
: assistant/chunk(token 级原始流,保回放保真)与assistant/message(组装后,派生历史用)分开存。 - 种子历史与实时工作分离
:恢复/fork 的会话追加一条 session/end-seed标记,区分"种子"与"本进程实时写入"。
数据完整性靠 append 的三道闸:JSON 可序列化校验(BigInt/函数/循环引用直接 throw)、deep-freeze(普通 JS 无法改写历史)、seq 连续性(seq === log.length,持久化不能过滤任何事件)。
五、主干四件套之二:agent-loop —— 驱动器与拦截点
这一层最关键的决定是接口与实现分离:agent/ 包只声明 Agent 接口,agent-loop/ 是唯一具体实现。扩展插件只依赖 agent,…