全景回顾与模式迁移

十章走完，把所有部件放回一张图。

从上往下看。入口层是四条通往同一运行时的路，浏览器应用、命令行、自动化协议、远程调用接口，它们都把输入送进同一个收件箱。驱动层是 agent-loop 插件，跑着第 5 章的 Turn 与 Step 周期，它本身薄得惊人，因为所有策略都挂在外围的事件链上。能力层是一排平行的插件，模型适配、工具、文件系统、Shell、子代理、技能、工作流，每一个都是第 6 章的接缝。日志层在下方承接一切，第 4 章那份唯一的事实来源。右侧贯穿三层的是权限、沙箱、审批、超时，第 7 章的三道关口在这里值守。这张图里没有一个方块是特殊的，包括画在中间的 agent-loop。

如果这本教程只能带走三件事，我会选下面三件。

第一件，把事实和推导分开。dsh 用一份只追加的事件日志承载全部事实，模型历史、界面、统计、分叉、续跑全部是投影。这条纪律的收益在时间轴上显现，系统跑得越久，能从日志里回答的问题越多。任何有审计、回放、分叉需求的系统，长会话产品、工作流引擎、协作编辑器，都值得认真考虑这个结构。落地时学 dsh 的狠劲，把纪律做成运行时断言，违背就报错，文档约束会松，机制约束不会。

第二件，用三角色定义能力边界。接口、实现、使用方各归其位，实现可整体替换，使用方零改动。判断一个系统插件化是否到位，就看替换一个关键能力时使用方要不要动。多数系统过不了这一关，因为接口是随着第一个使用者长出来的，从来没有为第二个实现做过设计。dsh 的接缝三角色齐备才算数，这条规矩本身就可以搬走。

第三件，让扩展发生在事件上而非核心里。waterfall 链给了每个插件加工与拦截两种权力，核心因此不再需要预留开关。你的系统里那些 if 配置项越积越多的地方，多半缺的就是这么一条链。改造的顺序也值得照搬，先把最要紧的一条路径事件化，权限或准入，其余的逐步迁移。

还有两个小一些但同样鲜明的模式。注册即效果，登记与撤销成对记账，让热替换和干净退场成为可能。作用域两层加遮蔽，用最小的机制满足了按身份定制，克制住不做深层嵌套。

最后说说这套架构的适用边界。插件化有真实的理解成本，接缝设计要求对能力的演化方向有预判，事件链让一次请求的路径变得不那么直白。团队小、需求收敛、生命周期短的产品，单体加清晰的模块边界可能更划算。dsh 押注的是另一端，需求会长年变化、扩展方不限于原作者、运行时需要被安全地重配置。Agent 运行时恰好全部命中，这也是为什么这些模式在它身上显得如此贴切。

给读者留一条动手的路径。仓库是开放的，文档站有完整的中英文架构文档。第一步，跑一次 headless 模式，感受最小组合；第二步，用 dump-config 打印插件树，把图 10-1 和你机器上真实的树对上号；第三步，挑一条接缝，读它的定义、提供者、使用者三个包，比如 shell，它最小也最完整；第四步，写一个监听 agent/request 的插件，给每次请求打一行日志，体会注册即效果的回退。四步走完，这本教程讲过的每个名词都会落到你手边的代码上。

架构学习最好的收尾是动手。当你能指着图 10-1 里任何一个方块说出它的三个角色，这本教程的目标就达成了。