为什么Dim的插件契约是概念而非类型?从ADR 006看懂其设计哲学
为什么Dim的插件契约是概念而非类型?从ADR 006看懂其设计哲学
Dim 是一个构建在**事件驱动时间线(event-driven timeline)**之上、运行时完全基于插件的 Agent 范式。而它最令人玩味的设计决策之一,就写在 ADR 006 里:插件契约(plugin contract)由概念和约定构成,而不是由 Rust 类型定义。这个看似"反工程直觉"的决定,背后是一整套关于分层、跨语言与可维护性的思考。本文带你用 5 分钟读懂这份 ADR 的设计哲学,以及它对插件架构的深远影响。
先看问题:用类型"表达"架构,代价有多大?
在 ADR 006 做出之前,Dim 的插件体系曾试图用 Rust 类型把整套架构理论"编码"进去。ADR 006 的背景章节列出了当时 main 分支上的规模:
| 概念 | 当时的类型表达 | 规模 |
|---|---|---|
| 部件放在哪里 | session_plugin、timeline_plugin、Capability::keys |
199 个 Capability 实现 |
| 依赖来自哪个实例 | InSession<T>、InBranch<T>、SessionGate<T> 等 |
221 处使用 |
| 给作者的规则散落在 | AGENTS.md、原则文档等 | 27 篇文档反复提及这些类型 |
规模本身不是问题,真正的问题是四个连带后果:
- 非 Rust 部件被迫"重新推导"。TypeScript/Python 插件没法使用这些 Rust 类型,宿主只能靠推断和硬编码来补偿,同一个服务的组(scope)甚至要在三处分别声明、彼此无法交叉校验。
- 每种语言都在重复实现同一套基础设施协议。每个有序消费方都要自己订阅、固定截点、折叠历史——Rust 里写一遍,TypeScript 里再写一遍。
- 文档混杂了四类陈述:理论、约定、Rust 写法、交付历史,贡献者分不清哪句是规则、哪句只是在描述当前代码。
- 底层框架 rutis 在 0.13 到 0.16 之间换了模型,而这些类型绑定的正是旧模型的细节。
一句话总结:当类型成为架构的定义,任何一层的风吹草动都会传导到所有语言的所有插件。
ADR 006 的四层分权:每层只有一个权威来源
ADR 006 的核心决策(D1)是把"架构知识"拆成四层,每层指定唯一的权威来源:
| 层 | 内容 | 权威来源 |
|---|---|---|
| Dim 架构理论 | 序列、所有权、指令、交接、重建 | 时间总线与设计原则 |
| 插件契约 | 实例树含义、放置规则、命名服务、Capability 约定 | 插件契约设计 |
| 如何使用 rutis | 插件行、按名服务、目录机制、跨语言 | How Dim uses rutis |
| 语言绑定 | Rust trait/宏、TypeScript definePlugin 等具体写法 |
各语言附录与 SDK |
这套分层有一条铁律:Rust 只是契约的一种绑定(binding),而不是契约的定义(ADR 002 D5 的补全)。绑定的职责是"把同一套规则用本语言写出来",不允许添加新语义。规则变了改设计文档,写法变了改绑定——两者井水不犯河水。
服务的身份是"名字",而非类型
这是 ADR 006 里最实用的一个决策(D4)。在旧模型里,一个部件依赖的是 InSession<ToolRegistry> 这样的类型;在新契约里,依赖声明只包含服务名——一个 camelCase 名字加上它所属的唯一组(process、session 或 branch)。
这套"名字即身份"的机制带来三个好处:
- 跨语言统一身份。Rust 部件和 TypeScript 部件在同一个实例里,用同一个名字互相调用服务。rutis 的目录(catalog)只分享已注册的名字,因此"恰好是目录里的那些名字"能跨越语言边界,不需要任何适配层。
- 目录由机器生成。
xtask从真实装配中生成服务目录表:每个名字的组、提供者、方法、是否跨语言,全部有据可查,而非散落在三处手工声明。 - 贡献向所有者登记。工具、prompt 来源、方法命名空间不再是"一堆名字",每个贡献直接调用所有者(如 ToolRegistry)的
register,注册随贡献者卸载而自动撤回——没有宿主预注册,也没有字符串匹配。
完整的名字清单见插件契约 §4「Dim 的服务」,包括 sessions、timeline、dispatcher、sessionLifecycle 等。
Capability 也是一条约定,不是一种类型
D6 把 "Capability" 这个词重新定义为一个约定:在分支 Timeline 上按序列折叠事实、或写入自己领域事实的部件,才叫 Capability——本质上是一台跑在分支时间线上的状态机。
关键点在于:成为 Capability 既不需要声明,也不被任何机制强制。没有角色字段、没有 trait、没有 loader 检查。原因很现实:受信任的进程内插件本来就不靠声明隔离(ADR 003),而在一条"平"的事件总线上,loader 检查能拦住注入却拦不住监听——"看起来像边界但不是边界"的检查毫无意义。
取而代之的是三道检查:xtask 的生成审计从真实装配推导出哪些部件注入了 dispatcher 或 timeline(即哪些是 Capability)、评审流程中的规则检查清单、以及验证可观测行为的 flow 测试。约定靠"生成 + 评审 + 测试"来守护,而不是靠类型系统。
机制保证什么,不保证什么
ADR 006 的 D7 用一张表把"机制"和"约定"划清了边界:可见性、暴露范围、Timeline 完整性、投递顺序、生命周期——这些由 rutis、Timeline、Dispatcher 等机制硬保证;而时间总线的其余规则、设计原则第 4 节等,则是约定,由评审与测试守护。
这种"保证清单"写法本身就是一种设计哲学:明确告诉插件作者,哪些东西框架兜底、哪些东西靠社区纪律,不再让读者从 199 个 trait 实现里自己去归纳。
这个决策换来了什么?
ADR 006 的迁移已全部完成(P1–P6 阶段),实际收益写得很直白:
- 更少的 Dim 专属类型:
Capabilitytrait、SessionScope/BranchScope、InSession/InBranch等按层类型全部删除,插件页面与设计文档不再复述 Rust 写法; - 一个特性在任何语言里都是一个插件:一行、一份配置、一次重载;
- Cordis 4 插件可以直接注册为分支部件,拿到自己分支的服务,无需修改;
- 文档分层清晰:中文 ADR 006、插件契约、rutis 使用指南各司其职,规则只在一个地方陈述。
结语:概念与约定,是一种更"轻"的契约
回到标题的问题:为什么插件契约是概念而非类型?因为 Dim 的架构理论(事件驱动时间线、状态单一所有者、按所有者放置)本身不依赖任何编程语言——用类型去"钉死"它,等于把理论的表达权交给了某一种语言,也让跨语言插件永远隔着一层需要重新推导的间接层。ADR 006 选择把权威来源留给概念文档,把类型降级为"最完备的一种绑定",用机器生成的目录、审计和 flow 测试来守护约定。
如果你正在设计自己的插件系统,这份 ADR 给出的启示可以浓缩为一句话:当你的架构需要被多种语言共享时,契约的权威来源应该是概念,而不是任何一种语言的类型系统。更多细节,欢迎从 ADR 006 原文和插件契约设计开始读起。

