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

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/weight-dequant-prologue-fusion/weight-quant-tiling-contract.md

@@ -0,0 +1,83 @@
+# Weight-Quant Tiling 参数合同专题
+
+本文是本场景的 Tiling 方法专题。Step 3 用它设计 Tiling/资源合同并编译 PLAN；Step 4 以 PLAN 初始 Tiling 基线为起点，按实际失败证据读取本文并执行诊断。本文不提供固定 Tiling recipe，当前合法值和支持域必须来自本次 Investigation 报告与 DESIGN。
+
+## 1. 输入与输出合同
+
+输入：`matmul_base_analysis`、Investigation 中已闭合的 Scheduler/Block/Prologue Params 语义事实、当前 Tiling Engine witness。输出：
+
+```text
+tilingdata_field_contract
+scheduler_params_contract
+prologue_params_contract
+alignment_and_space_constraint
+tiling_validation_additions
+```
+
+每个结论必须引用当前候选组装方案评估、witness 和 evidence IDs。
+
+## 2. TilingData 字段语义合同
+
+DESIGN 必须逐字段冻结 TilingData 的语义、单位、合法域和 consumer。当前参考字段（以 Asset Engine 为结构起点，实际字段由 Investigation 确认）：
+
+| 字段 | 语义 | 单位 | consumer | 合法域/约束 |
+|---|---|---|---|---|
+| `usedCoreNum` | 启动核数 | 核数 | kernel launch `<<<usedCoreNum>>>` | 正整数，受平台核数限制 |
+| `baseM` / `baseN` / `baseK` | L0 tile 颗粒 | 元素数 | BlockMmad::Init | baseM×baseN×4×DB ≤ l0cSize |
+| `kL1` | K 方向 L1 chunk | 元素数 | BlockMmad K 循环 + Prologue K 循环 | 分形轴 16 对齐 |
+| `nUbSize` | 单 AIV 单 buffer N 方向元素数 | 元素数 | Prologue UB 规划 | UB 空间约束 |
+| `kUbSize` | 单 AIV 单 buffer K 方向元素数 | 元素数 | Prologue UB 规划 | UB 空间约束 |
+| `mTailCnt` / `nTailCnt` | 尾块切分份数 | 份数 | Scheduler 尾轮 | transB=true 时 nTailCnt 不切分 |
+| `mBaseTailSplitCnt` / `nBaseTailSplitCnt` | 边块合并组数 | 组数 | Scheduler 边块 | 非负整数 |
+| `mTailMain` / `nTailMain` | 合并组主块尺寸 | 元素数 | Scheduler 边块 | 与 baseM/baseN 关系闭合 |
+| `l0cDB` | L0C 双缓冲级数 | 级数 | BlockMmad FIX_M flag | 1 或 2 |
+| `transB` | B 转置标志 | bool | Kernel 布局选择 + Prologue 切分轴 | true/false |
+| `hasOffset` | 有 offset | bool | Prologue VF 分支 + UB 布局 | true/false |
+| `hasBias` | 有 bias | bool | BlockMmad BT 路径 + L1 空间 | true/false |
+
+PLAN 必须逐字段验证复制后的 Asset Tiling Engine 与当前 Scheduler/Block/Prologue Params 合同兼容。只有全部语义/单位/合法域一致才复用或最小适配。
+
+## 3. Tiling Engine 合同
+
+当前 Asset 提供的 `WeightQuantTilingSwat` 是 SWAT 流式路径的 Tiling Engine。DESIGN 必须确认：
+
+1. Engine 入口签名和参数语义与 Investigation 确认的源码一致；
+2. Engine 内部分形轴对齐校验逻辑闭合（transB=true: `n%16==0`; transB=false: `k%16==0`）；
+3. Engine 返回的 TilingData 字段覆盖全部 Scheduler/Block/Prologue consumer；
+4. Engine 不支持的 partition 需要项目 Tiling 返回固定合法控制值时，固定值元组必须绑定 partition_id、legal predicate 和 consumer fields。
+
+不能复用但 device 合同已闭合时，PLAN 可令项目 Tiling Engine 返回经过证明的固定合法控制值。需要新的 Params、specialization 或合法域时返回 Step 2/3。
+
+## 4. 对齐校验合同
+
+Tiling 入口必须自动校验分形轴对齐：
+
+- transB=true：`n % 16 == 0`
+- transB=false：`k % 16 == 0`
+- 违反时抛出 `std::runtime_error`
+
+PLAN 的 Tiling action 必须验证此校验逻辑在复制后的 Engine 中保留。若项目修改了 Engine，必须重新验证校验闭合。
+
+## 5. Tiling 与 BlockMmad 空间一致性合同
+
+DESIGN 必须冻结 Tiling 计算与 BlockMmad/Prologue 使用的空间一致性。UB 空间约束必须按当前 B dtype 参数化，不得硬编码 int8 系数：
+
+| 空间 | Tiling 计算 | BlockMmad/Prologue 使用 | 一致性要求 |
+|---|---|---|---|
+| L1 bias 尾部 | `Align(baseN * biasElemBytes, 64)` | `TOTAL_L1_SIZE - CeilAlign(baseN * sizeof(BiasType), 64)` | biasElemBytes == sizeof(BiasType) |
+| L0C 双缓冲 | `baseM * baseN * 4 * DB_SIZE <= l0cSize` | `HALF_L0C_SIZE = TOTAL_L0C_SIZE / 2` | DB_SIZE 与 l0cDB 一致 |
+| UB | `2*(weightElemBytes+dequantBElemBytes)*kUbSize*nUbSize + 2*dequantBElemBytes*nUbSize*(1+hasOffset) <= UB_SIZE` | Prologue Init UB 布局 | weightElemBytes 与 BType 一致 |
+| L1 总空间 | B_dequant + A + bias | L1 布局合同 | 与 kL1/baseM/baseN 关系闭合 |
+
+参数化 UB 约束公式：设 `weightElemBytes = sizeof(BType)`，`dequantBElemBytes = sizeof(DequantBType)`（通常为 2），UB 系数 = `2 × (weightElemBytes + dequantBElemBytes)`。int8/fp8=1B → 系数 6。当前 Asset Tiling Engine 中 `elemBytesB()` 硬编码为 `DATA_SIZE_INT8`，切换 dtype 时必须参数化。
+
+## 6. 验证门禁
+
+- TilingData 全部字段有闭合的语义/单位/合法域/consumer 映射；
+- 分形轴对齐校验在 Tiling 入口保留；
+- Tiling 与 BlockMmad/Prologue 的空间一致性公式满足；
+- Engine 不支持的 partition 有固定合法值或 blocking 处置；
+- transB=true 时尾轮 N 方向不切分；
+- 官方源码区与 Blaze Asset 原文件保持零改动。
+
+具体 baseM/baseN/baseK/kL1/kUbSize/nUbSize 值来自 DESIGN/PLAN 和当前 shape/资源，不由本文固定。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/troubleshooting/compile-troubleshooting.md

