@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/vc-sync-and-l1-layout-design.md

@@ -0,0 +1,103 @@
+# V+C 数据流、CV 同步与 L1 布局专题
+
+本文是本场景 Kernel 层的 V+C 协作、CV 同步和 L1 内存规划专题。Step 3 用它设计 Kernel delta 和 Block delta 中的同步/L1 合同；DESIGN 冻结后，Step 3 用它编译对应 PLAN action；Step 4 只有在 PLAN 将本文绑定到当前 action 时才读取。本文不选择 Blaze 组装方案，也不提供固定同步 recipe。
+
+## 1. 输入与输出合同
+
+输入：`matmul_base_analysis`、Investigation 中已闭合的 CV 同步 API 事实、L1 容量事实和当前 Block/Prologue witness。输出：
+
+```text
+vc_dataflow_contract
+cv_sync_contract
+l1_layout_contract
+bias_consistency_contract
+sync_validation_additions
+```
+
+每个结论必须引用当前候选组装方案评估、witness 和 evidence IDs。
+
+## 2. V+C 数据流合同
+
+本场景的数据流方向为 V+C（AIV 先执行 → AIC 后执行），与 C+V epilogue 融合（AIC 先 → AIV 后）方向相反。DESIGN 必须冻结完整数据流：
+
+| 阶段 | 执行核 | 数据路径 | 必填合同 |
+|---|---|---|---|
+| Prologue | AIV | GM B(low-bit) → UB → VF 反量化 → UB → L1(bf16/fp16 B_dequant) | 每段搬运的 dtype/layout/extent/offset |
+| MMAD | AIC | GM A(bf16) → L1 → L0A; L1 B_dequant → L0B → MMAD → L0C → Fixpipe → GM | BlockMmad 的 K 循环、双缓冲和 L0C 输出 |
+
+DESIGN 必须确认：
+1. AIV 写入 L1 的 B_dequant 的 layout 与 AIC BlockMmad 从 L1 读取 B 的 layout 一致；
+2. AIC 不执行 B 的 GM→L1 搬运（B 来源从 L1 读取，非 GM）；
+3. A 侧搬运路径与官方 MatMul 一致（保留基础合同）。
+
+## 3. L1 布局合同
+
+L1 空间由 AIV 写入的 B_dequant 和 AIC 读取的 A 共享。DESIGN 必须冻结 L1 布局：
+
+| 区域 | 内容 | 必填合同 |
+|---|---|---|
+| Lower half | B0 + A0 | B_dequant buffer 0 和 A buffer 0 的字节范围、对齐 |
+| Upper half | B1 + A1 | B_dequant buffer 1 和 A buffer 1 的字节范围、对齐 |
+| Tail（可选） | bias | 64-byte 对齐、`Align(baseN * biasElemBytes, 64)` |
+
+DESIGN 必须回答：
+1. B_dequant 和 A 在每个 half 内的排列顺序和字节边界；
+2. bias 存在时 L1 尾部空间的计算公式和与 Tiling 的一致性；
+3. ping-pong half 的切换与 K-L1 迭代的对应关系；
+4. L1 总空间约束：`B_dequant + A + bias <= TOTAL_L1_SIZE`。
+
+## 4. CV 同步合同
+
+AIV 和 AIC 通过 CrossCore/HardEvent 同步。DESIGN 必须冻结同步时序：
+
+| 事件 | 方向 | 时机 | 必填合同 |
+|---|---|---|---|
+| AIC_SYNC_AIV_FLAG | AIC → AIV | AIC 消费完 L1 B_dequant | flag ID、count、pipe 配对 |
+| AIV_SYNC_AIC_FLAG | AIV → AIC | AIV 写完 L1 B_dequant | flag ID、count、pipe 配对 |
+
+DESIGN 必须回答：
+1. 首轮 K-L1 迭代是否预置 AIC_SYNC_AIV_FLAG（避免首轮阻塞）；
+2. K-loop 内 AIV/AIC 的 wait/set 交替顺序；
+3. 循环结束后剩余 flag 的消费（final drain）；
+4. 是否使用 CrossCore 同步还是仅 HardEvent（本场景 AIV/AIC 在同一核内，使用 HardEvent 即可，无需 CrossCore）；
+5. 预置 flag 的数量与 L1 buffer 数 × AIV sub-block 数的关系。
+
+同步事件 ID、count 和 pipe 必须来自当前 Investigation 的源码事实，不从历史实现泛化。
+
+## 5. Bias 类型一致性合同
+
+Bias 默认为 `float`，也可改为 `bfloat16_t` 或 `half`。当 BiasType 改变时，以下 4 处必须同步修改：
+
+| # | 组件 | 合同要求 |
+|---|---|---|
+| 1 | BlockMmad `using BiasType` | 与 DESIGN 冻结的 bias dtype 一致 |
+| 2 | BlockMmad `tensorBiasL1` | 自动跟随 BiasType |
+| 3 | Kernel `biasGmPtr` | 使用 `BiasType*`，不得用 `CType*` |
+| 4 | Tiling `biasElemBytes` | `sizeof(BiasType)`，与 BlockMmad 一致 |
+
+DESIGN 必须确认 GM/L1/BT 三处 bias 类型一致，否则 `CopyGM2L1` 的类型检查会编译失败。`biasL1Offset_` 使用 `sizeof(BiasType)` 计算 L1 空间，Tiling 的 `biasElemBytes` 必须与之匹配。
+
+## 6. 对齐约束合同
+
+DESIGN 必须冻结分形轴对齐约束：
+
+| 条件 | 约束 | 原因 |
+|---|---|---|
+| transB=true | N 必须 16 对齐 | N 是分形轴（ZN），AIV 切分点需 16 边界 |
+| transB=false | K 必须 16 对齐 | K 是分形轴（NZ），AIV 切分点需 16 边界 |
+| transB=true | 尾轮 N 方向不切分 | `CeilDiv` 不保证 16 对齐，破坏分形边界 |
+| M | 任意 | M 不是分形轴 |
+
+Tiling 入口必须校验分形轴对齐，违反时抛出 `std::runtime_error`。
+
+## 7. 验证门禁
+
+- V+C 数据流方向正确（AIV 先 → AIC 后），无反向依赖；
+- L1 布局的 B_dequant/A/bias 字节边界与 Tiling 一致；
+- CV 同步的 flag 预置、交替和 final drain 闭合，无死锁或残留 flag；
+- BiasType 在 GM/L1/BT/Tiling 四处一致；
+- 分形轴对齐约束在 Tiling 入口校验；
+- L1 总空间约束满足；
+- 官方源码区与 Blaze Asset 原文件保持零改动。
+
+具体 flag ID、L1 偏移、bias dtype 和对齐值来自 DESIGN/PLAN 和当前 Investigation，不由本文固定。

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

