# PR #2491 完整报告

- 仓库：`radixark/miles`
- 标题：docs: nest Environments under User Guide, rename to Agentic Environments
- 合并时间：2026-08-14 03:40
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2491

---

# 执行摘要

- 一句话：环境文档移入 User Guide 并更名 Agentic
- 推荐动作：该 PR 价值较低，无需精读，可作为 " 保持 URL 稳定前提下重排文档导航 " 的最小范例：显式声明 URL 不变、复用既有子分组结构范式、同步更新页面 title 与索引表格三处保持一致。若关注 Miles 文档信息架构演进，可顺带阅读 PR #2484 的导航结构改动。

# 功能与动机

issue #2409 明确要求：'Move Environments under the User Guide as a sub-entry. Rename Environments to Agentic Environments'。PR body 进一步说明：将 docs/docs.json 中的 Environments 分组移入 User Guide 分组作为嵌套子条目（与既有 Launch Script 子分组同构），保留其 root 与四个 connector 页面，放在 Agentic Rollout (TITO) 之后、CLI Reference 保持在最后；同时保持页面 URL 不变，使 index.md、harbor.md、openenv.md、nemo-gym.md 等既有入站链接继续有效。

# 实现拆解

变更入口是文档站点导航数据源 docs/docs.json，共三处同步修改：

1. 导航结构迁移（docs/docs.json）：将原来与 User Guide 主分组平级的 Environments 分组整体移入主分组的 pages 数组，成为嵌套子分组，结构范式与既有的 Launch Script 子分组完全一致；子分组保留原 root（user-guide/environments）及四个页面（harbor、openenv、nemo-gym、verifiers），名称改为 Agentic Environments，并放置在 agentic-rollout 之后、cli-reference 之前，确保 CLI Reference 仍为最后一项。
2. 页面标题同步（docs/user-guide/environments.md）：frontmatter 的 title 由 Environments 改为 Agentic Environments，保证侧边栏分组名与页面标题一致。
3. 索引表格同步（docs/user-guide/index.md）：User Guide 首页表格中的 Environments 行更名为 Agentic Environments，并移动到 Agentic Rollout (TITO) 行之后、CLI Reference 行之前，与导航顺序一一对应。
4. 兼容性保障与合流：所有页面 URL 均未变化，既有入站链接无需任何修改；第二个 commit 将 main 合入，解决了 docs.json 与 index.md 上与主线产生的冲突。

无源码、测试或部署配套改动；docs.json 由既有站点生成流程消费，本次仅涉及节点移动，键与页面路径均未变。

关键文件：
- `docs/docs.json`（模块 导航配置；类别 config；类型 configuration）: 站点导航唯一数据源，本次将 Environments 平级分组内移为 User Guide 嵌套子分组并更名，是核心变更所在。
- `docs/user-guide/environments.md`（模块 用户指南；类别 docs；类型 documentation）: frontmatter title 同步更名，保持导航分组名与页面标题一致。
- `docs/user-guide/index.md`（模块 用户指南；类别 docs；类型 documentation）: User Guide 索引表格行更名并调整顺序，与导航结构保持一致。

关键符号：未识别

## 关键源码片段

### `docs/docs.json`

站点导航唯一数据源，本次将 Environments 平级分组内移为 User Guide 嵌套子分组并更名，是核心变更所在。

```jsonc
// docs/docs.json —— User Guide 标签页配置（合并 main 后的最终形态）
{
  "tab": "User Guide",
  "groups": [
    {
      "group": "User Guide",
      "root": "user-guide/index",
      "pages": [
        "user-guide/concepts",
        {
          // 既有的 Launch Script 嵌套子分组，作为本次改动的结构范本
          "group": "Launch Script",
          "pages": ["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",
        {
          // 新位置：Environments 由平级分组内移为嵌套子分组，并更名为 Agentic Environments
          // 保留原 root 与四个 connector 页面，页面 URL 全部不变
          "group": "Agentic Environments",
          "root": "user-guide/environments",
          "pages": [
            "user-guide/harbor",
            "user-guide/openenv",
            "user-guide/nemo-gym",
            "user-guide/verifiers"
          ]
        },
        "user-guide/cli-reference" // 仍保持在最后
      ]
    }
  ]
}
```

# 评论区精华

仅有维护者 Shi-Dong 的一条 APPROVE，评论为 "Thanks!"，无实质技术讨论。由于本 PR 完全按 issue #2409 要求执行，且为纯文档导航调整，范围小、无争议，也没有未解决的问题。

- 暂无高价值评论线程

# 风险与影响

- 风险：主要风险集中在两点：一是 docs/docs.json 作为站点导航唯一数据源，手工编辑存在 JSON 语法风险，但本次仅移动已有节点、键值未变，且 merge commit 已解决与 main 的冲突，站点构建可兜底；二是导航层级变化——Harbor、OpenEnv、Nemo-Gym、Verifiers 四个页面从顶级分组降为 User Guide 下的嵌套子分组，侧边栏多一层折叠，短期可能降低环境类文档的直接可见性，这是 issue 的预期效果。无 URL 变更，无代码回归、性能与安全风险。
- 影响：对用户：文档侧边栏结构变化，环境类页面入口由平级组变为 User Guide 下的折叠子组，查找路径多一层。对团队：后续新增环境类文档需按新的嵌套结构维护 docs/docs.json，信息架构与 Launch Script 子组统一。对系统：仅影响文档站导航渲染，无代码与部署影响，影响范围小。
- 风险标记：纯文档变更 , 导航层级加深影响可发现性 , 手动编辑 JSON 配置

# 关联脉络

- PR #2484 docs: add disaggregated RL rollout guide: 同样修改 docs/docs.json，与本 PR 在导航结构上有直接交互；两 PR 合入时需要处理同一配置文件的冲突（本 PR 的 merge commit 正是为此）。
- PR #2383 [readme]: rewrite the README: 文档整体结构与首页信息架构调整，与本 PR 同属文档信息架构收敛方向。
- PR #2411 docs: drop the Latest updates section from the homepage: 同为文档信息架构精简，与本 PR 的导航收敛目标一致。