# PR #2606 完整报告

- 仓库：`radixark/miles`
- 标题：update doc & readme
- 合并时间：2026-08-18 19:38
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2606

---

## 执行摘要

PR #2606 是一次有明确策略的文档收缩：在 dashboard 五个方向并行重构（#2581、#2022、#2023、#2026、#2027）的窗口期，删除 485 行的 dashboard 独立文档页与 6 张真实运行截图，折叠为 Monitoring & Logging 下的简短指引，并通过 docs.json 的 permanent 重定向兜底旧链接，同步清理 README 与多页文档引用。纯文档变更，无源码与测试影响，但决策逻辑值得借鉴。

## 功能与动机

PR body 为空，动机完整记录在首个 commit message 中：dashboard 仍有多处未解决问题，#2581 在修复 partition-reader 竞争与 CP/PP 分片 dump，#2022、#2023、#2026、#2027 各自重构 dashboard 的不同部分。作者的核心判断是：

> A 485-line page walking through every view, plus six screenshots of a real run, documents a surface that is still moving, so parts of it are wrong as soon as any of those land.

即在界面仍在快速变动的阶段，带截图的长教程必然刚落地就过时，甚至误导用户。替代方案是保留最小可用信息：工具是什么、两个记录遥测的 flag、serve 命令、以及指向 --help 的指引。

## 实现拆解

1. **删除 dashboard 独立页面与素材**：整体删除 `docs/user-guide/dashboard.md`（485 行）及 `docs/assets/images/dashboard/` 下 6 张 PNG。删除内容覆盖 Metrics 分类语义（`rollout/`、`perf/`、`dump/` 等前缀）、Compute Utilization 的三段式视图结构、`dump/zero_std_group_frac` 与 `dump/mixed_version_frac` 等关键指标解读、以及 sglang 视图与 wandb 类别的差异说明。

2. **导航调整与永久重定向**：`docs/docs.json` 从 User Guide 导航组移除 `user-guide/dashboard`，并在 redirects 数组末尾追加 `{"source": "/user-guide/dashboard", "destination": "/user-guide/monitoring", "permanent": true}`，保证历史书签不 404。

3. **关联文档去引用**：`docs/user-guide/fully-async.md` 移除对 dashboard 的推荐与 Compute Utilization 视图的引导，性能指标章节改为独立基础参考；`docs/user-guide/monitoring.md`、`docs/index.md`、`docs/getting-started/quick-start.md`、`docs/developer/debug.md`、`docs/README.md` 同步清理 dashboard 提及。

4. **文案统一与素材刷新**：README 将 Models 导航改为 Supported Models（header 表格与 Getting Started 列表两处），删除 feature 列表中的 dashboard 条目；`docs/assets/images/acknowledgment.png` 致谢 logo 墙素材刷新。

### `docs/docs.json`

文档站导航与重定向的契约文件：从 User Guide 导航移除 dashboard 条目，并新增永久重定向兜底旧链接。

```jsonc
// docs/docs.json —— 页面删除与导航收编的契约配置
{
  "navigation": {
    "tabs": [
      {
        "tab": "User Guide",
        "pages": [
          {
            "group": "User Guide",
            "pages": [
              "user-guide/training-backend",
              "user-guide/monitoring",
              // 此处原为 "user-guide/dashboard"，已从导航移除；
              // 旧路径仍通过下方 redirects 指向 monitoring 页
              "user-guide/customization"
            ]
          }
        ]
      }
    ]
  },
  "redirects": [
    {
      "source": "/examples/openhermes-sft",
      "destination": "/models/qwen/qwen3",
      "permanent": true
    },
    {
      // 新增：删除 dashboard 独立页后，把历史链接永久指向 monitoring 页，
      // 避免外部书签与文档站内部旧链接 404
      "source": "/user-guide/dashboard",
      "destination": "/user-guide/monitoring",
      "permanent": true
    }
  ]
}
```

## 评论区精华

本 PR 没有实质技术讨论。claude[bot] 按仓库配置提示了手动 review 模式，Rockdu 给出空正文 APPROVED。真正有价值的 " 讨论 " 是作者在 commit message 中完成的自我论证——明确列出 dashboard 在重构的状态，并推理出详细文档的时效性矛盾。这是一种典型的单人主导、低摩擦文档 PR。

## 风险与影响

- **信息缺口**：dashboard 的深度使用指引（如 Compute Utilization 的分层解读、`dump/*` 指标含义）暂时消失，排查性能问题的用户需要依赖 --help 或源码。
- **重定向依赖**：旧链接安全性完全押在 `docs.json` 的 permanent 重定向上，若文档站构建未生效，外部书签会 404。
- **回补遗忘风险**：文档收缩是临时策略，dashboard 重构完成后没有显式 issue 跟踪文档重建，存在被遗忘的可能。
- **影响范围**：16 个文件、515 行删除、17 行新增，全部为文档与素材，对训练系统零运行时影响。

## 关联脉络

本 PR 处于两条线交汇处：一是 dashboard 功能重构线（#2581 等五个 issue/PR 并行改造 dashboard），文档为此让路；二是文档站导航持续整理线（#2565 将 Welcome 折入 User Guide、#2603 新增致谢 logo 墙），本 PR 继续沿用同一套 `docs.json` 结构。后续值得关注的是 dashboard 重构完成后，是否会以新截图和新结构回补详细文档，并与 #2581 的 CP/PP 分片修复形成闭环。