@@ -0,0 +1,231 @@
+# Blaze 编译问题排查
+
+## 适用范围
+
+用于 Step 4 中实际发生的 CMake configure、ASC/C++ 编译、链接、头文件解析和项目构建边界问题。不处理运行时精度、layout、同步或定制场景专属问题。
+
+## 触发信号
+
+- CMake configure/generate 失败；
+- ASC 源文件未按设备语言编译，或设备编译选项缺失；
+- Blaze/tensor_api 头缺失，或同名符号、宏、模板、constexpr 语义冲突；
+- `undefined reference`、入口符号或模板实例无法解析；
+- 实际命令引用项目外历史目录、错误源码副本或旧构建路径；
+- 构建结果与当前 action/checkpoint 的预期不一致。
+
+## 先做什么
+
+先保留完整错误输出，并查看失败 target 的实际 configure、compile 或 link 命令。根据错误只检查相关信息：源文件语言、include 来源、头文件解析路径、声明/定义、链接输入或缓存路径。不要在没有实际命令和错误证据时猜测库名、include 顺序或设备选项。
+
+## 构建前 preflight
+
+第一次完整构建前，先对目标工程做一次最小闭合检查。它的目的不是提前证明算子正确，
+而是避免把构建配置、共享头和 ABI 的问题误报成 Kernel 或设备问题：
+
+1. **目标架构进入真实设备编译命令。** 从 clean configure 产生的实际 ASC command
+   中确认目标 SoC/架构和设备语言选项，而不是只看 CMake cache、环境变量或 README。
+   目标选项缺失时先修 target 配置，再看后续诊断。
+2. **宏的定义语义与取值语义分开。** 对 `#ifdef`、`#if` 和命令行
+   `-DNAME=0/1` 做最小预处理检查；值为 `0` 的宏仍然是“已定义”，不能据此判断
+   分支被关闭。CPU debug、Host selector 和 Device selector 需要分别记录实际宏集。
+3. **共享头的来源和工程 include 根闭合。** 用同一语言、编译器和参数查看 include
+   trace/预处理结果，确认项目副本和当前工具链头来自同一版本；缺少项目根 include
+   时补 target 级路径，不用系统头或历史工程副本碰运气。
+4. **符号先在真实 link 闭合。** 对 `undefined reference` 或设备 link 缺符号，
+   同时检查定义是否进 target、实际 archive/shared library 是否含该符号（可用
+   `nm` 等只读工具核对）以及该库是否出现在实际 link command；头文件可见不等于
+   链接闭合。
+5. **当前 SDK 的签名和命名空间先做最小 compile probe。** 对入口修饰符、Params
+   引用限定、RegBase/PIPE 等名称和 Host/Device helper，直接以当前头文件做最小
+   调用编译。不要从相似版本、类型 alias 或命名猜测 API 所属命名空间。
+   自定义 RegBase Epilogue 还应分别 probe 实际使用的 elementwise、reduction、
+   rounding 和 store API；相似的动词名或 Host 可见声明不能证明 device 语义、
+   lane 结果或地址空间已经闭合。
+6. **三种上下文分别 clean 验证。** 普通 CXX、ASC Host 和 ASC Device/link
+   可能走不同宏、地址空间和符号实例；其中一侧通过不能关闭另外两侧门禁。每次
+   修改目标、宏、include 或 link 后重新 configure，避免旧缓存掩盖结果。
+
+这些检查来自实际出现过的“设备架构未进入 ASC 命令”“`-D...=0` 仍触发
+`#ifdef` 分支”“项目头未被解析”“库中有符号但未进入 link”以及“当前 SDK
+命名空间不同”等原始故障。具体 SoC、库名、错误码和某一版本的宏名只写入项目
+问题记录，不上升为本 Skill 的固定配置。
+
+### 本次 unary/MIX 负向 probe 的首错模式
+
+下面几类错误都曾在同一 fresh GMM custom 生成中出现；它们是 API/地址空间边界，
+不是通过换路线或关闭诊断来规避的理由：
+
+- `MakeTensor` 产生的 `NDExt` `LocalTensor` 传给 legacy `AscendC::Muls` 时，SDK
+  报 `LocalTensor::PrimType` 缺失和静态断言失败。根因是 tensor_api layout 类型与
+  legacy vector API 的类型约束不兼容，不是“float 不支持”。应让 tensor_api 和
+  legacy/RegBase API 在各自已证明的 layout 边界内使用，并用当前 SDK 的同 layout
+  最小 probe 选择调用面；不能靠类型别名或伪造 `PrimType`。
+- 初次写成 `__global__ __aicore__ __mix__` 或调用未在当前 source 中存在的同步 helper
+  时，ASC 首错是未知入口/未解析 helper。应先以当前版本的 typed entry spelling、
+  Params 地址空间和 source-backed CvSync helper 做最小 compile witness，再实现
+  body；compile witness 不能被当成设备可运行证据。
+- 直接把 `const __gm__` TilingData 绑定到普通 C++ 引用、猜测 `DataCopyPad` 方向/参数，
+  或把 `UpdateMask`/RegBase mask 保存成 `const`，会分别触发地址空间、重载和可变引用
+  错误。应使用当前 SDK 已证明的 GM loader、Copy specialization 和可变 mask lvalue，
+  分别 clean 验证普通 CXX、ASC Host、ASC Device/link。
+
+| 触发信号 | 首要检查方向 |
+|---|---|
+| ASC 源文件被按普通 C++ 处理，或缺少预期设备语言诊断 | target 的语言、源文件属性和设备侧编译选项 |
+| 普通 CXX、ASC Host 与 Device 对同一共享头看到不同符号 | 三种编译上下文的 source/宏分支和实际预处理结果 |
+| 项目内 Blaze/tensor_api 头缺失，或同名符号、宏、模板、constexpr 语义异常 | 实际头文件来源、include 形式和搜索顺序 |
+| `undefined reference`、入口符号或模板实例无法解析 | source 是否进入 target、声明/定义、二进制库和链接输入 |
+| 源文件和 ABI 已闭合但静态链接仍有未解析符号 | 当前 CANN/toolchain 的传递库闭包、库顺序和版本来源 |
+| 编译或链接命令出现项目外历史目录、外部源码或旧构建目录 | 项目自包含边界和缓存路径 |
+| Blaze/tensor_api 副本、submodule 或源码位置缺失/不一致 | Step 1 的 Blaze 源码工作区和项目内副本完整性 |
+
+排障和修复以 `<project-root>/operators/<operator_name>/` 为项目边界，不受 PLAN manifest 或当前 action 文件清单限制。修改后更新 PLAN 第 2、4--8 章，重新执行受影响 action/checkpoint，并把错误、实际修改和结果追加到第 11 章 `execution_record`。
+
+## ASC 语言和编译选项
+
+当 ASC 源文件被按普通 C++ 处理，或设备侧选项没有进入命令时：
+
+1. 查看实际 target 的源文件列表和语言属性；
+2. 确认设备侧源文件使用当前工具链要求的 ASC 构建入口；
+3. 确认设备架构和 ASC 选项只作用于相应 target/source；
+4. 修改已授权的项目构建文件，重新生成并构建。
+
+不要为快速通过而把所有 host 源文件都标为 ASC，也不要把设备选项设置成全局编译选项。
+
+## 头文件来源和同名冲突
+
+当报错涉及 Blaze/tensor_api 头、同名声明、模板或 constexpr 语义时：
+
+1. 从实际编译命令区分项目内 include、工具链内置 include 和其他外部 include；
+2. 必要时用同一 compiler、语言和参数查看预处理/include trace，确认真正解析的头文件；
+3. 对照项目内 Blaze/tensor_api 副本的 include 链，判断是否被 CANN 或历史副本中的同名头抢占；
+4. 在受影响 target 上做最小 include 调整并重新核验解析结果。
+
+一个已知类型是：项目内 tensor_api 与 CANN 工具链同时提供同名头，但其中函数的 constexpr、设备侧可用性或模板声明不同。此时不能通过包装同名函数、宏重定义或修改工具链头掩盖冲突。若源码使用引号形式 include，且 trace 证明工具链头抢占了项目内同源头，可以只对受影响的 ASC target 增加项目内 `-iquote` 路径；这是一种证据驱动的修复，不是默认配置。
+
+在普通 Step 4 排障中，禁止修改编译器、CANN 安装目录、Blaze 源码、tensor_api
+源码或未授权的 Skill Asset 原文件，也不要用强制预包含或伪声明绕过真实 API。
+若当前动作是维护本 Skill 明确授权的版本化 `assets/`，应按该维护计划更新
+asset，并以当前 SDK/target 的编译回归闭合，而不是把修改散落到生成算子或外部
+工具链目录。
+
+## `__VEC_SCOPE__` induction 类型闭合
+
+当 ASC 在 `__VEC_SCOPE__` 中报告 `Induction variable must have a type
+uint16_t`，或同时给出“expected type of ops in vector loop cond”时，这是 ASC
+向量循环 DSL 的语言约束，不是可以忽略的 C++ 兼容性 warning：
+
+1. 保留完整诊断，确认首错位于 `__VEC_SCOPE__` 的哪一个循环，以及实际的
+   induction 声明和 bound 类型。
+2. 将该向量循环的 induction variable 声明为 `uint16_t`，并让循环 bound、
+   loop count 在进入 scope 前转换到可证明的 `uint16_t` 范围；用独立的更宽
+   类型保存 byte offset、shape 和剩余元素，避免把地址算术窄化。
+3. 不要用 `const_cast`、关闭诊断、普通 C++ 外层循环或伪声明绕过 ASC DSL
+   约束。若支持域可能超过 `uint16_t`，应拆分向量循环并在每轮重新计算 mask，
+   而不是让 induction 溢出。
+4. 用同一 ASC compiler、架构和 target 做 clean rebuild，再继续真实设备
+   精度/同步回归；Host/C++ 编译通过不能关闭该语言边界。
+
+具体 induction 名称、tile 大小和某一版工具链的诊断文字只记录在项目
+`WALKTHROUGH.md`，不写成 Skill 常量。
+
+## Host/device helper 符号闭合
+
+当 ASC device link 报告某个项目命名空间 helper 的 `undefined symbol`，而普通
+Host 编译已通过时，先把它当作 Host/device 上下文边界问题处理，而不是立即
+添加运行时库或复制另一份实现：
+
+1. 保留 device link 的完整符号、参数类型和失败 target；确认调用点是否在
+   `__global__`/`__aicore__`/`__mix__` entry 的设备实例化路径。
+2. 检查 helper 的真实声明是否具有目标工具链要求的 device 可见限定。若同一
+   ASC 翻译单元确实需要一个 helper 同时生成 Host 和 Device 实体，双限定必须
+   由当前工具链 witness 证明；若代码按上下文分支编译，则 Host helper 可用
+   `inline constexpr`、纯 device helper 用 `__aicore__ inline`。普通 `inline`
+   或 `constexpr` 只说明 C++ 内联/常量语义，不能证明它会进入 device 编译上下文。
+3. 对需要 runtime 参数的 helper，优先在同一项目头中补齐已证明的
+   Host/device 声明；若只是设备侧简单推导，也可在 device 路径使用等价的
+   局部表达式。不得用 dummy 外部定义、伪 runtime 库或历史源码掩盖缺失的
+   device 定义。
+4. 用相同 ASC compiler、架构和 target 做 clean device link，再继续设备
+   运行验证；“Host 编译通过”不能关闭该边界。
+
+这条规则由以下可复用原始故障模式归纳：普通 Host 可见的 runtime helper
+被 ASC device 实例化后，因缺少 device 限定而留下未解析设备符号；最小修复
+是闭合 helper 的 Host/device 声明或使用等价 device-local expression，回归
+判据是 device link clean 且下游真实设备用例仍通过。具体函数名、tile、flag
+和某次工具链的符号名只保留在项目 `WALKTHROUGH.md`，不写成 Skill 常量。
+
+## 当前 ASC/RegBase 签名闭合
+
+当 RegBase、mask 或向量 helper 报参数类型、可变性或声明顺序错误时，以当前
+目标 CANN/ASC 头文件和实际编译命令为唯一事实源：先核对完整声明及调用上下文，
+再让实参的所有权和生命周期满足该声明（例如需要可变引用时使用可变的局部
+值），不要用 `const_cast`、伪声明或工具链补丁绕过错误。若 helper 使用返回类型
+推导，必须在首次调用前提供当前翻译单元可见的声明或定义；“Host 能编译”不等于
+ASC device 路径已闭合。修复后必须 clean rebuild 受影响 target，并把首个诊断、
+实际声明、改动和下游 device/link 回归写入 `execution_record`。具体函数名和
+某一版 SDK 的签名只保留在项目问题记录，不写成固定 Skill API。
+
+## 设备地址空间与编译期分支闭合
+
+当 `Reg::DataCopy`、UB load/store 或 GM/UB tensor view 报指针类型不匹配，或
+代码同时包含 AIC/AIV 路径时：
+
+1. 先按当前 CANN 头文件确认实参的地址空间。`LocalTensor::GetPhyAddr()` 得到
+   的 UB 地址必须在后续表达式中保持 `__ubuf__`，GM 入口和输出地址必须保持
+   `__gm__`；不要先声明成普通 `float*`/`const T*` 再期待 compiler 恢复地址空间。
+   可以用当前工具链接受的 `auto*` 继承地址空间，或显式写目标 address-space
+   pointer，并重新检查 DataCopy 的完整模板签名。
+2. `ASCEND_IS_AIC`、`ASCEND_IS_AIV` 等是编译期语法分区，不是可与运行时布尔
+   表达式拼接的普通值。把需要的运行时判断放在对应 compile-time block 内，不能
+   写成 `if ASCEND_IS_AIC && condition`，也不能让另一侧访问未实例化的对象。
+3. device GM POD/tiling 由 `__global__ __aicore__` entry 使用当前项目
+   生成的 `GET_TILING_DATA_WITH_STRUCT`/`GET_TILING_DATA_MEMBER` 或同一工具链
+   已证明的 typed loader 解包，再把本地 POD 传给 Kernel。公共 Kernel
+   资产不得直接持有 raw tiling `GM_ADDR`、逐字段复制或用
+   `reinterpret_cast`/伪声明掩盖生命周期和地址空间问题。
+4. 若当前 Tensor API/source witness 的 `MakeMemPtr` 接口接收 raw `GM_ADDR`，
+   Params 应保留 raw GM address；只在该 source-compatible 调用点形成 typed
+   `__gm__` view。typed `__gm__` 指针能够通过 Host 编译但设备挂起时，应先做
+   当前 SDK 的最小 GM-copy probe，不得把 typed pointer 形式当作 ABI 等价物。
+5. 修复后必须用同一 ASC compiler、架构和 target 做 clean configure/build，再
+   继续真实设备回归；只看到 Host/C++ 编译通过不能关闭该边界。
+
+这条规则由 MX MatMul+SwiGLU 的实际首错归纳：普通指针声明丢失 UB 地址
+空间、编译期宏与运行时 `&&` 混写、以及未经生成 loader 的 GM tiling
+aggregate helper 均会在设备
+编译边界失败。具体指针、tile 和函数名保留在项目问题记录，不写成固定 API。
+
+## 链接和项目边界
+
+遇到未解析符号时，依次确认：
+
+1. 定义所在源文件是否进入当前 target；
+2. 声明、定义、Wrapper 和入口 ABI 是否一致；
+3. 所需项目库或既有工具链/运行时库是否进入实际 link command；
+4. 路径是否错误指向其他项目、历史构建目录或不同版本副本。
+
+可以在项目根内修正 source、target 级链接配置和既有依赖路径，也可以补充项目内 helper 或构建文件，但不要照搬其他工程的库清单或全局链接目录。若修复需要新的外部依赖，返回 Step 3。
+
+## Blaze 源码工作区问题
+
+如果实际命令表明项目内副本、`ops-tensor/`、submodule 或缓存来源不一致：
+
+- 只读核对 Step 1 建立的 Blaze 源码工作区和递归 submodule；
+- 确认项目内 `blaze/`、`tensor_api/` 副本来自当前 Blaze 源码；
+- 确认构建没有读取其他项目或历史目录；
+- 源码位置、submodule 或项目副本不完整时停止修改并返回 Step 1；
+- 当前 Blaze 源码的类型、入口、Params 或 API 事实不足时返回 Step 2。
+
+不要用旧二进制、历史副本或项目外源码临时替代当前项目输入。
+
+## 修复边界和验证
+
+Step 4 可以在项目根内调整源码、include 顺序、target 编译选项和当前项目/既有工具链依赖的链接配置，以实现冻结设计。修复后重新执行失败的 checkpoint 及受影响的下游 checkpoint；构建通过后继续执行 PLAN 中的功能、精度和回归 checkpoint，不能把“编译成功”当作算子验证完成。实现问题应继续留在 Step 4 诊断和修复，除非证据要求改变冻结设计或补充上游源码事实。
+
+以下情况停止修复并返回 Step 3：
+
+- 需要改变实现路线、Blaze 组装方案或定制场景；
+- 需要改变算子接口、Kernel ABI 或 Tiling/Params 语义；
+- 需要改变数据语义、地址/ABI、支持范围或验证范围；
+- 需要新的 Blaze 源码事实或新的外部依赖。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/troubleshooting/optimized-runtime-hang.md

