# skill

**Repository Path**: chen-junhao1234/skill

## Basic Information

- **Project Name**: skill
- **Description**: aclgraph的skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aclgraph 问题定位 agent

面向 vLLM + omni-npu NPU 部署场景的**分层诊断 Skill 套件 + 编排引擎**:
日志输入 → 阶段识别 → 充足性判断 → 自主补充日志 → 路由到专用深度分析 → 案例库兜底 → 闭环复盘。

## 项目定位

本项目**不是**单一 skill,而是一组协作的 Claude Code Skills + 一个 Python 编排引擎,共享同一个知识库:

| 组件 | 作用 |
|------|------|
| **Claude Code Skills** (`skills/*/SKILL.md`) | 用户与 Claude Code 对话时自动加载的诊断 playbook |
| **Python 编排引擎** (`agent/`, `analyzers/`) | 通过 CLI 提供编程接口,跑同一套规则 |
| **共享知识库** (`knowledge/`) | L1 规则 (`l1_rules.yaml`) + 案例库 (`cases/*.yaml`),两条路径都查它 |
| **闭环产物** (`diagnostics/`) | 诊断总结 + 闭环复盘（合并在同一目录） |

## 分层诊断架构

```
            日志输入 (日志路径 / 报错描述)
                       │
                       ▼
   ┌─────────────────────────────────────────────────┐
   │ L1  diagnostic-instrumentation                   │
   │     · 信息收集 (LOG_PATH / 启动脚本 / 代码仓路径) │
   │     · 阶段识别 (torch_compile / capture / runtime)│
   │     · 日志充足性判断 + 自主重跑补日志            │
   │     · 路由决策                                    │
   └────────────┬────────────────────────────────────┘
                │
       ┌────────┼─────────────────┬────────────┐
       ▼        ▼                 ▼            ▼
    L2 路由匹配 L2 路由匹配      L2 ...     L3 兜底
       │        │                              │
   ┌───▼───┐ ┌─▼──────────────┐         ┌──────▼─────────────┐
   │ L2     │ │ L2              │        │ L3 aclgraph-       │
   │ multi- │ │ static-kernel-  │        │ general-expert     │
   │ tier-  │ │ analysis        │        │ knowledge/cases/   │
   │analysis│ │ (8 步流程自查)  │        │ 相似度评分匹配      │
   │(Dynamo │ │                 │        └─────────────────-──┘
   │ guard) │ │                 │
   └───┬────┘ └───┬─────────────┘
       │          │
       └────┬─────┘
            │
            ▼  (诊断完成,任何路径终态都触发)
   ┌─────────────────────────────────────────────────┐
   │ diagnostic-closure (跨层,非"另一层")              │
   │   阶段 1: 诊断结束 → diagnostics/ 生成 AI 总结    │
   │   阶段 2: 用户提供真实解法 → diagnostics/ 复盘    │
   │           对照 AI 分析 vs 真实方案,改进 case 库 / skill │
   └─────────────────────────────────────────────────┘
```

### 各层职责边界

| 层 | Skill | 干什么 | 不干什么 |
|----|-------|--------|---------|
| **L1** | `diagnostic-instrumentation` | 信息收集 + 阶段识别 + 充足性 + 路由 + 自主重跑 | 不做根因深度分析、不做案例匹配 |
| **L2** | `multi-tier-analysis` | 多档位 shape mismatch / Dynamo guard 硬编码值定位 | 不做静态 kernel / recapture |
| **L2** | `static-kernel-analysis` | 静态算子 (Aclnn static_kernel) 8 步流程自查 | 不做动态算子定位、不做性能 |
| **L2** | `npugraph-ex-precision-debug` | 多档位+多流+控核叠加精度异常诊断 | 不做 shape mismatch / 静态 kernel |
| **L3** | `aclgraph-general-expert` | 案例库匹配 + 通用兜底分析 | 不替代 L1 前置准备 |
| **跨层** | `diagnostic-closure` | 诊断后写总结、对照真实解法做复盘 | — |

## 目录结构

