DeepSeek Harness 深度源码解析：当「万物皆插件」遇上形式化理论！

admin@yesmiracle.net (万戈) — Wed, 02 Sep 2026 00:00:00 +0000

引言：破纪录的 Agent 运行时

2026 年 8 月 13 日，DeepSeek AI 做了一件它从未做过的事——开源了不是模型，而是模型周围的基建。DeepSeek Harness（CLI 名 dsh）以 MIT 许可证发布，两天内收割 95,000 星，四天内突破 140,000，刷新了 GitHub 星数增长速度的历史纪录。截至今天，该仓库拥有 208,000 颗星和 24,200 个 Fork。

为什么一个 Agent 运行时框架能引起如此大的轰动？答案藏在它的副标题里：「Everything is a Plugin」。

这不是一个营销口号。DeepSeek Harness 背后有一套完整的、拥有形式化证明的插件理论——Cordis。这篇文章将从源码架构的视角，拆解这个系统究竟做了什么，以及它为什么可能改变 Agent 基建的格局。

什么是 Agent Harness？为什么需要它？

在讨论 DeepSeek Harness 之前，先厘清一个关键区别：Agent Harness ≠ Agent Framework。

Agent Framework（如 LangChain、CrewAI）提供编排原语——链、路由、多 Agent 拓扑，偏重组织逻辑。
Agent Harness 提供运行时——模型适配、工具注册、会话管理、权限策略、沙箱、持久化。它负责让 Agent 活着并安全地与世界交互。

DeepSeek Harness 属于后者。它是将 LLM 连接到真实世界的中间层：文件系统、终端、网络、编辑器、数据库，以及权限边界。它的设计目标是忽可替换、可组合、可热插拔，而这一切的基础是Cordis。

我们此前拆解过 Lasso MCP Gateway 的三层插件体系，也深入过 AgentSight 的 eBPF 观测框架，但 DeepSeek Harness 的插件体系的野心比所有这些都大一个量级——它不是在一个产品的某个层面做插件化，而是整个运行时本身就是插件组合的结果。

Cordis：藏在 Agent 底下的形式化插件理论

理解 DeepSeek Harness 的关键在于理解 Cordis。这不是一个临时搭起来的插件管理器——它是一个有独立 GitHub 仓库、有多年生产验证、有 arXiv 论文的元框架。

论文背景

Cordis 的设计文档是《A Programming Paradigm for Spatiotemporal Composability》（arXiv:2608.25512），88 页，由三位作者联合署名：Shi Yifan（北京大学 & DeepSeek-AI）、Wei Zhang（北京大学）、Tianyi Cui（DeepSeek-AI）。

这是一篇编程语言论文，产自 AI 实验室内部。它回答的问题非常底层：如何组合一个运行时还在变化（动态组装）的软件系统？

论文证明了五个定理，涵盖效应复合的可交换性、卸载的原子性、依赖图的循环死锁避免等。这是 Agent 领域罕见的、拥有形式化证明的基建层工作。

时空分离：Effect + Coeffect

论文将动态组合拆解为两个正交维度：

时间维度：可逆效应（Revertible Effects）

插件加载时做的一切——注册命令、挂载事件、打开连接——都是对共享上下文（Context）的效应（Effect）。Cordis 要求每个效应携带自己的逆操作。当插件卸载时，运行时会自动执行逆操作链，回滚所有效应。

没有残留的监听器，没有悬挂的连接，没有幽灵命令。

回滚不再依赖手写的 cleanup() 函数，而是成为运行时语义的一部分。

空间维度：反应式共效应（Reactive Coeffects）

如果说 Effect 是插件对系统做了什么，那么 Coeffect 是插件需要系统提供什么——数据库、模型、服务。Cordis 允许插件声明这些依赖，运行时管理生命周期：依赖未就绪时不激活，依赖变化时自动停用或重构。

论文的核心理念是将两者统一到同一个上下文机制中，使得 Effects 和 Coeffects 被同一套引擎追踪。

Cordis 在生产中的实践

Cordis 并非为 DeepSeek Harness 而生。它是一个独立项目，在 Agent 领域之外已有多年生产经验。DeepSeek Harness 将其作为依赖引入，在其之上构建了完整的 Agent 运行时。

Cordis 的核心 API 包括：

Context — 共享上下文，所有插件注册的载体
Events — 类型化事件系统，插件间通信的管道
Service — 服务声明与发现机制
Fiber — 轻量级执行单元，管理异步生命周期
Plugin Registry — 插件注册表，管理安装、激活、卸载

