GitHub Actions 自动部署 PRD¶
1. 文档目的¶
本文件用于定义当前仓库的 GitHub Actions 自动化构建与部署要求，作为后续 AI 或开发者统一执行的依据。
目标是让不同执行者在实现或修改文档部署能力时，能够遵循相同的结构、职责边界和质量标准。当前仓库的文档正文分散在各目录 README 中，MkDocs 通过符号链接接入，因此工作流必须覆盖 README、文档站点配置和部署工作流本身的变更。
本 PRD 面向 Recommender-Systems 仓库，同时保留可迁移性。迁移到其他仓库时，应保留“文档工程独立构建、正文源由目录 README 维护、GitHub Pages 发布”的边界。
2. 建设目标¶
需要为目标仓库补充一套独立、标准、可维护的 GitHub Actions 工作流，满足以下目标：
- 支持在 GitHub 上自动执行构建与部署流程。
- 支持静态文档站点的自动发布。
- 优先兼容 GitHub Pages。
- 工作流结构清晰，便于理解、维护和迁移。
- 触发范围覆盖
docs-site/、.github/workflows/以及目录 README 变更。 - 方案具备通用性，适合作为其他仓库的参考模板。
3. 适用范围¶
本 PRD 适用于以下场景：
- 静态文档站点自动构建与部署。
- 基于 GitHub 仓库的持续集成与持续发布。
- 将文档工程与自动部署解耦管理。
- 为其他 AI 提供统一的 GitHub Actions 实现约束。
本 PRD 不要求覆盖业务应用发布、容器编排、复杂多环境发布或自定义基础设施部署。
4. 总体要求¶
4.1 独立性¶
- GitHub Actions 部署方案应独立定义。
- 自动化流程应聚焦文档站点构建与部署，不应混入无关业务流程。
- 工作流职责应单一明确，避免一个文件承担过多不相关任务。
4.2 通用性¶
- 工作流设计不应绑定当前仓库的业务术语。
- 不应依赖当前项目特有目录以外的硬编码约束，除非这些约束属于文档站点通用结构。
- 输出结果应具备迁移到其他仓库的可复用性。
4.3 稳定性¶
- 应优先采用 GitHub 官方或社区稳定的 Action。
- 应尽量减少不必要的自定义脚本。
- 工作流应在常规仓库权限模型下可运行。
5. 工作流职责要求¶
自动化工作流至少应覆盖以下职责：
- 在代码变更后自动触发。
- 支持手动触发。
- 检出仓库代码。
- 准备运行环境。
- 安装文档构建依赖。
- 执行文档站点构建。
- 上传构建产物。
- 将静态站点部署到目标托管平台。
6. 触发策略要求¶
6.1 自动触发¶
- 工作流应支持在主分支更新后自动执行。
- 不应对主分支上的所有
push默认全量触发。 - 必须优先限制为仅在文档相关内容发生变化时触发，以减少无效运行。
- 应使用
paths或等价机制，将触发范围限制在文档源码、文档配置、文档部署工作流以及少量明确指定的文档入口文件。 - 当前仓库还必须包含
**/README.md与**/README.zh.md，因为算法和数据集正文维护在目录 README 中。 - 触发路径设计应体现文档工程边界清晰的原则。
6.2 手动触发¶
- 工作流应支持
workflow_dispatch。 - 手动触发能力用于调试、补发部署和人工验证。
6.3 触发控制¶
- 应考虑并发控制，避免重复部署互相覆盖。
- 若采用并发组，应保证行为可预测、语义清晰。
7. 构建要求¶
7.1 运行环境¶
- 应使用稳定、主流的运行环境版本。
- 环境准备步骤应清晰可读。
- 不应为了小幅优化而引入显著复杂度。
7.2 依赖安装¶
- 依赖安装方式应明确、稳定。
- 应使用
docs-site/requirements.txt作为文档工程自身的依赖清单，而不是依赖仓库外部隐式环境。 - 依赖来源和安装步骤应便于维护者理解。
7.3 构建执行¶
- 构建命令应直接、清晰、可复现。
- 构建失败时应能明确暴露问题，而不是静默跳过。
- 如构建工具支持严格模式，应优先考虑启用，以尽早发现文档问题。
- 当前仓库使用
mkdocs build --strict，工作目录为docs-site/。 - 构建时应允许 MkDocs 读取
docs-site/docs/下指向仓库 README 的符号链接。
8. 部署要求¶
8.1 部署目标¶
- 优先支持 GitHub Pages。
- 若后续切换到其他静态托管平台，整体流程应尽量容易迁移。
8.2 产物处理¶
- 构建产物应与源码职责分离。
- 应通过标准化步骤上传和发布产物。
- 不应把部署逻辑与文档源码组织方式过度耦合。
8.3 权限要求¶
- 工作流权限应遵循最小必要原则。
- 只授予构建与部署所需权限。
- 不应配置明显超出文档部署场景的高权限能力。
9. 可维护性要求¶
9.1 可读性¶
- 工作流文件命名应清晰。
- Job 与 Step 命名应语义明确。
- 维护者应能快速看懂每一步的职责。
- 当前推荐文件名为
.github/workflows/deploy-docs.yml。
9.2 可迁移性¶
- 工作流不应深度耦合某个具体仓库的业务逻辑。
- 迁移到其他项目时，应尽量只需少量改动。
9.3 可扩展性¶
- 允许未来增加预检查、链接校验、格式校验或多版本部署能力。
- 但本次不要求一次性堆叠复杂 CI/CD 能力。
10. 非功能要求¶
10.1 简洁性¶
- 方案应尽量简单直接。
- 不要为了“看起来完整”而引入过多无关步骤。
10.2 一致性¶
- 工作流命名风格、步骤组织方式和注释风格应统一。
- 自动化方案应与文档工程结构相匹配。
10.3 可靠性¶
- 对常见文档发布场景应具有稳定表现。
- 尽量避免脆弱的临时脚本或隐式依赖。
11. 交付物要求¶
执行该 PRD 时，至少应交付以下内容：
- GitHub Actions 工作流文件
- 清晰的构建步骤定义
- 清晰的部署步骤定义
- 与当前 README 作为内容源相匹配的触发规则
- 必要的权限配置
- 简要说明文件或注释
12. 验收标准¶
满足以下条件时，视为该任务完成：
- 仓库中存在独立的 GitHub Actions 工作流文件。
- 工作流可在主分支相关变更后自动触发。
- 工作流支持手动触发。
- 工作流能完成代码检出、环境准备、依赖安装与构建。
- 工作流能完成静态产物上传与部署。
- 部署目标优先兼容 GitHub Pages。
- 工作流结构清晰，便于维护者阅读与修改。
- 修改任意目录的
README.md或README.zh.md会触发文档构建。 - 工作流具备迁移到其他仓库复用的价值。
13. 实施约束¶
执行者在实现时应遵守以下约束：
- 不要把工作流写成仅适用于某个单一仓库的特殊脚本。
- 不要把与文档无关的 CI/CD 任务强行塞入同一工作流。
- 不要将工作流配置为任意代码变更都会触发部署。
- 不要漏掉 README 触发路径。
- 不要省略手动触发能力。
- 不要省略最基本的构建与部署链路。
- 不要引入明显超出需求范围的高复杂度设计。
14. 对执行者的明确指令¶
请基于本 PRD，为目标仓库设计并实现一套 GitHub Actions 自动构建与部署方案。实现要求如下：
- 聚焦静态文档站点构建与部署
- 支持主分支自动触发
- 支持手动触发
- 优先兼容 GitHub Pages
- 使用清晰、稳定、可维护的工作流结构
- 尽量减少项目特化逻辑
- 输出结果应具备复用价值
15. 期望结果¶
最终应得到一套职责明确、结构简洁、可自动运行、适合长期维护的 GitHub Actions 自动部署方案。
该方案应满足以下目的：
- 当前仓库可直接接入自动部署
- 未来其他仓库可复用同类实现
- 其他 AI 可基于同一标准继续生成或修改工作流
- 团队成员能够快速理解并维护