智能 PR 验证工作流系统使用指南¶

本文档介绍了新实现的智能 PR 验证工作流系统，这是一套符合生产级别标准的自动化解决方案。

🎯 系统概览¶

我们的智能 PR 验证系统包含三个核心工作流：

🔍 智能 PR 验证与预览 (pr-preview.yml) - 智能检测文件变更并自动构建预览
🚀 生产环境部署 (deploy-docs.yml) - 增强的生产部署，包含自动清理功能
🧹 清理 PR 预览环境 (cleanup-pr-preview.yml) - PR 关闭时自动清理预览资源

🔍 智能文件检测机制¶

会触发构建的文件类型¶

当你的 PR 包含以下文件变更时，系统会自动触发文档构建：

文件类型	模式	说明
文档内容	`docs/`	所有文档目录下的文件
配置文件	`mkdocs.yml`	MkDocs 主配置文件
依赖配置	`pyproject.toml`	Python 项目依赖配置
主题覆盖	`overrides/`	自定义主题文件
工作流文件	`.github/workflows/`	GitHub Actions 工作流
首页文档	`README.md`	项目首页文档

会跳过构建的文件类型¶

以下文件变更不会触发文档构建，提高效率：

文件类型	模式	说明
课程作业	`class0/`	课程作业和练习文件
主程序	`main.py`	主要 Python 程序文件
草稿内容	`drafts/`	草稿和临时文档
配置文件	`.gitignore`, `.mailmap`, `.markdownlint.yaml`, `.python-version`	各种配置文件
锁定文件	`uv.lock`	依赖锁定文件
问题报告	`issues/`	问题报告和讨论

安全策略¶

对于未知文件类型，系统默认触发构建，确保不遗漏任何可能影响文档的变更。

🚀 PR 工作流程¶

1. 创建 Pull Request¶

当你创建 PR 后，智能检测系统会立即开始工作：

🔍 智能文件变更检测
  ├── 分析变更的文件列表
  ├── 应用检测模式
  └── 决定是否需要构建

2. 自动状态通知¶

系统会在你的 PR 中自动添加状态评论：

开始构建¶

## 📋 PR 预览构建状态

🔄 **正在构建中...**

📁 **检测到的相关文件变更:**

docs/new-guide.md mkdocs.yml

⏳ 请稍候，文档正在构建和部署中...

构建成功¶

## 📋 PR 预览构建状态

✅ **构建成功！**

🌐 **预览链接:** [查看预览网站](https://your-username.github.io/cs4ncu/pr-preview/pr-123/)

🎉 恭喜！您的文档变更已成功构建并部署到预览环境。

智能跳过¶

## 📋 PR 预览构建状态

⏭️ **智能跳过构建**

📁 **检测到的文件变更:**

class0/assignment.py main.py

🎯 **跳过原因:** 本次变更不涉及文档相关文件，无需构建预览。

3. 严格构建验证¶

当触发构建时，系统执行严格的质量检查：

📝 严格模式构建: 使用 --strict 确保无警告
📊 构建质量检查: 验证必要文件生成、统计文件数量
🔒 环境隔离验证: 检查是否包含开发环境残留
🌐 独立预览部署: 部署到 pr-preview/pr-{number}/ 子目录

4. 预览环境访问¶

构建成功后，你可以通过以下链接访问预览：

https://{用户名}.github.io/{仓库名}/pr-preview/pr-{PR编号}/

例如：https://ywh555hhh.github.io/cs4ncu/pr-preview/pr-123/

🧹 自动清理机制¶

PR 关闭时清理¶

当 PR 被关闭或合并时，系统会：

立即清理 PR 对应的预览环境
删除目录 pr-preview/pr-{number}/
通知确认 在 PR 中添加清理完成通知

定期清理¶

生产部署时，系统会：

扫描所有预览环境
检查对应 PR 状态
清理已关闭 PR 的预览

🔧 故障排除¶

构建失败¶

如果构建失败，检查以下常见问题：

Markdown 语法错误

# 本地验证
uv run mkdocs build --strict

链接错误
检查相对路径是否正确
确认引用的文件是否存在
图片路径错误
验证图片文件是否提交
检查路径大小写是否正确

预览环境访问问题¶

404 错误: 等待 2-3 分钟让 GitHub Pages 生效
样式问题: 检查 base_url 配置是否正确
缓存问题: 尝试强制刷新浏览器 (Ctrl+F5)

📈 性能优化¶

智能缓存¶

系统使用多层缓存优化：

依赖缓存: 缓存 Python 虚拟环境
构建缓存: 区分生产和预览环境
并发控制: 同一 PR 多次推送只保留最新构建

资源管理¶

存储优化: 自动清理过期预览环境
构建优化: 跳过不相关文件变更
网络优化: 预览环境独立部署，不影响生产

🛡️ 安全考虑¶

权限控制¶

工作流使用最小权限原则：

permissions:
  contents: read      # 读取仓库内容
  pull-requests: write # 写入 PR 评论
  pages: write        # 部署到 GitHub Pages
  id-token: write     # 用于环境认证

环境隔离¶

完全独立: 预览环境与生产环境完全隔离
路径隔离: 使用 pr-preview/ 前缀防止冲突
清理机制: 确保敏感信息不会残留

💡 最佳实践¶

为贡献者¶

小而频繁的提交: 更容易触发增量构建
本地预览: 推送前先本地验证 mkdocs serve
描述性提交信息: 帮助 reviewers 理解变更
关注构建状态: 及时修复构建问题

为维护者¶

及时审查: 预览环境让审查更直观
合并策略: 使用 Squash merge 保持历史清晰
定期维护: 检查自动清理是否正常工作

🔗 相关链接¶

测试新的流程

🤖 本文档由智能 PR 验证工作流系统自动维护