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

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

@@ -0,0 +1,241 @@
+# Buffer 规划（公式化清单）
+
+> 本步骤（S3）只产出**公式化 buffer 清单**：单份大小用符号（mBaseSize / s2BaseSize / D / d_s 等）表达，份数 N 用公式表达（预取深度作参数）。**大小数值由 S4 代入、份数数值由 S5 回填**（预取深度来自流水级数），两者齐备后以硬件内存为约束迭代校验。
+
+**回答：需要哪些 buffer？各自大小的符号公式？每个 buffer 的「生命周期」「物理份数 N」「跨 buffer 复用」分别是什么？**
+
+以下共享 K/V 槽池、P 的预填份数对应各自说明的候选模型。选定其他装载或交接排布时，按 [流水编排](pipeline.md) 回填逐对象的实际生命周期。max/sum、工作项缩放系数与 O_acc 分别记账。
+
+- 输入 buffer / 输出 buffer / 中间计算 buffer / 状态 buffer（max / sum / O_acc）
+- 各 buffer 单份大小公式（符号化，用 mBaseSize / s2BaseSize / D 等变量）
+- **数据生命周期**：常驻（KV 遍历期间数据不变）还是轮转（逐 KV 块替换覆写）
+- **物理份数 N**：分配几份 slot（1 份 / pingpong 2 份 / ring N 份），与生命周期正交
+- **Cube 侧 L0**（L0A / L0B / L0C）：份数**恒 pingpong（N = 2）**，不接受单缓冲（见下「L0」）
+- **跨 buffer 复用**：生命周期不重叠的不同 buffer 时分复用同一物理内存
+- 总占用 Σ = Σ(单份大小 × 份数)（符号化，大小待 S4 代入、份数待 S5 回填；L0 份数在 S3 即定死为 2）
+
+产出：
+- buffer 清单（名称 + 用途 + 符号化单份大小 + 生命周期 + 物理份数 N + 轮转方式）
+- 逐块占用分解（每个 buffer：单份大小 × N 份 = 小计）
+- 跨 buffer 复用方案
+- 总占用与容量校验的符号化公式
+
+## 三个正交维度：数据生命周期 × 物理份数 × 跨 buffer 复用
+
+「常驻」「轮转」「复用」分属三个正交维度，分开决策、分别标注：
+
+- **数据生命周期**：该 buffer 的数据在 KV 遍历过程中是否保持不变（数据特性，不涉及内存复用）。
+- **物理份数 N（slot 轮转）**：分配几个物理 slot 做预取 / 读写重叠。
+- **跨 buffer 复用**：生命周期不重叠的**不同 buffer** 时分复用同一块物理内存。**复用硬前提：格式（ND/NZ/DN）一致 + dtype 一致 + 生命周期不重叠**。
+
+> 例：Q_tile 生命周期上是**常驻**（切 KV 时，不同 KV 块与同一个 Q 块相乘，KV 在遍历、Q 块不动），物理上**仍可 pingpong 轮转**（Sq 分块时，算 Q 块 i 的同时预取 Q 块 i+1 到另一 slot）。二者可共存。S（fp32）消费完后其物理内存可被后续 tile 的别的 buffer **时分复用**——这是第三维，与前两维独立。
+
+### 维度一：数据生命周期
+
+| 生命周期 | 定义 | 命中 buffer |
+|---|---|---|
+| 跨块保留 | Q 保持不变，累计状态按 KV 顺序更新并承接旧值 | Q_tile、O_acc、max、sum |
+| 轮转 | 数据逐 KV 块替换（旧块数据失效、新块覆写） | K_tile、V_tile、S（UB）、P（UB 与 L1） |
+
+> **Q tile 块常驻是结构决策**：Q 在整个 Sk 遍历期间常驻片上（L1/UB），切 KV 块时不重复加载 Q，禁止每个 KV 块重搬 Q。
+>
+> 注：「轮转」描述的是**数据**逐块失效被覆写（生命周期特性），与「物理份数 N 的 slot 轮转」（维度二）是两层——前者说数据能活多久，后者说给几个物理槽。
+
+### 维度二：物理份数 N（轮转方式）
+
+| 份数 | 轮转方式 | 含义 |
+|---|---|---|
+| N = 1 | 单份 | 无读写重叠 |
+| N = 2 | pingpong | `slot = j % 2`，读写交替 |
+| N ≥ 2 | ring（预取深度 r） | `slot = j % N`，`r = N - 1`，更深预取 |
+
+### 交叉表：每个 buffer 的（数据生命周期, 物理份数）
+
+| Buffer | 数据生命周期 | 物理份数 N | 说明 |
+|---|---|---|---|
+| Q_tile `[mBaseSize, D]` | 常驻 | 1 或 ≥ 2 | 跨 KV 块复用不动；Sq 分块时可 pingpong 预取下一 Q 块 |
+| K/V 共享槽池 `[s2BaseSize, D]` | 轮转 | N_KV ≥ r+1 | K、V 单份同构，共享一个槽池按 `K(j),V(j),K(j+1),V(j+1)…` 交替承载（见下「K/V 共享槽池」） |
+| S `[mBaseSize, s2BaseSize]`（UB） | 轮转 | **恒 2** | L0C→UB 通路 pingpong，Cube 写 / Vector 读交替 |
+| P `[mBaseSize, s2BaseSize]`（UB vec1res） | 轮转 | **恒 2** | Vector 生产 / 搬出 L1 交替 |
+| P `[mBaseSize, s2BaseSize]`（L1） | 轮转 | **N_P_L1 = r + 1** | preload 阶段 Vector 连续产出多块 P 囤于 L1，与 K/V 槽池同构 |
+| O_acc `[mBaseSize, D]` fp32 | 跨块保留 | 尚未完成最后读取的 O_acc 份数 | 首次 V2 到输出读取完成，按 task 归属 |
+| max `[mBaseSize]` fp32 | 跨块保留 | 尚未完成最后读取的 max 份数 | 首次 V1 到最后使用，按 task 归属 |
+| sum `[mBaseSize]` fp32 | 跨块保留 | 尚未完成最后读取的 sum 份数 | 首次 V1 到最后使用，按 task 归属 |
+| alpha `[mBaseSize]` fp32 | 逐工作项保留 | 尚未被对应 V2 使用完成的版本数 | V1 产生，V2 延迟读取，与 task 槽分别编号 |
+| L0A `[subM, subK]` NZ | 轮转（逐 base 子块替换） | **恒 2** | 左操作数装载槽（Q / P）；单份则装载与矩阵乘串行 |
+| L0B `[subK, subN]` NZ | 轮转 | **恒 2** | 右操作数装载槽（K / V）；同上 |
+| L0C `[subM, subN]` fp32 | 轮转 | **恒 2** | 累加结果搬出槽（S / O_tile）；单份则矩阵乘与搬出串行 |
+
+### K/V 共享槽池
+
+当 `K_tile` 与 `V_tile` 的物理布局、类型与单份容量一致，且完成协议允许其存储复用时，可选择共享槽池；C1 消费 K(j)，C2 消费 V(j)。本模型在消费期间保留一个槽，其他槽用于预取：
+
+```
+N_KV ≥ r + 1        # r = 预取深度（已加载未消费的槽数）；+1 = 正在消费的槽
+```
+
+推导：C1 与 C2 在同一 Cube 单元上**串行**（Cube 核一次只跑一个 GEMM），稳态下任意时刻最多 1 个槽在被消费；其余槽全部可用于预取。槽位按数据流顺序 `K(j), V(j), K(j+1), V(j+1)…` 依次承载，物理槽在 K/V 间交替复用。
+
+- **r 由 S5 的实际预取排布决定**；份数覆盖尚未释放的预取与消费对象，选择更深预取时重新校验 Σ 容量、同步与收益。
+- 相比 K、V 各自独立 ring（各自需 r+1 槽、共 2r+2 槽），共享池只需 r+1 槽：省下的槽来自「同一时刻只有一个槽在被消费」——独立 ring 中未消费的 ring 槽无法跨张量挪用，共享池可以。
+- 约束：槽的释放须等其承载的 K 被 C1（或 V 被 C2）消费完，同步按槽序保证，**禁止 K/V 混用导致 C1/C2 读错槽**。
+
+### 状态 buffer 轮转语义（max / sum / O_acc）
+
+同一 task 的递推保持稳定逻辑归属，每次更新承接该 task 的正确旧值。max/sum 由 V1 更新，O_acc 由 V2 更新；初始化和最终释放按各自阶段定位。alpha 按工作项保留旧版本，直到所属 V2 使用完成。
+
+分别计算各状态的最大同时占用，再校验容量。多个短 task 交错时，max/sum 可以超过两份；V2 按 task 顺序推进且最终输出完成后再初始化下一 task 时，O_acc 可以独立用一份。具体推导见 [四阶段示例](pipeline-example.md)。容量不足时调整排布或块大小，并同步修改等待和释放。
+
+### L0：恒 pingpong（结构硬约束）
+
+Cube 处理一个 base 子块要串行走完三条通路，三条各由**不同硬件单元**承担：
+
+```
+L1 ──(装载单元)──> L0A / L0B ──(矩阵乘单元)──> L0C ──(搬出单元)──> UB
+```
+
+单元不同 ⇒ 三者落在**不同 slot 上**可以真正并行。因此相邻块重叠的前提是每个端口各留 2 份 slot：块 j 在算的同时，块 j+1 的装载（或块 j−1 的搬出）在另一个 slot 上进行。
+
+| 端口 | 单缓冲（N=1）的后果 | pingpong（N=2）后 |
+|---|---|---|
+| L0A / L0B | 装载块 j+1 必须等块 j 的矩阵乘读完，否则覆写正在被乘的操作数 → **装载与矩阵乘串行** | 装载块 j+1 与块 j 的矩阵乘并行 |
+| L0C | 块 j+1 的累加结果无处可写，必须等块 j 的 L0C→UB 搬完 → **矩阵乘与搬出串行** | 搬出块 j 与块 j+1 的矩阵乘并行 |
+
+结论：
+
+```
+N_L0A = N_L0B = N_L0C = 2      # 结构硬约束，不接受 N = 1
+```
+
+- **单缓冲 = 流水阻塞**：任一端退化到单份，该端两侧立刻串行，Cube 有效利用率腰斩（加载 / 搬出时间被完全暴露在关键路径上）。这属于 patterns.md 纪律中"把退化配置作为设计目标"的禁止项。
+- **与流水级数 r 正交**：r 描述 GM→L1 的 KV 槽池深度（S5 回填）；L0 是 **Cube 内部块级重叠**，份数恒 2，不随 r 增长、不经 S5 回填——S3 直接定死为 2。
+- **容量是唯一上界**：pingpong 使 L0A / L0B / L0C 各按 2 份计入 L0 容量（S4 校验，`2 × 单份 ≤ S_L0X`）。容量放不下时**缩小 subM / subN / subK（或减小 s2BaseSize）**，**禁止**退回单缓冲。
+- **三个端口独立成槽**：L0A / L0B / L0C 是三个独立物理缓冲，左操作数、右操作数、累加结果的角色与格式均不同，**禁止跨端口共用 slot**。
+
+## 份数决策规则
+
+```
+# 各状态分别按尚未完成最后读取的对象计数
+N_ms = max_t active_tasks_with_unreleased_max_sum(t)
+N_Oacc = max_t active_tasks_with_unreleased_Oacc(t)
+N_alpha = max_t active_workitems_with_unconsumed_alpha(t)
+
+# 常驻 buffer：份数与生命周期无关，按预取需求独立定
+N_Q = 1（不预取） 或 ≥ 2（Sq 分块时预取下一 Q 块）
+
+# 轮转 buffer：K/V 共享槽池 ≥ 预取深度 + 1；S（UB）恒 2；P（UB）恒 2；P（L1）= r + 1
+N_KV ≥ r + 1          # K、V 共享槽池，交替承载；C1/C2 同 Cube 串行故同时仅 1 槽在消费；取更大值加深预取
+N_S = 2               # L0C→UB 通路 pingpong，Cube 写 / Vector 读交替
+N_P_UB = 2            # Vector 生产 / 搬出 L1 交替
+N_P_L1 = r + 1        # preload 阶段 Vector 连续产出多块 P 囤于 L1，与 K/V 槽池同构
+
+# L0：恒 pingpong，与 r 无关、不经 S5 回填（S3 定死）
+N_L0A = N_L0B = N_L0C = 2     # 硬约束：单缓冲则装载/计算/搬出三者串行 → 流水阻塞
+```
+
+> 唯一「禁止轮转」的硬约束只落在**跨块累积状态的 task 内期间**（max / sum / O_acc，I3）；其跨 task 份数与其余 buffer 的 N 一样由流水 / 预取 / 容量独立决定，与「常驻 / 轮转」生命周期正交，**不因常驻就必须 N=1**。公式中的「预取深度」参数由 S5 流水编排提供，本步骤只出规则。
+
+## 总占用公式（含份数）
+
+```
+单份大小 size_i（符号化，代入 mBaseSize/s2BaseSize/D/d_s）
+Σ_total = Σ_i (size_i × N_i)
+        = size_Q×N_Q + size_KV×N_KV + size_S×2 + size_P×(2 + N_P_L1)
+        + size_Oacc×N_Oacc + size_max×N_ms + size_sum×N_ms + size_alpha×N_alpha
+        # K/V 与 P 的份数对应所选预取模型；各状态份数按各自最后读取推导
+
+Σ_L0（逐端口独立校验，不合并为一个池）
+     = 2 × size_L0A ≤ S_L0A      # size_L0A = subM × subK × d_s
+     = 2 × size_L0B ≤ S_L0B      # size_L0B = subK × subN × d_s
+     = 2 × size_L0C ≤ S_L0C      # size_L0C = subM × max(subN, D) × d_FP32（C1/C2 共用该端口）
+```
+
+容量校验对 UB / L1 / L0 分层，每层只累加驻留在该层的 buffer 的 `size_i × N_i`（S4 代入大小、S5 代入份数后校验）。
+
+- **以 N 表达流水策略，不省略**：份数 N 就是流水的物理体现（N=1 是单缓冲串行，N=2 是 pingpong，N=3 是更深预取）。只写"双缓冲"不落到 N 等于没定份数。
+- **约束归属按 buffer 生命周期 × 驻留层对位**：轮转 buffer（K/V 槽池、S、P、O_tile，块内一拍生产即消费、旧块失效被覆写）份数由流水级数/双缓冲定，其预取放大部分（K/V 槽池与 P 的 L1 份数，均 = r+1）驻留 L1、只受 L1 约束，UB 中的 S/P/O_tile 份数不随 r 增长；常驻状态 buffer（max/sum/O_acc，跨块保留、按累积域（task）各持一份）份数 = 同时活跃累积域数，活跃块（已进入流水、stage 序列未完成）跨多个 task 时该数随 r 增长、受 UB 约束；L0（L0A / L0B / L0C）份数恒 2、**与 r 无关**，只受 L0 容量约束（且各端口独立校验，不合并）。禁止跨层级 / 跨属性错配论证（如一律用 UB 余量限制 r，或忽略状态 buffer 的活跃域多份，或把 L0 容量省下来换 r）。
+
+> **校验口径必须按 CV 配比分层**：
+> - **UB 层（Vector 侧）**：1:2 型架构下 V1/V2 按 mBaseSize 行维在搭档 Vector 核间分摊，每核只驻留 `mBaseSize/r_cv` 行 ⇒ 按「每 Vector 核占用 ≤ 单核 UB」校验，即 UB 各 buffer 的 mBaseSize 以 `mBaseSize/r_cv` 代入。Cube 写入 UB 的 S / O_tile 同样按行切片落各核，适用同一口径。
+> - **L1 / L0 层（Cube 侧）**：按全量 mBaseSize 校验，不分摊。
+>
+> 若直接把全量 UB buffer 对单核 UB 校验（等效 1:1），会把 mBaseSize 人为压低一档（例如 D=128 时 256→128），丢失近一半 prefill 性能上限。
+
+## 实例：典型 FA 的 buffer 分层
+
+> 一份标准 FlashAttention 片上 buffer 分层参考，展示「复用语义 × 物理份数 × 层级 × dtype」如何落到真实算子。Q / K / V / P 用 fp16/bf16；GEMM 输出与 softmax 状态用 fp32。
+
+### 分层总览
+
+| 层 | buffer | 形状 | dtype | 格式 | 生命周期 | 物理份数 N |
+|---|---|---|---|---|---|---|
+| L1 | Q | `[mBaseSize, D]` | fp16/bf16 | NZ（GEMM 操作数） | 常驻 | 1 或 ≥2 |
+| L1 | K | `[s2BaseSize, D]` | fp16/bf16 | NZ | 轮转 | ≥2 |
+| L1 | V | `[s2BaseSize, D]` | fp16/bf16 | NZ | 轮转 | ≥2 |
+| L1 | P | `[mBaseSize, s2BaseSize]` | fp16/bf16 | **NZ（UB→L1 仅 NZ 通路）** | 轮转 | r + 1 |
+| L0A | 左操作数（Q / P） | `[subM, subK]` | fp16/bf16 | NZ | 轮转 | **2（硬约束）** |
+| L0B | 右操作数（K / V，转置形式） | `[subK, subN]` | fp16/bf16 | NZ | 轮转 | **2（硬约束）** |
+| L0C | 累加结果（S / O_tile） | `[subM, subN]` | fp32 | —（累加器） | 轮转 | **2（硬约束）** |
+| UB | bmm1res = S | `[mBaseSize, s2BaseSize]` | fp32 | ND（L0C 输出原生 ND） | 轮转 | 2 |
+| UB | max | `[mBaseSize]` | fp32 | —（一维） | 常驻 | 1 |
+| UB | sum | `[mBaseSize]` | fp32 | —（一维） | 常驻 | 1 |
+| UB | vec1res = P | `[mBaseSize, s2BaseSize]` | fp16 | **NZ（须在 UB 侧排成 NZ 再搬 L1）** | 轮转 | 2 |
+| UB | bmm2res = O_tile | `[mBaseSize, D]` | fp32 | ND | 轮转 | 2 |
+| UB | vec2res = O_acc | `[mBaseSize, D]` | fp32 | ND | 常驻 | 1 |
+
+> 格式列是**复用决策的硬输入**（前提见本文「三个正交维度」维度三）。S（ND, fp32）与 vec1res P（NZ, fp16）格式与 dtype 双不同，**禁止同槽**；O_tile（ND, fp32）与 S 格式与 dtype 一致、生命周期不重叠（S(j) 消费完后 O_tile(j) 才产生），**可同槽时分复用**。
+
+### 分层规则
+
+- **L1 放 GEMM 输入操作数**：Cube 只从 L1→L0A/L0B 取数，Q / K / V / P 都是矩阵乘输入，故都经 L1。
+- **UB 放 GEMM 输出 + Vector 工作区**：S / O_tile 由 L0C 搬入 UB，softmax / 累积（Vector）在 UB 上完成。
+- **P 在 L1 的原因**：PV 相乘在 Cube 核，P 是 BMM2 左输入，必须经 L1→L0A。
+- **L0 全 pingpong**：L0A / L0B / L0C 各 2 份（**不可省**，论证见本文「L0」）。
+
+### 数据流（C1 → V1 → C2 → V2）
+
+```
+C1: Q,K(L1 NZ→L0A/L0B) → Cube S=QK^T → L0C → UB(bmm1res, fp32, ND)
+V1: UB 上 reduceMax→max、exp→cast fp16 并按 NZ 排布存 vec1res、reduceSum→sum
+    vec1res(P, NZ) 经 UB→L1（仅 NZ 通路）搬成 L1 的 P
+C2: P,V(L1 NZ→L0A/L0B) → Cube O_tile=PV → L0C → UB(bmm2res, fp32, ND)
+V2: O_acc = exp(m_prev−m)·O_acc + bmm2res（UB 上，vec2res=O_acc, ND）；末块 O = O_acc/sum
+```
+
+### dtype 约定
+
+- **vec1res（P）是 UB 上唯一 fp16**：softmax 算出 P 后在 UB 上 cast 成 fp16 再存 vec1res，搬去 L1 的 P 已是 fp16。
+- **其余 UB buffer 全 fp32**：S、O_tile、max、sum、O_acc 保持 fp32，与「中间 softmax 状态（max/sum/O_acc）以 fp32 计算」一致 —— P 不属于 fp32 状态。
+
+### 命名映射
+
+| CANN 常见命名 | 含义 |
+|---|---|
+| bmm1res | S = QK^T 结果 |
+| bmm2res | O_tile = PV 单块结果 |
+| vec1res | P = softmax 结果（cast 后 fp16） |
+| vec2res | O_acc = 跨块累积输出 |
+
+> bmm1res（S, fp32, ND）用毕后其空间可复用给 bmm2res（O_tile）；vec1res（P, fp16, NZ）必须与 S 独立分块——复用前提与反例见本文「三个正交维度」维度三及上表注。
+
+> 量化变种需额外的 scale buffer 与回传路径，按量化 trait 规则处理。
+> 稀疏变种块长不定，buffer 按最坏块长分配。
+
+## 结构决策：∝ m×D 的 buffer 是否 streaming
+
+若存在尺寸 ∝ m × D 的常驻 buffer（典型如 O_acc `[mBaseSize, D]`），大 D 下必然溢出 → **必须**移出片上、改存片外 workspace，按 chunk 流式读回：
+
+```
+chunk 行数 = 预算字节 / (D_align × 字节宽)
+```
+
+这是**结构决策**（非数值标定）：定死后须有显式字段承载，禁止由实现自行改回常驻。
+
+streaming 到片外的 buffer（及 split-KV 的 partial max / sum / O_acc）落在一块**片外 workspace（GM）** 中，其总量按并发 task 槽位估算：
+
+```
+workspaceTotal = Σ(per-slot 段大小) × 并发槽位数
+并发槽位数 = min(totalTasks, usedCoreNum)   // ≈ 核数，不是总任务数
+```
+
+`totalTasks` = 任务总数、[M 分块 × S2 分块] 展开；`usedCoreNum` = 实际参与计算的核数（运行时输入）。按 `totalTasks` 分配会放大数百倍，推理小 batch 场景易超内存。

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

