diff --git a/docs/ONBOARDING_NEXT_AGENT_ZH.md b/docs/ONBOARDING_NEXT_AGENT_ZH.md index f58b718..b060e4d 100644 --- a/docs/ONBOARDING_NEXT_AGENT_ZH.md +++ b/docs/ONBOARDING_NEXT_AGENT_ZH.md @@ -11,7 +11,7 @@ 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 量级 +4. **你的任务**：在有 GPU + IB RDMA 的环境上跑 2 组对照实验，验证 (a) naive 1P3D + kv-aware 相对 KVC 的边际贡献、(b) 启用真 RDMA 后 KVC v2 的 TTFT p99 是否能压到 ~0.7s 量级 5. 跑完结果 push 到 `outputs/`，主 agent 会拉下来更新 paper draft 和 future-work 文档 --- @@ -41,12 +41,12 @@ ### 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`：早期实验日志 +- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md`：ts=10 时代的早期分析，结论已被 ts=1 数据 supersede +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md`：ts=10 数据下的结构性验证，同上 +- `docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md`：v1-v5 调优 sweep 的过程笔记，知道有这个文件就行 +- `docs/archive/V5_PROFILE_INVESTIGATION_ZH.md`：profile 调查，已 supersede +- `docs/archive/REFACTOR_PLAN_ZH.md`：v0 重构计划，已被 V1 supersede +- `docs/archive/SWEBENCH_EXPERIMENT_*.md`：早期实验日志 ### Level 0：本手册的"姐妹"文档（**读这个之前你应该已经在看本文了**） @@ -77,7 +77,7 @@ Branch: kvc-debug-journey-v1-to-v4 = 主分支（v2 已合入） | # | 假设 | 验证方法 | 预期结果 | |---|---|---|---| -| 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 层 | +| H1 | KVC v2 相对 4DP 的胜利不只是来自 1P3D 拓扑——KVC 层（admission / migration / direct-to-D）也有显著贡献 | 跑 naive 1P3D + policy=kv-aware ts=1 N=1（vanilla SGLang pd-disagg，无 KVC 层）作为中间对照 | 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 理论需要重审 | @@ -87,40 +87,37 @@ Branch: kvc-debug-journey-v1-to-v4 = 主分支（v2 已合入） ### 3.1 实验矩阵（按 ROI 排序） +GPU hour 珍贵，砍掉了原计划的 naive 1P3D + policy=default baseline（low-ROI——naive 1P3D 用 default policy 在多轮 cache 命中上几乎必败，没必要拿这个对比当 H1 的对照点）。最终保留 2 个 run： + | # | 配置 | 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 | +| **E1** | naive 1P3D kv-aware | 4 | pd-disaggregation | kv-aware | **on** | ~5.5h | H1：分离"1P3D + kv-aware policy"贡献 vs "KVC 层（admission/migration/direct-to-D）"贡献 | +| **E2** | KVC v2 + RDMA | 4 | kvcache-centric | kv-aware | **on** | ~5.5h | H2/H3：验证 RDMA 能把 TTFT p99 从 1.28s 压到 ~0.7s | -三个 run 串行约 16.5h，并行用两组 GPU 可压到 11h。 +两个 run 串行约 11h，并行用两组 GPU 可压到 ~5.5h。 ### 3.2 启动配置：详细 flag 清单 -参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版。三个新 sweep 脚本的关键 flag： +参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版。两个新 sweep 脚本的关键 flag： -#### E1: naive 1P3D default +#### E1: naive 1P3D kv-aware ```bash python -m agentic_pd_hybrid \ --mechanism pd-disaggregation \ - --policy default \ + --policy kv-aware \ --topology-pd 1P3D \ --transfer-backend mooncake \ - --force-rdma --ib-device mlx5_0 \ # ← 别忘了 RDMA（即使是 naive 也用 RDMA，单独测拓扑而非 transport） + --force-rdma --ib-device mlx5_0 \ # ← 单独测拓扑+policy 而非 transport，必须开 RDMA 才能跟 E2 公平 --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 + --output-root outputs/qwen3-30b-tp1-ts1-naive-1p3d-kvaware ``` -#### E2: naive 1P3D kv-aware - -同上，只改：`--policy kv-aware` 和 `--output-root` 路径 - -#### E3: KVC v2 + RDMA +#### E2: KVC v2 + RDMA 参考 `scripts/sweep_ts1_migration_v2.sh`，**只加两个 flag**： @@ -242,22 +239,22 @@ git -c user.email=YOUR_EMAIL -c user.name=YOUR_NAME commit -m "..." ☐ 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 段 | +| E1 (naive 1P3D kv-aware) vs E2 (KVC v2 + RDMA) | TTFT p50/p99、direct-to-D 占比 | 量化"KVC 层（admission/migration/direct-to-D）在 kv-aware 之上的额外收益"（H1） | +| KVC v2 (TCP, 历史 v2 run) vs E2 (KVC v2 + RDMA) | TTFT p99、reseed mode 的耗时（execution_mode == reseed 的 ttft_s p50） | 验证 H2/H3：RDMA 救多少 transfer 段 | +| E1 (naive 1P3D kv-aware) vs DP 4w（历史 ts=1 baseline）| 全部 latency / TTFT 指标 | 间接锚定"拓扑差异 + kv-aware policy"的天花板 | ### 期待的数字范围（如果实验顺利） | 配置 | 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 | +| **E1** naive 1P3D kv-aware | ~0.75s | ~8-10s | ~0.20s | ~0.8-1.2s | N/A | +| **E2** KVC v2 + RDMA | ~0.58s | ~7-8s | ~0.04s | **~0.5-0.8s** | ~91% | +| (参考) KVC v2 + TCP（历史） | 0.58s | 8.7s | 0.04s | 1.29s | 91.6% | +| (参考) DP 4w（历史 ts=1） | 0.67s | 8.4s | 0.09s | 0.43s | N/A | **如果你看到的数字偏离这个范围 ≥ 2×**，先停下来检查配置（环境验证 §3.3 那些项目），不是写报告。 @@ -290,7 +287,7 @@ A: 仓库里 `outputs/qwen3-30b-exps/pd-disaggregation-default-20260427T062616Z/ **Q: 我想跑别的对照（更大 trace / 更多 GPU / 真实 RDMA 跨节点）。** -A: 先把上面 3 个 E1-E3 跑完。这 3 个是论文核心 contribution 的 ablation，不能跳。其它对照（更长 trace、8 GPU 2P6D、真跨节点 RDMA）见 `V2_DEEP_ANALYSIS_ZH §7.3`，作为 follow-up。 +A: 先把上面 2 个 E1-E2 跑完。这 2 个是论文核心 contribution 的 ablation，不能跳。其它对照（更长 trace、8 GPU 2P6D、真跨节点 RDMA、补 naive 1P3D + policy=default）见 `V2_DEEP_ANALYSIS_ZH §7.3`，作为 follow-up。 **Q: 跑完后想自动出对比图。** @@ -318,14 +315,13 @@ A: 看 `src/agentic_pd_hybrid/metrics.py` 里 `RequestMetrics` dataclass。所 ## 9. 主 agent 留给你的两个具体期待 -1. **三组对照实验跑完后**，在新 commit message 里给我以下数字（用 `recompute_summary.py` 输出格式）： +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 分开 + E1 naive 1P3D kv-aware: lat={mean,p50,p90,p99} ttft={mean,p50,p90,p99} fail_count + E2 KVC v2 + RDMA: 同上 + reseed-mode 的 ttft p50/p99 分开 ``` -2. **跑 E3 时收集 reseed 路径的实测耗时分布**： +2. **跑 E2 时收集 reseed 路径的实测耗时分布**： ``` pd-router-d-session-reseed 这个 execution_mode 的 ttft_s 分布 并把 P→D mooncake transfer 时长 vs P 端 re-prefill 时长 单独拉出 diff --git a/docs/REFACTOR_PLAN_V1_ZH.md b/docs/REFACTOR_PLAN_V1_ZH.md index 4fda391..5423d58 100644 --- a/docs/REFACTOR_PLAN_V1_ZH.md +++ b/docs/REFACTOR_PLAN_V1_ZH.md @@ -2,9 +2,9 @@ **日期**：2026-05-08 **前置文档**： -- `docs/REFACTOR_PLAN_ZH.md`（v0，已被本文 supersede——v0 的 backpressure 切入点结论已撤回） +- `docs/archive/REFACTOR_PLAN_ZH.md`（v0，已被本文 supersede——v0 的 backpressure 切入点结论已撤回） - `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md`（包含 §1-§7 结构性问题清单） -- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md`（ts=10 数据下的早期验证） +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md`（ts=10 数据下的早期验证） **触发**：`outputs/qwen3-30b-tp1-ts1-validation/` 4 个 run 完成（KVC 1P3D × N=3 + 4DP CA × 1，全部 ts=1） @@ -372,11 +372,11 @@ score = ( ## 附录 B：相关文档 - `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` — §1-§7 原结构性问题清单 -- `docs/REFACTOR_PLAN_ZH.md` — v0 重构计划（本文 supersede） -- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析（§1-§7 来源） -- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 -- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 演进 -- `docs/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（已 critic 修订） +- `docs/archive/REFACTOR_PLAN_ZH.md` — v0 重构计划（本文 supersede） +- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析（§1-§7 来源） +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 +- `docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 演进 +- `docs/archive/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（已 critic 修订） - `scripts/sweep_ts1_kvc_n3_plus_dp.sh` — 本次 4 run sweep 脚本 - `scripts/analysis/analyze_ts1_validation.py` — 本次分析脚本 diff --git a/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md b/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md index b695b0a..6554731 100644 --- a/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md +++ b/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md @@ -633,9 +633,9 @@ errors 漂移 **2.5×**（372→912），P50 latency 漂移 ~30%，TTFT P50 漂 ## 附录 B：相关已有文档 - `docs/PROJECT_OVERVIEW.md` — 项目目标、microbench 结论 -- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 结构性缺陷的早期分析（本报告 §2 的来源） -- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 详细演进日记 -- `docs/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（含 critic 修订） -- `docs/SWEBENCH_EXPERIMENT_RESULTS.md` — SWE 35B 早期实验 -- `docs/REFACTOR_PLAN_ZH.md` — 当前重构计划 -- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — 结构性 claim 验证（本报告的精简版） +- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md` — 结构性缺陷的早期分析（本报告 §2 的来源） +- `docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 详细演进日记 +- `docs/archive/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（含 critic 修订） +- `docs/archive/SWEBENCH_EXPERIMENT_RESULTS.md` — SWE 35B 早期实验 +- `docs/archive/REFACTOR_PLAN_ZH.md` — 当前重构计划 +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md` — 结构性 claim 验证（本报告的精简版） diff --git a/docs/V2_DEEP_ANALYSIS_ZH.md b/docs/V2_DEEP_ANALYSIS_ZH.md index 9b34cbe..f5ec5f3 100644 --- a/docs/V2_DEEP_ANALYSIS_ZH.md +++ b/docs/V2_DEEP_ANALYSIS_ZH.md @@ -609,8 +609,8 @@ v2 p99 = slow path 主导 → 8.69s (KVC) vs 8.43s (DP) 接近 - `docs/REFACTOR_PLAN_V1_ZH.md` — ts=1 验证后的方向决策 - `docs/MIGRATION_V1_FINDINGS_ZH.md` — v1 thrashing 诊断 - `docs/V2_RESULTS_ZH.md` — v2 结果原始报告（本文是对它的 critique） -- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析（§1-§7 来源） -- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 +- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析（§1-§7 来源） +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 ## 附录 C：相关代码 diff --git a/docs/V2_RESULTS_ZH.md b/docs/V2_RESULTS_ZH.md index d9f05fb..4693eb0 100644 --- a/docs/V2_RESULTS_ZH.md +++ b/docs/V2_RESULTS_ZH.md @@ -271,8 +271,8 @@ p99 +3% 几乎全部来自这 5 个 timeout（每个 ~30s 拉到 p99）。**修 - `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` — §1-§9 原结构性问题清单 - `docs/REFACTOR_PLAN_V1_ZH.md` — 重构方向 + 三情景分支 - `docs/MIGRATION_V1_FINDINGS_ZH.md` — v1 thrashing 诊断 -- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析 -- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 +- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析 +- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 - `scripts/sweep_ts1_migration_v2.sh` — 本次 v2 sweep 脚本 - `scripts/analysis/analyze_ts1_validation.py` — ts=1 4-way 对比分析 diff --git a/docs/AGENTIC_FIT_ANALYSIS_ZH.md b/docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md similarity index 100% rename from docs/AGENTIC_FIT_ANALYSIS_ZH.md rename to docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md diff --git a/docs/KVCACHE_CENTRIC_PROGRESS_ZH.md b/docs/archive/KVCACHE_CENTRIC_PROGRESS_ZH.md similarity index 100% rename from docs/KVCACHE_CENTRIC_PROGRESS_ZH.md rename to docs/archive/KVCACHE_CENTRIC_PROGRESS_ZH.md diff --git a/docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md b/docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md similarity index 100% rename from docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md rename to docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..d53a338 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,34 @@ +# 归档文档说明 + +本目录保留项目历史阶段的过程文档。**新加入项目的 agent / 人员不需要阅读这些文档**，直接看 `docs/ONBOARDING_NEXT_AGENT_ZH.md` 即可。 + +保留它们的目的： +1. 论文写作时追溯 v1-v5 调优演化过程 +2. 未来若回到 ts=10 高压区间或更大 trace 时，可参考当年的结构性问题诊断 +3. 满足学术可追溯性要求 + +## 每个文档的简要说明 + +| 文档 | 归档原因 | 何时回头看 | +|---|---|---| +| `AGENTIC_FIT_ANALYSIS_ZH.md` | ts=10 时代的 §1-§7 结构性问题分析；结论已被 ts=1 数据全面 supersede | 想知道当年 ts=10 下我们认为有什么结构性问题时 | +| `STRUCTURAL_VALIDATION_REPORT_ZH.md` | 用 ts=10 数据对 AGENTIC_FIT_ANALYSIS 的 claim 做验证；同样被 ts=1 时代 supersede | 同上 | +| `KVC_DEBUG_JOURNEY_V1_TO_V5.md` | v1-v5 5 个调优 sweep 的过程笔记；包含 errors 9→912 漂移、direct-to-D 占比变化等历史数据 | 写 paper 时要写 "as we explored configurations v1-v5..." 段落 | +| `V5_PROFILE_INVESTIGATION_ZH.md` | 给 v5 加 1Hz polling instrumentation 的调查；让 errors 涨 46× 的现象记录 | 想理解 "admission RPC 干扰 scheduler 主循环" 这条 §5 残留风险时 | +| `REFACTOR_PLAN_ZH.md` | v0 重构计划，**已被 `REFACTOR_PLAN_V1_ZH.md` supersede** | 不需要看；只有想看作者一开始的设想时翻一翻 | +| `KVCACHE_CENTRIC_PROGRESS_ZH.md` | 项目最早期（2026-04-27）的进度记录；当时还没有完整的 sweep 数据 | 几乎不需要看；满足"项目起源记录"职能 | +| `SWEBENCH_EXPERIMENT_PROGRESS.md` | SWE-Bench trace 早期实验进度记录 | 想知道当年的 trace 生成 / 采样配置时 | +| `SWEBENCH_EXPERIMENT_RESULTS.md` | 同上，早期 result snapshot | 同上 | + +## 当前活跃文档（在 `docs/` 顶层） + +跳转去看： +- `docs/ONBOARDING_NEXT_AGENT_ZH.md` — 新人上手手册 +- `docs/PROJECT_OVERVIEW.md` — 项目目标 + 术语 +- `docs/KVC_ROUTER_ALGORITHM.md` — 算法形式化 +- `docs/V2_DEEP_ANALYSIS_ZH.md` — v2 完整分析 +- `docs/V2_RESULTS_ZH.md` — v2 原始战报 +- `docs/REFACTOR_PLAN_V1_ZH.md` — ts=1 方向决策 +- `docs/MIGRATION_V1_FINDINGS_ZH.md` — v1 thrashing 诊断 +- `docs/RESEED_SLOW_PATH_AND_D_TO_P_GAP_ZH.md` — reseed 长尾 + D→P 缺口审计 +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` — ts=10 时代的结构性问题清单（作为历史 baseline 仍在主目录） diff --git a/docs/REFACTOR_PLAN_ZH.md b/docs/archive/REFACTOR_PLAN_ZH.md similarity index 100% rename from docs/REFACTOR_PLAN_ZH.md rename to docs/archive/REFACTOR_PLAN_ZH.md diff --git a/docs/STRUCTURAL_VALIDATION_REPORT_ZH.md b/docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md similarity index 100% rename from docs/STRUCTURAL_VALIDATION_REPORT_ZH.md rename to docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md diff --git a/docs/SWEBENCH_EXPERIMENT_PROGRESS.md b/docs/archive/SWEBENCH_EXPERIMENT_PROGRESS.md similarity index 100% rename from docs/SWEBENCH_EXPERIMENT_PROGRESS.md rename to docs/archive/SWEBENCH_EXPERIMENT_PROGRESS.md diff --git a/docs/SWEBENCH_EXPERIMENT_RESULTS.md b/docs/archive/SWEBENCH_EXPERIMENT_RESULTS.md similarity index 100% rename from docs/SWEBENCH_EXPERIMENT_RESULTS.md rename to docs/archive/SWEBENCH_EXPERIMENT_RESULTS.md diff --git a/docs/V5_PROFILE_INVESTIGATION_ZH.md b/docs/archive/V5_PROFILE_INVESTIGATION_ZH.md similarity index 100% rename from docs/V5_PROFILE_INVESTIGATION_ZH.md rename to docs/archive/V5_PROFILE_INVESTIGATION_ZH.md