架构详解：从 Profile 到 Bundle 到 Subsystem

Profiles 与 Bundles

DSH 的启动是一个插件树的组装过程。结构如下：

[空配置层 []]
  → Bundle 1（dsh-base）
  → Bundle 2（dsh-web-app / dsh-headless / dsh-sdk-app / dsh-acp-app）
  → cordis.patch.yml（用户级配置覆盖）
  → --patch（运行时 overlay）

每个 Profile 是一个命名的组合配置。DSH 预置了 5 个 Profile 模板：

Profile	用途	启动命令
`web`	全功能 Web UI，默认端口 3080	`npx @deepseek-ai/dsh web`
`headless`	无服务器单次运行器	`dsh --profile headless`
`sdk`	JSON-RPC 服务模式	`dsh --profile sdk`
`sdk-minimal`	最小化 SDK（不使用 dsh-base）	`dsh --profile sdk-minimal`
`acp`	自动化 ACP 服务器	`dsh --profile acp`

每个 Bundle 是 Cordis 配置行 + 对应代码的发布格式。dsh-base 是所有核心 Profile 共享的第一层：模型适配器、工具、持久化、沙箱、审批策略、设置、凭据、遥测。

查看当前机器启动的完整插件树：

dsh --profile web --dump-config

输出的每一行都可以通过你自己写的 patch 替换。这是整个系统的核心哲学——没有特权核心。

核心子系统一览

DSH 采用 Monorepo 结构，核心包划分清晰：

