@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/design_sample/flash_attn-arch35-best-practices.md

@@ -0,0 +1,80 @@
+# flash_attn 最佳实践（arch35 / Ascend950PR / DAV_3510）
+
+> 非量化 GQA FlashAttention，FP16/BF16 only。源算子：`ops-transformer/attention/flash_attn`。
+> 芯片口径：L1 512KB、L0A/L0B 64KB、L0C 256KB、UB 248KB/AIV、Cube:Vector=1:2。
+
+## S1 选型
+
+- 基础形态：**GQA**（M = Sq×G 合轴，I2），MHA 为 G=1 退化。
+- trait：无（`flash_attn_template_tiling_key.h` 文件头明确"非量化，仅FP16/BF16"，`NoQuantMode=31`）。
+- Feature：causal / attenMask / sinks（kernel 已实现、接口未开放）/ softmax_lse。
+
+## S2 计算流
+
+标准 C1→V1→C2→V2。arch35 特有：
+- L0C→UB 走 **FixPipe 双目标写**：ND `dualDstCtl=1`、DN `dualDstCtl=2`，S/O_tile 从 L0C 直接按 M 维对半写入 2 个 AIV 的 UB，不落 GM。
+- P 在 UB 侧 cast FP16 并**排成 NZ** 再经 UB→L1（仅 NZ 通路）供 C2。
+
+**ND vs DN 双模板**（[flash_attn_tiling.cpp](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_host/arch35/flash_attn_tiling.cpp) `UpdateTilingKeyTemplateId`）：
+- ND（templateId=0）：全功能通用路径，支持 attenMask、全部 config。
+- DN（templateId=1）：性能特化，仅 `!hasAttenMask && config∈{0,2,6}`（mBaseSize=64 且 D≤128 或 192/128）启用；BMM1 转置计算（K 作左矩阵 Q 作右矩阵），省 mask copyIn。
+- 规则：**功能全集走 ND，热点无 mask 场景叠加 DN，tilingKey 静态分流**。
+
+## S3 基本块（编译期常量，8 档 config）
+
+来源：[fa_adjust_sinner_souter.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_host/fa_adjust_sinner_souter.h)、[flash_attn_template_tiling_key.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_kernel/arch35/flash_attn_template_tiling_key.h)
+
+| config | mBaseSize×s2BaseSize | D(qk,v) |
+|---|---|---|
+| 0/1 | 64×128 / 32×256 | (64,64) |
+| 2/3 | 64×128 / 32×256 | (128,128)，**D=72 复用此模板**（L1 pad 72→80 分形对齐，Mmad K=72 精确） |
+| 4/5 | 64×128 / 32×256 | (256,256) |
+| 6/7 | 64×128 / 32×256 | (192,128) MLA 形态 |
+
+- 默认 **64×128**；仅当 vHeadDim≤128 且 maxSeqQ≤64、maxSeqKv>128 等 decode 短行条件时切 **32×256**——按 shape 属性静态分流，无运行时动态块。
+- kernel 侧实际生效 `mBaseSize_effective = mBaseSize × r_cv`（64→128，32→64），s2BaseSize 不变。
+
+## S4 Buffer 清单（实测份数）
+
+来源：[flash_attn_block_cube_nd.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_kernel/arch35/flash_attn_block_cube_nd.h)、[flash_attn_block_vec_nd.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_kernel/arch35/flash_attn_block_vec_nd.h)
+
+| Buffer | 层 | dtype/格式 | 份数 |
+|---|---|---|---|
+| Q | L1 | INPUT_T/NZ | 2 |
+| K/V 共享槽池 | L1 | INPUT_T/NZ | **4×64KB**（config=5 时 2×128KB `L1_KV_LARGE_BUF`） |
+| P | L1 | INPUT_T/NZ | 3 |
+| L0A / L0B / L0C | L0 | — | 2 / 2( config=5 退 1) / **4×64KB** |
+| mmRes（S 与 O_tile **同槽复用**） | UB | FP32/ND | 4（D≤128）/ 2（D=256） |
+| vec1Res（P） | UB | FP16/NZ | 2（每份 +1 行错 bank） |
+| vec2Res（O_acc） | UB | FP32/ND | 1 |
+| softmaxSum/Max/Exp | UB | FP32 | 各 3，按 `loop%3` 轮转 |
+| maskBuffers | UB | uint8 | 2×8KB（仅 ND 有 mask） |
+
+- UB 布局 `static_assert(sizeof(UbLayout) ≤ 248K)` 编译期兜底。
+- S/O_tile 同槽复用由单调计数器 `mmResBufId_=(id+1)%4` 错开分配。
+
+## S5 流水编排
+
+来源：[flash_attn_kernel_nd.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_kernel/arch35/flash_attn_kernel_nd.h)
+
+- **任务级 2 级 preload**：`PRELOAD_N=2`，本轮跑 MM1/Vec1，`loop≥2` 时跑 2 轮前的 MM2/Vec2（MM1(j) ∥ MM2(j−2)）。
+- Cube 内部 MTE2→MTE1→M→FIX 硬件流水，靠 buffer 多份轮转。
+- 同步：跨核 flag `CROSSCORE_MM_0~3`（S/O_tile）、`CROSSCORE_L1P_0~2`（P），双 AIV 用 `AIV0_AIV1_OFFSET=16` 双路 flag；FD 段前后 `SyncAll()`。
+
+## S6 负载均衡
+
+- 任务维度：**B × N2 × gS1 × s2** 四维，metadata 由 AICPU 算子 `flash_attn_metadata` 预生成（每 AIC 16 字段：bN2/gS1O/s2O Start/End + firstFdDataWsPos），kernel 不现场算均衡。
+- **SectionStreamK**：按 L2 96MB 预算切 section，成本模型 `6*ceil(m/16)+10*ceil(s2/64)`；`maxCore=min(36, 块数)` 截断核数（核数运行时输入，禁止硬编码）。
+- **FlashDecode**（[flash_attn_block_vec_flashdecode.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/flash_attn/op_kernel/arch35/flash_attn_block_vec_flashdecode.h)）：`fdBalanceMBaseSize=8` 行一组；`preLoadNum_=2` 双 buffer 预取 accumOut；FD 区与 FA 区 **UB 分时复用**（FD base=FA mmRes 区大小）；`ComputeScaleValue` 归约各 split 的 m/ℓ，`ReduceFinalRes_VF` 加权累加除 ℓ_global。FA 段按 AIC 分核、FD 段按 AIV 分核。
+- causal：无 zigzag，`CalcCurS2StartEndWithSparse` token→block 窗口换算整块跳过。
+
+## S7 自检结论
+
+- K/V 槽池 4 ≥ r+1；状态 buffer task 内恒 1；L0A/L0C pingpong，L0B 仅 config=5（s2BaseSize=256 且 D>128）容量所迫退单 buffer（显式标注的退化，非设计目标）。
+- UB 按每 AIV 校验：ND `(actM+1)/2` 行、DN `align32(actM)/2` 行；L1/L0 按全量 mBaseSize 校验。
+- I4：split-KV 配 AIV 侧 log-sum-exp 归约；I5 不适用（无量化）。
+- 数值：RowInvalid 行（max=−inf）输出清零、LSE 置 3e+99；mask 用有限负数。
+
+## 平台依赖
+
+FixPipe 双目标写（dualDstCtl）、KERNEL_TYPE_MIX_AIC_1_2、L2 96MB 预算切 section——均为 arch35/950PR 实测口径；核数 28/32 运行时查 `PlatformAscendC`。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/design_sample/quant_flash_attn-arch35-best-practices.md

