DeepSeek Harness架构解析：AgentRuntime的极致设计

我们正在做Agent管理平台在搞Agent Runtime。正好DeepSeek发布了自家的开源Agent Harness——DeepSeek Harness下面简称DSH。DeepSeek出品必出精品。就去翻翻DSH的架构文档和源码看看DeepSeek团队对Agent Runtime的理解跟我们有什么不同哪些设计值得偷师。翻完官方GitHub的architecture.md和整个packages目录结构后说实话有几个设计确实让我眼前一亮。这篇文章不是评测不聊DSH好不好用。我只关心一个问题作为一个Agent Runtime的设计参考DSH给出了哪些值得借鉴的架构决策先搞清楚DSH在做什么定位从GitHub官方READMEDeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI. It uses an architecture where everything is a plugin, and is powered by Cordis.关键词三个open-sourceMIT协议、everything is a plugin一切皆插件、Cordis底层框架。它不是DeepSeek版的Codex。Codex是一个产品DSH是一个Agent运行时——你拿它来组装自己的Agent而不是直接用。一句话总结定位DSH交付的是零件和图纸不是成品。对我们做Agent管理平台的启发是Runtime层应该是可组装的而不是可配置的。可配置意味着在既定框架内调参数可组装意味着连框架本身都能替换。架构核心没有特权核心DSH架构文档里最狠的一句话There is no privileged core to patch: you extend dsh by mounting a plugin beside the others.没有特权核心。模型适配器是插件工具注册表是插件会话日志是插件连Agent Loop本身都是插件。你要改任何一部分不需要fork核心代码只需要挂一个新插件上去。这跟大部分Agent框架的设计完全不同。LangChain的核心链路是写死在代码里的你最多用Callback来旁路监听改不了主干逻辑。OpenClaw的核心循环heartbeat → memory → tools → reply也是固定的骨架。DSH的选择是把骨架也变成插件。代价是复杂度上去了——理解Cordis的事件系统需要学习成本。收益是灵活性极高——同一个进程里可以跑完全不同架构的Agent。对我们的参考价值我们的Agent Runtime在设计时也要想清楚哪些是骨架不可替换哪些是血肉可替换。DSH给出的极端答案是——全是血肉。你不需要走到这个极端但这个方向值得认真考虑。Session Logappend-only事件流DSH对会话数据的处理方式是我在其他Agent框架里没见过的。The session log is the source of the context the model sees. Model-visible means logged.模型能看到的一切都必须能从日志重建。Session Log是append-only的事件流。每一条事件turn/start、step/start、user/message、assistant/chunk、tool/call、tool/result、turn/end都不可修改地追加到日志里。上下文压缩不会删除原始数据——它只是插入一个replacement事件改变模型此后的视图。原始历史永远在。这意味着什么你可以完整回放Agent的每一步决策。Debug时可以精确定位到第3轮第2步模型收到的prompt是什么调了什么工具返回了什么。这在生产环境里价值巨大——出了问题不需要靠日志推断直接重放。还有一层好处fork和resume变得自然。因为日志是append-only的fork一个会话就是从某个事件点开始复制resume就是从某个事件点继续追加。对我们的参考价值我们的Agent Runtime目前用的是消息列表快照来管理状态。DSH的Event Sourcing模式更优雅尤其对于多Agent协作场景——每个Agent的决策链路都是可审计的。Seam机制能力可替换的三角色设计DSH用Seam接缝来定义可替换的能力。一个Seam有三个角色Service Definition声明接口比如文件系统读取Service Provider实现接口比如本地文件系统或远程沙箱文件系统Consumer使用接口通常是模型可调用的工具文档里举了个例子文件系统和子进程共享同一个执行环境所以把它们的Provider指向远程沙箱Bash、PTY、LSP工具就会自动跟着走不需要为每个工具单独适配。这就是换一个Provider整个产品的行为变了的效果。对我们的参考价值我们的Agent管理平台也在做能力抽象但抽象粒度偏粗——基本是工具级别。DSH的Seam设计提醒我们能力、实现、消费者三者分离才能做到真正的运行时可替换。插件即配置Profile Bundle PatchDSH的组合体系是三层Profile一个命名的组合方案存在Harness的home目录下。指定加载哪些Bundle以及用户自己的cordis.patch.yml。web和headless是两个自带的Profile模板。BundleCordis配置行和对应代码的分发格式。每个Bundle在自己的package.json里声明dsh.bundle指向自己的patch文件。Patch最细粒度的覆盖层。可以替换某个plugin row的整行配置也可以插入新行。加载顺序Profile指定的Bundle按顺序→ Profile的cordis.patch.yml → Home级别的patch → 命令行--patch参数。这是一个有序分层、逐层覆盖的配置系统。底层Bundle提供默认行为上层Patch可以精准替换任何一个具体的plugin row。看实际配置dsh --profile web --dump-config这行命令可以打印出当前机器实际启动时的完整插件树。任何一行都可以被你自己的Patch覆盖。对我们的参考价值我们的Agent配置目前是一套参数一套配置缺乏分层组合能力。如果要做多租户、多场景的Agent管理DSH的Profile→Bundle→Patch三层组合模型非常值得参考。Agent Loopturn和step两级生命周期DSH的Agent Loop设计一个turn包含零或多个step一个step是一次模型请求 模型调用的工具执行事件流turn/start→ step/start→ 模型请求 → 工具调用→ step/end→ [下一个step]→ turn/end每个关键环节都有对应的扩展事件agent/pre-step、agent/request、llm/stream、tools/pre-execute等插件可以拦截和修改。特别值得注意的是agent/pre-step事件——它在模型请求前触发监听器可以重写模型即将看到的消息甚至直接拒绝这一步。这意味着什么你可以在模型即将看到上下文之前插入一个审查层——比如过滤敏感信息、注入额外指令、甚至基于某些条件完全跳过这一步。对我们的参考价值我们的平台正在做Agent执行前的安全审查DSH的pre-step钩子设计提供了一个干净的实现路径——不需要侵入Agent Loop主流程挂在事件上就行。DSH的边界和风险不是所有设计都值得照搬。几个需要注意的点Cordis框架的学习曲线。DSH的底层是Cordis一个时空可组合的编程范式。这不是主流技术栈社区资源有限。选择它意味着跟DeepSeek的技术路线绑定。如果Cordis本身不火DSH的生态会受限。开发者预览阶段。官方README明确写了CURRENTLY IN DEVELOPER PREVIEW和THERE WILL BE COMPATIBILITY-BREAKING CHANGES。API不稳定生产使用有风险。复杂度的代价。一切皆插件听起来美好但对普通用户来说上手门槛高。大多数人需要的可能只是开箱即用的Agent而不是自己组装Agent的工具箱。文档还在早期。架构文档写得不错但cookbook和tutorial还不完整。上手需要读源码。我们可以怎么用DSH来验证自己的设计作为一个Agent管理平台的开发者我建议几个具体的实验方向实验一跑通极简Profile。npx deepseek-ai/dsh web先跑默认web profile用--dump-config打印插件树理解它的启动流程和插件加载顺序。实验二写一个最小的自定义插件。不需要复杂功能——写一个在system prompt里注入一句自定义指令的插件。验证插件能改变Agent行为这个核心承诺是否成立。实验三对比Session Log格式。跑一个简单的多轮对话然后去看Session Log的原始事件流。跟我们自己的日志格式对比评估Event Sourcing模式的优劣。实验四测试Seam的运行时替换。写两个不同的文件系统Provider一个真实文件系统、一个内存mock在运行时切换验证工具是否真的能跟着走。实验五跑headless模式做CI集成。DSH支持headless模式无UI一次性执行。用它跑一个自动化任务评估它作为CI/CD pipeline中Agent执行引擎的可行性。一句话总结DSH给Agent Runtime的设计者上了一课不是给Agent加插件而是Agent本身就是插件组合的产物。从模型适配器到工具注册表到Agent Loop到前端UI全是可替换的插件。没有特权核心只有有序的组合。这个方向对不对现在还没有定论。但至少DeepSeek给出了一个完整的、开源的、可运行的参考实现。对于正在做Agent Runtime的团队来说这份架构文档值得逐页精读。https://github.com/deepseek-ai/deepseek-harness 一句话带走DSH最值得偷的设计不是插件本身而是Agent Loop也是插件这个架构决策——它把Runtime从框架变成了组装台。你们团队在做Agent相关的平台吗Agent Runtime的设计上遇到过什么架构难题评论区聊聊说不定我们踩过同一个坑。