```
skill/
├── README.md                     # 本文档
├── CONTRIBUTING.md               # 贡献指南
├── Makefile                      # 常用命令快捷入口
├── cli.py                        # CLI 入口:diagnose / l2 / learn
├── pyproject.toml
├── pytest.ini
│
├── skills/                       # Claude Code Skills (markdown,Claude Code 自动加载)
│   ├── diagnostic-instrumentation/   # L1 — 信息收集 + 路由
│   │   └── SKILL.md
│   ├── multi-tier-analysis/          # L2 — 多档位 (含 references/)
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── code-paths.md
│   │       └── error-patterns.md
│   ├── static-kernel-analysis/       # L2 — 静态算子 (含 references/)
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── diagnostic-flow.md
│   │       └── responsibilities.md
│   ├── npugraph-ex-precision-debug/  # L2 — 多档位精度异常 (含 references/)
│   │   ├── SKILL.md
│   │   └── references/
│   ├── aclgraph-general-expert/      # L3 — 案例库兜底
│   │   └── SKILL.md
│   └── diagnostic-closure/           # 跨层 — 诊断后闭环
│       └── SKILL.md
│
├── agent/                        # Python 编排引擎 (CLI 路径用)
│   ├── core.py                   # AgentCore:串联 L1→L2→L3 的总编排
│   ├── l1.py                     # L1Engine:阶段识别 + 充足性 + 路由
│   ├── l2.py                     # L2Registry:L2 分析器的注册和查询
│   ├── l3.py                     # L3Engine:案例库匹配
│   └── report.py                 # ReportGenerator:Markdown/JSON/YAML 渲染
│
├── analyzers/                    # L2 Python 分析器实现
│   ├── base.py                   # L2Analyzer 抽象基类 + L2Report 数据类
│   ├── multi_tier.py             # 多档位 shape mismatch (已上线)
│   ├── recapture.py              # sleep/wakeup recapture (已上线)
│   └── # static_kernel.py        # 静态算子 (待补;当前只有 SKILL.md,Python 路径走 L3 兜底)
│
├── knowledge/                    # 共享知识库 (Claude Code 路径与 Python 路径都查)
│   ├── l1_rules.yaml             # L1 引擎阶段定义 + scenarios + 路由配置
│   ├── cases/                    # L3 案例库 (运行时 rglob 加载)
│   │   ├── aclgraph/             # omni-npu / aclgraph 相关案例
│   │   │   ├── torch_compile/    # aclgraph-tc-001.yaml ~ aclgraph-tc-006.yaml
│   │   │   ├── capture/          # aclgraph-cap-005.yaml, aclgraph-cap-006.yaml, aclgraph-cap-007.yaml
│   │   │   ├── runtime/          # aclgraph-rt-003.yaml + cap-001/004.yaml + rt-004~008.yaml
│   │   │   └── hs/               # HS 团队案例 (team=HS, 无 phase)
│   │   └── references/           # 使用 / 调优 / 适配指南 (markdown,被 case 引用)
│       └── super-kernel-*.md     # SK 原理 + 配置选项 + 调试调优 + 盘古配置参考
│
├── utils/                        # 共享工具
│   ├── models.py                 # Case / LogFeatures / L1Result / L3Result / DiagnosisReport
│   ├── log_parser.py             # 从日志提取 error code / code path / stack frame
│   └── auto_precipitate.py       # 案例自动沉淀(诊断结果 → cases/auto-*.yaml)
│
├── diagnostics/                  # 诊断总结 + 闭环复盘文档
│   ├── README.md                 # 总结格式规范 + 归档索引
│   └── YYYYMMDD-<model>-<keyword>.md
│
├── schemas/                      # Schema 定义
│   └── case-schema.json          # Case YAML 的 JSON Schema
├── templates/                    # 显式模板（贡献者使用）
│   ├── case-incident.yaml        # 事件型案例模板
│   ├── case-knowledge.yaml       # 知识型案例模板
│   └── skill-template/           # 新 Skill 脚手架
│       └── SKILL.md
│
├── scripts/                      # 安装/卸载
│   ├── install.sh
│   ├── uninstall.sh
│   ├── validate_cases.py         # Case YAML schema 校验
│   ├── case_stats.py             # 案例库统计
│   └── new_case.py               # 交互式创建新案例
│
├── tests/                        # 单元测试
└── docs/superpowers/             # 设计文档与实施计划归档
    ├── specs/                    # 设计文档
    └── plans/                    # 实施计划
```

## 两条诊断路径

本项目同一套规则可经两条路径触发,选哪条由用户使用习惯决定:

### 路径 A:Claude Code Skill (推荐,交互式)

