第 1 课：从零开始读 DSH
本课是社区导读，不是官方教程。 它解释的是 DSH 源码在某一个固定版本上的样子——教材把上游仓库钉在一次提交上，所以书里的行号和文件路径不会因为上游继续开发而失效（那次提交的编号记在 UPSTREAM.md，现在不需要关心）。其中的判断、建议和研究问题不代表 DeepSeek AI 的承诺。
这是一份给第一次读大型程序的人准备的路线图。你不需要先记住所有英文名；先把 DSH 想成一个“能让模型工作、调用工具、保存过程、让插件替换零件”的程序。
如果你从 START-HERE 进入，这就是现在要读的第一篇正文；读完后不要随机打开索引，先按本页的推荐顺序走一小段。
先把常见术语翻译成人话
第一次读源码时，不要因为英文词多就停下来背词。先用下面的意思理解；等真的要查代码时，再用括号里的英文搜索。
| 文中写法 | 先按这个意思理解 |
|---|---|
| Agent / 智能体 | 能根据结果继续决定下一步的程序 |
| Agent loop / 工作循环 | 反复“看情况 → 做一步 → 看结果” |
| Tool / 工具 | 模型可以请求宿主执行的一项动作 |
| schema / 参数说明 | 告诉模型这个动作需要哪些参数、参数长什么样 |
| Profile / 运行清单 | 这次启动准备打开哪些功能 |
| Bundle / 功能组合 | 一起安装、一起装配的一组插件 |
| Provider / 模型服务方 | 真正提供模型请求服务的一方 |
| Hook / 外部钩子 | 外部程序和宿主约定的一次输入输出 |
| Patch、Fork、注入 | 分别是改配置或源码、另维护一份源码、运行中改写宿主 |
后文仍会使用这些英文词，因为它们是源码中的真实名称；遇到时先回到上表对照。
读 DSH 源码时的四个问题
以后看到一个新插件、新工具或新 Harness 组件，先按下面顺序问：
- 它改变了循环的观测、上下文、动作、状态、策略还是评估？
- 它解决了什么问题，又引入了什么新的失败、延迟、成本或权限风险？
- 证据属于源码事实、单元测试、本地宿主实验、真实 Provider 还是模型任务结果？
- 还有什么没有验证，怎样回滚，谁对这部分负责？
后面每一课都会重复使用这套判断方法。
作者自己对 Agent 和 Harness 的判断，以及这些判断怎样影响了教材编排，单独放在作者的判断与理由。那一页是观点不是课程结论，读不读都不影响后面的课。
先记住六个词
- 插件：可以插入或拔出的功能模块。DSH 里模型适配器、工具注册表、Session、Agent Loop 和 Web 组件都可以作为插件装配；“模型”本身不等于插件。
- 服务：插件放进共享上下文后，其他插件可以取得的能力，例如
ctx.sessions或ctx.tools。 - 事件：带有类型和派发模式的运行时扩展点。有的事件只允许观察，有的可以作出决策或包裹流程；发送者不必知道所有接收者，因此新功能可以旁路接入。
- Profile：一次运行使用哪几层功能的名单，像一张装配清单。
- Bundle：一层可安装的功能组合，通常通过补丁把很多插件放进树里。
- Turn 与 Step：通常一次用户输入会触发一个 Turn。一个 Turn 可以包含 0 个或多个 Step；每个 Step 是一次模型请求，以及这次请求触发的工具调用。若首次输入被拒绝或被改写为空，也可能记录一个没有 Step 的 Turn。
关键提醒：“一切皆插件”描述的是能力如何装配，不是“所有插件都必须把工具发给模型”。 工具还要经过作用域、呈现方式和执行策略；后面读到“工具可见性与非侵入扩展”时，再把“已注册、模型可见、执行允许”分开。
先看一个贯穿示例
假设你想写一个“只记录工具结果、不改变工具行为”的小插件。第一次不要从 Loader 或模型请求开始，先把问题压缩成四句话：
入口：公开的 tools/result 事件。
动作：收到最终结果后，只生成一段限长文本预览。
已经能证明：源码和单元测试显示它订阅了事件，并且不会改写输入结果。
还没有证明：真实 DSH Profile 已加载它，或模型因此收到了更少 token。这四句话就是本教材反复使用的阅读方法：先找公开入口，再找实际动作，然后把源码/测试证据和仍缺少的运行证据分开。后面的最小插件示例会把这四句话变成可以运行的 Node 测试；它仍然不会自动变成真实 DSH 安装证明。
这一页读完算什么
- [ ] 我能用自己的话解释插件、服务、事件、Profile、Bundle 和 Turn。
- [ ] 我能画出“输入 → Prompt → 模型 → 工具 → Session”的最小链路。
- [ ] 我能用“已证明／还没有证明”描述一个源码结论，而不是只说“它应该能用”。
如果三项中有一项说不清，停在本页或回到从这里开始，暂时不打开逐文件索引。
推荐阅读顺序
前七课是一条主线，先按顺序读完；后面的课按你要做的事插进来，不必全部顺读。
| 阶段 | 课程 | 什么时候读 |
|---|---|---|
| 主线（1–7） | 仓库地图 → Cordis 与插件树 → 核心文件精读 → Agent 与 Turn 流程 → Session 日志与恢复 → LLM 与工具执行 → Host、Client、示例、测试与发布 | 第一次来，按这个顺序走完 |
| 查文件（8） | 逐文件索引怎么读 | 想找某个具体文件时 |
| 扩展与生态（10–12） | 社区生态与扩展边界 → 如何写一个合规插件 → GitHub 生态检索与插件实战核验 | 准备扩展 DSH 或安装社区项目时 |
| 工具预算（22） | 工具可见性与非侵入扩展 | 担心“万物皆插件”带来过多工具时 |
| 插件专题（13–15） | 官方工具插件完整契约、官方 HookBridge 与兼容层、Bundle、Profile、Loader 与发布安装 | 写工具插件、接外部 hook、发布 Bundle 时各取一篇 |
| 动手实验（16） | 学习工作簿与首个实验 | 想第一次照着做时 |
| 核对与维护（17–20） | 完成度审计与证据矩阵、维护、更新与版本迁移、插件测试、卸载与版本证据、学习仓库实际使用手册 | 想确认覆盖范围、换基线或留运行证据时 |
| 计划栈（37） | 计划栈：Plan、Goal、Todo、Schedule 与 Workflow | 想看模型侧的清单、计划态与定时提醒怎样落在日志上时 |
| 进阶实验（23、24、33、36） | 工具可见集合观测与性能实验、高风险索引人工抽查、研究与 Debug 协作、确定性可视化实验协议与 Code Mode 权限管线 | 想把“工具太多”变成可测问题、抽查索引、交 Debug 复核或逐帧检查权限时 |
一个最小的心智模型
可以把一次请求画成：
用户输入
-> Agent 收到输入
-> Session 记录输入
-> Prompt 组装上下文和工具说明
-> LLM 产生流式回答
-> Agent 判断是否要调用工具
-> Tool 执行并返回结果
-> Session 记录结果
-> 需要时进入下一步，否则结束 Turn这里的箭头大多表示服务和事件连接，只有一部分是直接函数调用。读源码时要问两件事：这条信息在哪里产生，最后由谁消费；这项能力是稳定接口，还是某个可替换提供方。
想在浏览器里亲手走一遍这条链路，打开 Turn 流程与日志对应实验：步进滑杆能停在任意一步，每一步的数据都来自固定提交里的模型函数。第 4 课会把同一条轨迹逐段拆开讲。
读扩展生态时还要问第三件事：我使用的是上游公开接口，还是自己 fork 中新增的内部接口？前者可以写成第三方插件；后者应写成 patched fork 的私有扩展点，不能只因为它能运行就称为官方插件。
怎样读一个文件
先读文件所在包的 README，再读 index.ts 入口，然后看类型和事件，接着看实现，最后看同包测试。遇到一个名字时，不要只看它“做了什么”，还要看它为什么没有放进另一个文件：通常答案是边界、替换、测试或生命周期。
读到不懂时怎么办
不要从一个 2,000 行文件的第一行硬读到最后。先从核心精读中的文件开始，再顺着“直接协作者”和测试链接跳转。索引中标为“自动索引”的条目只提供方向；涉及行为时必须回到固定版本源码核对。