执行摘要

• 一句话：将 CI 文档目录从 docs/ci/ 迁移到 docs/developer/ci/，对齐开发者导航结构。
• 推荐动作：这是一个值得精读的、高质量的重构 PR。虽然变更规模不小（33 个文件），但其核心是高度机械和一致的路径替换操作，逻辑清晰。PR 审查过程严谨，通过自动化工具和人工审核确保了变更的完整性和正确性。对于维护文档结构和代码-文档映射规范的团队来说，这是一个很好的实践范例，展示了如何安全、彻底地进行大规模的目录重构。

功能与动机

根据 PR body，动机是为了让源码结构与文档站点的导航层级保持一致。文档站点已经将 CI 内容展示在 Developer Guide 下，但源码树中 CI 文档仍作为顶层文件夹存在。此次对齐为未来仅面向开发者的文档提供了统一的父目录，且不改变 CI 指南的含义，同时通过永久重定向保留了所有现有的 /ci/* URL。

实现拆解

1. 文件搬迁：使用 git mv 将 docs/ci/ 目录下的七个 Markdown 文件（如 00-stage.md, 01-label.md 等）移动到 docs/developer/ci/ 目录。这是变更的核心物理动作。
2. 导航与重定向配置：更新 docs/docs.json 文件。在 Developer Guide 标签页的 CI 分组中，将所有页面路径从 ci/* 更新为 developer/ci/*。同时，在 redirects 数组中为所有七个移动的页面添加了永久重定向规则（permanent: true），将旧的 /ci/* 路径映射到新的 /developer/ci/* 路径。
3. 同步内部引用：更新所有依赖于这些文档路径的引用。这包括：
   • docs/developer/contributor-guide.md 和 docs/developer/versions.md 等文档中的内部链接和文本描述。
   • tests/ci/metric_history/*.py 和 tests/ci/test/test_stage_selection.py 等测试文件中以 # doc-dev: 开头的哨兵注释，这些注释将代码模块与对应的文档页面关联起来。
   • .github/workflows/*.yml 文件和 docker/Dockerfile 中指向这些文档的注释链接。

关键文件：

• docs/docs.json（模块 文档配置；类别 config；类型 configuration）: 这是文档站点的导航和重定向配置文件，包含了本次变更的核心配置更新：页面路径重命名和永久重定向规则的添加。
• tests/ci/test/test_stage_selection.py（模块 阶段选择测试；类别 test；类型 test-coverage）: 这是路径敏感的测试文件，其变更展示了如何同步更新测试数据中的文档路径引用，确保了 CI 策略测试的正确性。
• tests/ci/metric_history/constraints.py（模块 约束模块；类别 test；类型 test-coverage）: 展示了代码-文档映射哨兵注释（doc-dev）的更新，这是维护代码与文档关联性的重要实践。

关键符号：未识别

关键源码片段

tests/ci/test/test_stage_selection.py

这是路径敏感的测试文件，其变更展示了如何同步更新测试数据中的文档路径引用，确保了 CI 策略测试的正确性。

# 在测试函数 test_docs_tooling_and_cpu_only_tests_skip_every_gpu_stage 中
# 模拟的变更文件路径被更新，以匹配新的文档位置
changed_files = (
    # 之前 : ChangedFile("M", ("docs/ci/00-stage.md",)),
    ChangedFile("M", ("docs/developer/ci/00-stage.md",)), # 更新为新路径
    # ...
)
# ...
# 在测试函数 test_cli_publishes_all_gpu_stages_for_docs_diff 中
# 写入测试数据的路径也被同步更新
# 之前 : diff_path.write_bytes(b"M\0docs/ci/00-stage.md\0")
diff_path.write_bytes(b"M\0docs/developer/ci/00-stage.md\0") # 更新为新路径

tests/ci/metric_history/constraints.py

展示了代码-文档映射哨兵注释（doc-dev）的更新，这是维护代码与文档关联性的重要实践。

# doc-dev: docs/developer/ci/03-metric-history-gate.md
# 这个注释标记了当前代码模块对应的文档页面。
# 在目录重构后，路径被更新以指向新的位置。
# 确保了代码与文档的映射关系保持准确。
"""The band constraint for the CI regression gate.
​
* A constraint decides whether one extracted scalar `cur` passes against a
  reference `ref` -- the mean of the trusted baseline for the historical
  gate.
# ... (模块的文档字符串)

评论区精华

Claude[bot] 的自动审查是主要的讨论内容，它确认了变更的机械性和正确性。其结论是："Nothing blocking. The comments below are optional suggestions." 它指出这是一个直接的、机械性的路径重命名（docs/ci/* → docs/developer/ci/*），并匹配了重定向和所有引用更新。审查中仅发现了一个微小的遗留问题：在 docs/developer/contributor-guide.md 第 36 行有一个过时的 docs/ci internals 注释，但这是一个仅影响外观的小问题，不影响功能。最终由 Shi-Dong 和 yueming-yuan 两位人工审核员批准合并。

• CI 文档目录重构的审查确认 (style): 审查认为变更无阻塞性问题，建议可合并。它确认了实现的完整性和正确性。

风险与影响

• 风险：风险极低。这是一个纯粹的文档路径重构和引用同步变更，不涉及任何业务逻辑、代码路径、认证、权限或数据处理的改动。主要风险在于：
  1. 链接断裂：虽然已为所有七个页面添加了永久重定向，但如果项目中有未更新的外部链接或书签，它们仍会通过重定向正常工作。内部引用（如测试中的 doc-dev 注释）已全部更新。
  2. 测试覆盖：测试文件中的路径引用（例如 test_stage_selection.py）已同步更新，确保了路径敏感测试的正确性。
• 影响：对用户和系统的影响范围有限且正面：
  1. 用户影响：开发者和贡献者访问 CI 文档时，URL 将从 /ci/* 统一变为 /developer/ci/*，与文档导航栏的展示路径一致，提升了用户体验和信息架构的一致性。旧 URL 通过永久重定向保持兼容，不会立即失效。
  2. 系统影响：文档站点的导航结构变得更加清晰和规范。代码库中关于“代码-文档”映射的元数据（doc-dev 哨兵注释）被准确维护，有助于未来的开发和维护。
  3. 团队影响：为团队建立了更清晰的文档组织规范，便于未来在 developer/ 目录下添加更多开发者专属文档。
     - 风险标记：文档路径重构

关联脉络

• 暂无明显关联 PR