引言：为什么要从源码理解 DSH¶
写作目标¶
模型能力快速变化，具体提示词和 API 名称很容易过时。相对稳定的是系统问题：上下文从哪里来，工具如何被发现和执行，副作用由谁治理，会话怎样回放，插件如何组合，失败如何被观测。DSH 把这些问题放进一个插件化 Harness 中，因此适合作为理解 Agent 工程的具体样本。
本书采用三条并行线索：
- 原理线：先解释系统为什么需要某个机制，再讨论 DSH 的选择。
- 源码线：从入口、服务和事件追踪真实实现，不按目录机械罗列。
- 实践线：用最小实验验证一个行为，再讨论生产环境还缺什么。
本书不是什么¶
本书不把 DSH 描述成“从 Linux 裸机自动生成一切成熟应用”的万能框架。DSH 是 Agent 应用的运行与扩展底座；数据库、身份权限、业务语义、可观测性和产品界面仍然需要独立工程建设。
本书也不把插件数量等同于生态成熟度。社区项目的价值要从许可证、维护状态、安装脚本、权限面、失败方式、测试和版本兼容性共同判断。
如何阅读一段 DSH 源码¶
每次遇到一个包，先回答五个问题：
- 它声明、提供还是消费哪项能力？
- 它在
ctx上使用什么服务键？ - 它监听或发出哪些事件？
- 它产生的副作用如何在卸载时撤销？
- 哪些状态进入持久会话，哪些只存在于实时运行期？
这五问比记住某个类名更有价值，因为 DSH 仍在快速迭代，文件位置和接口可能变化，而能力关系更稳定。
正文与实验双轨¶
正文按十章逐层展开。每章实验分为三级：
- ★ 观察：运行已有系统并记录现象；
- ★★ 改造：实现一个局部能力并通过测试；
- ★★★ 设计：处理权限、并发、恢复或评估等生产问题。
实验状态单独记录。代码存在只表示“提供了实验材料”，不表示已经在所有系统和DSH版本上验证通过。
版本方法¶
本书用 upstream.lock.json 固定官方仓库、提交和包版本。定时任务只报告上游漂移，不自动改写正文。更新必须经过源码复核、兼容性说明、实验复跑和人工审阅，避免社区一更新，书里的结论就悄悄改变。
前置知识¶
读者最好会使用 Git 和命令行，能够阅读基础 TypeScript，并理解 HTTP 与 JSON。不了解 Agent、MCP 或插件系统并不影响开始；相关概念都会在需要时引入。
下一章从最小公式开始，把模型、Harness、Agent 和应用之间的边界拆开。