从这里开始：DSH 源码学习
这是面向社区的非官方学习入口，不是 DeepSeek AI 的官方教程。 本页帮助你阅读固定版本源码、理解插件与工具边界、审查社区扩展；官方 API、版本承诺和运行行为仍以上游仓库及官方文档为准。
如果你第一次打开这个仓库，不要先点开 2,973 个文件，也不要先下载源码。按下面的顺序做完三步，再对照本页的七个检查点自测：能答出其中五项以上，你就知道 DSH 是什么、下一步该看哪里。
你现在只做三步
- 打开第一课：从零开始读 DSH，先读“教材总论”，再读“六个词”。
- 打开仓库地图，知道
apps、packages、vendor、examples和scripts各自负责什么。 - 根据你的目的，从下面的路线表只选一条，不要同时打开所有专题。
如果你只想先弄懂“工具为什么多、插件为什么分很多种”，直接打开工具预算与插件责任决策卡。它先给结论和分类，再把你带到 22、23、10、11、13、14 的细节课。
第一次阅读不需要下载源码、不需要 API key、不需要安装 pnpm，也不需要先会 TypeScript。普通 GitHub 网页足够完成这一轮。课程页右下角有一个可选的学习进度组件：“标记本课已读”只写进你自己浏览器的本地存储，不上传任何数据；换设备或换浏览器时，用它上面的导出/导入按钮把记录搬走。
如果你已经打开了 Codespaces，想先确认“这个学习仓库能不能按设计工作”，只复制下面这一条命令。它只检查教材入口、离线快照、固定源码链接和学习工具单元测试，不启动 DSH、provider 或模型：
pnpm run study:quick-check想把最小示例的 test 和 lint 也一起跑，再用：
pnpm run study:quick-check --example如果你已经在终端，只想先看“插件收到结果后会输出什么”，可以只运行示例的 demo：
pnpm --dir study-examples/minimal-observer-plugin run demo正常会看到类似 [study-observer] study_greet -> ["hello world","second block"] 的一行。它使用 fake context，不启动 DSH；要验证行为，再回到最小插件示例与学习检查运行 test 和 lint。
你属于哪种情况
| 你想做什么 | 现在点击哪里 | 做完后应该能回答什么 |
|---|---|---|
| 我完全不知道 DSH 是什么 | 00-开始这里 → 01-仓库地图 | 插件、服务、事件、Profile、Bundle、Turn 分别是什么 |
| 我想先动手拆一个实验再读课文 | 实验室总览（网页版入口；在 GitHub 页面上请从 README 的实验表进） | 四十个离线实验各自回答什么问题、有哪些控件、进度记在哪里 |
| 我想知道一次请求怎么跑 | 03-核心文件精读 → 04-Agent与Turn流程 | 用户输入怎样变成模型请求、工具调用和 Session 事件 |
| 我想读懂 Session 和恢复 | 05-Session日志与恢复 | 为什么模型可见内容必须能从事件日志重建 |
| 我想写普通插件 | 27-工具预算与插件责任决策卡 → 10-社区生态与扩展边界 → 11-如何写一个合规插件 | 哪些是公开扩展点，插件怎样挂载、测试和卸载 |
| 我想先实际改一个最小插件（需要终端） | 28-最小插件示例与学习检查 | 怎样运行最小 Bundle 的单元测试和 lint，又不把它误当成真实 DSH 运行证据 |
| 我想知道 CI、lint 和 Agent 审阅有什么用 | 29-学习仓库的质量检查与审阅 | 哪些检查会自动阻止文档或示例回归，为什么 Agent 的意见不能代替测试和真人判断 |
| 我想实际跑一遍插件生命周期 | 最小插件工作台 → 插件测试、卸载与版本证据 | 怎样从构建产物出发，真实注册一个插件，再确认服务和 effect 已经卸载 |
| 我想亲手做一次确定性可视化实验 | 33-确定性可视化实验协议与Code-Mode权限管线 | 权限检查和工具主体执行怎样在二维时间轴上分开，预测怎样被实验检验 |
| 我想把研究问题交给 Debug 复核 | 36-研究与Debug协作 | 一份 request 怎样变成另一份 result，哪些字段是安全合同 |
| 我想写工具插件 | 13-官方工具插件完整契约 | 工具 schema、权限、取消、结果事件和 UI 呈现如何配合 |
| 我想先搞懂插件生态怎么分层 | 27-工具预算与插件责任决策卡 | 普通插件、Bundle、Hook bridge、patch、fork、注入分别由谁负责 |
| 我担心工具太多、模型上下文太长 | 27-工具预算与插件责任决策卡 → 22-工具可见性与非侵入扩展 → 23-工具可见集合观测与性能实验 → 13-官方工具插件完整契约 | 已注册、模型可见、执行允许为什么是三件事，以及怎样做 A/B 实验 |
| 我想不改源码做 Hook | 27-工具预算与插件责任决策卡 → 10-社区生态与扩展边界 → 14-官方HookBridge与兼容层 | 普通插件、Hook bridge、注入、patch 和 fork 的边界在哪里 |
| 我想审核社区项目 | 27-工具预算与插件责任决策卡 → 12-GitHub生态检索与插件实战核验 → 19-插件测试卸载与版本证据 | 项目自述、静态检查、真实安装和卸载证据分别证明什么 |
| 我只想查一个文件 | 逐文件索引导航 | 这个文件的用途、协作者、测试线索和下一跳源码在哪里 |
| 我想运行命令或做实验 | GitHub 网页、github.dev 与 Codespaces 学习路线 | 什么时候用 GitHub 网页、github.dev 或 Codespaces |
| 我想照着命令检查教材或工具快照 | 学习工具箱 | 怎样在不启动 DSH 的前提下运行入口、索引、A/B 和发布检查 |
| 我不想选择，想照着做一遍 | 15 分钟动手任务单 | 怎样得到第一条有源码证据的学习记录 |
| 我想知道还有哪些值得做 | 后续研究路线 | 哪些工作能马上做，哪些工作必须有运行条件 |
| 我想处理依赖漏洞和网页发布 | 安全告警与网页发布维护 | 如何读取 Dependabot、解释 Node 20 提示，并确认整套教材的网页路由完整 |
| 我想知道教材为什么这样设计 | 源码学习项目的渐进式设计 | 首页分流、最小示例、练习、自检和 CI 如何组成完整的一轮学习 |
第一轮分成 5 分钟认识和 10 分钟产出（7 个检查点）
前 5 分钟只读00-开始这里和01-仓库地图：教材总论、六个词、目录分工。再用约 10 分钟完成下面的检查点，留下一个固定版本源码文件的学习记录。时间是上限，不是要求一次读完。
- [ ] 我能用自己的话解释“插件”和“服务”的区别。
- [ ] 我能说出事件为什么可以让发送者不认识所有接收者。
- [ ] 我知道 Profile 是运行组合清单，Bundle 是可以装配的一组功能。
- [ ] 我能解释 Turn 和 Step 的关系。
- [ ] 我能从仓库地图找到一个
packages/下的功能组。 - [ ] 我知道普通 GitHub 网页能阅读，但不能证明插件已运行。
- [ ] 我能区分“工具已注册”“当前 agent 可见”和“这次执行被允许”。
七个检查点里有三个以上说不清，就回到00-开始这里，不要跳去逐文件索引。
不想做选择？直接照任务单走
打开15 分钟动手任务单，它会把“打开首页、读两篇基础课、选一条路线、找到一个固定源码文件、写下四句话”拆成可以逐项勾选的动作。
只想先判断工具和插件边界？直接打开工具预算与插件责任决策卡，先记住三层工具状态和六层社区生态。
迷路时只有一条规则
看不懂某个文件或术语时，先回到 00 课查词，再回到 01 课确认它属于哪一层；仍然不清楚，就把问题写成“这个东西接收什么、产出什么、由谁使用”，不要继续随机点下一篇。
第二轮再读一条主链路
完成第一轮后只选一个问题：
- 想看启动：读核心文件精读中的 Boot、Profile 和 Bundle 文件。
- 想看模型：读LLM 与工具执行，再回到
packages/llm和packages/core索引。 - 想看工具：先读工具可见性与非侵入扩展，再读工具可见集合观测与性能实验，最后读官方工具插件完整契约，追工具注册、schema、执行和结果事件。
- 想看工具和插件责任：先读工具预算与插件责任决策卡，再按它的链接进入工具可见性、社区生态或插件实现专题。
- 想看界面：读Host、Client、示例、测试与发布，再进入
packages/client索引。 - 想看扩展：读Bundle、Profile、Loader 与发布安装，再做一个最小静态插件练习。
- 想跑一遍最小流程：先做最小插件工作台，再回到 19 课补失败、取消和构建后消费者证据。
每读一个具体文件，只记录四句话：它解决什么问题、为什么放在这里、谁直接使用它、什么证据还没有验证。索引卡片提供下一跳，不替你完成源码阅读。
什么时候需要下载或开云端
只看导读、索引和固定版本源码链接：不需要下载。
想在浏览器里搜索和写少量 Markdown 笔记：打开 github.dev，但记得及时提交；它没有终端，不能运行 DSH。
想运行文档检查、构建、调试或插件实验：看GitHub 网页、github.dev 与 Codespaces 学习路线，再决定是否创建 Codespace。创建 Codespace 可能消耗免费额度，第一次学习不要为了打开 README 就创建。
需要终端而不想自己配置环境时，可以打开这个仓库的 Codespace 创建页；创建后先在仓库根目录执行 pnpm install --frozen-lockfile，再复制上面的快速检查命令。Codespace 是云端开发环境，不等于真实 DSH 运行环境。
遇到看不懂的词怎么办
先回到00-开始这里查六个基础词，再看02-Cordis与插件树理解 Context、Fiber、Service 和 Effect。仍然不清楚时，打开逐文件索引怎么读，照着“用途、设计原因、代码证据、测试关联依据”四个字段重新读卡片。
不要把索引卡片里的“直接协作者”直接当成完整调用图，也不要把“对应测试”直接当成已运行证明。具体结论要回到固定 commit 的源码和测试；真实运行结论还要记录命令、平台、输入、输出和清理。
这一轮学习完成的标准
完成下面五项，就可以进入下一个专题：
- [ ] 画出一次“输入 → Turn → Step → LLM → 工具 → Session → UI/Host”的简图。
- [ ] 从索引中选出一个源文件，并打开它的固定版本链接。
- [ ] 找到一个直接协作者和一个测试线索。
- [ ] 写下一个“源码已经支持的结论”和一个“当前还没有运行证据的结论”。
- [ ] 选择下一篇导读，而不是随机打开更多文件。
想把教材当成一个真实开源项目维护时，再读安全告警与网页发布维护。它解释为什么“网页能打开”“CI 通过”“漏洞已修复”和“运行时安全”必须分开记录。
如果你想保存这次学习结果，使用学习工作簿与首个实验的记录格式。完成度、质量统计和未验证范围统一看完成度审计与证据矩阵。
如果你已经知道文件名、包名或术语，Pages 页面右上角的“搜索文档”可以直接查；例如先试着搜索 Agent、tools 或 session。不知道要搜什么时，才回到逐文件索引导航按目录缩小范围。
看不懂、打不开或发现风险时
不要把未知社区项目当成官方插件直接运行。Issue 反馈入口按四种情况分好了表单：
- 文档事实错误：给出页面、固定版本和源码或官方文档依据。
- 链接或页面无法阅读：给出 URL、最小复现步骤和浏览器宽度。
- 教程无法复现：给出命令、脱敏输出、环境以及“应该看到 / 实际看到”。
- 社区扩展审计线索：只给公开项目 URL，区分项目自述、源码已核对和仍待核验的风险。
反馈时不要粘贴 API key、Cookie、真实 provider 凭据或私有源码；还没运行过，就写“还没有运行过”。