@@ -0,0 +1,111 @@
+# 单核计算流
+
+> 本步骤（S2）定义**核内数据流**与**核间流水**两个层次，是 S3 Buffer 规划、S4 性能建模、S5 流水编排的逻辑前置。
+>
+> **边界**：本步骤只描述数据流方向与 stage 接力（数据沿哪些缓存层级流动、跨核如何传递），**不决定切块**（tile 大小 / subM / subN / subK 等）；切块是 S4 性能建模的职责。
+
+**回答两个问题：**
+
+1. **核内**：单个 Cube 核 / Vector 核内部，数据在 GM / L1 / L0A / L0B / L0C / UB 之间如何搬运（通道连接）？
+2. **核间**：Cube 与 Vector 两个计算单元如何接力（stage 序列 + 跨核通道）？
+
+产出：
+
+- 核内数据流：Cube 核内通路 + Vector 核内通路
+- 核间 stage 序列 + 跨核通道
+
+下面的 C1 → V1 → C2 → V2 四阶段、核内搬运路径与跨核通道，只是\*\*标准 FlashAttention（无 feature 的 GQA / MHA）\*\*的一个典型示例，并非所有变体都必须遵守的唯一形式。
+
+## 核内数据流
+
+数据以「通道」为单元流动：一条通道连接两个缓存层级，数据沿通道单向搬运；通道的份数（pingpong / ring）由 S3 Buffer 规划确定，本步骤只标通道方向。
+
+### Cube 核内（矩阵乘 stage）
+
+矩阵乘沿专用硬件通路流动：
+
+```
+GM ──ND──>(GM→L1 搬运自带 ND→NZ)──> L1(NZ) ──NZ──> L0A / L0B(NZ) ──(矩阵乘)──> L0C ──ND──> UB
+```
+
+- 输入操作数先驻留 L1，再送入 L0A（左矩阵）/ L0B（右矩阵，转置形式）
+- 矩阵乘在 L0C 累加出结果，从 L0C 搬到 UB（ND），交给 Vector 侧
+- L0A / L0B / L0C 恒 pingpong（N=2，结构硬约束）
+
+C1 / C2 两个 stage 的核内通路：
+
+| stage | 左操作数                    | 右操作数                         | 结果                 |
+| ----- | ----------------------- | ---------------------------- | ------------------ |
+| C1 QK | Q：GM(ND)→L1(NZ)→L0A(NZ) | K：GM(ND)→L1(NZ)→L0B(NZ)（K^T） | S：L0C→UB(ND)       |
+| C2 PV | P：L1(NZ)→L0A(NZ)        | V：GM(ND)→L1(NZ)→L0B(NZ)（V^T） | O\_tile：L0C→UB(ND) |
+
+> 数据流层面的复用语义：Q 常驻 L1（KV 遍历期间不重载，GM→L1 一次），K / V 流式（随 KV 遍历加载）。各 buffer 的份数与大小分别在 S3 / S4 决定，本步骤仅标数据流方向。
+
+### Vector 核内（softmax / 累积 stage）
+
+数据在 UB 上做逐元素计算，通路：
+
+```
+UB(ND)（读入 S / P@V）──(逐元素计算)──> UB（P / O_acc）
+UB ──仅 NZ──> L1（P 交接给 Cube）     UB(ND) ──> GM（最终 O 写回）
+```
+
+- **softmax**：UB 上读 S（ND），做 scale / mask / rowmax / exp，产出 P（cast 后）到 UB，再搬到 L1 供 Cube 的 PV 用。**P 必须在 UB 侧就排成 NZ 布局**——「cast 出 P」与「排成 NZ」是同一 V1 stage 内必须完成的事
+- **累积**：UB 上读 P\@V（ND），累积到 O\_acc（UB，ND），末块归一化后 cast 写回 GM（ND）
+
+## 核间流水（跨 Cube / Vector 的 stage 接力）
+
+同一 KV 分块内严格 `C1 → V1 → C2 → V2`（I1，禁止重排）；末块归一化只在最后 KV 块做一次。
+
+| stage | 计算单元   | 操作                                                | 输入 → 输出          |
+| ----- | ------ | ------------------------------------------------- | ---------------- |
+| C1    | Cube   | `S = Q·K^T × scale`                               | Q, K → S         |
+| V1    | Vector | softmax：`reduceMax` / `exp` / `reduceSum`（含 mask） | S → P, max, sum  |
+| C2    | Cube   | `O_tile = P·V`                                    | P, V → O\_tile   |
+| V2    | Vector | 跨块累积 `O_acc = exp(m_prev−m)·O_acc + O_tile`       | O\_tile → O\_acc |
+| 末块    | Vector | `O = O_acc / sum`（仅一次）                            | O\_acc → O 写回 GM |
+
+跨核通过**跨核通道**传递中间结果（生产者写、消费者读）：
+
+| 交接   | 生产者        | 消费者        | 通道所在层级 | 格式                                |
+| ---- | ---------- | ---------- | ------ | --------------------------------- |
+| S    | Cube（C1）   | Vector（V1） | UB     | ND（L0C 输出原生 ND）                   |
+| P    | Vector（V1） | Cube（C2）   | L1     | **NZ（UB→L1 仅 NZ，P 须在 UB 侧排成 NZ）** |
+| P\@V | Cube（C2）   | Vector（V2） | UB     | ND                                |
+
+> **CV 配比与行维分摊**：1:2 型架构下 1 个 Cube 搭档 r\_cv=2 个 Vector 核，V1/V2 按 mBaseSize 行维在搭档核间对半并行；L0C→UB 的 S / O\_tile 按行切片落入对应 Vector 核的 UB，UB→L1 的 P 由各核分别搬出自己那半行（各核 NZ 分形独立成块）。状态 max/sum/O\_acc 每核只持自己行段，无跨核归约。
+
+> P 是唯一「Vector 产出、Cube 消费」的中间量：Cube 的矩阵乘输入只从 L1→L0A 取数，P 须搬到 L1，且 NZ 布局由 Vector 在 UB 侧完成。
+
+## 完整数据流（核内 + 核间串起来）
+
+| stage      | 完整搬运路径                                                                   |
+| ---------- | ------------------------------------------------------------------------ |
+| C1 QK      | Q：GM(ND)→L1(NZ)→L0A(NZ)；K：GM(ND)→L1(NZ)→L0B(NZ)；L0A×L0B→L0C；S：L0C→UB(ND) |
+| V1 softmax | S：UB(ND) 读入→(scale/mask/rowmax/exp/cast)→P(UB, NZ)；P：UB→L1（仅 NZ 通路）      |
+| C2 PV      | P：L1(NZ)→L0A(NZ)；V：GM(ND)→L1(NZ)→L0B(NZ)；L0A×L0B→L0C；O\_tile：L0C→UB(ND)  |
+| V2 累积      | P\@V：UB(ND) 读入→(rescale+add)→O\_acc(UB, ND)；末块 O\_acc→(cast)→GM(ND)      |
+
+## 与 S5 流水编排的边界
+
+- 本步骤定**逻辑计算流**：核内搬运通路 + 核间 stage 序列（做什么、谁做、数据怎么流）。
+- S5 流水编排定**物理排布**：stage 如何重叠 / 几级流水 / 同步语义（怎么排）。
+- 本步骤的 stage 顺序与跨核通道方向是 S5 的输入约束（I1 不可重排）。
+
+## 特性对 stage 序列的改造
+
+上面的 `C1 → V1 → C2 → V2` 只是无 feature 的基线。命中 trait 后 stage 序列按需改造，本步骤须按实际 trait 重新梳理 stage 与跨核通道，禁止照搬基线：
+
+| trait | stage 序列变化 | 新增 / 修改的跨核通道 |
+| --- | --- | --- |
+| 稀疏（token/paged 粒度） | C1 前插入 **V0 gather** stage → `V0 → C1 → V1 → C2 → V2` | 聚合结果经片外周转交回 Cube，槽池份数与 K/V 一致（≥ r+1） |
+| 量化（Vector 预反量化） | V1 内新增 dequant 子步骤，或新增独立 dequant stage | 反量化结果 UB→L1 回灌；P scale 随 P 写回 L1 |
+| 量化（Cube 硬件反量化） | stage 序列不变，scale 作为 GEMM 额外输入 | scale 驻留 L1 与数据同层 |
+| MLA | GEMM 语义改变（latent absorption 进 Q 侧），D 方向超宽需内迭代 | Q 沿 D 切分多次载入，latent 维决定 L0 子块约束 |
+
+各 trait 的具体 stage 定义见对应 trait 文件；多 trait 叠加时按各自插入位置组合（如稀疏+量化 = `V0 → dequant → C1 → …`），并重新校验跨核通道的格式与驻留层约束。
+
+## 检查点
+
+- [ ] stage 序列完整（覆盖计算图全部节点），数据流方向与 I1 一致（无 stage 重排）
+- [ ] 计算图逐 buffer 标注格式（ND / NZ / DN）；所有 UB→L1 搬运的 buffer（如 P）在 UB 侧即为 NZ

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

