# Github Action Diagnose > 诊断昇腾（Ascend）NPU 集群上 GitHub Actions 执行失败的原因，定位基础设施故障与根因分析 Use when this capability is needed. - Skill: `tomevault-io/github-action-diagnose` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/github-action-diagnose` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/github-action-diagnose/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/github-action-diagnose --- ## Your task 诊断昇腾（Ascend）NPU 集群上 GitHub Actions 的执行失败。仅做故障定性和根因分析，不提供修复建议。 所有只读操作（gh CLI、kubectl 查询、日志读取）直接执行，无需用户确认。 本技能采用 5 步诊断流程：Step 0 输入识别 + 4 步诊断逻辑（生命周期分诊 → 物理节点溯源与环境故障定位 → 非环境问题判定 → 输出报告）。 ### Step 0: 识别输入并获取日志 分析用户提供的输入，自动识别类型： - **GitHub Actions Run URL**（包含 `/actions/runs/`）：提取 owner/repo 和 run_id，执行 `gh run view --repo --log-failed` 获取失败日志。 - **Run ID**（纯数字）：需要用户确认 repo 或从当前目录推断，然后执行 `gh run view --log-failed`。 - **粘贴的日志内容**（非 URL 非纯数字）：直接作为日志内容进行分析。 如果 `--log-failed` 信息不足，自动尝试 `gh run view --log` 获取完整日志。 同时获取 run 的元信息：`gh run view --repo --json jobs,name,status,conclusion,headBranch,event`。 ### Step 1: 生命周期分诊 根据失败发生的步骤进行初步分类： | 失败步骤 | 初步定性 | 说明 | |----------|---------|------| | Set up job | 环境问题 | Runner 无法拉起/调度失败 | | Initialize containers | 环境问题 | 容器运行时异常/镜像拉取失败 | | Checkout / Setup Environment | 环境问题 | 网络/挂载/权限故障 | | Run steps（pytest/lint 等） | 需进一步分析 | Runner 已就绪，进入 Step 2-3 细分 | 如果失败在前三类步骤，直接标记为环境问题并进入 Step 2。 如果失败在 Run steps，需要同时执行 Step 2 和 Step 3 来区分环境故障与代码问题。 ### Step 2: 物理节点溯源 + 环境故障深度定位 #### 2a. 物理节点溯源 当判定为环境故障或怀疑硬件问题时，定位物理节点： 1. 从 `Set up job` 日志或 `gh api` 获取 `runner_name`（即 Pod 名称）。 2. 从 `runner_name` 前缀或 Job Labels 识别节点池（如 `a3-0`）。 3. 自动发现 namespace：`kubectl get pods --all-namespaces --no-headers | grep ` 提取 namespace。 4. 反查物理机： - Pod 未销毁：`kubectl get pod -n -o custom-columns=NODE:.spec.nodeName --no-headers` - Pod 已销毁：在日志中搜索 `Successfully assigned to `。 #### 2b. 环境故障深度定位 检查以下故障模式： - **驱动/硬件失效**：`npu-smi info` 报错、`ERR99999`、`error code 507035`、`Device not found`。 - **资源溢出 (OOM)**：系统级 `Killed` 信号、`Bus error`（SHM 不足）、`No space left on device`。 - **多机连锁超时**：多机任务中某节点报 `Timeout`，优先识别并检查 Master 节点。Master 节点识别方法： - 检查 `RANK_TABLE_FILE` 中 `rank_id=0` 对应的节点 - 或在日志中搜索 `master_addr` / `MASTER_ADDR` 环境变量指向的节点 - 确认 Master 节点是否有 `Unexpected Exit` 或驱动报错 ### Step 3: 非环境问题判定 如果 Step 2 未发现环境/硬件故障，检查以下非环境因素： - **YAML 语法错误**：如 `undefined variable "False"`（应为小写 `false`）。 - **业务逻辑报错**：`AssertionError`、Python Traceback 指向业务源码、测试用例失败。 - **依赖问题**：pip/npm 安装失败但非网络原因（版本冲突、包不存在）。 ### Step 4: 输出诊断报告 根据诊断结果选择输出模式： #### 情况 A：确认为基础设施/硬件故障 严格按照以下格式输出： ``` # GitHub Action 故障诊断报告 ## 1. 故障概览 - **任务名称**: [Job Name] - **Run ID**: [Run ID] - **故障定性**: 环境问题 / 硬件故障 / 集群调度异常 - **判定依据**: [驱动报错/调度异常/硬件死锁/OOM 等] ## 2. 详细诊断 - **失败步骤**: [Set up job / Initialize containers / Run steps 等] - **报错原文**: [引用关键日志片段] - **物理节点**: [Runner 名] -> [Pod] -> [物理机/节点池] - **根因分析**: [深层原因说明] ``` #### 情况 B：环境正常，非基础设施问题 采用自然语言简要反馈： 1. **结论**：直接告知"未发现环境/基础设施故障"。 2. **依据**：简述分析了哪些环节（调度、镜像拉取、NPU 挂载等均正常）。 注意：两种情况均不输出修复建议或操作手册。 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/opensourceways) — claim your Tome and manage your conversions.