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

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

@@ -0,0 +1,197 @@
+# FlashAttention 常识与硬件基础
+
+> 前置知识：开始出方案前先加载本文档，建立 FlashAttention 的公共认知。所有变体（GQA / MHA / MLA / 量化 / 稀疏）共享本节内容。
+
+## §1 FlashAttention 是什么
+
+FA（FlashAttention）类算子是**分块化、不显式实例化 attention score 矩阵**的 attention 计算族。三个输入 Q / K / V，一个输出 O，沿 KV 维度分块流式累积 softmax 与加权和，**不在显存中构建完整的 \[Sq, Sk] score 矩阵**。
+
+输入语义（维度名）：
+
+- **Q**：query，含 batch / Sq / qHead / D 维
+- **K / V**：key / value，含 batch / Sk / kvHead / D 维
+- **O**：输出，维度与 Q 同
+
+D 为 head dim，Hq / Hkv 为 query / kv head 数。变体在 Hq 与 Hkv 的关系、KV 是否压缩、Sq 是否退化为 1 等维度特化。
+
+字节宽记号（全文档通用）：`d_s` = 输入张量字节宽（fp16/bf16 = 2，fp8 = 1，int8 = 1），`d_FP32` = 4（GEMM 累加器与 softmax 状态）。
+
+与其他算子族的关键区别：
+
+| 维度        | FA 类                                     | 其他族     |
+| --------- | ---------------------------------------- | ------- |
+| 计算类型      | 矩阵乘 + softmax 混合                         | 多为单一    |
+| 计算流       | 跨核 stage 化（Cube 算 GEMM，Vector 算 softmax） | 单核内完成   |
+| 跨 KV 分块状态 | 必须在线 softmax 累积（max / sum / O\_acc）      | 多数无在线状态 |
+
+因此 FA 不能套用 reduction / elementwise / matmul 的设计模式。
+
+### 全局符号表
+
+| 符号                          | 含义                           | 首次出现 |
+| --------------------------- | ---------------------------- | ---- |
+| `Sq` / `Sk`                 | query / key-value 序列长度       | §1   |
+| `D`                         | head dim                     | §1   |
+| `Hq` / `Hkv`                | query / kv head 数            | §1   |
+| `G`                         | `Hq / Hkv`（GQA 合轴倍数）         | §1   |
+| `mBaseSize`                 | 任务/L1 级 M 轴分块（合轴后）           | S4   |
+| `s2BaseSize`                | 任务/L1 级 KV 轴分块               | S4   |
+| `subM` / `subN` / `subK`    | L0 级 M/N/K 子块                | §5   |
+| `r_cv`                      | Vector:Cube 核数配比（如 2 表示 1:2） | §5   |
+| `r`                         | 预取深度（GM→L1 槽池深度）             | S5   |
+| `d_s`                       | 输入张量字节宽（fp16=2, fp8=1）       | §1   |
+| `d_FP32`                    | fp32 字节宽（=4，累加器与 softmax 状态） | §1   |
+| `S_UB` / `S_L1`             | UB / L1 容量                   | §5   |
+| `S_L0A` / `S_L0B` / `S_L0C` | L0A / L0B / L0C 容量           | §5   |
+
+和arena仓一致
+
+## §2 数学公式（Online Softmax）
+
+对每个 KV 分块 `j = 0, 1, ..., (Sk/s2BaseSize)-1` 顺序累积：
+
+```
+S_j   = (Q · K_j^T) * scale                       # [mBaseSize, s2BaseSize]
+m_j   = max(m_{j-1}, rowmax(S_j))                 # [mBaseSize]   (m_{-1} = -∞)
+sum_j = exp(m_{j-1} - m_j)*sum_{j-1} + rowsum(exp(S_j - m_j))   # [mBaseSize]
+O_j   = exp(m_{j-1} - m_j)*O_{j-1} + exp(S_j - m_j)·V_j         # [mBaseSize, D]
+
+最终: O = O_last / sum_last
+```
+
+关键性质：
+
+- `S_j` 仅 `[mBaseSize, s2BaseSize]` 大小，与 Sk 无关 —— FA"不实例化全矩阵"由此实现。
+- 跨块累积需 **rescale 旧状态**（`exp(m_{j-1} - m_j)`），这是 online softmax 的本质。
+- 末块归一化（除以 `sum_last`）只做一次；**中间步骤的 P 不做归一化**。
+
+## §3 数据流四阶段
+
+每个 KV 分块的计算切成 4 个 stage，跨计算单元协同：
+
+| 阶段     | 操作                               | 产出                             |
+| ------ | -------------------------------- | ------------------------------ |
+| **C1** | Q·K^T 矩阵乘                        | `[mBaseSize, s2BaseSize]` 中间矩阵 |
+| **V1** | scale + softmax（未归一化 `exp(S-m)`） | 未归一化 P                         |
+| **C2** | P·V 矩阵乘                          | `[mBaseSize, D]` 中间矩阵          |
+| **V2** | 跨块累积（rescale + Add）+ 末块归一化       | 写回 O                           |
+
+C1 → V1 → C2 → V2 是同一 KV 分块内的**严格数据流方向**（正确性约束 I1）。不同 KV 分块之间如何交错（流水排布、几级流水）由设计阶段决定。
+
+## §4 跨 KV 分块状态
+
+**task（任务）**：多核并行的最小分发单元，粒度为二维分块 **\[M 分块，S2 分块]**——M 轴（合轴后的 Sq×G，见 I2）上的一个分块 × KV 轴（S2/Sk）上的一个分块范围。task 内部沿 KV 维顺序遍历自己的分块、持有并累积自己的 max / sum / O\_acc。
+
+- 默认（不切 S2）：task 的 S2 范围覆盖全 Sk，跨块状态 task 内闭环，末块归一化后直接写回 O。
+- 切 S2（split-KV / FlashDecoding）：同一 M 分块的多个 task 各自累积 partial max / sum / O\_acc，须由跨任务 reduce 合并（rescale 后求和）再归一化。
+
+跨 KV 分块需持有三类量：
+
+- **max**：`[mBaseSize]`，每行当前最大 score
+- **sum**：`[mBaseSize]`，每行归一化 sum
+- **O\_acc**：`[mBaseSize, D]`，累积的未归一化输出
+
+并行策略不同，这三类量的物理实现与生命周期不同（默认 task 级顺序累积 vs split-KV reduce）。
+
+## §5 硬件基础
+
+### 计算单元
+
+- **Cube 单元**：矩阵乘（GEMM），吞吐以 FLOPS 计。
+- **Vector 单元**：softmax 的 ReduceMax / Exp / ReduceSum 等归约与指数。
+- 两者跨核协同（stage 化），需片上握手同步。
+
+### CV 配比（Cube:Vector 核数比）
+
+芯片规格给出的核数分 Cube 核与 Vector 核两类，二者配比不恒为 1:1：
+
+- **1:2 型**（如 DAV\_2201 / DAV\_3510，型号仅为**示例**）：**1 个 Cube 核固定搭档 2 个 Vector 核（AIV）**，构成一个执行组。
+- **其他型**：Cube/Vector 集成于同一核（无独立配比），或配比非 1:2——以芯片规格为准，禁止默认 1:1。
+
+> 记号约定：`r_cv` = **Vector:Cube 配比**（每个 Cube 核搭档的 Vector 核数）。1:2 型（Cube:Vector = 1:2）架构下 `r_cv = 2`——注意两个比值的表达方向相反，禁止把 r\_cv 误取为 1/2。
+
+对 FA 设计的影响（贯穿 S2–S5）：
+
+- **UB 每 Vector 核私有**：规格里的 UB 容量是**单个 Vector 核**的值；1:2 下一个执行组有 2 份独立 UB。
+- **V1/V2 按 mBaseSize 行维分摊**：同一 task 的 softmax / 累积由搭档的多个 Vector 核按行对半并行，每核只驻留 `mBaseSize/r_cv` 行（`r_cv` = Vector:Cube 配比）。max / sum / O\_acc 每核只持自己那部分行，行间无依赖，无需跨核归约。
+- **容量校验口径分层**：UB 层按「每 Vector 核占用（mBaseSize/r\_cv 行）≤ 单核 UB」校验；L1 / L0 挂 Cube 侧，按全量 mBaseSize 校验。**禁止把全量 UB buffer 直接对比单核 UB**（等效按 1:1 计，会把 mBaseSize 压低一档）。
+- **Vector 有效吞吐** = 单核 Vector 算力 × r\_cv。
+
+### 片上缓存层级
+
+- **UB**：最靠近计算单元的统一缓冲，容量最受限。
+- **L1**：片上次级缓冲。
+- **L0**：矩阵乘专用分块缓冲，含三个端口：
+  - **L0A**：左输入缓冲
+  - **L0B**：右输入缓冲
+  - **L0C**：累加输出缓冲
+  - **FA 中 L0 三个端口均需 pingpong（各 2 份 slot，结构硬约束）**
+- **HBM / GM**：片外显存，带宽相对低。
+
+### 多级搬运数据流
+
+矩阵乘的数据流：`GM(HBM) → L1 → L0 → L0C → 输出`。各级带宽与容量来自芯片规格，禁止硬编码。链路上每一跳由独立搬运 / 计算单元完成，只有两端各有 2 份 slot 才能让相邻块重叠。
+
+### 切分粒度两级
+
+- **任务/L1 级**：M 轴分块 `mBaseSize`、KV 轴分块 `s2BaseSize`、N 轴（D 维，不切）
+- **L0 级**：`subM / subN / subK`，层级约束 `subX ≤ 任务级对应维度`
+
+两个 GEMM 的 L0 子块映射：
+
+| GEMM    | M         | K          | N          | L0 子块约束                                       |
+| ------- | --------- | ---------- | ---------- | --------------------------------------------- |
+| C1 QK^T | mBaseSize | D          | s2BaseSize | subM ≤ mBaseSize, subK ≤ D, subN ≤ s2BaseSize |
+| C2 PV   | mBaseSize | s2BaseSize | D          | subM ≤ mBaseSize, subK ≤ s2BaseSize, subN ≤ D |
+
+### 对齐约束
+
+subM / subN / subK 必须对齐到矩阵乘硬件粒度（如 16），否则利用率下降。
+
+### 数据格式（ND / NZ / DN）与通路转换约束
+
+数据在片上流转时分三种存储格式，**不同 buffer 的格式不同直接决定能否原位写 / 同槽复用**，buffer 规划（S3）与计算流（S2）必须逐 buffer 标注：
+
+| 格式     | 含义                         | 典型所在                                          |
+| ------ | -------------------------- | --------------------------------------------- |
+| **ND** | 行优先常规连续布局（每行 D 个元素连续）      | GM 上的 Q/K/V/O；Vector 在 UB 的输入输出               |
+| **NZ** | 分形（fractal）块化布局，矩阵乘装载要求的格式 | **L1 上所有 GEMM 操作数（Q/K/V/P，L1 只存 NZ）**；L0A/L0B |
+| **DN** | 分形转置布局                     | 特定转置装载通路（按需）                                  |
+
+**通路转换能力（硬件事实，方案不得违反）**：
+
+```
+GM ──ND──>(GM→L1 搬运完成 ND→NZ 转换)──> L1(NZ) ──NZ──> L0A/L0B ──(矩阵乘)──> L0C ──ND──> UB
+UB ──仅 NZ──> L1        （UB→L1 无格式转换能力，写入 L1 的数据必须已是 NZ）
+```
+
+- **L1 上格式必须全是 NZ**：GM→L1 的搬运通路自带 ND→NZ 转换，数据一进入 L1 即为 NZ；L1→L0 装载通路不做格式转换，要求 L1 侧已是 NZ。**方案中任何标注为 L1 的 buffer 格式一律 NZ，禁止标注 ND**。
+- **L0C→UB 输出为 ND**：Vector 拿到的 S / O\_tile 是 ND。
+- **UB→L1 必须 NZ**：Vector 产出要回交 Cube 的中间量（典型即 P）**必须在 UB 侧先排成 NZ** 再搬入 L1——「UB 上 cast 出 P」与「P 排成 NZ」是同一 V1 stage 内必须完成的事，不是可选优化。
+- **原位写 / 同槽复用前提：格式一致 + dtype 一致 + 生命周期不重叠**，三者缺一禁止同槽。反例：S（UB，ND，fp32）与 P（UB→L1，NZ，fp16）格式与 dtype 双不同，**禁止原位复用 / 共享槽**——不考虑格式会错误地把两者划入同一 slot 池，物理上写出的 NZ P 会按 ND 解读，直接错数。
+
+### 性能主线
+
+三个独立吞吐通道：Cube 算力 / HBM 带宽 / 片上跨核吞吐，性能取三者最小。
+
+> 芯片规格（UB / L1 / L0 容量、核数、Cube 算力、Vector 算力、带宽）来自 patterns.md 输入的第二个输入，Peak 值与容量一律运行时查询，禁止硬编码。
+
+## §6 正确性约束 I1-I5
+
+任何 FA 实现都必须满足，**违反必崩**（输出全零 / NaN / 精度崩溃 / 死锁）。
+
+- **I1 数据流方向**：同一 KV 分块内 stage 依赖严格有序 C1→V1→C2→V2，禁止重排。
+- **I2 同 kvHead 同任务**：同一 kvHead 的 KV 数据只加载一次、由同一任务消费。实现上把该 kvHead 下的 G 个 qHead 与 Sq **合轴**成一条 M 轴（M = Sq × G），M 轴分块大小即 `mBaseSize`；M 轴分块全部留在同一任务内共享 KV 加载，禁止按 qHead 逐头拆任务（否则 KV 重复搬运 G 次）。
+- **I3 跨任务状态隔离**：跨任务持有的状态（max / sum / O\_acc）按任务分槽，禁止共享同一物理位置。
+- **I4 状态累积正确性**：跨块累积的状态必须完整正确。沿累积维（S2）切分出的多个 task 各持 partial max / sum / O\_acc，**必须配跨任务 reduce 合并**（rescale 后求和）再归一化，禁止只累积不合并。
+- **I5 量化 scale 轴对齐**：量化 scale 沿被消费矩阵乘的 reduction 轴量化，禁止轴错位。**反直觉点**：V 在 `[B, Sk, Hkv, D]` 布局下 innermost 是 D，但 P·V 的 reduction 轴是 S\_k，故 **V 的 scale 沿 S\_k**（不是 D）。
+
+## §7 softmax 数值陷阱
+
+除 I1-I5 结构约束外，softmax 数值计算还有以下易错点：
+
+- **mask 用大有限负数**（如 -1e30），**禁用 -∞**：整行被屏蔽时 -∞ 会使 `rowmax = -∞`，`exp(-∞-(-∞)) = NaN`，并沿 S2（KV 轴）跨块累积传播。
+- **完全屏蔽的 tile**：跳过其矩阵乘的同时，也**必须跳过**该 tile 的 softmax 与状态更新（贡献为 0）；只跳一半会得到 NaN。
+- **padding 行**：softmax 前写屏蔽值，输出最终强制清零，不参与有效累积。
+- **首块初始化**：running max = -∞、sum = 0、O\_acc 清零；rescale 因子等价于 1（首块不做 rescale）。
+- **末块除零保护**：`O = O_acc / sum` 前对 sum 做下限保护（加 eps / clamp），避免 padding 或极端输入导致 inf / NaN。

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

