name: dart-ci description: DART CI/CD 故障排除 - GitHub Actions，缓存调试，平台特定失败
<!-- AUTO-GENERATED FILE - DO NOT EDIT MANUALLY -->
<!-- Source: .claude/skills/dart-ci/SKILL.md -->
<!-- Sync script: scripts/sync_ai_commands.py -->
<!-- Run pixi run sync-ai-commands to update -->
DART CI/CD 故障排除
在调试 CI 失败或使用 GitHub Actions 时加载此技能。
快速命令
# 监控 PR 检查
gh pr checks <PR_NUMBER>
gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast
# 查看运行详情
gh run list --branch <BRANCH> -e pull_request -L 20
gh run watch <RUN_ID> --interval 30
gh run view <RUN_ID> --json status,conclusion,url
# 调试失败
gh run view <RUN_ID> --job <JOB_ID> --log-failed
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'
# 重新运行失败任务
gh run rerun <RUN_ID> --failed
gh run rerun <RUN_ID> --job <DATABASE_ID>
完整文档
完整 CI/CD 指南：docs/onboarding/ci-cd.md
常见失败模式
| 失败类型 | 解决方案 |
|---|---|
| 格式化失败 | pixi run lint 然后推送 |
| Codecov 补丁失败 | 为未覆盖行添加测试 |
| FreeBSD RTTI 失败 | 使用类型枚举 + static_cast 而不是 dynamic_cast |
| macOS ARM64 段错误 | 替换 alloca()/VLAs 为 std::vector<T> |
| RTD 构建失败 | 使用防御性 .get(key, default) 模式 |
| gz-physics 失败 | 使用 pixi run -e gazebo test-gz 重现 |
工作流架构
| 工作流 | 目的 | 平台 |
|---|---|---|
ci_lint.yml |
格式化 | Ubuntu |
ci_ubuntu.yml |
构建 + 测试 + 覆盖率 | Ubuntu |
ci_macos.yml |
构建 + 测试 | macOS |
ci_windows.yml |
构建 + 测试 | Windows |
ci_freebsd.yml |
构建 + 测试 (VM) | FreeBSD |
ci_gz_physics.yml |
Gazebo 集成 | Ubuntu |
快速迭代循环
- 从任务日志中识别失败步骤
- 使用相同构建切换本地重现
- 修复最小的失败测试
- 推送并监控：
gh run watch <RUN_ID>
缓存
- sccache/ccache 减少构建时间 50-70%
- 在工作流日志中检查缓存命中率
- 如有需要，通过更改缓存键强制缓存失效
预期 CI 时间
| 平台 | 缓存 | 无缓存 |
|---|---|---|
| Ubuntu | 20-30 分钟 | 45-60 分钟 |
| macOS | 15-25 分钟 | 30-45 分钟 |
| Windows | 15-20 分钟 | 25-35 分钟 |