@@ -0,0 +1,102 @@
+# Blaze 优化构建运行时挂起与数据损坏排查
+
+> **适用范围**：设备运行在优化构建下挂起、超时或产生大范围错误，而低优化构建、
+> 禁用别名优化或局部诊断路径表现不同。本文只提供运行时证据采集和因果闭合方法；
+> 不替代冻结的 DESIGN/PLAN，也不授权新增实现动作。
+
+## 1. 触发信号
+
+出现以下任一信号时读取本文：
+
+- 同一输入在优化构建下超时，而低优化构建或禁用别名优化后完成；
+- trace 表面停在 Fixpipe、Copy、HardEvent 或终端 consumer，但没有证明上游
+  producer 的次数和形状；
+- Host 打印的 Tiling 正常，设备侧 Scheduler/Block 收到的 shape、tile 或循环次数异常；
+- 正式路径通过，但新增 staged diagnostic 失败，或反之。
+
+低优化、`-fno-strict-aliasing`、额外 barrier、清零和绕过某阶段都只能作为
+诊断探针。它们改变代码生成或执行时序，不能单独成为根因或正式修复。
+
+## 2. 先验证运行时控制数据
+
+在修改同步前，按以下顺序取证：
+
+1. 证明实际执行的是本次构建产物，并记录设备可见命令、架构和返回码。
+2. 在设备侧完成 Tiling 装载后、进入 Scheduler 前，采集最小本地快照：
+   M/N/K、base shape、used core、workspace offset 以及控制 producer 次数的字段。
+3. 将本地快照与 Host 序列化字节和字段定义逐项比较；Host 打印正确不能证明
+   Device 已按相同类型和偏移读取。
+4. 检查每个终端 consumer 是否存在对应 producer，并核对零循环和空分组路径。
+5. 只有控制数据和 producer/consumer 次数均正确后，才继续分析 event、barrier
+   和跨核同步。
+
+若 shape 或循环次数字段已错误，后续 Fixpipe/HardEvent 等待通常是上游控制数据
+损坏的结果，不应直接归因到同步 API。
+
+## 3. TilingData 的类型化装载
+
+Host 和 Device 必须共享同一 POD 字段类型、顺序、对齐和序列化合同。Device
+装载后应通过声明类型读取字段。禁止用不兼容类型指针写入一个已声明类型对象，
+再从其成员读取：
+
+```cpp
+// 禁止：uint32_t 写入破坏后续 uint64_t/float 成员的别名语义。
+auto *dst = reinterpret_cast<uint32_t *>(&localTiling);
+for (uint32_t i = 0; i < wordCount; ++i) {
+    dst[i] = src[i];
+}
+```
+
+可接受的实现必须由当前工具链和源码事实证明，例如：
+
+- 按字段从 GM 读取并赋给同类型成员；
+- 使用当前 CANN 已证明支持的 TilingData loader；
+- 以字节复制到对象表示，并满足该对象可按当前语言/工具链规则使用的前提。
+
+不能仅以“字节数相同”证明 word-wise pointer punning 合法。若
+`-fno-strict-aliasing` 能使失败消失，它只提高“类型别名违规”假设的可信度；
+正式修复仍须恢复合法的类型化装载，并在原优化级别回归。
+
+## 4. Producer/Consumer 因果闭合
+
+对挂起点建立次数表：
+
+```text
+runtime field -> loop bound -> producer count -> consumer count -> terminal wait
+```
+
+必须检查零次 producer 路径。例如 K 被错误解码为 0 时，MMAD 循环可能不产生
+任何结果，而无条件 L0C-to-UB/Fixpipe consumer 仍等待一个永远不会到达的完成事件。
+这类现象不能用“最后卡在 Fixpipe”归因到 Fixpipe。
+
+根因结论至少需要：
+
+1. 原始失败可复现；
+2. 一个正交探针隔离候选因素；
+3. 反向探针恢复原始优化条件后，仅修复候选因素即可通过；
+4. 可行时用故障注入重现同类信号；
+5. 正式路径在 clean build、原优化级别和边界矩阵下回归。
+
+## 5. Staged Diagnostic 冲突
+
+诊断路径与正式路径结果冲突时，先把诊断路径本身视为未校准。检查它是否保持：
+
+- 相同 AIC/AIV lane 所有权、M/N 分片和 inactive lane 规则；
+- 相同 workspace layout、row pitch、地址偏移和 tail 处理；
+- 相同 producer/consumer 同步边界和输出生命周期；
+- 合法的 UB-to-GM 搬运，而不是改变语义的临时 scalar store。
+
+场景级 staged diagnostic 的输出合同和校准门禁见对应 scenario development guide。
+未经已知正确 case 校准的诊断结果不能用于判定 BlockMmad、Epilogue 或 Quant 的责任。
+
+## 6. 回退边界
+
+| 发现 | 回退目标 |
+|---|---|
+| 当前构建产物、设备上下文或 Tiling 序列化来源不一致 | Step 1 |
+| TilingData 类型、设备 API 或 producer/consumer 事实不足 | Step 2 |
+| base shape、loader、同步或诊断输出合同需要改变 | Step 3 |
+| 已冻结 action 内的普通实现错误，且已有修复/回归 action | Step 4 |
+
+不要把 O0、禁用别名优化、额外同步、清零或关闭某阶段保留为最终修复，除非它本身
+就是 DESIGN 明确冻结且有当前源码依据的合同。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/workflow/step1-project-setup.md