@@ -0,0 +1,289 @@
+# Weight-Dequant Prologue Fusion 设计指导
+
+本文是 `weight-dequant-prologue-fusion` 在 Step 3 唯一命中后的设计入口。它明确消费 `matmul_base_analysis` 形成的 MatMul 基础分析，设计 AIV 侧反量化 Prologue 与 AIC 侧 MMAD 的 V+C 融合增量；不重新选择基础 MatMul Blaze 组装方案，不编写代码、编译或上板。若报告缺少本场景要求的 Blaze 源码事实，本文只提出一次语义化补充调查并返回 Step 2。
+
+## 目录
+
+1. 场景范围与入口门禁
+2. 输入和依赖 Skill
+3. 设计流程
+4. 三层增量合同
+5. Tiling/资源/同步合同
+6. 场景验证增量
+7. 输出、合并与门禁
+
+## 1. 场景范围与入口门禁
+
+本场景只处理 `AIV 先反量化低比特权重 B → AIC 后 MMAD` 的 V+C prologue 融合。设低比特权重为 `B[q,k,n]`（int8），反量化参数为 `scale[n]`/`offset[n]`（bf16/fp16），反量化后权重为 `B_dequant[k,n]`（bf16/fp16），最终输出为 `C[m,n] = A[m,k] × B_dequant[k,n]`。只有同时满足以下条件才进入本场景：
+
+- B 输入为低比特量化权重（int8），需在 device 侧反量化后参与 MMAD；
+- 反量化发生在 MMAD 之前（V+C 方向），AIV 先执行反量化写入 L1，AIC 从 L1 读取 B_dequant 做 MMAD；
+- 反量化参数为 perchannel（`scale[n]`/`offset[n]`）；
+- 所有参与输入和输出的 shape、dtype、layout、transpose 及索引规则均可冻结；
+- Step 3 已在官方 Blaze 方案分析中记录 `native_gaps`，并由[场景索引](../index.md)唯一命中本场景。
+
+以下语义不属于本场景：
+
+- Blaze 原生支持的量化 MatMul（A8W8/MX scale 路径）——这些走 `blaze_native`，不进入场景匹配；
+- pergroup 量化——当前只支持 perchannel；
+- Weight-Quant + Vector Epilogue 后融合——Epilogue 固定为 void；
+- C+V epilogue 融合（AIC 先 MMAD → AIV 后处理）——这是 `elementwise-broadcast-epilogue-fusion` 场景，数据流方向相反，不可能同时命中。
+
+本场景不属纯 Quantized MatMul 范畴。纯 Quantized MatMul（A8W8/MX）使用 Blaze 原生 scale 路径，走 `blaze_native`；本场景的权重反量化 prologue 融合是 Blaze 无入口的 V+C 融合，走 `blaze_custom`。
+
+场景名称不自动证明任意 dtype、layout、transpose、hasOffset、hasBias 组合受支持。所有能力都由当前需求、Investigation 和 DESIGN 冻结。
+
+## 2. 输入和依赖 Skill
+
+### 2.1 必需输入
+
+进入正文前必须具备：
+
+```text
+requirements_contract
+operator_interface_contract
+matmul_base_analysis
+matmul_base_analysis.abi_bindings[]
+investigation_report_facts
+native_gaps
+```
+
+本场景明确要求 `blaze_custom` 路线消费 `matmul_base_analysis` 产出的 MatMul 基础合同投影。`matmul_base_analysis` 至少包含：
+
+```text
+candidate_evaluation_ids_considered
+concrete_blaze_composition_and_specialization
+kernel_policy_block_scheduler_chain
+tilingdata_params_and_scheduler_semantics
+abi_bindings[]:
+  design_binding_ref
+  partition_ids
+  assembly_witness_ref
+  kernel_abi_contract
+  abi_crosswalk
+  source_backed_signature_skeleton
+final_partial_workspace_and_output_lifecycle
+logical_and_physical_data_contract
+resource_and_dispatch_contract
+evidence_refs
+```
+
+本文消费这份投影中的官方 BlockMmad/Scheduler 组件事实（Params 语义、L1/L0 布局约定、ABI crosswalk 基础行）作为 custom 组装的基础参照。场景 delta 在此基础上定义保留、替换和新增合同。基础合同或场景前提缺失时，不得继续场景设计；向 Step 2 提交一次精确的无场景名补充问题。一次补充后仍缺关键事实时停止等待用户澄清，不写最终路线，也不生成 DESIGN/PLAN。
+
+### 2.2 Blaze 源码前提与补充问题
+
+在设计 Block层、Kernel层或 Prologue 层之前，检查 Investigation 报告是否已经记录以下事实：
+
+| 前提 | 需要的 Blaze 源码事实 |
+|---|---|
+| 官方 BlockMmad 组件 | BlockMmad Params 字段语义、L1/L0 布局约定、bias 路径、K 循环结构 |
+| 官方 Scheduler | Scheduler Params 语义、蛇形遍历、尾块切分和 grid/usedCore |
+| VF Cast API | 当前 CANN 中各 BType（int8/fp8）的 Cast dtype 组合是否受支持（查阅 asc-devkit `Cast.md` 数据类型组合表）；CastTrait、LoadDist、StoreDist 等具体配置由 Investigation 确认 |
+| CV 同步 | HardEvent/CrossCore flag 配对、pipe、producer/consumer 和 final drain |
+| Tensor API | B_dequant 写入 L1 的 Copy API、layout 和 alignment |
+
+缺少其中的决定性事实时，写入下一轮同一 Investigation 报告的：
+
+```text
+requested_by: Step 3
+affected_requirement_ids
+semantic_questions: <例如"确认 int8→bf16 CastTrait 的声明形式和可用性">
+required_blaze_source_frontier
+why_decision_is_blocked
+```
+
+不得写入本场景 ID、场景路径、Prologue/Block/Kernel 选择或定制实现建议。只允许一次补充；补充后仍缺事实则等待用户澄清。
+
+### 2.3 依赖 Skill 门禁
+
+场景设计必须先加载两个 Skill 根入口：
+
+- [`/ascendc-api-best-practices/SKILL.md`](../../../../ascendc-api-best-practices/SKILL.md)
+- [`/ascendc-regbase-best-practice/SKILL.md`](../../../../ascendc-regbase-best-practice/SKILL.md)
+
+再按当前公式读取必要的 VF Cast API、限制、pitfalls 和真实参考实现。直接打开叶子文档不能替代加载根入口。DESIGN 要记录两个 Skill 的 `source_ref`、当前 API 证据、适用限制和用于比较的真实实现来源。
+
+## 3. 顶向下设计流程
+
+### 3.1 冻结公式和反量化合同
+
+先写出完整公式 DAG，不以"weight-quant matmul"之类名称代替数据合同：
+
+| 对象 | 必填合同 |
+|---|---|
+| A 输入 | 逻辑/物理 shape、dtype（bf16/fp16）、layout、transpose |
+| B 输入 | 逻辑/物理 shape、dtype（int8）、layout、transpose、perchannel 量化模式 |
+| scale | dtype（bf16/fp16）、shape `(N,)`、perchannel 加载方式、广播映射 |
+| offset | dtype、shape `(N,)`、可选语义、缺省为 0 的条件 |
+| bias | dtype（float/bf16/fp16）、shape `(N,)`、可选语义、缺省为 nullptr |
+| B_dequant | dtype（bf16/fp16）、L1 layout、写入时机和生命周期 |
+| 最终输出 C | 逻辑/物理 shape、dtype、累加/转换/舍入、GM layout |
+| Golden | 与设备相同的操作和 dtype 转换顺序 |
+
+对每个 `(k,n)` 显式写出反量化公式：`B_dequant[i,j] = (B[i,j] + offset[j]) * scale[j]`。Cast 链：int8→fp16→bf16（两步）或 int8→fp16（一步，当目标为 fp16 时）。
+
+对每个新增 operand、B_dequant 中间值、Prologue Params 字段或同步对象，追加一行 `abi_crosswalk_delta`：`delta_crosswalk_row_id`、`base_design_binding_ref`、`base_crosswalk_row_refs`、物理 buffer/字节规则、Launcher/Wrapper/Kernel 接线、Tiling/Params 字段或 `not_applicable` 理由、设备消费者、生命周期和 `source_refs`。
+
+### 3.2 消费 MatMul 基础合同
+
+核对：
+
+1. 官方 BlockMmad 的 Params 字段语义、L1/L0 布局约定和 bias 路径已闭合；
+2. 官方 Scheduler 的 Params 语义、蛇形遍历和尾块切分已闭合；
+3. 官方 Blaze 组装方案的 ABI crosswalk 基础行可作为 custom 接线的参照；
+4. `native_gaps` 已列明 Blaze 无法覆盖的需求项（无 V+C prologue Kernel、无 AIV→L1→AIC B 路径、无 WeightQuantMatmulPolicy 特化）；
+5. 本文只设计该增量，不重新作官方路线判定。
+
+本文按以下方式消费基础合同：
+
+| 合同 | 消费方式 |
+|---|---|
+| Scheduler 语义（SWAT 蛇形 + 尾块） | **preserved**：直接复用官方 Scheduler，不修改 |
+| A 侧搬运路径（GM A → L1 → L0A） | **preserved**：与官方 MatMul 一致 |
+| L0C → GM Fixpipe 输出 | **preserved**：与官方 MatMul 一致 |
+| BlockMmad | **replaced**：特化为 WeightQuantMatmulPolicy 版本，B 从 L1 读取（非 GM） |
+| Kernel | **replaced**：自定义 mixed Kernel（AIC BlockMmad + AIV Prologue） |
+| Prologue | **added**：新增层（VF 反量化 + UB 管理 + L1 写入 + CV 同步） |
+
+不得静默改变基础 MatMul 的 A 侧数学语义、Scheduler 语义或 L0C 输出生命周期。
+
+### 3.3 兼容性和 custom 授权
+
+按顺序比较：
+
+1. `matmul_base_analysis` 已调查的官方 Blaze 库事实是否提供 V+C prologue Kernel 或 AIV→L1→AIC B 路径；
+2. `native_gaps` 是否能在不改变需求合同的前提下由本场景增量闭合；
+3. 只有明确缺失且修改范围可隔离时，才授权项目内 Block层、Kernel层或 Prologue 层 custom 文件；
+4. 每个 custom 授权必须记录来源、首个修改点、保留不变量、ABI 边界和验证门禁。
+
+`blaze_custom` 是本场景的定制路线。Asset（`weight_quant_matmul_kernel.h`、`weight_quant_matmul_block_mmad.h`、`dispatch_policy.h`、`weight_quant_tiling.h` 等）只能是 DESIGN 明确授权的可选结构起点，不能证明公式、dtype、layout、slot、同步或支持范围。复制后必须按当前 ABI/公式/API 重写和验证。
+
+## 4. 三层增量合同
+
+### 4.1 Block层
+
+按 [V+C 同步与 L1 布局专题](vc-sync-and-l1-layout-design.md) 冻结：
+
+- `WeightQuantMatmulPolicy<NO_FULL_LOAD_MODE>` 特化的 SFINAE 约束和 source_ref；
+- B 从 L1 读取（非 GM），跳过 GM→L1 B 搬运的修改点和保留不变量；
+- L1 布局：lower half [B0|A0], upper half [B1|A1], bias at tail 64-byte aligned；
+- BiasType 一致性合同（GM/L1/BT/Tiling 四处一致）；
+- 分形轴对齐约束（transB=true: N%16==0; transB=false: K%16==0）；
+- 使用官方 Scheduler（`MatmulSwatScheduler`）或 custom Block 的证据和授权范围。
+
+每个新增或替换的接线必须写入 `abi_crosswalk_delta`，并引用对应 `matmul_base_analysis.abi_bindings[]` 的 `kernel_abi_contract`/签名骨架和 `base_design_binding_ref`。
+
+### 4.2 Kernel层
+
+按 [V+C 同步与 L1 布局专题](vc-sync-and-l1-layout-design.md) 冻结：
+
+- concrete mixed Kernel 入口（`__global__ __aicore__ __mix__(1,2)`）、AIC/AIV 角色；
+- AIC 侧：BlockMmad + Scheduler 初始化和 K 循环；
+- AIV 侧：Prologue 初始化、UB 管理、VF 反量化、L1 写入和 CV 同步；
+- CV 同步：HardEvent flag 配对、首轮预置、K-loop 内交替、final drain 消费剩余；
+- slot 数、flag ID、pipe 和 producer/consumer 的当前 witness 事实；
+- Params/TilingData、Wrapper 和 Launcher 的新增 ABI。
+
+每个新增或替换的接线必须写入 `abi_crosswalk_delta`，并引用对应基础 binding 的 `kernel_abi_contract`/签名骨架和 `base_design_binding_ref`。本文不允许因 V+C 融合需要重排、重命名或重新解释基础 MatMul 的 A 侧 GM 参数；需要改变基础 ABI 时回通用 Step 3。
+
+ratio、flag ID、bridge 等只能来自当前 witness；历史设备记录必须同时绑定同一 Investigation、Blaze 组装方案、构建和验证范围才能复用。
+
+### 4.3 Prologue层
+
+按 [VF 反量化链路专题](prologue-vf-dequant-design.md) 冻结：
+
+- B 输入 dtype（int8/fp8_e4m3fn/fp8_e5m2）、B_dequant 输出 dtype（bf16/fp16）和 Cast 链（见专题 §3 已验证链路表）；
+- 每步 Cast 的 CastTrait、LoadDist、StoreDist 配置（从 asc-devkit API 文档确认，编译+精度验证）；
+- `__simd_vf__` + `asc_vf_call` 三层调用结构和参数打包 struct；
+- 按 BType 的 `if constexpr` 分支选择中间寄存器类型和 Cast 链；
+- UB ping-pong 布局：[bIn|bOut|scale|offset] × 2 half；
+- UB 空间约束公式和 scale/offset 加载时机；
+- hasOffset 的 `if constexpr` 编译期分支；
+- Prologue K-L1 循环与 AIC K 循环的对应关系；
+- CV 同步的 AIV 侧 wait/set 交替。
+
+每路 operand 和中间值必须按自己的 dtype/alignment 计算 UB 空间。不得把整块 UB 同时分配给多个 buffer，或从 Asset 继承固定容量。
+
+## 5. Tiling/资源/同步合同
+
+按 [Tiling 参数合同专题](weight-quant-tiling-contract.md) 冻结：
+
+- TilingData 逐字段语义、单位、合法域和 consumer 映射；
+- Tiling Engine（`WeightQuantTilingSwat`）的入口签名和对齐校验逻辑；
+- Tiling 与 BlockMmad/Prologue 的空间一致性（L1 bias 尾部、L0C 双缓冲、UB 约束、L1 总空间）；
+- UB 空间约束公式必须按当前 B dtype 参数化，不得硬编码 int8 系数；
+- Tiling Engine 的 GetTilingData 签名必须接受 weightElemBytes 和 dequantBElemBytes 参数；
+- DESIGN 必须冻结当前项目的 weightElemBytes 值（由 B dtype 决定）；
+- 分形轴对齐校验（transB=true: N%16==0; transB=false: K%16==0）；
+- transB=true 时尾轮 N 方向不切分；
+- host Tiling 策略：复用 Asset Engine（逐字段兼容后）、固定合法值或独立计算。
+
+Tiling/Params 字段、同步事件和资源约束必须与 Block层、Kernel层和 Prologue层 delta 的字段交叉一致。不一致时回 Step 3 修正。
+
+## 6. 场景验证增量
+
+使用 [精度诊断专题](pitfalls-and-diagnosis.md) 将场景增量写入 DESIGN：
+
+| 模式 | 隔离目标 |
+|---|---|
+| A-only-MMAD | AIC 侧 MMAD（使用预反量化 B_dequant 作为输入） |
+| Dequant-only | AIV 侧反量化（零 MMAD，验证 VF Cast 链） |
+| Full | 完整 V+C（AIV 反量化 + AIC MMAD + CV 同步） |
+
+具体 dtype、shape、transB、hasOffset、hasBias、重复次数和阈值由需求与 DESIGN 冻结。至少包含：
+
+- 逻辑输入、物理转换、CPU Golden（bf16 精度）和全元素非有限值门禁；
+- 每个声明支持的 transB/hasOffset/hasBias 组合及 alignment/tail 边界；
+- 单变量负/正对照，未得到两者时不得宣称根因；
+- 清理临时诊断注入、Dump 和诊断入口后的 Full 回归；
+- 一个 C+V epilogue 需求的负向路由检查，证明其不命中本场景。
+
+Step 3 只能记录 `planned/unverified`。任何 `device_verified` 结论必须引用与当前 Investigation、Blaze 组装方案、构建和测试范围一致的外部验证记录。
+
+## 7. 输出、合并与门禁
+
+DESIGN 的场景合同必须输出：
+
+```text
+selected_scenario: weight-dequant-prologue-fusion
+registry_entry_source
+design_guide_source
+development_guide_source
+consumed_contracts
+preserved_contracts
+replaced_contracts
+added_contracts
+required_investigation_fact_refs
+dependency_skills
+dependency_skill_evidence
+formula_and_interface_delta
+formula_and_dequant_contract
+kernel_and_layer_contract
+block_layer_delta
+kernel_layer_delta
+prologue_layer_delta
+final_interface_delta
+abi_crosswalk_delta
+tiling_resource_data_sync_contract
+tiling_resource_data_sync_delta
+customization_scope
+scenario_validation_additions
+scenario_unsupported_boundary
+```
+
+本场景用以下关系满足通用场景合同：`formula_and_interface_delta` 由 `formula_and_dequant_contract` 和 `final_interface_delta` 展开；`kernel_and_layer_contract` 由 Block层、Kernel层和 Prologue层 delta 展开；`tiling_resource_data_sync_contract` 由 `tiling_resource_data_sync_delta` 展开。
+
+合并顺序固定为：
+
+```text
+requirements
+  -> operator interface
+  -> matmul_base_analysis
+  -> abi_bindings[] within matmul_base_analysis
+  -> scenario delta
+  -> final operator/kernel/resource/validation contracts
+```
+
+本场景是冲突 owner：能由已闭合证据解决的冲突必须写明保留/替换关系；需要新 Blaze 源码事实时回 Step 2，需要改变需求/接口/候选时回通用 Step 3。禁止循环"校正"或现场实验。
+
+DESIGN 冻结前不得读取开发指导正文。场景合同与通用最终合同闭合后，Step 3 写入 `implementation_route: blaze_custom` 与唯一 `selected_scenario`，再读取[场景开发指导](weight-dequant-prologue-fusion-development.md)编译项目 `operators/<operator_name>/docs/PLAN.md`。PLAN 未完整覆盖本场景 required 方法时，回 Step 3 修正，不交给实施阶段。

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

