业界案例与写法

你想做的事情没有一个统一的行业术语。对本仓库，最清楚的主称呼是：固定版本的中文源码导读：逐文件索引与核心链路精读。英文搜索时还可以使用 version-pinned source tour、codebase study guide、study fork、source atlas 或 literate architecture guide；它们是帮助定位相似项目的描述性关键词，不是公认的统一分类。

这种做法合理吗

合理，但要守住三个边界。第一，必须固定上游提交，否则今天的文件说明可能指向明天已经改变的代码。第二，必须分清机器生成的路径事实和人工写出的设计解释，不能用“索引生成成功”冒充“已经读懂所有实现”。第三，必须显眼声明非官方身份、许可证和第三方代码来源。

“每个源文件一条”适合做入口和查找表，不适合让每条都写成同样长的论文：入口、事件、类型、运行时和测试可以精读，简单常量或小测试只需要短而准确的说明。这个仓库因此让所有文件都有文件条目，再把复杂内容集中到主链路教程里。

公开案例和借鉴点

展开公开案例和借鉴点（16 行）

案例	链接	核验时使用的分支、版本或状态	本仓库借鉴的写法
DeepSeek Harness 官方架构文档	architecture.md	DSH 固定提交 aa6c361a972c8369148dea7380bb5c21c24e07ec	按 Cordis、Profile、Bundle、事件、Turn、Session 和能力扩展点讲主流程，而不是按文件名堆目录
DSH 社区 Orange Book	alchaincyf/deepseek-harness-orange-book	main，滚动页面；核验日期 2026-08-16	用人话解释、记录实际命令和现象，并配术语与版本说明；本仓库额外把 DSH 事实固定到 commit
Rust 编译器开发指南	rustc-dev-guide、章节清单	官方持续发布的网站；核验日期 2026-08-16	文档按问题和子系统组织，读者可以从自己的问题进入，不要求从第一页线性读完
CPython 内部文档	InternalDocs、入口说明	main，滚动目录；核验日期 2026-08-16	把解析器（parser）、编译器（compiler）、运行帧（frame）、垃圾回收（GC）等实现主题分开，并区分语言规范与实现细节
xv6 与 xv6 book	xv6-riscv、xv6-riscv-book 与 在线教材	源码仓库 xv6-riscv（分支 riscv）；教材仓库 xv6-riscv-book（分支 xv6-riscv）；在线教材持续发布；核验日期 2026-08-16	教材在关键解释处链接到具体源码文件、函数和行号，先讲整体，再带读关键实现
Crafting Interpreters	craftinginterpreters	master，滚动仓库；核验日期 2026-08-16	书、两种实现、测试和构建工具放在同一研究项目里，章节和可运行代码绑定
linux-insides	0xAX/linux-insides	master，滚动仓库；网页首页核验日期 2026-08-16	按启动、内存、中断和系统调用组织；README 先给项目目标、目录、内核版本、章节完成状态、前置知识和翻译入口——对应本仓库“阅读顺序、固定版本、未验证范围”三件套
esbuild 架构说明	architecture.md	main，滚动仓库；核验日期 2026-08-16	以扫描（scan）和编译（compile）两阶段为骨架，再展开解析、链接、树摇（tree shaking）、代码分割和打印
Tauri 架构说明	ARCHITECTURE.md	dev，开发分支；核验日期 2026-08-16	列出核心组件、运行时、插件、外部 crate/fork 以及开发和发布流程，适合借鉴模块边界说明
VS Code Extension API	官方 API 参考	官方持续发布页面；核验日期 2026-08-16	先定义宿主提供的扩展 API 和生命周期，再让第三方扩展围绕公开类型开发；适合借鉴“支持接口”和“内部实现”分离
Koishi 插件指南	认识插件	官方文档站持续发布页面；核验日期 2026-08-16	用中文解释插件、上下文和生态包的关系；适合借鉴面向初学者的术语解释，但不能把 Koishi API 当成 DSH API
DSH 社区目录与市场	awesome-dsh-plugin、awesome-deepseek-harness、dsh-market	社区仓库滚动更新；核验日期 2026-08-16	目录、市场和安装器要明确收录规则、来源、权限提醒和“不代表官方背书”；它们是生态基础设施，不是官方认证中心
dsh-super-injector 边界案例	yjh051108/dsh-super-injector	commit f4ef59fb31439225abefe45d6e793235a2a9d5e0；核验日期 2026-08-16	把第三方 Bundle、Loader 内部运行时注入、Fiber 重建、模块缓存和自愈分层说明；不能把“能热注入”直接写成官方插件 API
OSSU Computer Science	ossu/computer-science	master，网页首页核验日期 2026-08-16	README 先讲目标、前置与课程选择标准，再给 Contents、阶段、时长、费用、过程和社区；适合借鉴“读者先知道投入和完成标准”
Coding Interview University	jwasham/coding-interview-university	master，网页首页核验日期 2026-08-16	README 明确“是什么、需要什么、如何使用、目录、主题、每日计划和可选内容”；适合借鉴“给第一次打开的人一条可执行清单”
Build Your Own X	codecrafters-io/build-your-own-x	master，网页首页核验日期 2026-08-16	README 先按主题分类，再把每个主题指向独立的 step-by-step 教程；适合借鉴“根 README 做导航，具体教程承担细节”

