ascend-ai-coding Ascend C Matmul 单算子生成（Blaze 路径）
该能力解决 Matmul 单算子生成场景下的问题：tensor_api/Blaze API 约束确认、三模板选型（纯AIC / StreamK / FixpOpti）、统一工程模板复用、SWAT/全载 Tiling 改造、流水与排错。
架构限定：核心验证在
DAV_3510。其他架构必须在 DESIGN.md 中显式说明差异并给出适配方案。
首次使用：
matmul_custom/依赖tensor_api/，首次需拉取外部依赖。步骤见matmul_pattern.md§0.5.0。
何时使用
满足以下任一条件时使用该能力：
- 算子类型为 Matmul 族（GEMM/BMM/量化 matmul/matmul+bias/mxfp8 matmul）。
- 代码或讨论中出现
tensor_api、blaze等信号。 - 需要选择模板（纯AIC/StreamK/FixpOpti）、切换 dispatch mode（NO_FULL/A_FULL/B_FULL_LOAD）、进行 Tiling 改造或流水排错。
不要把该能力当成默认算子开发路径的通用替代品。Vector 类逐元素/归约算子、matmul+eltwise 深度融合（含激活/残差等 Vector 后处理）、matmul+softmax 等不在本 skill 模板直接覆盖范围内；这些场景使用本 skill 的 FixpOpti 模板做 Cube 段，epilogue 部分需自行扩展。
三模板速览
| 模板 | 典型场景 | 交付状态 |
|---|---|---|
| 纯AIC | 通用场景（默认） | 已交付 |
| StreamK | MN 欠并行 + 长 K（≥4096） | 设计文档 |
| FixpOpti | AIC/AIV 流水重叠、可定制 epilogue | 已交付 |
三模板共享同一基底
references/matmul_custom/（common/、tiling/、scheduler/、utils/）。 FixpOpti 专用文件（matmul_fixpopti.cpp、matmul_kernel_fused.h、epilogue/）也在该目录中。
详细对比（执行模式、调度器、同步机制、Workspace、ASCII 数据流图、决策树）见
matmul_pattern.md§10，此处不重复。
按角色/阶段查阅
阅读顺序：先速览 tensor_api_user_guide.md 了解 API → matmul_pattern.md §10 选模板 → 纯AIC 路径继续 §0 选 mode → §0.5 复制+改造 → 共享基础 §1–§9 + 专属深度文档。
| 阶段/角色 | 主文档 | 辅助 / 深度 |
|---|---|---|
| 方案决策（Architect） | matmul_pattern.md §10 三模板选择 + §0 模式总览 |
tensor_api_user_guide.md（API 速查） |
| 设计（Architect） | 选定模板后进入深度文档：- 纯AIC：matmul_basic.md / matmul_full_load.md- StreamK：matmul_streamk.md- FixpOpti：matmul_fixpopti.md |
matmul_pattern.md §1–§9 共享基础 |
| 实现（Developer） | 统一从 references/matmul_custom/ 基底出发：纯AIC → matmul_custom.cpp（[MODIFY] N/C/A）FixpOpti → matmul_fixpopti.cpp（[MODIFY] N/C/A/E），按 matmul_fixpopti.md §3 改造 |
matmul_fixpopti.md（改造食谱） |
| 审查（Reviewer） | matmul_pattern.md §8 排障速查 |
对应模板深度文档的「常见陷阱」表 |
| 修复调试 | matmul_pattern.md §8（编译期 / 精度 / 跑通自检） |
matmul_fixpopti.md §6 陷阱表 |
约束
- 架构验证范围：DAV_3510。其他架构因
tensor_api依赖和 L1/L0 容量差异，可能不兼容。 - 全载交付状态：
A_FULL_LOAD_MODE已落地（matmul_block_mmad_a_full_load.h+MatmulTilingAFullLoad，3 行 diff 切换）。B_FULL_LOAD_MODE仅有设计草案（见matmul_full_load.md§3.2 / §4.2 / §4.3），仓库中无B_FULL_LOAD_MODE常量、MatmulMultiBlockPolicy<B_FULL_LOAD_MODE>特化、MatmulSwatScheduler<B_FULL_LOAD_MODE>selector、MatmulTilingBFullLoad类、matmul_block_mmad_b_full_load.h头文件——使用前必须按对称设计自行镜像补齐，不能套用matmul_pattern.md§0.5.3 的切换 diff（B 全载段已替换为告警 NOTE）。 - 模板复制起手：纯AIC 从
references/matmul_custom/matmul_custom.cpp入手，FixpOpti 从references/matmul_custom/matmul_fixpopti.cpp入手；两条路径共享references/matmul_custom/下的 common/、tiling/、scheduler/、utils/。均按[MODIFY]标记改造。FixpOpti 额外需要：(1) 替换启动器matmul_custom.cpp→matmul_fixpopti.cpp，(2) BlockMmad 的CopyL0C2GM改为CopyL0C2UB+SPLIT_M Trait（见matmul_fixpopti.md§3.5），(3) 新增matmul_kernel_fused.h和 epilogue 文件。比纯AIC 多一档[MODIFY] E用于自定义 Epilogue。 - API 签名不猜测：
AscendC::Te::系列接口有大量重载和模板特化。查阅references/tensor_api_user_guide.md或官方文档。 - 伪代码不等于可编译实现：设计文档中的代码片段为说明概念而简化。写代码时回到对应模板工程——细节已处理好。
- mode 和模板选择说明依据：在 DESIGN.md 中写清楚为何选这个 mode/模板。
与 CANNBot 集成
| CANNBot 阶段 | 调用方 | 加载方式 |
|---|---|---|
| Step 2 设计 | Architect Subagent | 当用户需求路径判定为「tensor_api / CUTLASS 风格 API」时显式加载本 skill |
| Step 3 开发 | Developer Subagent | 按设计选定模板，复用模板工程 |
| Step 4 审查 | Reviewer Subagent | 用 matmul_pattern.md §8 排障速查交叉验证 |