用途
GitHub Actions Pipeline Debugger 是一个专注于 CI/CD 诊断的技能，定位为专家级流水线诊断器。它专门读取失败的 GitHub Actions 原始日志，识别崩溃或失败的根因，并输出修复流水线所需的精确 YAML 或代码变更。
主要能力
- 日志摄取与脱敏：分析提供的 GitHub Actions 工作流日志（通常为导出的原始文本文件或直接粘贴）。关键安全要求：用户或智能体必须在粘贴或上传前，对日志中所有敏感凭据、密钥、令牌、私钥和内部系统路径进行脱敏。
- 上下文映射：将失败点与 .github/workflows/*.yml 定义中的具体步骤和作业进行交叉引用。
- 根因分析：判断失败是否源于以下原因：密钥缺失或配置错误（${{ secrets.API_KEY }}）；Node/Python/操作系统环境版本不匹配；不稳定的测试或超时限制；run: 块中 bash 脚本的语法错误；无效的 action 版本或已弃用的 action。
- 解决方案建议：提供需要修改的 .yml 文件或底层脚本的直接 diff。
使用方式
当 GitHub Actions 工作流意外失败且错误日志冗长、晦涩或具有误导性时使用；调试 CI 中的依赖不匹配错误、密钥缺失、缓存问题或运行器环境问题时使用；通过识别工作流步骤中的瓶颈来优化缓慢的流水线时使用；更新和现代化已弃用的 action 或工作流语法时使用。
最佳实践包括：同时审查工作流定义（.yml 文件）和失败日志以确保诊断准确；检查 action 版本，许多失败源于旧第三方 action（如 actions/checkout@v2）中已弃用的运行时版本（如 Node.js 16），应检查已安装运行器要求和支持的 action 发布版本，核实上游变更，并固定经过审查的完整提交 SHA，不要假设历史 v4 示例就是最新版；进行权限审计，确保工作流具有正确权限，若尝试写入仓库、包或部署环境则需阻止；关注可复现性，若测试在 CI 中失败但在本地通过，应调查时区、无头浏览器状态、内存限制或并行执行竞态条件等环境差异。
示例
示例 1：修复已弃用的 Node.js action 版本错误。失败日志显示 Node.js 16 actions 已弃用，建议更新为 Node.js 20。建议的修复 diff 为将 actions/checkout@v2 改为 actions/checkout@v4。
示例 2：诊断并修复缺失的仓库密钥。失败日志显示部署需要 API Key，进程以代码 1 退出。建议的修复 diff 为在部署步骤中添加 env 块，设置 DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}。
精确运行绑定
记录仓库、运行 ID、尝试次数、事件、head SHA、运行器和失败步骤。从同一提交读取工作流和引用的脚本，而不仅仅是当前 main 分支。区分源错误、权限、缺失工具和观察超时。绝不为获得绿色徽章而削弱测试或必需检查。
安全与安全说明
凭据暴露与原始日志脱敏：在任何情况下，都不得在未事先脱敏的情况下处理包含未屏蔽密钥、私有 URL、部署目标或令牌的原始日志。始终确保用户或智能体在摄取前脱敏所有敏感信息。
干跑模式：当建议修改工作流中的 bash 脚本步骤时，确保建议尽可能添加 --dry-run 或暂存执行等标志，以防止调试期间对下游环境产生意外副作用。
限制
该技能无法安全读取仓库密钥，只能根据日志中关于未定义环境变量或认证失败的报错来推断密钥缺失或格式错误。它无法自行执行 GitHub action 来测试修复，验证需要将建议的修复推送到仓库并触发工作流运行。网络相关的瞬时故障（如包注册表临时宕机）若未仔细分析，可能被错误诊断为结构性工作流问题。
常见陷阱
忽略瞬时故障：将临时网络中断或注册表宕机（如 npm 或 pip 安装错误）误认为实际的代码或配置缺陷。重新运行前检查证据：部署或发布步骤可能重复副作用。重新运行通过并不能抹去可复现的确定性缺陷。
硬编码令牌：通过将密钥或 API 令牌直接硬编码到 YAML 文件中来修复认证错误，而不是使用 GitHub Secrets（${{ secrets.SECRET_NAME }}）。
忽视缓存副作用：忘记过时的缓存键可能导致损坏的依赖持续被加载。如果依赖安装失败，尝试在绕过 actions 缓存的情况下运行作业。
相关技能
@devops-troubleshooter：通用 DevOps 和基础设施问题解决。 @cicd-automation-workflow-automate：用于从零创建新的 CI/CD 流水线。