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

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/conversion/patterns.md

@@ -0,0 +1,261 @@
+# Conversion 类算子模式
+
+> 本文档按 conversion 子场景逐步补充设计模式；当前已经展开的是 **small-channel transpose** 这一支。
+
+## 1. 当前适用场景
+
+当前这部分内容面向 small-channel transpose，常见特征是：
+
+- 输入输出元素总数相同，但维度顺序发生重排
+- 需求描述中出现 transpose / permute / NCHW→NHWC / `[M, N] -> [N, M]2维场景`
+- 核心代价来自数据重排，不是跨元素归约
+- 通道维较小，可先按 `C <= 16` 判断
+- 其余维度可以展平成一条长轴 `N`
+- kernel 可以按 `[C, N] -> [N, C]` 或等价形式理解, 通道维较小，可先按 `C <= 16` 判断，
+
+***
+
+## 2. 如何合轴
+
+small-channel transpose 的关键是先把问题整理成：
+
+```text
+输入:  [C, N]
+输出:  [N, C]
+```
+
+合轴时优先遵守下面两条：
+
+- 先保留被转到末维或首维的那组小通道轴，合成总通道数 `C`
+- 其余轴保持原有相对顺序，合成一条长轴 `N`
+
+常见例子：
+
+- `[3, H, W] -> [H, W, 3]` 可合成 `C = 3, N = H * W`
+- 如果有多条小轴一起参与重排，只要它们在目标布局里仍然相邻，也可以先合成一条总通道轴 `C`
+
+如果被移动的轴在目标布局中不再相邻，或者 transpose 后还混入了更复杂的 layout 变换，就不要强行套这条分支。
+
+***
+
+## 3. 路由原则
+
+### 融合场景说明
+
+本文档整体适用于 small-channel transpose 的场景判断。
+
+如果问题里除了 transpose 之外，还带有逐元素后处理或类型转换，可以考虑放到同一个 tile pipeline 中一起实现。
+
+后续章节会以 `TransDataTo5HD + Gather` 这一类实现为例，说明 small-channel transpose 的建模和 tiling 方式。
+
+### 这类融合场景下不推荐默认走的路线
+
+| 路线                 | 为什么当前不优先                           |
+| ------------------ | ---------------------------------- |
+| 通用 transpose 高级API | 在部分 small-channel 融合场景下，内部固定开销可能过大 |
+| 标量抽取再重排            | `GetValue / SetValue` 吞吐太差         |
+| 逐像素 DMA 提取         | `blockLen` 太小，DMA setup 成本占主导      |
+
+当前章节的核心是：**small-channel transpose 先做场景判断；如果目标是融合实现，再进一步参考这条分支。** 后续新增其他场景时，可以在同一文档下继续补充分支。
+
+***
+
+## 4. 统一建模方式
+
+为了让 tiling 可计算，先把问题统一成：
+
+```text
+输入:  [C, N]
+输出:  [N, C]
+```
+
+其中：
+
+- `C` 是小通道维
+- `N` 是展开后的长轴
+- 如果后续还有逐元素后处理或类型转换，把它们视为每个元素独立的后处理
+
+这个建模方式的好处：
+
+- transpose 路径只需要处理“小 C + 大 N”
+- `C` 决定 buffer 预算、offset table 和写回宽度
+- `N` 决定 tile 数、多核切分和尾块处理
+
+***
+
+## 5. Tiling 核心参数
+
+### 参数定义
+
+| 参数           | 含义                     |
+| ------------ | ---------------------- |
+| `C`          | 小通道维                   |
+| `N`          | 展平后的长轴                 |
+| `tileN`      | 每个 tile 处理的有效元素数       |
+| `tileNA`     | `tileN` 对齐后的 UB 宽度     |
+| `repeats`    | `TransDataTo5HD` 的重复次数 |
+| `totalTiles` | 总 tile 数               |
+| `blockDim`   | 实际使用的 vector core 数    |
+
+### 对齐规则
+
+```cpp
+tileNA = AlignUp(tileN, 32);
+repeats = tileNA / 16;
+```
+
+这里用 32 元素对齐，是为了同时兼顾：
+
+- FP32 输入搬运时的 32B 对齐
+- half `vnchwconv` 路径的 16-half block 组织
+- 后续 `Gather / Cast / CopyOut` 的连续处理
+
+这里的 `tileNA` 属于 host/tiling 设计口径。实际执行到尾块时，`TransDataTo5HD` 的 `repeats` 往往会按 `AlignUp(curN, 16) / 16` 计算；这是 runtime 的 tail-tile 口径，和固定 tile 宽度并不冲突。
+
+***
+
+## 6. UB 预算公式
+
+小通道 transpose 融合路径的 UB 预算可以直接写成：
+
+```text
+ubBytes = tileNA * (16 * C + 32)
+```
+
+拆解如下：
+
+- `2 * C * tileNA * sizeof(float)`：`VECIN` 双缓冲
+- `2 * C * tileNA * sizeof(uint8)`：`VECOUT` 双缓冲
+- `C * tileNA * sizeof(half)`：half 中间 buffer
+- `16 * tileNA * sizeof(half)`：`vnchwconv` 输出 buffer
+- `C * tileNA * sizeof(uint32_t)`：offset table buffer
+
+在 `C = 3` 时可化成：
+
+```text
+ubBytes = tileNA * 80
+```
+
+### repeat 上限
+
+`TransDataTo5HD` 的 `repeats` 不能超过 255，因此：
+
+```cpp
+repeats = tileNA / 16 <= 255
+tileNA <= 4080
+```
+
+最终 `tileN` 必须同时满足：
+
+- UB 容量约束
+- `repeats <= 255`
+- 向量对齐约束
+
+***
+
+## 7. tile 大小计算方法
+
+```cpp
+uint32_t ubBudget = ubSize - reservedBytes;
+uint32_t perElemBytes = 16 * C + 32;
+uint32_t tileNMax = AlignDown(ubBudget / perElemBytes, 32);
+tileNMax = Min(tileNMax, 255 * 16);  // 同时满足 UB 和 repeats 上限
+
+uint32_t tileN = AlignUp(CeilDiv(N, blockDim), 32);  // 先按目标核数均分
+if (tileN > tileNMax) {
+    uint32_t minTiles = CeilDiv(N, tileNMax);
+    uint32_t alignedTiles = CeilDiv(minTiles, blockDim) * blockDim;  // 让总 tile 数更接近 blockDim 的整数倍
+    tileN = AlignUp(CeilDiv(N, alignedTiles), 32);
+}
+```
+
+这一步的目标不是“把 tile 做到越大越好”，而是：
+
+- 单 tile 尽量大，减少调度开销
+- 但总 tile 数又足够多，能够铺满所有核
+
+***
+
+## 8. 多核切分策略
+
+### 原则
+
+- `blockDim = min(可用 vector core 数, totalTiles)`
+- `totalTiles = CeilDiv(N, tileN)`
+- 尽量让 `totalTiles` 接近 `blockDim` 的整数倍
+
+### 推荐分配方式
+
+```cpp
+blockDim = Min(coreNum, totalTiles);
+tilesPerCore = CeilDiv(totalTiles, blockDim);
+startTile = blockIdx * tilesPerCore;
+endTile = Min(startTile + tilesPerCore, totalTiles);
+```
+
+这样做的目的：
+
+- 尽可能让可用的 vector core 都有活干
+- 避免前面很多核只做 1 个 tile、最后一个核扛大尾巴
+- 保持 CopyIn / Compute / CopyOut 的流水节奏稳定
+
+如果 `N` 较小，导致 `totalTiles < coreNum`，则实际只开 `totalTiles` 个核，不做空核占位。
+
+***
+
+## 9. offset table 设计
+
+`Gather` 需要的offset 在device 侧提前生成，考虑性能使用Tbuff，全局管理只需要申请一次即可。
+
+### 公式
+
+```cpp
+for (uint32_t p = 0; p < tileNA; ++p) {
+    for (uint32_t c = 0; c < C; ++c) {
+        offsetBuff.SetValue(p * C + c, (p * 16 + c) * sizeof(half));
+    }
+}
+```
+
+### 设计要点
+
+- offset 表按 **对齐后的** **`tileNA`** 构建，而不是按 `tileN`
+- 每个 16-half block 只前 `C` 个位置有效
+- 这张表可以在 kernel 初始化阶段一次 DMA 到 UB，后续 tile 复用
+
+如果 `C` 变化，offset table 也必须跟着重建；不要把它硬编码成某一个具体通道数的常量表。
+
+***
+
+## 10. Kernel 侧执行骨架
+
+```cpp
+for (uint32_t t = startTile; t < endTile; ++t) {
+    CopyIn(t);   // GM -> UB, 按通道连续搬运
+    Compute(t);  // elementwise -> round -> half -> vnchwconv -> gather
+    CopyOut(t);  // UB -> GM, 写回 [tileN, C]
+}
+```
+
+关键点：
+
+- `CopyIn` 不是逐像素 gather，而是按通道连续搬运 `[C, tileN]`
+- `Compute` 用 `tileNA` 组织 UB；尾块依靠对齐和有效 count 控制
+- `CopyOut` 按 `curN * C` 字节写回，非对齐场景优先 `DataCopyPad`
+
+***
+
+## 11. 转置类算子设计检查表
+
+设计 transpose 类 kernel 时，至少检查下面 10 项：
+
+- 是否已经把问题统一建模为 `[C, N] -> [N, C]`
+- 如需融合实现，当前问题是否命中本文已展开的实现分支
+- `tileN` 是否按 32 对齐
+- `tileNA / 16` 是否满足 `repeats <= 255`
+- UB 预算是否使用了 `tileNA * (16 * C + 32)` 公式
+- `totalTiles` 是否足够铺满核
+- `blockDim` 是否受 `totalTiles` 限制
+- offset table 是否按 `tileNA` 构建
+- 是否为尾块保留了 `curN` 和 `tileNA` 的区分
+- 是否把 transpose 和后处理融合在同一个 tile pipeline 中

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/elewise/patterns.md

@@ -0,0 +1,46 @@
+# EleWise 类算子场景路由
+
+> 本文档用于**场景判定**和**策略选择**。确定场景后，按链接进入对应详细文档。
+
+---
+
+## 场景判定流程
+
+EleWise（Elementwise）：输入输出 Shape 相同，逐元素独立计算，无跨元素依赖。不区分一元/二元，Sin、Cos、Abs、Add、Mul 等均可。
+
+```
+给定: N 个输入 shape + M 个输出 shape
+
+Step 1 — Shape 判定:
+  所有输入输出 shape 完全相同？
+    ├─ YES → EleWise，展平为 dim0，1D 线性处理 → 进入 Step 2
+    └─ NO  → Broadcast → [../broadcast/patterns.md]
+
+Step 2 — dtype × 运算 判定（决定 Compute 路径）:
+  运算为 Add/Sub / 以加减为主的累加链路 AND dtype ∈ {FP16, BF16} AND spec 未声明"输入同量级"？
+    ├─ YES → 升精度分支：Cast→FP32 计算→Cast，需额外 K 份 FP32 中间 Buffer
+    └─ NO  → 原 dtype 直接计算分支
+  两分支的 UB 预算与 ubFormer 公式见 [tiling.md](tiling.md)
+  （乘法/除法等其他场景暂未覆盖，沿用原 dtype 直算分支）
+```
+
+**Step 2 策略说明**：半精度"大数吃小数"问题需要升精度规避，K 值与 Cast 写法等属 API 实现细节。tiling-design 负责宏观切块（分支判定、UB 预算、ubFormer），API 实现细节由 Compute 阶段落地时确定。
+
+---
+
+## 通用规则
+
+- **多核对齐**：元素数对齐到 512 的倍数（ELEM_ALIGN_FACTOR），每个核至少 4KB 数据
+- **UB 对齐**：按 256B 对齐，确保 Vector 指令效率
+- **区分首/尾 block**：尾 block 数据量可能小于首 block，循环次数和 tail 大小不同
+
+常量定义和计算公式详见 [tiling.md](tiling.md)。
+
+---
+
+## 跨场景参考
+
+| 主题 | 文档 |
+|------|------|
+| EleWise Tiling 详细计算（常量、公式、模板、dtype 分支 UB 预算） | [tiling.md](tiling.md) |
+| Broadcast 场景路由（输入 Shape 不同时） | [../broadcast/patterns.md](../broadcast/patterns.md) |

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/elewise/tiling.md

@@ -0,0 +1,215 @@
+# EleWise - Tiling 详细计算
+
+> **适用场景**: 输入输出 Shape 完全相同，逐元素独立计算
+
+---
+
+## 一、多核切分（blockFormer / blockNum）
+
+### 核心思想
+
+确保每个核处理的数据量 >= 最小阈值，并按 512 字节对齐。
+
+### Tiling 参数说明
+
+| 参数 | 含义 | 计算公式 |
+|------|------|---------|
+| `dim0` | 元素总数量 | 所有维度相乘 |
+| `coreNum` | 实际使用的核数 | `min(计算核数, 最大核数)` |
+| `blockFormer` | 每个核的基础元素数（对齐到 512 元素） | `((dim0 / coreNum) + 511) / 512 * 512` |
+| `blockNum` | 虚拟 block 数量 | `(dim0 + blockFormer - 1) / blockFormer` |
+
+### 计算步骤
+
+```cpp
+// Step 1: 计算核数（保证每个核至少处理 4KB 数据）
+// 注意：MIN_TILING_BITS_SIZE_PER_CORE 和 minDtypeBits 单位都是 bits
+coreNum = (dim0 * minDtypeBits + MIN_TILING_BITS_SIZE_PER_CORE - 1) / 
+           MIN_TILING_BITS_SIZE_PER_CORE;
+coreNum = min(coreNum, availableCoreNum);
+
+// Step 2: 每个核的基础元素数，对齐到 512 元素
+blockFormer = ((dim0 + coreNum - 1) / coreNum + ELEM_ALIGN_FACTOR - 1) / 
+               ELEM_ALIGN_FACTOR * ELEM_ALIGN_FACTOR;
+
+// Step 3: 计算虚拟 block 数量
+blockNum = (dim0 + blockFormer - 1) / blockFormer;
+```
+
+### 核间数据偏移
+
+```cpp
+template <typename DataType>
+__aicore__ inline int64_t CalcBlockOffset() {
+    return blockFormer * GetBlockIdx() * sizeof(DataType);
+}
+```
+
+---
+
+## 二、UB 切分（ubFormer / ubLoop / tail）
+
+### 核心思想
+
+确保 UB 处理量是 256B 的整数倍（Vector 指令最优）。
+
+### Tiling 参数说明
+
+| 参数 | 含义 | 计算公式 |
+|------|------|---------|
+| `ubFormer` | 每个 UB 块的基础大小（256B 对齐） | 对齐到 256B |
+| `ubLoopOfFormerBlock` | 首块的 UB 循环次数 | `(blockFormer + ubFormer - 1) / ubFormer` |
+| `ubTailOfFormerBlock` | 首块的尾部大小 | `blockFormer - (ubLoopOfFormerBlock - 1) * ubFormer` |
+| `ubLoopOfTailBlock` | 尾块的 UB 循环次数 | `(blockTail + ubFormer - 1) / ubFormer` |
+| `ubTailOfTailBlock` | 尾块的尾部大小 | `blockTail - (ubLoopOfTailBlock - 1) * ubFormer` |
+
+### 计算步骤
+
+```cpp
+// Step 1: 计算 UB 能容纳的最大元素数
+bufferDivisor = bufferNum * elemBytes;
+maxElemNum = (ubSize - extraSize) * 8 / bufferDivisor;
+
+// Step 2: 按 256B 对齐
+alignFactor = REPEAT_BYTES * 8 / minDtypeBits;  // 如 FP32 = 64 元素
+ubFormer = (maxElemNum / alignFactor) * alignFactor;
+
+// Step 3: 计算循环次数
+ubLoopOfFormerBlock = (blockFormer + ubFormer - 1) / ubFormer;
+ubTailOfFormerBlock = blockFormer - (ubLoopOfFormerBlock - 1) * ubFormer;
+```
+
+---
+
+## 三、Kernel 执行模型
+
+### Process 循环结构
+
+**核心逻辑**：区分首 block 和尾 block，因为它们的 UB 循环次数可能不同。
+
+```cpp
+// 1. 判断当前处理的是否是最后一个 block
+bool isLastBlock = (blockIdx == blockNum - 1);
+
+// 2. 获取当前 block 的循环次数和尾部大小
+//    首 block 和尾 block 的循环次数/尾部大小可能不同
+loopNum = isLastBlock ? ubLoopOfTailBlock : ubLoopOfFormerBlock;
+tailNum = isLastBlock ? ubTailOfTailBlock : ubTailOfFormerBlock;
+
+// 3. 主循环（处理完整的 UB 块）
+for (uint64_t i = 0; i < loopNum - 1; i++) {
+    ProcessTile(offset, ubFormer);
+    offset += ubFormer;
+}
+
+// 4. 尾部处理（处理最后一个不完整的 UB 块）
+ProcessTile(offset, tailNum);
+```
+
+**为什么要区分首/尾 block？**
+
+- `blockFormer` 是按 512B 对齐的，可能略大于平均分配
+- 最后一个 block 分配的原始数据量 `blockTail` 可能小于 `blockFormer`
+- 导致 `ubLoopOfFormerBlock` ≠ `ubLoopOfTailBlock`，`ubTailOfFormerBlock` ≠ `ubTailOfTailBlock`
+
+---
+
+## 四、最小可执行 Tiling 模板
+
+```cpp
+struct TilingData {
+    int64_t dim0;           // 元素总数量
+    int32_t coreNum;        // 实际核数
+    int64_t blockFormer;    // 每个核的基础数据量
+    int64_t blockNum;       // block 数量
+    int64_t ubFormer;       // UB 基础大小
+    int64_t ubLoopOfFormerBlock;
+    int64_t ubTailOfFormerBlock;
+    int64_t ubLoopOfTailBlock;
+    int64_t ubTailOfTailBlock;
+};
+
+TilingData ComputeTiling(int64_t dim0, int64_t elemBytes, int64_t ubSize, 
+                         int64_t bufferNum, int64_t availableCoreNum) {
+    TilingData tiling;
+    
+    // 常量
+    constexpr int64_t MIN_TILING_BITS = 32768;       // 4KB，单位 bits
+    constexpr int64_t ELEM_ALIGN_FACTOR = 512;       // 多核切分元素对齐因子
+    constexpr int64_t ALIGN_256 = 256;               // UB 对齐字节数
+    
+    // 1. 多核切分（minDtypeBits = elemBytes * 8）
+    tiling.coreNum = (dim0 * minDtypeBits + MIN_TILING_BITS - 1) / MIN_TILING_BITS;
+    tiling.coreNum = std::min(tiling.coreNum, availableCoreNum);
+    
+    tiling.blockFormer = ((dim0 + tiling.coreNum - 1) / tiling.coreNum + ELEM_ALIGN_FACTOR - 1) / ELEM_ALIGN_FACTOR * ELEM_ALIGN_FACTOR;
+    tiling.blockNum = (dim0 + tiling.blockFormer - 1) / tiling.blockFormer;
+    
+    // 2. UB 切分
+    int64_t bufferDivisor = bufferNum * elemBytes;
+    int64_t maxElemNum = (ubSize * 8) / bufferDivisor;
+    int64_t alignFactor = ALIGN_256 * 8 / elemBytes;
+    tiling.ubFormer = (maxElemNum / alignFactor) * alignFactor;
+    
+    // 3. 循环次数
+    tiling.ubLoopOfFormerBlock = (tiling.blockFormer + tiling.ubFormer - 1) / tiling.ubFormer;
+    tiling.ubTailOfFormerBlock = tiling.blockFormer - (tiling.ubLoopOfFormerBlock - 1) * tiling.ubFormer;
+    
+    int64_t blockTail = dim0 - (tiling.blockNum - 1) * tiling.blockFormer;
+    tiling.ubLoopOfTailBlock = (blockTail + tiling.ubFormer - 1) / tiling.ubFormer;
+    tiling.ubTailOfTailBlock = blockTail - (tiling.ubLoopOfTailBlock - 1) * tiling.ubFormer;
+    
+    tiling.dim0 = dim0;
+    return tiling;
+}
+```
+
+---
+
+## 五、经验总结
+
+| 经验 | 说明 | 代码模式 |
+|------|------|----------|
+| **最小粒度** | 每个核至少 4KB 数据，否则不值得开核 | `MIN_TILING_BITS = 32768` |
+| **多核对齐** | 元素数对齐到 512 的倍数 | `blockFormer = (原始值 + 511) / 512 * 512` |
+| **UB 对齐** | 按 256B 对齐，确保 Vector 指令效率 | `ubFormer = (原始值 / alignFactor) * alignFactor`，其中 alignFactor = 256 / elemBytes（如 FP32=4字节 则 alignFactor=64） |
+| **跨核偏移** | 当前核 GM 偏移 = `blockFormer * blockIdx` | `CalcBlockOffset()` |
+
+---
+
+## 六、dtype 分支：FP16/BF16 升精度（Add/Sub）的 UB 预算
+
+**何时启用**：patterns.md 的 Step 2 判定命中升精度分支时使用。
+
+### 1. Buffer 规划差异
+
+升精度分支在原 dtype Queue 之外，额外引入 **K 份 `ubFormer * sizeof(float)` 的 FP32 中间 Buffer**。K 由 API 层的别名约束决定，tiling 阶段只需将其作为参数代入 UB 预算。
+
+| 项 | 原 dtype 直算 | 升精度分支 |
+|---|--------------|-----------|
+| 输入/输出 Buffer dtype | 原 dtype（half/bf16） | 原 dtype（不变） |
+| FP32 中间 Buffer 份数 | — | **K**（由 API 别名约束给出） |
+| 单份 FP32 中间大小 | — | `ubFormer * sizeof(float)` |
+| 总 UB 占用 | `bufferNum * ubFormer * elemBytes` | `bufferNum * ubFormer * elemBytes + K * ubFormer * sizeof(float)` |
+
+### 2. ubFormer 计算调整
+
+升精度分支下 `bufferDivisor` 需同时包含半精度 Queue 和 FP32 中间 Buffer 两部分：
+
+```cpp
+// 原直算分支
+bufferDivisor = bufferNum * elemBytes;
+
+// 升精度分支：bufferNum 份半精度 + K 份 FP32
+bufferDivisor = bufferNum * elemBytes + K * sizeof(float);
+
+maxElemNum = (ubSize * 8) / bufferDivisor;
+alignFactor = ALIGN_256 * 8 / elemBytes;       // 对齐仍按输入 dtype
+ubFormer = (maxElemNum / alignFactor) * alignFactor;
+```
+
+K 的取值取决于 Compute 阶段选用 API 是否支持 dst/src 别名，该参数由 API 实现细节给出后回填。
+
+> 升精度分支不新增 TilingData 字段，Kernel 侧按 dtype 模板参数静态选择分支即可。具体 Cast/Add/Sub 调用、RoundMode、别名写法等属 API 实现细节，tiling 阶段不涉及。
+
+---

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/flashattention/design/_governance.md