上表事实的读取方式

截至 2026-08-16，我逐个检查了上表中的公开页面或仓库入口。下面这些原文事实直接影响本仓库的写法：

补充核验使用了公开的 GitHub raw/API 入口，而不是把搜索摘要当成事实。Rust 读取了 rustc-dev-guide 的 SUMMARY.md。

CPython 读取了 InternalDocs/README.md。

同时读取了 esbuild 的 architecture.md 和 Tauri 的 ARCHITECTURE.md。

DSH 社区候选则用 GitHub topic 搜索 API 和固定的 dsh-super-injector commit 交叉核对。

此前记录在 2026-08-16 的 API 查询返回过 total_count=4099 和 4136；本篇后来的一次刷新用同一个 q=topic:dsh-plugin&per_page=30 读到 5234，那次读取没有记录精确时刻。这些数字都是不同时间点的公开检索快照，只代表当时的候选集合，不能解释成已验证插件数；引用前应重新执行查询，完整的分类、版本和安装前核验方法见GitHub 生态检索与插件实战核验。

直接核对过的三个首屏结构

还直接打开了三个公开页面，专门核对“第一次打开时到底给了什么动作”，而不是只看项目名：

案例	页面上实际给出的结构	本仓库吸收的做法
GitHub Skills: Introduction to GitHub	首屏明确 Who is this for、What you'll learn、What you'll build、Prerequisites、How long，再给四个动作和“怎样开始”	首页和 START-HERE 同时写适合谁、这一轮学什么、留下什么、是否需要终端、预计用时和第一步按钮
Microsoft MCP for Beginners	用 Foundation / Building / Growing / Mastery 分阶段；每个模块继续拆成实操、样例、测试、部署、研究资料和贡献入口	侧栏按“认识 → 主链路 → 扩展 → 实验 → 生态 → 示例与维护”分组；最小示例、质量课和后续研究路线分别承载动手、验证和继续学习
VitePress: What is VitePress?	默认文档骨架提供搜索、侧栏、页内目录、上一篇/下一篇；正文还说明静态首屏、站内 SPA 导航和 Markdown 扩展	保留 VitePress 的阅读骨架，再用 reading.css 加课程卡、阅读进度、响应式卡片和证据边界；视觉增强不能替代构建后的链接门禁

这些页面的共同点是让读者在首屏完成一个小决策：我是谁、现在做什么、完成后得到什么、卡住时回哪里。对 DSH 这种包含官方源码、自动索引和实验工具的学习仓库，这比继续往首页堆专题链接更有效；首页负责分流，课程负责解释，示例负责动手，CI 负责发现结构回归。

本次用公开 HTTP 页面直接核对了VitePress 的介绍、VitePress 默认首页参考、Docusaurus 文档首页、Rust 交互式教材入口和TypeScript Handbook 入口，这些页面当时均返回 HTTP 200。它们给出的可复用模式分别是：VitePress 用 Hero、Features 和正文内容分层；Docusaurus 先给 Fast Track、Features 和 Design principles；Rust 把键盘快捷键、交互机制和内容说明独立出来；TypeScript Handbook 先写读者范围、章节结构、非目标和 Get Started。

这些模式落到本仓库，就是三条首屏动作、下一层完整路线表、可选的最小示例页、明确的完成产出和独立的证据边界。Pages 投影和入口检查这两道门禁负责发现“文案已经更新但路由没有接上”的结构回归。它们都不能替代真实 DSH、Provider 或浏览器人工阅读。

