代码导读#

代码导读部分的职责，不是把仓库目录逐层复述一遍，而是把前文已经建立好的心智模型重新压回真实源码树。读到这里，读者不再缺“系统是什么”的解释，而更容易缺“现在该进哪一棵树、先读哪个文件、怎样避免读散”。这一部分要解决的，正是这种从抽象回到实现时的阅读阻力。

因此，这一部分最重要的产出不是更多目录名，而是几条稳定的源码阅读路线：从公开入口读进去，从请求主线读进去，从执行中枢读进去，从缓存和观测树读进去，以及从 examples / tests / benchmark 这些验证材料读进去。只有这些路线足够清楚，代码导读才像书的后半程，而不是一张目录清单。

这一部分怎样读#

这一部分目前章节很多，但它们并不是三十多篇并排短文。更稳的读法，是把它们压成五组阅读任务。

第一组：先确认外部入口和协议桥#

如果你的问题是“这个系统到底从哪里进来”，先读这组：

• 7.1 从仓库入口回到请求主线
• 7.8 读 entrypoints/openai：协议表面怎样回到 runtime
• 7.9 读 protocol.py 与 io_struct.py：公开协议怎样变成内部对象
• 7.18 读 http_server.py：接口森林与 app.state 装配
• 7.19 读 launch_server.py：模式分叉怎样决定全书入口

这组章节回答的是同一个问题：外部请求如何被解释成系统内部对象，而不是“有哪些入口文件”这么浅的一层。

第二组：顺着请求与 manager 主线往里走#

如果你的问题是“请求怎样在 runtime 里被编排和收口”，先读这组：

• 7.20 读 tokenizer_manager.py：入口、状态桥与回包收敛
• 7.21 读输出尾部：scheduler output processor 与 detokenizer
• 7.23 读 detokenizer_manager.py：decode_status、stop trim 与文本收口
• 7.24 读 multi_tokenizer_mixin.py：多 worker 入口与回包拆分
• 7.26 读 health_generate：探活请求怎样穿过 runtime

这组章节的核心，是把“入口 manager、调度器输出尾部和回包收口”看成同一条请求桥，而不是几个散点文件。

第三组：进入调度、执行和缓存中枢#

如果你的问题是“系统真正怎样把请求变成 batch、执行对象和缓存状态”，优先读这组：

• 7.11 读 scheduler.py 与 schedule_batch.py：主循环和对象骨架
• 7.27 读 BasePrefixCache 与 radix_cache.py
• 7.31 读 model_runner.py：执行壳的真正汇合点
• 7.32 读 model_loader：权重如何进入执行壳
• 7.33 读 forward_batch_info.py：执行对象如何真正落地
• 7.35 读 tp_worker.py：scheduler 与执行壳之间的 worker 外观

这是整本书和源码贴得最紧的一组章节。前文的 Req、ScheduleBatch、ForwardBatch、ModelRunner 和 KV cache 语义，都会在这里重新汇合。

第四组：读控制面、观测面和维护支线#

如果你的问题是“系统怎样被观察、控制和维护”，先读这组：

• 7.13 读 observability 源码树：从 RequestStage 到 exporter
• 7.25 读 session_controller.py 与 SessionAwareCache
• 7.28 读运行时控制面：logging、weights group 与 expert record
• 7.29 读 request_logger 与 schedule_simulator
• 7.34 读 server_args.py 与 PortArgs

这组章节把“维护者视角”正式拉回源码层，避免读者只在第 8 节里学会排障，却不知道对应实现藏在哪些树里。

第五组：把源码阅读重新接回验证材料#

如果你的目标是“读完源码之后如何验证理解”，再读这组：

• 7.2 文档、示例、测试与 benchmark 怎样支撑阅读
• 7.5 通过 tests 反向理解系统行为
• 7.6 从 README 到 benchmark：一条更完整的仓库主线
• 7.7 从 benchmark 和 profiler 反向理解实现
• 7.12 用 bench_one_batch.py 做最小执行显微镜

这组章节的重点不是再介绍新模块，而是告诉你：源码理解要怎样回到 examples、tests、profiling 和 benchmark，才算真正闭环。

为什么这一部分不该写成逐章目录#

代码导读部分最容易失控成“目录越厚越像资料汇编”。但优秀技术书不会让读者在第七部分看到一份三十多项的平铺目录，因为那会立即把“源码阅读路线”重新打散成“单篇主题列表”。

更稳的办法，是像上面这样把章节压成少数几条阅读任务。这样读者面对的不是三十五个平行入口，而是五种明确的问题场景：我是在找入口，找请求桥，找执行中枢，找维护支线，还是在找验证材料。只要问题先明确，章节数量再多也不容易读散。

这一部分和前后章节的关系#

代码导读放在 6. 结构化生成与 API 之后，不是因为源码没有前面重要，而是因为这里的阅读质量高度依赖前文。如果你还没有把请求主线、运行时边界、调度对象和执行对象分清，直接读 scheduler.py、radix_cache.py 或 model_runner.py，通常只会得到很多局部事实，而不会形成稳定地图。

同样，代码导读之后立刻接 8. 扩展与调试，也不是偶然。第七部分负责告诉你“源码在哪、怎样读”，第八部分负责告诉你“读完之后出了问题怎么看、要改系统怎么进”。这两部分合起来，才是一本系统书真正落到工程动作的地方。