DEEPSEEK HARNESS FROM SOURCE

DeepSeek Harness 源码解析

一个「一切皆插件」的 agent harness——把模型循环本身做成可装卸的插件树

本书是一份教育性的源码研究笔记。分析对象 DeepSeek Harness（DeepSeek AI 开源的 agent harness，简称 dsh）采用 MIT 许可发布，书中所有代码片段均直接取自真实源码，文件路径与函数名皆可逐一核对。本书与 DeepSeek 官方无关，未获其背书或赞助。

分析基于的版本为 monorepo 0.1.0-rc.5。书中所有文件路径均相对于 dsh-src/ 目录。

这本书想回答什么问题

在我们的前作《Pi Agent 源码解析》里，你见过一种极端：刻意保持最小的包联邦，把复杂性挡在核心之外，模型通过结构化 JSON 工具调用行动。在《Prime Agent 源码解析》里，你见过另一种极端：把模型放进持久的 IPython 解释器，让「一切皆程序」——执行是代码、子代理是调用、上下文是变量。这两条路线回答的是同一个问题的两个方向：模型到底应该以什么方式行动？

DeepSeek Harness 没有回答这个问题——它回答的是一个更早、也更根本的问题：

agent harness 本身应该是什么？

绝大多数 agent 框架的答案都是「一个核心 + 一圈扩展」：核心里有模型适配、工具注册表、会话管理、Agent 循环，扩展通过某种 SDK 挂在核心外面。扩展可以很多，但核心是特权层——它有别的模块没有的权力，也有别的模块没有的维护负担。

dsh 的答案是一个字：没有核心。它的 README 第一行写着：

It uses an architecture where everything is a plugin, and is powered by Cordis.

模型适配器是插件，工具注册表是插件，会话日志是插件，Agent 循环本身也是插件。整个系统是一棵在启动时由配置（cordis.yml）拼出来的插件树，没有任何一行代码有特权。你可以用一行 patch 换掉文件系统后端，用几行配置让一个会话挂上完全不同的工具集与提示词，甚至让模型在运行期把自己没装过的插件装进自己的运行时。没有特权核心，就不存在「核心之外」——扩展不是挂在边上，而是长在树上。

于是这本书的核心问题是：

当「一切皆插件」被认真推到极致——模型适配、会话日志、Agent 循环、安全边界、Web 界面全部是配置拼出的插件树——一个生产级 harness 会是什么形状？它靠什么保持不散架？又付出什么代价？

与前作的关系：三条路线的对照

把 dsh 与两本前作放在一起看，会发现 agent 工程里三条不同的路线正在成形：

维度pi（工具调用范式）Prime Agent（一切皆程序）DeepSeek Harness（一切皆插件）
模型如何行动结构化 JSON 工具调用在持久 IPython 里写 Python，唯一内置工具是 ipython原生工具调用，但工具集本身按会话由 preset 拼装，工具面还可整体换成 Code Mode（run_code）
系统的心脏agent-loop 两层循环持久 kernel + 宿主桥append-only 会话日志 + 可替换的 Agent 驱动（agent-loop 只是默认实现）
扩展机制TypeScript 扩展系统/refine 自我改进 harness插件树：任何能力（含循环本身）都是注册进 Context 的插件，可装卸、可 patch、可自修改
子代理扩展自行实现rlm(...) 函数调用subagent capability：一个模型工具、七个传输后端（spawn/fork/acp/codex/claude-code/dsh-sdk…）
执行环境本机 bashIPython kernelcapability seam：fs/subprocess/shell 是三个可换后端，本地 ↔ 沙箱 ↔ 远端（e2b）整体迁移
界面终端 TUI终端 TUI浏览器 Web UI：连 Cordis 运行时本身都跑在浏览器里
会话真相源消息数组 + 会话树消息 + kernel 变量空间append-only 的 SessionEvent 日志，「模型可见 ⟺ 已记录」是运行时不变式