• DSH 固定提交的官方架构文档明确建议修改 packages/ 前先读架构，并把 Cordis、插件、服务、事件和可撤销效果作为理解入口；因此本仓库先讲概念和主链路，再列文件，而不是把目录树当成教程。
• DSH Orange Book 是社区作者的实机记录，不是 DeepSeek 官方文档。它的价值在于把安装、运行、费用、文件影响和实际现象写给普通读者；本仓库借鉴表达方式，但不把它的观察当成官方架构事实。
• rustc-dev-guide 明确说它帮助新贡献者定位编译器子系统，并建议按需要查找，不要求从头到尾线性阅读。这支持“问题导向的索引 + 关键链路精读”这种组织方式。
• CPython InternalDocs 明确提醒：它描述的是实现细节，不等于 Python 语言规范，而且不同版本或不同实现可能变化。对应到 DSH，就是每条导读都要写固定 commit，不能把当前内部实现说成稳定 API。
• Crafting Interpreters 的仓库把书稿、两种解释器实现和构建系统放在同一个项目中，说明教材、可运行代码和构建材料绑定起来，读者更容易从概念回到证据。
• linux-insides 在 README 中公开声明目标内核版本，并逐章标注已完成或待复核状态；这对应本仓库的“阅读顺序、固定版本、未验证范围”三件套，但不应把它的章节状态当成权威内核版本基线。
• esbuild 的架构文档以扫描（scan）和编译（compile）两个顶层阶段为骨架，再展开解析、符号绑定、链接、树摇（tree shaking）、代码分割和打印；这说明复杂仓库适合围绕数据流和阶段边界讲，而不是只按文件名逐项翻译。
• Tauri 的架构说明从 Rust、WebView、消息传递、核心组件、插件和发布流程讲系统边界；这对应本仓库把 Host、Client、native 和 vendor 分开说明的做法。
• VS Code 的 Extension API 把可供扩展使用的接口单独作为参考文档，并为扩展作者提供版本化的宿主 API；这支持本仓库把“公开 DSH 扩展点”和“Cordis 内部实现”分开记录。
• Koishi 的中文插件文档把插件加载、上下文和服务化能力拆成逐步教程；它说明中文学习材料可以先解释术语和生命周期，再进入类型与实现，但它只是同类生态的写法参考。
• DSH 自己的 Cordis 教程明确展示 ctx.on()、ctx.effect()、ctx.tools.register()；dsh.bundle.patch 则写在 bundle 包的 README 和 JSDoc 里（packages/bundle/base、packages/bundle/web-app），不在 Cordis 教程正文。因此本仓库关于“不改源码如何扩展”的结论分别以这两类官方文档为出处，而不是社区注入文章。
• GitHub topic:dsh-plugin 是用户自报的发现标签，不是官方注册表。本次 API 查询返回的结果包含 DSH 插件、目录、桌面封装和只在描述中提及 DSH 的项目，所以本仓库把 topic 数量当作“搜索噪声中的候选规模”，不当作已验证插件数量。
• dsh-super-injector 的 manifest 确实使用 dsh.bundle.patch，但源码还直接触碰 loader.internal.loadCache、entry._dispose、entry.fiber、Cordis registry 和宿主内部表；这正好说明“采用官方装配格式”和“完全使用公开插件 API”是两件不同的事。

这些仓库或持续发布的网站会继续变化；它们只用于参考文档组织方式，不是本仓库固定版本事实的证据。DSH 的源码和架构结论仍以 上游固定版本说明 和固定 commit aa6c361a972c8369148dea7380bb5c21c24e07ec 的源码为准。

另外四种直接核验的教材结构

下面四个案例是直接打开公开页面或仓库目录后记录的结构事实，不是根据搜索摘要推测出来的结论。它们的分支会继续变化，所以这里只借鉴“怎样组织读者路径”，不把它们当前的文件数量、版本号或实现内容当成 DSH 证据。

1. Linux Kernel documentation 先把文档分成“开发社区协作”“内部 API 手册”“开发工具和流程”“面向用户的文档”“固件”“CPU 架构”“翻译”等大类，再在大类下面进入子系统。它没有要求读者从一个巨大的文件清单开始，而是先让读者按身份和问题选择入口。对 DSH 的启发是：START-HERE.md 和 study/00 到 study/07 负责分流，study/文件索引/ 负责查文件；二者不能互相替代。