@@ -0,0 +1,67 @@
+# quant_flash_attn 最佳实践（arch35 / Ascend950PR / DAV_3510）
+
+> 量化 GQA FlashAttention，三套 dtype：FP8(E4M3) / HIF8 / MXFP8。源算子：`ops-transformer/attention/quant_flash_attn`。
+
+## S1 选型
+
+- 基础形态：GQA。trait：**量化**（Q/KV dtype ∉ {fp16,bf16}），按 dtype 分三套独立 kernel/tiling。
+- quantMode 编码（[quant_flash_attn_template_tiling_key.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/quant_flash_attn/op_kernel/arch35/quant_flash_attn_template_tiling_key.h)）：0=HIF8_FP32、1=MXFP8_PREFILL、2=MXFP8_DECODE、6=GQA_FP8_FULLQUANT。注册优先级 mxfp8=1、fp8=2、hif8=3。
+
+## 三套量化路线的本质差异（核心蒸馏）
+
+| 维度 | FP8 GQA Fullquant | HIF8 | MXFP8 |
+|---|---|---|---|
+| 量化粒度 | Q/K per-token-per-head、V per-head、P per-tensor | 全 per-tensor 标量 | Q/K/V/P per-block E8M0（2 的幂） |
+| **AntiQuant 位置** | **全在 AIV**：cube 纯 FP8 matmul，descale 融进 Vec1 softmax / Vec2 乘 V scale | **全在 AIV**：cube 传 dummyScale，Vec1 乘 descaleQK、Vec2 乘 vScale | **全在 AIC 硬件原生**：`MatmulFullMX` 把 E8M0 scale 作为 GEMM 输入，AIV 零 dequant |
+| scale 驻留层 | **UB**（vec 侧消费）：Q scale 沿 S1 轴拷 UB，K scale 沿 S2 轴双缓冲拷 UB | 无逐 token scale buffer，3 个标量 | **L1**（cube 侧消费）：Q/K scale 沿 D 轴 per-32 组、V scale 沿 S2 轴 per-64 组驻留 L1 |
+| KV 布局 | 强制 PA_BnNBsD | BSND/SBND/BNSD/TND/NTD | NO_PA/PA_BBND/PA_BNBD/PA_NZ |
+| FlashDecode | 无 | 无 | **有**（quantMode=2） |
+
+**蒸馏规则**：
+1. **scale 跟随消费方驻留**：AIV 反量化 → scale 进 UB；cube 硬件反量化 → scale 进 L1 与数据同层。不用 FB/BT。
+2. **I5 轴对齐实测**：Q/K scale 沿 reduction 轴（D 轴 per-32 组）；**V scale 沿 S_k 轴（per-64 组，不是 D）**——V 在 [B,Sk,Hkv,D] 下 innermost 是 D，但 P·V 的 reduction 轴是 S_k。
+3. **MXFP8 的 P scale 反向回传**：AIV Vec1 在 UB 生成 per-32 E8M0 scale（`pScaleByteOffset=16640`），写回 **L1P 尾部**（`pScaleL1Offset=mBaseSize*s2BaseSize`）供 cube MM2 消费；DN 路径 fake scale 填 `0x7f7f`（E8M0 中 2^0=1.0 恒等编码）。
+
+## S3 基本块（量化对 tile 的修正）
+
+来源：[qfa_adjust_sinner_souter.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/quant_flash_attn/op_host/qfa_adjust_sinner_souter.h)
+
+- **mBaseSize 恒 64**（kernel 生效值 = 64×r_cv = 128，与非量化一致）。
+- **s2BaseSize：FP8/HIF8 → 256，MXFP8 → 512**，D=256 时回落 256。
+- 对照 fp16 FIA 默认 s2BaseSize=128：**量化只放大 S2 方向基本块，不动 mBaseSize/D tile**。原因：FP8 字节宽减半 → AI_HBM 翻倍、K/V 驻留 L1 容量压力减半；MXFP8 dequant 在 cube 内免费 → 需要更大 S2 tile 喂饱 Cube 并摊薄 AIV softmax。
+- MXFP8 kernel 内再按 `s2SplitSize=(dBase==256)?128:256` 把 512 切 subLoop，奇偶交替用 `l1PBuffers_.Get()/GetPre()` 控制 L0 占用。
+
+## S4 Buffer 清单
+
+| Buffer | FP8/HIF8 | MXFP8 |
+|---|---|---|
+| L1 | Q/K/V + P（`BuffersPolicy3buff<L1>`），L1 总预算恒 `Init(512KB)` | 同左 + Q/K/V scale 随数据驻留 |
+| UB | bmm1 ×2（`BuffersPolicyDB`）、bmm2 ×1、stage1OutQue 各 16640B；FP8 另有 Q/K scale UB 缓冲（K scale ×2 各 `(s2BaseSize+8)*4*4`B，4 份解 bank 冲突） | stage1OutQue 各 16896=16640+256B（P scale 区） |
+| L0 | L0A 恒 DB（32KB）；**L0B 在 s2BaseSize=256 且 D>128 时退单 buffer，否则 DB**；L0C 满足 `mBaseSize*s2BaseSize*4 ≤ L0C/4 && mBaseSize*dVBase*4 ≤ L0C/4` 用 4buff 否则 DB | 同左，`mm2LeftSize = mBaseSize*s2BaseSize*(1+1/32)`（P 数据+E8M0 scale）计入 L1P 首 policy |
+
+## S5 流水编排
+
+- 三套 kernel 调度同构（[quant_flash_attn_kernel_fp8.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/quant_flash_attn/op_kernel/arch35/quant_flash_attn_kernel_fp8.h) 等）：`PRELOAD_N=2`、`PRELOAD_TASK_CACHE_SIZE=3`，本轮 MM1/Vec1，**MM2/Vec2 延迟 2 个 task**（`loop≥2` 才跑 runInfoNegN）。
+- MXFP8 的 MM1/Vec1 内部 subLoop（`c1v1Loop=CeilDiv(actS2, s2SplitSize)`）。
+- HIF8/MXFP8 的 bmm2 结果另经 `BuffersPolicy3buff<GM>` 周转。
+
+## S6 负载均衡
+
+- 仅 MXFP8 支持 FlashDecode（[quant_flash_attn_block_vec_flashdecode.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/quant_flash_attn/op_kernel/arch35/quant_flash_attn_block_vec_flashdecode.h)，631 行）：
+  - **AIV-only 归约**：只读各核 FA 写到 workspace 的 accumOut/lseSum/lseMax 合并，不碰 matmul；主循环 CopyLseIn→ComputeScaleValue(VF)→CopyAccumOutIn+ReduceFinalRes_VF→Cast→CopyOut。
+  - 常量：`fdBalanceMBaseSize=8`、`FD_LSE_BUF_BYTES=6144`、总 UB `5*6144+4*FD_MM2_BUF_BYTES+4*256`。
+  - **同步改用硬件信号量** `Mutex::Lock/Unlock<PIPE_V/MTE2/MTE3>(flag)`（flag 取 8/9/10/11/2/4，避开 TPipe AllocEventID 低段 id），不用 eventID。
+  - **UB 分时复用**：FD 区落 FA vec block 瞬态区，`static_assert(FdTotalUbSize <= FaTransientUbSize)` 编译期校验。
+  - 与 FA 侧 bit 级一致：`CalcMinCheckValueVF` 与 FA max 的 scaleValue×ln2+Truncate(CAST_CEIL) 量化对齐。
+- FP8 GQA / HIF8 无 FD（tiling `flashDecodeFlag_=false`）。
+
+## S7 自检结论
+
+- I5 轴对齐：Q/K 沿 D、**V 沿 S_k**、P 由 AIV 生成回传 L1——全部满足，无量化轴错位。
+- L0A 恒 pingpong；L0B 单 buffer 仅出现在 s2BaseSize=256 且 D>128 的容量死角（显式标注退化）；L0C 按容量 4buff/DB 静态分档。
+- 基本块编译期常量：mBaseSize 恒 64，s2BaseSize 按 dtype/D 静态分档，无运行时动态块。
+- 量化 AI 修正已入基本块：FP8 s2BaseSize 256、MXFP8 s2BaseSize 512。
+
+## 平台依赖
+
+`MatmulFullMX`（MXFP8 硬件 dequant，arch35 特有）、HIFLOAT8 dtype、KERNEL_TYPE_MIX_AIC_1_2、FixPipe、硬件信号量 Mutex——均 DAV_3510 口径。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/design_sample/sparse_flash_attention-arch35-best-practices.md

