学习仓库实际使用手册

这份手册回答“我打开仓库以后该做什么”。本仓库是固定版本源码的中文导读和索引，不是 DSH 的替代实现，也不是把所有上游源码复制过来的镜像。你可以先在 GitHub 上阅读；只有需要逐行跟踪、运行测试或重新生成索引时，才下载同一固定提交的上游源码。

如果这是你第一次打开仓库，先看根目录的开始学习入口，按目标选一条路线，再回到本手册查具体操作。

如果你不想下载到本地，先读GitHub 网页、github.dev 与 Codespaces 学习路线。普通 GitHub 网页适合只读，github.dev 适合搜索和少量编辑，Codespaces 才适合运行命令；不要把三者的能力混在一起。

先按目标选择路线

展开先按目标选择路线（12 行）

你的目标	推荐入口	这条路线最后应得到什么证据
第一次理解 DSH	00 → 01 → 02 → 03	能说清插件、服务、事件、Profile、Bundle、Session、Agent 和 Turn 的关系
追一个具体文件	08 → study/文件索引/README.md → 对应索引页	找到该文件的用途、设计证据、直接协作者、测试线索和固定版本源码链接
理解一次请求	03 → 04 → 05 → 06 → 07	能沿输入、模型请求、工具调用、Session 事件和宿主退出顺序追踪一次 Turn
写普通插件	10 → 11 → 13 → 19	选到公开扩展点，并拥有最小 Context、Loader、构建和卸载证据
判断插件责任和工具预算	27 → 22 → 23 → 10 → 11	能先判断工具可见性和扩展层级，再决定是否写插件或维护 fork
控制工具上下文	22 → 13 → 19	能把工具注册、模型可见和执行权限分层，并知道真实性能仍需基准
接入外部 Hook	10 → 14 → 19	能区分协议解析、bridge 映射、typed Decision、外部命令权限和 dispose
发布 Bundle	12 → 15 → 19	能说明 manifest、patch、Profile、Loader、版本范围、安装脚本和失败恢复
审核社区项目	10 → 12 → 15 → 19	能把官方事实、项目自述、静态检查和已运行测试分开记录
第一次照着做	16 → 00 → 08	完成一张文件卡片、一张 Turn 图和一次静态插件检查
判断教材是否够用	17 → 08 → 对应索引页	知道哪些内容已覆盖，哪些仍需源码或运行实验证明
更新上游版本	18 → 20 → 08	能保留旧快照、重新生成索引并复核高风险专题

上面的选择器把这张表变成可点选的：选一个目标，右侧列出路线链（数字可直接点进对应课程）和走完应得到的证据；路线与证据逐字来自表格，「对应索引页」没有唯一目标所以不带链接。

不要从 2,973 个索引条目第一页开始顺序通读。索引的价值是按目标定位；概念路线负责建立心智模型，文件卡片负责把概念落回源码。

第一次使用：先做一轮不下载的阅读

第一步打开根目录 README，确认仓库身份、固定提交、文件范围和证据边界。你会看到本仓库是面向社区的非官方学习材料，不是 DeepSeek AI 官方仓库，也不会把索引生成成功写成 DSH 已经构建或真实模型调用成功。

第二步读 00-开始这里 和 01-仓库地图。先记住六个词：插件、服务、事件、Profile、Bundle、Turn；如果这六个词还不能用自己的话解释，不要急着打开最大的索引页。

第三步读 02-Cordis与插件树，理解 Fiber、Context、效果清理和插件装配。读到“注册”时要继续问：注册返回什么 disposer，谁拥有它，Fiber dispose 时怎样撤销。

第四步按兴趣选择 03-核心文件精读 或 04-Agent与Turn流程。每读一个文件，先看它的包 README、入口和类型，再看实现，最后看测试；不要只凭文件名猜设计原因。

怎样使用逐文件索引

先打开 文件索引导航，按 apps、packages、vendor、scripts 或具体功能组选择页面。packages-core.md 不是一个文件，而是 packages/core/ 下所有纳入范围源文件的分片索引；根部 vitest-*.md 才是单个配置文件的索引页。

打开索引页后，用文件路径搜索目标条目。每条记录按固定字段阅读：所属层、文件角色、用途、设计原因、文件级设计证据、直接协作者、对应测试、测试关联依据、阅读顺序、代码证据和固定版本。

索引卡片给你的是“下一跳”，不是结论终点。先点击固定版本源码，再打开同包 README 和测试；如果卡片只有静态 import 或文件顶部声明，就把它记录为定位证据，不要写成“已经证明运行时行为”。

怎样真正读懂一个文件

给目标文件建立一张自己的学习记录：

文件路径：
所属层和包：
它解决的问题：
为什么单独放在这里：
直接协作者：
我找到的测试：
测试实际证明了什么：
还没有证明什么：
固定提交：aa6c361a972c8369148dea7380bb5c21c24e07ec

先看声明和导出，知道文件对外承诺什么；再看调用者，知道谁依赖它；然后看实现的成功、失败、取消和清理路径；最后看测试断言是否覆盖这些路径。一个测试文件被 import 了，只能说明存在静态关联，不能说明每个分支都被运行。

遇到 vendor/ 文件，先看上游许可证、Manifest 和 local modifications。它可能是第三方固定副本，也可能有 DSH 的重命名、构建配置或局部修改；不能因为文件在官方仓库里，就把全部实现归为 DSH 原创。

怎样学习写插件

先读 社区生态与扩展边界，判断需求属于普通插件、工具插件、Hook bridge、Bundle/Profile 配置层、源码 patch、fork 还是运行时注入。能使用公开事件、服务或工具接口时，优先选择公开接口；如果必须改源码，就在项目说明中明确写成 patched fork，并记录基线提交和维护差异。

