上游版本、提交与源码锚点约定#

这一节负责把“引用哪份源码、怎样稳定落到具体位置”说明清楚。没有这层约定，后面的章节就很容易在不同版本之间漂移，读者也很难判断哪些结论是事实，哪些只是工作性推断。

为什么这层必须先说清楚#

这本书不是只讲观念，也不是只讲接口。它会反复回到真实代码路径，所以一开始就必须先回答两个问题：

1. 整本书默认以哪一版上游仓库为准；
2. 正文里的源码引用怎样稳定落到具体位置。

如果这两个问题不先收口，后面的章节就很容易出现这种情况：

• 某一页讲的是 main 的行为
• 另一页讲的是旧 tag 的行为
• 读者却以为整本书都在讲同一份代码

这会直接破坏一本系统书最基本的可信度。

当前的上游基线是什么#

本书当前默认以：

• sgl-project/sglang
• v0.5.10
• commit 1519acf37c23f2189adb93f57ca9cd2db1bebf18

为基线。

这个约定的价值，不只是“以后方便核对”，而是让后面的每个结论都能回到同一份源码时间点上。这样读者在不同章节之间切换时，不需要一直怀疑“是不是版本又变了”。

为什么源码链接不能靠手写#

如果所有链接都手写成 GitHub 长链接，短期看起来当然能用，但后面会很快出现三个问题：

1. 版本一旦更新，整本书要到处找链接替换；
2. 同一段代码在多章被引用时，容易出现路径或行号不一致；
3. 正文会混入很多又长又难维护的 URL。

所以这本书现在统一用 sglref 这套约定：正文只写稳定的引用 id，实际渲染时再落到固定 commit 的 GitHub 行号。

sglref 解决的是什么问题#

sglref 不是为了花哨，而是为了把两件事拆开：

• 正文里引用“什么概念 / 什么符号”
• 渲染时跳到“哪一份代码 / 哪一行”

这样做的收益很直接：

• 作者写正文时不必反复手拼 GitHub URL；
• 同一锚点在多章复用时，只需要维护一份映射；
• 以后如果锚点更新，可以集中改，不必改散落在正文里的每个链接。

这本书后面的所有代码书写和 review，都会默认站在这个约定之上。

反复回扣的主锚点有哪些#

从整本书后面的结构看，最值得反复回扣的几组锚点大概是：

• 入口锚点：
  • python/sglang/launch_server.py
  • python/sglang/srt/entrypoints/http_server.py
• 请求主线锚点：
  • python/sglang/srt/managers/tokenizer_manager.py
  • python/sglang/srt/managers/scheduler.py
  • python/sglang/srt/managers/detokenizer_manager.py
• 执行核心锚点：
  • python/sglang/srt/managers/schedule_batch.py
  • python/sglang/srt/model_executor/forward_batch_info.py
  • python/sglang/srt/model_executor/model_runner.py
  • python/sglang/srt/sampling/sampling_params.py
• 结构化语义锚点：
  • python/sglang/srt/entrypoints/openai/protocol.py
  • python/sglang/srt/function_call/function_call_parser.py
• 维护与证据锚点：
  • python/sglang/srt/observability/req_time_stats.py
  • python/sglang/srt/utils/request_logger.py

这份列表不是为了让读者现在就背下来，而是为了让后面的章节在反复回扣时看起来像回到同一组主脊梁，而不是不断引入新的零散文件。

这节和后面章节怎样配合#

第二部分以后，读者会不断看到：

• 代码路径
• 函数符号
• 运行时对象
• 章节里的源码链接

这一节的作用，就是让这些东西在第一次出现之前先有共同规则。这样后面每次看 sglref 或代码锚点时，读者都知道这不是随手贴的链接，而是整本书共同使用的引用系统。

小结#

这一节真正要做的，不是列出更多仓库信息，而是先把“整本书依赖哪份代码”和“整本书怎样稳定引用代码”这两条底线钉住。只要这层先稳住，后面的每一章才能既像书、又像源码导读，而不是散乱的链接集合。