DeepSeek Harness 架构拆解:一个"一切皆插件"的 Agent 运行框架

导语:很多人第一次听到 DeepSeek Harness(命令行 dsh),会以为它是 DeepSeek 的推理引擎。其实恰恰相反——它不含任何模型算力,而是一个 Agent 运行框架。本文从架构师视角,把它拆成三层、四个核心包、两个代码模板,讲清楚它"为什么这么设计"。

一、先纠一个概念:Harness 不是推理引擎

DeepSeek Harness 的官方定位是一条公式:

Agent = Model + Harness

Model 负责推理和决策,Harness 负责模型之外的一切:记忆、工具、权限、执行循环、会话管理、沙箱。模型算力是通过"模型适配器"接入的外部服务(DeepSeek、Anthropic、OpenAI,或任意 OpenAI 兼容网关)。

所以你想学它,其实是两件事:①它的插件化架构(如何把 Agent 运行时拆成可拼装的件);②它的程序应用(怎么写插件、怎么接自己的模型)。下面分而治之。

二、架构骨架:三层模型

整个框架只有三层,别被"200+ 个包"吓到:

  1. Cordis 微内核
    (约 2700 行,不可动部分仅 ~2%)。核心机制是"时空可组合性":每个插件的每次改动都必须附带"如何撤销"的说明,卸载时按注册顺序逆序回滚;插件声明依赖,依赖项出现/消失时自动启停。
  2. 一切皆插件
    (其余十几万行全是插件)。工具、技能、UI、会话记录是插件,连 Agent 主循环本身也是可替换的插件。通过 profile/patch/--patch 叠加插件树,运行时热插拔。
  3. LLM 适配层
    (packages/llm)。唯一和"推理引擎"交界的地方:LlmAdapter 契约 + StreamChunk 流协议 + 内容块词汇表。

一句话总结设计哲学:扩展方式不是改内核,而是把插件挂到别的插件旁边。

三、Cordis 内核:五个概念,四种分发

读任何核心包之前,先建立这五个概念——它们是整个框架的"地基":

概念
含义
插件 = 实现 Service 的对象
函数、带 apply 的对象、或 Service 子类
上下文 = 服务容器
每个服务占一个 ctx.,按 key 查服务,从不 import 实现
inject
 声明依赖
加载顺序由依赖图决定,不是手动编排启动序列
类型化事件通信
四种分发模式(见下)
注册 = 可逆副作用
ctx.effect()
/ctx.on() 装的东西,卸载时自动逆序撤销

四种分发模式,读 agent-loop 和 tools 管道前必须懂:

模式
await?
顺序
返回值
用在哪
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,…

— 以上为试看内容(约 40%),开通会员后阅读全文 —