@@ -0,0 +1,66 @@
+# sparse_flash_attention 最佳实践（arch35 / Ascend950PR / DAV_3510）
+
+> MLA + 稀疏：latent 512 + rope 64 = 576 维，token-wise topk 稀疏。源算子：`ops-transformer/attention/sparse_flash_attention`。
+
+## S1 选型
+
+- 基础形态：**MLA**（`attentionMode` host 强制校验为 2；kernel/service 文件名全带 `mla`）。
+- 维度：**dSizeNope=512、dSizeRope=64、dSize=576(HAS_ROPE)/512(无)、dSizeV=512**；`HAS_ROPE` 为独立模板参数 + tilingKey 单独占 1 bit，不污染无 rope 路径；queryRope/keyRope 必须同时存在或同时为空。
+- trait：**稀疏**，`sparse_indices`(int32 topk) + `sparse_block_size` 控粒度；**arch35 强制 sparse_block_size=1（token-wise）**；sparse_mode 仅 0（全量）或 3（preTokens/nextTokens 窗口，tiling 强制 INT64_MAX，由 kernel 按 actualSeq 自算）。
+- V1 vs V2 API：V2 新增 `sinksOptional`([N1], float，仅 950/DAV_3510)；V2 去掉 V1 的 dummy softmaxMax/Sum 自动创建，改严格空指针检查。
+
+## S3 基本块（编译期常量）
+
+来源：[sparse_flash_attention_service_cube_mla_arch35.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_attention/op_kernel/arch35/sparse_flash_attention_service_cube_mla_arch35.h)
+
+- **mBaseSize=64、s2BaseSize=128、dBaseSize=576/512、dBaseMatmulSize=128**。
+- **qSNumInOneBlock=1：SFA 不切 G 轴，每个基本块只处理一行 query 的 topk**——与 SMLA 的 split-G 路线相反，是本算子的关键差异。
+- PA 场景 KV 按 `PA_BSND` 布局，`S2 = maxBlockNumPerBatch × blockSize`；blockSize 须 16 对齐且被 sparseBlockSize 整除；KV 非连续仅允许第 0 维（batch/block 维），`keyStride0 /= (n2Size × qkHeadDim)` 用于跨 block 跳读。
+- `returnSoftmaxLse=true` 时不支持 PA_BSND（host 检查）。
+
+## S4 Buffer 清单
+
+| Buffer | 层 | 份数/大小 |
+|---|---|---|
+| l1Right（BMM1/BMM2 右矩阵 KV） | L1 | **3（`BuffersPolicy3buff`）** |
+| v0ResGm（vector 聚合后的稀疏 KV 写回 GM） | GM | **3（`BuffersPolicy3buff`）** |
+| bmm1 | UB | 2（`BuffersPolicyDB`） |
+| bmm2 | UB | 1（`BuffersPolicySingleBuffer`） |
+| stage1OutQue / stage0OutBuf | UB | 各 2 |
+| softmaxMax/Sum/Exp | UB | 各 2 |
+| L0A / L0B / L0C | L0 | 64KB(2×16KB) / 64KB(2×32KB) / 256KB(2×128KB)，DB |
+| l1Q | L1 | 单 buffer 常驻：`s2LoopCount==0` 全载，后续循环复用 |
+
+**稀疏 KV 收集数据面（本算子特有）**：vector 侧 `ProcessSparseKv` 按 `sparseIndicesGm` 读 token 索引，PA 场景再经 `blockTableGm` 找物理 block，**把分散 KV 聚合到 UB 后写回 GM workspace（v0Res 三缓冲）**，供 cube 侧作右矩阵加载——稀疏 gather 在 AIV 完成，cube 拿到的是聚合后的连续数据。
+
+## S5 流水编排
+
+- **3 级流水**：`RunInfo runInfo[3]`，`taskId%3` 轮转——task j 跑 **BMM1(cube)/Vec0(vector)**，task j+2 跑 **BMM2/Vec1**，task j+1 跑 **Vec2**；`PRELOAD_NUM=2` 在最后两个 gS1 循环做 preload 补算。
+- `SYNC_MODE=4` 跨核 flag；`CV_RATIO=2`。
+- 注意与 SMLA 的阶段命名差异：SFA 有 **Vec0（稀疏 KV gather 聚合）→ BMM1 → Vec1 → BMM2 → Vec2** 五段，Vec0 是稀疏 trait 引入的前置 stage。
+
+## S6 负载均衡
+
+- 任务切分：以 **(B, N2, G×S1)** 为调度单元，统计 `sfaTotalBaseNum` 后按 AIC 核数均分；`bN2Start/gS1Start` → `bN2End/gS1End` 左闭右开（`InitCalcParamsEach`）。
+- **IS_SPLIT_G**（G>64 即 N1>64）：相邻两个 cube 核处理同一 s1，核数减半（`coreNum >>= 1`）。
+- 稀疏块跳过（[sparse_flash_attention_kvcache.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_attention/op_kernel/arch35/sparse_flash_attention_kvcache.h)）：`ComputeS2LoopInfo` 按 sparseMode 算 `s2LineStartIdx/s2LineEndIdx`（mode 3 再按窗口与 sparseBlockCount 取 min），`s2LoopEndIdx=ceil(s2LineEndIdx/128)`，无效 s1/s2 组合 `continue` 整块跳过。
+- Paged Attention：`isPa` 模板参数由 `kvLayout==PA_BSND` 决定，tilingKey 占 1 bit。
+
+## arch35 特有：Regbase 跨核直传
+
+[util_regbase.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_attention/op_kernel/arch35/common/util_regbase.h)：
+- 定义 `CVSharedParams`：AIC/AIV 经 **`__ssbuf__` 寄存器直传**的共享参数结构（bSize/n2Size/gSize/s1Size/s2Size/dSize/dSizeRope/sparseBlockCount/softmaxScale/blockSize/usedCoreNum/returnSoftmaxLse），**位域压缩**（`dSize:10`、`dSizeVInput:12`、`maskMode:4`）。
+- 握手：AIC `CrossCoreWaitFlag<SYNC_MODE, PIPE_S>(15)` 等 vector 写 ssbuf，按 uint32 逐字拷到本地。
+- vector 服务内部用 `Reg::` 寄存器级 API（RegTensor/LoadAlign/Cast/CreateMask）做 scale 处理与 softmax SIMD 优化。
+
+## S7 自检结论
+
+- I2：MLA kvHead=1；不切 G 轴（qSNumInOneBlock=1），KV 每行 query 独立 topk 聚合，无跨头重复加载问题。
+- I4：无 split-KV 需求时单 task 闭环；FD 未在本算子启用（与 SMLA 差异点）。
+- 稀疏不定长：buffer 按 s2BaseSize=128 常量分配，topk 数量运行时只裁剪循环范围。
+- K/V 槽池 3 ≥ r+1（3 级流水 r=2）；L0 三端口全 DB 无退化。
+- 数值：mode 3 窗口外整块双侧跳过。
+
+## 平台依赖
+
+ssbuf Regbase 跨核直传、SIMD-Regbase 双发（vector 服务内 `Reg::` API）、sinks 仅 DAV_3510、sparse_block_size=1 限制、KERNEL_TYPE_MIX_AIC_1_2——均 950PR 口径。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/design_sample/sparse_flash_mla-arch35-best-practices.md

