# PR #2565 完整报告

- 仓库：`radixark/miles`
- 标题：docs: fold Welcome into the User Guide tab and lead with it
- 合并时间：2026-08-16 05:45
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2565

---

# 执行摘要

本 PR 是纯文档导航配置变更，仅修改 `docs/docs.json`：把原 `Welcome` 独立标签页折叠成 `User Guide` 标签页内的首个分组，并将 `User Guide` 标签页移到导航栏最前。未新增、删除、重命名或移动任何页面，所有 URL 保持不变；review 仅有一个不阻塞的外观 nit，已由维护者 Zhichenzzz 合入。

# 功能与动机

PR body 说明了动机：`Welcome` 标签页只包含首页和三个 getting-started 页面，却排在 `Models` 之后，读者从文档根进入后要跨过 `Models` 标签才能继续 Quick Start 之后的指南。本次改动把整条“从首页到 CLI reference”的阅读路径收进同一个侧边栏：

> ...a reader landing on the docs root had to cross a tab boundary — skipping past `Models` — to continue into the guide that follows on from Quick Start.

同时把 `User Guide` 提到导航栏首位，`/docs` 首页内容不变，但激活标签变为 `User Guide`，下一步就是侧边栏第一行。

# 实现拆解

1. **折叠 Welcome**：删除 `navigation.tabs` 里的独立 `Welcome` tab，四页原样包成 `Welcome` group，置于新 `User Guide` tab 的 `pages` 首位。
2. **重组 User Guide**：原 `user-guide/*` 页面包成 `User Guide` group；`Agentic Environments` 组随之从 tab 直属降为二级分组，`user-guide/cli-reference` 仍留在 tab 直属层级。
3. **调整 tab 顺序**：`User Guide` 移到 tabs 数组第一位，`Models` 后移，`Advanced Features` 不变；`index.md` 与 `user-guide/index.md` 的 frontmatter 均未触碰。
4. **配套情况**：整个 PR 只有 `docs/docs.json` 一个文件（+37/-32），无测试、无构建配置改动，两次 merge commit 仅为同步 main。

## 关键源码片段

### `docs/docs.json`

本次 PR 唯一变更文件，集中体现导航结构重组的全部逻辑：Welcome 从独立 tab 降为 User Guide 的首个 group，User Guide 标签页移入导航栏首位。

```jsonc
// docs/docs.json —— navigation.tabs 核心结构（head 版本，已整理）
"navigation": {
  "tabs": [
    {
      // User Guide 现在是导航栏第一个标签页，Welcome 页组折叠为它的首个分组
      "tab": "User Guide",
      "pages": [
        {
          // 原 Welcome 标签页的四页原样保留，仅从 tab 降级为 group
          "group": "Welcome",
          "pages": [
            "index",
            "getting-started/index",
            "getting-started/installation",
            "getting-started/quick-start"
          ]
        },
        {
          "group": "User Guide",
          "pages": [
            "user-guide/index",
            "user-guide/concepts",
            "user-guide/launch-script",
            "user-guide/argument-groups",
            "user-guide/fully-async",
            "user-guide/training-backend",
            "user-guide/monitoring",
            "user-guide/dashboard",
            "user-guide/customization",
            "user-guide/generate-endpoint",
            "user-guide/agentic-rollout",
            {
              // 该组从标签页直属降为二级分组，未补 expanded: false，是唯一外观不一致点
              "group": "Agentic Environments",
              "pages": [
                "user-guide/environments",
                "user-guide/harbor",
                "user-guide/openenv",
                "user-guide/nemo-gym",
                "user-guide/verifiers"
              ]
            }
          ]
        },
        "user-guide/cli-reference"
      ]
    },
    // Models、Advanced Features 等标签页整体保持不变，仅顺序后移
    ...
  ]
}
```

# 评论区精华

- claude[bot]："Looks good — a straightforward docs navigation restructure with one minor cosmetic nit flagged inline."，并确认 JSON 有效、无页面丢失、无 URL 变化。
- inline 意见：嵌套后的 `Agentic Environments` 组缺少 `expanded: false`，成为文件内唯一默认预展开的二级分组；评审者定性为 cosmetic，"not significant enough to block approval"。
- 维护者 Zhichenzzz 直接 APPROVED，无附加评论。

# 风险与影响

整体低风险：这是文档站点静态导航配置，最大影响是文档读者首次进入 `/docs` 时的导航路径更连续；唯一的可见不一致是 `Agentic Environments` 组会以预展开状态渲染。代码、训练、CI 均不受影响，所有 URL 与页面内容保持不变。

# 关联脉络

这是文档导航系列的又一步：PR#2491 先把 Environments 挪进 User Guide 并更名 Agentic Environments，本 PR 再将其降为二级分组；PR#2489 确立了纯标签式侧边栏分组与 Overview 落地页；PR#2487 清理了导航栏 Contact 按钮；PR#2533 同步了 Agentic 文案与 README。系列整体方向是把新读者路径收敛到单一标签页、减少导航层级跳跃。