把 AI Agent 框架拆成插件树,DeepSeek Harness 架构到底强在哪?

当 AI Agent 框架开始"卷"底座

我先讲个真实场景。

你想给自己的产品接一个 AI Agent。打开 GitHub 搜一圈——Claude Code、Cursor Agent Loop、LangChain、CrewAI，每个都写着"强大、可扩展、生产可用"。

你点开源码一看：核心循环和插件机制焊在一起，工具注册和 UI 渲染搅成一锅，模型适配器藏在你找不到的角落。想加一个"调用内部数据库"的能力？对不起，要么 fork 整个项目，要么等官方更新。

为什么所有的 Agent 框架都长得这么"硬"？

因为大多数框架在写第一个版本的时候，根本没想过"换底座"这件事。模型、工具、UI、Agent 循环、持久化——都耦合在一棵主干上。等到用户想换模型、换工具、换执行环境时，只能硬 fork。

DeepSeek 团队刚开源的deepseek-harness干了一件不一样的事：

把整个 Agent 框架变成一棵"插件树"——核心就是加载插件，连 Agent 循环本身都是一个插件。

它到底是个什么东西

一句话定位：DeepSeek Harness（dsh）= DeepSeek 出品的开源 Agent 运行时底座。

它不是一个完整的 Agent 产品，也不是某种聊天界面。它是"Agent 跑起来需要的那套基础设施"——Agent 循环、工具注册、模型适配、会话日志、事件总线、能力注入，全部以插件形式存在。

最反常识的一点：它自己的"Agent 循环"也是一个插件。

也就是说，你想换 Agent 循环？写个插件挂上去就行。想换模型？写个插件挂上去就行。想换文件系统、换 Shell、换沙箱、换工具执行管线？全都是插件。

它有一个内部代号dsh，目前是 0.1.0-rc.5 状态，开发者预览版，每周都在快速迭代。

让我眼前一亮的 4 个设计

1. "一切皆插件"是真的，不是营销话术

很多框架嘴上说"插件化"，但你看一眼源码就知道：核心循环里硬编码了十几处 if-else 走不同分支。插件只能填边边角角的洞。

dsh 不一样。它的核心只有一件事——"按顺序加载插件树"。每个插件注册三类东西：

• 服务（Service）—— 一个可调用的能力
• 事件（Event）—— 一个可监听的信号
• 副作用（Effect）—— 一个会自动反注册的状态

插件卸载时，所有副作用会自动回滚。这等于把"插件生命周期"做成了一等公民。

底层依赖的是一个叫 Cordis 的框架，作者专门写了篇论文《A Programming Paradigm for Spatiotemporal Composability》来解释这个范式。

2. Profile + Bundle 的分层组合

一个跑起来的 dsh 实例，是一棵"插件树"。它由几层组合而成：

• Profile（配置）—— 一份"我要加载哪些 Bundle"的清单，存放在用户家目录
• Bundle（分发包）—— 一组 Cordis 配置 + 实际代码，可以独立分发
• Patch（补丁）—— 用户自己的覆盖层，最顶层生效

比如官方提供了三个 Bundle：

• dsh-base—— 模型适配、工具、持久化、沙箱、配置、凭据、遥测
• dsh-web-app—— 浏览器端的 Web UI
• dsh-headless—— 无服务器的 one-shot 执行器

要查看当前机器实际启动了什么，跑一行命令：

它会打印完整的插件树。每一行你都可以用 patch 替换成自己的实现。

这意味着 dsh 不强迫你"全盘接受官方实现"。你可以只换模型适配器、只换沙箱后端、只换 UI，其他一切照旧。

3. Session Event 是模型的"唯一真相"

Agent 框架里最容易乱的是"状态"。模型看到了什么、工具调用了什么、中间发生了哪些事——这些信息如果不集中管理，到处都是拼凑出来的。

dsh 的做法很硬核：模型看到的任何输入，必须能从 Session Event 日志里重建出来。

这是一条运行时不变式，由代码强制保证。如果你新增了一个"模型可见的输入"类型，必须先在SessionEventMap里加事件定义，否则会编译失败。

结果是：fork（分叉会话）、resume（恢复）、transcript（导出对话）、telemetry（遥测）、persistence（持久化）——所有这些能力都从同一份日志派生出来，不会出现"每个模块各管各的真相"的情况。

4. Capability Seams 让"换底座"成为一等操作

dsh 里有个概念叫 Seam（能力缝）—— 一个可替换的能力接口，由三部分组成：

• Service Definition —— 接口契约
• Service Provider —— 具体实现（比如本地文件系统 vs 远程沙箱）
• Consumer —— 使用方（通常是给模型暴露的工具）

一个典型的例子是文件系统 + 子进程：

它们共享同一个"执行世界"。你把本地文件系统的 Provider 换成远程沙箱的 Provider，整个 Bash、PTY、LSP 也跟着一起迁移——不用每个工具单独适配。

Subagent（子代理）也是一样。一个 Provider 可以是"新起一个子 Agent"，也可以是"代理到另一个产品里的 turn"，对外都是同一个接口。

这种"一处替换，全局生效"的设计，是 dh 真正能被称为"基础设施"的原因。

5 步快速上手

步骤 1：装 Node.js

确保 Node.js ≥ 18.0。

步骤 2：一行启动

默认会在http://127.0.0.1:3080启动 Web UI。

步骤 3：从源码运行（可选）

如果你想自己改：

步骤 4：探索架构

打开docs/architecture.md读一遍。如果不熟 Cordis 范式，先看docs/cordis-primer.md。

步骤 5：写第一个插件

按docs/cookbook/adding-a-package.md的步骤，在packages/下加一个目录，注册一个 Service，发布时打上dsh-plugintopic 标签，就能被社区发现。

整个过程比想象中轻——dsh 的"一切皆插件"是认真的。

小结

AI Agent 框架的下一战场，不在"谁的模型更强"，而在"谁的底座更可换"。

DeepSeek 这次开源的 dsh，把"插件化"做成了真正的运行时范式——核心循环、工具、UI、沙箱全部可替换，Session Event 作为单一真相，Capability Seam 让一处替换全局生效。

它不是一个能让你"明天就用起来"的产品。它是给"想做自己 Agent 平台"的人留的一个底座。

如果你正在考虑自建 Agent 基础设施，或者对"插件化运行时"这个范式感兴趣，这个项目值得花一个下午读一读架构文档。

仓库地址：

https://github.com/deepseek-ai/deepseek-harness