# 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-07-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # aclgraph 问题定位 agent 面向 vLLM + omni-npu NPU 部署场景的**Router Skill + Handoff 对接 Skill + 两个 Subagent + 分层诊断 Skill 套件**: 日志输入 → aclgraph-diagnostic-router skill → diagnostic-instrumentation Subagent → L1 阶段识别/充足性判断 → L2 专用深度分析 → L3 案例库兜底 → case-manager 闭环复盘。 ## 项目定位 本项目**不是**单一 skill,而是一组协作的 Agent / Subagent / Skills,共享同一个知识库: | 组件 | 作用 | |------|------| | **Router Skill** (`skills/aclgraph-diagnostic-router/SKILL.md`) | 面向用户和其他 skill 的唯一逻辑入口,负责识别意图、调度 Subagent、汇总结果 | | **Handoff Skill** (`skills/aclgraph-diagnostic-handoff/SKILL.md`) | 面向其他 skill 的受控对接协议,归一化上游输入后转入 router | | **Subagents** (`agents/*.md`) | `diagnostic-instrumentation` 执行 L1→L2/L3 诊断; `case-manager` 执行总结、入库、闭环 | | **Claude Code Skills** (`skills/*/SKILL.md`) | 专项诊断 playbook; 默认由指定 Subagent 点名加载,L2/L3/closure 不作为外部直连入口 | | **共享知识库** (`knowledge/`) | L1 规则 (`l1_rules.yaml`) + 案例库 (`cases/*.yaml`) | | **闭环产物** (`diagnostics/`) | 诊断总结 + 闭环复盘（合并在同一目录） | ## 分层诊断架构 ``` 用户输入（范围不明的推理部署问题） │ ▼ ┌─────────────────┐ │ SkillBackup │ L0 预分诊（可选上游入口） │ inference-debug │ │ skillset │ └────────┬────────┘ │ ┌───────────┴───────────┐ │ 是否 ACLGraph 入图问题？ │ │ (多档位/图捕获/static │ │ kernel/recapture/精度) │ └───────────┬───────────┘ │ ┌───────────┴───────────┐ │ │ 是 否 │ │ ▼ ▼ aclgraph-diagnostic SkillBackup 内部继续 (本项目的 primary) (owner 定位 / online / Git) │ ▼ ┌───────────────────┐ │ 命中精度关键词？ │ └─────────┬─────────┘ │ ┌───────┴───────┐ 是 否 │ │ ▼ ▼ npugraph-ex-precision L1 diagnostic-instrumentation -debug (primary 直接调用) · 信息收集 · 阶段识别 · 日志充足性判断 · 路由决策 │ ┌────────────┼────────────┐ ▼ ▼ ▼ L2 路由匹配 L2 路由匹配 L3 兜底 │ │ │ ┌───▼───┐ ┌─▼───────────┐ ┌▼─────────────────┐ │ L2 │ │ L2 │ │ L3 aclgraph- │ │ multi-│ │ static-kernel│ │ general-expert │ │ tier- │ │ -analysis │ │ knowledge/cases/ │ │analysis│ │ (8 步自查) │ │ 相似度评分匹配 │ │(Dynamo│ └──────┬───────┘ └───────────────────┘ │ guard)│ │ └───┬───┘ │ │ │ │ ┌──────────┼──────────┐ │ │ │ │ │ ┌─▼───┐ ┌──▼─────────┐ ┌▼──────────────────┐ │ │ L2 │ │ L2 │ │ L2 │ │ │ acl-│ │ capture- │ │ custom-op-meta │ │ │graph│ │ config- │ │ -debug │ │ │-re- │ │ validator │ │ (fake/meta/guard) │ │ │capture│ └────────────┘ └───────────────────┘ │ │-debug│ │ └──┬───┘ │ │ └─────┼─────┘ │ ▼ (诊断完成,任何路径终态都触发) ┌─────────────────────────────────────────────────┐ │ diagnostic-closure (跨层,非"另一层") │ │ 阶段 1: 诊断结束 → diagnostics/ 生成 AI 总结 │ │ 阶段 2: 用户提供真实解法 → diagnostics/ 复盘 │ │ 对照 AI 分析 vs 真实方案,改进 case 库 / skill │ └─────────────────────────────────────────────────┘ ``` ### 各层职责边界 | 层 | Skill / Agent | 干什么 | 不干什么 | |----|-------|--------|---------| | **L0** | `inference-debug-skillset` (SkillBackup) | 上游预分诊：划分问题范围，识别是否 ACLGraph 入图问题 | 不做 ACLGraph 专项根因分析；不直接调用 diagnostic-instrumentation | | **Primary** | `aclgraph-diagnostic` (`AGENTS.md`) | 接收 SkillBackup handoff 或直接用户输入；按精度豁免/诊断/闭环规则二次路由 | 不做 L1/L2/L3 深度分析 | | **L1** | `diagnostic-instrumentation` | 信息收集 + 阶段识别 + 充足性 + 路由 + 自主重跑 | 不做根因深度分析、不做案例匹配 | | **L2** | `multi-tier-analysis` | 多档位 shape mismatch / Dynamo guard 硬编码值定位 | 不做静态 kernel / recapture / 配置错配 | | **L2** | `static-kernel-analysis` | 静态算子 (Aclnn static_kernel) 8 步流程自查 | 不做动态算子定位、不做性能 | | **Primary 直接调用** | `npugraph-ex-precision-debug` | 多档位+多流+控核叠加精度异常诊断 | 不做 shape mismatch / 静态 kernel | | **L2** | `aclgraph-recapture-debug` | sleep/wakeup recapture 失败 / 多 wrapper 状态共享 | 不做配置错配（先走 capture-config-validator） | | **L2** | `capture-config-validator` | capture 配置快查（capture_sizes / max_num_seqs / MTP 错配） | 不做代码级根因分析 | | **L2** | `custom-op-meta-debug` | 自定义算子入图全链路调试（Meta/Fake/DCE/静态编译/direct_register_custom_op/框架适配） | 非自定义算子问题 | | **L3** | `aclgraph-general-expert` | 案例库匹配 + 通用兜底分析 | 不替代 L1 前置准备 | | **跨层** | `diagnostic-closure` | 诊断后写总结、对照真实解法做复盘 | — | ## 目录结构 ``` skill/ ├── README.md # 本文档 ├── agents/ # Subagents │ ├── diagnostic-instrumentation.md │ └── case-manager.md ├── CONTRIBUTING.md # 贡献指南 ├── Makefile # 常用命令快捷入口 │ ├── skills/ # Claude Code Skills (markdown,Claude Code 自动加载) │ ├── aclgraph-diagnostic-router/ # Router — 用户/其他 skill 的唯一逻辑入口 │ │ └── SKILL.md │ ├── aclgraph-diagnostic-handoff/ # 对接 — 上游请求归一化后转入 router │ │ └── SKILL.md │ ├── 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/ # Primary 直接调用 — 多档位精度异常 (含 references/) │ │ ├── SKILL.md │ │ └── references/ │ ├── aclgraph-recapture-debug/ # L2 — sleep/wakeup recapture │ │ └── SKILL.md │ ├── capture-config-validator/ # L2 — capture 配置快查 │ │ └── SKILL.md │ ├── custom-op-meta-debug/ # L2 — 自定义算子 meta/fake │ │ └── SKILL.md │ ├── aclgraph-general-expert/ # L3 — 案例库兜底 │ │ └── SKILL.md │ └── diagnostic-closure/ # 跨层 — 诊断后闭环 │ └── SKILL.md │ ├── knowledge/ # 共享知识库 │ ├── l1_rules.yaml # L1 引擎阶段定义 + scenarios + 路由配置 │ ├── cases/ # L3 案例库 │ │ ├── aclgraph/ # omni-npu / aclgraph 相关案例 │ │ │ ├── torch_compile/ # aclgraph-tc-001.yaml ~ aclgraph-tc-004.yaml, tc-006.yaml, tc-009~018.yaml 等 (精度相关已迁 precision/) │ │ │ ├── capture/ # aclgraph-cap-005.yaml, aclgraph-cap-006.yaml, aclgraph-cap-007.yaml │ │ │ ├── runtime/ # cap-001/004.yaml + rt-004~008.yaml (rt-003 精度相关已迁 precision/) │ │ │ ├── precision/ # aclgraph-tc-005/007/008/016/019/022 + aclgraph-rt-003 (精度相关案例) │ │ │ └── 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 │ ├── diagnostics/ # 诊断总结 + 闭环复盘文档 │ ├── README.md # 总结格式规范 + 归档索引 │ └── YYYYMMDD--.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 # 交互式创建新案例 │ └── docs/superpowers/ # 设计文档与实施计划归档 ├── specs/ # 设计文档 └── plans/ # 实施计划 ``` ## 诊断路径 ### 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/ ``` > **精度问题旁路**：若用户描述命中精度关键词（精度异常 / 输出不对 / eager vs graph 不一致等），Primary 会直接调用 `npugraph-ex-precision-debug`，不经过 L1 路由。 ## 快速开始 ### 一键安装(推荐) ```bash git clone https://gitee.com/chen-junhao1234/skill cd skill ./scripts/install.sh ``` 安装后在任意目录打开 Claude Code,直接提交日志即可: ``` 用户: server.log 里有报错,帮我看看 Claude: [自动加载 diagnostic-instrumentation L1 skill] [按步骤收集信息 → 路由 → 调用对应 L2 / L3] → 输出诊断报告 [diagnostic-closure 自动写 diagnostics/<...>.md] ``` ### 卸载 ```bash ./scripts/uninstall.sh ``` ## 知识库维护 ### 新增案例 直接在 `knowledge/cases//` 对应子目录下新建 YAML(`torch_compile/` / `capture/` / `runtime/`),无需重建索引,启动时递归加载。 文件名格式 `aclgraph--.yaml`(与 case_id 字段保持一致,按阶段分目录存放),case_id 字段为 `aclgraph--`。 字段约定参考 `torch_compile/aclgraph-tc-001.yaml`(incident 型)或 `runtime/aclgraph-rt-001.yaml`(`kind: knowledge` 流程沉淀型)。 GE 相关案例放在 `knowledge/cases/ge/` 下,文件名格式 `ge-.yaml`。 ### 调整 L1 路由规则 直接编辑 `knowledge/l1_rules.yaml`: - `phases` 控制阶段识别的关键字与权重 - `scenarios` 控制路由决策。每个 scenario 含 `indicators`(关键词 + log_patterns)、`sufficiency`(必填特征 + 必须环境变量)、`routing.l2_skill` / `routing.l3_case_id`。 ## 扩展指南 ### 新增 L2 在 `skills//` 下新建 SKILL.md + 可选 `references/*.md`,然后更新 `l1_rules.yaml` 的 `routing.l2_skill` 和 `diagnostic-instrumentation` 的 L2 表与路由表。 ### 新增/修改诊断流程 - 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-18) - L1: 1 个 skill（diagnostic-instrumentation） - L2: 6 个（multi-tier-analysis / static-kernel-analysis / aclgraph-recapture-debug / capture-config-validator / custom-op-meta-debug / torch-compile-error-diagnosis） - 精度豁免直接调用：1 个（npugraph-ex-precision-debug） - L3: 1 个 skill + 81 个案例（事件型 49 个 + 知识型 32 个；其中 HS 团队早期通用案例 5 个已独立编号为 aclgraph-hs-NNN），详见下方"L3 案例库速览" - references/: 10 篇（SK 5 + static-kernel 2 + capture 1 + debug-toolkit 1 + ACLGraph 设计文档 1） - 闭环: 1 个 skill（diagnostic-closure 三入口路径）+ `diagnostics/`（16 份文档：14 已闭环 + 2 待验证） - **合计 12 个 Skill**（Router×1 + 对接×1 + L1×1 + L2×6 + 精度豁免×1 + L3×1 + 跨层×1） - 另有 `skills/aclgraph-handoff-demo/` 保留作为 handoff -> router 链路的测试载体，不列入正式 Skill 一览 - **设计模式**: 新增 L2 采用「锚定-注入-开放」(Anchor-Inject-Open) 三段式结构：标准化检查 → 案例上下文注入 → 灵活推理 ### 案例库全景图 ```mermaid pie title 案例库总览 (77 个) "事件型 (incident)" : 38 "知识型 (knowledge)" : 39 ``` ```mermaid pie title 事件型案例 — 按阶段分布 (38 个) "torch_compile" : 14 "runtime" : 8 "precision" : 7 "capture" : 5 "hs (无 phase)" : 5 ``` ```mermaid pie title 知识型案例 — 按主题分布 (39 个) "superkernel" : 19 "static-kernel" : 7 "runtime (phase 内)" : 5 "debug-toolkit" : 3 "capture (phase 内)" : 2 "capture (kn/)" : 3 ``` ```mermaid pie title 诊断闭环文档状态 (16 份) "已闭环 🟢" : 14 "待验证 🟡" : 2 ``` > **说明**: 知识型案例共 39 个 = kn/ 目录 32 个 + phase 目录内 `kind: knowledge` 的 7 个（capture/ 2 个 + runtime/ 5 个）。事件型案例 39 个 = phase 目录内非 knowledge 的案例（torch_compile/14 + runtime/8 + precision/7 + capture/5 + hs/5）。 ## L3 案例库速览 事件型案例按问题暴露阶段分目录存放(`knowledge/cases//aclgraph-.yaml`)。详细字段(`triggers` / `verified_isolations` / `fix` 等)见对应 yaml。 知识型案例（从 reference 拆分而来）按主题分目录存放(`knowledge/cases/kn//aclgraph-kn-NNN.yaml`),无 phase 字段、team 留空,靠 keywords 命中。GE 相关案例放在 `knowledge/cases/ge/` 下。 ### torch_compile 阶段 (14 个，全部 incident) | 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) | | `aclgraph-tc-018` | Pangu-35B 静态 kernel OPC 编译失败：Pioneer 算子包 include 路径与 OPC PRECOMPILE include context 不兼容；AiInfraAttentionPioneer 的 arch35/ 和 ../../common/ 路径在静态编译下失效，SparseFlashAttentionPioneer fallback 路径缺少 op_kernel/ 子目录 + arch35/util.h 缺失；PR !75 (#if __has_include 守卫 12 个文件) + PR !115 (修正 fallback + 补 util.h) 已合入 | | `aclgraph-tc-019` | npugraph_ex 评测集精度偏差+卡死：(1) 自定义算子注册无返回值被 Dynamo DCE 消除(AiInfraScatterBlockUpdate/npu_apply_rotary_pos_emb);(2) capture 前 torch.compile 触发 metadata 缓存命中导致算子不执行 | | `aclgraph-tc-020` | torch.compile + HSDP _forward_pre_hook 冲突：Dynamo 追踪 compiled layer 时 hook 内遍历 named_modules，同一 module 对象经两条路径被追踪触发 mutation tracking AssertionError；_forward_hook 同需禁用（setattr NPU Layout unhashable）；两个 hook 必须在 fully_shard 之前 dynamo.disable | | `aclgraph-tc-021` | 手动 compile 子模块后 accelerator.prepare KeyError _orig_mod：has_compiled_regions 返回 True 但顶层 __dict__ 无 _orig_mod（只有 compile_regions() 才设置），修复=在 _prepare_fsdp2 调用 _get_named_parameters 前设置 model.__dict__["_orig_mod"]=model | ### capture 阶段 (7 个：5 incident + 2 knowledge) > cap-005、cap-007 为 `kind: knowledge` 流程沉淀型，其余为 incident 型。 | 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)解决,**不改代码** | | `aclgraph-cap-010` | capture 阶段 107024 rtStreamWaitEvent — `sub_stream.wait_stream()` 被放在 `if layer.shared_experts is not None:` 之外,shared_experts=None 时 wait 泄漏无对应 record;将 wait_stream 移入 if 块内(一行)修复(compressed_tensors_moe.py) | | `aclgraph-cap-011` | pangu_omni 3B/5B capture 阶段 561103 — `aclnnRotaryPositionEmbeddingV2` 算子不支持 CUDAGraph 多档位 capture,首档 tiling/workspace 状态未刷新导致第二档 JudgeLayoutByShape 失败;临时规避=回退 list comprehension 写法恢复 graph break,根治需算子修复 | ### runtime 阶段 (13 个：8 incident + 5 knowledge) > rt-004~008 为 `kind: knowledge` 流程沉淀型，其余为 incident 型。 | Case ID | 一句话 | |---------|--------| | `aclgraph-rt-001` | Sleep/Wakeup 后多 wrapper (MTP) recapture 失败;全局 recapture 标记被首个 wrapper 消费后清除,后续 wrapper replay 旧图(case_id 前缀 cap-,文件在 runtime/ 下,phase=runtime) | | `aclgraph-rt-003` | 多流场景子流输入 tensor 被主流提前回收,需 `record_stream` 延长生命周期 | | `aclgraph-rt-002` | 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，独立编号空间 aclgraph-hs-NNN) > 原案例曾占用 cap-002 / rt-001 / rt-002 / tc-002 / tc-003 编号，与 omni-npu 实战案例（runtime/ 下的 rt-001/rt-002 为 wakeup recapture 507011）case_id 冲突，已统一改为 hs-NNN 独立编号。 | Case ID | 一句话 | |---------|--------| | `aclgraph-hs-001` | capture 阶段存在未回归主流的 stream,导致 graph capture 失败 | | `aclgraph-hs-002` | 控核 `limit_core_num` 不生效 — 大算子包裹整个 forward 后,控核仅对 Ascend C 算子生效,无法渗透 | | `aclgraph-hs-003` | 运行阶段通信超时/卡死;需 Plog 区分算子卡死 / 通信超时 / 内存问题 | | `aclgraph-hs-004` | Dynamo 在 run node 阶段执行 fake tensor 时,图内节点缺少 fake 实现 | | `aclgraph-hs-005` | 已编译模型重复调用时触发重编译;常因输入 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//` 是 **知识型** —— 从 reference 拆分而来,聚焦单一症状/操作/规则,无 phase 字段