DSH 的设计原语:一切皆插件如何运行

DSH 的设计原语：理解“一切皆插件”背后的运行模型

资料范围：本文只依据 DeepSeek Harness（DSH）官方仓库及官方文档整理。核对日期：2026 年 8 月 27 日。文中的评价与推论会明确标注为分析，不作为官方承诺。

在讨论 DSH 之前，先对齐“设计原语”

一个软件框架往往有很多功能：模型接入、工具调用、会话保存、权限检查、遥测、命令行界面等。但功能不是设计原语。

设计原语是系统用来构造这些功能的最小、稳定概念。就像操作系统用进程、文件和权限组织上层应用，DSH 也需要一组基础概念来回答几个更底层的问题：

• 一个能力以什么形式进入系统？
• 插件之间如何寻找并使用彼此？
• 依赖尚未就绪时，插件是否应该启动？
• 一个插件退出后，它注册的服务、监听器和中间件如何撤销？
• 同一套能力如何组合成 CLI、SDK 或另一种 Agent 产品？
• Agent 已经发生的行为，怎样成为可以保存和推导的事实？

DSH 的答案并不是再造一套孤立的插件 API，而是建立在 Cordis 的运行模型上。官方架构文档把模型适配器、工具注册、会话日志乃至 Agent Loop 都视为插件能力；一个运行中的 DSH，则是由 profile、bundle 和局部 patch 组合出来的一棵插件树。DSH Architecture

这也是理解 DSH 的起点：“一切皆插件”描述的不是插件数量，而是产品能力是否服从同一套依赖、生命周期、事件和组合规则。

为什么 Agent Harness 需要这些原语

在普通应用里，替换日志库或数据库驱动通常不会改变程序的基本运行方式。但 Agent Harness 的可变部分要多得多：

• 模型供应商和请求协议可能更换；
• 工具集会按项目、权限和环境动态增减；
• 模型调用前后可能插入权限、hook、压缩或遥测逻辑；
• 会话既要服务实时界面，也要服务恢复、分支、回放和审计；
• 不同产品可能采用不同的 Agent Loop，而不只是不同的 UI。

如果这些差异全部固化在一个核心循环中，扩展最终会变成不断增加条件分支。DSH 的设计方向是把“能力如何接入和退出”本身标准化，让上层产品尽量通过组合完成，而不是持续修改一个特权核心。

原语一：Plugin——能力的基本交付单位

在 Cordis 中，插件可以是实现 Service 的对象、带有 inject 与 apply(ctx) 的函数，也可以是继承 Service 的类。Cordis Primer

插件同时承担三项职责：

1. 声明自己依赖哪些服务；

2. 向 Context 注册服务、事件监听或行为；

3. 在退出时释放注册和受管理资源。

因此，DSH 的插件不只是界面扩展或命令扩展。模型适配器、工具注册器、会话系统、持久化后端和 Agent Loop 都可以使用同一种插件生命周期接入。DSH Architecture

所谓“一切皆插件”，更准确的解释是：DSH 的产品级能力都可以通过统一的插件机制提供和替换。这不代表底层不存在运行时；Cordis 本身仍然负责 Context、服务、事件和生命周期管理。

原语二：Context 与 Service——能力的注册、发现和隔离

Context 是插件运行的上下文，也是服务仓库。Provider 把服务挂载到一个稳定的 Context key 上，Consumer 通过这个 key 使用能力，而不必直接引用具体实现。

例如，上层只依赖“会话持久化”接口，底层可以安装 JSONL Provider，也可以换成 SQLite Provider。调用方不需要维护一组“如果是 A 就调用 A、如果是 B 就调用 B”的条件分支。

Context 也不等于一个无边界的全局单例。Cordis 支持作用域和隔离组，同一种服务可以在不同插件子树中存在不同实例。这让一套进程能够容纳不同配置或相互隔离的运行环境。Cordis Service

Context/Service 解决的是两个问题：能力在哪里，以及谁可以看到它。

原语三：Inject——依赖关系也是生命周期关系

插件通过 inject 声明依赖。Cordis 会等待所需服务出现，再启动插件；如果依赖服务消失，依赖它的插件会被处置；当服务重新出现时，插件可以重新装载。Cordis Service

这比普通构造函数注入多了一层含义。普通依赖注入主要解决“对象如何拿到依赖”，Cordis 还用依赖关系决定：

• 插件何时具备启动条件；
• 依赖退出后，插件何时必须停止；
• 依赖恢复后，插件怎样重新激活。

所以，DSH 的依赖图同时也是一张运行时生命周期图。这是插件能够动态安装、替换和撤出的基础。

原语四：Typed Event——插件之间的协作协议

Service 适合表达“一个插件提供某种稳定能力”，Event 则适合表达“运行过程中发生了一件事，其他插件可以参与”。Cordis 提供类型化事件，并区分多种分发语义：