@@ -0,0 +1,42 @@
+# 负载均衡策略
+
+> 与 tiling 核心（基本块 / Buffer / 流水）解耦，放在流程末尾单独决策。
+>
+> 本文给的是**决策框架 + 候选手段 + 权衡**，不是固定套路。具体选型随形态（GQA / MHA / MLA）、trait（稀疏 / 量化）、芯片与 spec 变化，由 agent 结合输入自行判断。
+> 参考案例：非量化 GQA 的分核元数据预生成见 [flash_attn-arch35-best-practices.md](../design_sample/flash_attn-arch35-best-practices.md) 的 S6——**仅是其中一种做法，可借鉴而非照搬**。
+
+**回答：任务如何分配到多个计算核，并保证负载均衡？**
+
+产出（每个决策点给出选择 + 理由，不必面面俱到）：
+
+- **任务维度构造**：沿哪些轴切、任务粒度多大。
+  - 常见：`(B × 头)` × M 轴块（`Sq × G` 合轴或纯 `Sq`）× KV(S2) 轴块；头轴取 kvHead 还是 qHead 取决于是否合轴。
+  - 稀疏 / MLA 等可能改变切分轴（如不切 G、按行任务），以 trait 契约为准。
+  - 顺带估个任务数上界量级，用于判断核数是否吃得下。
+- **负载怎么估**：估算口径决定分配精度。
+  - 从简到繁：块数（最简）→ 加权代价（区分满块 / 尾块 / 行首开销）→ 平台实测 / 拟合代价。
+  - 模型越细越准、实现与调参成本越高；按 shape 差异程度和收益取舍，并让**估算口径与分配粒度自洽**。
+- **用几个核**：先定并行度，再谈怎么分。
+  - 可选：吃满可用核（简单）；或在合法区间（下界 ~ 与任务粒度相关，上限 = `min(设备核数, 任务数)`）内评估取更优（如最慢核耗时最小）。
+  - 权衡：核数过多有空核 + 调度/同步开销，过少有慢核拖尾；任务数 < 核数时必然有核空闲，此时考虑下面的 split-KV。
+- **怎么摊到核上**：分配启发式。
+  - 可选：均匀切片（基准）/ 分级贪心（先粗后细）/ 水位线 + 容差 / 二分搜索阈值 / 其他自创启发式。
+  - 共性要点：以「块 / 行」为最小分配单位减少碎片；容差类机制可避免「差一点装不下」浪费核数。
+- **稀疏怎么剪**：跳过无效 KV 块（仅命中稀疏 trait / 规则掩码时）。
+  - 常见：按 M 行推导有效 S2 块区间（causal → 下三角、band → 对角带），区间外整块跳过；行级 + 块级两级。
+  - 注意**双侧跳过**（GEMM 与 softmax 状态更新都跳，否则 NaN）；细则见 [trait-sparse.md](./trait-sparse.md)。
+- **要不要 split-KV（FlashDecoding）**：核数富余时的补核 / 均载手段。
+  - 适用动机：M 轴小（decode 短行）→ 任务数少、核数富余，且 KV 够长值得切。这是 decode 短行优化的常见承载点。
+  - 权衡：能补核数与均载，但引入跨任务 reduce 与 workspace。启用判据可以是简单阈值（核数富余 + KV 足够长），也可以是「切 / 不切」两套方案的收益比较——由 agent 按精度需求选。
+
+可选手段参考（非规范，可选用或另起炉灶）：
+- **L2 复用段**：按 L2 预算把相邻 head 归组为段、段内共享 Q/K/V 驻留、段间独立调度；L2 预算未知或数据规模小时不分组。
+
+禁止：
+- 核数硬编码；核数应作为运行时输入
+
+检查点：
+- [ ] 任务空间完整覆盖、无重复、无遗漏
+- [ ] 负载估算口径与分配粒度自洽（用块数估就按块分配；用加权代价则考虑尾块 / 剪枝后的有效块）
+- [ ] 核数来源为运行时输入，且给出核数取值的理由
+- [ ] 启用 split-KV 时已配跨任务 reduce（I4），并说明启用理由

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

