Skip to content

homemade-risc-v-64-vector-linux-emulator 文档站 GitHub Actions 部署 PRD

1. 文档目的

本文件定义当前模拟器仓库的 MkDocs 文档站自动检查、构建和 GitHub Pages 部署要求。

目标是在不触碰模拟器构建、Linux 产物或宿主网络的前提下，对双语 symlink 文档树执行严格验证，并把可复现静态站点部署到本仓库的 GitHub Pages。

本 PRD 绑定 billzi2016/homemade-risc-v-64-vector-linux-emulator。工作流可以保持清晰可迁移，但触发路径、站点目录和 Pages 目标必须以本项目为准。

2. 建设目标

需要为目标仓库补充一套独立、标准、可维护的 GitHub Actions 工作流，满足以下目标：

  • 支持在 GitHub 上自动执行构建与部署流程。
  • 支持静态文档站点的自动发布。
  • 部署到当前 public 仓库的 GitHub Pages。
  • 在构建前验证中文/英文入口命名、导航完整性和相对 symlink 安全性。
  • 使用 docs-site/requirements.lock 中锁定的依赖构建 docs-site/mkdocs.yml。
  • 工作流结构清晰，便于理解、维护和迁移。
  • 方案具备通用性，适合作为其他仓库的参考模板。

3. 适用范围

