From 5a2fb8799c8cf85a4d7ee379e646b8dd4e4638ca Mon Sep 17 00:00:00 2001 From: kzlin Date: Mon, 11 May 2026 22:31:08 +0800 Subject: [PATCH] docs(kvc): onboarding manual for the next SWE agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A single self-contained reading manual designed to bring a fresh agent (LLM or human) to current-state proficiency in 30 min of reading + 30 min of environment validation, then have them run the next round of ablation experiments without re-litigating questions already settled. Structure: §0 TL;DR -- what you are inheriting in 5 lines §1 Reading order, tiered into Must-Read / On-Demand / Archive, with reasons for each §2 Current-state snapshot: trace/hardware/branches + claims verified + hypotheses pending §3 The three ablation experiments (E1/E2/E3) with full CLI flag specifications and environment-validation checklist §4 Known gotchas (8 of them) with symptoms and fixes -- the most important section to skim before you start §5 CLI cheatsheet: run experiments / read data / plot / git §6 Result-analysis checklist: numbers to collect, expected ranges §7 FAQ for likely stuck-points §8 Anti-patterns: what NOT to do §9 Two specific deliverables the main agent expects back Appendix A: file location lookup table Appendix B: commit lookup table (by intent) Goals encoded into the doc: - Frame "your job is ablation, not new development" -- the new agent should not be tempted to start D->P sync work; that goes on the feat/d-to-p-sync branch in a separate phase. - Make abort-accounting / max-input-len / mooncake-TCP-default pitfalls extremely visible up front so they don't get repeated. - Provide expected-result ranges so a 2x deviation is treated as a config check, not a "finding". - Make the critic-vs-production framing explicit so the new agent knows when an audit-style "MAJOR" is actually a design intent. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/ONBOARDING_NEXT_AGENT_ZH.md | 368 +++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 docs/ONBOARDING_NEXT_AGENT_ZH.md diff --git a/docs/ONBOARDING_NEXT_AGENT_ZH.md b/docs/ONBOARDING_NEXT_AGENT_ZH.md new file mode 100644 index 0000000..f58b718 --- /dev/null +++ b/docs/ONBOARDING_NEXT_AGENT_ZH.md @@ -0,0 +1,368 @@ +# 接班 Agent 上手手册 + +**对象**：接手本项目的下一个 SWE/research agent +**目标**：30 分钟读完后达到当前主 agent 的认知水平，能独立跑对照实验、看懂数据、避开历史坑 +**作者状态**：本手册定稿于 `kvc-debug-journey-v1-to-v4 @ 506d360`，下一个工作分支是 `feat/d-to-p-sync` + +--- + +## 0. 你是谁，你将要做什么（5 行 TL;DR） + +1. 你接手的是 **agentic-pd-hybrid**——SGLang xPyD 基础上加 session-aware KVCache 层的 LLM serving 框架，目标是在多轮长 context coding agent workload 上比 vanilla DP 快 +2. v2（迁移机制 + threshold tuning）已经在 SWE-Bench 50sess trace ts=1 上**击败 4DP CA** 6/8 个 latency/TTFT 指标，但 **TTFT p99 输 3×**（1.28s vs 0.43s） +3. 上一个 agent 已诊断出 TTFT p99 长尾的根因——8.3% 请求走 reseed 慢路径，每次需要 P 重算 prefill + mooncake transfer = 3-7s +4. **你的任务**：在有 GPU + IB RDMA 的环境上跑 3 组对照实验，验证 (a) naive 1P3D 拓扑相对 KVC 的边际贡献、(b) 启用真 RDMA 后 KVC v2 的 TTFT p99 是否能压到 ~0.7s 量级 +5. 跑完结果 push 到 `outputs/`，主 agent 会拉下来更新 paper draft 和 future-work 文档 + +--- + +## 1. 必读文档（按这个顺序读，**不要乱跳**） + +### Level 1：核心 30 分钟（**必读**，读完就能开始干活） + +| # | 文档 | 时长 | 为什么读它 | +|---|---|---:|---| +| 1 | `docs/PROJECT_OVERVIEW.md` | 5min | 项目目标 + 三种 mechanism（pd-disagg / pd-colo / kvcache-centric）的术语区分 | +| 2 | `docs/V2_DEEP_ANALYSIS_ZH.md` §0 (TL;DR) + §6 (生产决策) | 10min | 当前状态最准确的 snapshot——v2 赢什么、输什么、为什么 | +| 3 | `docs/KVC_ROUTER_ALGORITHM.md` §1-§3 + §9 | 10min | 形式化的算法（Algorithm 1/2/3）+ 4 个 open questions。**§9 OQ#4 就是你正在解决的问题** | +| 4 | `docs/RESEED_SLOW_PATH_AND_D_TO_P_GAP_ZH.md` §0-§2 | 5min | reseed 路径完整时间线（t=0 → t=4550ms），知道每段耗时分别来自哪里 | + +读完上面 4 篇就能跑实验了。如果你时间紧张，**就只读这 4 篇 + 本手册**。 + +### Level 2：进阶（**遇到具体问题时再读**） + +| 文档 | 何时读 | +|---|---| +| `docs/REFACTOR_PLAN_V1_ZH.md` | 想理解为什么从 ts=10 切到 ts=1 | +| `docs/MIGRATION_V1_FINDINGS_ZH.md` | 想理解 v1→v2 演化（v1 为何 thrashing，v2 reset-on-success 怎么修的） | +| `docs/V2_RESULTS_ZH.md` | v2 原始战报（注意：headline 表略乐观，请优先看 `V2_DEEP_ANALYSIS_ZH.md` 的修订版） | +| `docs/V2_DEEP_ANALYSIS_ZH.md` §4 全文 | 论文 reviewer 的对等性挑战 + 我们的辩驳；写 paper 时必读 | +| `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` | 想理解 ts=10 时代的 §1-§9 结构性问题清单（很多问题在 ts=1 下消失，但底层机制仍在） | + +### Level 3：归档（**别读**，是历史包袱） + +- `docs/AGENTIC_FIT_ANALYSIS_ZH.md`：ts=10 时代的早期分析，结论已被 ts=1 数据 supersede +- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md`：ts=10 数据下的结构性验证，同上 +- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md`：v1-v5 调优 sweep 的过程笔记，知道有这个文件就行 +- `docs/V5_PROFILE_INVESTIGATION_ZH.md`：profile 调查，已 supersede +- `docs/REFACTOR_PLAN_ZH.md`：v0 重构计划，已被 V1 supersede +- `docs/SWEBENCH_EXPERIMENT_*.md`：早期实验日志 + +### Level 0：本手册的"姐妹"文档（**读这个之前你应该已经在看本文了**） + +- `docs/ONBOARDING_NEXT_AGENT_ZH.md`（就是本文） + +--- + +## 2. 项目当前状态快照（用一张表说清） + +``` +Trace: outputs/qwen35-swebench-50sess.jsonl (4449 reqs / 52 sessions, time-scale=1.0) +Hardware: 4× H100 80GB + Mellanox mlx5_0/_1 @ 200 Gb/s IB (active, but **未启用** in current sweep) +Model: Qwen3-30B-A3B-Instruct-2507 (TP1) +Branch: kvc-debug-journey-v1-to-v4 = 主分支（v2 已合入） + feat/d-to-p-sync = 预留给 D→P 增量同步的开发，**当前空** + main = 旧 baseline，比主分支落后 18 commit +``` + +### 已得出的结论（高置信度） + +1. **v2 (reset-on-success + threshold 8192) 击败 4DP CA**：lat mean -1.4%、p50 -13%、TTFT mean -25%、TTFT p50 -55%、TTFT p90 -67% +2. **TTFT p99 KVC 输 3×**：1.28s vs 0.43s。来自 8.3% reseed/fallback 慢路径 +3. **慢路径耗时五五开**：P 端 re-prefill ~1.5-3s + mooncake P→D transfer ~1.5-4s（**当前是 TCP loopback**，未启用真 RDMA） +4. **capacity-backup 救不了 slow path**：直接 audit 过，P 端 backup 不会随 direct-to-D append 更新，是 seed-time 静态快照 +5. **D→P 增量同步代码不存在**：经 Opus agent forensic 审查 + 全分支 git 检索确认 + +### 待验证的核心假设（**这是你的实验任务**） + +| # | 假设 | 验证方法 | 预期结果 | +|---|---|---|---| +| H1 | KVC v2 相对 4DP 的胜利不只是来自 1P3D 拓扑——KVC 层（admission / migration / direct-to-D）也有显著贡献 | 跑 naive 1P3D ts=1 N=1（vanilla SGLang pd-disagg，policy=default 和 kv-aware 各一次）作为中间对照 | naive 1P3D 应该处于 KVC v2 和 4DP 之间。如果它 ≈ KVC v2 → 胜利来自拓扑而非 KVC 层；如果 ≈ 4DP → 胜利来自 KVC 层 | +| H2 | 启用真 RDMA 把 mooncake P→D transfer 从 1.5-4s 压到 200-400ms，TTFT p99 从 1.28s 降到 ~0.7s | 在 v2 sweep 加 `--force-rdma --ib-device mlx5_0`，跑同 trace 同 ts=1 | TTFT p99 应该 ~0.5-0.8s 区间。如果没改变 → mooncake 实际没用 RDMA / 配置错误；如果降到 ~0.3s → 我们对 transfer 段贡献的估计偏低 | +| H3 | 即使启用 RDMA，TTFT p99 仍然输 DP（因为 re-prefill 段不动） | 同 H2 实验结果 | 应该看到 TTFT p99 ~0.7s > DP 0.43s。如果 ≤ DP → 我们对 re-prefill 段成本的估计错了，可能整个 slow path 理论需要重审 | + +--- + +## 3. 你要跑的实验（the main task） + +### 3.1 实验矩阵（按 ROI 排序） + +| # | 配置 | GPU | mechanism | policy | RDMA | 预期时长 | 目的 | +|---|---|---:|---|---|---|---:|---| +| **E1** | naive 1P3D default | 4 | pd-disaggregation | default | 不影响 | ~5.5h | H1 baseline 1 | +| **E2** | naive 1P3D kv-aware | 4 | pd-disaggregation | kv-aware | 不影响 | ~5.5h | H1 baseline 2 | +| **E3** | KVC v2 + RDMA | 4 | kvcache-centric | kv-aware | **on** | ~5.5h | H2/H3 | + +三个 run 串行约 16.5h，并行用两组 GPU 可压到 11h。 + +### 3.2 启动配置：详细 flag 清单 + +参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版。三个新 sweep 脚本的关键 flag： + +#### E1: naive 1P3D default + +```bash +python -m agentic_pd_hybrid \ + --mechanism pd-disaggregation \ + --policy default \ + --topology-pd 1P3D \ + --transfer-backend mooncake \ + --force-rdma --ib-device mlx5_0 \ # ← 别忘了 RDMA（即使是 naive 也用 RDMA，单独测拓扑而非 transport） + --trace outputs/qwen35-swebench-50sess.jsonl \ + --time-scale 1.0 \ + --concurrency 32 \ + --request-timeout-s 300 \ + --max-input-len 87811 \ # ← 拉齐到 DP 限，消除 abort 数量不对等 + --output-root outputs/qwen3-30b-tp1-ts1-naive-1p3d-default +``` + +#### E2: naive 1P3D kv-aware + +同上，只改：`--policy kv-aware` 和 `--output-root` 路径 + +#### E3: KVC v2 + RDMA + +参考 `scripts/sweep_ts1_migration_v2.sh`，**只加两个 flag**： + +```diff + --transfer-backend mooncake \ ++ --force-rdma --ib-device mlx5_0 \ ++ --max-input-len 87811 \ + --kvcache-direct-max-uncached-tokens 8192 \ + --kvcache-migration-reject-threshold 3 \ + --kvcache-prefill-backup-policy release-after-transfer \ +``` + +**保留 v2 的其它所有配置**——这是 v2 + RDMA 的 ablation，**不要顺手改其它东西**。 + +### 3.3 实验前的环境验证（**别跳**） + +```bash +# 1. GPU +nvidia-smi -L # 应该看到 4 张 H100 80GB + +# 2. RDMA +ibstat | grep -E "State|Rate|Port" +# 期望：mlx5_0 / mlx5_1 都是 State=Active, Rate=200 Gb/s + +# 3. Mooncake 能识别 RDMA 设备 +python -c "from mooncake_transfer_engine import TransferEngine; e=TransferEngine(); print(e.get_local_topology())" +# 期望：输出包含 mlx5_0 / mlx5_1 + +# 4. 现有 v2 数据可读 +python3 scripts/analysis/recompute_summary.py outputs/qwen3-30b-tp1-ts1-migration-v2/kvc_1p3d_migration_v2_run1_metrics.jsonl +# 期望：打印出 failure_count=45, abort_count=40 等 + +# 5. 算法实现 syntax check +python3 -m py_compile src/agentic_pd_hybrid/{policies,replay,metrics,benchmark,cli}.py +# 期望：全过 +``` + +任何一步失败**立刻停下来排查**，不要硬上。 + +--- + +## 4. 已踩过的坑（避免重复） + +| # | 坑 | 症状 | 教训 | +|---|---|---|---| +| 1 | **abort 被计入 latency stats** | DP/KVC 都有 0.08s 的快速失败被算成"快请求"，拉低 mean/p50 | 已在 `metrics.py` 修复（commit `5eac9b4`）。新 run 出 summary 时会自动包含 `abort_count` / `failure_count` 字段 | +| 2 | **max-input-len 双方不一致**（KVC=92098 vs DP=87811） | SGLang 按 mem_fraction_static 自动算 max_total_num_tokens，KVC decode-only worker GPU 内存多 2 GB | 跑新 run 时显式传 `--max-input-len 87811` 强制对齐 | +| 3 | **mooncake 默认 TCP loopback** | sweep 脚本只传 `--transfer-backend mooncake` 不够，会落到 TCP，跑出来比 RDMA 慢 10× | 必须加 `--force-rdma --ib-device mlx5_0` | +| 4 | **capacity-backup 不是 D→P 同步** | flag 名字误导，看代码就会发现它只是"reseed 完不关 P session"，KV 是 seed-time 静态快照 | 不要在 capacity-backup 上浪费时间；要真正消灭 reseed 长尾必须实现 D→P，去 `feat/d-to-p-sync` | +| 5 | **N=1 在 ts=1 下"够用"是有条件的** | baseline N=3 确认 categorical 完全确定，但 v2 引入的 reset-on-success 等新代码路径未独立验证 | v2 + RDMA 的对照建议 N=2，对 RDMA-on/off 各一次 | +| 6 | **ts=10 数据**别参考 | 当年的 372/912/396 errors 是 benchmark artifact，不代表真实生产 | 所有比较锁定 ts=1，不要尝试 ts=10 "复现"或验证 | +| 7 | **critic agent 的 "MAJOR" 别盲信** | 上一轮 critic 把 cache fragmentation / prefill 闲置标为 MAJOR，其实是 KVC 的**设计意图** | 详见 `V2_DEEP_ANALYSIS_ZH §4.4 / §4.5`。Audit 视角和生产视角要分清 | +| 8 | **GPU utilization 图布局有残留小问题** | 组标签 (KVC 1P3D / DP 4-way CA) 与 subplot title 视觉上仍有轻微挤压 | 已被用户接受为可发表状态。不要再花时间调这张图 | + +--- + +## 5. CLI 速查表 + +### 跑实验 +```bash +# 完整 sweep（参考 v2） +bash scripts/sweep_ts1_migration_v2.sh + +# 写自己的 sweep：复制 sweep_ts1_migration_v2.sh，改 mechanism/policy/output-root +``` + +### 看数据 +```bash +# 修复版 summary（推荐用这个，旧的 summary.json 含 abort 污染） +python3 scripts/analysis/recompute_summary.py outputs//*_metrics.jsonl + +# 跨配置对照 +python3 scripts/analysis/analyze_ts1_validation.py # 比较 KVC vs DP ts=1 4-run +``` + +### 出图（参考 v2 流程） +```bash +# 4 张已有的图，对应不同 viz 问题 +python3 scripts/analysis/plot_v2_path_breakdown.py # execution_mode 分布 + path-level latency +python3 scripts/analysis/plot_ttft_pdf.py # TTFT PDF (KVC vs DP) +python3 scripts/analysis/plot_gpu_utilization.py # GPU 利用率（请求计数 vs 工作量） +python3 scripts/analysis/plot_cache_efficiency.py # cache 效率（hit rate vs turn + uncached ECDF） + +# 数据更新后重新出图：直接 rerun，每个脚本都参数化了输入路径 +``` + +### Git +```bash +# 主分支（实验） +git checkout kvc-debug-journey-v1-to-v4 + +# 新功能分支（D→P 同步，空） +git checkout feat/d-to-p-sync + +# 远程 +origin = git@ipads.se.sjtu.edu.cn:wangjh/agentic-pd-hybrid.git + +# Push 用 (SSH known_hosts 第一次需要 accept) +GIT_SSH_COMMAND='ssh -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=~/.ssh/known_hosts' git push + +# user.email 没设全局，建议 per-commit 传： +git -c user.email=YOUR_EMAIL -c user.name=YOUR_NAME commit -m "..." +``` + +--- + +## 6. 跑完结果后看什么数字（checklist） + +每个 run 跑完，**至少**收集以下几个数字（用 `recompute_summary.py`）： + +``` +☐ request_count (期望 4449) +☐ error_count + abort_count + failure_count +☐ latency_stats_s.{mean, p50, p90, p99} +☐ ttft_stats_s.{mean, p50, p90, p99} ← 别忘 p99！这是 KVC 的真实代价点 +☐ execution_modes 分布 +☐ per_decode_load 分布（看负载均衡） +☐ per_prefill_load （注意：dispatcher 计数 ≠ GPU 工作量） +☐ cache_hit_request_count + total_cached_tokens (推 cache hit rate) +``` + +### 三组对照实验跑完后看以下"决定性数字" + +| 比较 | 关键看点 | 决策 | +|---|---|---| +| naive 1P3D default vs naive 1P3D kv-aware | TTFT p50 差距 | 量化"policy=kv-aware 单独带来的收益" | +| naive 1P3D kv-aware vs KVC v2 | TTFT p50/p99、direct-to-D 占比 | 量化"KVC 层（admission/migration/direct-to-D）在 kv-aware 之上的额外收益" | +| KVC v2 (TCP) vs KVC v2 + RDMA | TTFT p99、reseed mode 的耗时（execution_mode == reseed 的 ttft_s p50） | 验证 H2/H3：RDMA 救多少 transfer 段 | + +### 期待的数字范围（如果实验顺利） + +| 配置 | lat p50 | lat p99 | TTFT p50 | TTFT p99 | direct-to-D % | +|---|---:|---:|---:|---:|---:| +| naive 1P3D default | ~0.85s | ~9-12s | ~0.30s | ~1.5-2s | N/A | +| naive 1P3D kv-aware | ~0.75s | ~8-10s | ~0.20s | ~0.8-1.2s | N/A | +| KVC v2 + RDMA | ~0.58s | ~7-8s | ~0.04s | **~0.5-0.8s** | ~91% | +| (参考) DP 4w | 0.67s | 8.4s | 0.09s | 0.43s | N/A | + +**如果你看到的数字偏离这个范围 ≥ 2×**，先停下来检查配置（环境验证 §3.3 那些项目），不是写报告。 + +--- + +## 7. 遇到 X 怎么办（FAQ） + +**Q: 跑出来 KVC v2 + RDMA 的 TTFT p99 比预期高很多（> 1s）。** + +A: 大概率 RDMA 没真用上。检查： +1. `outputs///benchmark-config.json` 里 `force_rdma` 是不是 `True`、`ib_device` 是不是 `"mlx5_0"` +2. 服务器 startup log（`outputs///logs/prefill-0.log`）有没有 "MOONCAKE_DEVICE=mlx5_0" / "using RDMA" 类信息 +3. `ibstat mlx5_0` 看 active 状态没掉 + +**Q: KVC v2 + RDMA 跑出来 TTFT p99 ≤ DP（违反 H3）。** + +A: 这是个好消息。可能性： +1. 我们对 re-prefill 段耗时估计偏高（实际 SGLang 的 prefix cache 把 P 端 re-prefill 救了一半） +2. RDMA 直接快到把 transfer 段压到 ~50ms 量级，整个 reseed < 1.5s +3. v2 的 reseed 触发频率被 RDMA 间接降低（某种 race condition 改善了 LRU 行为） + +任一情况都值得**深挖**，建议把 reseed mode 的 `ttft_s` 分布单独拉出来看（应该有清晰的双峰：fast reseed + 极少数 outlier）。 + +**Q: naive 1P3D 跑不起来 / SGLang 报错。** + +A: 仓库里 `outputs/qwen3-30b-exps/pd-disaggregation-default-20260427T062616Z/` 有过历史的 1P1D 跑通配置可以参考。常见坑： +1. `--mechanism pd-disaggregation` 和 `--topology` 必须配合，topology 不能用 KVC 的 1P3D 名字 +2. SGLang vendored 在 `third_party/sglang/`，**不要**`pip install sglang` 用外部版本——可能 API 不对齐 +3. `--policy default` 时不要传 `--kvcache-*` 系列 flag，会被 ignore 但会污染 config 输出 + +**Q: 我想跑别的对照（更大 trace / 更多 GPU / 真实 RDMA 跨节点）。** + +A: 先把上面 3 个 E1-E3 跑完。这 3 个是论文核心 contribution 的 ablation，不能跳。其它对照（更长 trace、8 GPU 2P6D、真跨节点 RDMA）见 `V2_DEEP_ANALYSIS_ZH §7.3`，作为 follow-up。 + +**Q: 跑完后想自动出对比图。** + +A: 4 个现有 `plot_*.py` 脚本都是参数化的，把输入路径改成你的新 run 就能复用。如果对比维度变多（如三方对比 naive vs KVC vs DP），可以扩展现有脚本而不是新写——见 `plot_ttft_pdf.py` 的模板。 + +**Q: 发现 metrics.jsonl 字段不一致 / 缺字段。** + +A: 看 `src/agentic_pd_hybrid/metrics.py` 里 `RequestMetrics` dataclass。所有新增字段必须在那里加，否则 `recompute_summary.py` 会报 KeyError。**注意**：dataclass 的 `field_names` 是按 `RequestMetrics.__dataclass_fields__` 取的，不是 jsonl 里所有 key。 + +--- + +## 8. 如果你完全卡住 + +读这一段： + +1. **不要**尝试在没看本手册 §1 必读文档的情况下硬上代码 +2. **不要**在 main 分支或 `feat/d-to-p-sync` 上跑实验——用 `kvc-debug-journey-v1-to-v4` +3. **不要**修 metrics.py 的统计字段，除非你能解释清楚为什么它当前的 abort 排除是对的 +4. **不要**信任 critic agent 的"MAJOR"标签，要看代码层证据 +5. **不要**跳过环境验证（§3.3）直接跑长 sweep——5h 跑出垃圾数据浪费的成本更高 + +如果你卡住超过 30 分钟，把卡点写成一句话，去主 agent 留言（git commit message / branch 注释）。 + +--- + +## 9. 主 agent 留给你的两个具体期待 + +1. **三组对照实验跑完后**，在新 commit message 里给我以下数字（用 `recompute_summary.py` 输出格式）： + ``` + E1 naive 1P3D default: lat={mean,p50,p90,p99} ttft={mean,p50,p90,p99} fail_count + E2 naive 1P3D kv-aware: 同上 + E3 KVC v2 + RDMA: 同上 + reseed-mode 的 ttft p50/p99 分开 + ``` + +2. **跑 E3 时收集 reseed 路径的实测耗时分布**： + ``` + pd-router-d-session-reseed 这个 execution_mode 的 ttft_s 分布 + 并把 P→D mooncake transfer 时长 vs P 端 re-prefill 时长 单独拉出 + （需要在 structural/admission-events.jsonl 里找 timestamp diff） + ``` + + 这两组数字直接决定 paper future-work 章节怎么写 D→P sync 的必要性。 + +--- + +## 附录 A：关键文件位置速查 + +| 你在找什么 | 在哪 | +|---|---| +| 算法实现 | `src/agentic_pd_hybrid/policies.py` (KvAwarePolicy + RoutingState) | +| 整个 replay orchestration | `src/agentic_pd_hybrid/replay.py` (~3000 行，**慢慢读**) | +| 指标统计 | `src/agentic_pd_hybrid/metrics.py` | +| CLI 入口 | `src/agentic_pd_hybrid/cli.py` | +| Server 启动配置 | `src/agentic_pd_hybrid/stack.py` | +| SGLang 改动 | `third_party/sglang/python/sglang/srt/{managers/scheduler.py, managers/io_struct.py, disaggregation/mooncake/...}` | +| 历史 sweep 脚本 | `scripts/sweep_ts1_*.sh` | +| 分析脚本 | `scripts/analysis/*.py` | +| 实验输出 | `outputs/qwen3-30b-tp1-ts1-*/` | + +## 附录 B：关键 commit 速查（按"想理解什么改动看什么 commit"组织） + +| 想理解 | 看 commit | +|---|---| +| v2 的核心改动 | `2ec0deb feat(kvc): session migration with reset-on-success + direct-append threshold tuning` | +| metrics.py 修复 | `5eac9b4 fix(metrics): exclude aborted requests from latency/ttft/tpot stats` | +| 完整 analysis 文档（多版本叠加修订）| `c01d610` (latest) / `9ccd853` / `b5af195` / `c551906` / `517677d` | +| 算法形式化定义 | `37e9caa docs(kvc): production-decision reframe + formal router algorithm spec` | +| 各种 figure 脚本 | `c551906` (TTFT PDF) / `b5af195` (path breakdown) / `517677d` (GPU + cache) | +| backpressure 代码 | `c47adaf feat(kvc): honor admission backpressure hints` 和 `ca4b64c feat(sglang): expose backpressure pause hint` | + +--- + +**核心句**：先读 §1 Level 1 的 4 篇文档（30 min）+ 本手册（30 min），然后按 §3 跑 E1/E2/E3 三组实验，按 §6 收集决定性数字，遇到坑查 §4，结果 push 到 `outputs/` 下。**别瞎改不属于本任务的代码**——你的工作是验证 v2 的胜利在 ablation 中是否站得住，不是开发新机制（那是 `feat/d-to-p-sync` 分支的事，下一阶段才做）。 + +跑完之后期待你的 commit！