core/session — 仅追加（append-only）的 SessionEvent 日志 + 内存存储
core/system-prompt — Prompt 段组装 + 工具 Schema 组合
core/tools — 带作用域的工具注册 + 守卫执行管道
core/agent — Agent 接口、实时注册表、agent/* 事件
core/agent-loop — 默认的 Agent 驱动实现
llm/llm — 消息/流词汇表 + 适配器层接口
webhook/webhook — 认证投递调度 + Workspace Session 创建

每个核心子系统对应一个 ctx 键，实现了完整的依赖注入和生命周期管理。

Turn Flow：Step 与 Turn 的精确划分

DSH 在 Agent 执行模型上做出了一个重要的区分：

Step（步骤） — 一次模型请求 + 该请求调用的工具
Turn（轮次） — 零次或多次 Step，从接收输入开始，到没有欠任何响应时结束

执行流如下：

turn/start
  认领输入
  组装 Prompt + 工具 Schema
  → agent/pre-step
    step/start
    追加用户消息
    推导模型历史
    agent/request → llm/stream → assistant/chunk* → assistant/message
    tool/call* → tools/pre-execute → tools/execute → tools/post-execute
    step/end
    （工具要求继续 或 新输入到达 → 下一个 step）
  → agent/turn-stopping
turn/end

关键设计点：turn/*、step/*、assistant/*、tool/* 是持久化会话事件，记录在仅追加日志中。agent/pre-step、agent/request 等是实时扩展点，采用瀑布式调用（listener 必须调用 next() 才能继续传递）。agent/turn-stopping 是串行的且没有 next()。

会话日志：模型可见即日志

DSH 有一条严格的不变式：

模型看到的任何内容，必须可从会话日志中重建。

deriveMessages() 从日志投影出模型历史。原始 assistant/chunk 事件保留回放和 UI 保真度。Fork、恢复、转录、遥测、持久化都从这条流推导。

这意味着：如果需要添加一个新的模型可见的输入，就必须扩展 SessionEventMap 并实现从日志渲染的逻辑。没有悄悄绕过日志的路径。

Capability Seams：可替换能力的三层结构

DSH 定义了 Capability Seam（能力缝） 的概念——可替换的能力单元，由三个角色组成：

Service Definition — 声明接口
Service Provider — 实现接口
Consumer — 使用接口（通常是模型面的工具）

一个包可能组合多个角色，但单一角色本身不是 Seam。真正的替换需要设计全部三个角色。

这就是为什么切换一个 Provider 就能改变整个产品的行为。Filesystem 和 Subprocess Provider 共享同一个执行世界——将它们指向远程沙箱，Bash、PTY、LSP 都会被一起迁移，不需要为每个单独创建分支。

Capability Seam 的设计思想与 MCPZERO 中的 Provider 抽象有异曲同工之处——都通过接口层将底层实现与上层策略解耦，使得安全策略的替换不需要修改工具调用本身。

事件即扩展点

DSH 的事件系统分为三个领域：

Session 事件 — 持久化事实，追加到日志并通过 session/event 广播
Agent 事件（agent/*）— 携带实时 Agent Handle，用于观察或拦截飞行中的工作
能力事件 — 在 seam 上挂载策略和适配器（fs/*、tools/*、telemetry/*），不侵入 Loop

四种运行模式

DSH 支持四种运行模式，覆盖从开发者个人工具到 CI/CD 管道的各种场景：

Web UI（dsh web）— 全功能浏览器界面，默认端口 3080
Headless（dsh --profile headless）— 单次运行，无服务器进程
SDK（dsh --profile sdk）— JSON-RPC 服务模式，支持 Python SDK
ACP（dsh --profile acp）— 自动化协议服务器模式

同一套代码，同一个 CLI，支撑从开发者本地调试到 CI/CD 自动化到多 Agent 分布式系统的各种用例。

横向对比：与同类系统的差异

维度	LangChain	Anthropic MCP	DeepSeek Harness
核心范式	链式编排	工具发现协议	插件化运行时
热插拔	ẑ 需重启	N/A（协议层）	✅ 实时重载
形式化基础	❌	❌	✅ Cordis 定理
会话日志	可变	可变	✅ 仅追加（append-only）
能力替换方式	复写类	切换 Server	✅ Patch 配置层
运行时安全	依赖外部	依赖 Host	✅ 内置沙箱 + 审批策略

DSH 与其说是一个框架，不如说是一个 Agent 操作系统内核——它不规定你怎么写 Agent 的业务逻辑，而是提供了装载、运行、监控、替换这些逻辑的运行时基础设施。

从源码看设计哲学

深入源码 docs/architecture.md，可以感受到 DSH 的设计文档写得极其严谨。整个架构文档被组织为 40+ 个子系统和参考文件，每处事件接口、每个 seam 定义都有精确的说明。对比很多开源项目「README 即一切」的做法，DSH 的文档质量本身就是一种工程信号。

几个让我印象深刻的源码设计细节：

app-boot 的 Profile 组装逻辑 — 代码清晰地展示了空配置列表如何被各层 bundle patch 逐步充实。每个 patch 定位到具体 row 的 id，不是模糊的「加载顺序」。
session-projection 的设计 — 这是一个「必选 seam」。想读取会话状态的人必须注册这个服务，不存在「悄悄跳过」的路径。这种强制执行在 Agent 框架中极为罕见。
dsh-sdk-minimal 的独立性 — 它故意不继承 dsh-base，实现了完全独立的 SDK 插件树。这展示了 Cordis 插件模型的可组合性极限——你可以构建自己的 bundle stack 而不依赖任何预置层。

局限与风险

客观来看，DSH 仍是 Developer Preview 阶段，README 明确标注了「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」：

Node.js 生态依赖 — 整个系统基于 pnpm/Monorepo，Python SDK 通过包装器调用底层 CLI。对于 Python-first 团队，这不是原生体验。
学习曲线陡峭 — Cordis 的时空组合模型不是主流编程范式。开发者需要理解 Effect/Coeffect、Fiber、Patch 层等概念才能有效扩展。
文档仍在建设中 — 虽然有详尽的架构文档和子系统参考（40+ 个参考文档），但实际使用中社区插件仍较少——毕竟上线不到三周。
DeepSeek 品牌依赖 — 项目虽开源 MIT，但核心维护方是 DeepSeek AI。社区治理模式、外部贡献流程有待观察。

写在最后

DeepSeek Harness 的开源不仅是 DeepSeek 公司的一次策略转变——从闭源模型公司走向开源基建提供方——更重要的是，它引入了一种 有形式化理论支撑的 Agent 运行时架构。

「Everything is a Plugin」之所以不是空话，是因为底部有 Cordis 的五个定理保证插件的可逆加载、安全卸载、依赖驱动生命周期。这种严格性在 Agent 基建领域极为罕见。大多数 Agent 框架仍停留在「框架作者写了什么就怎么运行」的阶段，而 DSH 尝试回答：我如何证明一个新插件不会破坏正在运行的系统？

对于 Agent 基建创业者、AI 安全研究者、以及关心下一代 Agent 架构的人来说，研究 DeepSeek Harness 的源码（14,874 次提交，208K 星）可能是理解 Agent 运行时下一步演化方向的最佳起点。

资源链接：

GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
官方文档：https://deepseek-harness.github.io/deepseek-harness/
Cordis 论文：https://arxiv.org/abs/2608.25512
Cordis 仓库：https://github.com/cordiverse/cordis
DeepSeek Harness Discord：https://discord.gg/Ycq5dCaS4

架构分析 on AI博士 万戈