为什么需要又一个 Agent 运行时

把大模型接上工具，让它替人查资料、改代码、跑命令，这件事早已不新鲜。真正让工程团队头疼的，是另一件事。产品从演示走到生产，需求开始变化。今天的模型供应商变了，明天要换一套沙箱，后天运营要求给某类会话加上额外的审批。在多数 Agent 框架里，这些变化都要去改框架本身，或者绕开框架做一层私有的封装。改得多了，框架就成了负资产。

这个困境指向一个架构问题。一个 Agent 系统里，模型适配、工具注册、会话存储、执行循环、权限策略，这些部件在多数框架里是一体的，由同一个仓库、同一批核心开发者维护。使用者想替换其中任何一件，都得动到核心代码。DeepSeek Harness 对这个问题给出了一个相当彻底的回答。它的答案是，把这些部件全部拆成插件，一个不留。

DeepSeek Harness（仓库地址 github.com/deepseek-harness）是一个基于 Cordis 框架构建的开源 Agent 运行时，项目内部简称 dsh。运行时的意思是，它负责承载 Agent 的完整生命周期，从接收用户输入，到调度模型请求，到执行工具，再到把过程记录下来。你可以把它理解成 Agent 的操作系统，模型只是插在上面的一块能力。

它最显眼的特征写在项目文档的第一句话里。Everything is a plugin，一切皆插件。这句话需要当真。模型适配器是插件，工具注册表是插件，会话日志是插件，连驱动整个 Agent 的执行循环本身也是插件。没有特权核心可以打补丁。想扩展 dsh，就在其他插件旁边挂上你自己的插件；想替换某块能力，就换掉那个插件，其余部分照常运转。

这个设计不是为开源而摆的姿态，它直接决定了使用者的日常操作。dsh 的组合机制里有 profile 和 bundle 两层。bundle 是一组 Cordis 配置行加上它们挂载的代码，profile 是若干 bundle 的有序叠加，再盖上用户自己的补丁文件。官方提供了 web 和 headless 两个模板。web 模板启动浏览器应用，headless 模板跑一次性任务，连服务器都不起。两者共享同一个基础层 dsh-base，里面是模型适配、工具、持久化、沙箱与审批策略这些通用件。

想在某个环节做替换，操作是声明式的。执行 dsh --profile web --dump-config，终端会打印出当前机器实际启动的插件树，每一行都可以被上层补丁整行替换。这个体验与传统框架形成对照。传统框架里，配置项是核心代码预留的开关，开关没留的地方就得改源码。dsh 里没有预留这一说，任何一行组合配置都暴露在同一个层次上，基础件和你的私有件地位平等。

代价同样存在，公平起见应该讲清楚。插件化架构要求每个部件先被抽象成接口，再被实现，再被组合，理解成本高于单体。dsh 用三类角色约束这个复杂度，服务的定义方、实现方和使用方各司其职，这套约束贯穿全书。对愿意读完这本教程的读者，回报是一套可以随需求生长、而不必随需求腐化的 Agent 底座。

这个仓库本身也值得当作架构课的教材看一眼。dsh 的代码按包组织，三十多个包分成十几组。core 组是产品主线，会话、系统提示、工具、Agent、执行循环都在这里。llm 组放着模型能力，shell、fs、lsp、terminal 各自对应一种执行环境能力，subagent、workflow、skill 是更上层的协作能力，session、settings、credentials 管耐久数据和配置。支撑 Cordis 的本体代码单独放在 vendor 目录下，用一份清单锁住上游版本，同步与修改都有书面流程。仓库还带一个 Python SDK 和若干可以直接运行的示例包，文档站由同一批双语源文件投影生成。一个开源项目把自身的结构梳理到这个程度，本身就在示范它所主张的工程观。

本教程面向对架构设计有兴趣的泛技术读者，不要求你写过 TypeScript，但假定你了解软件工程的基本概念。全书十章，从插件系统讲起，经过事件机制、会话日志、执行周期、能力接缝、工具管道、作用域定制、子代理委托，最后一章把全部内容拼回一张全景图，并讨论这套设计模式如何迁移到你自己的系统里。

下一章我们先认识这一切的出发点，Cordis 插件系统。