再读 如何写一个合规插件，从只观察一个事件的最小插件开始。先验证挂载和 dispose，再增加服务或工具；每加入 timer、watcher、网络连接、子进程、凭据或临时文件，就同时增加对应的取消、失败和清理测试。

如果插件向模型提供工具，接着读 官方工具插件完整契约。重点检查工具 schema、native/code/both 呈现方式、restrict() 可见性、guard() 拒绝、并发、取消、结果事件和最终面向模型的内容。

如果插件要兼容外部 shell hook，读 官方 HookBridge 与兼容层。不要把外部命令、协议共享库或 bridge 自动称作 marketplace 插件；它们还要分别说明协议子集、操作系统权限、matcher、超时、abort 和 drain。

如果插件要作为可安装组合发布，读 Bundle、Profile、Loader 与发布安装。同时检查 package.json、manifest、patch、dependencies、exports、构建脚本和 Profile 顺序，不能只看一个 dsh.bundle.patch 字段。

最后用 插件测试、卸载与版本证据 完成证据链。单元测试、最小 Context、Loader 组合、构建产物、快照、E2E 和真实 API 是不同层级，不能用低层绿色结果替代高层验证。

如果你只是想确认“我有没有读对”，先打开完成度审计与证据矩阵；如果你准备研究新版本，再打开维护、更新与版本迁移。这两篇是判断和维护材料，不是要求每次学习都执行的实验。

怎样审核一个社区项目

先核对项目身份：仓库所有者、维护者、许可证、源码地址、发布包名、固定 DSH 版本和是否明确声称官方。dsh.bundle.patch、官方风格的包名、GitHub topic、注册表条目或 UI 位置都不能单独证明官方背书。

再核对安装行为：读取 package.json 的 dependencies、exports、bin、scripts 和发布文件，特别注意 prepare、preinstall、postinstall、构建许可、网络、凭据、子进程、注册表和文件写入。安装前先在隔离环境检查，不要把“能安装”当成“值得信任”。

然后核对运行方式：项目是调用公开插件接口，还是依赖 patched fork、修改构建产物、运行时注入、注册表覆盖或某个私有内部路径。README 应该明确写出基线版本和失败方式；如果它只说“支持 DSH”而不说明入口和版本，证据不足。

最后核对测试和卸载：找真实 Loader/Bundle 组合、构建后入口、快照、E2E、取消和 dispose 断言。记录“项目 README 自称通过”和“你实际运行的命令”两栏，不能把别人的截图或 CI 徽章当成本地复核。

什么时候需要下载上游源码

只看概念、索引卡片和固定链接时不需要下载。需要逐行阅读、运行上游测试或重新生成索引时，下载官方固定提交到独立临时目录，不要把它放进学习仓库，也不要使用其他项目的工作目录。

PowerShell 示例：

$commit = 'aa6c361a972c8369148dea7380bb5c21c24e07ec'
$sourceRoot = Join-Path (Split-Path (Get-Location) -Parent) ('_dsh-study-upstream-' + $commit)
if (Test-Path -LiteralPath $sourceRoot) { throw "临时目录已存在，请先人工确认：$sourceRoot" }
git clone --filter=blob:none https://github.com/deepseek-ai/deepseek-harness.git $sourceRoot
git -C $sourceRoot checkout --detach $commit
git -C $sourceRoot rev-parse HEAD

最后一条命令必须输出固定提交。研究完成后只删除这个明确命名的临时目录；删除前再次用 Resolve-Path -LiteralPath $sourceRoot 核对路径，不要把变量改成仓库根、用户目录或通配路径。若要重新生成索引，把该目录作为 --source-root 传给生成器。

清理时可以使用下面的检查：只有临时目录名称仍然等于当前固定提交对应的名称，才执行删除。

$resolvedSource = (Resolve-Path -LiteralPath $sourceRoot).Path
$expectedLeaf = '_dsh-study-upstream-' + $commit
if ((Split-Path -Leaf $resolvedSource) -ne $expectedLeaf) { throw '拒绝清理非预期目录' }
[System.IO.Directory]::Delete($resolvedSource, $true)

怎样运行学习仓库自己的检查

在学习仓库根目录运行下面的命令。它们检查文档工具和索引自洽，不启动 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 页、固定 commit 一致、每条记录有完整中文字段、索引内部链接存在、质量审计没有结构错误。质量审计的提示不一定是错误；要结合提示内容判断是否是自动索引边界的正常提醒。

怎样判断自己真的学会了

不要用“我读完了多少页”衡量。做一轮完整的练习：从一个索引条目出发，指出文件用途和设计原因，找到直接协作者，解释一条测试断言，说明一个失败或清理路径，再说明哪些结论仍然没有运行时证据。

对插件写作，再增加三个问题：它使用哪个公开扩展点，安装时由哪个 Bundle/Profile/Loader 组合，dispose 后怎样证明事件、工具、watcher、连接和子进程都停稳。如果答不出来，就回到 13、15 和 19，不要急着发布。

本仓库目前把“每个纳入源码扩展名白名单的文件都有中文结构化入口”和“少量核心文件人工精读”明确分开。前者已经可以用于全量定位，后者才是深入语义阅读；不能把 2,973 张卡片说成 2,973 个文件都被逐行人工审查。

一轮学习结束后的记录格式

每完成一个主题，保留四行记录：

我读了：哪些导读、索引页和固定版本文件
我证明了：哪些用途、协作关系、测试或生命周期事实
我还不知道：哪些运行时、平台、真实 API 或社区项目事实
下一步：一个明确的源码文件、测试或小实验

这样使用时，这个仓库就是一张从概念到源码、从源码到测试、从测试到扩展和发布证据的学习路线图。