@@ -0,0 +1,173 @@
+# FA 四阶段时序与状态示例
+
+适用于采用 C1→V1→C2→V2 的在线 softmax 计算图，Cube、Vector 可独立推进，同一 task 的有效 KV 工作项连续排列。该例选择 Cube 先 C1 后 C2、Vector 先 V1 后 V2；阶段偏移与份数对应本排布。输入装载、额外阶段、交错 task 或更长异步存续区间另行推导。
+
+参考依据为 `cannbot-arena/samples/flash_attn/flash_attn.py` 中的任务推进、四阶段交接和分开的状态版本。本文展开算法与完成协议；实际物理布局、分配深度及类型在所选路径的资源预算中代入。
+
+## 1. 公式与状态所有权
+
+对 task g 的 KV 工作项 n，逐输出行定义：
+
+```text
+C1: S_n = Q_g * K_n^T
+V1: Z_n = scale * S_n，按语义应用掩码
+    m_n = max(m_prev, row_max(Z_n))
+    alpha_n = exp(m_prev - m_n)
+    P_n = exp(Z_n - m_n)
+    l_n = alpha_n * l_prev + row_sum(P_n)
+C2: B_n = P_n * V_n
+V2: U_n = alpha_n * U_prev + B_n
+末项: O_g = U_last / l_last
+```
+
+首次有效项取 `m_prev=-inf、l_prev=0`，首次 V2 直接令 U=B；本例每个工作项的各行有有效分数。全掩码、零工作项及特殊数值按接口语义展开相应转移。P 的转换与累积精度由数值计算链实例化。
+
+| 对象 | 更新者 | 后续读取 | 保留范围 |
+|---|---|---|---|
+| task 的 max/sum，即 m、l | V1，按该 task 的 KV 顺序 | 后续 V1；末次 V2 读取最终 l | 首次 V1 到最终读取完成 |
+| 工作项的 alpha | 对应 V1 | 对应 V2 | 当前 V1 到延迟 V2 的最后读取 |
+| task 的输出累计 U | V2，按该 task 的 KV 顺序 | 后续 V2 与最终输出 | 首次 V2 到输出读取完成 |
+
+V1 可继续更新同一 task 的 m/l，V2 使用所属工作项已保存的 alpha；非末次 V2 只更新 U，末次 V2 读取最终 l。该 task 的末次 V1 已完成，且其状态尚未被新 task 覆盖。这些条件支持本例的 V1 先于 V2。
+
+## 2. 工作项与完整时序
+
+g 是当前任务流中连续推进的有效 task 序号，w 是有效工作项的连续发射序号；输出坐标另行记录。全局工作项携带 `D[w]=(task 序号 g, 实际 KV 序号 n, n_begin, n_end, 有效行列, 输出范围)`。首次判断为 n=n_begin，末次判断为 n=n_end-1；task 的起点可以非零。状态槽按有效 task 序号轮转，alpha 槽按工作项发射序号轮转。
+
+| w | task g | 有效区间 | n | 首次 / 末次 |
+|---|---|---|---|---|
+| 0 | 0 | [3,5) | 3 | 是 / 否 |
+| 1 | 0 | [3,5) | 4 | 否 / 是 |
+| 2 | 1 | [0,1) | 0 | 是 / 是 |
+| 3 | 2 | [7,8) | 7 | 是 / 是 |
+| 4 | 3 | [1,3) | 1 | 是 / 否 |
+| 5 | 3 | [1,3) | 2 | 否 / 是 |
+| 6 | 4 | [2,3) | 2 | 是 / 是 |
+| 7 | 5 | [5,6) | 5 | 是 / 是 |
+
+调度步 t 中，Cube 先 C1(t) 后 C2(t-2)，Vector 先 V1(t-1) 后 V2(t-3)。索引在 `[0,N)` 内才发射；同一资源栏中的两个阶段顺序执行。调度步表示依赖与发射顺序，实际重叠由完成协议与目标资源支持。
+
+| t | 推进阶段 | Cube 顺序 | Vector 顺序 | task 状态的关键动作 |
+|---|---|---|---|---|
+| 0 | warmup | C1(0) | — | — |
+| 1 | warmup | C1(1) | V1(0) | 初始化 task0 的 m/l |
+| 2 | warmup | C1(2) → C2(0) | V1(1) | 更新 task0 的 m/l |
+| 3 | steady | C1(3) → C2(1) | V1(2) → V2(0) | 初始化 task1 的 m/l；首次更新 task0 的 U |
+| 4 | steady | C1(4) → C2(2) | V1(3) → V2(1) | 初始化 task2 的 m/l；输出 task0 并释放其状态 |
+| 5 | steady | C1(5) → C2(3) | V1(4) → V2(2) | 初始化 task3 的 m/l；输出 task1 |
+| 6 | steady | C1(6) → C2(4) | V1(5) → V2(3) | 更新 task3 的 m/l；输出 task2 |
+| 7 | steady | C1(7) → C2(5) | V1(6) → V2(4) | 初始化 task4 的 m/l；首次更新 task3 的 U |
+| 8 | drain | C2(6) | V1(7) → V2(5) | 初始化 task5 的 m/l；输出 task3 |
+| 9 | drain | C2(7) | V2(6) | 输出 task4 |
+| 10 | drain | — | V2(7) | 输出 task5；全部释放 |
+
+## 3. 各对象的槽与代次
+
+| 对象 | 本例份数与索引 | 生产 | 最后读取与释放 | 推导依据 |
+|---|---|---|---|---|
+| S 队列 | 2，槽 w mod 2 / 代 floor(w/2) | C1(w)，步 w | V1(w)，步 w+1 | 两资源可先生产新项再释放旧项 |
+| P 队列 | 2，槽 w mod 2 / 代 floor(w/2) | V1(w)，步 w+1 | C2(w)，步 w+2 | 相邻生产、消费间最多持有两项 |
+| B 队列 | 2，槽 w mod 2 / 代 floor(w/2) | C2(w)，步 w+2 | V2(w)，步 w+3 | 两资源可先生产新项再释放旧项 |
+| alpha 版本 | 3，槽 w mod 3 / 代 floor(w/3) | V1(w)，步 w+1 | V2(w)，步 w+3 | 同一步先 V1(w+2) 再 V2(w)，可同时持有三项 |
+| task 的 m/l | 3，槽 g mod 3 / 代 floor(g/3) | 首次 V1 | 末次 V2 的最终读取 | 步4初始化 task2 后仍保留 task0、task1 的状态 |
+| U | 1，所属 task 在首次 V2 切换 | 首次 V2 初始化，后续 V2 更新 | 末次输出的最后读取 | V2 按全局工作项顺序执行，前一 task 输出完成后再初始化下一 task |
+
+连续 task 模型下，末次 V1 到末次 V2 跨两步；新 task 每步到来时，m/l 最多三份未释放。U 的初始化发生在首次 V2，因此该排布可独立使用一份 U。alpha 每工作项一版，其索引与 m/l 的 task 索引分别推进。
+
+本例交接队列的份数为所示完成协议的推导值；额外预取、异步读者或实际采用的更深分配各自记账。物理量按池分别汇总：`2*bS + 2*bP + 2*bB + 3*bAlpha + 3*bML + bytes_U`，另加 Q/K/V、副本、转换临时区、同步及描述存储。各 b 包含实际类型、步长、布局、对齐与填充。
+
+每槽记录所属 task/工作项和代次。写完成且对读者可见后发布 READY，最后读取完成后释放。m/l 保留到最终 l 的读取完成；U 保留到输出读取完成；alpha 保留到所属 V2 使用完成。
+
+## 4. warmup / steady / drain 伪代码
+
+以下完成操作表达抽象协议。两角色各自按顺序执行阶段，并通过依赖与可用槽等待推进。
+
+```text
+run(N, D):
+    if N == 0:
+        complete_boundary_outputs()
+        return
+    initialize_ownership_and_generations()
+    start_roles_concurrently(Cube, Vector):
+        for t in [0, min(N,3)): advance(role, t, N)   # warmup
+        for t in [3, N):       advance(role, t, N)   # steady
+        for t in [N, N+3):     advance(role, t, N)   # drain
+    join_roles_and_finish_outputs()
+
+advance(Cube, t, N):
+    if 0 <= t   < N: C1(t,   D[t])
+    if 0 <= t-2 < N: C2(t-2, D[t-2])
+
+advance(Vector, t, N):
+    if 0 <= t-1 < N: V1(t-1, D[t-1])
+    if 0 <= t-3 < N: V2(t-3, D[t-3])
+
+C1(w, d):
+    s = acquire_free(S, w mod 2, floor(w/2))
+    write(s, d, Q[d.g] * K[d.n]^T)
+    publish_after_write_complete(s, w)
+
+V1(w, d):
+    s = wait_ready(S, w, floor(w/2))
+    if d.first:
+        ml = acquire_free(ML, d.g mod 3, floor(d.g/3))
+        initialize(ml, owner=d.g, max=-inf, sum=0, next_n=d.n_begin)
+    else:
+        ml = wait_owned(ML, d.g, floor(d.g/3))
+    require(ml.next_n == d.n)
+    z = scale_and_apply_mask(s, d.valid_extent)
+    m_new = max(ml.max, row_max(z))
+    alpha = exp(ml.max - m_new)
+    p_value = exp(z - m_new)
+    ml.sum = alpha * ml.sum + row_sum(p_value)
+    ml.max = m_new
+    ml.next_n = d.n + 1
+    complete_online_state_update(ml)
+    a = acquire_free(Alpha, w mod 3, floor(w/3))
+    write(a, d, alpha)
+    publish_after_write_complete(a, w)
+    p = acquire_free(P, w mod 2, floor(w/2))
+    write(p, d, convert_as_designed(p_value))
+    publish_after_write_complete(p, w)
+    release_after_last_read(s)
+
+C2(w, d):
+    p = wait_ready(P, w, floor(w/2))
+    b = acquire_free(B, w mod 2, floor(w/2))
+    write(b, d, p.value * V[d.n])
+    publish_after_write_complete(b, w)
+    release_after_last_read(p)
+
+V2(w, d):
+    b = wait_ready(B, w, floor(w/2))
+    a = wait_ready(Alpha, w, floor(w/3))
+    if d.first:
+        u = acquire_free(U)
+        initialize(u, owner=d.g, value=b.value, next_n=d.n+1)
+    else:
+        u = wait_owned(U, d.g)
+        require(u.next_n == d.n)
+        u.value = a.value * u.value + b.value
+        u.next_n = d.n + 1
+    complete_accumulator_update(u)
+    if d.last:
+        ml = wait_owned(ML, d.g, floor(d.g/3))
+        require(ml.next_n == d.n_end)
+        finish_output(d.output_range, u.value / ml.sum)
+        release_after_last_read(ml)
+        release_after_last_read(u)
+    release_after_last_read(a)
+    release_after_last_read(b)
+```
+
+实际机制核对任务描述、代次和读写范围。首次 alpha=0 在本例按统一协议传递；采用首次项直接计算的路径时，对省略的访问及其索引规则另行展开。
+
+## 5. 边界、选择与验证
+
+- N=1：warmup 为步0，drain 为步1、2、3；每阶段恰处理工作项0一次。
+- N=2：warmup 为步0、1，drain 为步2、3、4；索引检查按有效 N 执行。
+- N≥3：warmup 三步、steady 共 `max(0,N-3)` 步、drain 三步。三步来自本例的最大阶段偏移。
+- task 的实际有效起点随描述传递；首末判断、最终 l 与 U 的归属在非零起点和短 task 下保持一致。
+- 尾部、被跳过工作项、空 task 及错误后的完成协议按实际语义补齐。
+
+用不同 KV 起点、不同 task 长度与不同值核对独立的全量 attention 参考结果。协议检查覆盖描述、阶段次数、alpha 代次、m/l 归属、U 更新顺序与最终释放。V2 先于 V1 的候选重新推导生命周期；比较资源、等待与 [阶段成本](stage-cost.md)，实际重叠和收益在后续实现验证。

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