2. The Rust Programming Language 使用一个清晰的目录树：先有前言、引言和 Getting Started，再按编号进入概念章节；每章下面还有小节，同时穿插猜谜游戏、命令行 I/O 项目和多线程 Web Server 等可见成果，最后用附录承载关键词、工具、版本和翻译。对 DSH 的启发是：学习路线要有“先理解、再追主链路、最后做实验”的里程碑，逐文件索引则应该像参考目录，而不是要求初学者线性读完 2,973 个条目。

3. Kubernetes 的贡献者入口 把“贡献”继续分成文档、博客、内容改进、新内容、评审、本地化、SIG Docs、写作风格、参考文档生成和分析等动作；页面还提供编辑页面、创建子页面、创建 Issue 和打印整节等下一步操作。其 GitHub 源目录 content/en/docs/contribute 也按这些动作拆成子目录和文件。对 DSH 的启发是：学习者不只需要“读什么”，还需要知道“看不懂时怎么报告、想实验时怎么做、发现事实错误时往哪里提”。

4. xv6-riscv 源码仓库 与 xv6-riscv-book 教材仓库 是一个很接近本仓库的例子：源码仓库集中放 kernel/、user/、mkfs/、Makefile 和 test-xv6.py，README 说明它是用于 MIT 课程的教学操作系统；教材仓库则放章节源文件、图、字体、构建脚本和源码 booklet，README 直接链接 HTML/PDF，并说明如何用 make 构建。对 DSH 的启发是：官方源码、学习解释和生成站点可以分层保存，再用固定链接把解释带回真实代码；教材仓库不应伪装成官方运行时仓库。

把这四种结构落到本仓库，分工是：

• 根目录 README 负责“我是谁、从哪里开始”。
• START-HERE.md 负责选择路线。
• 编号课文（study/00 到 study/36）负责按概念和任务教学，确定性实验组件挂在对应课文里。
• study/文件索引/ 负责逐文件回查。
• UPSTREAM.md 负责版本锚点。
• docs/ 保留官方文档。
• website/ 只负责把这些来源投影成可搜索的 Pages 站点。

这样既能让第一次打开的人有一条短路径，也不会牺牲研究者需要的文件级可追溯性。

新手入口的共同规则

这几类项目还会把“课程路线”“主题索引”“状态/未完成项”“贡献方式”和“运行方法”分开，避免新读者在一张巨大的目录中迷路。

本仓库据此增加根目录 START-HERE.md，把 DSH 学习拆成“15 分钟基础、第二轮主链路、按目标选专题、需要运行时再开云端”四段；逐文件索引用于定位，不要求读者线性读完全部文件。

这套写法还保留两个 DSH 特有的要求：一是每条源码链接固定到同一个上游 commit，二是把“静态定位证据”“测试线索”和“真实运行证据”分开。学习项目可以从低门槛步骤开始，但不能为了易懂而把没有运行过的内容写成已经验证。

这里实际采用的规则

1. 根 README 只负责说明这是什么、从哪里开始、边界在哪里；细节下沉到 study/。
2. 00 到 07 先讲概念和主流程，避免初学者一上来面对几千个路径。
3. 文件索引 保证一文件一条，字段固定，能够由脚本重复生成。
4. 核心文件精读明确“人工读取过哪些文件”，普通条目明确“自动索引的边界”。
5. DSH 自身的官方源码链接固定到 commit；外部案例优先链接官方维护页面，并记录分支、标签或核验日期。若外部案例中的具体事实需要复现，再额外固定到对应 commit。
6. 每个解释都用“用途、为什么、协作者、测试”四个问题展开，让中学生也能先理解角色，再回到代码细节。
7. 对扩展生态额外写清“谁维护、改了哪一层、使用什么公开入口、如何卸载和验证”，不把最终效果相同的方案都叫作 hook 或插件。

这不是哪几种东西

它是面向 DSH 社区的非官方教材，不是把官方源码翻译成中文的授权版本，也不是完整的安全审计、API 兼容承诺或生产部署手册。它是带有阅读顺序的源码索引和链路说明：索引负责定位文件，固定版本源码、测试和运行结果负责证明实际行为。

参考资料的时间边界

这些案例用于学习文档组织方法，不表示它们的当前分支、许可证或内部实现与 DSH 完全相同。涉及 DSH 的事实以 上游固定版本说明 和官方提交为准；案例链接若发生变化，应在下一次导读维护中复核。