本 PRD 仅覆盖以下场景：

  • README.md、AGENTS.md、specs/** 或 docs-site/** 变化后的文档构建。
  • 文档 PR 的严格构建验证。
  • main 分支文档变更后的 GitHub Pages 部署。
  • 人工 workflow_dispatch 的重建和补发。

本 PRD 不运行模拟器、不下载 OpenSBI/Linux/rootfs、不创建 TAP、不执行项目发布，也不把文档部署权限用于代码或 Release 写入。

4. 总体要求

4.1 独立性

  • GitHub Actions 部署方案应独立定义。
  • 自动化流程应聚焦文档站点构建与部署，不应混入无关业务流程。
  • 工作流职责应单一明确，避免一个文件承担过多不相关任务。
  • 工作流文件固定为 .github/workflows/docs-pages.yml；除该平台必需文件外，配置、依赖和校验脚本都收敛在 docs-site/。

4.2 通用性

  • 工作流必须明确使用 docs-site/、项目权威 Markdown 和 GitHub Pages 环境。
  • 通用步骤可复用，但不得以通用性为由使用宽泛 push 触发或跳过本项目 symlink 检查。

4.3 稳定性

  • 应优先采用 GitHub 官方或社区稳定的 Action。
  • 应尽量减少不必要的自定义脚本。
  • 工作流应在常规仓库权限模型下可运行。

5. 工作流职责要求

自动化工作流至少应覆盖以下职责：

  • 在代码变更后自动触发。
  • 支持手动触发。
  • 检出仓库代码。
  • 准备运行环境。
  • 安装文档构建依赖。
  • 验证所有文档 symlink 是相对链接、目标存在且解析后仍位于仓库内。
  • 验证 docs-site/docs/zh/ 只包含 .zh.md Markdown 入口，docs-site/docs/en/ 只包含 .en.md Markdown 入口。
  • 执行文档站点构建。
  • 上传构建产物。
  • 将静态站点部署到目标托管平台。

6. 触发策略要求

6.1 自动触发

  • 工作流应支持在主分支更新后自动执行。
  • 不应对主分支上的所有 push 默认全量触发。
  • 必须优先限制为仅在文档相关内容发生变化时触发，以减少无效运行。
  • 应使用 paths 或等价机制，将触发范围限制在文档源码、文档配置、文档部署工作流以及少量明确指定的文档入口文件。
  • 触发路径设计应体现文档工程边界清晰的原则。
  • 自动部署触发范围固定包含 README.md、AGENTS.md、specs/**、docs-site/** 和 .github/workflows/docs-pages.yml。
  • Pull Request 可以执行验证构建，但不得部署 Pages；只有 main 的受控 push 或人工触发可以部署。

6.2 手动触发

  • 工作流应支持 workflow_dispatch。
  • 手动触发能力用于调试、补发部署和人工验证。

6.3 触发控制

  • 应考虑并发控制，避免重复部署互相覆盖。
  • 若采用并发组，应保证行为可预测、语义清晰。
  • Pages 部署使用单一并发组；新提交可以取消尚未开始部署的旧构建，但不得中断已经进入不可安全取消阶段的发布。

7. 构建要求

7.1 运行环境

  • 应使用稳定、主流的运行环境版本。
  • 环境准备步骤应清晰可读。
  • 不应为了小幅优化而引入显著复杂度。
  • 使用 GitHub 托管的稳定 Linux runner，确保仓库内相对 symlink 按 Linux 语义检出和解析。

7.2 依赖安装

  • 依赖安装方式应明确、稳定。
  • 应使用文档工程自身的依赖清单，而不是依赖仓库外部隐式环境。
  • 依赖来源和安装步骤应便于维护者理解。
  • Python、MkDocs、Material 和 i18n 插件版本必须锁定，禁止每次 CI 隐式安装不受控最新版本。

7.3 构建执行

  • 构建命令应直接、清晰、可复现。
  • 构建失败时应能明确暴露问题，而不是静默跳过。
  • 如构建工具支持严格模式，应优先考虑启用，以尽早发现文档问题。
  • 固定构建入口为从仓库根目录执行 mkdocs build --strict --config-file docs-site/mkdocs.yml。
  • 构建前必须运行项目自有 symlink/导航检查；检查失败不得继续上传产物。

8. 部署要求

8.1 部署目标

  • 固定支持当前仓库的 GitHub Pages。
  • 若后续切换到其他静态托管平台，整体流程应尽量容易迁移。

8.2 产物处理

  • 构建产物应与源码职责分离。
  • 应通过标准化步骤上传和发布产物。
  • 不应把部署逻辑与文档源码组织方式过度耦合。
  • 只上传 MkDocs 生成的静态 site/ 目录，不上传源码、构建缓存、Linux 镜像或仓库其他文件。

8.3 权限要求

  • 工作流权限应遵循最小必要原则。
  • 只授予构建与部署所需权限。
  • 不应配置明显超出文档部署场景的高权限能力。
  • 构建使用 contents: read；部署仅增加 pages: write 与 id-token: write。不得授予 contents: write、packages: write 或仓库管理权限。
  • Pages 部署 Job 必须绑定 GitHub github-pages environment，并暴露最终页面 URL。

8.4 Action 供应链约束

  • 优先使用 GitHub 官方 checkout、Pages 配置、artifact 上传和 Pages 部署 Action。
  • Action 必须锁定经审查的稳定主版本或完整 commit SHA；版本升级属于需验证的独立变更。
  • 禁止从未审查的第三方 Action 执行仓库写入或部署。

9. 可维护性要求

9.1 可读性

  • 工作流文件命名应清晰。
  • Job 与 Step 命名应语义明确。
  • 维护者应能快速看懂每一步的职责。

9.2 可迁移性

  • 工作流应清楚体现当前仓库的文档边界；迁移时必须显式修改仓库名、触发路径和导航校验，不假装零配置通用。

9.3 可扩展性

  • 允许未来增加预检查、链接校验、格式校验或多版本部署能力。
  • 但本次不要求一次性堆叠复杂 CI/CD 能力。

10. 非功能要求

10.1 简洁性

  • 方案应尽量简单直接。
  • 不要为了“看起来完整”而引入过多无关步骤。

10.2 一致性

  • 工作流命名风格、步骤组织方式和注释风格应统一。
  • 自动化方案应与文档工程结构相匹配。

10.3 可靠性

  • 对常见文档发布场景应具有稳定表现。
  • 尽量避免脆弱的临时脚本或隐式依赖。

11. 交付物要求

执行该 PRD 时，至少应交付以下内容：

  • GitHub Actions 工作流文件
  • 清晰的构建步骤定义
  • 清晰的部署步骤定义
  • 与文档工程相匹配的触发规则
  • 必要的权限配置
  • symlink、语言后缀和严格构建检查
  • GitHub Pages environment 与部署 URL 输出
  • 简要说明文件或注释

12. 验收标准

满足以下条件时，视为该任务完成：

  1. 仓库中存在独立的 GitHub Actions 工作流文件。
  2. 工作流可在主分支相关变更后自动触发。
  3. 工作流支持手动触发。
  4. 工作流能完成代码检出、环境准备、依赖安装与构建。
  5. 工作流能完成静态产物上传与部署。
  6. 部署目标优先兼容 GitHub Pages。
  7. 工作流结构清晰，便于维护者阅读与修改。
  8. 工作流具备迁移到其他仓库复用的价值。
  9. Pull Request 只验证不部署，main 文档变更才触发部署。
  10. 任何失效、绝对、循环或越过仓库根目录的 symlink 都会使构建失败。
  11. GitHub Pages 显示顶部语言切换、左侧导航，中文和英文 URL 可稳定访问。
  12. 工作流没有模拟器运行、外部镜像下载或宿主网络修改步骤。

13. 实施约束

执行者在实现时应遵守以下约束：

  • 不要把项目文档部署写成与当前目录和安全规则脱节的通用占位脚本。
  • 不要把与文档无关的 CI/CD 任务强行塞入同一工作流。
  • 不要将工作流配置为任意代码变更都会触发部署。
  • 不要省略手动触发能力。
  • 不要省略最基本的构建与部署链路。
  • 不要引入明显超出需求范围的高复杂度设计。
  • 不要跳过 symlink 校验，不要跟随仓库外链接，不要复制权威 Markdown 到构建目录冒充修复。

14. 对执行者的明确指令

请基于本 PRD，为目标仓库设计并实现一套 GitHub Actions 自动构建与部署方案。实现要求如下：

  • 聚焦静态文档站点构建与部署
  • 支持主分支自动触发
  • 支持手动触发
  • 优先兼容 GitHub Pages
  • 使用 docs-site/ 的锁定依赖和严格构建入口
  • 验证 zh/、en/ 目录下的 .zh.md/.en.md 与相对 symlink
  • 使用最小 Pages 权限，PR 不部署
  • 使用清晰、稳定、可维护的工作流结构
  • 尽量减少项目特化逻辑
  • 输出结果应具备复用价值

15. 期望结果

最终应得到一套服务当前模拟器文档站、严格验证双语 symlink、最小权限部署 GitHub Pages且适合长期维护的自动化方案。

该方案应满足以下目的：

  • 当前仓库可直接接入自动部署
  • 未来其他仓库可复用同类实现
  • 其他 AI 可基于同一标准继续生成或修改工作流
  • 团队成员能够快速理解并维护