# PR #1932 完整报告

- 仓库：`radixark/miles`
- 标题：docs: the miles dashboard design and usage
- 合并时间：2026-07-30 02:18
- 原文链接：http://prhub.com.cn/radixark/miles/pull/1932

---

## 执行摘要

本 PR 为 miles dashboard 补充了用户面向的完整文档 `docs/user-guide/dashboard.md`，此前只有实现者 README。文档覆盖 dashboard 的设计（两条数据源、存储布局、读写路径、失败策略）与使用（采集参数、服务方式、视图解释），所有事实均基于源码核对，并修正了 README 中失效的安装指令。同时接入 User Guide 导航并链接到监控页。

## 功能与动机

PR body 明确说明：此前 dashboard 只有实现者 README，公开文档中没有任何内容解释如何记录遥测或如何解读视图。因此本 PR 的目标是补齐用户指南，使使用者能够理解 dashboard 的双数据源机制、存储设计的意义以及故障处理行为，从而正确采集和阅读遥测数据。

## 实现拆解

1. **新增 `docs/user-guide/dashboard.md`（+325 行）**：核心文档，分为 Design 与 Usage 两大部分。
 - 设计部分详述两条独立数据源：实时遥测（`Timer` 阶段 sink、rollout hooks、NVML sampler、sglang scraper → `DashboardCollector` 命名 actor）和训练产物（`--dump-details` 写入的各类文件）。
 - 解释存储布局动机：append only 流支持 `follow()` 字节偏移尾部追踪、并发读无锁；高吞吐流用 polars 列式帧减少内存开销；小时分区与惰性解析处理长运行任务。
 - 明确失败策略：producer 为 fire and forget，collector 异常不影响训练；写失败会 loud 报错。
 - 使用部分列出全部采集参数及默认值，说明服务方式、三视图（Metrics、Compute Utilization、Rollouts）用途，以及未启用 `--use-miles-dashboard` 时的可用能力。
2. **修改 `docs/docs.json`（+1 行）**：在 User Guide 导航数组中加入 `user-guide/dashboard`，使文档站点可见。
3. **修改 `miles/dashboard/README.md`（+4/-1）**：修正 `pip install -e .[dashboard]`（该 extra 不存在）为直接安装 `fastapi`、`uvicorn`、`polars`，并注明用户文档位置。
4. **修改 `docs/user-guide/monitoring.md`（+3 行）**：在监控页顶部添加指向 dashboard 指南的链接。

无测试、配置或部署配套改动，属于纯文档与导航调整。

### 本次 PR 为纯文档变更，没有涉及源码实现，因此不展示代码片段。核心内容见 `docs/user-guide/dashboard.md` 文档本身。

## 评论区精华

本 PR 无实质 review 讨论。唯一评论来自 `gemini-code-assist[bot]`，声明其审查服务已停止；审核者 `yueming-yuan` 直接 APPROVED，无评论内容。

## 风险与影响

风险极低，主要是文档与未来代码变更的一致性维护问题：
- dashboard 的视图结构、数据流、存储格式若后续调整，需同步更新本文档，否则会误导用户（本 PR 已发生过一次事实纠正，如 Efficiency 视图并入 Compute Utilization）。
- README 中直接列出的依赖若未来变动，需保持同步。

影响面为文档读者，对系统运行无任何影响。团队可从文档中快速掌握 dashboard 的设计边界和故障行为，降低支持成本。

## 关联脉络

本 PR 与 dashboard 相关历史 PR 相互补充：#1965 修复 dashboard 阶段可见性，本 PR 文档中描述的视图行为与其对应；#2028 扩展 session 计数器采集，属于文档中的遥测数据源之一。整体上，dashboard 正在从一个仅实现者了解的内部功能走向对用户开放的正式能力，本 PR 是这一演进的关键文档配套。