```
用户对 Claude Code 说:"server.log 里有报错,看一下"
   ↓
Claude 自动加载 L1 diagnostic-instrumentation SKILL.md
   ↓
按 SKILL.md 步骤收集信息 + 识别阶段 + 判断充足性
   ↓
路由到 L2 SKILL.md (multi-tier / static-kernel / ...)
   或路由到 L3 aclgraph-general-expert SKILL.md (案例库兜底)
   ↓
诊断完成后 diagnostic-closure 写 diagnostics/<日期>-<问题>.md
   ↓
用户后续提供真实解法 → diagnostic-closure 阶段 2 更新 diagnostics/*.md 并改进 cases/
```

### 路径 B:Python CLI (编程化,自动化)

```
python cli.py diagnose error.log
   ↓
AgentCore.diagnose_and_report():
   [1] L1Engine.detect_phase()       — 阶段识别 (l1_rules.yaml indicators)
   [2] L1Engine.check_sufficiency()  — 充足性 (l1_rules.yaml sufficiency)
   [3] L1Engine.route()              — 路由 (l1_rules.yaml scenarios.routing)
   [4] L2Registry.get(name).analyze()  — 跑 Python 分析器
       └─ 找不到对应 Python 实现 → 降级到 L3
   [5] L3Engine.match()              — 案例库相似度匹配
   [6] ReportGenerator                — Markdown / JSON / YAML 输出
```

**关键事实**: 两条路径**共享 `knowledge/l1_rules.yaml` + `knowledge/cases/*.yaml`**,所以增删规则/案例对两条路径同时生效。
Python L2 分析器是路径 B 特有的优化项 —— 没有对应 Python 实现时,路径 B 会自动降级到 L3 案例匹配;路径 A 则始终按 SKILL.md 执行。

## 快速开始

### 一键安装(推荐)

```bash
git clone <repo-url>
cd skill
./scripts/install.sh
```

安装后在任意目录打开 Claude Code,直接提交日志即可:

```
用户: server.log 里有报错,帮我看看
Claude: [自动加载 diagnostic-instrumentation L1 skill]
       [按步骤收集信息 → 路由 → 调用对应 L2 / L3]
       → 输出诊断报告
       [diagnostic-closure 自动写 diagnostics/<...>.md]
```

### 卸载

```bash
./scripts/uninstall.sh
```

### Python CLI (路径 B)

```bash
# 全自动诊断
python cli.py diagnose error.log

# 仅 L1
python cli.py diagnose error.log --depth l1

# 分步执行
python cli.py diagnose error.log --step

# JSON / YAML 输出
python cli.py diagnose error.log --output json

# 直接调用某个 L2 分析器
python cli.py l2 multi-tier error.log
python cli.py l2 recapture error.log
# python cli.py l2 static-kernel error.log    ← Python analyzer 待补,会降级到 L3
```

### Python API

```python
from agent.core import AgentCore

core = AgentCore()
report = core.diagnose_and_report(log_text, output_format="markdown")
print(report)
```

## 知识库维护

### 新增案例

直接在 `knowledge/cases/<phase>/` 对应子目录下新建 YAML(`torch_compile/` / `capture/` / `runtime/`),无需重建索引,L3Engine 启动时 rglob 递归加载。
文件名格式 `aclgraph-<tc|cap|rt>-<NNN>.yaml`(与 case_id 字段保持一致,按阶段分目录存放),case_id 字段为 `aclgraph-<tc|cap|rt>-<NNN>`。
字段约定参考 `torch_compile/aclgraph-tc-001.yaml`(incident 型)或 `runtime/aclgraph-rt-001.yaml`(`kind: knowledge` 流程沉淀型)。

GE 相关案例放在 `knowledge/cases/ge/` 下,文件名格式 `ge-<NNN>.yaml`。

### 从诊断结果自动沉淀

```bash
python cli.py learn error.log --fix '具体的修复步骤...'
```

写入 `knowledge/cases/auto-YYYYmmdd-HHMMSS.yaml`,关键词/错误码由 `utils/log_parser.py` 自动提取。

### 调整 L1 路由规则

直接编辑 `knowledge/l1_rules.yaml`:
- `phases` 控制阶段识别的关键字与权重
- `scenarios` 控制路由决策。每个 scenario 含 `indicators`(关键词 + log_patterns)、`sufficiency`(必填特征 + 必须环境变量)、`routing.l2_skill` / `routing.l3_case_id`。

## 扩展指南