@@ -0,0 +1,220 @@
+# 基本块与 Roofline 分析
+
+> 承接 S3 的公式化 buffer 清单。本文推导的 `mBaseSize` / `s2BaseSize` / 性能区制，是 S5 流水、S6 负载均衡的输入，需代入 S3 buffer 清单以硬件内存为约束迭代收敛。
+
+## §1 为什么 FA 需要专门的 Roofline
+
+FA 是混合算子：矩阵乘（GEMM）+ softmax（归约 / 指数），跨核 stage 化。性能瓶颈**不能用单一算术强度（AI）概括**，三个独立吞吐通道各自可能成为瓶颈：
+
+1. 计算算力（Cube 矩阵乘单元吞吐）
+2. 内存带宽（K / V / Q / O 的加载与写回）
+3. 跨核 / 片上吞吐（Vector softmax 吞吐 + Cube↔Vector 片上握手）
+
+> 常见建模错误：把片上握手与 HBM 加载混进同一个 AI 分母，再用"混合带宽"求单一 AI——会把 AI 人为封顶在 `D/sizeof(T)`，并掩盖真正的第三瓶颈。
+>
+> 正确做法：**三通道各自独立建模，性能 = 三个 ceiling 取 min**；瓶颈 = 限制项。
+
+## §2 三通道 Roofline
+
+### §2.1 mBaseSize：GQA 多头合轴后的 M 维分块
+
+同一 kvHead 下的 G 个 qHead 与 Sq **合轴**成一条 M 轴（`M = Sq × G`，I2），矩阵乘的有效 m 维就是 M 轴的分块大小：
+
+```
+mBaseSize = 合轴 M 轴上的分块行数
+```
+
+- **M 轴 = Sq×G（GQA 合轴）**，mBaseSize 的取值原则：UB 容量允许的前提下尽量取大，目标是把 `AI_HBM ∝ mBaseSize` 推到 ridge_HBM 以上——此时 Cube 是瓶颈、HBM 带宽被喂满，即"以 Cube-bound 为目标"。**基本块套数由 spec 驱动**——spec 未给场景典型值时归一为单一常量（prefill/decode 共享）；spec 给了明确典型值时可按典型值分多套常量。
+- **M 轴小（decode 短行）**：mBaseSize 有效值受 M 轴锁死、低于块常量属固有 HBM-bound，基本块改不动 AI，优化下沉到 S6 split-KV（见下）。
+
+**mBaseSize 是核心自变量**，同时决定 AI 和三通道的相对松紧。
+
+### §2.2 单 task 的 FLOPs 与双 GEMM 映射
+
+两个 GEMM 各遍历全 Sk：
+
+```
+FLOPs_total = 4 × mBaseSize × Sk × D
+```
+
+| GEMM | 计算 | M | K | N | L1 关键输入 |
+|---|---|---|---|---|---|
+| Bmm1 | Q·K^T | mBaseSize | D | s2BaseSize | Q(D×mBaseSize) + K(D×s2BaseSize) |
+| Bmm2 | P·V | mBaseSize | s2BaseSize | D | P(mBaseSize×s2BaseSize) + V(s2BaseSize×D) |
+
+> **causal 的影响不在 AI**：被完全 mask 的 tile 被跳过，FLOPs 与 K/V 加载同比例减少，AI ≈ 不变；causal 真正影响的是**绝对耗时**与**核间负载均衡**，不是算术强度。
+
+### §2.3 HBM 带宽与 AI_HBM（主 Roofline）
+
+单 task 的 HBM 流量（遍历全 Sk）：
+
+| 张量 | 流量 | 说明 |
+|---|---|---|
+| K 加载 | `Sk × D × sizeof(T)` | 全序列加载一次 |
+| V 加载 | `Sk × D × sizeof(T)` | 全序列加载一次 |
+| Q 加载 | `mBaseSize × D × sizeof(T)` | 驻留，摊薄 |
+| O 写回 | `mBaseSize × D × sizeof(T)` | 末块写出 |
+| O_acc streaming（仅 streaming 模式） | `2 × mBaseSize × D × sizeof(acc) × (Sk/s2BaseSize)` | 每个 chunk 读回 + 写出，共 Sk/s2BaseSize 次 |
+
+`Sk ≫ mBaseSize` 时 K/V 主导：
+
+```
+Bytes_HBM ≈ 2 × Sk × D × sizeof(T) + 2 × mBaseSize × D × sizeof(acc) × (Sk/s2BaseSize)
+AI_HBM = FLOPs_total / Bytes_HBM
+```
+
+忽略 O_acc streaming 项的清晰上界：
+
+```
+AI_HBM ≈ 2·mBaseSize / sizeof(T)
+```
+
+关键结论：
+- **AI_HBM ∝ mBaseSize**（不封顶在 D/sizeof(T)）
+- **M 轴小（decode 短行，mBaseSize 受 M 锁死）**：`AI_HBM = 2·mBaseSize/sizeof(T)` 被行数压死，GQA 合轴（M = Sq×G）是提升 AI 的唯一杠杆；基本块改不动，由 split-KV 补核数
+- **s2BaseSize 通过 O_acc streaming 项影响 AI**：streaming 下增大 s2BaseSize 减少 O_acc 往返；非 streaming（O_acc 驻留）下 s2BaseSize 对 AI 无直接影响
+
+HBM ceiling：
+
+```
+Perf_HBM = Peak_BW × AI_HBM
+ridge_HBM = Peak_FLOPS / Peak_BW    (FLOPs/Byte)
+AI_HBM < ridge_HBM → HBM-bound
+```
+
+### §2.4 跨核 / 片上吞吐（cross-core-bound 校核）
+
+若 **Vector 端（softmax）吞吐 < Cube 端（GEMM）吞吐**，即使带宽与算力都不饱和，算子仍被 Vector 拖住。
+
+Vector 端每 tile 工作量：
+- softmax over `[mBaseSize, s2BaseSize]`：ReduceMax / Exp / ReduceSum，∝ mBaseSize·s2BaseSize
+- 片上握手（不占 HBM，占片上带宽）：各 ∝ mBaseSize·s2BaseSize 或 mBaseSize·D
+
+校核判据（吞吐平衡）：
+
+```
+T_cube(tile)  ≈ FLOPs(tile) / (Peak_FLOPS × util)
+T_vec(tile)   ≈ softmax_ops(mBaseSize·s2BaseSize) / (vec_throughput × r_cv) + onchip_bytes / onchip_BW
+cross-core-bound ⟺ T_vec > T_cube
+```
+
+`r_cv` = Vector:Cube 核数配比（1:2 型架构 r_cv=2）：同一 task 的 V1/V2 由搭档的 r_cv 个 Vector 核按 mBaseSize 行维分摊并行，Vector 有效吞吐按 `vec_throughput × r_cv` 折算。**禁止默认 r_cv=1**，否则会把 Vector 端低估一倍、误判 cross-core-bound。
+
+> **算力口径警示（`vec_throughput` 与 `Peak_FLOPS` 的单核化）**：芯片规格里的 Cube / Vector 算力通常是**全芯片合计**。代入上式前必须先单核化（以下数字为**示例**，仅示意换算方法，禁止代入方案）：
+>
+> ```
+> # 示例芯片：Cube 总算力 432T / 32 核，Vector 总算力 54T / 64 核（54T = 基准 27T × 双发 2）
+> 单 Cube 算力  = Cube总算力 / CubeCore核数            # 432T/32 = 13.5T
+> 单 AIV 算力   = Vector总算力 / VectorCore核数         # 54T/64 ≈ 0.84T（勿按 CubeCore 核数均摊）
+> 执行组 vec_throughput × r_cv = 单 AIV × r_cv          # 0.84T×2 ≈ 1.69T
+> ```
+>
+> 两类典型错误：① 把 Vector 总算力按 **CubeCore 核数**均摊（`54T/32`），再乘 r_cv → 单执行组算力被**高估一倍**（3.4T vs 实际 1.69T）；② 只取单 AIV 不乘 r_cv → **低估一倍**。Cube 与 Vector 核数不同（1:2），均摊除数必须与该算力所属核类一致。
+
+主杠杆：
+- 提高 Cube:Vector 配比（即利用芯片固有的 r_cv 个 Vector 核分摊，而非只用 1 个）
+- 减小握手粒度、per-stage 同步、双缓冲让两单元重叠
+- 减少冗余同步屏障
+
+### §2.5 计算算力（compute ceiling）
+
+```
+Perf_compute = Peak_FLOPS × util
+```
+
+util 主要由矩阵乘的 m / n / k 对齐决定。
+
+### §2.6 三通道取 min
+
+```
+Perf ≈ min(Perf_compute, Perf_HBM, Perf_crosscore)
+瓶颈 = 三者中最小的通道
+```
+
+| 区制 | 判据 | ceiling | 主杠杆 |
+|---|---|---|---|
+| Compute-bound | AI_HBM ≥ ridge 且算力最低 | `Peak_FLOPS × util` | 矩阵乘对齐、Cube/Vector 重叠、减同步 |
+| HBM-bound | AI_HBM < ridge 且带宽最低 | `Peak_BW × AI_HBM` | 增大 mBaseSize、Q 驻留、增大 s2BaseSize 减 O_acc 往返 |
+| Cross-core-bound | T_vec > T_cube | 片上吞吐 | 提配比、减握手粒度、双缓冲 |
+
+### §2.7 搬运 / 计算比 R_compute（等价精确判定）
+
+Roofline 用 AI vs ridge 判区制，工程上更直接的是**搬运/计算比**：
+
+```
+R_compute = 搬运耗时 / 计算耗时
+```
+
+- `R < 1`：compute-bound；`R = 1`：临界；`R > 1`：memory-bound
+- 优化目标 `min max_i R_compute^(i)`（最差核的比值最小）
+
+**D 的影响**：
+- GM→L1 搬运主导的边界：R_compute 中 D 被约去，**与 D 无关**
+- L0C→输出搬运的边界：`R ∝ (1/s2BaseSize + 1/D)`，D 减小时输出搬运更易成为瓶颈
+
+## §3 基本块可行域：下界（性能）与上界（硬件）
+
+### §3.1 下界 — Roofline 反推最小 mBaseSize
+
+HBM-bound 下 `Perf ∝ AI_HBM ∝ mBaseSize`，需要 mBaseSize 足够大才能达到可接受性能：
+
+```
+目标 AI = α × ridge_HBM    (α 为可接受 ridge 占比，如 0.3~0.5)
+→ mBaseSize_min = ceil(α × ridge_HBM × sizeof(T) / 2)
+```
+
+M 轴小（decode 短行）时 mBaseSize 受 M 轴锁死：若 `mBaseSize_min > M`，说明该 shape 下 HBM-bound 无法靠增 mBaseSize 突破 → 依赖流水隐藏延迟或 split-KV reduce（见 S6 负载均衡），**不改基本块**。
+
+### §3.2 上界 — 硬件容量约束
+
+基本块受 UB / L1 / L0 多层片上容量约束，取交集。softmax 状态 buffer（max / sum）随 mBaseSize 线性增长，是常驻项。
+
+矩阵乘侧容量约束：
+- L1：`subK × (subM + subN) × d_s ≤ S_L1 / 2`（÷2 为输入双缓冲）
+- L0A：`2 × subM × subK × d_s ≤ S_L0A_avail`（×2 为 pingpong，硬约束）
+- L0B：`2 × subK × subN × d_s ≤ S_L0B_avail`（×2 为 pingpong，硬约束）
+- L0C：`2 × max(subM × subN, subM × D) × d_FP32 ≤ S_L0C`（两 GEMM 复用同一 L0C，×2 为 pingpong，硬约束）
+
+> **L0 的 ×2 不可省**：L0A / L0B / L0C 份数恒 2（单缓冲会使装载 / 计算 / 搬出串行、流水阻塞）。容量放不下时**缩小 subM / subN / subK（或减小 s2BaseSize）**，禁止退回单缓冲；L0 容量与 K/V 槽池的 L1 余量（决定 r）互不占用，不得"省 L0 换 r"。
+
+### §3.3 硬件常量来源
+
+所有 Peak 值与容量必须**运行时查询（来自芯片规格），禁止硬编码**。
+
+## §4 场景特化：Prefill / Decode / Causal（同一基本块下的瓶颈对照）
+
+| 场景 | M 轴 | 典型瓶颈 | 首要杠杆 |
+|---|---|---|---|
+| Prefill（M=Sq×G 大） | 大，切满 mBaseSize 块 | compute / cross-core | 增大 mBaseSize 提 AI（受容量约束）；对齐；流水重叠 |
+| Decode（M 轴小，Sq=1 / MTP 短行） | 小，mBaseSize 受 M 锁死 | HBM / cross-core | 基本块改不动 AI；核数富余时 split-KV（S6） |
+| Causal（叠加） | 同上 | 同上 + 负载不均 | AI 近似不变；zigzag / 剪枝均衡 |
+
+> 三场景共用同一套基本块（Cube-bound 目标统一切分），差别只在 M 轴有效行数与 S6 任务分发（split-KV / 剪枝 / zigzag），**不在基本块层分流**。
+
+## §5 量化路径的 AI 修正
+
+量化 dtype 下 K/V 的 HBM 流量按量化字节宽计：
+
+```
+Bytes_HBM ≈ 2 × Sk × D × sizeof(quant_T)
+AI_HBM = 2·mBaseSize / sizeof(quant_T)
+```
+
+fp16（2B）→ fp8（1B）：`sizeof` 减半 → **AI_HBM 翻倍（约 +100%）**。
+
+## §6 产出清单
+
+进入 S5 流水前，方案必须展示以下推导（**每项展示算式，禁止只给结论**）：
+
+逐阶段计算及搬运按 [FA 阶段成本](stage-cost.md) 代入；Vector 负载包含 V1 与 V2，Cube 负载包含 C1 与 C2，并关联各自共享资源与状态依赖。
+
+- [ ] AI_HBM 公式 + 代入 mBaseSize/D/sizeof 的数值 + ridge_HBM
+- [ ] 三通道 ceiling 各自估算 + min 取哪个 → 瓶颈区制
+- [ ] cross-core 校核：T_vec vs T_cube 的定性 / 定量判断（含 r_cv 配比折算）
+- [ ] mBaseSize_min（下界）+ mBaseSize_max / s2BaseSize_max（上界）
+- [ ] 候选 mBaseSize、s2BaseSize + 在可行域中的相对位置
+- [ ] 代入 S3 buffer 清单：Σ 总占用 ≤ 硬件容量（UB / L1 / L0）校验；L0 按 ×2（pingpong）计入，逐端口独立校验
+- [ ] 容量不满足时的调整路径（减小 s2BaseSize / 转 streaming / split-KV）+ 迭代收敛后的最终 tiling 块
+- [ ] 场景：prefill / decode /（是否 causal）
+- [ ] 性能上限估算 = min(三通道 ceiling)
+- [ ] 基本块套数由 spec 驱动：spec 未给场景典型值时默认 Cube-bound 归一为单一编译期常量切分（decode 短行优化下沉 S6 split-KV）；给了典型值时可分多套、每套仍为编译期写死常量并按 shape 属性静态分流，无运行时动态块值

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