@@ -0,0 +1,232 @@
+# Weight-Dequant Prologue Fusion 开发指导
+
+本文是 Step 3 在场景 DESIGN 冻结后编译项目 `operators/<operator_name>/docs/PLAN.md` 的方法输入，不是 Step 4 的独立设计入口。本文不重新匹配场景、选择 MatMul Blaze 组装方案、选择 Block/Kernel/Prologue 组件、改变支持范围或补充 DESIGN；实施阶段按 `operators/<operator_name>/docs/DESIGN.md`/`operators/<operator_name>/docs/PLAN.md` 实现，并可在 `<project-root>/operators/<operator_name>/` 内为闭合设计补充修复步骤。
+
+**当前支持范围**：本场景偏重 perchannel 量化模式（scale/offset 按 N 维广播），不支持 pergroup 量化。weight dtype 支持 int8 和 fp8（fp8 的 Cast 链路见 [VF 反量化链路专题](prologue-vf-dequant-design.md) §3.1）。
+
+## 目录
+
+1. PLAN 编译门禁
+2. 阅读与依赖清单
+3. 有序动作规则
+4. 接线和项目文件合同
+5. 验证、交付与清理
+6. 合规映射和回退
+
+## 1. PLAN 编译门禁
+
+Step 3 读取本文前必须确认：
+
+```text
+implementation_route: blaze_custom
+selected_scenario: weight-dequant-prologue-fusion
+matmul_base_analysis: present
+matmul_base_analysis.abi_bindings[]: source_backed_and_closed_for_consumed_partitions
+abi_crosswalk_delta: source_backed_and_closed
+design_plan_generation_phase: after_design_freeze
+```
+
+并且：
+
+- DESIGN 已冻结唯一首选、公式/反量化合同、三层增量（Block层替换 + Kernel层替换 + Prologue层新增）、Tiling/资源/同步、customization scope 和验证合同；`abi_crosswalk_delta` 只追加额外 operand（B/scale/offset/bias）、B_dequant 中间值、Prologue Params、Wrapper 或同步接线，且每行具有 `delta_crosswalk_row_id` 并引用 `base_design_binding_ref` 和基础 MatMul `crosswalk_row_id`；
+- DESIGN 的 `dependency_skills` 与 `dependency_skill_evidence` 已冻结，覆盖当前首选路线的根入口、必要叶子及 API/路线证据；
+- 根 `ops-tensor` 和 Blaze skill Asset 原文件始终只读；项目内官方副本只允许执行 PLAN 登记的缺失目录 create-only 原样物化，物化后只读；
+- 无决定性 unknown、TBD、未选择分支、Grouped 基础分区缺口或要求 Step 4 决策的字段。
+
+失败时回 Step 3，不生成可执行 PLAN；不得把本文默认值或历史实现写入可执行 action。
+
+## 2. 阅读与依赖清单
+
+Step 3 根据首选 DESIGN 生成 PLAN `reading_manifest` 作为初始阅读基线。初始资料应绑定 `read_before_action_ids` 和 action `source_refs`；未激活资料写 N/A 或不登记，Step 4 可按实际实现和错误证据读取必要资料，但不能据此改变设计。
+
+| 设计合同 | PLAN 必读来源 | 条件 |
+|---|---|---|
+| Block层 delta | [V+C 同步与 L1 布局专题](vc-sync-and-l1-layout-design.md)、Investigation 指定的 concrete source locations | 使用/扩展 BlockMmad 特化 |
+| Kernel层 delta | [V+C 同步与 L1 布局专题](vc-sync-and-l1-layout-design.md)、实际 mixed Kernel/同步定义 | 存在 AIC/AIV 协作和 CV 同步 |
+| Prologue层 delta | [VF 反量化链路专题](prologue-vf-dequant-design.md)、[Prologue UB 布局专题](prologue-ub-layout-design.md) | 使用 VF 反量化 prologue |
+| Cast API | DESIGN `dependency_skills` 记录的 ascendc-api-best-practices 根入口和必要叶子 | 使用 VF Cast API |
+| RegBase | DESIGN `dependency_skills` 记录的 ascendc-regbase-best-practice 根入口和必要叶子 | 使用 RegBase VF 反量化 |
+| Tiling | [Tiling 参数合同专题](weight-quant-tiling-contract.md)、[Tiling 方法](../../kernel-design/tiling-selection.md) | 按 DESIGN 选择所需章节 |
+| Launcher | [Launcher 方法](../../launcher/launcher-development.md) | 按 DESIGN 选择所需章节 |
+| Event/pipe | [同步方法](../../fundamentals/blaze-sync-patterns.md) 和当前 CANN 实际头文件 | DESIGN 激活相关同步 |
+| Layout 边界 | [Layout 支持范围专题](layout-variant-boundary.md) | 确认支持域和拒绝域 |
+| 诊断 | [精度诊断专题](pitfalls-and-diagnosis.md) | 所有本场景实现 |
+
+PLAN 先登记 DESIGN `dependency_skills` 中的根入口，再登记当前首选路线需要的叶子。`reading_manifest` 只登记当前首选路线的初始资料，不能把全目录一股脑列入。
+
+## 3. 有序动作规则
+
+Step 3 将下列稳定动作类别实例化为 PLAN 的 `ordered_actions`。每个初始动作必须含 DESIGN refs、source refs、计划目标文件、前置、产物、checkpoint 和 failure rollback。
+
+### 3.1 来源与项目副本
+
+1. 核对 DESIGN/Investigation 与当前 Blaze 源码版本的抽象一致性。
+2. 对 DESIGN 选择的官方组件（Scheduler、A 侧搬运路径等 preserved 合同）登记 read-only 来源；满足合同时直接引用，不创建 custom 副本。
+3. 只有 `customization_scope` 明确授权时，登记从具体来源复制到项目目标文件并适配的 action，记录首个修改点和必须保持的不变量。
+4. 只有 DESIGN 明确授权结构起点时，才可复制以下 Asset 到项目文件；Asset 原文件只读，复制后必须按当前 ABI/公式/API 重写和验证：
+   - `assets/blaze_custom/kernel/weight_quant_matmul_kernel.h`（场景核心：V+C mixed Kernel）
+   - `assets/blaze_custom/block/weight_quant_matmul_block_mmad.h`（场景核心：B 从 L1 读取的特化 BlockMmad）
+   - `assets/blaze_custom/policy/dispatch_policy.h`（场景核心：WeightQuantMatmulPolicy 定义）
+   - `assets/op_tiling/weight_quant/weight_quant_tiling_data.h`
+   - `assets/op_tiling/weight_quant/weight_quant_tiling.h`
+5. 以下 Blaze 组件由 asset 代码直接 include 引用，不需复制到项目：
+   - `blaze/gemm/utils/common_utils.h`（MNK_M/N/K/B、CeilDiv、CeilAlign、FINAL_ACCUMULATION 等）
+   - `blaze/gemm/utils/layout_utils.h`（IsTrans、IsWeightNz）
+   - `blaze/gemm/block/block_scheduler_matmul_swat_with_tail_split.h`（SWAT Scheduler）
+6. 不复制整个 Blaze，不通过 include 顺序覆盖官方 specialization，不创建项目根之外或 DESIGN forbidden scope 内的目录。
+
+### 3.2 Block层动作
+
+按 DESIGN 冻结的 Block delta 实例化：
+
+- `WeightQuantMatmulPolicy<NO_FULL_LOAD_MODE>` 特化绑定和 SFINAE 约束；
+- B 从 L1 读取（非 GM）的修改点：跳过 GM→L1 B 搬运，BlockMmad 从 L1Params 提供的 B_dequant 地址读取；
+- L1 布局：lower half [B0|A0], upper half [B1|A1], bias at tail 64-byte aligned；
+- BiasType 一致性核对（GM/L1/BT/Tiling 四处）；
+- 分形轴对齐约束校验；
+- 官方 Scheduler（`MatmulSwatScheduler`）的直接引用和绑定；
+- 结构/ABI 静态检查及必要的单变量正负对照。
+
+未授权 custom Block 时只登记官方组件绑定和核对 action，不生成修改动作。
+
+### 3.3 Kernel层动作
+
+按 concrete witness 实例化：
+
+- mixed Kernel entry（`__global__ __aicore__ __mix__(1,2)`）、AIC/AIV 角色和 ratio；
+- AIC 侧：BlockMmad + Scheduler 初始化、K 循环和 L0C→GM 输出；
+- AIV 侧：Prologue 初始化、UB 管理、VF 反量化、L1 写入；
+- CV 同步：flag 预置（首轮）、K-loop 内 wait/set 交替、final drain 消费剩余；
+- Block/Prologue、Params/TilingData、Wrapper 的类型接线；
+- DESIGN 已证明必要的同步事件配对及负向对照。
+
+所有涉及新增 operand（B/scale/offset/bias）、B_dequant 中间值、Prologue Params、Wrapper、Kernel entry 或同步的动作必须引用由 `base_design_binding_ref` 选定的 `matmul_base_analysis.abi_bindings[]` 中 `kernel_abi_contract`/`abi_crosswalk` 与对应 `abi_crosswalk_delta` 行；Wrapper、Kernel entry 或 Launcher 启动绑定还必须引用同一 binding 的 `source_backed_signature_skeleton`。不通过融合动作重新解释基础 MatMul 的 A 侧 GM 参数。
+
+不得从专题或历史实现补入固定 ratio、flag ID 或 bridge。实现发现调用点不一致时回 Step 2/3，不临时改 DESIGN。
+
+### 3.4 Prologue层动作
+
+只实例化 DESIGN 的唯一首选路线：
+
+- B 输入 dtype → B_dequant 输出 dtype 的 Cast 链（按 BType 分支选择，见 [VF 反量化链路专题](prologue-vf-dequant-design.md) §3 已验证链路表和 §3.1 实践参考）；
+- 每步 Cast 的 CastTrait、LoadDist、StoreDist 配置从 asc-devkit API 文档确认并经编译+精度验证；
+- `static constexpr` 声明形式与源码一致；
+- UB ping-pong 布局：[bIn|bOut|scale|offset] × 2 half 的字节范围和对齐；
+- UB 空间约束公式验证；
+- scale/offset 加载时机（首轮 K-L1 迭代加载，后续复用）；
+- hasOffset 的 `if constexpr` 编译期分支；
+- Prologue K-L1 循环与 AIC K 循环的对应关系；
+- CV 同步的 AIV 侧 wait/set 交替。
+
+Prologue 层不形成可切换的备选分支；备选只留在 DESIGN，PLAN 不自动切换。
+
+建议将 Prologue 的 `operator()` K 循环体拆分为三个无返回值、不含同步的纯数据操作方法，同步逻辑全部写在 `operator()` 中显式排列：
+
+- **`LoadGM2UB`** — GM→UB 搬运 B/scale/offset，通过出参返回 UB 地址
+- **`DequantVF`** — 调用 `asc_vf_call` 执行 VF 反量化，通过出参返回 bOut 地址
+- **`StoreUB2L1`** — UB→L1 搬运（使用 `copy_ubuf_to_cbuf` 显式指定 srcGap=1 解除 bank 冲突）
+
+`operator()` 只负责在三个阶段之间排列 `WaitFlag`/`SetFlag`/`CrossCoreWait`/`CrossCoreSet` 同步，使数据流和同步逻辑一目了然。
+
+### 3.5 Tiling、Params、Wrapper 和 Launcher
+
+按以下单向接线形成 action：
+
+```text
+project host Tiling
+  -> TilingData
+  -> Scheduler/Block/Prologue Params
+  -> concrete Kernel type and entry
+  -> Wrapper/build target
+  -> Launcher buffers and arguments
+```
+
+- 先逐字段验证复制后的 Blaze skill Tiling Engine 与当前 Scheduler/Block/Prologue Params 合同兼容；只有全部语义/单位/合法域一致才复用或最小适配。
+- 将 Tiling Engine 的 `elemBytesB()`/`elemBytesA()`/`elemBytesDequantB()` 从 `static constexpr` 改为 Args 成员字段，由 `GetTilingData` 新增参数 `weightElemBytes` 和 `dequantBElemBytes` 传入。
+- 将 `CalL1AndUbTiling()` 中的魔数 `6UL` 替换为 `NUM_TWO * (args_.weightElemBytes + args_.dequantBElemBytes)`；逐字段验证参数化后的 Tiling Engine 与各 dtype 的 UB 空间约束公式一致。
+- 不能复用但 device 合同已闭合时，为对应 demand partition 实例化返回固定合法控制值的项目 Tiling action。
+- 需要重划 partition、新 specialization 或未知合法域时回 Step 2/3；不能让 Step 4 猜值。
+- Launcher 只执行设备 Kernel 和输出结果；逻辑输入、物理转换、CPU Golden 和比较由 PLAN 指定的 host/Python 产物负责。
+- 不预设固定工程树、脚本数量或文件名；PLAN 的 `target_file_manifest` 提供初始项目文件，实施阶段可在 `<project-root>/operators/<operator_name>/` 内补充实现文件，更新 PLAN 第 2 章并在第 11 章记录实际路径。
+- Tiling、Wrapper、Launcher 和 buffer action 必须把额外 operand（B/scale/offset/bias）/B_dequant 中间值的物理字节、offset 单位、Params、workspace、grid/usedCore、entry 绑定和设备消费者映射回 `abi_crosswalk_delta`；任一项缺失时回 Step 3，不启动 Kernel。
+
+### 3.6 数据、诊断和验证入口
+
+实例化：
+
+1. 逻辑输入和 deterministic seed；
+2. 每个 Tensor 的逻辑到物理转换、padding/packing/broadcast 映射；
+3. 与 DESIGN 公式/dtype 顺序一致的 CPU Golden（bf16 精度运算）；
+4. A-only-MMAD、Dequant-only、Full 三模式；
+5. transB、hasOffset、hasBias 的实际激活子集；
+6. int8 边界值（-128, 127）、alignment/tail 和重复运行；
+7. 诊断开关、额外输出和 Dump 的清理 action。
+
+## 4. 接线和项目文件合同
+
+PLAN 的 `target_file_manifest` 应逐文件记录初始目标的 `create/copy_and_adapt/modify/delete/read_only/forbidden`。至少覆盖当前项目预期需要的：
+
+- Kernel/Wrapper 和可选 custom Block/Kernel/Prologue；
+- TilingData、host Tiling、Params 和构建接线；
+- Launcher 及其 ABI/Buffer 接线；
+- 逻辑数据、物理转换、Golden 和比较入口；
+- 模式分发、诊断、验证和交付产物。
+
+这些是角色，不是固定文件树。PLAN 初始文件必须属于 DESIGN `allowed_change_scope`，并记录为以 `operators/<operator_name>/` 开头的项目相对路径；实施阶段新增文件只能位于当前 `operator_root`，必须避开 DESIGN `forbidden_change_scope`，更新第 2 章并追加第 11 章。根 `ops-tensor`、Skill Asset 原文件、当前 `operator_root` 之外的路径、未注册 custom 层和无关用户文件必须列为 read_only/forbidden；项目内官方副本已存在时列为 `read_only`，缺失时先列为 `create`，完成原样物化和同源核对后转为 `read_only`。
+
+`implementation_wiring_contract` 必须能从最终 operator interface 一路追到每个文件和参数，并显式保留基础 ABI 与场景增量的边界：
+
+```text
+logical operand
+  -> physical buffer
+  -> Launcher argument
+  -> Wrapper argument
+  -> Kernel GM parameter
+  -> Params/Tiling field
+  -> Block/Kernel/Prologue consumer
+  -> output buffer and Golden comparison
+```
+
+基础 MatMul 行必须引用与其 `design_binding_ref` 对应的 `matmul_base_analysis.abi_bindings[].abi_crosswalk` 和 `crosswalk_row_id`；只有本场景新增/替换的行写入 `abi_crosswalk_delta`，并写明 `delta_crosswalk_row_id`、`base_design_binding_ref` 和 `base_crosswalk_row_refs`。每行都要映射到 action、checkpoint 和 source ref，不能用泛化接线图替代。
+
+## 5. 验证、交付与清理
+
+PLAN checkpoints 至少包括：
+
+1. source/ABI/模板实例化静态核对，包括基础 ABI、场景 delta、物理字节/offset、TilingData、workspace、grid/usedCore、Wrapper/entry 和设备消费者；
+2. 分层构建和最小功能运行；
+3. 三模式（A-only-MMAD、Dequant-only、Full）按最早失败域定位；
+4. 每个声明支持的 transB/hasOffset/hasBias 组合、dtype、shape/alignment/tail；
+5. CV 同步的 flag 预置/交替/final drain 用例；
+6. required 单变量负/正证据；
+7. 非有限值和 DESIGN 阈值门禁；
+8. 清理临时诊断后重新构建并执行 Full 回归；
+9. 最终 Asset/官方源码只读、交付件和支持边界审计。
+
+`deliverable_manifest` 只列当前项目必需产物。`cleanup_contract` 必须覆盖 Dequant-only/A-only 诊断注入、故障开关、额外 Kernel entry/Params、Dump、临时数据、日志和构建产物；清理后回归未通过时不得交付。
+
+## 6. 合规映射和回退
+
+PLAN 的 `scenario_guidance_compliance` 必须把本文每个激活要求映射到：
+
+```text
+DESIGN contract ID
+reading_manifest ID
+ordered_action ID
+checkpoint ID
+deliverable/cleanup ID
+or evidence-backed not_applicable
+```
+
+每个激活的 `abi_crosswalk_delta` 行都必须映射到基础 ABI ref、初始 action、checkpoint 和 source ref。未映射 required 设计要求、只写"参见场景指导"或留下待选分支时，PLAN 为 blocking；实现阶段新增的项目文件和修复步骤不要求回写这组映射。
+
+| 发现的问题 | 回退目标 |
+|---|---|
+| Blaze 源码版本不一致 | Step 1 |
+| Blaze 源码类型链、Params/API/物理事实被推翻或缺失 | Step 2，再重做 Step 3 |
+| DESIGN 首选、范围、场景合同或设计边界不完整 | Step 3 DESIGN |
+| 本文无法表达必要 PLAN 动作/门禁 | Blaze skill 场景维护；修订指导后重新编译 PLAN |
+| 实现或验证推翻设计前提 | Step 3；需要新 Blaze 源码事实时先 Step 2 |
+| 普通编码、构建或验证错误 | Step 4 在项目根内持续诊断、修复和重跑；只有推翻设计前提才回 Step 3 |
+
+Step 4 的规范性输入只有当前项目的 DESIGN 和 PLAN。它以 PLAN 登记资料为起点，也可以读取本文或其他相关资料诊断和实现，但不能据此重新匹配场景、生成新的设计路线、切换备选或扩大支持范围。