@@ -0,0 +1,60 @@
+# 流水编排
+
+> 流水编排把 S2 定义的 stage 序列（逻辑计算流）映射为物理执行的时间排布：几级流水、不同块的 stage 如何重叠并行、跨 Cube / Vector 核如何同步握手、需要几份 buffer 支撑重叠。S2 回答「做什么、数据怎么流」，本步骤回答「几级、怎么并行、怎么同步」。
+
+**回答：几级流水？stage 顺序？同步语义？slot 与 buffer 策略？**
+
+- 候选流水排布及其阶段延迟，由关键等待、状态依赖与 buffer 余量权衡
+- 数据流 stage 顺序（同一块内的严格依赖方向 C1→V1→C2→V2）
+- **V2 vs V1 相对顺序**：逐项列 max/sum、逐工作项缩放系数和 O_acc 的读写者及最后读取。V1 先于 V2 时保留 V2 所需的旧版本；V2 先于 V1 时也核对更早工作项仍在使用的版本。执行顺序与版本隔离共同满足依赖。
+- **阶段数、阶段延迟与预取深度 r**：分别定义。C1/V1/C2/V2 有四个计算阶段；每级延迟一个推进步的示例，其最大阶段偏移为3。r 由实际预取排布决定，按所选 K/V 槽池协议代入 S3 的份数公式。
+- **按各对象生命周期推导容量**：活跃块指已进入流水且阶段尚未全部完成的工作项；每个对象的活跃版本从首次写到最后读完成计数。S、P、O_tile、Q/K/V、max/sum、缩放系数和 O_acc 各自推导份数。
+  - **流式中间结果**：按实际生产、消费偏移与先读/先写顺序确定 S、P、O_tile 的最大占用。S3 中共享 K/V 槽池及 `N_P_L1=r+1` 对应相应预取模型；采用独立 K/V 队列或其他交接偏移时，回填实际生命周期推导。
+  - **任务状态**：max/sum 从该 task 首次 V1 保留到最终使用完成；O_acc 从首次 V2 保留到末次输出读取完成。两类状态的活跃 task 数分别计算。缩放系数按工作项保留到对应 V2，另列其版本数。
+  - **容量约束**：对每个候选排布分别求 UB、L1、L0 的实际分配，包含预取副本、转换两侧、填充和所有版本；各池容量与可复用条件共同限制深度。详见 [完整示例](pipeline-example.md) 与 [阶段成本](stage-cost.md)。
+- **块内三通路重叠（L0，与 r 正交）**：L0A / L0B / L0C 恒 pingpong（N=2，结构硬约束，S3 已定死、不经本步骤回填），只受 L0 容量约束。
+- **buffer 通信策略**：中间矩阵数据量大 → 双缓冲；数据量小 / buffer 紧张 → 单缓冲（**仅指 UB / L1 上的中间矩阵 buffer，不含 L0——后者恒 pingpong**）
+- **slot 语义分离**：不同语义槽用不同计数器 / 常量，禁止共用
+
+## 软件流水的 preload / 稳态 / drain
+
+> 下面只是**非量化 GQA / MHA、3 级流水**的一种典型排布示例，preload 方式并非唯一：流水级数（2 级 / 3 级）、量化 / MLA / 稀疏变体都会改变 stage 填充序列与本表。以下仍以 3 级流水（C1 → V1 → C2 → V2，每级延迟 1 tick）为例展示。**注意：同一栏内的多个 stage（如 `C1(块2) + C2(块0)`）表示同一核在该 tick 内先后串行执行，不是并行**——Cube 核一次只跑一个 GEMM，Vector 核同理一次只跑一个 stage。
+
+| tick | Cube 核（串行）      | Vector 核（串行）    |
+| ---- | ----------------- | ------------------- |
+| 0    | C1(块0)            | —                   |
+| 1    | C1(块1)            | V1(块0)              |
+| 2    | C1(块2) + C2(块0)   | V1(块1)              |
+| 3    | C1(块3) + C2(块1)   | V2(块0) + V1(块2)     |
+| 稳态   | C1(块j) + C2(块j−2) | V2(块j−3) + V1(块j−1) |
+
+> 上表选择 V2 先于 V1，列内顺序即发射顺序；其正确性仍需逐对象证明旧版本保留到最后读取。采用 V1 更新 max/sum、V2 更新 O_acc 且缩放系数独立保留的方案时，也可选择 V1 先于 V2，完整实例见 [时序与状态示例](pipeline-example.md)。
+
+> Cube 侧 C1/C2 的准备、计算与搬出分别核对依赖；L0 pingpong 支持不同块的装载与消费重叠，交接数据和可用槽也须在发射前满足完成条件。
+
+- **preload（填充）**：按表的步0、1、2推进；首个 C2 出现在步2，首个 V2 出现在步3。
+- **稳态**：Cube 核 `c1 c2` 交替；本表 Vector 核 `v2 v1` 交替。两类核之间的重叠由实际数据可见性与资源能力支持。
+- **drain（排空）**：停止 C1 后继续剩余 V1、C2、V2，直到最后输出及槽释放完成。
+
+按 tick 展开的 stage 序列：
+
+- Cube 核：`c1, c1, c1, c2, c1, c2, c1, c2, …`（preload 后进入 c1 / c2 稳态交替）
+- Vector 核：`v1, v1, v2, v1, v2, v1, …`（对应上表；稳态每 tick 内 v2 先于 v1）
+
+产出：
+
+- 流水级数 + stage 执行顺序（含 V2 vs V1）+ 选择理由
+- 预取深度 r（代入 S3 的份数下界 `N_KV ≥ r+1`，份数数值以 S3 为准）
+- 各跨核传递段的 buffer 策略
+- 各 buffer 份数 N（所选预取模型及逐对象生命周期代入 S3 得到）
+- L0A / L0B / L0C 份数（恒 2、与 r 正交，本步骤只需声明未被降级为单缓冲）
+- 同步语义
+- 带 task/KV 工作项索引的 warmup/steady/drain 时序表与一致伪代码
+- max/sum、缩放系数、O_acc 的所有权、版本、最后读取及分别计入的物理份数
+- 共用 Cube 与 Vector 资源的累计阶段负载、短流收尾开销及选择依据
+
+检查点：
+
+- [ ] 流水 stage 顺序与数据流方向一致（无 stage 重排）
+
+禁止：把同一块内的 stage 依赖方向重排；不同语义的槽 / 状态用同一个量表达；把 L0 降级为单缓冲（换取容量或简化同步均不成立）。