### 新增 L2 (两种形态,按需选)

**最小形态:只加 Claude Code Skill (markdown)**
- 适合规则化的流程性问题(例如 `static-kernel-analysis`)
- 步骤:`skills/<name>/SKILL.md` + 可选 `references/*.md` + 更新 `l1_rules.yaml` 的 `routing.l2_skill` + 更新 `diagnostic-instrumentation` 的 L2 表与路由表
- 此时 Python 路径会降级到 L3,只有 Claude Code 路径走专用 skill

**完整形态:同时加 Python 分析器**
- 适合可以从日志正则/数值提取做精确分类的问题(例如 `multi-tier-analysis`)
- 在最小形态基础上加:
  1. `analyzers/<name>.py` 继承 `L2Analyzer`,实现 `can_analyze()` 与 `analyze() → L2Report`
  2. `agent/l2.py` 的 `L2Registry._ensure_loaded()` 注册实例
  3. `tests/test_<name>.py` 添加单测

### 新增/修改诊断流程

- L1 步骤、信息收集门控 → 改 `skills/diagnostic-instrumentation/SKILL.md`
- L1 路由规则、关键词、必需环境变量 → 改 `knowledge/l1_rules.yaml`
- 跨 skill 经验(比如"先关 static_kernel_compile 二分") → 在相关 L2 的 SKILL.md 互相 cross-ref

### 诊断闭环 + 案例入库

`diagnostic-closure` skill 覆盖**三种入口路径**,统一管理诊断材料和案例库:

- **情况 1A** — 用户直接给完整案例(已含根因+修复) → 跳过 `diagnostics/`,直接走"案例库写入规则"
- **情况 1B** — AI 诊断完成但无真实方案 → 写 `diagnostics/<日期>-<模型>-<关键词>.md` (🟡 待验证),可选起草 unverified case yaml
- **情况 2** — 用户后续提供真实方案(可跨会话) → 找回对应 `diagnostics/*.md`,补复盘 → 走"案例库写入规则",文档改 🟢 已闭环

"案例库写入规则"含 4 个场景: A(补已有 case)、B(新事件型)、C(新知识型 kn-)、D(新 reference)。
触发词、流程细节、文档模板见 `skills/diagnostic-closure/SKILL.md` 和 `diagnostics/README.md`。

## 当前状态速览 (2026-06-05)

- L1: 1 个 skill（diagnostic-instrumentation）
- L2: 3 个（multi-tier-analysis 含 Python + SKILL.md；static-kernel-analysis 仅 SKILL.md；npugraph-ex-precision-debug 仅 SKILL.md）
- L3: 1 个 skill + 71 个案例（事件型 39 个 + 知识型 32 个；事件型按 phase 分布：torch_compile/17 + capture/5 + runtime/14 + hs/5；知识型按主题分布：superkernel/19 + static-kernel/7 + capture/3 + debug-toolkit/3），详见下方"L3 案例库速览"
- references/: 10 篇（SK 5 + static-kernel 2 + capture 1 + debug-toolkit 1 + ACLGraph 设计文档 1）
- 闭环: 1 个 skill（diagnostic-closure 三入口路径）+ `diagnostics/`（12 份文档）
- **合计 6 个 Skill**（L1×1 + L2×3 + L3×1 + 跨层×1）

## L3 案例库速览

事件型案例按问题暴露阶段分目录存放(`knowledge/cases/<phase>/aclgraph-<NNN>.yaml`)。详细字段(`triggers` / `verified_isolations` / `fix` 等)见对应 yaml。

知识型案例（从 reference 拆分而来）按主题分目录存放(`knowledge/cases/kn/<topic>/aclgraph-kn-NNN.yaml`),无 phase 字段、team 留空,靠 keywords 命中。GE 相关案例放在 `knowledge/cases/ge/` 下。

