手册/第 02 章
02
为什么是「可替换」而不是「删减」
pi 的答案是「我不需要的东西不造」。dsh 的答案是「我需要的每个东西都可替换」。 两者都在对抗同一个敌人——不可预期的 harness——但用的是反向手段。
"Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration."
产品的每一个部分都是插件,包括模型适配器、工具注册表、会话日志,以及 agent 循环本身——所以每一个都能从配置里替换掉。
— docs/architecture.md:9
底层是一个通用插件框架,不是自研内核
dsh 没有自己发明组合机制,它用 Cordis——其设计写在论文
A Programming Paradigm for Spatiotemporal Composability(arXiv 2608.25512)里。
官方 docs/cordis-primer.md 把需要的概念压成五条,值得逐条读:
| 想法 | 含义 |
|---|---|
| 插件是实现了 Service 的对象 | 可以是一个带 inject / apply(ctx) 的函数,也可以是 Service 子类。 |
| 上下文是服务的仓库 | 服务占一个稳定的 ctx.<key>(ctx.tools、ctx.llm、ctx.sessions),别人按 key 找,不 import 具体实现。 |
依赖用 inject 声明 | 加载顺序由「服务需求」表达,而不是手写启动序列。 |
| 用类型化事件通信 | 事件名通过 TypeScript 声明合并定义,派发方式有 5 种。 |
| 注册是可逆副作用 | prompt section、工具 schema、适配器、监听器都经 ctx.effect() / ctx.on() 安装,重载与拆卸时可预测地展开。 |
五种派发模式:事件的「公开契约」
这是 Cordis 与常见事件总线最大的差别——派发方式是事件契约的一部分,不是调用方的自由选择
(docs/cordis-primer.md:19–27):
| 模式 | 是否等待 | 顺序 | 有返回值 |
|---|---|---|---|
emit | 否 | 按注册顺序观察 | 无 |
waterfall | 否 | 按注册顺序包裹 | 有 |
parallel | 是 | 并行触发所有监听者 | 无 |
serial | 是 | 按注册顺序依次执行 | 有 |
bail | 否 | 依次执行,直到有人放弃 | 有 |
waterfall 是 around-middleware
监听者收到
(...args, next)。调 next() → 把(可能被改写过的)结果交给下一个;
不调 next() 直接返回 → 短路。所以在 dsh 里,「拒绝一个请求」不是一个特殊 API,
而是一个不调 next() 的监听者。
三种范式税的付法
可替换不是免费的。dsh 把成本明确摊到三层上,每一层都对应一类人:
Ⅰ读代码的人
得先读
cordis-primer.md,理解 ctx / inject / effect / 五种派发。
否则看到的只是散落的 ctx.on,看不出执行顺序。
Ⅱ做产品的人
得理解 profile → bundle → patch 三层,否则不知道自己的改动会被哪一层覆盖。
出厂 5 个 profile 不是 5 个程序,是 5 份可被上层 patch 的清单。
Ⅲ用产品的人
得接受 developer preview 的破坏性变更——这是「不断重组插件树」的直接代价,
不是没做完的借口,是路线的必然结果。
和 pi 的分歧其实只有一句
| pi | dsh | |
|---|---|---|
| 不确定性放哪 | 消灭在源头:不做没用的功能,所以没有意外的行为 | 转移到组合层:每个部分都可换,所以意外的行为可以换掉 |
| 你信任谁 | 作者删得对 | 框架组合得对 |
| 扩展的形态 | 同进程 TS 扩展(一个文件) | 插件树上的节点(可被配置替换、可卸载回滚) |
| 失败模式 | 想要的功能它没有 | 能做的事太多,不知道哪个在起作用 |
这两条路线都自洽。真正的判断依据是你的角色:如果你既是作者又是唯一用户,删减更划算; 如果你要在 harness 上长出产品,可替换才有回报。第 09 章会把这条分歧落到具体数字上。
architecture.md:9 · 每一部分都是插件 cordis-primer.md:7 · 五个想法 cordis-primer.md:19 · 五种派发模式