一切皆插件

「一切皆插件」不是一句口号，它是一条可证伪的断言：在 dsh 里找不到一个不能被卸载的特权核心——模型适配器、工具注册表、会话日志，连 agent loop 本身，都只是插件树上的一行。官方 docs/architecture.md 把这句话写死了：「没有一个可以打补丁的特权核心：你通过在其他插件旁边挂载一个插件来扩展 dsh。」

这一页先把承载它的框架讲清楚，再用 web 能力当解剖样本看一个 seam 到底长什么样，然后拆开三层组合机制，最后算一笔账：这套纪律要求每个能力写三个包，什么规模的团队值得付这个成本。

2.1　Cordis 十分钟入门

Cordis 是 dsh 底下那层插件框架，以 vendor/ 源码副本的方式钉在仓库里。它不是这个项目发明的，但 dsh 对它的用法是这套架构的全部前提。官方 primer 把它压成五句话，这五句话你得先接受，后面的一切才成立。

• 插件就是一个实现了 Service 的对象。可以是一个带可选 inject 和 apply(ctx) 字段的函数，也可以是一个 Service 子类。
• context 是服务的仓库。一个服务占住一个稳定的 ctx.<key>——ctx.tools、ctx.llm、ctx.sessions——别的插件按 key 找服务，而不是 import 某个具体实现。
• 依赖靠 inject 声明。一个插件列出它需要哪些服务，Cordis 就等到那些服务存在了再启动它。加载顺序是推导出来的，不是手写的启动序列。
• 通信靠类型化事件。服务用 TypeScript 声明合并（declaration merging）声明事件名，再按 emit / waterfall / parallel / serial 之一分发。
• 注册是可撤销的 effect。prompt section、工具 schema、适配器、provider、监听器，全部通过 ctx.effect() 或 ctx.on() 安装，于是 reload 和 teardown 能可预测地把它们撤回去。

四种分发模式，以及 next() 的含义

事件的分发模式是它公开契约的一部分，不是实现细节。新加的 harness 事件必须用 @mode 标注，生成式 catalog 会拿声明去核对真实的分发点——声明和调用对不上，门禁就红。

waterfall 是 around-middleware：监听器收到 (...args, next)。调用 next() 才把（可能已被包装的）结果交给下一个服务；不调 next() 直接返回就是短路。这两种行为都是设计内的：一个只做标注或观察的监听器必须委托下去，而一个拥有决定权的策略监听器应该短路。

这条规则被 AGENTS.md 提到了硬约束的高度——因为忘记调 next() 造成的 bug 表现为「某个插件莫名其妙不生效」，而不是崩溃，极难查。

2.2　Capability Seam 三件套

一个 capability seam（能力接缝）由三个角色构成：Service Definition 声明接口并拥有 ctx 上那个 key，Service Provider 把一个具体实现注册进去，Consumer 只按接口取用、永远不知道背后是谁。

关键在于：seam 是这三个角色的总和，单独一个角色不算 seam。仓库的 AGENTS.md 把这条写成了硬约束——只有当三个角色会各自独立演化时才允许拆成三个包，否则就是在制造无谓的抽象。

这也是判断一份「插件化架构」是真是假最省事的检验：看它有没有一个不属于任何 seam 的、谁都动不了的中心。大多数号称插件化的 agent 产品，工具层是插件化的，而模型调用、会话存储、主循环是硬编码的核心——插件只能在核心留好的几个 hook 上挂东西，换不掉核心本身。

案例解剖：web 能力的六个包

把 packages/web/ 打开，六个包正好排成三个角色。这不是我归纳的，是这个 group 自己的 README 表格：

这六个包里没有一个知道另一个的存在。tool-web 不知道搜索是谁做的，三个 provider 也不知道自己被谁调用——它们唯一的共识是 web 声明的那份接口。

所以「换后端」这件事，在 dsh 里退化成了一次配置改写：

# patch 按 id 定位某一行，替换它整个 config，而不是合并进去
- insert:
    - id: web
      name: '@deepseek-ai/dsh-web'
      config:
        searchProvider: exa
    - id: web-search-exa
      name: '@deepseek-ai/dsh-web-search-exa'
      config:
        searchType: neural
        apiKey: !!js process.env.EXA_API_KEY

代码 2.2　核心零改动。dsh --profile web --dump-config 可以看到这两段落在树的哪一层。完整走一遍见 Lab 2。

2.3　组合机制：三层叠加

一个跑起来的 dsh 是启动时按顺序叠出来的一棵插件树。层序在 apps/cli/reference/README.md 里写死：

1. profile manifest 里 dsh.profile.bundles 列出的每个 bundle 的 patch，按列表顺序
2. 然后是 profile 自己的 cordis.patch.yml
3. 然后是 home 级的 $DSH_HOME/cordis.patch.yml（机器本地偏好，所以它排在 profile 后面、优先级更高）
4. 最后是 argv 顺序的每一个 --patch <path> overlay

后写的赢。每一层做的事只有两种：按 id 定位一行、替换它整个 config，或者 insert 新行。

想知道你这台机器上到底叠出了什么，不需要读代码：

$ dsh --profile web --dump-default-config   # 只有 bundle 层
$ dsh --profile web --dump-config           # 加上 profile / home / --patch 三层

两条命令都会打注释，标明每一行来自哪个文件、被哪些 overlay 改过；!!js 表达式原样保留不求值；patch 指向的 id 在树里找不到，会往 stderr 报一行警告。app-boot 里有个更讲究的设计：dump 走的是 include 自己的解析器和 patch 算法（entryListSchema / applyEntryPatches），所以 dump 出来的东西和 boot() 实际挂载的不可能不一致。它不是一个「大概是这样」的诊断工具。

2.4　纪律的代价

刚才那份优雅是有账单的。一个能力拆三个包，意味着三份 package.json、三份 README（每份还得写「模型看见什么 / 花多少 token / 对 KV cache 有什么影响」三节，见 M4）、三份要跑到逐文件 100% 行覆盖的测试。

227 个包不是灵活性的证据，是这套纪律的成本。把账摊开：