跳转至

mcts-cpu-validate 文档站 GitHub Actions PRD

1. 目的

本 PRD 用来约束 mcts-cpu-validate 文档站的 GitHub Actions 构建与部署流程。

它只处理文档站，不处理训练、测试、打包或其他 CI 任务。职责要单一，这样后续维护时才能快速看懂哪一个工作流负责发布文档。

2. 项目背景

本项目的文档站部署目标已经确定为：

https://billzi2016.github.io/mcts-cpu-validate/

因此自动化流程的职责很明确：

  • 当文档相关内容变化时构建 docs-site/
  • 生成静态站点
  • 发布到 GitHub Pages

它不应该在每次代码改动时都触发，也不应该把无关任务混进来。

3. 本次建设目标

需要提供一套面向本项目的 GitHub Actions 工作流，满足下面要求：

  1. 支持主分支文档相关变更后的自动触发。
  2. 支持手动触发，便于补发部署和调试。
  3. 只对文档相关路径触发，避免无效运行。
  4. 构建 docs-site/ 下的 MkDocs 站点。
  5. 将产物部署到 GitHub Pages。
  6. 工作流命名、步骤命名和权限范围都要清楚。

4. 为什么需要单独的文档部署工作流

这个项目的主体是 Rust + Python 的训练系统，后续可能有：

  • Rust 构建
  • Python 测试
  • 数据校验
  • 工具脚本检查

如果把文档部署塞进这些流程里，会带来两个问题：

  • 文档问题和代码问题混在一起，不容易定位失败原因。
  • 只改文档时也会跑一堆无关任务，浪费时间。

因此文档部署工作流必须独立。

5. 触发范围

5.1 自动触发

主分支 push 时，只在下面这些路径变化时触发：

  • docs-site/**
  • .github/workflows/** 中与文档站相关的工作流
  • 根目录 README.md
  • 根目录 README.zh.md
  • CONFIGURATION.md
  • STEP_BY_STEP_GUIDE.md
  • data/README.md

这样设计的原因是：这些文件会直接影响文档站内容或文档站部署行为。

5.2 手动触发

必须支持 workflow_dispatch。这样在下面几种情况可以直接人工触发：

  • 首次开通 GitHub Pages 后补发
  • 调整主题或导航后复验
  • 仅修改仓库设置但未改源码时重新部署

5.3 并发控制

需要设置并发组，避免连续推送时多个部署互相覆盖。旧运行应允许被新运行取消，这样最终线上内容和最新提交保持一致。

6. 构建输入与输出

6.1 输入

构建输入包括：

  • 仓库源码
  • docs-site/ 下的 MkDocs 配置和页面
  • 通过 symlink 接入的仓库现有 Markdown

6.2 输出

构建输出是一个可部署到 GitHub Pages 的静态站点目录，通常是 site/。

对维护者来说，判断输出是否正常，至少要看三件事：

  1. 构建阶段没有因为链接、导航或缺页失败。
  2. 站点首页能打开。
  3. 中英文切换都能进入对应页面。

7. 运行环境要求

7.1 Python 环境

MkDocs 是 Python 工具，因此工作流需要安装稳定的 Python 版本，并基于 docs-site/ 自己的依赖清单安装依赖。

7.2 依赖来源

依赖必须来自文档工程自己的配置，而不是假设 GitHub runner 已经有某个全局环境。

7.3 构建命令

构建命令必须直接、稳定、可读。失败时应明确报错，不要静默跳过。

8. GitHub Pages 部署要求

8.1 部署目标

部署目标固定为 GitHub Pages，对应地址：

https://billzi2016.github.io/mcts-cpu-validate/

8.2 权限

工作流权限使用最小必要集合。通常只需要：

  • 读取仓库内容
  • 写入 Pages 部署产物
  • 写入 id-token 以完成官方 Pages 部署流程

8.3 产物职责分离

源码和构建产物要分开。工作流应上传构建结果，再部署该产物，而不是把生成目录反向提交回仓库。

9. 与本项目文档结构的耦合边界

该工作流允许依赖本项目的文档结构事实，但只能依赖稳定边界，不应写成脆弱脚本。

可以依赖的事实包括：

  • 文档工程位于 docs-site/
  • 站点使用 MkDocs
  • 双语页面位于 docs-site/docs/zh/ 和 docs-site/docs/en/
  • 根目录若干 Markdown 会被站点复用

不应依赖的东西包括：

  • 某个临时文件名
  • 某个开发者个人目录
  • 只有当前一次提交才成立的路径习惯

10. 可维护性要求

工作流文件要让维护者一眼看懂：

  • 什么时候触发
  • 用什么环境
  • 从哪里安装依赖
  • 执行什么构建命令
  • 如何发布到 Pages

步骤名不要写成模糊词，例如 build、deploy2、misc 这种后续很难维护。

11. 验收标准

满足下面条件视为本 PRD 对应工作流完成：

  1. 仓库中存在独立的文档部署工作流文件。
  2. 工作流支持 workflow_dispatch。
  3. 工作流只在文档相关路径变化时自动触发。
  4. 工作流能安装文档站依赖并构建 MkDocs 站点。
  5. 工作流能把产物部署到 GitHub Pages。
  6. 工作流具备并发控制。
  7. 权限范围符合最小必要原则。

12. 对执行者的明确要求

执行该 PRD 时，必须遵守下面这些要求：

  • 工作流只负责文档站。
  • 不把项目测试或训练任务塞进文档部署流程。
  • 自动触发范围要收敛到文档相关文件。
  • 产物发布使用 GitHub Pages 标准链路。
  • 对读者可见的文档地址以 https://billzi2016.github.io/mcts-cpu-validate/ 为准。