@@ -0,0 +1,32 @@
+# Attention 变种选型
+
+> 选型分两步：先定**基础形态**（GQA / MHA / MLA，沿 head / hidden-dim 变化的三选一），再按需**正交叠加** trait（量化 / 稀疏，各自独立可选）。
+
+## 基础形态（三选一，必选）
+
+| 形态 | 数学差异 | 选型触发条件 |
+|---|---|---|
+| **GQA**（默认） | `Hq = G × Hkv` | 默认路径；`Hq % Hkv == 0` |
+| **MHA**（GQA 退化） | `G = 1`（`Hq = Hkv`） | GQA 的退化特例 |
+| **MLA**（latent 变体） | KV 经 latent 压缩，`kvHeadNum = 1` | 数学公式含 latent absorption |
+
+## 正交叠加 trait（各自独立可选，叠在基础形态之上）
+
+| trait | 触发条件 |
+|---|---|
+| **量化** | Q / KV dtype ∉ {fp16 / bf16} |
+| **稀疏** | KV 稀疏 pattern 由外部索引 / 掩码数据给定（规则掩码如 causal / 滑窗 / Sink 属 Feature，不触发） |
+
+> 量化 trait 改变核心计算路径，稀疏 trait 仅影响块跳过（各自契约见 trait 文件）。
+
+## Feature（可叠加在任意组合之上）
+
+`causal` / `RoPE` / `PSE` / `Sink` / `滑动窗口` / 其他位置或掩码特性。
+
+## 选型规则
+
+1. 数学公式与标准 attention 一致 + `Hq % Hkv == 0` → **GQA 形态**（`G=1` 即 MHA 退化）。
+2. 数学公式含 latent absorption → **MLA 形态**（kvHeadNum=1 + latent 维）。
+3. **量化 / 稀疏是正交 trait，不是子族**：定完基础形态后按需叠加。
+
+> **说明**：FlashDecoding（split-KV reduce）是**并行实现技术**，不是子族 / trait，可叠加在任意组合之上。

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