一句话概括差异：pi 把复杂性挡在核心之外，Prime 把执行搬进解释器之内，而 dsh 宣布核心不存在。后两本书的读者会认出许多熟悉的机制——turn/step 循环、子代理委托、压缩、持久化——但它们在 dsh 里全部换了一套组织方式：不再是模块，而是插件；不再是调用图，而是事件流；不再是「核心提供的 API」，而是「任何插件都能注册的扩展点」。

黄金路径：一次 prompt 的旅程

先建立一条贯穿全书的路径。当你在浏览器里打开 dsh web 启动的 http://127.0.0.1:3080，输入「修一下 auth.ts 里的 bug」，请求会这样流过整个系统：

图 1：一次 prompt 的黄金路径。从浏览器输入到会话日志，每一步都是插件树里的注册项——没有一行代码是「核心」。

这条路径上的每一段都是后续某一章的放大：

  • 从 dsh web 到插件树如何拼成 → 第 2 章
  • Agent 驱动如何把「一条消息」变成「turn/step」并决定要不要再走一步 → 第 3 章
  • 每一步的每个事实如何写进会话日志、模型历史如何从日志投影 → 第 4 章
  • 模型输出的工具调用如何走完注册、守卫、执行、后处理四段管道 → 第 5 章
  • 提示词、运行时上下文与压缩如何装配进每一次请求 → 第 6 章
  • read/bash 等工具如何经能力接缝落到可换的执行后端 → 第 7 章
  • LLM 请求如何经 adapter 流出、chunk 如何聚回消息 → 第 9 章
  • 每一步的渲染如何经 WebSocket 推回浏览器、按日志重放 → 第 17 章

代码组织：五十多个包的插件树

dsh 的仓库由 packages/ 下五十多个 npm 包（@deepseek-ai/dsh-*）组成，外加 vendor/（vendored 的 Cordis 源码）、apps/（cli 与 web 两个表面）、python/（Python SDK）与 native/（Landlock 沙箱 addon）。理解它们各自的职责与边界，是理解整个系统的前提：