@@ -0,0 +1,69 @@
+# sparse_flash_mla 最佳实践（arch35 / Ascend950PR / DAV_3510）
+
+> MLA + 稀疏双 trait：latent 压缩 KV（kvHeadNum=1, D=512）+ 外部 topk 稀疏索引。源算子：`ops-transformer/attention/sparse_flash_mla`。
+
+## S1 选型
+
+- 基础形态：**MLA**（latent absorption，`n2Size≠1` 直接报错，D_latent 固定 512）。
+- trait：**稀疏**（外部 `ori/cmp_sparse_indices` int32 topk 块索引 + `ori/cmp_topk_length` 有效长度裁剪，`TOPK_LIMIT=8192`）。
+- 本算子**不做 nope/rope 拆分**（448+64 字段属兄弟算子 mixed_quant_sparse_flash_mla），本体不做量化。
+- **5 种模板模式**（[sparse_flash_mla_common.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/sparse_flash_mla_common.h) `SMLATemplateMode`）：
+  - **CSA（=2）**：cmp_kv + cmp_sparse_indices，压缩 KV 稀疏注意力，cmpRatio∈{1,2,4}；
+  - HCA（=1）：cmp_kv 无索引，cmpRatio 必须 128；
+  - ORI_SPARSE(=3)/ORI_CMP_SPARSE(=4)：仅 A5，稀疏索引直通；
+  - **SWA（=0）**：无压缩分支的滑窗路径，无索引时强制 oriMaskMode=4 且默认 128 滑窗（winLeft=127, winRight=0）。
+- mask mode：0=topk/全量、3=RightDownCausal、4=Band 滑窗；A5 上 ori∈{0,3,4}、cmp∈{0,3}。
+
+## S3 基本块（编译期常量）
+
+来源：[sparse_flash_mla_csa_block_cube_arch35.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/arch35/sparse_flash_mla_csa_block_cube_arch35.h)
+
+- **mBaseSize=64、s2BaseSize=128、dBaseSize=512、dBaseMatmulSize=128、sparseBlockSize=1**。
+- D=512 超宽不进基本块常量：cube 侧沿 D 以 128 迭代，Q 沿 D 切半两次载入（`qHalfNum=2`）。
+- IS_SPLIT_G 时 `mRealSize = s1RealSize × gSplitSize`（G 维对折进 M 维）。
+- paged KV：A5 blockSize∈[1,1024]（`BLOCK_SIZE_LIMIT=1024`）；向量化地址模式要求 blockSize 为 2 的幂。
+
+## S4 Buffer 清单
+
+来源：[smla_common_defs.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/arch35/common/smla_common_defs.h)、CSA/SWA kernel Init
+
+| Buffer | 层 | 大小 | 份数 |
+|---|---|---|---|
+| l1P | L1 | 64×128 each | 2，**必须排 L1 最前**（保证与 vec 地址一致） |
+| l1Q | L1 | 16384 elem(32KB) each | 3 |
+| l1 K/V 共享槽池 | L1 | 65536 elem(128KB=128×512×2B) each | 3（`rightBufNum=3`） |
+| L0A / L0B / L0C | L0 | 16KB / 32KB / 128KB | 2 / 2 / 2（恒 pingpong） |
+| bmm2 | UB | 32×512 | 1 |
+| bmm1 | UB | 32×128 each | 2 |
+| vec UB 固定地址 | UB | `ATTEN_OUT_POP_BUF=184KB`、`LSE_POP_BUF=216KB` | — |
+| 跨核 GM v0Res | GM | 128×512×2B/core each | 3（`TRIPLE_BUFFER_NUM`）+ S2 实长缓冲 `3*128*4B*aivNum` |
+
+- L1 512KB 预算下，128KB 的 KV 单块使槽池上限=3（对应 r=2 的下界 r+1），**D 超宽是槽池份数的第一约束**。
+- buffer 轮转用 `BuffersPolicy3buffSFA`（a/b/c 三块，Get/GetVec/GetCube/GetPre(Q 复用)/GetReused(KV 复用)）。
+
+## S5 流水编排
+
+- **CSA `PRELOAD_NUM=3`，SWA `PRELOAD_NUM=2`**（`RunInfo runInfo[3]` 轮转）——压缩稀疏双路负载更重，预取更深；滑窗短路降 2 级。
+- 同步：`SYNC_MODE=4` 跨核 flag（CROSSCORE_L1P/BMM2/BMM1/V0RES）+ 核内 flag（INNERCORE_L0AB/L0C/L1Q/L1KV）。
+- **GetKVPhyAddr 独立相位**：BLKTABLE_FREE=3/READY=8、SPARSEIDX_FREE=4/READY=6、KVADDR_READY=5/FREE=7——地址计算与数据搬运各自成对 flag，互不阻塞。
+- vec 侧 KV 搬运粒度：`KV_COPYIN_UNIT=8` 行、`KV_PROCESS_UNIT=16` 行；FD 归约 `FD_VEC1_MAX_ROWS=32`、`FD_REDUCE_CHUNK_ROWS=16`。
+
+## S6 负载均衡
+
+- **metadata 预算分核**（arch35 标配，[sparse_flash_mla_kernel_metadata.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/sparse_flash_mla_kernel_metadata.h)）：1024×int32 GM 张量（输入索引 17），`SmlaMetadata{faMetadata[36][9], fdMetadata[72][8]}`（AIC_CORE_MAX_NUM=36、AIV_CORE_MAX_NUM=72）。FA metadata 9 字段/AIC：CORE_ENABLE/BN2_START/M_START/S2_START/BN2_END/M_END/S2_END/FIRST_FD_WORKSPACE_IDX/S2_MAX_NUM；FD metadata 8 字段/AIV。metadata 为 nullptr kernel 早退——**arch35 必选数据面，kernel 不现场算均衡**。
+- **FlashDecode（split-KV）**（[flash_decode.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/arch35/common/flash_decode.h)）：`FD_MAX_S2_SPLIT_NUM=2`、`FD_INCREMENTAL_MERGE_INPUT_NUM=2`；GM staging 三段 `[partial O][max][sum]`，log-sum-exp 合并 `M=max(m_i), G=Σexp(m_i−M)·s_i, O=Σw_i·p_i`；主循环后由空闲核做 `ProcessFlashDecode`。
+- **split-G**：gSize>64（n1>64）时 AIC 一分为二处理 G 前后各半（tilingKey splitG 位）；batch consistency（确定性规约）时 intraCoreSlots=2×logicalSlots、crossCoreSlots=aicNum×33。
+- **稀疏块跳过**（[sparse_flash_mla_kvcache.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/arch35/sparse_flash_mla_kvcache.h)）：`smlaSkipThreshold=min(−nextTokensOri, −nextTokensCmp)` 跳 S1 前部无效块；`ComputeS2LoopInfo` 按 topk_length 裁剪 S2，`loopEndIdx` 按 s2BaseSize=128 上取整。
+- **paged KV 地址向量化**（[get_kv_phy_addr_vf.h](file:///Users/wangwei/Desktop/项目/ops-transformer/attention/sparse_flash_mla/op_kernel/arch35/common/get_kv_phy_addr_vf.h)）：VF 寄存器级算物理地址，每 loop 处理 128 个 sparse idx（2×64 寄存器），`DataCopyGather` 收集 blockTable，int64 地址拆高低 32 位；`phyAddr = phyBlkId*kvStride + (sparseIdx*sparseBlockSize mod blockSize)*kvDim`；仅 A5 + CSA/稀疏路径且 UB 184KB 预算内启用（`vectorizeFlag`/`IS_VEC_S2PHYADDR`），稀疏块数 128 对齐（`SPARSE_BLOCK_ALIGN_NUM=128`）。
+
+## S7 自检结论
+
+- I2：kvHead=1 天然满足；split-G 把 G 折进 M 轴共享 KV 加载。
+- I4：FD split-KV 配 GM staging + log-sum-exp 跨核归约。
+- 稀疏不定长：buffer 按最坏块长分配（s2BaseSize=128 常量 + topk_length 运行时裁剪范围），基本块不随稀疏度变化。
+- K/V 槽池 3 = r+1（r=2）满足下界；L0 三端口恒 pingpong。
+- 数值：topk_length=0 的行按完全屏蔽处理，双侧跳过（GEMM 与状态更新都跳）。
+
+## 平台依赖
+
+A5 专属模板模式（ORI_SPARSE/ORI_CMP_SPARSE）、paged blockSize∈[1,1024] 放宽（A2/A3 需 16 对齐）、VF 向量化地址（184KB UB 预算）、metadata 36AIC/72AIV 上限、ssbuf/Regbase——均 DAV_3510 口径。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/patterns.md

@@ -0,0 +1,65 @@
+# FlashAttention 范式入口（语言中立）
+
+针对 Attention 及其变种（GQA、MHA、MLA、量化、稀疏等）生成语言无关的 Tiling 设计方案。用于用户描述 attention 算子并要求产出 Tiling 设计或方案文档时。
+
+进入本模块前核对实际公式中的分数计算、行归一化与加权值聚合。C1/V1/C2/V2 是相应计算图的一种阶段划分，具体排布由数据依赖、状态版本与目标资源推导。
+
+芯片规格缺失时向用户补齐；无法提供则在方案中标注"待提供"，不猜测。
+
+## 前置知识
+
+先加载 [pre-knowledge.md](./references/pre-knowledge.md)，建立 FlashAttention 常识与硬件基础（数学公式、数据流四阶段、片上缓存层级、正确性约束 I1-I5）。
+
+## 方案步骤
+
+按顺序执行 S1→S7。每个步骤只加载该步骤所需的 reference（见"加载协议"）。
+
+| 步骤           | 做什么                                                                  | 基础加载                                                                        |
+| ------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| S1 选型        | 定基础形态 + 正交 trait + Feature                                           | [selection.md](./references/selection.md)                                   |
+| S2 单核计算流     | 定义单核内 stage 序列 + 数据流方向                                               | [compute-flow.md](./references/compute-flow.md)                             |
+| S3 Buffer 规划 | 出公式化 buffer 清单（大小符号化 + 份数公式化，预取深度作参数；含 L0A/L0B/L0C pingpong 硬约束） | [buffer.md](./references/buffer.md)                                         |
+| S4 基本块与性能建模  | Roofline 与逐阶段成本定候选块，分析两次矩阵计算、向量阶段及搬运，代入 buffer 大小 | [roofline.md](./references/roofline.md)、[stage-cost.md](./references/stage-cost.md)、[buffer.md](./references/buffer.md) |
+| S5 流水编排      | 流水级数 + stage 顺序 + 同步语义 + 回填 buffer 份数                                | [pipeline.md](./references/pipeline.md)                                     |
+| S6 负载均衡策略    | 多核切分 + 负载均衡                                                          | [load-balancing.md](./references/load-balancing.md)                         |
+| S7 自检        | 跑 Self-Check 清单                                                      | [advanced.md](./references/advanced.md)                                     |
+
+> **基本块与 buffer 的迭代闭环（S3↔S4↔S5）**：S3 出公式化 buffer 清单（大小、份数与生命周期）；S4 由 Roofline 与阶段成本定候选块并代入大小；S5 按实际流水、预取及最后读完成推导份数；以硬件内存（UB / L1 / L0）对 Σ(size×N) 校验。不满足则调整基本块、复用或排布并重新代入，直到收敛到可行的 tiling 块。
+
+> **自检不通过**：定位失败项，回退到对应步骤重新决策（对应关系见 Self-Check），修正后重新自检，直至全部通过；未通过不允许产出方案。
+
+## 加载协议（按需加载）
+
+**基础加载**：S1→S7 依上表逐步加载对应文件。
+
+**四阶段排布示例**：S5 采用 C1→V1→C2→V2 并交错推进多个 KV 工作项时，按需读取 [完整时序与状态示例](./references/pipeline-example.md)。其中的阶段偏移、队列和状态份数只对应所示排布，实际路径结合 S3、S4、S5 重新代入。
+
+**特性加载**：命中下列特征时，在相关步骤额外加载对应 trait 文件：
+
+| 特征  | 触发条件                                                         | 额外加载                                                        | 涉及的步骤                       |
+| --- | ------------------------------------------------------------ | ----------------------------------------------------------- | --------------------------- |
+| 量化  | Q / KV dtype ∉ {fp16 / bf16}                                 | [trait-quantization.md](./references/trait-quantization.md) | S4 算术强度修正 / S3 scale buffer |
+| 稀疏  | KV 稀疏 pattern 由外部索引 / 掩码数据给定（规则掩码如 causal / 滑窗属 Feature，不触发） | [trait-sparse.md](./references/trait-sparse.md)             | S6 块跳过 / S3 不定长 buffer      |
+| MLA | 数学公式含 latent absorption                                      | [trait-mla.md](./references/trait-mla.md)                   | S3–S6 全链路                   |
+
+**样例加载**（arch35 / Ascend950PR / DAV_3510 量产算子蒸馏的完整 S1–S7 走查）：spec 芯片为 arch35 时按 trait 命中加载对应 best-practices，作为 S3–S6 的参考实现锚点（基本块取值、buffer 份数、流水深度、均衡手段均以样例为实测基准，roofline 推导用于解释而非推翻样例值）：
+
+| 算子 | 形态 | 加载文件 |
+| --- | --- | --- |
+| flash_attn | 非量化 GQA（ND/DN 双模板） | [flash_attn-arch35-best-practices.md](./design_sample/flash_attn-arch35-best-practices.md) |
+| quant_flash_attn | 量化 GQA（FP8 / HIF8 / MXFP8 三套） | [quant_flash_attn-arch35-best-practices.md](./design_sample/quant_flash_attn-arch35-best-practices.md) |
+| sparse_flash_attention | MLA + token 稀疏（不切 G、Vec0 gather） | [sparse_flash_attention-arch35-best-practices.md](./design_sample/sparse_flash_attention-arch35-best-practices.md) |
+| sparse_flash_mla | MLA + 稀疏双 trait（split-G、CSA/SWA 五模式） | [sparse_flash_mla-arch35-best-practices.md](./design_sample/sparse_flash_mla-arch35-best-practices.md) |
+
+> 样例符号与规则文件一致（`mBaseSize` / `s2BaseSize`）。注意样例 kernel 侧存在 `mBaseSize_effective = mBaseSize × r_cv` 的生效值换算（UB 分摊口径），读 buffer 份数与容量校验时区分。样例值是 arch35 特定芯片（L1 512KB / L0A/B 64KB / L0C 256KB / UB 248KB）下的实测最优点，迁移到其他芯片时须重新走 S3↔S4↔S5 闭环推导，禁止直接搬运数值。
+
+## 纪律
+
+- 语言无关：方案中不出现任何编程语言、框架或硬件 API 符号，只描述切分维度、buffer 公式、并行策略、流水级数、同步语义等 Tiling 决策。
+- 信息来源可信：芯片容量 / 核数 / 算力等参数未经确认时标注"待验证"，不编造。
+- 设计即最优：每个决策（基本块、流水级数、并行度等）必须取 Roofline + 容量推导的最优点，可用优化手段有软流水 / 双缓冲 / 负载均衡 / 编译期分流；其中 Cube 侧 **L0A / L0B / L0C 恒 pingpong（各 2 份），单缓冲属退化配置、不接受**；低于最优须显式标注其绑定的硬件 / 容量约束；禁止"先跑通后优化"式性能推迟、把退化配置作为设计目标。
+- **基本块必须是静态常量切分，套数由 spec 驱动**：mBaseSize / s2BaseSize / D / r 都是**编译期写死的常量**，**禁止输出运行时计算的动态块值**（如 `min(mBaseSize×G, cap)` 作为块大小）。**套数取决于 spec 是否给出场景典型值**——
+  - **spec 未指定场景 / 未给典型值**：默认把 mBaseSize 取为 UB 容量允许下的最大值（目标 `AI_HBM ≥ ridge_HBM`，Cube 吃满），prefill 与 decode 归一为同一基本块常量。不为 decode 短行单设第二套块的原因：decode 的 HBM-bound 由 M 轴行数锁死、基本块改不动 AI，优化下沉到 S6 split-KV（任务分发层）解决。
+  - **spec 给了明确的场景典型值**（如明确 prefill 主打 Sq=X、decode 主打 Sq=1）：可按典型值分**多套常量基本块**，每套针对一类典型 shape 调优，但每套内部仍为编译期写死常量、按 shape 属性静态分流，**不得退化为运行时动态块值**。
+  - 运行时只允许"有效行数 ≤ 常量块、不满则 padding"，块本身不变。
+- 设计期 vs 验收边界：本 skill 只产出设计期可校核的决策（结构决策 + 公式推导 + 容量校验）；实测验证（profiling 采集、反汇编检查、性能对标）属于性能验收阶段，不属于设计期。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/FA/references/advanced.md

@@ -0,0 +1,37 @@
+# 高级通用参考
+
+> 供 S7 自检及需要更严谨方案时加载。复杂变种（量化 / 稀疏 / MLA）的变体契约已拆到对应 trait 文件。
+
+## 正确性约束校核
+
+约束 I1–I5 本体不在此重复。方案自检时必须逐条给出**校核结论**：切分方案对 I2 的满足性说明（kvHead 合轴情况）、I4 的满足性说明（split-KV 是否配 reduce）等，而非仅复述约束。
+
+产出：每条正确性约束的校核结论。
+
+## 平台依赖
+
+**回答：设计中哪些参数 / 行为依赖特定硬件平台？**
+
+- 依赖项清单（容量、核数、算力、同步能力等）
+- 每项标注"已知差异"或"待验证"
+
+产出：平台依赖清单 + 待验证项。
+
+---
+
+## Self-Check
+
+未通过时回退到对应步骤重新决策，修正后重新自检，直至全部通过。
+
+> 各步骤内部正确性（stage 完整性、任务覆盖、格式标注、基本块推导、buffer 容量与复用前提、流水顺序）已在对应步骤的检查点自查，此处只校核**跨步骤一致性**与**全局汇总**。
+
+- [ ] K/V、P 的份数对应所选预取模型；max/sum、alpha、O_acc 分别按初始化到最后读取求最大占用，完整计入各池；task 与工作项的槽代次分别核对（S3/S5）
+- [ ] C1/V1/C2/V2 排布的带索引时序与 warmup/steady/drain 一致；V1/V2 相对顺序有状态版本与最后读取依据，短 task 与非零 KV 起点可推进并排空（S5）
+- [ ] 阶段调用、重复搬运、共用 Cube/Vector 负载与最慢执行单元的成本支撑候选选择，后续性能观测与瓶颈假设对应（S4/S5/S6）
+- [ ] L0A / L0B / L0C 均 pingpong（N=2），无单缓冲端口降级；L0 容量校验按 ×2 计入且逐端口独立，容量放不下时缩小 base 块而非关 pingpong（S3/S4）
+- [ ] 容量校验口径正确：UB 按每 Vector 核（mBaseSize/r_cv 行）校验、L1/L0 按 Cube 侧全量校验，未默认 1:1（S3/S4）
+- [ ] 每处非最优取值标注了绑定约束（全局贯穿）
+- [ ] 所有正确性约束 I1–I5 已逐条给出校核结论（全局贯穿）
+- [ ] 数值陷阱已处理（mask 用有限负数、完全屏蔽 tile 双侧跳过、padding 清零、首块初始化、末块除零保护）
+- [ ] 符号一致性：全文仅使用 pre-knowledge.md 符号表中的符号（`mBaseSize` / `s2BaseSize` / `subM` / `subN` / `subK` / `r_cv` / `d_s` 等），未混用旧符号（`mEff` / `Bq` / `Bk` / `baseM` / `baseN` / `baseK`）或未定义的新符号；任务/L1 级切分与 L0 级子块的符号未互换
+- [ ] 平台依赖项与待验证项已列出（全局贯穿）