### torch_compile 阶段

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-tc-001` | 多档位编译时 Dynamo 把第一档 shape 硬编码到 FX Graph,后续档位 shape 不匹配失败 |
| `aclgraph-tc-004` | Dynamo 遇到 Unsupported 操作(tensor 切片参数、图内调 `current_device()` 等)触发 trace 断图 |
| `aclgraph-tc-005` | 多档位 cudagraph + compile + MTP 共存触发启动期 AOT `out_spec != out_desc_spec`(`status: unresolved-but-workaround-verified`,根因未最终定位,有验证可用 workaround) |
| `aclgraph-tc-006` | 多档位 MHC 模块自定义算子被 Dynamo 硬编码 shape 导致 view 不匹配(算子非 omni-npu 责任田,给出包裹模块/修复 meta 两种建议) |
| `aclgraph-tc-007` | 多档位+多流+控核叠加导致 npu_quant_matmul 精度异常(tiling 按 24 核切分但实际运行按控核核数,GetCoreNum 在多档位下异常) |
| `aclgraph-tc-008` | custom_attention_pioneer 算子缺失 Meta Kernel 导致 torch.compile 失败,C++ TORCH_LIBRARY_IMPL 同时为 V1/V2 注册 Meta |
| `aclgraph-tc-009` | 开启静态kernel编译后 FIA(FusedInferAttentionSink) 算子性能从 25us 劣化到 40us,attention_metadata 缓存与 capture 前 torch.compile 共享导致 sink_meta 跳过 |
| `aclgraph-tc-010` | FIA/ATTR 算子静态编译报错 sparse_values nullptr,aclnn 框架未适配可选输出 |
| `aclgraph-tc-011` | 静态 kernel 编译不支持非连续 stride 传入(GetInputStride returned nullptr),临时模型转连续/根治需 GE+aclnn+OPC 联动 |
| `aclgraph-tc-012` | CreateView 在静态编译路径下把 storageshape 转一维,isView 接口动静返回值不一致触发算子 input dim 校验 |
| `aclgraph-tc-013` | 自定义算子静态编译 const rvalue 初始化 member 报错,算子源码 const 修饰不当 |
| `aclgraph-tc-014` | 自定义算子 mhc_pre 静态编译"看似生效实则未走",手写框架算子未把 double→float 转换导致 simplifiedKey attr 截断不匹配 |
| `aclgraph-tc-015` | 盘古V2 92B 启动 coredump,算子原型/配置遗留 ValueDepend 脏配置导致静态kernel 误判读 actual_seq_len |
| `aclgraph-tc-016` | aclgraph 叠加 aicpu 下沉精度异常,静态kernel 仍按常量处理 actualseqlen 走 GetData,tiling 数据全 0 |
| `aclgraph-tc-017` | Qwen3.6-35B-A3B (qwen3_next) 多档位 compile_sizes=[32,316] 第二档 capture 失败：真凶是 `causal_conv1d_update` 内 `torch.cat([state_t, x_t])` 触发 `Eq(s59,316)` guard 把全图 batch SymInt 钉成 316;修 = `direct_register_custom_op` 包裹 + `_gdn_active_decode_batch` 调用层 min 对齐 + q_norm/MoE/apply_rotary view 显式 SymInt(commits 2b4a7e15/5813b0f9/40c77b1f/b5596052) |

### capture 阶段

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-cap-005` | capture 阶段动态 shape 导致 stream/event 资源耗尽(`kind: knowledge`,流程沉淀型) |
| `aclgraph-cap-006` | capture 阶段触发 rtMemcpy / CPU↔NPU 拷贝被禁止(`kind: knowledge`,流程沉淀型) |
| `aclgraph-cap-007` | ACLGraph 通用定位手段速查 — 开日志/抓现场/定界方向(`kind: knowledge`,流程沉淀型) |
| `aclgraph-cap-008` | FULL_DECODE_ONLY 多档位入图 capture_graph_task `KeyError: 4` — `cudagraph_capture_size=[2,12,24]` 与 MTP3 错配,需把档位补到含 num_tokens 最小值 4 |
| `aclgraph-cap-009` | capture 阶段 107027 StreamSynchronize — `cudagraph_capture_sizes=[64]` > `max_num_seqs=32` 让 prefill 误入图;改启动脚本配置 capture_sizes ≤ max_num_seqs(或 capture_mode=FULL_DECODE_ONLY)解决,**不改代码** |

