先弄清每个部分做什么、输入输出是什么、需求应该接在哪里，再按问题深入实现。以一个 Coding Agent 任务为例，把模型调用、工具与环境、上下文、轨迹、评测和训练的交接串起来。
当前先完成 4.1：沿 generate 走完一次 Agent 任务。 以完整任务为主线，进入组件读清职责后返回调用处，再继续下一步。
第 2 章的深入阅读已设立专用入口：Trajectory Management 专题笔记。 读过 generate()／_run_turn() 后，按“历史接续与分叉 → assistant 改写 → token 对齐和 Sample 导出”继续。它属于现有第 2 章，不新增执行阶段，也不表示已完成学习。
第一遍：认识每个部分
| 顺序 | 阅读单元 | 图文对照 | 第一遍的目标 | 首个源码入口 |
|---|---|---|---|---|
| 00 | 全局职责与三种运行粒度 | 1.1、4、7.1 | 先认识各模块做什么、在哪里运行，以及任务、请求、训练的包含关系。 | train.py · main |
| 01 | 完整任务、Harness 与执行环境 | 4.1 的动作 4、5、6、7；7.1 | 掌握任务执行的责任划分、环境接口、成功和失败的清理位置。 | examples/coding_agent_rl/generate.py · generate |
| 02 | 模型协议、上下文与训练轨迹 | 4.1 的动作 2、3、3.5；补读会话结束 | 掌握模型调用封装、工具消息处理、上下文变化和轨迹导出的接口。 | slime/agent/adapters/common.py · BaseAdapter._run_turn |
| 03 | 策略接入、数据生成与评测合同 | 4.5、3.4、3.3、3.2、3.1；7.5/7.6/7.10 作为对照 | 掌握单样本生成、整批 rollout、评分、hook、过滤和评测配置的区别。 | slime/rollout/sglang_rollout.py · generate_and_rm |
| 04 | Trace、结果分析、测试与复现 | 9、8.2、3.5；源码 tests/ 和复现文档 | 掌握 Trace 与日志的区别、结果分析、接口测试、实验配置和可复现性边界。 | slime/observability/trace_utils.py · trace_span |
| 05 | 并发、任务数据、背压与恢复 | 7.7、4.5、4.6；6.2 为独立服务对照 | 掌握 Asyncio 调度、并发预算、任务队列、传输、持久化、取消和恢复的职责。 | slime/rollout/fully_async_rollout.py · AsyncRolloutWorker |
| 06 | 模型服务、Ray 资源与容器边界 | 4.3、4.4、2.1；Kubernetes 为独立实践 | 掌握运行位置、服务生命周期和资源治理，能定位 Kubernetes 需要补充的适配。 | slime/ray/placement_group.py · create_placement_groups |
| 07 | 训练交接、策略版本与权重更新 | 4.2、5.1、7.8；7.9 与 SFT 作为第二遍 | 掌握生成与训练的工程合同、基本 RL/SFT 区别、checkpoint 与策略版本边界。 | train.py · train |
本轮源码固定在 22a89f96835969a47055a659c588f46151f8b07a。核心包是 slime/，任务组装和策略示例还在 examples/，训练入口在 train.py，验证材料在 tests/。现有 4.1 动作讲解使用早期固定版本，辅助定位时需核对当前源码。
第二遍：优先读通三个单元
- 完整任务与环境：
generate()→ Harness → Sandbox → CLI 启动与等待 → API 回连 → diff 与独立评估 → 清理。对应 4.1 的动作 4、5、6、7 和 7.1。 - 模型与上下文：
_run_turn()→ 协议转换 → 模型输入 → SGLang 生成 → 响应与轨迹 →finish_session()→Sample。对应动作 2、3、3.5。 - 策略与评测接入：
generate_and_rm()→ 自定义生成/评分 → 样本 hook/过滤 → 评测配置 → 批次结果合同。对应 4.5 和 3.1–3.4。
随后结合 Trace 与行为测试深入并发、恢复、资源和训练交接。每个单元读完应能说明调用者、输入输出、可替换接口，以及失败后由谁处理和清理。
最终代码阅读清单
这是基于本轮确认源码的文件/函数顺序，依附原有 00–07 单元；路径均相对于源码仓库根目录，链接固定在 22a89f96835969a47055a659c588f46151f8b07a。
当前先用 4.1 连续导览走通一份任务，再用 01–26 条目回查和扩展；各条目先看职责、输入输出与停止点，随后按问题深入。 Trace 与契约测试的意识从第一条任务链就开始使用，配套测试先看 fixture/断言，不把源码阅读当作运行通过。
起步：扫 README 架构段与 train.main 的角色，再从 01 的 Sample 字段和 02 的 generate 骨架进入。当前 4.1 连续导览先选 Claude/Anthropic，沿用现有图文；下表中的 Codex/OpenAI 是同一职责的实现对照，完整链读通后再比较，避免同时展开两套协议。
00 全局职责
| 顺序 | 阅读入口 | 第一遍读到这里 | 第二遍与边界 | 配套验证材料（先读） |
|---|---|---|---|---|
| 01 · 样本数据合同 | slime/utils/types.py · Sample | 只读主要字段到 SpecInfo 前：任务身份、prompt、tokens、reward、mask、logprob、状态和 Session。 | 先能说明一次任务、一次请求、一份训练样本的区别；完整序列化与所有方法后置。 | tests/test_sample.py |
01 完整任务与环境
02 模型、上下文与轨迹
03 策略与评测接入
04 Trace、验证与复现
| 顺序 | 阅读入口 | 第一遍读到这里 | 第二遍与边界 | 配套验证材料（先读） |
|---|---|---|---|---|
| 17 · Trace 与真实埋点位置 | slime/observability/trace_utils.py · bind_trace slime/observability/trace_utils.py · trace_span slime/observability/trace_utils.py · trace_function | 先看身份、父子 span、耗时和错误，再回 sglang_rollout 的真实调用点；此步的思想也用于 02–16 的测试。 | 第二遍看 export/import 与重试关联；Coding Agent/CLI/环境/评分的端到端传播仍需补覆盖和验证。 | tests/observability/test_trace_utils.py |
| 18 · 结果分析与实验复现 | tools/trace_timeline_viewer.py · _build_items_from_trace tools/trace_timeline_viewer.py · _build_cache_data tools/trace_timeline_viewer.py · main slime/observability/metric_utils.py · compute_pass_rate docs/zh/advanced/reproducibility.md | 只读 Trace 到离线时间线的输入/缓存/入口，以及 pass@k 的分组假设；不通读 Viewer。 | 保存代码/模型/tokenizer/数据/采样/依赖/资源配置；固定 seed 不保证所有实现行为完全一致。 | tests/observability/test_trace_utils.py |
05 并发、队列与恢复
06 服务、资源与部署
| 顺序 | 阅读入口 | 第一遍读到这里 | 第二遍与边界 | 配套验证材料（先读） |
|---|---|---|---|---|
| 23 · 服务和资源的真正拥有者 | slime/ray/placement_group.py · create_placement_groups slime/ray/serving.py · ServingCluster.init slime/backends/sglang_utils/deployment.py · start_rollout_servers slime/backends/sglang_utils/external.py · discover_external_engines | 画 PG、router、Ray engine actor 和 HTTP 模型进程的运行位置，定位它们的创建者。 | 当前服务所有者在 ray/serving.py；第二遍读 engine_group/sglang_engine 与容器；Kubernetes 并行实践。 | tests/test_placement_group.py tests/test_external_sglang_engines.py |
| 24 · 健康、恢复与退出策略 | slime/ray/serving.py · ServingCluster.finish_rollout slime/ray/serving.py · ServingCluster.recover_updatable_engines slime/ray/serving.py · ServingCluster.dispose slime/ray/rollout.py · RolloutManager.dispose slime/utils/health_monitor.py · RolloutHealthMonitor.check_once slime/utils/cleanup.py · Cleanup | 区分 rollout 结束、故障引擎退役、更新前恢复、训练失败保留 serving 和成功完整回收。 | RolloutManager 只清理自己拥有的资源；第二遍沿 health checks、engine recover/shutdown；部分测试启动 CPU Ray。 | tests/test_rollout_manager_recovery.py |
07 训练交接
实现对照与后置范围
首条 CLI/协议链读通后，比较 ClaudeCodeHarness 的 write_config/launch_and_wait 与 AnthropicAdapter 的路由/_translate/_respond；共享处理与轨迹流程不用重读。
Search-R1、Tau-bench 和独立 Rollout Buffer 作为策略/环境/服务对照；模型结构、MLA、量化内核、NPU/GB10、全部 Megatron 并行实现和所有权重传输后端按实际需求后置。Kubernetes、外部 CLI 工具循环、端到端 Trace 和吞吐/恢复/训练实验需要独立实践，不能只靠阅读数量证明。
当前证据：文件、符号、行号与本地 Git blob 已静态核对；配套测试在本轮只作为阅读材料，未执行源码仓库的测试、模型服务、Ray、训练或 Kubernetes。
需要单独实践的边界
CLI 的完整工具循环来自外部实现；OpenAI/Anthropic 在当前示例中是协议形状，实际模型生成交给 SGLang。独立 Rollout Buffer 服务、会话轨迹与主链任务队列也分别承担不同职责。
Kubernetes 环境操作、容器网络与存储、资源限制、取消和清理需要独立集群实践。Ray 调度和 Docker 镜像提供参考，但不能代替这部分经验。
生成与训练交接要分清任务、请求与训练样本三个粒度，并保留所选训练方法依赖的 token、mask、reward、logprob 和策略版本信息。模型内部算子、量化和特殊硬件实现可后置。