学习工作簿与首个实验

这篇把“读学习仓库”变成可以完成、可以记录、可以复查的练习。它不要求你先构建 DSH，也不要求 API key；前半部分只用浏览器和本仓库，后半部分才按条件使用固定版本的上游源码或本地 DSH CLI。

本文使用的上游版本是 aa6c361a972c8369148dea7380bb5c21c24e07ec。学习仓库自己的版本则看 GitHub 提交；两者不要混为一个版本号。

先选择你要走的模式

模式	需要什么	能得到什么	不能顺便声称什么
GitHub 阅读	浏览器	概念路线、固定源码链接、逐文件索引	没有证明本地构建或运行
本地读文档	Git 或下载 ZIP	全文搜索、个人笔记、文档门禁	没有证明上游 DSH 已安装
上游源码追踪	固定提交的完整源码目录	逐行阅读、重新生成索引、运行选定测试	没有证明真实模型和所有平台都通过
插件实验	已安装 DSH 或完成上游构建	Loader/Profile/插件生命周期证据	没有自动获得官方背书

第一次学习建议只走前两种模式。看到 pnpm install 不用急着安装完整 DSH；概念和证据边界先立住，后面的命令才有判读依据。

第一次打开仓库：十五分钟路线

第一步：确认你读的是什么

先看根目录 README 和 上游固定版本说明。确认三件事：这是非官方学习型 fork、源码链接固定到哪个提交、哪些文件被纳入逐文件索引。

然后看完成度审计与证据矩阵。它把“已覆盖”和“尚未证明”分开，避免你把学习仓库的绿色门禁误读成 DSH 运行成功。

第二步：建立心智模型

依次读从零开始读 DSH、仓库地图和Cordis 与插件树。读完后，用自己的话回答：插件由谁拥有、服务放在哪里、事件怎样连接、Fiber 什么时候清理。

第三步：选择一条主链

想理解一次请求，就读核心文件精读到LLM 与工具执行。想理解安装和扩展，就读社区生态与扩展边界到Bundle、Profile、Loader 与发布安装。

不要从 2,973 张卡片的第一页开始顺序通读。概念文章负责建立地图，索引卡片负责把问题落到某个文件。

工作簿一：从一张卡片追到源码

选一个初学者容易观察的目标，例如 packages/core/tools/src/index.ts。打开逐文件索引导航，进入 packages-core.md，搜索完整路径。

把下面的记录复制到自己的笔记中：

固定提交：aa6c361a972c8369148dea7380bb5c21c24e07ec
文件路径：
所属层和包：
文件角色：
它解决的问题：
为什么单独放在这里：
直接协作者：
对应测试和测试主题：
我从源码看到的一个关键声明或不变量：
我还没有证明的行为：
下一跳文件：

先打开卡片里的固定源码链接，再打开同包 README、入口类型和对应测试。卡片里的 import、声明和顶部注释是定位证据；真正的行为结论要由源码和测试断言补齐。

完成这一练习的标准是能回答：谁调用这个文件、它输出什么、失败时发生什么、谁负责清理、测试实际断言了哪一条规则。

工作簿二：把一次 Turn 画出来

使用Agent 与 Turn 流程、Session 日志与恢复和LLM 与工具执行，在纸上或笔记里补齐下面的箭头：

用户输入
  -> 哪个 Context/Agent 接收
  -> 哪个事件或服务预处理
  -> Session 记录了什么
  -> Prompt 怎样加入工具和历史
  -> LLM 返回什么
  -> 工具怎样被校验、审批、执行和呈现
  -> 哪些事件持久化
  -> Turn 怎样结束、取消或恢复

每个箭头都写一个固定源码链接。若只能写“某个模块会处理”，说明还没有追到足够具体；若只能写测试文件名，也要回到实现确认测试究竟证明了什么。

