DeepSeek 开源的智能体框架凭什么“一切皆插件”？11 页图解，一次拆透
从插件生命周期、主循环、会话日志到分层配置，用 11 页图解理解 DeepSeek Harness 的架构、组合方式与交付边界。
DeepSeek 开源了智能体框架 DeepSeek Harness（下文简称 DSH）。本文讨论的是开发者预览版，采用 MIT 许可，源码在 GitHub 上（deepseek-ai/deepseek-harness）。
先解释一下 harness 这个词。DeepSeek 官方的说法是：Agent = Model + Harness。模型是智能体的灵魂，但光有灵魂干不了活——理解环境、调用工具、在真实系统里持续工作，这些靠的是 harness。你可以把它理解成一辆车的底盘、方向盘和仪表盘：不产生动力，但决定动力能不能安全地用到路上。
DSH 的特点是：没有写死的智能体业务核心。主循环、日志、重试、审批、上下文压缩、模型接入、界面，都由可替换的插件提供。官方口号是 Everything is a plugin，一切皆插件。这里的“没有内核”是一种图解表达：底层仍有 Cordis 内核，负责插件加载、卸载与依赖关系，只是不把智能体能力写死在内核里。
这篇文章用 11 页图解把它拆开讲清楚：积木怎么拼、怎么配合、为什么这样设计。不需要任何技术背景，适合正在给团队选型 agent 框架的人读完。
一、它是什么：一个没有固定业务核心的框架
先把整张地图摊开。在 DSH 里，审批、重试、上下文压缩、会话日志、沙箱、模型接入、网页界面，全部是插件，和你自己写的插件使用同一套机制。底下的基座负责插件的加载、卸载和依赖关系。
这和多数框架的思路是反着的。常见的框架是“一个写死的核心，加几个允许你插手的口子”：核心管主循环、管记忆、管重试，作者心情好就给你留个 hook。口子留多少、留在哪，全看框架作者。
DSH 把这个逻辑倒过来了：
别人留口子，它给你整块地。连主循环、日志、重试都是插件，和你写的没有区别——不存在「官方能做、第三方做不了」的事。
举一个具体例子：DSH 有一个「兼容 Claude Code 钩子」的功能。按照别的框架的做法，这种官方功能多半要走特权通道。在 DSH 里，它就是一块普通插件——和你在社区里下载的、自己写的插件走完全相同的装卸流程。
但这个设计有代价，图解里没有回避，我们也不回避：行为由很多积木共同决定，出了问题更难查。传统框架出了 bug，你翻框架源码；DSH 出了问题，你要先弄清楚是哪几块插件在哪个环节互相影响。自由换来的是排查成本，这是一笔明账，不是免费午餐。
DSH 的基座构建在开源插件系统 Cordis 之上。选择已有的插件系统做底座，而不是从零自造一套，是一个值得注意的工程判断。
二、积木怎么拼：登记、状态、主循环
插件不是补丁，是一位新入职的同事
DSH 插件的扩展方式是向系统登记自己能提供什么：像新同事入职，登记自己的职责和能力，通过宿主接口参与工作。这是一种设计方式，不是“插件代码无法修改共享状态”的安全保证。
常用的登记有五种，正好对应插件能提供的五类能力：
① 加一个工具——让模型多一样能调用的能力，比如一个查数据库的工具；
② 加一段提示词——告诉模型要守的规矩，比如“输出前必须引用来源”；
③ 订阅一个事件——在某个环节被通知或拦截，比如“每轮结束前让我看一眼”；
④ 提供一项服务——让别的插件来调用，插件之间这样分工协作；
⑤ 挂一块界面——把自己做的界面放进网页的预留位置。
关键规则是：登记和撤销成对出现，撤销由生命周期管理。插件卸载时，通过受管理接口登记的工具、提示词、事件、服务和界面会被清理。它能减少插件增多后的残留；但插件自行创建的外部副作用、未纳入管理的资源，不会因此自动回滚。
每个插件只有三种状态：等、干、走
基座怎么决定一块插件什么时候上岗？每个插件要事先声明“我离不开谁”（依赖），基座据此安排生命周期，一共三个状态：
等——依赖没到齐，先不启动；
干——依赖到齐，启动并登记；
走——被关掉或依赖消失，登记全部撤销；依赖回来时，自动重新上岗。
这带来三个实际好处：可以支持不重启替换插件；不同对话挂不同能力；智能体在运行中扩展能力。最后一条是这套架构值得关注的可能性，实际能做什么，仍取决于部署提供的插件和权限。
主循环：AI 每走一步，都绕这个表盘一圈
最核心的主循环，本身朴素得让人意外——就是右边这个表盘，六步一圈：
① 整理资料（提示词＋工具＋历史）→ ② 开工前检查（可拦截）→ ③ 问模型（出错可重试）→ ④ 记下回复写入日志 → ⑤ 执行工具（执行前可拦截）→ ⑥ 记下结果写入日志。转到模型不再调用工具为止，这一步才算完。
那重试、压缩、审批这些“聪明”的行为在哪？答案是：都不在循环里。它们是别的插件在表盘的红点处插手实现的——红点就是插件可以喊“等一下”的位置。比如你的合规插件想在工具执行前做一次检查，不需要改框架代码，写一块插件挂在第 ⑤ 步的红点上就行。
在这份图解描述的主循环中，没有写死最大步数限制；设上限也是可以加上的策略。评估实际部署时，应检查所用版本与配置中的停止条件和预算控制，不能假定默认行为适合所有任务。
三、一本账：会话日志为什么是被低估的设计
如果整套架构里只让记一条设计，我们选会话日志。它的规则简单到近乎笨拙：只有一本账，只能往后追加，不能修改。对话不是存在内存里的某个对象，而是一条只增不改的日志——连系统提示词都是日志里的一条记录，和用户提问、模型回复平起平坐。
这本账为六类能力提供了共同的数据基础：
模型看到的对话——每步从日志推导上下文，减少“内存里的对话”和“日志里的对话”不一致的问题；
界面上的状态——从同一份记录展示运行轨迹，便于对照模型获得的上下文；
崩溃后恢复——通过重放恢复已记录的会话状态；外部工具已产生的副作用仍需另行处理；
从任意处分叉——复制前半段，另起一条线试别的方案；
上下文压缩——只是“隐藏”早期内容，原文还在账上，随时可查；
审计留痕——谁在什么时候让模型看了什么、调了什么工具，账上全有。
我们的看法是：只增不改的日志，是智能体框架中被低估的设计。它在演示时不显眼，却决定团队能否还原一次运行。DSH 给可追溯性提供了数据结构基础；生产环境里的审计，仍需要保存期限、访问权限、完整性保护以及外部系统记录等配套措施。
这一页还有一句话值得单独抄下来：
模型看到的内容，应当能在日志中找到对应记录。日志与上下文构建，应该能够互相对照。
反过来看更有用：想知道插件对模型做了什么，检查它追加了什么记录，以及上下文如何由这些记录生成。文档描述意图，运行轨迹帮助你核对实际发生的事。
插件之间不用认识，靠广播和闸门
几十块插件互不认识，怎么配合？靠事件系统，一共两种：
通知型——“某件事发生了”。发出的一方不知道谁在听，听的一方也不需要对方同意，只能知道、不能改变结果。例：一轮对话结束了，自动起个标题；工具跑完了，抄送一份给审计。
拦截型——“某件事要发生了，谁有意见”。事件逐个经过每个订阅者：放行、修改、或者拒绝。例：工具执行前做合规检查；请求出错后，决定要不要重试。
拦截型事件是 DSH 最强的扩展点——重试、压缩、审批、沙箱、计划模式，这些听起来很“核心”的能力，全部是用它实现的。这也再次印证了第一部分那句话：官方功能和你写的插件，走的是同一条路。
但图解里有一条警告必须原样转述，因为它是实际使用中最容易踩的坑：多个插件守同一道闸时，结果和先后顺序有关，而基座不替你排顺序。比如插件 A 想拦截并修改，插件 B 也想拦截并修改，谁先谁后，最终结果可能不同。这是组合插件时最该测试的地方——不是“能不能跑”，而是“多个拦截器叠在一起时，行为是否符合你的预期”。
四、怎么装配：清单层层叠加
“装哪些插件”就是一份清单。对清单的修改只有三种：插入、替换、关闭。而真正的关键在于，清单不是一份，是层层叠加的——上层覆盖下层，一共四层：
第一层 · 厂商的安装包（bundle）——一组插件＋怎么装配它们，带版本号发布；
第二层 · 这家客户的调整——开关、阈值、模型路由；
第三层 · 个人的调整——我自己加的、关掉的；
第四层 · 启动参数里的临时修改——最后生效，优先级最高。
这套叠法解决的是厂商升级与客户定制如何共存：厂商升级基础层，客户与个人修改保留在各自的层里。配置没有被覆盖，不等于升级绝不会产生兼容问题。插件接口与行为变化后，仍需验证上层配置能否继续工作。
注意图解里那句话：这不是一项额外开发的功能，是装配方式自带的性质。分层清单这种结构，天然就把“谁的修改记在谁那一层”分开了。
插件、bundle、patch、profile、preset：一条装配线上的五个位置
读 DSH 资料会反复遇到五个词，容易绕晕。其实真正在跑的只有插件，其余四个词回答的都是同一个问题：哪些插件、以什么配置、装给谁。
① 插件——一块积木，真正在跑的代码；
② bundle 安装包——一盒积木＋一张装配说明，厂商发布、带版本号（装配说明本身就是一份内置的 patch）；
③ patch 调整单——对清单的修改，只有插入、替换、关闭三种；
④ profile 运行环境——一个目录：用哪些 bundle＋自己的 patch，层层叠加（启动时的临时 patch 优先级最高）；
⑤ 进程与 preset 岗位配方——启动后是一个进程；每个对话再各选一份 preset，决定这个“AI 员工”会什么。
最后一层值得展开。进程分两层：宿主层全进程共用（模型、日志、工具表、网页界面，由 profile 决定）；agent 层每个对话各挂各的，由 preset 决定。preset 也是一份“一行一个插件”的清单，语法和 profile 完全相同——删掉 bash 那一行，这个岗位就没有 bash。
所以同一个进程里，对话 1 可以是投研岗，对话 2 可以是合规岗，对话 3 可以是宏观岗。拼出来的不是一个“产品”，是一个正在运行的、千人千面的进程。
五、放回坐标系：它和 MCP、Skill、Hook 是什么关系
读到这里你可能会问：已经有 MCP 和 Skill 了，为什么还需要一整套插件体系？一张图说清分工：
MCP——给模型加工具，像请外部供应商；
Skill——教模型怎么做事的操作手册；
Hook——在关键环节拦截的门口检查岗；
DSH 插件——像常驻员工：既可以参与工具、提示词和事件机制，也能提供服务、扩展界面、保留状态。这里比较的是扩展范围，不代表插件直接替代了 MCP 协议或 Skill 的封装形式。
更贴切的类比是浏览器扩展：常驻宿主，参与宿主本身的行为。这个比喻描述架构角色，不是技术标准之间的严格等价。
MCP 和 Skill 在支持它们的平台之间通常更容易复用，但仍要检查兼容性。选型时，可把数据接入与方法沉淀为便于迁移的 MCP 和 Skill；把与运行时紧密相关的拦截、上下文注入和界面扩展放进 DSH 插件。
这套架构对“驻场式交付”意味着什么
驻场式交付（FDE，Forward Deployed Engineering）的难点，从来不是给第一家客户做出第一个 agent——而是做到第十家客户时，还能不能复用前九家的积累。用这个标准看 DSH 的架构，会发现它的几个设计几乎逐条对上了交付场景的真实需求：
做过的东西要能复用 → 插件打成 bundle，带版本号，一次开发、多家交付；
每家客户都不一样 → 差异写成 patch 和 preset，不用改插件代码；
持续升级保留定制 → 厂商配置与客户修改分层保存，升级时仍需验证兼容性；
要深入改造 AI 行为（合规、审计、记忆）→ 没有内核＋拦截型事件，任何环节都能插手；
运行过程可追溯 → 只增不改的会话日志为排查、恢复、分叉提供基础，再补齐实际部署所需的控制；
支持本地模型与数据 → 模型接入可通过插件替换；但本地运行不等于数据不会出网，仍需检查模型端点、工具、插件和外部连接；
长期运营，调用成本要可控 → 整体架构围绕缓存命中设计。
图解报告了 95% 以上的缓存命中率，我们自己的环境尚未复测，应当视为未经验证的参考值。缓存效果取决于对话结构和使用方式，别人的数字不能替代自己的成本测试。
提供的材料还列出三条短板，评估时需要对照实际部署版本：
接口仍在演进；插件共享进程，并不自动获得安全隔离；多用户访问、团队记忆与协作空间还需要额外的产品建设。
这些问题也指出了值得动手的位置：运行时隔离、团队记忆与会话日志的关系、多用户权限模型。交付团队可以把这些工作逐步积累成可复用的产品能力。
你可以先做什么
如果只做一件事，建议是这个：跑一次 DSH，把一次完整任务的会话日志导出来，从头看到尾。装好 Node.js 之后一行命令：
npx @deepseek-ai/dsh web重点检查：系统提示词以及每项传给模型的上下文，是否都能在记录中对应起来。再尝试只凭日志还原一次任务。这能为判断恢复、分叉和可追溯能力建立一个具体标准。
最后提醒一句：DSH 还在开发者预览期，官方明确说核心插件和接口还会变。现阶段值得投入的是看懂架构的时间，不是押注的时间。架构判断做对了，接口怎么变都接得住；架构没看懂，追 API 文档追得再紧也是白忙。
参考资料
2. GitHub · deepseek-ai/deepseek-harness
3. 本文由所提供的公众号原稿及 11 页图解改编，英文配图采用 DSH-Core-Mechanisms-EN-v3，繁中配图由中文图解转换。图解用于解释架构，具体实现以官方文档和实际使用版本为准。