图 2：代码组织。底层是 vendored 的 Cordis 插件框架；产品层是一组「能力接缝」（三件套）与「产品包」；两个表面（CLI 与 Web）只是不同的装配入口。
位置一句话职责对应章节
vendor/cordis插件框架：Context、Service、事件、effect、Loader（vendored 源码）第 1 章
packages/core/*产品 API 脊柱：session 日志、system-prompt、tools、agent 接口、agent-loop第 3–6 章
packages/{fs,subprocess,shell,terminal,lsp,llm,sandbox,web}/*能力接缝三件套：Service Definition / Provider / Consumer第 7–9 章
packages/{skill,subagent,workflow,goal,plan,todo,jobs,schedule}产品能力：技能、子代理、多代理编排、目标与任务第 10–13 章
packages/{session,storage,settings,credentials,identity}持久化、设置、凭证与匿名身份第 14–15 章
packages/{preset,bundle,extensions,hooks,mcp,interaction}预设、自修改、生态集成与审批交互第 16 章
packages/client/* + packages/{api,typert} + apps/web浏览器 UI、API 网关、类型图协议第 17 章
packages/{acp,sdk} + python/ACP、JSON-RPC 与 Python SDK第 18 章
packages/boot + apps/cli启动装配：profile、bundle、patch 分层第 2 章

全书结构

全书七个部分。第一部分建立全景——为什么「一切皆插件」成立，插件树如何从配置里长出来；第二部分是本书的心脏，拆开核心循环的四个支柱：Agent 驱动、会话日志、工具管道、提示词与上下文；第三部分讲能力接缝——dsh 如何把「可替换的能力」做成显式的一等概念；第四部分讲多代理与长任务；第五部分讲会话的持久性、身份与扩展生态；第六部分讲界面与协议；第七部分是结语。

第一部分 · 总览

在深入任何机制之前，先看清整个系统的形状——以及它为什么敢说自己没有核心。

  1. 01架构总览：一切皆插件Cordis 四件套、三域事件、turn flow 鸟瞰、范式对照
  2. 02启动装配：从 dsh web 到插件树CLI、profile/bundle、patch 分层、app-boot、配置 HMR

第二部分 · 核心循环

模型请求如何变成日志里的一串事实，工具如何执行，上下文如何装配。

  1. 03Agent 接口与 agent-loop：turn/step 状态机Agent 接口、Inbox、瀑布事件、取消与 max-tokens sticky、scope
  2. 04会话日志：可重建的真相源SessionEventMap、声明合并、deriveMessages、模型可见 ⟺ 已记录
  3. 05工具系统：注册表与执行管道ToolDefinition、五段管道、守卫与超时、Code Mode
  4. 06提示词、上下文与压缩分节注册、BlockAssembler、运行时上下文投影、compaction capability

第三部分 · 能力接缝

可替换的能力不是「接口 + 实现」，而是定义、提供、消费三个角色组成的一等概念。

  1. 07能力接缝：三件套与可换后端Service Definition / Provider / Consumer，fs/subprocess/shell/terminal 实例
  2. 08沙箱与代码执行wrap-argv 接缝、Landlock native addon、平台链、e2b、code-runtime
  3. 09LLM 接缝与流式block/chunk/finish 词汇、BlockAssembler、prepareCall、DeepSeek adapter
  4. 10技能系统SKILL.md、provider 注册表、skill 工具、目录与手势注入

第四部分 · 多代理与长任务

一个 agent 不够时：委托、编排，以及让工作跨越时间的状态。

  1. 11子代理：作为能力的递归provider 注册表、one-shot 与 continuable、send_message、事件回流
  2. 12workflow：模型自写的编排脚本脚本钩子、worker-thread provider、并发与上限、与 subagent 的分工
  3. 13目标、计划与后台任务goal 状态机、plan mode、todo_write、jobs、schedule

第五部分 · 会话、身份与扩展

会话如何活过重启，系统如何被配置、被信任、被扩展。

  1. 14会话持久化与投影write-behind、JSONL、崩溃修复、projection、标题、storage
  2. 15设置、凭证与匿名身份settings 接缝、credentials 分层引用、anonymous user id
  3. 16预设、自修改与集成生态preset、bundle、cordis 工具族、Claude Code/Codex hooks 桥、MCP、审批

第六部分 · 界面与协议

浏览器是另一个运行时，协议面让机器也能对话。

  1. 17Web 界面与 API 网关浏览器里的 Cordis、ConversationNode、非对称传输、Typert 类型图
  2. 18协议面：ACP、JSON-RPC 与 Python SDKAgent Client Protocol、JSON-RPC 传输、Python 一等公民

第七部分 · 结语

  1. 19结语：插件化的赌注架构赌注盘点、可迁移的模式、未尽的代价

代码引用约定

  • 书中所有文件路径均相对于 dsh-src/ 目录（即 DeepSeek Harness 仓库的根）。例如 packages/core/agent-loop/src/agent.ts 指 dsh-src/packages/core/agent-loop/src/agent.ts。
  • 代码片段为便于讲解可能省略部分类型标注或分支，但函数名、类型名、字段名与文件位置均与源码一致，可直接检索核对。
  • 中文行文；代码、标识符、文件路径、CLI 命令保持英文。
  • 分析基于的版本为 monorepo 0.1.0-rc.5（developer preview，迭代很快，细节可能已漂移；以源码为准）。

适用人群

  • 构建 Agentic 系统的工程师——想看「插件化 harness」如何落地：事件溯源式会话、可替换循环、能力接缝都是可迁移的模式。
  • 写过或读过工具调用型 agent 的团队——本书与《Pi Agent 源码解析》《Prime Agent 源码解析》构成三本对照读物，三条路线放在一起读收获最大。
  • 对「agent 自修改运行时」感兴趣的读者——第 16 章的 cordis 工具族让你看到模型亲手把插件装进自己运行时、再卸载自己的完整闭环。

免责声明

本书为独立的技术分析，纯属教育目的。DeepSeek Harness 是 DeepSeek AI 的产品，本书与其无关，未获背书或赞助。书中观点为作者基于源码的解读，如有错漏，以源码为准。