### runtime 阶段

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-cap-001` | Sleep/Wakeup 后多 wrapper (MTP) recapture 失败;全局 recapture 标记被首个 wrapper 消费后清除,后续 wrapper replay 旧图(case_id 前缀 cap-,文件在 runtime/ 下,phase=runtime) |
| `aclgraph-rt-003` | 多流场景子流输入 tensor 被主流提前回收,需 `record_stream` 延长生命周期 |
| `aclgraph-cap-004` | Wakeup 重捕获时 `aclnnNonzero` 访问已释放的 KV-cache 内存(507011)(case_id 前缀 cap-,文件在 runtime/ 下,phase=runtime) |
| `aclgraph-rt-004` | 静态算子 (Aclnn static_kernel) 执行/加载失败 — 8 步流程自查综述(`kind: knowledge`,流程沉淀型,非 incident) |
| `aclgraph-rt-005` | Super Kernel 范围内算子未融合(SK 断开)定位 — 5 类断开原因诊断流程沉淀(`kind: knowledge`,流程沉淀型,非 incident) |
| `aclgraph-rt-006` | 静态 kernel 下控核失效 — 匹配到不带控核的静态包(`kind: knowledge`,流程沉淀型,非 incident) |
| `aclgraph-rt-007` | Super Kernel 综合使用指南与诊断调优(`kind: knowledge`,流程沉淀型) |
| `aclgraph-rt-008` | 盘古模型适配 Super Kernel + DCCI 配置参考(`kind: knowledge`,流程沉淀型) |
| `aclgraph-rt-009` | 静态kernel 叠加 SuperKernel 编译 launchKernel — sqe 刷新与 kernel launch 检查规则不一致,Runtime KernelLaunch 流程重构需求 |
| `aclgraph-rt-010` | matmulV3 算子无法 SuperKernel 融合,多核同步模板要求 schedule_mode=1 与 SK 要求 schedule_mode=0 冲突 |
| `aclgraph-rt-011` | SuperKernel DCCI 优化配置 — GetValue/SetValue 自动刷新与 SK 框架全局刷新重复,通过 dcci_before_kernel_start / dcci_disable_on_kernel 消除 |
| `aclgraph-rt-012` | SuperKernel 融合断开 — Event Wait 占用 aicore 等待,Notify 调度风险时 SK 强制断开避免死锁(机制问题) |
| `aclgraph-rt-013` | AiInfraScatterBlockUpdate 算子全核同步导致 SK 融合断开,算子 BlockDim 小于 SK BlockDim 时 syncall 卡死,框架主动断开 |
| `aclgraph-rt-014` | 1.0.3 推理分支 sleep/wakeup + MTP 参数 update 报错 "The handle only can be updated by one stream";1.0.3 不同 wrapper 共用全局 graph_params,需按 layer_name 隔离(PR !1298 已合) |

### HS 团队案例 (无 phase)

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-cap-002` | capture 阶段存在未回归主流的 stream,导致 graph capture 失败 |
| `aclgraph-rt-001` | 控核 `limit_core_num` 不生效 — 大算子包裹整个 forward 后,控核仅对 Ascend C 算子生效,无法渗透 |
| `aclgraph-rt-002` | 运行阶段通信超时/卡死;需 Plog 区分算子卡死 / 通信超时 / 内存问题 |
| `aclgraph-tc-002` | Dynamo 在 run node 阶段执行 fake tensor 时,图内节点缺少 fake 实现 |
| `aclgraph-tc-003` | 已编译模型重复调用时触发重编译;常因输入 shape 变化 / dynamic 配置不当 / guard 失效 |

### 知识型案例 (knowledge/, 无 phase, 从 reference 拆分而来)

知识型案例不绑定 phase,靠关键词与场景词命中。源 reference 文档头部维护"拆分索引",反向指向各 kn-case。

