Skip to main content

P0问题预防CI测试套件文档

概述​

这是一个完整的CI测试套件，用于防止RFC文档项目中的P0级别问题再次出现。

测试内容​

1. 命名规范验证 (Naming Validation)​

  • 脚本: scripts/validate-naming.js
  • 功能:
    • 验证文件名是否符合命名规范
    • 检查大小写、分隔符、特殊字符
    • 跨语言文件名一致性
  • 运行: npm run test:p0:naming

2. 文件结构一致性 (Structure Consistency)​

  • 脚本: scripts/test-structure-consistency.js
  • 功能:
    • 检查docs和i18n目录的文件结构对称性
    • 确保所有语言版本有相同的文件列表
    • 检测缺失或多余的翻译文件
  • 运行: npm run test:p0:structure

3. ID唯一性检查 (ID Uniqueness)​

  • 脚本: scripts/test-id-uniqueness.js
  • 功能:
    • 扫描所有Markdown文件的frontmatter id字段
    • 检测重复的id
    • 验证id命名格式
  • 运行: npm run test:p0:id
  • 脚本: scripts/test-link-integrity.js
  • 功能:
    • 验证内部链接的目标文件是否存在
    • 检查锚点是否有效
    • 识别断链和错误的相对路径
  • 运行: npm run test:p0:links

5. 重复文件检查 (Duplicate Files)​

  • 脚本: scripts/test-duplicate-files.js
  • 功能:
    • 计算文件内容哈希值
    • 检测完全相同的重复文件
    • 识别命名变体（如1.Introduction.md vs 1-introduction.md）
  • 运行: npm run test:p0:duplicates

6. 占位符检查 (Placeholder Check)​

  • 脚本: scripts/test-placeholder-check.js
  • 功能:
    • 检测TODO、TBD、FIXME等占位符标记
    • 识别"待翻译"、"未完成"等中文占位符
    • 检查内容完整性（最小长度、段落数）
    • 检测空文件或仅有标题的文件
  • 运行: npm run test:p0:placeholders

使用方法​

本地运行​

运行所有测试​

npm run test:p0
# 或
./scripts/test-p0-issues.sh

运行单个测试​

npm run test:p0:naming
npm run test:p0:structure
npm run test:p0:id
npm run test:p0:links
npm run test:p0:duplicates
npm run test:p0:placeholders

即使测试失败也继续运行​

./scripts/test-p0-issues.sh --continue-on-error

查看帮助​

./scripts/test-p0-issues.sh --help

CI/CD集成​

GitHub Actions工作流​

测试套件已集成到 .github/workflows/p0-prevention.yml

触发条件:

  1. Pull Request: 当PR修改docs或i18n目录的Markdown文件时自动运行
  2. Push到主分支: 当代码推送到main/master分支时运行
  3. 定时任务: 每天UTC 00:00（北京时间08:00）自动运行
  4. 手动触发: 在GitHub Actions页面手动运行

工作流程:

  1. 并行运行6个测试作业
  2. 生成各项测试报告
  3. 汇总生成综合报告
  4. 上传报告为Artifacts（保留90天）
  5. 在PR中自动添加测试结果评论

阻止不合规提交​

  • 如果任何测试失败，PR将无法合并
  • CI状态检查会显示具体失败的测试项
  • 必须修复所有问题后才能通过检查

测试报告​

本地报告​

本地运行时，报告会保存在 test-reports/ 目录：

test-reports/
├── 命名规范验证_20260327_120530.txt
├── 文件结构一致性_20260327_120531.txt
├── ID唯一性检查_20260327_120532.txt
├── 链接完整性检查_20260327_120533.txt
├── 重复文件检查_20260327_120534.txt
└── 占位符检查_20260327_120535.txt

CI报告​

CI运行时：

  1. GitHub Step Summary: 在工作流运行页面查看摘要
  2. Artifacts: 下载完整的测试报告
  3. PR评论: 在PR页面自动添加测试结果评论

配置文件​

.p0-test-config.json​

测试套件的配置文件：

{
  "p0-prevention-tests": {
    "tests": {
      "naming": { "enabled": true, "severity": "error" },
      "structure": { "enabled": true, "severity": "error" },
      // ... 其他配置
    },
    "ci": {
      "failOnWarning": false,
      "failOnError": true
    }
  }
}

修改配置​

  • enabled: 启用/禁用特定测试
  • severity: error 或 warning
  • timeout: 测试超时时间（毫秒）
  • failOnWarning: CI是否因警告失败

常见问题修复​

命名规范问题​

# 自动修复命名问题（谨慎使用）
npm run validate:naming:fix

# 预览重命名
npm run rename:preview

# 应用重命名
npm run rename:apply

结构不一致​

手动添加缺失的文件或删除多余的文件，确保所有语言版本文件列表一致。

ID重复​

修改frontmatter中的id字段，确保每个id在整个项目中唯一。

断链​

修正链接路径或添加缺失的目标文件。

重复文件​

删除重复文件，只保留符合命名规范的版本。

占位符​

完善文档内容，移除所有占位符标记（如"待完成"、"待翻译"等）。

开发者指南​

添加新的测试​

  1. 在 scripts/ 目录创建新的测试脚本
  2. 添加到 .p0-test-config.json
  3. 在 p0-prevention.yml 添加新的job
  4. 更新 package.json 添加npm脚本
  5. 更新本文档

测试脚本规范​

  • 使用Node.js编写（.js）或Bash（.sh）
  • 成功退出码为0，失败为1
  • 输出清晰的报告到stdout
  • 包含统计信息和详细问题列表

性能考虑​

  • 并行执行: CI中6个测试并行运行，提高效率
  • 缓存: npm依赖使用缓存，加快安装速度
  • 增量检查: PR只检查变更的文件（部分测试）
  • 超时设置: 每个测试都有超时限制，防止hang

维护者信息​

  • 创建时间: 2026-03-27
  • 最后更新: 2026-03-27
  • 维护者: RFC文档翻译团队

相关文档​

License​

与主项目保持一致

Last updated on