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

三、Cordis 内核：五个概念，四种分发

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

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

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，绝不依赖 agent-loop——于是替换 Agent 循环不需要改任何消费方。教科书级的依赖倒置。

四个 waterfall 拦截点是控制中枢：

最值得细品的是 agent/turn-stopping 的语义：数据决定结果，监听器顺序无法改变结果——机器重读 inbox，有 pending 就再跑一步，没有就关轮次。控制流被表达成了数据状态。

六、主干四件套之三：tools —— 受控执行管道

一次工具调用依次经过这条链：

tools/pre-execute (waterfall: allow/deny/ask)       ↓ 单调 guard（只能 deny，不能 allow）       ↓ tools/execute (waterfall: 超时/重试/指标)       ↓ tools/post-execute (waterfall: accept/replace/block)       ↓ finalizeContent → tools/result (emit)

三个安全设计值得抄走：

• 单调策略
  ：guard 故意没有 allow 结果，监听器顺序无法把 deny 变回 allow。权限只减不增，这是"默认拒绝、顺序无关"的安全模型。
• 参数不可改写
  ：模型发出的 arguments 一旦进日志就是审计证据，谁都不能改——历史、审计、UI、执行必须一致。
• value/content 分离
  ：程序拿到完整 value（不持久化），模型看到 content（持久化）。回放能重现展示，重建不了规范中间值。

七、主干四件套之四：llm —— 模型接缝

LlmAdapter 抽象类唯一必须实现的方法是 stream()，但配套一堆"必须遵守"的约定——薄接口 + 强约定：

• usage
   在 finish 之前，finish 之后无分片
• 工具参数全程保持原始 JSON 字符串
• 两条错误路径共用一个规范化的 LlmFailure
• 一次适配器调用 = 一次提供方尝试
  ，重试在 agent 层
• 上下文溢出只有一个规范 code，消费方按 code 路由，绝不依赖提供方文本

核心洞察：适配器把"提供方的千奇百怪"归一化成"框架的单一真相"。上层永远面对干净的、提供方无关的语义，绝不去猜各家各报什么错。

八、贯穿始终的四条不变量

读完四件套，会发现四条主线贯穿所有包：

1. 模型可见即已记录
   ——凡进模型的，都能从日志重建，有运行时断言。
2. 参数/请求不可改写
   ——进日志/进模型的都是不可篡改的事实。
3. 失败归一化
   ——LlmFailure、单一 code、空响应可重试。
4. 一切可插拔
   ——从工具到循环，全部是可替换插件。

九、程序应用：两个代码模板

模板 A：最小工具插件

import { readFile } from 'node:fs/promises' import type { Context } from '@deepseek-ai/cordis' import { defineTool } from '@deepseek-ai/dsh-tools'  export const name = 'my-tool' export const inject = ['tools']        // 声明依赖，等 ctx.tools 就绪才启动  export function apply(ctx: Context) {   ctx.tools.register(defineTool({      // 注册是副作用，卸载自动注销     name: 'read_file',     description: 'Read a file from disk.',     parameters: {                      // 一个 schema 三合一：类型+校验+模型schema       path: { type: 'string', required: true, description: 'Absolute path' },       limit: { type: 'number' },     },     output: {       schema: { type: 'string' },       render: (_args, value) => [{ type: 'text', text: value }],  // value→content     },     async execute(args, exec) {       // args 已被校验并类型收窄；exec.signal 必须透传       return readFile(args.path, { encoding: 'utf8', signal: exec.signal })     },   })) }

模板 B：接自己的 vllm 模型（OpenAI 兼容）

import { LlmAdapter } from '@deepseek-ai/dsh-llm'  class VllmAdapter extends LlmAdapter {   async *stream(options: GenerateOptions): AsyncIterable {     const res = await fetch(`${this.baseUrl}/v1/chat/completions`, {       method: 'POST',       headers: { 'Content-Type': 'application/json',                  'Authorization': `Bearer ${this.apiKey}` },       body: JSON.stringify({ model: options.model, messages: options.messages,                              tools: options.tools, stream: true }),       signal: options.signal,          // 必须遵守取消信号     })     // 解析 SSE，按序 yield StreamChunk（text-delta / usage / finish...）   } }  export function apply(ctx: Context, config: { baseUrl: string; apiKey: string }) {   ctx.llm.registerAdapter(['my-vllm'], new VllmAdapter(config.baseUrl, config.apiKey)) }

你要做的全部：实现一个 stream()，把 vllm 的 OpenAI 兼容输出翻译成框架的 StreamChunk，然后 registerAdapter。重试、缓存、审计、日志全由框架接管。

结语

一句话总结这个框架的设计哲学：

Harness 是一个事件溯源的、一切皆插件的、依赖注入的执行底座——存的是事实（append-only 日志），跑的是循环（可替换的 driver），改的是数据（waterfall 决策 + 单调策略），接的是翻译器（LlmAdapter 归一化协议）。

如果你也在做 Agent 工程，最值得搬走的三样东西是：事件溯源 + 派生历史（存事实不存视图）、单调安全策略（顺序无关的默认拒绝）、薄接口 + 强约定（适配器归一化一切差异）。