@@ -0,0 +1,63 @@
+# FA 阶段成本与排布选择
+
+用于 S4、S5、S6 联合比较基本块、交错排布与任务分配。按所选 FA 计算图展开阶段；本表对应 C1→V1→C2→V2 的在线 softmax 路径。量化、稀疏或新增阶段在相应输入范围重新计数，设备耗时注明依据。
+
+## 1. 逐阶段计数
+
+定义有效输出行数 m、当前 KV 行数 n、分数收缩维度 d、值输出维度 d_v。task g 的有效 KV 工作项数为 L_g，总数 `N=sum_g L_g`。固定初始化、每工作项计算与最终归一化分别计数。
+
+| 阶段 | 资源及调用次数 | 每工作项计算 | 数据与重复操作 | 依赖及状态 |
+|---|---|---|---|---|
+| Q 装载 | 所选搬运通路，每 task 的实际次数 | 按实际重排计数 | 逻辑 `m*d` 元素；按共享范围与物理布局记录装载及转换 | 保留到最后 C1 读取完成 |
+| C1 | Cube，按有效 KV 项及 d 子块数 | QK 约 `2*m*n*d` FLOPs | K 装载、Q/K 到计算存储、S 搬出；按子块与布局统计重复次数 | S 发布给对应 V1 |
+| V1 | Vector，每有效 KV 项 | scale/mask、max、exp、sum 与在线 m/l 更新 | S 读取、P 转换与交接；分别计入各存储层级 | m/l 按 task 更新，alpha 按工作项保留 |
+| C2 | Cube，按有效 KV 项及输出子块数 | PV 约 `2*m*n*d_v` FLOPs | V 装载、P/V 读取及 B 搬出；输出分段时统计 P 再读取次数 | B 发布给对应 V2 |
+| V2 | Vector，每有效 KV 项 | U 缩放、累加约与 `m*d_v` 成正比 | B、alpha 与 U 的真实读写 | U 更新按所属 task 顺序 |
+| 最终输出 | Vector/输出通路，每 task 一次 | U/l、转换及约定的统计输出 | 输出写回，状态与结果的最后读取 | 完成后释放所属 task 的状态 |
+
+上述计算量是有效量；实际对齐、完整访问宽度、尾部及填充产生的执行量另外计入。S/P/B 的写与读分别记账，P 的转换两侧和片上搬运与外部存储流量分别记录。分段、共享或重置引起的重复操作按实际内外循环展开。
+
+## 2. 共用资源的吞吐约束
+
+Cube 内 C1/C2 的计算负载合计；Vector 内 V1/V2 的负载合计。搬运引擎、片上路径和存储带宽按实际共用关系合并。目标平台的 Cube/Vector 配比与可参与执行的核数采用已确认事实，逐行分摊与物理容量使用同一口径。
+
+```text
+tau >= max(
+    C1 与 C2 在同一 Cube 实例上的累计占用,
+    V1 与 V2 在同一 Vector 实例上的累计占用,
+    共享搬运通路和存储带宽的占用,
+    在线状态及有限缓冲带来的推进约束
+)
+```
+
+每个时间分量明确计算、搬运、转换或等待；已确认独立且可重叠的分量按最大值形成下界，串行分量沿依赖链累计。峰值与有效吞吐分别注明来源，实际可达到的推进间隔由所选时序支持。
+
+## 3. 候选排布比较
+
+[完整示例](pipeline-example.md) 选择 V1 先于 V2，保存每工作项 alpha，并把 task 的 m/l 与 U 分开保留。V2 先于 V1 的候选按其读写顺序重新求未释放版本数。新增份数、释放时点和等待变化进入资源及成本比较。
+
+| 候选及完整输入 | C1/V1/C2/V2 的次数与偏移 | 各层搬运及重复次数 | m/l、alpha、U 与交接份数 | 共用资源与关键等待 | 选择依据及后续观测 |
+|---|---|---|---|---|---|
+| 实际方案 | 逐 task 与 KV 项代入 | Q/K/V、S/P/B、状态与输出 | 分别求生命周期与物理分配 | 推进间隔限制 | 估算、已测或待测 |
+
+改变预取、块大小、状态保留或阶段顺序时，重新代入计算、搬运、份数、填充及排空。容量中包含所有副本、布局填充、临时区与同步存储；当前方案中的数值仅支持其前提及路径。
+
+## 4. 短流、task 边界与最慢核
+
+- 少量 KV 项：按完整时间表计算初始填充与剩余 V1/C2/V2，工作项数不足时按实际发射次数计算。
+- 多个相邻 task 连续推进：计算跨 task 同时保留的 m/l、alpha、Q 与输出状态；初始化和最后读取分别定位到具体阶段。
+- 每 task 排空或分段重置：按实际边界次数累计开销，并核对输入、workspace 及状态可见性。
+- 多核分配：按各 task 的有效 m/n、KV 项数、内部子块数估算各核负载，总计算阶段取最慢核，再计最终汇合与输出。
+
+长流可用 `T_setup + T_first_item + (N-1)*tau + T_finish` 作近似结构；T_first_item 包含首项经过完整阶段链的延迟，T_finish 只计最后阶段后剩余收尾。变长 task、短流与不同阶段成本按具体排布推导。
+
+## 5. 输出与验证义务
+
+设计中给逐阶段成本、候选资源代入、预计瓶颈与选择范围。后续实现验证按相同语义、合法输入与统计条件比较：
+
+- KV 工作项较少与较多，区分填充/排空和长流推进间隔。
+- m/n/d/d_v 改变，检查 C1/C2、V1/V2 与搬运成本的相对变化。
+- 相同输出范围、不同 task 划分，检查重复装载、各核负载和收尾次数。
+- V1/V2 顺序或缓冲候选改变，检查代次安全、复用等待与实际重叠。
+
+总时延结合阶段或资源时间线、搬运/转换次数及等待证据判断归因；观察不符时修订遗漏的调用、状态依赖或分配成本。数值结果仍由独立 attention 参考计算判定。

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