• emit
  ：广播通知；
• parallel
  ：并行处理；
• serial
  ：串行处理；
• waterfall
  ：把前一处理结果交给下一处理者；
• around/middleware：在核心行为前后包裹逻辑，通过 next() 继续调用链。

这允许权限检查、请求变换、hook、遥测等横切能力独立存在。插件不必直接依赖另一个插件的具体类，只需要共同遵守事件名称、数据结构和分发语义。Cordis Primer

Service 与 Event 因而形成互补：前者提供能力，后者组织协作。

原语五：Effect——插件撤出为什么不会留下注册残骸

插件装载时通常会产生一系列作用：注册服务、监听事件、插入中间件、启动定时器或占用资源。如果插件退出时只删除插件对象，这些作用仍可能残留，形成重复监听、幽灵服务或资源泄漏。

Cordis 把这类作用建模为可撤销的 effect。插件可以通过 ctx.effect() 注册作用及其清理逻辑；通过 ctx.on() 注册的监听器也与 Context 生命周期绑定。插件或所属 Context 被处置时，这些 effect 会被撤销。Cordis Primer

完整过程可以概括为两段。

插件装载后，注册服务、事件与中间件，并创建受生命周期管理的资源。

插件卸载时，撤销这些注册，移除监听和中间件，释放受管理资源，并处置失去依赖的下游插件。

这里需要澄清“撤出无副作用”的边界。Cordis 能结构化撤销的是已经纳入 Context 生命周期、并提供 disposer 的作用。已经发送到外部系统的消息、已经执行的命令或已经写入外部数据库的数据，并不会因为插件卸载而自动消失。此类不可逆作用仍需要插件或业务系统自行提供幂等、清理或补偿机制。

因此，更准确的说法是：DSH 可以让插件的运行时注册和受管理资源随插件一起退出，但不能自动逆转插件曾经造成的所有外部世界变化。

架构模式一：Capability Seam——定义、提供与消费分离

在上述原语之上，DSH 官方架构进一步把一项可替换能力拆为三个角色：

1. Service Definition：能力契约；

2. Provider：能力实现；

3. Consumer：能力使用者。

DSH 把这种边界称为 capability seam。DSH Architecture

以持久化为例，上层会话模块只消费统一接口，JSONL 与 SQLite 分别作为 Provider 安装。替换后端时，变化集中在插件组合，而不是向上渗透到每一个消费者。

Capability seam 不是新的底层语法原语，而是 DSH 使用 Service、Context 和 Inject 形成的架构模式。

架构模式二：Profile、Bundle 与 Patch——完整应用也是组合结果

单个插件解决一项能力怎样进入系统，profile 和 bundle 则解决一整套应用如何组装。一个产品形态可以组合模型、工具、会话、持久化和 Agent Loop；profile 提供默认组合，局部 patch 再替换或覆盖其中一部分。DSH Architecture

这意味着 CLI、SDK 或不同工具集不一定需要维护几套分叉核心。它们可以是同一组能力的不同插件树。

从产品工程角度看，这也是 DSH 最有辨识度的主张：不仅扩展功能是插件，最终应用本身也是组合产物。

领域原语：SessionEvent——把 Agent 行为变成持久化事实

Cordis 解决运行时组合，DSH 的 SessionEvent 则解决 Agent 行为如何被记录。

DSH 将 Session 定义为 append-only、类型化的事件日志，并把它作为会话的单一事实来源。模型上下文、界面回放、分支、恢复、转录和遥测都可以从这条日志推导。DSH Session

官方架构同时区分：

• Session events：需要持久化的事实；
• Agent events：当前执行过程中的实时信号；
• Capability events：策略和适配器参与的扩展点。

这种区分避免把所有运行时信号都永久写入会话，也避免只保存最终聊天文本而丢掉关键行为事实。

总结：DSH 真正标准化的是“能力的生命周期”

DSH 的设计原语可以归纳为：

• Plugin：能力的交付单位；
• Context/Service：能力的注册、发现和隔离；
• Inject：依赖和生命周期；
• Typed Event：插件之间的协作；
• Effect：注册和资源的可撤销性；
• Capability Seam：契约、Provider 与 Consumer 分离；
• Profile/Bundle/Patch：完整产品的组合；
• SessionEvent：Agent 已发生行为的持久化事实。

因此，“一切皆插件”的真正价值不在于插件数量，而在于模型、工具、Agent Loop、会话和持久化是否能够服从同一种装载与退出协议。

这套结构降低了替换能力时修改特权核心的需要，也为不同 Agent 产品共享底层能力提供了条件。但 DSH 官方仍把项目标记为 developer preview，并提示可能存在破坏性变化。架构方向已经清楚，接口稳定性则仍需按预览阶段看待。DSH 官方仓库