社区导读

简体中文

English

简体中文

English

外观

怎样使用逐文件索引 ​

study/文件索引/ 不是把 2,973 个文件复制一遍，而是给每个真实源文件放一张小卡片。卡片上的路径链接固定到官方提交，便于从中文解释回到原始代码。

索引页的总导航在文件索引目录说明。它按 78 个页面列出覆盖目录和入口；先从目录选择功能组，再在对应页面搜索文件路径，最后沿条目里的协作者、测试和固定链接回到上游源码。

每条记录的字段 ​

每条记录有 11 个必填字段，另有可选的「测试支持」字段：

  • 所属层：它属于 packages、apps、vendor 或其他哪一层。
  • 文件角色：入口、类型契约、适配器、运行时、工具、测试等。角色根据路径和文件名生成，用来帮助第一次定位。
  • 这个文件有什么用：用不依赖具体代码细节的语言回答“它解决哪个问题”。
  • 为什么这样设计：解释拆成单独文件的常见工程原因，例如替换、测试、生命周期和边界。
  • 文件级设计证据：把当前固定提交中能定位到的顶部注释、声明、HTML/CSS/SQL 结构和静态 import 关系列出来，防止“为什么这样设计”只剩角色套话；它是静态定位证据，不是完整语义证明。
  • 直接协作者：优先列同包 README、同目录文件和同包测试，帮助你沿依赖方向继续读。
  • 对应测试：优先依据固定提交中的本地静态 import、包入口和模块别名关系寻找测试，区分“直接引用”和“经过入口或中间模块的间接线索”；只有没有这些证据时，才使用同包同名等保守线索。没有找到直接关联，不等于运行时没有测试覆盖。
  • 测试关联依据：说明“对应测试”的来源是直接 import、间接线索还是保守推断，让测试列可以被核查。
  • 阅读顺序：根据文件角色给出路线；入口、契约、状态/持久化、测试、配置和普通实现的下一跳不同，不把所有文件当成同一种代码。
  • 代码证据：记录固定提交归档扫描到的行数、声明和源码顶部注释；这些是定位线索，不等于完整语义证明。
  • 固定版本：把源码链接固定到同一个官方 commit，切换版本后必须重新生成索引。
  • 测试支持：可选字段；当对应测试依赖共享的测试支持文件时列出它们，没有就不出现。

上面的注解器把这份清单变成可点选的：选一个字段，右侧给出课程原文的定义；「必填/可选」标记来自本节第一句。

自动索引和人工精读的区别 ​

自动索引保证“每个源文件都有一条对应记录”，并且由 生成器 根据 Git tree 重新生成。它不声称已经理解每个函数的全部语义，尤其不会替代异常路径、并发和权限审查。

人工精读集中在官方主链路：Cordis、Profile、Bundle、Session、Agent、Agent Loop、工具、LLM 和 CLI。它们在核心文件精读中逐文件说明用途、设计原因、协作者和测试；其他条目先作为可追踪入口，再按需要深入。

覆盖怎样验证 ​

在仓库根目录执行：

powershell
$manifest = Get-Content -Raw study/source-index-manifest.json | ConvertFrom-Json
$headings = (Get-ChildItem study/文件索引 -File | Select-String '^### ').Count
"清单文件数: $($manifest.files.Count)"
"索引标题数: $headings"
node study-tools/verify-source-index.mjs
node study-tools/verify-study-links.mjs
node study-tools/audit-source-index-quality.mjs

当前两个数字都应为 2973。准备好同一固定提交的完整源码目录后，还可以重新运行生成器，检查它打印的提交、读取文件数和数量是否与 UPSTREAM.md 一致。不要在没有 --source-root 的 sparse-checkout 工作树里直接覆盖现有索引：那只会保留路径覆盖并丢失源码证据。若省略 --source-root，新条目会明确写“未执行源码扫描”，不能把全零 import 图误读成源码确实没有依赖。这个检查证明的是路径覆盖，不证明 DSH 能构建、能连接真实模型或所有测试都通过。

三个校验器各有分工：

  • verify-source-index.mjs 检查逐文件清单、索引条目、字段、固定 commit 和索引内部链接。
  • audit-source-index-quality.mjs 进一步统计设计理由的重复模式，并检查测试关系、文件级设计证据和自动索引边界是否自洽。
  • verify-study-links.mjs 检查手写教程中的官方源文件路径和固定版本 URL。

它们都通过，只能说明“文档指向的路径存在、索引覆盖完整、静态证据没有越界”，不能把它当成源码语义审查或运行验证。

怎样从一条记录继续追代码 ​

先按条目给出的路线走：

  • 测试：先看被测实现和断言。
  • 契约：先看消费者。
  • 状态/持久化：先看事件与不变量。
  • 入口：先看它交给的应用。
  • 配置：先看 loader 和使用者。
  • 普通实现：再沿直接依赖和测试阅读。

若条目位于 vendor/，先看第三方许可证和上游说明。

为什么选择分片索引 ​

一个 Markdown 文件放 2,973 条记录会很难搜索、加载和审阅。现在按顶层目录和 packages 功能组拆成 78 页，既保留“一文件一条”的精确对应，也让读者可以先选择自己关心的层。生成器负责清单，人工文档负责解释，两者的职责不会互相覆盖。