@@ -0,0 +1,36 @@
+# MLA trait
+
+> 触发条件：数学公式含 latent absorption。MLA 沿 KV 侧做 latent 压缩，kvHeadNum = 1。
+
+## 核心影响
+
+MLA 把标准 KV 投影成低维 latent，再做 latent absorption，影响全链路 S3–S6。
+
+## 关键决策
+
+- latent 压缩：KV 投影到低维 latent 的维度选择
+- latent absorption：吸收进 Q 侧的矩阵乘
+- 中间精度：latent 路径的中间段是否需要更高精度
+- kvHeadNum = 1 对负载均衡（S6）和 buffer（S3）的影响
+
+## 涉及影响点
+
+### S3 buffer：D 超宽是全链路第一约束
+
+- **latent 维 D_latent（如 512，或 nope 512 + rope 64 = 576）远大于常规 head dim**——单块 KV（`s2BaseSize × D_latent`）占 L1 的比例被 D 放大数倍，**K/V 槽池份数的上界由 D_latent 锁死**（D=512、s2BaseSize=128 时单块即 128KB，512KB L1 下槽池只能开 3 份，正好压在下界 r+1 上）。
+- **D 不进基本块常量**：基本块仍写死 `mBaseSize × s2BaseSize`，D 方向由固定的子块宽（如 128）在 GEMM 内部迭代消化；Q 沿 D 切半/分段多次载入。
+- rope 拆分与否是**模板级分流**：带 rope（D=576）与不带（D=512）按模板参数静态分开，rope 维作为独立常量，不混入主 D 的动态计算。
+
+### S6 负载均衡：kvHeadNum=1 使 G 维成为唯一杠杆
+
+- I2 合轴后 M = Sq × G 中 **G 可极大（全部 qHead 压在一个 kvHead 上，G 可达 128）**——G 既是 AI 的放大器，也是任务粒度失衡的来源。
+- **split-G**：G 超过阈值（如 64）时把 G 对折进 M 维、由相邻核分摊同一 M 分块的 G 前后各半，以核数换任务粒度——这是 MLA 特有的均衡手段，GQA 不需要（G 小）。
+- **split-KV（FlashDecoding）仍是 decode 短行的承载点**：kvHead=1 时 totalTasks = B × M分块 更少、核更富余，split-KV 判据（`totalTasks < usedCoreNum` 且 Sk 够长）更容易命中。
+- 与之正交的另一路线：**不切 G、每个基本块只处理一行 query**（逐行 M=1 任务）——任务是够细了，但放弃 G 合轴的 AI 增益，仅当 G 维无法合轴共享 KV（如逐行独立稀疏索引）时才选。
+
+### S4/S5 联动
+
+- D 超宽不改 AI 公式（`AI_HBM ≈ 2·mBaseSize/sizeof(T)` 与 D 无关），但**绝对耗时中 D 方向迭代次数翻倍**，Cube:Vector 的节拍比须按 `D_latent/128` 折算校核 cross-core-bound。
+- 流水级数与常规 FA 相同（r=2、槽池 ≥3）；D 超宽挤压的是槽池**上界**，不是流水结构本身。
+
+产出：latent 维度 / absorption 位置 / 中间精度选择。

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