画完以后，用两个实验对答案：Turn 流程实验把这条链摆成可步进的时间线，滑杆停在哪一步都能对上日志；Session 日志重放实验演示状态怎样从事件逐条折叠出来。你的手画图和它们的分步展开对不上时，差异处就是要回源码确认的地方。

工作簿三：先做静态插件实验

先阅读如何写一个合规插件。把示例复制到学习仓库之外的临时目录，例如 dsh-study-lab；不要把实验代码混进本仓库的索引目录。

第一阶段只做三件事：检查包名不是官方 namespace、检查 apply(ctx) 使用公开接口、检查每项资源都有 dispose 路径。可以先运行入口语法检查：

node --check .\index.js

这只能证明 JavaScript 能被解析。它不能证明 DSH Loader 能找到包，也不能证明工具、事件、Profile 或卸载行为正确。

工作簿四：有 DSH CLI 时做组合实验

只有在目标版本的 DSH CLI 已安装，或你已经按官方文档完成上游构建时，才进入这一步。命令以固定提交的 CLI 实现和 README 为准；不要把本机另一个版本的命令当成永久 API。

把本地 Bundle 加入一个专用 Profile 后，先检查组合层，再启动：

dsh plugin --profile study add ./dsh-yourname-study-plugin
dsh --profile study --dump-config
dsh --profile study

观察证据要分开记录：--dump-config 只能证明 patch 被组合；启动日志或状态才可能证明 Fiber 激活；事件输出或工具结果才可能证明行为发生；dispose 后再次触发且没有旧输出，才是卸载证据。

实验结束后移除包和配置。若命令与当前版本不一致，记录“命令版本不匹配”，不要为了让实验通过而修改官方源码。

工作簿五：工具、Hook 和社区项目

想写工具插件，先按工具可见性与非侵入扩展设定正常 agent 的工具预算，再按官方工具插件完整契约逐项检查 schema、exec.signal、并发、结果内容、可见性和卸载。先做无网络、无子进程的纯工具，再增加外部资源。

想接外部 Hook，按官方 Hook Bridge 与兼容层记录 matcher、stdin、退出码、超时、abort、drain 和支持事件。不要把外部 shell 命令直接叫作原生 DSH 插件。

想审核社区项目，按GitHub 生态检索与插件实战核验填表：身份、基线提交、装配格式、安装脚本、文件/网络/凭据权限、测试、卸载和官方身份声明分别记录。

学习仓库自己的门禁

这些命令只检查学习仓库的文档和索引，不启动 DSH，不调用真实模型：

node --check study-tools/generate-source-index.mjs
node --check study-tools/verify-source-index.mjs
node --check study-tools/audit-source-index-quality.mjs
node --check study-tools/verify-study-links.mjs
node study-tools/verify-source-index.mjs
node study-tools/audit-source-index-quality.mjs
node study-tools/verify-study-links.mjs
git diff --check

当前固定版本的预期重点是：清单和索引各为 2,973 条、索引页为 78 页、结构错误为 0、手写路径错误为 0。质量审计的重复模板提示需要人工理解，不要把“提示数为 0”当成唯一目标。

一轮学习怎样才算完成

一轮完整的学习至少要留下四行记录：

我读了：导读、索引页、固定版本源码和测试
我证明了：一个用途、一个设计原因和一条生命周期/测试事实
我还不知道：一个没有运行时证据的边界
下一步：一个具体源码文件、测试或受控实验

如果你能从一张索引卡片追到实现、测试和清理路径，再用一个最小插件验证公开接口，这份记录就已经可以被别人复核：每个结论都带着它的源码位置和证据边界。

出现问题时怎样判断

链接打不开，先检查你是否仍在固定提交；索引找不到文件，先检查路径是否属于当前白名单；命令失败，先区分 Node/依赖问题、Loader 装配问题、权限问题和真实 API 问题。

不要用“页面能打开”“配置里出现一行”或“测试被 import”代替运行时结论。把失败原样记录下来，并标注它属于哪一类（Node/依赖、Loader 装配、权限、真实 API）；下次遇到同类报错就能直接定位。