@@ -0,0 +1,170 @@
+# Step 1: Project Setup
+
+> **定位**：建立当前算子工程、根级 Blaze 源码版本、只读源码区和版本一致性记录。Step 1 保留 clone、递归 submodule 初始化和版本确认；不调查 Blaze 组装方案、不选择路线、不创建场景实现。
+
+## 1. 路径合同和目录结构
+
+`<project-root>` 是最高层项目根，`<operator_name>` 是 `operators/` 下的当前算子目录。`ops-tensor/` 与 `operators/` 必须同级：
+
+```text
+project_root: <project-root>
+operators_root: <project-root>/operators/
+operator_name: <operator_name>
+operator_root: <project-root>/operators/<operator_name>/
+blaze_source_root: <project-root>/ops-tensor/
+```
+
+完整目录结构：
+
+```text
+<project-root>/
+├── ops-tensor/                         # 共享 Blaze 上游源码，只读
+└── operators/
+    └── <operator_name>/
+        ├── docs/
+        │   ├── blaze/
+        │   │   └── blaze-investigation-report.md # Step 2 输出
+        │   ├── DESIGN.md               # Step 3 输出
+        │   └── PLAN.md                 # Step 3 输出
+        ├── op_kernel/
+        │   ├── include/
+        │   │   ├── blaze/              # 同源官方副本，只读
+        │   │   ├── tensor_api/         # 同源官方副本，只读
+        │   │   └── blaze_custom/       # 仅 blaze_custom 按 PLAN 使用
+        │   │       ├── block/
+        │   │       ├── kernel/
+        │   │       ├── epilogue/
+        │   │       ├── policy/
+        │   │       └── utils/
+        │   └── <Kernel/Wrapper 文件>   # 由 PLAN 冻结
+        ├── op_tiling/
+        │   └── <TilingData/Tiling 文件>
+        ├── <Launcher 文件>
+        ├── scripts/
+        ├── data/
+        │   ├── input/
+        │   ├── golden/
+        │   └── output/
+        ├── CMakeLists.txt
+        └── <其他构建文件>
+```
+
+创建当前算子根和最小空目录。不要预先生成固定 Kernel、Wrapper、Launcher、脚本或测试文件；DESIGN/PLAN 只由 Step 3 生成。
+
+```bash
+mkdir -p <project-root>/operators/<operator_name>/docs/blaze
+mkdir -p <project-root>/operators/<operator_name>/op_kernel/include
+mkdir -p <project-root>/operators/<operator_name>/op_tiling
+```
+
+## 2. Blaze 源码版本门禁
+
+### 2.1 首次拉取
+
+`<project-root>/ops-tensor/` 不存在时，从授权仓库递归拉取 ops-tensor 及全部 submodule：
+
+```bash
+git clone --recurse-submodules \
+  https://gitcode.com/cann/ops-tensor.git \
+  <project-root>/ops-tensor
+git -C <project-root>/ops-tensor submodule sync --recursive
+git -C <project-root>/ops-tensor submodule update --init --recursive
+```
+
+clone 目标只能是 `<project-root>/ops-tensor/`。不得拉取到 `operators/`、当前算子目录、其他项目或其他临时位置。
+
+### 2.2 已存在源码
+
+已有 `<project-root>/ops-tensor/` 时不重复 clone。只在当前版本合同授权下更新，并检查 remote、branch、worktree、父仓 gitlink 和递归 submodule：
+
+```bash
+git -C <project-root>/ops-tensor remote -v
+git -C <project-root>/ops-tensor status --short --ignore-submodules=none
+git -C <project-root>/ops-tensor fetch origin master
+git -C <project-root>/ops-tensor checkout master
+git -C <project-root>/ops-tensor pull --ff-only origin master
+git -C <project-root>/ops-tensor submodule sync --recursive
+git -C <project-root>/ops-tensor submodule update --init --recursive
+git -C <project-root>/ops-tensor submodule status --recursive
+git -C <project-root>/ops-tensor rev-parse HEAD
+git -C <project-root>/ops-tensor ls-tree HEAD include/tensor_api
+```
+
+命令输出仅用于建立抽象一致性状态。不要把提交 ID、manifest/hash、文件哈希或时间戳写入 Blaze Skill 合同。dirty、detached、ahead/diverged、remote 不匹配、父仓 gitlink 不一致、未初始化或不匹配的递归 submodule 都必须停止。
+
+## 3. 同源只读区
+
+从同一 `blaze_source_root` 复制或绑定编译所需的官方目录：
+
+```bash
+cp -r <project-root>/ops-tensor/include/blaze \
+  <project-root>/operators/<operator_name>/op_kernel/include/
+cp -r <project-root>/ops-tensor/include/tensor_api \
+  <project-root>/operators/<operator_name>/op_kernel/include/
+```
+
+实际源目录以当前 checkout 为准；布局不一致时停止，不猜测替代路径。以下三个区域始终只读：
+
+- `<project-root>/ops-tensor/`；
+- `<project-root>/operators/<operator_name>/op_kernel/include/blaze/`；
+- `<project-root>/operators/<operator_name>/op_kernel/include/tensor_api/`。
+
+Skill Asset 原文件同样只读。后续编译 include path 显式指向项目副本，不通过修改只读源码绕过版本问题。
+
+每次复制都必须显式区分 source 和 destination，并在命令返回后核对目标文件树；
+source 与 destination 相同、目标目录落入只读区或复制返回非零时，首个失败边界是
+Step 1 setup，必须先修复并重新核对，不能继续生成代码或把工具错误归因于编译/设备。
+
+## 4. Custom 隔离区
+
+Step 1 可以建立空目录：
+
+```bash
+mkdir -p <project-root>/operators/<operator_name>/op_kernel/include/blaze_custom/{block,kernel,epilogue,policy,utils}
+```
+
+该目录不表示已经选择 `blaze_custom`。只有同时满足以下条件，Step 4 才能复制并适配项目副本：
+
+1. Step 3 冻结 `implementation_route=blaze_custom`；
+2. 唯一场景合同授权对应层级；
+3. PLAN 明确列出复制、修改和验证动作。
+
+`blaze_native` 和 `unsupported` 不预复制 custom 文件。纯 MatMul 的官方能力缺口不能通过创建 custom 文件自动 fallback。Custom 符号使用独立 namespace，不依靠 include 顺序覆盖官方偏特化。
+
+## 5. 最小工程边界
+
+Step 1 只建立工程路径和明确需要的空目录，不实现公式、Tiling、Golden 或测试。具体文件名、数据格式、构建目标和脚本数量由 Step 3 PLAN 决定。
+
+不要把固定 Basic/Grouped/MX 工程、固定 recipe、旧 Launcher 或静态组合表复制为默认工程。`assets/op_tiling/` 只有在 Step 3 逐字段证明兼容并写入 DESIGN/PLAN 后，才能由 Step 4 复制到项目内适配；Asset 原文件保持零 diff。
+
+## 6. Handoff
+
+Step 1 交接以下抽象字段：
+
+```text
+project_root
+operators_root
+operator_name
+operator_root
+blaze_source_root
+source_version_status: current_checkout | same_investigation_source | consistent
+checkout_consistency: confirmed | blocking
+submodule_status
+read_only_source_regions
+upstream_read_roots
+```
+
+`upstream_read_roots` 只能包含同一 `blaze_source_root`，不能引入第二源码根。Step 2/3/4 必须绑定同一次一致的 Blaze 源码版本；后续发现变化时返回 Step 1。
+
+## 7. 完成门禁
+
+- `project_root`、`operators_root`、`operator_root` 和 `blaze_source_root` 已按合同派生；
+- `ops-tensor/` 与 `operators/` 同级；
+- ops-tensor 来自授权仓库，remote/branch/worktree 状态可核验；
+- 所有递归 submodule 已初始化且与父仓 gitlink 一致；
+- 三个官方源码区和全部 Skill Asset 原文件只读；
+- custom 空目录没有被当作路线选择或能力证据；
+- 未预复制场景实现、固定工程或旧 recipe；
+- 版本记录使用抽象字段，不包含实际提交节点。
+
+完成后进入 [Step 2: Blaze Investigation](step2-blaze-investigation.md)。