@@ -0,0 +1,51 @@
+# 量化 trait
+
+> 触发条件：Q / KV dtype ∉ {fp16 / bf16}。量化 trait 改变核心计算路径，在 S3 / S4 额外加载。
+
+## 核心影响
+
+量化 trait 在乘法前对操作数做量化（量化乘法），引入 scale，需在方案中额外决策。
+
+## S3 scale buffer 与回传
+
+- scale 的存储 layout（沿被消费乘法的 reduction 轴）
+- scale 是否需要反量化（AntiQuant）回传路径
+- scale 额外 buffer 的大小公式与复用
+
+### AntiQuant 位置决策（决定全链路）
+
+| 位置 | 含义 | scale 驻留层 | 适用 |
+|---|---|---|---|
+| **Vector 侧反量化** | Cube 做纯量化 matmul，descale 融合进 V1 softmax / V2 累积 | **UB**（跟随消费方 Vector） | 对称 8-bit（per-token / per-tensor 细粒度 scale） |
+| **Cube 侧硬件反量化** | scale 作为矩阵乘输入，dequant 在 GEMM 内完成，Vector 零 dequant | **L1**（与量化数据同层） | per-block power-of-two scale（MXFP8 类） |
+| **Vector 预反量化（非对称必选）** | 量化权重先在 Vector 反量化成 16-bit，**经 UB→L1** 再以 16-bit 喂 Cube GEMM | 量化数据进 UB，反量化结果 UB→L1 | 非对称量化（A16W8 / A16W4） |
+
+- **平台硬约束：Ascend950 系列 Cube 不支持非对称矩阵计算**——A16W8 / A16W4 无法作为 GEMM 输入，必须先在 Vector 侧把权重反量化回 16-bit，再走 UB→L1 通路送入 Cube。即非对称量化的 AntiQuant 位置**没有选择权**，恒为"Vector 预反量化 + UB→L1 回灌"，其代价是 L1 上驻留的仍是 2B 数据（L1 容量不省，只省 HBM 带宽），且 Vector 侧新增一段 dequant 计算须计入 cross-core-bound 校核。
+- 对称 8-bit 量化才有上表前两行的二选一：Cube 支持 A8W8（32B=32 个数，峰值 2 倍），故可在"Vector 融合 descale"与"Cube 硬件 dequant（MXFP8 类）"之间按 scale 粒度选择。
+- **规则：scale 跟随消费方驻留**——Vector 反量化则 scale 进 UB，Cube 反量化则 scale 与数据同层驻留 L1；禁止跨层搬运（如 scale 进 UB 却给 Cube 用）。
+- **P 的 scale 反向回传**：量化路径下 P 也须量化后才能进 C2，其 scale 由 V1 在 UB 侧生成，随 P 一起写回 L1 供 Cube 消费；P scale 的大小计入 L1P 的分配（P 数据 + scale 一体）。
+- 量化粒度谱系（由粗到细）：per-tensor < per-token-per-head < per-block（power-of-two）。粒度越细 scale buffer 越大、搬运开销越高；Cube 硬件反量化可把细粒度的计算成本归零，是细粒度可行的前提。
+
+## S4 基本块算术强度修正
+
+量化乘法的算力消耗与标准 fp16 / bf16 乘法不同，Roofline 计算通道的算术强度需按量化位宽修正，可能导致基本块取值改变。
+
+实测修正规律（蒸馏自量产算子）：
+
+- **计算通道峰值按量化对称性分情况**（Cube 每拍以 K 方向 32B 计：`16 × 32B × 16`）：
+  - **非量化（fp16/bf16）**：32B = 16 个数 → 每拍 16×16×16 = **4096 MAC**。
+  - **非对称量化（A16W8 / A16W4）**：activation 仍是 16-bit，K 方向 32B 仍是 16 个数 → 峰值不变（4096/拍）。量化只省 HBM/L1 字节，**不省算力**。
+  - **对称量化（A8W8，双侧 8-bit，如 FP8 / HIF8 / MXFP8）**：32B = 32 个数 → 每拍 16×32×16 = **8192 MAC，峰值 2 倍**。ridge 点右移，打满 Cube 需要 2 倍算术强度。
+- **HBM 通道 AI 按字节宽翻倍**：fp16(2B)→fp8(1B) 使 `AI_HBM ≈ 2·mBaseSize/sizeof(T)` 翻倍，且 K/V 驻留 L1 的容量压力减半——这与计算通道的修正独立，A16W8 同样享受。
+- **只放大 s2BaseSize，不动 mBaseSize / D**：A8W8 场景下峰值翻倍 + AI 翻倍叠加，s2BaseSize 可从 128 放大到 256（Vector 反量化）或 512（Cube 硬件反量化，dequant 免费故可喂更大块）；mBaseSize 由 UB/ridge 决定、与量化无关，保持不变。
+- **s2BaseSize 放大受 L0/UB 再约束**：放大后若 L0B / UB 放不下，在基本块内部再切子循环（sub-loop）控制驻留，而非回退 s2BaseSize；L0 某端口因此退化单缓冲时须显式标注为容量所迫的退化。
+
+## 正确性约束
+
+- **I5 量化 scale 轴对齐**：scale 沿被消费乘法的 reduction 轴量化，禁止轴错位（否则输出 NaN / inf）。
+
+## 常见变体
+
+- **MXFP8**：power-of-two scale，per-block 布局
+- **INT8**：integer scale，per-tile 布局
+- **AntiQuant**：反量化后走原路径 + scale 回传

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

