pillumina/ascend-sleuth / skills/diagnose
diagnose
Verified昇腾训练/推理问题的核心诊断循环:收集症状、按 triage-tree 路由、两阶段加载 并验证 Tier 2 case、命中给 fix(高危 root cause 改提示 halt)或转深度排查。 Tier-2 未命中但最终解决时起草候选 case。全程写 trace。 仅在能执行命令的 agent(Claude Code / Codex / pi)中可用。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 45.1 KB |
| references/collect-gates.yaml | config | 17.4 KB |
| references/diagnosis-procedure.md | markdown | 46.4 KB |
| references/diagnosis-trace.md | markdown | 46.2 KB |
| references/platform-dispatch.md | markdown | 1.6 KB |
| references/procedure-gates.yaml | config | 4.3 KB |
| references/report-template.md | markdown | 23.7 KB |
| references/script-integration.md | markdown | 2.2 KB |
| references/src-fetch.md | markdown | 9.2 KB |
references/collect-gates.yaml
View on GitHub# 采集闸门表(diagnose 的「数据缺口」消费点)——结构化绑定,不写散文
#
# 为什么存在:reference 的检索层定位是「候选命中后的辅助查询」(不参与候选路由/排序,
# 这一不变量不变)。但 tool 类里有一组内容服务的是**数据缺口**——把数据拿回来本身。
# 这段绑定过去只写在 SKILL.md 散文里(硬编码
# ref-id 字符串),已发生静默腐化:`profiling-performance-fault-patterns` 全库不存在
# (真 id `msprof-tool-fault-patterns`)。现在绑定落成数据,由 verify_references.py
# 校验(id 必须存在于 references/ 且 status: active),腐化从静默变为 CI 红。
#
# **时点:候选加载后**(原设计写"Tier2 候选加载之前",改动的理由记在这里,不让它变成
# 无从追溯的口径):候选加载前问「你有数据吗」,问句只能停在类别层面("你有 dump 吗"),
# 而工程师此刻还不知道这次要 dump 什么,他答的是猜的类别;加载后缺口已经具体到某个值的
# 名字("这条 case 要确认 optimizer 的 exp_avg 是否溢出,你手上有 dump 吗"),他答的是事实。
# 路由与候选筛选本身不依赖测量数据(候选按症状与签名匹配),所以把探询放到加载后不丢信息。
#
# 分工:**形态归 SKILL,内容归 reference**——本表只决定「问什么、按什么分支、取哪些词条」;
# 探询只问一次、只问一句,采集面只在 no_data / gap 分支展开(原则九),
# 交互纪律见 skills/diagnose/SKILL.md「数据资产探询」节。
# **本表是唯一绑定处**:SKILL / diagnosis-procedure 只写形态与纪律,不重复 ref-id——
# 改词条、改分支只改本表一处(散文与数据双源必漂移,改一处即生效)。
#
# 校验(verify_references.py,随 CI):文件必须存在(约定 <skill>/references/*-gates.yaml);
# gate id 唯一;category / categories ∈ triage-tree 取值;kind ∈ {probe, conditional}
# 且 probe 必带 question、conditional 必不带;**branches[].refs 与 caveat_refs 的每个 id
# 都必须存在且 status: active**(不只是被引用,还要被绑定,见下面那条覆盖环)。
#
# kind 两种(两种都发生在候选加载后:探询的问题要带这次缺的具体值):
# probe 探询型——先问一句,按对方回答分支(精度/性能:有数据就不讲采集)
# conditional 条件型——不预先问;仅当缺口出现(现有材料不足以定位)才给采集指引
#
# 覆盖环(为什么本表要收全,而不是"用到再补"):tool 类词条 38 条里,靠这条闸门进来的
# 是**唯一**入口——它们不进候选路由(不是 case),背景 summary 层也不按工具名收窄到具体命令。
# 于是"某条工具词条没被任何闸门绑定"在运行时的唯一表现就是**它永远不会出现在诊断上下文**,
# 而没有任何信号会报这件事。CI 因此加一条:**每条声明了 category 的 active tool 词条,
# 必须出现在本表的某个 branches[].refs 或 caveat_refs 里**——漏绑定即红(原则二:把不变量
# 写进结构;原则八:不可观测的机制无法证明它没有在腐化)。
# 边界如实标注:该检查保证"有入口",**不保证入口在对的分支上**(分支语义归人审)。
gates:
- id: precision-data
category: precision
kind: probe
trigger: 候选加载后、某个具体测量值不在手上(数值比对 / 溢出检测 / 精度预检)而它决定下一步能不能走
question: "你已经有 dump 数据 / 分析结果了吗?还是要我给到代码级接入步骤?"
branches:
- when: has_data
action: 直接进比对 / 分析路径,不展开接入说明
refs:
- msprobe-accuracy-compare
- msprobe-overflow-check
- msprobe-accuracy-checker
- when: no_data
action: >-
给接入步骤(API 骨架 + config.json);接入点用调用栈法现场定位(不背位置);
明确这是临时调试改动、需回滚
refs:
- msprobe-data-dump
caveat_refs:
- msprobe-tool-side-effect-fault-patterns # 工具介入可能让同步/踩踏类问题消失——先排除再下结论
- id: precision-analysis-tools
category: precision
kind: probe
trigger: 手上已有精度数据(dump / 比对结果 / 训练曲线),要判断"下一步看哪一份"
question: "你手上有哪些精度的数据产物(dump 目录 / 比对结果 / 逐 step 曲线)?"
branches:
- when: has_data
action: >-
按产物选读法:先确认配置与数据本身没读错(config 检查、数据加载面),再看单步比对与
编译期精度预检,长跑看趋势、异常值看 response anomaly;可视化只用来定位可疑层,
结论仍要回到数值
refs:
- msprobe-config-check
- msprobe-data-load
- msprobe-checkpoint-compare
- msprobe-compile-precision-checker
- msprobe-response-anomaly
- msprobe-trend-visualization
- msprobe-visualization
- precision-first-divergence-triage
- precision-threshold-cascade
- accuracy-operator-exemption-and-verification
- single-operator-accuracy-verification
- train-infer-paired-collection
- verl-cross-validation
- verl-probs-diff-monitoring
- verl-uwc-weight-consistency
- when: no_data
action: 不展开分析路径——回到本 category 的采集探询(precision-data 闸门)
refs:
- msprobe-data-dump
caveat_refs:
- msprobe-tool-side-effect-fault-patterns
- id: performance-data
category: performance
kind: probe
trigger: 候选加载后、某个具体测量数据不在手上(指标阈值 / 时间线 / 通信占比)而它决定下一步能不能走
question: "你已经有 profiling 数据了吗(采集产物)?还是要我给采集指引?"
branches:
- when: has_data
action: >-
先判这份产物能不能用(认类型 / 查是否正常结束 / 对交付件清单,三态 valid|unparsed|invalid),
再直接分析(kernel_details.csv / step trace 等),不展开采集说明。**问题落在显存面时走另一条**
(显存采集与判读、碎片与泄漏口径),先确认数据可用度再定分支
refs:
- msprof-collect-parse
- ascend-profiling-collection-planning
- msprof-tool-fault-patterns
- msprof-comm-bottleneck-thresholds
- msmemscope-collect-and-query
- memory-symptom-triage
- when: no_data
action: >-
给采集方式(命令 + PROF_* 产物结构);具体命令以客户环境的工具版本为准
(版本差异以实际输出为准,不照搬示例)。**外层包不住命令时走框架侧接入**
(训练改框架 YAML 的 profile 配置块、推理服务走 `--profiler-config` + HTTP 启停),
两条路都先算清采集窗口与开销。**显存面是另一套采集**:先问清诉求(OOM / 怀疑泄漏 /
想知道花在哪)再定配置,别默认一套参数;泄漏与 OOM 归因必须带调用栈
refs:
- msprof-collect-parse
- framework-profiler-instrumentation
- msprof-tool-fault-patterns
- msmemscope-collect-and-query
- id: performance-analysis-tools
category: performance
kind: probe
trigger: 手上已有 profiling 产物,要判断"下一步看哪一份 / 动哪个算子"
question: "你的 profiling 产物是哪种(timeline / kernel_details / 通信矩阵 / 仿真报告)?"
branches:
- when: has_data
action: >-
按产物选读法:先跑执行层命令拿结论(集群综合分析 / advisor / free 分析),命令答不了具体问题时降到 SQL 直查;
再把读数套判据表分流(快慢卡 / 空闲 / 频率 / 链路 / 算子 Bound,每条都带反面条款);
其余读法:timeline 横条(µs 级归因、区分计算与空泡)、算子内部 pipe 分解、
仿真报告(无上板条件时)、静态编译视角看搬运与切分、融合类看编译策略是否生效;
具体调优动作落到对应的流程词条,不在这里展开
refs:
- profiler-analysis-cli
- profiler-analysis-triage
- profiler-db-query
- msmemscope-collect-and-query
- memory-leak-and-oom-triage
- memory-symptom-triage
- cpu-binding-affinity-triage
- cpu-binding-inspection-procedure
- multi-rank-slow-rank-detection
- cluster-compare-diagnosis
- operator-pipe-bound-classification
- operator-tuning-experiment-method
- operator-compute-failure-modes
- npu-memory-snapshot-analyzer
- msprof-timeline-lane-reading
- msopprof
- cannsim-sim-profiling
- op-compiler-static-kernel
- autofuse-fusion-enable-and-diagnostics
- aoe-model-tuning
- msprobe-monitor
- msprobe-trend-visualization
- torchtitan-npu-training-metrics-and-debugging
- when: no_data
action: 不展开分析路径——回到 performance-data 闸门先拿产物
refs:
- msprof-collect-parse
caveat_refs:
- msprof-tool-fault-patterns # 采集行为本身可能改变现象——先排除再下结论
- id: interrupt-evidence-gap
category: interrupt
kind: conditional
trigger: >-
已提供的日志不足以定位——缺另一层日志(级别不够 / 只有 Host 侧 / 需按时间找首报错 rank)
或需卡住进程的调用栈;或现象指向内核级事件(进程被 OOM killer 杀掉 / 节点重启 / 掉卡复位)
而手上只有 CANN 侧日志
question: null
branches:
- when: gap
action: >-
给采集方式并说明需复跑与影响面:提日志级别重跑;导出 Device 侧日志按时间找首报错;
一键收集故障信息;卡住进程取堆栈(不中断进程);现象指向内核级事件时另取 Host 内核日志。
日志面还有两个高频自伤要一起给:日志不落盘 / 时间戳不对 / 多余打屏的分流,
以及日志模块配置本身(改配置要给回滚)
refs:
- ascend-log-levels
- ascend-device-log-ops
- ascend-asys
- ascend-stack-view
- ascend-msaicerr
- host-kernel-log-collection
- ascend-slog-conf
- ascend-restart-slogd
caveat_refs:
- ascend-log-troubleshooting # 日志量级/裁剪纪律:只贴失败 rank + 栈尾,别灌全量
- id: interrupt-deep-debug-gap
category: interrupt
kind: conditional
trigger: >-
日志与栈已够定位到"哪一层"但还缺"哪一行"——疑似算子内部 / 框架适配层问题
(越界、踩踏、竞争、精度与执行耦合),需要源码级或工具级手段;或多机通信类问题
已排除日志面、要收网络与链路面
question: null
branches:
- when: gap
action: >-
给源码级 / 工具级手段并标注影响面:调试算子与 kernel(可断点、可看中间值)、
竞争与内存类问题走 sanitizer、算子编译期问题看调试套件;多机通信问题收敛到
网络诊断与通信链路资源两面(链路面含网口 QoS:PFC 位图、优先级到 TC、TC 缓冲)。
这些手段多数需要**重跑或改变执行方式**,给之前先说清楚影响(可能让复现消失)
refs:
- msdebug-operator-source-debug
- operator-debug-entrypoints
- mssanitizer
- operator-sanitizer-suite
- operator-coredump-forensics
- asc-tools-ascendc-debug-suite
- hccn-tool-network-diagnosis
- hccn-tool-qos-pfc-tc-dscp
- hixl-tool-route-and-comm-res
- npu-smi-950-device-ops
caveat_refs:
- msprobe-tool-side-effect-fault-patterns # 工具介入改变时序——先排除工具副作用再下结论
- id: source-location
categories: [interrupt, precision, performance]
kind: conditional
trigger: >-
走到源码分析、但报错签名指向的仓不能从已知表直接定下来(签名像 aclnn*/Hccl*/ge::/aclrt*/drv*/
AscendC:: 这类接口前缀,或报错文本里有算子名而没有仓名)
question: >-
"这个报错在你们那的 CANN 安装目录里落在哪个子目录?"——附上脚本给的候选表让他选一个
(别的问法都不如这一句准,因为装目录的子目录名就是仓名)
branches:
- when: repo_ambiguous
action: >-
按发现顺序找,别把"源码在哪个仓"直接问人(那是可枚举的事实):①候选表
`python3 scripts/src_fetch.py --find "<签名>" --ref <版本>`(脚本逐个试该 ref,
只有一个候选能解析就自动取回,多个或只命中兜底则 exit 3);②组织枚举
`--list-orgs` 与 `--list-org-repos <组织>`(GitCode 组织匿名可枚举);③搜仓名,
用 gh 或 web 搜报错里的接口名、算子名、库名,得到 org/repo;④取回并验证
`src_fetch.py <org/repo> --ref <版本> --verify "<签名>"`。验证不过或版本定不下来时,
按 question 问一句并要求他回候选编号。**不许猜仓**:取错仓会产出错版本的证据,
比不取更糟(与"没拿到该版本"等价)。私有仓/内网镜像才直接要 clone 地址(`--url`),
镜像内代码按冻结 commit 取,不能按 tag 推断
refs:
- cann-source-location # 仓在哪一层(平台结构事实);怎么调脚本见本 skill 的 src-fetch.md
- when: repo_resolved
action: >-
按版本取源码并验证(`src_fetch.py <org/repo> --ref <版本> --verify "<签名>"`),
验证命中后 grep 报错签名/算子名定位到文件与行;退出码非零(含 6 验证未通过)就是
不能把这棵树当证据,结论写"无法判定",不要用其他版本或 web 搜索结果顶替
refs:
- cann-source-location
- operator-debug-entrypoints
caveat_refs:
- cann-source-location # 各仓共用 CANN 发布号:tag 能解析不构成定位证据
# 外部查证(可选能力):工具由 DSH 插件提供,端点在 ~/.dsh/sleuth-kb.json。
# 三个点共用一个闸门:它只回答「这个缺口能不能交给外部查证」「工具不在怎么办」,
# 具体调哪个工具、参数怎么填在词条里。工具不在或返回不可用时一律回原路径,不重试。
- id: external-evidence
categories: [interrupt, precision, performance]
kind: conditional
trigger: >-
**只在本单框架是 vllm-ascend 或 vllm 时适用**(含部署成 0day 镜像、fork、定制构建的 vllm-ascend);
mindspeed、verl、torch-npu、sglang 等其他框架不展开,记 skipped 加 reason: not-applicable,
不要拿别家的框架去查,命中了也不是这次部署的代码。适用且工具可用时,两个缺口才展开:
步骤 5 需要按版本或镜像定位源码(本地 src_fetch.py 只按官方 tag 取,镜像与 fork 取不到),
或要给「已修复 / 升级即可」结论的修复依据;以及步骤 1 工程师给的是截图、模型自己不能读图、且需要转成文字或签名时(能读图就直接读,这条是兜底)。
工具不在或不可用就记 skipped 并走原路径。
question: null
branches:
- when: gap
action: >-
先判两件事:框架是不是 vllm-ascend 或 vllm,工具在不在(主组:vllm_kb_code / vllm_kb_fix / vllm_kb_doc;截图那条还要 vllm_kb_ocr 那一行开着)。
框架不是这两家 → 记 skipped、`reason: not-applicable`,本节到此为止,不要调;
工具不在 → 记 skipped、reason 写工具未装或工具行关着,回到原路径(gh search 加 src_fetch.py)。
两种都不要问用户"为什么没有这个工具"。
在就按缺口选一个:源码定位用 vllm_kb_code(镜像与 fork 必须带 repo),
修复链用 vllm_kb_fix(结果只当线索;fixes 空不代表未修复),手册原文用 vllm_kb_doc(body 空=没拿到原文),截图转文字用 vllm_kb_ocr(兜底;模型能读图或能贴文字时不用它;它由 `vllm-kb-ocr` 那行单独控制,没开就当没有)。
工具返回 ok:false 时先分类:http-4xx 且 detail 指明是参数问题(version 不带 v、镜像 tag 非法、缺参)
→ 按返回提示改正后**最多重试一次**,仍失败才回原路径;http-404 路由不存在、http-5xx、unreachable、
not-configured、timeout → **不重试**,记 external_lookup 的 skipped 加对应 reason,回原路径。
两种都在依据链里标"离线/未验证",不把工具不可用写成结论缺口。
refs:
- vllm-kb-versioned-code
- vllm-kb-upstream-fix
- vllm-kb-manual-doc
- vllm-kb-screenshot-ocr
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |