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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/shape-preprocessing.md

@@ -0,0 +1,209 @@
+# Broadcast 范式 shape 归一化（补 1 / 去 1 / 归一 / 合轴）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/tiling-preprocess.md §2/§3（原 broadcast-standard-tiling-preprocess.md）。C++ 参考实现（PadAndSqueeze / BroadcastMergeAxis / CheckBroadcastShape）与错误上报接口在适配层。
+
+## 1 目标与产出
+
+输入预处理是每个 Broadcast 算子都要做的通用步骤。目标：将不同 shape 的入参和出参归一化，拉到同一个参照系 `maximumBroShape` 下。
+
+预处理产出三类 shape：
+
+- `maximumBroShape` — 坐标系，所有输入/输出的 broadcast 上界
+- `normalInputShapes` — 归一化后各输入 shape，与 maximumBroShape 同 rank
+- `normalOutputShapes` — 归一化后各输出 shape，与 maximumBroShape 同 rank，输出可能比坐标系小
+
+## 2 四步算法
+
+> **顺序：补 1 → 去 1 → 归一 → 合轴，顺序不可换**
+
+1. **补 1**：低 rank 入参/输出在 shape **最前面**补 1，拉齐到 maxRank（含入参+出参）。只能在 shape 最前面补 1，不允许在中间或末尾维度补 1
+2. **去 1**：对齐后，所有入参+出参在某轴都是 1 → squeeze 掉，消除废维度
+3. **归一**：去 1 后若 maximumBroShape 为空（全部均为标量），填 `(1,)`
+4. **合轴**：归一后从最后一维向前贪心合并相邻维。对候选组 [d..groupHighDim]（闭区间），每个入参/出参在组内的维度乘积必须为 **1**（整组广播）或等于**坐标系 maximumBroShape 在组内的乘积**（整组稠密）；组内部分维为 1、部分维稠密的混合模式不能合并。扩展失败时封闭当前组，从当前维重新开组
+
+**合轴的判定本质**：组内每个张量的乘积只有两种合法取值——`1`（该张量整组都是 1，合并后整维广播，stride=0）或 `坐标系组乘积`（该张量整组无 1，合并后整维稠密连续）。组内混有 1 和非 1（如某张量组内乘积为 `3×1×1=3`）说明广播边界落在组内部，合并后会破坏元素映射，必须拒绝。
+
+**合轴的收益**：rank 与循环维数下降、内层连续段变长——单次搬运量从"最内维 × 少数几维"提升为"整组连续元素"，且 rank 超过搬运维数上限（`TRANSFER_MAX_DIMS`）时，split 轴更容易进入搬运单元的维数窗口，避免退化成逐次碎片化搬运。
+
+**broadcast 兼容校验**：补 1 后逐维检查——对每个维度，若某入参/输出在该维的大小不为 1 且与其他入参/输出同维不为 1 的大小不同，则**报错并返回失败**。校验失败直接返回，不进入合轴——合轴必须在兼容校验通过之后执行（合轴的乘积判等依赖"每维取值 ∈ {1, 该维最大值}"这一前提）。
+
+## 3 示例
+
+例 1（正常广播，补 1 个 1）：
+```
+入参 A: shape = (4, 8)
+入参 B: shape = (1, 8)
+入参 C: shape = (8,)       // 补 1 → (1,8)
+
+补 1 → A=(4,8), B=(1,8), C=(1,8)
+去 1 → dim0: A=4, B=1, C=1 → 不全为 1，保留
+        dim1: A=8, B=8, C=8 → 全为 8≠1，保留
+maximumBroShape = (4, 8)
+校验 → dim0: 4,1,1 → ref=4 ✓
+        dim1: 8,8,8 → ref=8 ✓
+
+合轴（从最后一维 dim1 开始，向左尝试扩展）：
+  尝试 [dim0,dim1]: A=4×8=32, B=1×8=8, C=1×8=8, 坐标系组乘积 = 32
+                     → B/C 的 8 既非 1 也非 32 ✗ → 封闭组 (8)，从 dim0 开新组
+  尝试 [dim0]: 单维成组
+
+合轴后: maximumBroShape = (4, 8)   — 无可合并，保持不变
+        normal_A = (4, 8)
+        normal_B = (1, 8)
+        normal_C = (1, 8)
+```
+
+例 2（正常广播，补多个 1）：
+```
+入参 A: shape = (2, 4, 8)
+入参 B: shape = (8,)       // 补 1 → (1,1,8)
+
+补 1 → A=(2,4,8), B=(1,1,8)
+去 1 → dim0: A=2, B=1 → 不全为 1，保留
+        dim1: A=4, B=1 → 不全为 1，保留
+        dim2: A=8, B=8 → 全为 8≠1，保留
+maximumBroShape = (2, 4, 8)
+校验 → dim0: 2,1 → ref=2 ✓
+        dim1: 4,1 → ref=4 ✓
+        dim2: 8,8 → ref=8 ✓
+
+合轴（从最后一维 dim2 开始，向左尝试扩展）：
+  尝试 [dim1,dim2]: A=4×8=32, B=1×8=8, 坐标系组乘积 = 32
+                     → B 的 8 既非 1 也非 32 ✗ → 封闭组 (8)，从 dim1 开新组
+  尝试 [dim0,dim1]: A=2×4=8, B=1×1=1, 坐标系组乘积 = 8
+                     → A 稠密(8=maxProd)、B 整组广播(1) ✓ → 合并，当前组 = (8)
+
+合轴后: maximumBroShape = (8, 8)
+        normal_A = (8, 8)   — 原 dim0,dim2 合并为单维 8
+        normal_B = (1, 8)   — 原前两维整组广播，合并后该维为 1
+```
+
+例 3（broadcast 不兼容报错）：
+```
+入参 A: shape = (4, 8)
+入参 B: shape = (4, 3)
+
+补 1 → A=(4,8), B=(4,3)     // 同 rank，无需补 1
+去 1 → dim0: 4,4 → 不全为 1，保留
+        dim1: 8,3 → 不全为 1，保留
+maximumBroShape = (4, 8)
+校验 → dim0: 4,4 → ref=4 ✓
+        dim1: 8,3 → 两者均非 1 且 8≠3 → 报错！
+→ 报错内容：dim 1、input[1] size 3 与 ref 8、broadcast incompatible: input sizes must be equal or 1
+→ return false
+（校验失败直接返回，不进入合轴）
+```
+
+例 4（标量）：
+```
+入参 A: shape = ()
+入参 B: shape = ()
+
+补 1 → A=(), B=()     // rank=0，无轴可补
+去 1 → maximumBroShape = ()
+归一 → maximumBroShape = (1,)
+normal_A = (1,)
+normal_B = (1,)
+校验 → dim0: 1,1 → 全为 1 ✓
+合轴 → rank=1，单维无可合并，保持 (1,)
+```
+
+例 5（合轴，从最后一维向前贪心合并）：
+```
+入参 A: shape = (2, 3, 4, 5)
+入参 B: shape = (2, 3, 1, 1)
+输出 C: shape = (2, 3, 4, 5)
+
+补 1 → rank 已对齐，无需补 1
+去 1 → 每维均非全 1，无废维
+坐标系 maximumBroShape = (2, 3, 4, 5)
+
+合轴（从最后一维 dim3 开始，向左尝试扩展）：
+  尝试 [dim2,dim3]: A=4×5=20, B=1×1=1, C=4×5=20
+                     → 乘积均为 20 或 1 ✓ → 合并，当前组 = (20)
+  尝试 [dim1,dim2,dim3]: A=3×20=60, B=3×1=3, C=3×20=60
+                     → 3 既非 1 也非 60 ✗ → 封闭组 (20)，从 dim1 开新组
+  尝试 [dim0,dim1]: A=2×3=6, B=2×3=6, C=2×3=6
+                     → 乘积全等 ✓ → 合并，当前组 = (6)
+
+合轴后: maximumBroShape = (6, 20)
+        normal_A = (6, 20)
+        normal_B = (6, 1)     // 整组广播 → 合并后该维为 1
+        normal_C = (6, 20)
+校验 → dim0: 6,6,6 → ref=6 ✓
+        dim1: 20,1,20 → ref=20 ✓
+```
+
+## 4 产出校验 golden
+
+**对范式开发者的要求**：
+1. 给一个复杂输入的样例，以合轴后的结果作为 golden，需要"人"保证正确性
+2. 删除 golden，agent 读取本文档可以产出同样的合轴后的输出；产出不了则不断改进范式质量，直到成功
+3. 样例随本文档上库
+
+**golden 样例（Adam: 5 输入 3 输出, 输入 shape 全部一致）**：
+
+```
+输入:
+  IN0 (input0):           (256, 128, 64)
+  IN1 (input1):           (256, 128, 64)
+  IN2 (input2):           (256, 128, 64)
+  IN3 (input3):           (256, 128, 64)
+  IN4 (input4):           (256, 128, 64)
+  mul0_x/mul1_x/mul2_x/mul3_x/add2_y: (256, 128, 64)
+输出:
+  OUT0 (out0):            (256, 128, 64)
+  OUT1 (out1):            (256, 128, 64)
+  OUT2 (out2):            (256, 128, 64)
+
+补 1 → 所有 tensor rank=3，无需补 1
+去 1 → dim0: 256（非 1，保留）; dim1: 128（非 1，保留）; dim2: 64（非 1，保留）
+归一 → 坐标系 maximumBroShape = (256, 128, 64)
+校验 → 所有维度一致 ✓
+
+合轴（从最后一维 dim2 开始，向左尝试扩展）：
+  尝试 [dim1,dim2]: 各张量 = 128×64 = 8192，坐标系组乘积 = 8192
+                     → 乘积均为 8192 = maxProd ✓ → 合并，当前组 = (8192)
+  尝试 [dim0,dim1,dim2]: 各张量 = 256×8192 = 2097152，坐标系组乘积 = 2097152
+                     → 乘积均为 2097152 = maxProd ✓ → 合并，当前组 = (2097152)
+
+合轴后: maximumBroShape = (2097152,)
+        normalInputShapes[0..9]  = (2097152,)  — 全部稠密连续
+        normalOutputShapes[0..2] = (2097152,)
+        inputStrides/outputStrides = (1,)
+rank = 1 → 落入低档 RANK（rank ≤ 4）
+```
+
+**shape 不一致的样例（假设 IN1 shape=(128,64)）**：
+```
+补 1 → IN1=(1, 128, 64)，其他=(256, 128, 64)
+去 1 → dim0: 256,1 → 不全为 1，保留
+归一 → maximumBroShape = (256, 128, 64)
+校验 → dim0: 256,1 → ref=256 ✓
+        dim1/dim2: 全等 ✓
+
+合轴（从最后一维 dim2 开始，向左尝试扩展）：
+  尝试 [dim1,dim2]: IN1 = 128×64 = 8192，其他 = 8192，坐标系组乘积 = 8192
+                     → IN1 整组稠密（8192 = maxProd）✓ → 合并，当前组 = (8192)
+  尝试 [dim0,dim1,dim2]: IN1 = 1×8192 = 8192，坐标系组乘积 = 256×8192 = 2097152
+                     → 8192 既非 1 也非 2097152 ✗ → 封闭组 (8192)，从 dim0 开新组
+  尝试 [dim0]: 单维成组
+
+合轴后: maximumBroShape = (256, 8192)
+        normalInputShapes[1] = (1, 8192)      — dim0 broadcast，dim1 整组稠密
+        inputStrides[1] = (0, 1)              — dim0 stride=0（broadcast）
+        其他输入/输出 = (256, 8192)，strides = (8192, 1)
+rank = 2 → 落入低档 RANK（rank ≤ 4）
+校验（合轴后坐标系） → dim0: 256,1 → ref=256 ✓
+                         dim1: 8192,8192 → ref=8192 ✓
+```
+
+## 5 适配层落地
+
+| 事项 | 位置 |
+|------|------|
+| C++ 参考实现（PadAndSqueeze / BroadcastMergeAxis / CheckBroadcastShape） | adapters/ascendc/tiling-preprocess.md §2 |
+| 错误上报接口与错误日志分层 | 各语言适配层定义（AscendC: `OP_LOGE_FOR_INVALID_*` 系列） |
+| 平台/算子信息获取（值依赖、可选输入、attr 默认值） | 各语言适配层 tiling-preprocess 文档 |

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/splitting.md

@@ -0,0 +1,158 @@
+# Broadcast 范式切分算法（片上内存单切分 + 多核均衡切分）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/tiling.md §1/§2/§3/§6（原 broadcast-standard-tiling.md）。C++ 实现（FindSplitAxis / MultiCoreSplit）、平台信息获取与注册流程在适配层。
+
+## 1 记号与输入
+
+| 记号 | 含义 |
+|------|------|
+| `maximumBroShape` | 切分坐标系（见 [shape-preprocessing.md](shape-preprocessing.md)） |
+| 片上容量 | 单核算可用的片上 buffer 总容量（AscendC: UB 大小） |
+| `P` | 物理存活节点数（见 [liveness-fusion.md](liveness-fusion.md)），决定 buffer 槽位数 |
+| `ALIGN_GRANULARITY` | 片上 buffer 对齐粒度（能力谓词） |
+| `COMPUTE_PRECISION` | 范式统一计算精度（能力谓词），perBufElems 按其字节宽算 |
+| `maxCores` | 可用核数 |
+
+## 2 片上内存单切分
+
+### 2.1 切分原理
+
+以 effective_shape 为坐标系选择**单根切分轴**。
+
+被切分的轴 a = ubOuter × ubFactor。包含 ubFactor 在内的所有内侧轴为「内轴」，一次加载进片上；ubOuter 至最外侧轴为「外轴」，是片上外的 for 循环。
+
+```
+内轴 = 轴 k (贡献 ubFactor) + 轴 k+1..n-1 (全量)
+外轴 = 轴 0..k-1 (全量循环) × ubOuter (轴 k 的分段循环)
+
+片上内存占用 = ubFactor × ∏_{j>k} d_j
+必须满足: ubFactor × inner ≤ perBufElems
+```
+
+**通用约束**：
+- 每份 buffer 大小需按 `ALIGN_GRANULARITY` 对齐
+- 所有 buffer 总和不能超过实际片上容量
+- 必须考虑空 tensor 场景：**使用核数为 0 时仍按 1 核发起**，kernel 侧通过 usedCoreNum=0 短路处理
+- perBufElems 必须满足内轴需求：`perBufElems ≥ effective_shape[ubSplitIdx]` 对应的内轴连乘
+
+### 2.2 选轴算法
+
+从最内轴向外扫描，累积内侧轴连乘 inner。当 `d_k × inner > perBufElems` 时，该轴无法全量放入——在此切分。
+
+```
+inner = 1
+for k from n-1 down to 0:
+    if d_k × inner > perBufElems:
+        split at k
+        ubFactor = perBufElems / inner
+        ubOuter = ceil(d_k / ubFactor)
+        break
+    inner *= d_k
+```
+
+永远至少有一根可切轴。
+
+**尾块**：d_k 不能整除 ubFactor 时，最后一轮 ubTail = d_k % ubFactor（整除时为 ubFactor）。段大小查询：`ubBlockLength = (ubBlockIdx == ubOuter - 1) ? ubTail : ubFactor`。
+
+### 2.3 特殊场景
+
+- 末尾轴装不下：`d_{n-1} > perBufElems` → ubSplitIdx = n-1, ubFactor = perBufElems
+- 全量装得下：`total ≤ perBufElems` → ubSplitIdx = 0, ubFactor = d_0, ubOuter = 1
+- 空 tensor：`numel == 0` 直接返回，不走 kernel（但仍按 1 核发起）
+
+### 2.4 buffer 预算公式
+
+- `perBufBytes = floor(片上容量 / P)` 按 `ALIGN_GRANULARITY` 向下对齐
+- `perBufElems = perBufBytes / sizeof(COMPUTE_PRECISION)`——**永远按统一计算精度算**，不随输入 dtype 变化（原因：低精度输入搬入后立即转换到计算精度，真正填满 buffer 的是计算精度数据；即使输入本身就是计算精度，也按同一公式保持 TilingData 统一）
+
+## 3 多核均衡切分
+
+以片上切分产出的 tile 为单元，将 `totalTiles = ubOuter × Π_{j<k} d_j` 平摊到多核。
+
+**通用约束**：
+- 发起核数严禁为 0（空 tensor 场景见 §2.3）
+- 发起核数严禁超过实际物理核数
+- 使用核间均衡策略，字段约定：
+
+| 字段 | 含义 |
+|------|------|
+| totalTiles | 用于切多核的总 tile 块数 |
+| coreNum | 总核数 |
+| usedCoreNum | 实际使用的核数 |
+| mainTiles | 主核分配的 tile 块数（尾核分配的 tile 块数 = mainTiles − 1） |
+| mainCoreNum | 主核数（尾核数 = usedCoreNum − mainCoreNum） |
+
+**切分公式**：
+
+```
+usedCoreNum = (totalTiles < maxCores) ? totalTiles : maxCores
+mainTiles   = ceil(totalTiles / usedCoreNum)
+mainCoreNum = totalTiles - (mainTiles - 1) × usedCoreNum
+```
+
+前 `mainCoreNum` 个核各处理 `mainTiles` 块，其余核各处理 `mainTiles−1` 块。
+
+**核间 tile 区间解码**（kernel 侧）：
+
+```
+GetCoreRange(coreId, mainTiles, mainCoreNum) → [start, end):
+    if coreId < mainCoreNum:
+        start = coreId × mainTiles
+        end   = start + mainTiles
+    else:
+        start = mainCoreNum × mainTiles + (coreId − mainCoreNum) × (mainTiles − 1)
+        end   = start + mainTiles − 1
+```
+
+## 4 坐标解码与偏移计算（通用算法）
+
+- **flat → 坐标**：`ubBlockIdx = flat % ubOuter`（split 轴外层偏移），`outer = flat / ubOuter`（split 轴以外各维的 flat 索引），从 ubSplitIdx−1 向外逐维取模解码；`coord[ubSplitIdx] = ubBlockIdx × ubFactor`
+- **坐标 → GM 偏移**：`offset = Σ coord[d] × strides[d]`，**返回元素个数**（非字节）；B 轴 stride=0 实现随路广播，padding 轴 stride=0 不贡献偏移
+- **搬运量计算**：split 轴为广播轴（该张量 split 轴大小 == 1）时 split 段只搬 1 个元素（由搬运单元随路展开）；否则搬 ubBlockLength 个元素；总量 = split 段 × 内轴连乘
+
+## 5 切分策略微调
+
+不涉及。当前单切分以 effective_shape 为坐标系，功能全覆盖。部分场景非最优（多数入参远小于 effective_shape 时 padding 占比高），预留多切分扩展点。
+
+## 6 产出校验 golden
+
+**对范式开发者的要求**：
+1. 给一个 case，枚举所有切分可能性，作为 golden；需要"人"保证正确性
+2. 删除 golden，agent 读取本文档可以产出所有的切分可能；产出不了则不断改进范式质量，直到成功
+3. golden 随本文档上库
+
+**golden 样例（Adam: fp32, P=5, 片上容量=262144B, 对齐粒度=32B, coreNum=24）**：
+
+输入 shape 全同 `(256, 128, 64)`，归一化后 `maximumBroShape=(256,128,64)`, rank=3 → 落入低档 RANK=4。
+
+| 参数 | 值 | 计算 |
+|------|-----|------|
+| perBufBytes | 52416 | `(262144 / 5) & ~31` |
+| perBufElems | 13104 | `52416 / 4`（按 4 字节计算精度） |
+| split.ubSplitIdx | 1 → 修正为 0 | d=2(64): 64×1=64 ≤ 13104 ✓; d=1(128): 128×64=8192 ≤ 13104 ✓; d=0(256): 256×8192 > 13104 ✗ → split at 0 |
+
+修正：split.ubSplitIdx=0（d=0 无法全量放入），ubFactor=13104/8192=1（取整后=1），ubOuter=ceil(256/1)=256。
+
+| 参数 | 值 |
+|------|-----|
+| split.ubSplitIdx | 0 |
+| split.ubFactor | 1 |
+| split.ubOuter | 256 |
+| split.ubTail | 1 |
+| totalTiles | 256 |
+| usedCoreNum | 24 |
+| mainTiles | 11 (ceil(256/24)=11) |
+| mainCoreNum | 16 (256−(11−1)×24=16) |
+
+前 16 个核各处理 11 个 tile，后 8 个核各处理 10 个 tile。
+
+## 7 适配层落地
+
+| 事项 | 位置 |
+|------|------|
+| C++ 实现（FindSplitAxis / MultiCoreSplit / GetCoreRange 等） | adapters/ascendc/tiling.md、kernel-helpers.md |
+| 平台信息获取（核数/片上容量，零值守卫） | adapters/ascendc/tiling-preprocess.md §1、tiling.md §8 |
+| 超过搬运维数上限（`TRANSFER_MAX_DIMS`）的逐段搬运分叉 | 各语言适配层 kernel 文档（AscendC: NDDMA outer iters） |
+| TilingKey / TilingData 写入与维测日志 | 各语言适配层 tiling 文档 |

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/sync-model.md

@@ -0,0 +1,79 @@
+# Broadcast 范式同步模型（RAW/WAR 依赖 → 同步点推导）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/kernel-template.md §7（原 broadcast-standard-kernel-template.md）、dag-buffers.md 持有法则。同步原语实体（AscendC: SetFlag/WaitFlag/HardEvent/eventID）在适配层。
+
+## 1 同步的本质
+
+同步 = **跨执行单元的数据依赖**。同一个 buffer，执行单元 A 写、执行单元 B 读（RAW），或执行单元 A 读、执行单元 B 写（WAR）——就必须同步。
+
+- 同一执行单元内自动串行（同单元的读后读/写后写不需同步），由编译器/硬件保证
+- 不同 buffer 互不干扰
+- 无跨执行单元数据依赖时，不需要任何显式同步
+
+## 2 执行单元与事件对
+
+执行单元划分由谓词 `EXEC_UNITS` 定义。本范式涉及三个单元：
+
+| 单元（中立名） | AscendC 实例 | 职责 |
+|------|------|------|
+| 搬入单元 | MTE2 | GM → 片上 |
+| 计算单元 | V | 片上计算 |
+| 搬出单元 | MTE3 | 片上 → GM |
+
+依赖类型与事件对：
+
+| 依赖类型 | 含义 | 事件对（源→目标） | 方向 |
+|---------|------|------|------|
+| RAW | 生产者写 buffer → 消费者读 buffer | 搬入→计算、计算→搬出 | 正向 |
+| WAR | 消费者在读 buffer → 生产者要覆盖 buffer | 计算→搬入（覆盖）、搬出→搬入（跨迭代覆盖） | 反向 |
+
+## 3 四种同步场景
+
+1. **RAW → 搬入_计算**：搬入写完片上 → 计算要读该片上
+2. **WAR → 计算_搬入**：计算正在读片上 → 搬入要覆盖该片上
+3. **RAW → 计算_搬出**：计算写完片上 → 搬出要读该片上
+4. **跨迭代 WAR → 搬出_搬入**：上轮搬出读片上 → 下轮搬入要覆盖该片上
+
+不是每条搬入后都插一对同步——同步点必须由依赖推导而来，不是模板化插入。
+
+## 4 同步点推导方法
+
+**持有法则 → 同步点**（持有法则见 [liveness-fusion.md](liveness-fusion.md) §2）：
+
+1. 遍历每个 buffer 的生命周期，逐步标注三态持有
+2. 标记每一次跨执行单元的 RAW/WAR——持有注释中"上一动作写、本动作读（跨单元）"即 RAW，"上一动作读、本动作写（跨单元）"即 WAR
+3. 每个标记点即一个同步点：正向同步在生产者操作后 Set、消费者操作前 Wait；反向同步在覆盖者操作前 Wait、被覆盖读完成后 Set
+
+**循环间的反向同步**：
+- 末轮迭代跳过 Set（后面没有下一轮消费者）
+- 首轮迭代跳过 Wait（前面没有上一轮生产者）
+
+## 5 多输出同步原则
+
+- 所有计算完成后、**第一次搬出之前**，插入一次 计算→搬出 的正向同步
+- 后续各搬出之间不需要额外同步（搬出单元顺序执行）
+- 若某输出 buffer 在下一轮迭代中被覆写，需确保该次搬出在 跨迭代反向同步（搬出→搬入）完成之前结束
+
+## 6 退出前屏障
+
+Kernel 退出前必须排空所有执行单元（屏障/等待全部流水线），防止搬出未完成即退出。
+
+## 7 事件管理通用约束
+
+（由谓词 `SYNC_PRIMITIVE` 承载，各适配层填值）
+
+- 同步原语必须**成对使用**：一次 Set 必须有对应的一次 Wait
+- 同类型事件可共用一个事件 ID（前一个 Wait 清零后可复用）；不同类型事件必须用不同事件 ID
+- 事件 ID 通过框架接口获取，不可硬编码；部分事件 ID 可能被内部占用而不可用
+- 在 Init 或 Process 开头统一获取事件 ID
+
+## 8 适配层落地
+
+| 事项 | 位置 |
+|------|------|
+| SetFlag/WaitFlag API 签名与 HardEvent 枚举 | adapters/ascendc/kernel-template.md §7.1 |
+| eventID 获取（FetchEventID）与Event ID 池管理 | 同上 |
+| 调用模式代码示例（正向/反向同步） | 同上 |
+| 持有法则完整定义（读/写/原地规则） | paradigms/common/sync-and-consistency.md §2.2.2（AscendC 公共知识） |

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/verification.md

@@ -0,0 +1,131 @@
+# Broadcast 范式设计验证方法论（golden/opt 交叉验证）
+
+> **层级**：通用知识层（generic/），语言中立（harness 为 Python，与开发语言无关）。
+>
+> 来源：adapters/ascendc/tiling.md §6/§7（原 broadcast-standard-tiling.md）。NDDMA 参数块等语言相关验证项在适配层。
+
+## 1 方法论
+
+用两份**独立实现**跑随机 case 对比，验证计算流设计正确性：
+
+- **golden**：spec 公式的逐行翻译（原始计算语义）
+- **opt**：计算流伪码的逐行翻译（融合 + 重排后的物理执行序）
+
+两者必须独立实现（禁止互相参考）。随机 case 至少 180 组，容差默认 `rtol=1e-5, atol=1e-5`。
+
+**用途**：验证 P trace 选定的三要素组合（API 能力 + 融合策略 + buffer 分配）能否兑现为正确计算流。
+
+## 2 使用流程
+
+1. 写 `golden.py` — 导出 `golden(*args, **kwargs)` 和 `generate_test_cases()`
+2. 写 `opt.py` — 导出 `opt(*args, **kwargs)`，签名与 golden 一致，独立实现
+3. 把下方 harness 存为 `verify.py`，取消 `from golden import ...` / `from opt import ...` 两行注释
+4. `python3 verify.py`，exit 必须为 0
+5. `cat verify_results.json` 确认 `total >= 180` 且 `failed == 0`
+
+`generate_test_cases()` 返回 `list[dict]`，每项至少含 `"args"`（位置参数 list）、`"kwargs"`（关键字参数，至少含 `"dtype"`）、可选 `"tolerance"`（`{"rtol": float, "atol": float}`）。
+
+## 3 验证 harness（通用模板）
+
+```python
+#!/usr/bin/env python3
+"""算子物理计算流验证脚本（通用模板）。
+
+约定：
+    golden.py  — 导出 golden(*args, **kwargs) 和 generate_test_cases()
+    opt.py     — 导出 opt(*args, **kwargs)，签名与 golden 一致，独立实现
+"""
+
+import json
+import sys
+import numpy as np
+
+# ── 填入你的 golden / opt 模块 ──
+# from golden import golden, generate_test_cases
+# from opt import opt
+
+
+def main():
+    cases = generate_test_cases()
+    passed = 0
+    failed = 0
+    failures = []
+
+    for i, case in enumerate(cases):
+        case_id = case.get("case_id", f"case_{i:04d}")
+        args = case["args"]
+        kwargs = {k: v for k, v in case.items() if k not in ("args", "tolerance", "case_id")}
+        tol = case.get("tolerance", {"rtol": 1e-5, "atol": 1e-5})
+
+        try:
+            g = golden(*args, **kwargs)
+            o = opt(*args, **kwargs)
+
+            if isinstance(g, np.ndarray):
+                ok = bool(np.allclose(g, o, rtol=tol["rtol"], atol=tol["atol"], equal_nan=True))
+            elif isinstance(g, (tuple, list)):
+                ok = all(
+                    np.allclose(gi, oi, rtol=tol["rtol"], atol=tol["atol"])
+                    for gi, oi in zip(g, o)
+                )
+            else:
+                ok = bool(np.isclose(g, o, rtol=tol["rtol"], atol=tol["atol"]))
+
+            if ok:
+                passed += 1
+            else:
+                failed += 1
+                failures.append({"case_id": case_id, "error": "tolerance exceeded"})
+
+        except Exception as e:
+            failed += 1
+            failures.append({"case_id": case_id, "error": f"{type(e).__name__}: {e}"})
+
+    total = len(cases)
+
+    with open("verify_results.json", "w") as f:
+        json.dump(
+            {"total": total, "passed": passed, "failed": failed, "failures": failures[:20]},
+            f, indent=2, default=str,
+        )
+
+    with open("verify_results.txt", "w") as f:
+        f.write(f"Total: {total}  Passed: {passed}  Failed: {failed}\n")
+        for r in failures[:10]:
+            f.write(f"  FAIL {r['case_id']}: {r['error']}\n")
+        f.write("ALL PASSED\n" if failed == 0 and total >= 180 else "INCOMPLETE OR FAILED\n")
+
+    print(f"Total: {total}  Passed: {passed}  Failed: {failed}")
+    if total < 180:
+        print(f"ERROR: total={total} < 180 — 试验次数不足!")
+        sys.exit(2)
+    if failed > 0:
+        print("FAILED")
+        sys.exit(1)
+    print("ALL PASSED")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## 4 切分逻辑交叉验证块
+
+切分与搬运逻辑按纯逻辑分块，各出 Python 对比，随机 case 100 次：
+
+| # | 验什么（通用块） | 关键检查点 |
+|---|--------|----------|
+| 1 | 计算流序列 | golden(原始公式) vs opt(融合+重排) vs kernel 计算序 — 三者一致 |
+| 2 | 循环 count | `count = ubBlockLength × Π maxBroShape[d>ubSplitIdx]`；split 轴 = 最内维时 inner=1 |
+| 3 | 地址偏移 | B 轴 stride=0 → offset 不贡献；padding 轴 stride=0 → offset 不贡献；GM 偏移 = Σ coord×stride |
+
+第 4 块（多维搬运参数，如 AscendC 的 NDDMA 五字段）与语言强耦合，在对应适配层的 tiling/kernel 文档中定义。
+
+> **注意**：交叉验证的输入数据要和 kernel 看到的完全一致——验证脚本用 `maxBro`（实际 rank 元素），kernel 用 `maxBroShape[RANK]`（特化档位维数，含 padding）。差一个 padding 值就是 bug 盲区。
+
+## 5 何时执行
+
+agent 自行判断：
+- 计算逻辑复杂（链长 >5、含分支/并行路径、多输出）、不确定正确性时执行
+- 简单算子（≤3 步链、单输出、无 精度转换+融合 混合）可跳过

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

@@ -0,0 +1,62 @@
+# Broadcast 范式入口（语言中立）
+
+> 本文件是 Broadcast 范式的**统一入口**：场景判定 + 语言路由 + 消费规则。具体知识分布在两个层次：
+>
+> - **通用知识层** `generic/` — 语言无关的算法、模型、方法论
+> - **语言适配层** `adapters/<lang>/` — 强耦合具体开发语言的实现知识（当前提供 `ascendc`、`dsl`）
+>
+> 范式路由（`routes.yaml` → 本文件）与语言路由（本文件 → 适配层）分离：范式路由由 `op.paradigms` 决定，语言路由由开发语言决定。
+
+---
+
+## 场景判定
+
+满足以下条件的算子属于 Broadcast 范式：
+
+1. **element-wise 计算语义**——输出元素由输入元素的逐点函数计算得到
+2. **多输入间存在 broadcast**——输入 shape 不一致，需广播对齐后计算
+3. **计算公式不含 Reduce**——无跨元素归约（归约类走 Reduction 范式）
+
+典型场景：输入输出 shape 不一致需广播对齐的 element-wise 算子。语言中立的场景模型、坐标系理论与数据流骨架见 [generic/scene.md](generic/scene.md)。
+
+---
+
+## 语言路由
+
+按开发语言选择适配层。语言由调用方显式提供，或读取 `spec.yaml` 的 `op.language`；缺失或未知时先报告输入缺口，不选择语言适配层。
+
+| 开发语言 | 加载内容 | 入口 |
+|------|------|------|
+| `ascendc` | 通用知识层 + AscendC 适配层 | [adapters/ascendc/index.md](adapters/ascendc/index.md) |
+| `dsl`（CANNBotDSL） | 通用知识层 + CANNBotDSL 适配层 | [adapters/dsl/index.md](adapters/dsl/index.md) |
+| 其他语言 | 通用知识层；适配层待确认 | 报告当前没有对应的语言适配层，不读取其他语言的 API 或模板 |
+
+**互斥规则**：一次任务只加载命中语言的适配层，其他语言的适配层不加载、不参考其 API 与代码模板。
+
+---
+
+## 通用知识层索引
+
+语言无关的算法与模型，按需展开（完整检索表见 [generic/index.md](generic/index.md)）：
+
+| 文档 | 覆盖 |
+|------|------|
+| [generic/scene.md](generic/scene.md) | 场景模型、坐标系理论、数据流骨架、能力边界 |
+| [generic/capability-contract.md](generic/capability-contract.md) | 能力谓词定义（通用层算法引用的语言/硬件能力参数） |
+| [generic/shape-preprocessing.md](generic/shape-preprocessing.md) | 补 1 / 去 1 / 归一 / 合轴四步算法与兼容校验 |
+| [generic/splitting.md](generic/splitting.md) | 片上内存单切分与多核均衡切分算法 |
+| [generic/liveness-fusion.md](generic/liveness-fusion.md) | L/P 存活节点模型、持有法则、融合决策方法论 |
+| [generic/sync-model.md](generic/sync-model.md) | RAW/WAR 依赖识别与同步点推导 |
+| [generic/compute-flow.md](generic/compute-flow.md) | 计算流伪码规范（P 分析到编码的桥梁） |
+| [generic/verification.md](generic/verification.md) | golden/opt 交叉验证方法论与 harness |
+
+---
+
+## 消费规则
+
+1. **按需加载**：先读对应语言适配层的 index，再展开当前问题需要的叶子文档。
+2. **叶子文档限额**：单个子问题最多展开 5 个叶子文档，仍未闭环则拆分为更小的子问题
+3. **能力真值**：通用层算法中的能力谓词，以命中语言适配层的 capability-mapping 填值为准（ascendc: [adapters/ascendc/capability-mapping.md](adapters/ascendc/capability-mapping.md)；dsl: [adapters/dsl/capability-mapping.md](adapters/dsl/capability-mapping.md)，其中标注"待验证"的谓词须在产出中声明假设并给出验证义务）
+4. **实现依据**：Ascend C 编码前检视 `adapters/ascendc/example/` 中的参考实现，选型参考 `references/reference-ops/open_source_operator_table.md`。DSL 实现依据对应适配层的能力映射与实现约束。参考实现中的具体算法与参数须按当前算子规格重新核定。
+5. **设计依据**：根据规格读取通用算法与对应语言约束，给出分支、数据结构、资源预算、同步和验证结论；输出格式由调用方指定。Ascend C 设计检查见 [design-spec.md](adapters/ascendc/design-spec.md)，DSL 使用 `references/paradigms/general-methodology-dsl.md`。
+6. **范式优先级**：本范式的专用知识优先于 agent 通用知识；同一设计点结论冲突时，以本范式指向的必读文件为准