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/src-fetch.md
View on GitHub# src_fetch(按版本取源码 / 源码位置发现)
`/diagnose` 步骤 5 深度排查走到源码分析时的入口契约。**SKILL.md 只写"什么时候用"**,这里的展开是"命令行怎么写、退出码怎么读、仓不知道时按什么顺序找、拿不到时怎么问"。
## 两种形态
| 形态 | 命令 | 用在什么时候 |
|---|---|---|
| 已知仓 | `python3 scripts/src_fetch.py <repo> --ref <tag\|commit>` | 报错已经指向具体仓(`--list` 看已知表) |
| 不知道仓 | `python3 scripts/src_fetch.py --find "<报错签名>" --ref <版本>` | 只知道接口前缀与算子名(`aclnn*`、`Hccl*`、`ge::`、`aclrt*`…) |
辅助开关:`--offline`(`--find` 只给候选、不联网)、`--self-test`(校验数据目录与真实签名用例)、`--list-versions`(本地已有版本,命中即复用)、`--prune`(按 `--ref` 手工删版本目录,无自动 GC)、`--url`(私有/内网仓)、`--dest`(换缓存根,默认主检出 `src-code/`)。
## 发现与目录命令
| 命令 | 用在哪一步 |
|---|---|
| `python3 scripts/src_fetch.py --list` | 已知表:目录里登记过的仓、别名与 host |
| `python3 scripts/src_fetch.py --list-orgs` | 候选表给不出仓时,先看有哪些组织、哪个可枚举 |
| `python3 scripts/src_fetch.py --list-org-repos cann` | 可枚举组织现枚举仓与说明;不可枚举组织列目录里登记过的仓 |
| `python3 scripts/src_fetch.py <org/repo> --ref <版本> --verify "<签名>"` | 取回对应版本,并在树里验证签名是否出现 |
| `python3 scripts/src_fetch.py --catalog <目录>` | 换源码仓目录(私有部署、场景测试),默认 `source-catalog.d/` |
两种形态都建议带 `--verify`:验证是取源码的收尾动作,见「验证是收尾动作」。数据目录与补仓方式见「数据目录」。
## 缓存布局
`src-code/<org>/<repo>/<解析后的 ref>/`——**一个版本一个目录**,各版本物理隔离(并发诊断各读各版本,不存在"别人 checkout 走了我正在读的版本")。缓存根锚在**主检出**,同一克隆的所有 worktree 共读共写。版本目录名与 case 的 `source_ref.ref` 是同一个 token,案例与源码互查不用转换。
## 退出码就是契约
调用方只看退出码与 stdout 末行,别看输出里的路径:
| 码 | 含义 | stdout 末行 | 该做什么 |
|---|---|---|---|
| 0 | 已在本地产出该 ref 的树并核对通过(带 `--verify` 时签名也命中) | 版本目录绝对路径 | 直接 grep 那个目录 |
| 2 | 用法问题(未知仓无 `--url`、`--find` 没给签名、`--verify` 签名空、`--list-org-repos` 组织不存在…) | 失败声明 | 看 stderr 的修法 |
| 3 | ref 解析不了(tag 名不同,输出里有可用 tag)**或**候选定不下仓(≥2 未定、只命中兜底、零候选;输出里有候选表或下一步) | 失败声明 | 前者按列出的 tag 重试;后者按「发现顺序」继续 |
| 4 | 拉取失败(网络/私网/凭据)或拉到的提交与 ref 不符 | 失败声明 | 可达地址用 `--url`;镜像内代码按冻结 commit 取 |
| 5 | 本地有该版本目录但核对不通过 | 失败声明 | 确认是它才加 `--force` 重拉 |
| 6 | 取到了树,但 `--verify` 的签名没出现在里面 | 失败声明 | 写「不能证明是这个仓或版本」;换仓或版本重试,不要读这棵树当证据 |
**非零 = 不能把这棵树当证据。** 退出码 3、4、5 是没拿到这个版本;6 是拿到了但不能证明是它。都不要拿本地其他版本的目录去读(那是错版本的证据),也不要用 web 搜索结果代替源码(搜上游 issue/PR 状态是另一回事)。
## `--find` 怎么读结果
1. 脚本按签名里的**接口前缀**与**算子名**给带理由的候选(默认前 3 个,按命中分排序)。
2. 候选逐个试该 ref:**只有一个能解析 → 自动取回(exit 0)**。
3. 多个候选都能解析 → exit 3,交回候选表与各自的解析结果。**同名 tag 不构成定位证据**(CANN 各仓共用同一套发布号)。
4. 只命中**公共前缀**(`aclnn xxx` 没给算子名)→ 命中的是**兜底候选**,仍 exit 3:补算子名或接口名重试,或按下面的发现顺序继续。
5. 已经确定是哪个仓 → 把仓名写在签名后面(`--find "<签名>" cann/ops-nn`),**以它为准**,候选表只作对照。
6. 零候选也 exit 3,输出里已有下一步该跑的命令。继续走发现顺序,不要直接问工程师。
## 发现顺序(`--find` 没有定下仓之后)
exit 3 之后按这个顺序继续,前四步都不需要工程师:
1. **先看已知表与候选表**:`--list` 看登记过的仓与 host;`--find` 的输出里已有带理由的候选。
2. **再看可枚举组织**:`--list-orgs` 看有哪些组织、哪个可枚举;`--list-org-repos cann` 现枚举该组织的仓与说明。GitCode 组织匿名可枚举,这一步不需要账号。断网时加 `--offline`,只列目录里登记过的仓。
3. **再搜仓名**:上面两步都没有目标仓时,用 `gh search repos <关键词>` 或 web 搜索报错里的接口名、算子名、库名,得到 `org/repo` 形态的仓名。
4. **取回并验证**:`python3 scripts/src_fetch.py <org/repo> --ref <版本> --verify "<签名>"`。exit 0 才算拿到证据。直接给 `org/repo` 取源码时先试 GitHub、再试 GitCode;走 `--find` 且带 `--org` 时先按该组织的 host 试,再试另一个。只在 GitCode 上有的仓因此不用另找地址;只有私有仓或两个 host 都取不到时,才从仓页面取克隆地址配 `--url`。
5. **最后才问工程师**:验证不过、或版本定不下来时,问一句。
**定不下来时问的那一句**(绑定在 `collect-gates.yaml` 的 `source-location` 闸门,探询纪律同其它闸门:只问一次、只问一句):
「这个报错在你们那的 CANN 安装目录里落在哪个子目录?」附上候选表让他回编号。安装目录的子目录名就是仓名,比任何描述都准。
**不要向工程师要 URL**:组织仓库清单是可枚举的事实(`--list-org-repos` 一条匿名请求),把它变成别人的记忆负担,等于把可复现的一步退回给猜。只有候选都试不通、或仓是私有的,才要地址。
## 验证是收尾动作
**仓名与 tag 都是弱证据**。CANN 各仓共用同一套发布号,同名 tag 在每个仓里都能解析;仓名也可能只是搜索结果里的相似项。它们只缩小范围。
**签名出现在树里才算证据**。取到树后在同一条命令上加 `--verify "<签名>"`。它按字面量在树里搜,区分大小写:
- 命中:exit 0,打印命中的文件与行(最多列 20 处,其余略)。二进制文件里的命中按文件报出(`Binary file <路径> matches`,没有行号)。stdout 末行仍是版本目录路径。后面的 grep 从这个目录开始。
- 未命中:exit 6,打印「✗ 验证未通过」。这时写「不能证明是这个仓或版本」,**不要写「不是这个仓」**:可能是版本号不对,也可能签名只出现在编译产物或驱动包里。
- 签名可能只在二进制里:树内的二进制文件有命中时按文件报出;编译产物或驱动包里的签名不在源码树里,本该命中却未命中时,说明这个局限,再向工程师要该二进制所在路径或其它信息。
- 复用本地缓存时同样验证:`--verify` 对本地已有版本也生效,不要跳过这一步。
## 数据目录(source-catalog.d)
源码仓目录是数据,不是代码。`source-catalog.d/<层>.yaml` 一层一个文件(`cann.yaml`、`training.yaml` 等),是已知表、签名候选表与可枚举组织的唯一来源。
- `src_fetch.py` 只做取用流程。
- `source_catalog.py` 只做加载、校验与候选计算。
- 私有部署或场景测试换目录用 `--catalog <目录>`。
接口前缀与层的对应判据见先验层 `references/software-facts/cann-source-location.yaml`。
每个层文件里与本流程相关的有三部分:
- `orgs`:组织名、host、`enumerable` 与说明。只有可枚举组织才走现枚举。
- `repos`:一个仓一条,含 `repo`(`org/repo`)、`sources`(host 与 owner/repo,可多条并按可信度排序)、`aliases`、`why`,以及 `discover`(签名关键词规则:`all_of` / `any_of` / `primary` / `discriminators` / `fallback`)。
- `self_test`:真实签名到期望仓的用例,`--self-test` 逐条跑。用例的组织必须在 `orgs` 里声明,跨层合并。
补一个仓只改数据:在对应层文件的 `repos` 里加一条;报错签名会点到它时,再加 `discover` 与 `self_test`。不改脚本。改完跑 `python3 scripts/src_fetch.py --self-test`。
数据写坏时只有这一步会明确报错:关键词含大写、仓名写错、真实签名不再命中,都只表现为零候选(看起来像"上游没有这个仓");`--self-test` 把它们变成 exit 1 并点名。
**诊断中发现缺仓不直接改**:先用 `python3 scripts/evolve_intake.py record …` 记一条改进信号(按部署声明写成改进项或信号记录),由演进流程决定补哪一层。诊断中途改仓目录,会让这次诊断的证据依赖一份未审的改动。
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 | Verified | 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 |