@@ -0,0 +1,132 @@
+# 设计治理(节点 G)
+
+> **节点 G — 设计治理**:产出清单 + 设计即最优门禁 + 计算顺序/依赖链 + 结构决策定位。
+> 依赖前置:—(全流程起点)。下游:所有 N0-N12 节点在此门禁与依赖链约束下展开。
+> 本文档列出 FA 类算子设计阶段**必须回答的问题**(WHAT)与**必须定死的结构性决策**(HOW WELL)。二者在每个节点**合一**——离开设计即最优(§2 门禁),故不再分"先对后快"两阶段。
+> **变体特定扩展**:每个节点在对应 `subfamilies/` 文件中有"该变体如何特化"的章节,加载条件见 [`patterns.md` §4](../patterns.md)。
+
+---
+
+## §1 设计阶段必须产出清单
+
+进入实现之前,DESIGN 文档(或同等位置)必须显式产出以下条目。每条对应一个设计节点。
+
+| # | 产出 | 对应节点 |
+|---|---|---|
+| 1 | 选型确认(承接 fundamentals)| **N0**(进入 N1 前)|
+| 2 | 宏观决策(架构选型 4 项 + 并行策略选择 + V1/V2 softmax 算法模式 + 平台依赖识别)| **N1**(宏观)+ **N2**(并行)+ **N4**(softmax)+ **N5**(平台依赖)|
+| 2.5 | 基本块与 Roofline 分析(Bq/Bk 选定 + AI + 性能区域)| **N3**(承接 N2 并行策略之后)|
+| 3 | 多核切分方案(任务维度构造 / 不变量校核 / 核数获取 / 负载均衡)| **N6** |
+| 4 | 内存划分(UB / L1 / L0 / GM workspace 各自的 buffer 清单与公式)| **N7** |
+| 5 | 编译宏分类(条件性功能识别 + 编译宏 vs 运行期 if 判定)| **N8** |
+| 6 | Host Tiling 决策结果(输入、输出字段、决策维度、维度打开纪律)| **N9** |
+| 7 | 流水线编排(节拍数 / 同步事件 / slot 命名 / slot 公式分离 / PipeBarrier 契约 / Fixpipe 参数)| **N10** |
+| 8 | 开发起点(模块化构建与验证)| **N11** |
+| 9 | 校验门禁规划(atol 来源指向 `/ops-precision-standard`,本阶段不重复)| 见 [`fundamentals.md` §4.4](../foundation/fundamentals.md)|
+| 10 | 优化策略(流水编排 / 跨核同步 / 负载均衡 / 编译期特化 / 变体特定)| **N12**(结构决策定位见本文 §4)|
+
+任一条目未产出 → 阻塞,不得进入实现。
+
+## §2 设计即最优(强制门禁)
+
+离开设计阶段的方案必须是**目标平台上的最优性能方案**,不是"先跑通、后优化"的退化基线。各节点中一切承诺值(`mEff` / `curG` / 流水级数 + double buffer / `PipeBarrier<PIPE_ALL>` 数量 / Cube 分块 K_BASE / split-KV 启用)必须取 **N3 Roofline** + 容量约束推导出的最优点。任何低于最优点的取值(如 `mEff=1`、`curG=1`、关闭 double buffer、逐 KV 块 `PipeBarrier<PIPE_ALL>`、K_BASE 取值偏小)**只有当它是硬件约束被迫退化时才允许**,且必须在对应节点写明"绑定约束 = 哪条容量 / 平台限制"。**禁止**以"首版求正确""性能留待 S5 / 后续迭代""基线先行"为由把退化配置作为设计目标——那是实现推进顺序(见 N9 维度打开纪律,resources §2),不是设计目标。
+
+> **门禁一致性**:本门禁与 [`base_design.md` §10.2 清单 10](../subfamilies/base_design.md) 绑定——该清单明确要求设计阶段就取 Roofline 最优 mEff/K_BASE、必须用 double buffer / 软流水、**禁止 "S5 / 后续迭代" 式性能推迟**。故 §4 的结构性决策是**设计义务**,不是可选优化。
+
+## §3 计算顺序 + 设计依赖链
+
+**计算顺序**:按节点序依次完成。DESIGN.md 模板节号与节点号不同,但基本块参数(mEff / Bk / V1 模式)必须来自 **N3** 的 Roofline 推导,不可在 N3 完成前凭经验选取。后续节点(N6 多核、N7 内存)的数值处标注"见 N3 推导"。
+
+**设计依赖链**(自顶向下,无前向依赖):
+
+```
+N1 架构选型(kernel/UB/cube/流水级数)
+    ↓
+N2 并行策略(默认 / split-KV)
+    ↓
+N3 基本块与 Roofline 分析 → 产出 mEff, Bk, V1 模式
+    ├─→ N4 V1/V2 Online Softmax 算法模式(消费 N3 基本块结论定 V1 模式)
+    ├─→ N5 平台依赖识别(macro 早置,标记供 N8/N10 消费)
+    ↓
+N6 多核切分(基于 N3 的 mEff/Bk 计算 totalTasks)
+    ↓
+N7 内存划分(buffer 大小引用 N3 的 mEff/Bk)
+    ↓
+N8 编译宏(在 N7 内存划分下,判定依据 = TBuf 变化)
+    ↓
+N9 Host Tiling 决策(把 N1-N8 所有决策汇总成 Tiling 函数产出)
+    ↓
+N10 流水线编排(基于 N1 §1.4 + N6 + N7 的节拍 / 同步 / barrier 一体)
+    ↓
+N11 开发起点(进入实现的最后准备)
+    ↓
+N12 优化策略产出(在 N1-N11 骨架上汇总优化策略产出 DESIGN.md)
+```
+
+> **依赖链核对**:N2(并行)先于 N3(Roofline);N4(softmax)依赖 N3(消费 N3 基本块结论定 V1 模式);N5(平台依赖)依赖 N3(平台约束早置,标记供后续 N8/N10 消费,非收尾)。
+
+---
+
+## §4 结构决策定位
+
+> ⚠️ **定位:这是设计期必须定死的结构性决策,不是实现后的 profiling pass。** §1-§3 的产出与依赖链决定 **code skeleton**(流水 stage 顺序 / slot 隔离 / 同步原语 / 编译期分流),一旦缺席设计就无法靠后续 workflow 补救,只能整段重写。真正可后置的只有基于 working baseline 的**数值标定**(标注为"默认值 + 可 profiling 微调")与**实测验证**(属性能验收阶段)。
+
+### §4.1 WHAT 与 HOW WELL 合一
+
+骨架相同、实现策略不同的 FA 算子,性能可以差数倍。因此结构性决策(**流水编排 / 跨核同步 / 负载均衡 / 编译期特化**)与正确性契约在**同一节点内合一确定**,让实现从一开始就知道"怎么做才对且做好"。凡涉及正确性契约(不变量 / 容量校验 / 同步时序),在对应节点(N6/N7/N8/N10)一次定死,不分阶段。
+
+### §4.2 结构决策五层模型
+
+结构性决策按五层组织,**决策顺序从上到下**——上层决策错误无法靠下层优化弥补:
+
+```
+流水层  →  决定 Cube/Vector 如何交错工作          (N10,execution §3.1)
+  ↓
+同步层  →  决定跨核通信如何执行                    (N10,execution §3.2)
+  ↓
+负载层  →  决定任务如何在核间均衡                  (N6,shape §5.5)
+  ↓
+内存层  →  决定数据在 L1/UB/L0/GM 如何分布         (N7,resources §1)
+  ↓
+计算层  →  决定计算指令与编译期特化如何编排        (N8,execution §2)
+```
+
+### §4.3 各层决策的验证方法
+
+验证分两类,**归属不同工作流**:
+
+**(a) 设计期可校核**(自检清单 O1-O16 覆盖,随各节点迁移,无需跑起来):
+
+| 层 | 设计期校核手段 | 关键指标 | 清单 |
+|----|---------|---------|---|
+| 负载层(N6)| 典型 shape 核数利用率估算 | 空闲核有处理策略 | O8-O9 |
+| 内存层(N7)| 代码验算 buffer 容量 | UB 总占用 ≤ 查询容量 | O10-O12 |
+| 流水层(N10)| — | — | O1-O3 |
+| 同步层(N10)| — | — | O4-O7 |
+| 计算层(N8)| — | — | O13-O16 |
+
+**(b) 实测验证**(需 working baseline,**属性能验收工作流,不在设计期做**;对应 PLAN.md §7 性能验收阶段):
+
+| 层 | 实测手段 | 关键指标 |
+|----|---------|---------|
+| 流水层 | msprof op 采集 PipeUtilization | Cube/Vector 利用率差距 < 20% |
+| 同步层 | 代码统计 PipeBarrier 数量 | 冗余率 < 30% |
+| 计算层 | 反汇编检查 | constexpr 分支已消除 |
+
+> (b) 类指标是**验收门槛**,不是设计输入。设计期只需保证结构性决策(流水级数 / 同步原语 / 编译期分流)已定死且理由充分;实测数值达标由性能验收阶段判定。
+
+### §4.4 基本块对结构决策的约束
+
+基本块大小(**N3** 确定)从三个维度约束结构决策的选择空间:
+
+| 影响维度 | 机制 | 对应节点 |
+|---------|------|---------|
+| 流水级数 | 基本块大 → tile FLOPs 大 → 2 级流水可能已足够;基本块小 → 需更深流水 | N10 |
+| Buffer 开销 | 基本块 UB 占用 × 流水槽数 ≤ UB 容量 → 约束流水深度上限 | N10 / N7 |
+| 同步开销 | 基本块小 → tile 数多 → 跨核同步次数多 | N10 |
+
+**交叉验证**:应验证 N3 选定的基本块与 N10(流水/同步)的策略选择一致。
+
+### §4.5 产出规范
+
+每个结构决策维度必须给出:**选定方案 + 决策理由**。**禁止**只写"使用 N 级流水"而不写 stage 顺序、ring buffer 深度、同步粒度等编排细节。