@@ -0,0 +1,35 @@
+# 稀疏 trait
+
+> 触发条件：KV 稀疏 pattern 由**外部数据给定**（稀疏索引 / 掩码张量），非块坐标解析可推导。稀疏 trait 不改变核心计算路径，仅影响块跳过。
+>
+> **边界**：causal / 滑动窗口 / Sink 等 pattern 由 Sq/Sk 坐标关系**解析确定**的规则掩码，属于 Feature，不触发本 trait——它们无需外部索引数据，块跳过仅需坐标比较，buffer 也无不定长问题。
+
+## 核心影响
+
+稀疏关注被 mask 掉的 KV 块，引入块跳过逻辑，buffer 与字段随之改变。
+
+## S3 buffer（不定长块）
+
+- 稀疏块长度不定，buffer 按最坏块长分配
+- 块跳过逻辑下的 buffer 生命周期
+
+实测要点（蒸馏自量产稀疏算子）：
+
+- **基本块仍是编译期常量**：不定长只表现为"有效长度 ≤ 常量块"，buffer 按常量 s2BaseSize 分配，稀疏索引的有效数量在运行时只裁剪**循环范围**，不改变块尺寸——稀疏度不进基本块。
+- **稀疏 KV 收集数据面（稀疏 trait 引入的前置 stage）**：当稀疏粒度是 token 级 / paged 时，分散的 KV 须先按索引 gather 聚合成连续块再供 Cube 消费。聚合由 Vector 侧完成，聚合结果经片外周转（多份槽池）交回 Cube——这实质是在 C1 之前插入一个 **V0 gather stage**，流水 stage 序列变为 `V0 → C1 → V1 → C2 → V2`，V0 的槽池份数与 K/V 槽池一致（≥ r+1）。
+- **地址计算可与数据搬运解相位**：paged 场景下"索引 → 物理块号 → 物理地址"的换算可用向量单元批量预计算（每拍处理一个对齐批的索引），其同步 flag 与 KV 数据搬运各自成对、互不阻塞。
+
+## S6 负载均衡（块跳过）
+
+- 稀疏块长度不定，块跳过逻辑影响任务切分与负载均衡
+- 跳过空块的调度方式
+
+实测要点：
+
+- **两级跳过**：行级（M 方向）——按稀疏窗口推导整行不可能有有效 KV 的阈值，跳过 M 轴前部无效块；块级（S2 方向）——按每行有效索引数裁剪 S2 循环上界，无效组合整块 continue。两级都须**双侧跳过**（GEMM 与 softmax 状态更新都跳，否则 NaN）。
+- **任务区间预算前置**：稀疏使每核实际工作量与索引分布强相关、kernel 内现场算均衡代价高——把 per-core 任务区间（起止坐标 + split-KV 槽位）在 host / 调度侧**预生成、以定长元数据传入**，kernel 只读表执行。这是稀疏变体在 arch35 类平台上的标配做法。
+- **G 维切分与稀疏的耦合**：若稀疏索引是逐 query 行独立的，G 合轴共享 KV 的前提被破坏——此时选"逐行任务（不切 G）"路线（见 trait-mla 的 S6 对照）；若索引按 kvHead 共享，仍可 split-G。
+
+## 常见变体
+
+- **BlockSparse**：块级稀疏，跳过空块的索引预计算