#### superkernel/ (19 个,源 5 篇 reference)

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-kn-001` | SK 融合断开 §A — TBE/TIK 算子不支持融合（必须迁 AscendC） |
| `aclgraph-kn-002` | SK 融合断开 §B — 非 aicore (aicpu) 算子打断多流融合（task_breaker_bypass） |
| `aclgraph-kn-003` | SK 融合断开 §C — FA Host Tiling 刷新 SQE 路径不被支持（须拆 aicpu+aicore） |
| `aclgraph-kn-004` | SK 融合断开 §D — Event 相关（External / Memory / Wait 死锁三子类） |
| `aclgraph-kn-005` | SK 融合断开 §E — 全核同步且 BlockDim 不对齐 |
| `aclgraph-kn-006` | SK 配置 — `dcci_disable_on_kernel` 关闭 DCCI All 冗余刷新 |
| `aclgraph-kn-007` | SK 配置 — `auto_op_parallel` C-V 多流自动并行 |
| `aclgraph-kn-008` | SK 配置 — `aggressive_opt_strategies` 激进融合（task/value bypass） |
| `aclgraph-kn-009` | SK 调试选项 — `debug_sync_all` / `debug_op_exec_trace` / `debug_cross_core_sync_check` |
| `aclgraph-kn-010` | SK 调试 — 内部保存 tensor 默认导致融合断开（须配 task_breaker_bypass） |
| `aclgraph-kn-011` | SK Profiling — `ASCEND_PROF_SK_ON` 抓 SK 内部时序 |
| `aclgraph-kn-012` | SK + msprof — EventWait 时间被 ValueWait Profiling 缺陷拉长（观测端非真实劣化） |
| `aclgraph-kn-013` | SK 开启方式 — npugraph_ex 后端 + super_kernel_scope 范围标记 |
| `aclgraph-kn-014` | SK 算子适配 — `<<<>>>` 算子的 SK 入口与 SK_BIND 注册 |
| `aclgraph-kn-015` | SK 算子适配 — `<<<>>>` 算子的 tilingdata 常量折叠静态 kernel |
| `aclgraph-kn-016` | SK 算子适配 — aclnn 自定义算子全核同步与启动核数 4 条约束 |
| `aclgraph-kn-017` | omni-npu npugraph_ex 后端切换（torchair → 独立 npugraph_ex） |
| `aclgraph-kn-018` | SK + DCCI 策略 — 默认全关 + 5 个写共享内存算子前显式加 DCCI |
| `aclgraph-kn-019` | 新模型适配 SK 清单 — vLLM 配置 + 算子 DCCI 名单 + 验证步骤 |

#### static-kernel/ (7 个,源 2 篇 reference)

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-kn-020` | 静态 kernel 执行/加载失败 — 8 步诊断流程 |
| `aclgraph-kn-021` | 静态 kernel 不上板根因 — 算子在 Aclnn 黑名单（含 MC2 / 部分 AscendC） |
| `aclgraph-kn-022` | 静态 kernel 不上板根因 — runtime shape/dtype/format/attr 与编译 json 不匹配 |
| `aclgraph-kn-023` | 静态 kernel 不上板根因 — opp/static_kernel/ 被 PTA 进程结束清理 |
| `aclgraph-kn-024` | 静态 kernel 不上板根因 — 控核 (aic/aiv coreNum) 与编译期不一致 |
| `aclgraph-kn-025` | 静态 kernel 控核失效 — 7 步排查流程（首图→终图→RTS→enqueue→dequeue→GetRes→Launch） |
| `aclgraph-kn-026` | 静态 kernel 控核根因 — 多个静态包,Aclnn 选到无控核版本 |

#### capture/ (2 个,源 1 篇 reference)

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-kn-027` | ACLGraph 动态 shape 导致 stream/event 资源耗尽（"resources are insufficient"） |
| `aclgraph-kn-028` | ACLGraph kv-cache 最大值预分配模式（避免 shape 变化触发 re-capture） |
| `aclgraph-kn-032` | 多档位 Eq guard 修复必须分层加固 — 边界 custom op + 调用层 batch min 对齐 + 下游 view 显式 SymInt 三件套(从 [[aclgraph-tc-017]] 复盘提炼;`kind: knowledge`,流程沉淀型) |

#### debug-toolkit/ (3 个,源 1 篇 reference)

| Case ID | 一句话 |
|---------|--------|
| `aclgraph-kn-029` | 诊断工具 — Plog (NPU Runtime) 日志开启与常用 grep |
| `aclgraph-kn-030` | 诊断工具 — TORCH_COMPILE_DEBUG 抓 FX 图（首图/终图） |
| `aclgraph-kn-031` | 诊断工具 — 同步阻塞调试与其他常用环境变量速查 |

### 案例类型约定

- 默认是 **incident 型** —— 某次具体故障的复盘(根因 + 修复 + PR + 短期规避)
- `kind: knowledge` 标记的是 **流程沉淀型** —— 一类问题的诊断流程总结,不绑定单次事件(例:`aclgraph-rt-004` 静态算子)
- `status: unresolved-but-workaround-verified` 标记的是 **未结案** —— 已有可用 workaround,但根因仍在追(例:`aclgraph-tc-005`)
- `aclgraph-kn-NNN` 前缀 + 位于 `knowledge/cases/kn/<topic>/` 是 **知识型** —— 从 reference 拆分而来,聚焦单一症状/操作/规则,无 phase 字段