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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/reading/kernel-execution-units.md

@@ -0,0 +1,189 @@
+# 核内执行单元阅读参考
+
+这份文档不是某一版 dispatch/combine 的实现说明，而是给阅读类 agent 用的“核内执行单元识别规则”。目标是回答：看到 AscendC 代码时，怎样基于官方架构定义，再结合代码证据判断 `Scalar`、`MTE`、`AIV`、`AIC` 分别在做什么。
+
+## 官方依据
+
+这部分优先依据昇腾官方文档，而不是经验推测：
+
+- 抽象硬件架构：
+	- https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/programug/Ascendcopdevg/atlas_ascendc_10_0015.html
+- 硬件实现与基本架构：
+	- https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/programug/Ascendcopdevg/atlas_ascendc_10_0008.html
+
+官方文档给出的稳定结论有：
+
+- `Scalar`：执行地址计算、循环控制等标量计算工作，并把向量计算、矩阵计算、数据搬运、同步指令发射给对应单元执行。
+- `Vector`：负责执行向量运算。
+- `Cube`：负责执行矩阵运算。
+- `DMA / MTE`：负责数据搬运，包括 Global Memory 和 Local Memory 之间、以及不同层级 Local Memory 之间的数据搬运。
+- 在具体硬件实现里：
+	- `MTE2` 负责 `GM -> {L1, L0A/B}` 和 `GM -> UB` 这类搬运。
+	- `MTE3` 负责 `UB -> GM` 这类搬运。
+- 典型向量数据流是：`GM -> UB -> Vector -> UB -> GM`。
+- 典型指令流是：`Scalar` 读取指令并把 Vector / Cube / MTE 指令发射到各自队列，不同指令序列可并行执行；跨序列依赖通过同步机制控制。
+
+因此，阅读 agent 在识别执行单元职责时，应先服从这些官方定义，再用代码去定位“当前这段逻辑落在哪个官方定义的单元上”。
+
+## 代码映射依据
+
+在官方定义已经明确之后，再用下面 3 类代码证据把职责落到具体代码段：
+
+1. 原语名字本身
+
+- `DataCopy` / `DataCopyPad` / `DataCopyExtParams`：按照官方 DMA / MTE 定义，优先判为搬运路径。
+- `Cast` / `Add` / `Mul` / `Muls` / `Sum` / `ReduceSum` / `CompareScalar` / `Select` / `Exp`：按照官方 Vector 定义，优先判为向量计算路径。
+- `SyncFunc<MTE2_V>`（sample 自定义封装，等价于官方 `SetFlag<HardEvent::MTE2_V>(FetchEventID<MTE2_V>()) + WaitFlag<MTE2_V>(id)`）、`SyncFunc<V_S>`、`SyncFunc<S_MTE3>`：事件名直接暴露了"哪个执行单元的结果要交给哪个执行单元"。
+- `PipeBarrier<PIPE_V>`、`PipeBarrier<PIPE_MTE3>`、`PipeBarrier<PIPE_ALL>`：说明当前代码正在显式处理同核不同 pipe 的可见性与串接。
+
+2. 数据流方向
+
+- 如果某段代码把数据从 GM / window / 状态区搬到 `LocalTensor` / UB，再靠事件同步交给后续计算，这段首先归到官方定义中的 DMA / `MTE` 搬运路径。
+- 如果某段代码在 `LocalTensor` 上做 cast、逐元素算子、mask、reduce，再把结果交给 `Scalar` 读取或交给 `MTE3` 写回，这段首先归到官方定义中的 `Vector` 路径。
+- 如果某段代码主要在做分支判断、区间计算、状态轮询、地址偏移、ready 判定、循环推进，而不是做大块 tensor 算子，这段首先归到官方定义中的 `Scalar` 路径。
+
+3. 任务类型和分支
+
+- 如果入口显式写了 `ASCEND_IS_AIV`、`KERNEL_TYPE_AIV_ONLY`，说明主热路径至少是 AIV 可见的；这时不要默认 `AIC` 一定参与。
+- 只有当代码里真的出现 cube / matmul / 专门走 `AIC` 的算子或任务类型证据时，才把某段路径归到 `AIC`。
+- 如果图里画了 `AIC`，必须能在代码里指出它参与的真实算子或真实路径；否则应明确写“当前主热路径未见 AIC 参与”。
+
+## 各执行单元的官方职责与阅读落点
+
+### Scalar
+
+官方定义：
+
+- 执行地址计算、循环控制等标量计算工作。
+- 把向量计算、矩阵计算、数据搬运、同步指令发射给对应单元执行。
+
+阅读时常落在：
+
+- 区间切分
+- 地址和偏移计算
+- ready / not ready 判断
+- while / for 轮询推进
+- 条件路径选择
+- 读取少量标量结果并决定下一步控制流
+
+常见代码信号：
+
+- `if` / `while` / `for`
+- `GetValue()` / `SetValue()` 读取或写少量标量
+- 对 `tokenIndex`、`slotIndex`、`begin/end`、`count` 的控制逻辑
+
+### MTE2 / MTE3
+
+官方定义：
+
+- `MTE` 属于搬运单元。
+- 在具体硬件实现里，`MTE2` 负责 `GM -> UB` 等搬入路径，`MTE3` 负责 `UB -> GM` 等搬出路径。
+
+阅读时常落在：
+
+- GM / window / 状态区 与 UB 之间的数据搬运
+- 把向量结果写回 GM / window / 状态区
+
+常见代码信号：
+
+- `DataCopy` / `DataCopyPad`
+- `DataCopyExtParams` / `DataCopyPadExtParams`
+- `SetFlag<HardEvent::MTE2_V>` / `WaitFlag<HardEvent::MTE2_V>`（或 sample 中的封装 `SyncFunc<MTE2_V>`）、`SetFlag<S_MTE2>` 等：跨 pipe 事件同步
+
+阅读时的映射规则：
+
+- `GM -> UB` 优先记到 `MTE2`
+- `UB -> GM` 优先记到 `MTE3`
+- 如果代码只写了 `DataCopyPad`，但上下文是“从 GM 读入 LocalTensor”，就按 `MTE2` 画；如果上下文是“把 LocalTensor 写回 GM”，就按 `MTE3` 画。
+
+### AIV / Vector
+
+官方定义：
+
+- `Vector` 负责执行向量运算。
+- 在具体硬件实现里，Vector 的源数据和目标数据都要求放在 `Unified Buffer` 中。
+- 典型向量数据流是：`GM -> UB -> Vector -> UB -> GM`。
+
+阅读时常落在：
+
+- cast
+- add / mul / reduce
+- mask 处理
+- 向量比较
+- dequant / quant 中的向量部分
+- token 载荷整理和张量级中间结果生成
+
+常见代码信号：
+
+- `Cast`
+- `Add` / `Mul` / `Muls`
+- `Sum` / `ReduceSum`
+- `CompareScalar` / `Select`
+- `Exp` / `Mins` / `GatherMask`
+- `PipeBarrier<PIPE_V>`
+
+阅读时的映射规则：
+
+- 只要是在 `LocalTensor` 上做批量元素级或向量级运算，先归到 `AIV`。
+- 如果一段逻辑包含“先搬入，再在 UB 上一连串算，再把结果写回”，中间那一串通常就是 `AIV` 主体。
+
+### AIC
+
+官方定义：
+
+- `Cube` 负责执行矩阵运算。
+- 在 AI Core 分离模式下，`AIC` 是一组 `Cube Core + Vector Core` 组合中的 `Cube Core`。
+
+阅读时常落在：
+
+- cube / matmul / 矩阵类融合计算
+
+常见代码信号：
+
+- 明确的 cube / matmul 类算子
+- 明确的 `AIC` 任务类型或专门路径
+
+阅读时的映射规则：
+
+- 没看到明确证据，就不要自动把“复杂计算”归到 `AIC`。
+- 许多 MoE dispatch/combine 实现虽然逻辑复杂，但主热路径仍可能只是 `MTE + AIV + Scalar`。
+
+## 怎样从同步原语反推职责边界
+
+同步原语是最稳定的证据之一：
+
+- `SetFlag<MTE2_V>` + `WaitFlag<MTE2_V>`（sample 中封装为 `SyncFunc<MTE2_V>`）：说明"搬入已经完成，接下来向量计算可以消费"。
+- `SetFlag<V_S>` + `WaitFlag<V_S>`：说明"向量结果已经可被标量读取或用于控制判断"。
+- `SetFlag<S_MTE3>` + `WaitFlag<S_MTE3>`：说明"标量已经完成地址/控制决策，接下来可以写回"。
+- `PipeBarrier<PIPE_V>`：说明同核向量阶段之间有真实数据依赖。
+- `PipeBarrier<PIPE_ALL>`：说明当前阶段切换涉及多条 pipe 的整体可见性。
+
+这些判断同样不是拍脑袋得出的，而是因为官方文档明确说明了：
+
+- `Scalar` 会把不同类型指令发射到独立的分类序列。
+- 不同指令序列之间可以并行执行。
+- 跨序列依赖通过同步机制控制。
+- `PipeBarrier` 用于序列内部约束执行顺序，`SetFlag/WaitFlag` 用于序列之间建立同步关系。
+
+所以，阅读 agent 不应该只说“这里有同步”，而应该进一步写出：
+
+- 这是哪两个执行单元之间的交接点
+- 为什么这个交接点存在
+- 它是否切断了原本可重叠的流水
+
+## 给阅读 agent 的落地规则
+
+当 agent 画核内 stream 图时，按下面顺序判断：
+
+1. 先找 `DataCopy*`，标出 `MTE2/MTE3` 主路径。
+2. 再找 `Cast/Add/Mul/Sum/Reduce/Mask`，标出 `AIV` 主路径。
+3. 再找 `if/while/GetValue/SetValue` 和等待判定，标出 `Scalar` 控制路径。
+4. 最后再问一句：代码里有没有明确证据表明 `AIC` 参与；没有就写“未见 AIC 参与”。
+
+## 给文档作者的硬约束
+
+- 不要把执行单元职责写成“我觉得像什么”；先回到官方架构定义，再落到代码。
+- 不要因为图里想凑完整，就默认把 `AIC` 画进去。
+- 不要把“函数名阶段”直接等同于“执行单元职责”。一个函数里常常同时跨 `Scalar`、`MTE`、`AIV`。
+- 不要只写“这里是计算阶段”；要明确是 `AIV` 还是 `AIC`，依据是什么。
+- 不要只写“这里有同步”；要明确是 `MTE2 -> V`、`V -> S`，还是 `S -> MTE3`。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/reading/mega-moe-reading-guide.md

@@ -0,0 +1,123 @@
+# MegaMoE / 融合实现专用阅读指南
+
+在已经确认目标代码属于 mega_moe 或其他 dispatch + expert 计算 + combine 融合实现后，使用这份文档继续做专用分析。
+
+## 适用范围
+
+满足下面任一特征时，优先使用本指南：
+
+- 输入侧沿用 dispatch 风格输入，例如 `x`、`expertIds`、路由索引、topK 元信息，但输出侧直接得到 combine 最终输出，例如 `XOut`、残差、归一化结果。
+- 主入口内同时包含分发、expert 计算或 FFN、聚合回写三类职责。
+- 通信、计算、聚合共享同一套状态区、workspace 或跨阶段缓冲，已经不能拆成两个独立算子来解释。
+- 旧版 `expandX`、`expandIdx`、`epSendCounts`、`epRecvCounts` 等中间量不再完整落成外部接口，而是以内联缓冲或内部协议存在。
+
+## 核心阅读原则
+
+- 先还原真实主控制流，再做职责映射；不要先假设它等于“dispatch 文档 + combine 文档”的简单拼接。
+- 先回答“哪里完成了 dispatch 职责、哪里完成了 expert 计算职责、哪里完成了 combine 职责”，再回答每一段具体怎么实现。
+- 如果融合实现重写了旧版通信协议、状态布局、内存分区，结论必须以当前代码为准，不要用旧版术语硬套。
+- 如果某个阶段被彻底内联，例如旧版 `expandX` 不再落地，而是直接进入 expert 计算，必须明确写“旧中间量被消掉”，以及替代它的新载体。
+
+## 建议先补的信息
+
+这些不是硬前置条件，但会显著提高阅读质量：
+
+- 最终外部接口的输入输出列表。
+- expert 计算主体是什么：FFN、激活、量化、AIC 融合还是其他路径。
+- 旧版 dispatch/combine 哪些接口或中间量仍保留，哪些已经消失。
+- 当前最关心的是通信协议、融合流水、内存排布、分核方式，还是最终输出顺序。
+
+## 融合职责语义
+
+阅读时至少把真实控制流映射成下面 3 类职责，允许一段代码同时承担多类职责：
+
+- 分发职责：路由、目标 expert / rank / slot 计算、输入搬运、远端写入、就绪发布。
+- expert 计算职责：expert 输入组织、GEMM/FFN/激活/量化/反量化/局部融合计算。
+- 聚合职责：按 token 或来源恢复、局部累加、跨核汇总、最终输出回写、附加统计收口。
+
+如果代码里还有独立的重要职责，例如共享 expert、special expert、辅助统计、动态量化、额外残差路径，应单独加第四类或第五类职责，而不是强塞进前三类。
+
+## 必答问题
+
+- 当前实现的真实主入口调用链是什么，哪些子路径是主热路径，哪些是条件路径。
+- dispatch、expert 计算、combine 各自的职责边界在哪里，边界之间靠什么协议衔接。
+- 旧版独立算子里的中间量哪些还存在，哪些被消掉，消掉后由什么缓冲、寄存态、workspace 或状态槽位替代。
+- 通信是“先完整分发再算再聚合”，还是已经和 expert 计算、聚合回写发生重叠。
+- 状态区、workspace、共享区、中间 staging 区分别承担什么职责，为什么这样设计。
+- 核内是谁负责搬运、谁负责向量计算、谁负责 AIC / Cube、谁负责 Scalar 控制；这些单元之间怎样形成融合流水。
+- 分核是按 token、expert、rank、阶段，还是混合切分；哪些边界在不同职责之间共用。
+- 哪些同步是跨职责同步，例如“通信 ready 后立刻驱动 FFN”或“局部聚合完成后再发布最终 ready”。
+- 最终输出顺序由什么决定；如果没有显式 `expandIdx`，恢复原 token 顺序的依据是什么。
+- 哪些差异只是代码组织变化，哪些差异已经改变了协议、正确性约束或性能上限。
+
+## 入口定位
+
+优先定位下面这些角色：
+
+- 初始化入口
+- 主调度或主 `Process()` 入口
+- 路由 / 分发入口
+- 状态发布与状态等待入口
+- expert 输入组织入口
+- expert 计算或 FFN 融合入口
+- 聚合或输出恢复入口
+- 最终输出回写入口
+- 最终统计、性能信息或附加输出收口入口
+
+## 阅读落点
+
+至少找到下面这些代码落点：
+
+- 输入张量、输出张量、workspace、tiling 的基址绑定
+- 路由元信息、slot、rank、expert 映射的生成或消费位置
+- 通信 token 或等价 payload 的写入与读取位置
+- 状态 ready、计数、阶段切换标记的写入和等待位置
+- expert 输入缓冲区、中间结果缓冲区、局部累加缓冲区的组织方式
+- MTE、AIV、AIC、Scalar 各自落在哪些热路径
+- 跨核汇总、前缀和、边界计算或等价输出恢复逻辑
+- 最终输出写回与附加统计收口逻辑
+- 特殊路径，例如量化、shared expert、special expert、copy expert、fallback 路径
+
+## 图表额外要求
+
+在通用方法要求之外，融合实现还要额外保证：
+
+- 跨卡 / 多核总图里明确标出 dispatch、expert 计算、combine 三类职责在时间轴上的重叠关系。
+- 核内 stream 图里明确标出“通信搬运主路径”和“expert 计算主路径”何时交叉、何时等待。
+- 只要正文里要解释 AIC/AIV、MTE/AIV、MTE3/AIV 之间的等待、交棒、pingpong 或跨 lane overlap，就必须补 `gantt`，不能只给一张 `sequenceDiagram`。
+- 对融合实现，默认至少补 2 张 `gantt`：
+	- 一张“按同步点拆开的执行单元掩盖图”，解释 dispatch/GMM1/GMM2/combine send/unpermute 里哪些同步点是强串行边界。
+	- 一张“稳态跨 token / 跨 tile 接力图”，解释在 pingpong、queue 或双缓冲稳定后，哪些 overlap 只发生在不同 lane 之间。
+- 若当前代码只能静态确认第一张图，不能静态确认第二张图，也必须把“不能确认”的原因写出来，而不是直接省略。
+- 如果旧版中间量被消掉，例如 `expandX` 不再落地，图里要直接画出替代它的新缓冲或新依赖边。
+- 如果存在共享状态区或融合控制区，内存排布图里必须单独命名，不要藏在“其他空间”。
+
+## 优化分析清单
+
+这部分比通用方法更偏融合实现热点，至少覆盖：
+
+- 分发结束到 expert 计算开始之间是否存在不必要空泡。
+- expert 计算是否必须等待整批输入 ready，还是可以按 chunk、expert、token 子集推进。
+- expert 计算和聚合是否共享同一缓冲，是否带来额外同步或覆盖风险。
+- 旧版拆成两个算子时存在的串行瓶颈，是否在融合后消失，还是只是被隐藏在新状态协议里。
+- 路由、计算、聚合三段是否共用了过粗的全局同步。
+- 最终输出回写是否重新形成单核或单阶段尾收口。
+- 特殊路径是否污染主热路径，例如 shared expert、量化或异常 fallback。
+
+## 常见高性能关注点
+
+- 通信缓冲、expert 中间区、聚合区是否造成重复搬运。
+- 数据布局是否同时兼顾分发写入、expert 读取和聚合回写，还是只优化了其中一段。
+- 融合后 UB 是否被更高效地复用，还是变成多个阶段争抢同一块空间。
+- Scalar 控制逻辑是否因为融合而显著变重，造成轮询、分支或生命周期管理成本上升。
+- 分核边界是否兼顾通信和计算负载均衡，还是一段均衡另一段失衡。
+- 最终输出顺序约束是否迫使前面已经可并行的阶段重新串行化。
+
+## 结论要求
+
+交付阅读结论时，除通用阅读文档外，还必须单独显式写出：
+
+- 这是一个怎样的融合实现，不再适合被解释成纯 dispatch 或纯 combine 的原因。
+- 当前实现相对旧版拆分实现，最大的协议变化是什么。
+- 当前实现相对旧版拆分实现，最大的性能机会和最大的正确性风险各是什么。
+- 哪些经验可以沉淀回 skill 作为融合实现通用规则。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/samples/build-framework.md

@@ -0,0 +1,177 @@
+# MoE Dispatch/Combine 编译框架特需说明
+
+本文记录 mc2 算子直调工程在编译框架上与普通 AscendC 算子的差异，并沉淀 sample 中可复用的工程 blueprint：host 多卡调用方式、工程编译方式和算子验证链路。
+
+参考工程：`moe_dispatch_direct_invoke_sample/`
+
+## 工程结构差异
+
+与通用单文件 `.asc` 工程不同，mc2 算子直调工程为 `host + kernel` 双层结构：
+
+```
+moe_dispatch_direct_invoke_sample/
+├── CMakeLists.txt          # host 可执行 + kernel 库双目标
+├── build.sh                # 封装 cmake + make
+├── moe_dispatch.cpp        # kernel launch 入口（非 .asc）
+├── include/
+│   ├── tiling_data.h       # HcclA3/A5OpResParam + MoeDispatchTilingInfo
+│   ├── moe_dispatch_base_compat.h  # 平台 compat 层（GetBaseWindAddrByRankId 等）
+│   └── utils.h             # AlignUp / CeilDiv / SyncFunc（SetFlag+WaitFlag 封装）等工具函数
+├── kernel/
+│   ├── moe_dispatch.h      # kernel 主流程
+│   └── mte_dispatch_comm.h # window 地址计算 + 状态写入/等待
+└── test/
+    └── test_moe_dispatch.cpp  # host 测试：HCCL 初始化 + 通信资源 + launch
+```
+
+这份结构的核心价值在于明确工程分层职责：
+
+- host 侧文件负责设备初始化、多卡通信域建立、stream 管理、通信资源创建和 kernel launch
+- kernel 主流程文件负责算子计算本体
+- include 中的 tiling / compat 头文件负责 HCCL 约定结构和平台差异适配
+- test / script 负责结果校验和端到端验证
+
+这几层职责共同构成 mc2 直调工程的基本组织方式。
+
+## CMakeLists.txt 关键差异
+
+### 双目标
+
+```cmake
+# kernel 库（编译为 .so，供 host 调用）
+ascendc_library(ascendc_kernels SHARED moe_dispatch.cpp)
+ascendc_include_directories(ascendc_kernels PRIVATE ${INCLUDE_DIRS})
+
+# host 可执行（链接 HCCL + tiling + platform）
+add_executable(test_moe_dispatch test/test_moe_dispatch.cpp)
+```
+
+### mc2 特殊链接依赖
+
+```cmake
+target_link_libraries(test_moe_dispatch PRIVATE
+    ascendc_kernels
+    tiling_api      # tiling API，提供 GetTilingKey 等
+    platform        # 平台能力查询
+    pthread
+    hccl            # HCCL 核心，提供 HcclAllocComResourceByTiling
+    hccl_fwk        # HCCL 框架层
+    hcomm           # 通信底层
+)
+```
+
+普通 AscendC 算子不需要 `hccl`、`hccl_fwk`、`hcomm`，这三个是 mc2 特有依赖。
+
+### CANN 路径
+
+```cmake
+# 支持两个安装路径
+set(ASCENDC_CMAKE_DIR "${ASCEND_CANN_PACKAGE_PATH}/compiler/tikcpp/ascendc_kernel_cmake")
+if(NOT EXISTS "${ASCENDC_CMAKE_DIR}")
+    set(ASCENDC_CMAKE_DIR "${ASCEND_CANN_PACKAGE_PATH}/tools/tikcpp/ascendc_kernel_cmake")
+endif()
+include("${ASCENDC_CMAKE_DIR}/ascendc.cmake")
+```
+
+### host 侧编译选项
+
+```cmake
+target_compile_options(test_moe_dispatch PRIVATE -O2 -std=c++17 -D_GLIBCXX_USE_CXX11_ABI=0)
+target_compile_definitions(test_moe_dispatch PRIVATE SOC_VERSION="${SOC_VERSION}")
+```
+
+`-D_GLIBCXX_USE_CXX11_ABI=0` 是 HCCL 对 ABI 兼容性的要求，**不要移除**。
+
+## 平台宏处理
+
+`moe_dispatch_base_compat.h` 通过 `__NPU_ARCH__` 在编译期选择 dav-3510 / dav-2201 实现（对应样例结构名 `HcclA5OpResParam` / `HcclA3OpResParam`，A3/A5 为工程惯称）：
+
+```c++
+#if defined(__NPU_ARCH__) && (__NPU_ARCH__ == 3510)
+    using HcclOpParam = HcclA5OpResParam;
+    // dav-3510（Ascend 950PR/950DT）地址实现
+#else
+    using HcclOpParam = HcclA3OpResParam;
+    // dav-2201（Atlas A2/A3 系列）地址实现（默认）
+#endif
+```
+
+**`SOC_VERSION` 控制 `__NPU_ARCH__`**，通过 `-DSOC_VERSION=` 传入编译器。目标 dav-2201（Atlas A2/A3 系列，工程惯称 A3）芯片不需要特殊设置；dav-3510（Ascend 950PR/950DT，工程惯称 A5）需要确认 `SOC_VERSION` 正确。
+
+## Host 侧通信资源创建（mc2 特需）
+
+直调工程 host 侧需显式调用 `HcclAllocComResourceByTiling` 创建通信资源并传给 kernel：
+
+```c++
+// host test/test_moe_dispatch.cpp 的核心流程
+HcclComm comm = ...;                // HCCL 通信域
+void *stream = ...;                 // 当前 stream
+void *mc2Context = nullptr;
+// 创建 MTE 通信资源，返回 mc2Context 指针（内含 window 地址等）
+// 注意：签名是 HcclAllocComResourceByTiling(comm, stream, mc2Tiling, &mc2Context)，
+//       mc2Tiling 传完整 tiling（host 侧指向含 Mc2InitTiling 的 TilingData），
+//       不能只传 &tilingData.mc2CcTiling，也不可省略 stream（与 asc-devkit hccl_mc2.h 一致）。
+HcclAllocComResourceByTiling(comm, stream, tilingData, &mc2Context);
+
+// 将 mc2Context 的地址传给 kernel（作为 GM_ADDR）
+// kernel 中通过 InitHcclContextByAddr(mc2Context, ...) 访问
+```
+
+**与 registry invoke 的区别**：registry 模式下 mc2Context 由框架自动注入；直调模式下必须手动创建和传递，`InitHcclContextByAddr` 内不再调用任何框架接口。
+
+从工程职责看，这一节对应 host 侧多卡调用路径：
+
+- 设备和通信域初始化，拿到 `HcclComm`
+- 基于 tiling 创建通信资源，拿到 `mc2Context`
+- 将 `mc2Context` 和 tiling 一起传给 kernel launch
+- 由 host 测试或运行入口负责同步、回收和结果校验
+
+多卡调用路径本身是 sample 最重要的工程价值之一，不属于隐含在 test 文件中的附带信息。
+
+## 头文件包含顺序
+
+kernel 文件的典型包含顺序：
+
+```c++
+// 优先使用正式安装路径的头，fallback 到本地 compat
+#if __has_include("common/op_kernel/moe_distribute_base.h")
+#include "common/op_kernel/moe_distribute_base.h"
+#else
+#include "moe_dispatch_base_compat.h"
+#endif
+#include "utils.h"
+#include "basic_api/kernel_basic_intf.h"
+```
+
+这个 `__has_include` 保护允许工程同时在 mc2 内部环境（有 `moe_distribute_base.h`）和外部样例工程（只有 compat 层）中编译。
+
+## build.sh 简化流程
+
+```bash
+# build.sh 核心
+cmake -DSOC_VERSION=${SOC_VERSION} -DCMAKE_BUILD_TYPE=Release ..
+make -j$(nproc)
+```
+
+## 验证链路
+
+验证链路包括：
+
+- host 测试入口负责准备输入、初始化 HCCL、launch kernel、回收输出
+- 校验脚本负责将输出结果与预期或基线比较
+- README 或运行说明负责给出多卡启动方式、环境变量和执行命令
+
+这部分属于算子工程交付说明的组成部分。
+
+## 新增或修改算子时的检查清单
+
+- `tiling_data.h` 中 `HcclA3OpResParam` / `HcclA5OpResParam` 结构体字段顺序不能随意调整（与 HCCL ABI 绑定）
+- 新增 tiling 字段加在 `MoeDispatchTilingInfo` 中，不要修改 `Mc2InitTiling` / `Mc2CcTiling`
+- kernel 函数签名修改后，`moe_dispatch.cpp` 和 `test_moe_dispatch.cpp` 需同步更新
+- 链接库版本随 CANN 升级变化时，只需修改 `CMakeLists.txt` 的 `target_link_libraries`
+
+## 下一跳
+
+- 工程文件落点与改动定位：`change-routing.md`
+- 通信资源和地址获取接口：`../api-rules/mte-address-access.md`
+- `samples` 路径入口：`index.md`

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/samples/change-routing.md

@@ -0,0 +1,18 @@
+# MoE Dispatch/Combine 改动定位
+
+当任务已经进入生成 / 改造路径，但还没决定先改哪个文件时，按变化类型定位：
+
+- 构建方式、源文件组织、编译选项变化：先改 `CMakeLists.txt`、`build.sh`
+- host 侧输入输出、tiling、launch 参数、通信资源创建方式变化：先改 `test/test_moe_dispatch.cpp`
+- 通信资源结构体、tiling 字段、kernel 入参语义变化：先改 `include/tiling_data.h`
+- `mc2Context` 字段解释方式、基础地址辅助函数变化：先改 `include/moe_dispatch_base_compat.h`
+- window 布局、状态区布局、状态写入/等待协议变化：先改 `kernel/mte_dispatch_comm.h`
+- 路由规则、slot 计算、发窗组织、输出回搬、`expandIdx` 写回顺序、输出统计变化：再改 `kernel/moe_dispatch.h`
+- kernel 入口签名、模板实例或 launch 包装变化：再改 `moe_dispatch.cpp`
+- 输出结果校验规则变化：最后改 `scripts/verify_dispatch.py`
+
+## 避免以下做法
+
+- 不要跳过样例工程直接从空文件开始写 dispatch 工程
+- 不要一开始同时重写 host、context 辅助层、comm、kernel 全链路
+- 没有明确差异前，不要先改 `kernel/moe_dispatch.h` 主流程

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/samples/combine-dataflow.md

@@ -0,0 +1,144 @@
+# MoE Combine 数据流
+
+这个页面承接 combine 的阶段控制流、槽位语义和聚合闭环；不展开 window 字节布局、地址公式和状态槽大小计算。
+
+## 最小阶段划分
+
+| 阶段 | 输入 | 产出 | 本阶段只回答什么 |
+| --- | --- | --- | --- |
+| 初始化 | EP 参数、`mc2Context`、输出张量 | 上下文、回传地址、聚合输出地址、分核边界 | 回传与聚合地址从哪里来 |
+| 回传发送 | `expandX` `expandIdx` `epSendCounts` | 回程 window 与远端状态 | 如何按 `expandIdx` 恢复来源位置并写回 |
+| 接收等待 | 本地状态区 | 可聚合的完成状态 | 何时本地 token 所需贡献已经收齐 |
+| 本地聚合 | 本地 window、`expertScales` | `x` | 如何恢复原 token 并完成加权求和 |
+
+阶段附加约束：
+
+- 回传阶段遵循“先写数据，再写状态”
+- 等待完成后再清状态，避免旧轮次状态污染下一轮
+- `expandIdx` 必须能唯一定位原始 `(srcRank, srcTokenIdx, srcTopKIdx)`
+
+## 真实接口参数
+
+以下参数直接对齐 `aclnnMoeDistributeCombineGetWorkspaceSize`。
+
+### 输入参数
+
+记号约定：
+
+- `A` 表示 dispatch 侧为本卡接收量预留的最大 token 容量
+- `H_expand` 表示 `expandX` 的单行存储宽度。对普通 dtype，`H_expand = H`；对 `fp4x2` 这类打包存储类型，`H_expand = ceil(H / 2)`
+
+| 参数 | 含义 / 用意 | 逻辑维度 / shape | dtype | 关键约束 |
+| --- | --- | --- | --- | --- |
+| `expandX` | dispatch 传来并经过比如 FFN 计算的 token 特征输入，是 combine 的主数据输入 | 2D，按接口容量预留，常见为 `(A, H_expand)` | `ExpandXType` | 这里只包含特征载荷，不包含三元组附加信息 |
+| `expertIds` | 原始 token 的 topK expert 路由表 | 2D，通常为 `(Bs, K)` | `INT32` | 与 dispatch 输入保持一致 |
+| `expandIdx` | 标识每个有效展开条目的来源 rank、token 和 topK 槽位 | 2D，按容量视角预留为 `(A, 3)`；线性存储时长度至少为 `A * 3` | `INT32` | 每个有效条目固定为 `[srcEpRankId, srcTokenIndex, srcTopKIndex]` |
+| `epSendCounts` | 描述本卡需要回传给 EP 通信域各目标 rank 的 token 数量 | 1D；按 EP rank 维度组织，常见为 `(epWorldSize,)` | `INT32` | 接口语义上与 dispatch 输出的 `epRecvCounts` 完全同构 |
+| `expertScales` | token-topK 维度上的聚合权重 | 通常为 `(Bs, K)` | `FLOAT` | combine 聚合权重 |
+| `xActiveMask` | 有效 token 或路由项的 mask | 1D 或 2D mask，依实现而定 | `BOOL` | 常见有 token 级 mask 和 expert 级 mask 两条路径 |
+| `residualX` | 可选残差输入 | 通常为 `(Bs, H)` | `ExpandXType` | 仅在 combine 带残差融合语义时使用 |
+| `gamma` | 可选归一化权重 | 通常为 `(H,)` 或路径相关 | `ExpandXType` | 仅在 combine 带 RMSNorm / 归一化融合语义时使用 |
+| `sharedExpertX` | shared expert 额外输出输入 | 通常为 `(Bs, H)` | `ExpandXType` | 若存在 shared expert 直加路径，会在最终聚合时累加 |
+| `oriX` | 原始 token 输入 | 通常为 `(Bs, H)` | `ExpandXType` | 若存在 copy expert 或 const expert 路径，常会直接读取 |
+| `constExpertAlpha1` | const expert 的第一组权重 | 通常为 `(constExpertNum, H)` | `ExpandXType` | 仅在 const expert 路径存在时使用 |
+| `constExpertAlpha2` | const expert 的第二组权重 | 通常为 `(constExpertNum, H)` | `ExpandXType` | 仅在 const expert 路径存在时使用 |
+| `constExpertV` | const expert 的常量向量 | 通常为 `(constExpertNum, H)` | `ExpandXType` | 仅在 const expert 路径存在时使用 |
+| `performanceInfo` | 可选性能等待信息输出缓冲 | 路径相关 | `INT32` | 仅在需要性能统计输出时使用 |
+| `groupList` | 预留的 group list 参数 | 路径相关 | 路径相关 | 当前版本通常不支持 |
+| `expandScales` | 与 `expandX` 对齐的权重或量化 scale | 通常按 routed item 对齐 | `FLOAT` | 若启用，必须与 `expandX` 行对齐 |
+| `groupEp` | EP 通信域标识 | 标量属性 | - | 专家并行域 |
+| `epWorldSize` | EP 域内 rank 总数 | 标量属性 | `INT64` / `INT32` | EP 域大小 |
+| `epRankId` | 当前卡在 EP 域中的 rank 编号 | 标量属性 | `INT64` / `INT32` | 当前 rank |
+| `moeExpertNum` | 全局 MoE expert 总数 | 标量属性 | `INT64` / `INT32` | MoE expert 总数 |
+| `expertShardType` | 共享专家卡的部署方式 | 标量属性 | `INT64` / `INT32` | 共享专家部署方式 |
+| `sharedExpertNum` | 共享专家数量 | 标量属性 | `INT64` / `INT32` | 共享专家数量 |
+| `sharedExpertRankNum` | 承载共享专家的 rank 数 | 标量属性 | `INT64` / `INT32` | 共享专家使用的 rank 数 |
+| `globalBs` | EP 域视角下的全局 batch 上界 | 标量属性 | `INT64` / `INT32` | EP 域全局 batch size |
+| `outDtype` | 输出 `x` 的数据类型控制参数 | 标量属性 | `INT64` / `INT32` | 输出 `x` 的数据类型控制 |
+| `commQuantMode` | 通信量化模式 | 标量属性 | `INT64` / `INT32` | 与 dispatch 量化路径配套 |
+| `groupListType` | group list 的格式控制参数 | 标量属性 | `INT64` / `INT32` | 预留参数 |
+
+### 输出参数
+
+| 参数 | 含义 / 用意 | 逻辑维度 / shape | dtype | 关键约束 |
+| --- | --- | --- | --- | --- |
+| `XOut` | combine 聚合后的最终 token 输出 | 2D，通常恢复为 `(Bs, H)` | `ExpandXType` 或量化/输出控制对应类型 | 第 `b` 行对应原始 token 维 |
+| `performanceInfo` | 可选性能等待输出 | 路径相关 | `INT32` | 仅在 `isPerformance` 打开时写回；按来源 rank 做 atomic max |
+
+## 通用控制流
+
+只要 combine 采用“回来源槽位 + 本地等待 + 本地聚合”这类协议，主路径通常可以抽象成：
+
+1. 初始化发送侧和聚合侧所需的基础缓冲
+2. 按 `expandIdx` 把 `expandX` 回传到来源 rank 的 window 槽位，并在对应状态槽发布 ready
+3. 计算或加载 token mask / expert mask，并把 special expert 相关过滤条件融合进有效项集合
+4. 各核按 token 子区间轮询本地状态区，等待该 token 需要的 expert/shared expert 槽位 ready
+5. 状态满足后，从本地 window 读出各 expert 结果，按 `expertScales` 聚合，并叠加 shared/copy/const expert 等额外路径；最后写回 `XOut`
+6. 如果需要性能统计，再把等待信息或附加统计写回对应输出
+
+## 核心约束
+
+- 回传阶段的目标地址必须与 `expandIdx[i] = [srcRank, srcTokenIdx, srcTopKIdx]` 一一对应
+- 若使用 window + 状态协议，通常是“先写来源 rank 的 window 数据区，再写对应状态槽”
+- 等待阶段是按 token 检查本地状态区累计和，不是按整卡一次性 barrier 后再处理
+- 状态满足后立即清该 token 的状态槽，然后进入本地聚合
+- 量化打开时，发送端先量化写 window，消费端再反量化后参与聚合，combine 必须与 dispatch / 通信侧量化布局配套
+- combine 可能同时支持 moe expert、shared expert、zero expert、copy expert、const expert 等多路径；不要把 combine 固化成单一路径乘权求和
+
+## 容量与有效长度
+
+- `expandX` 和 `expandIdx` 采用“最大容量预留 + 实际有效长度由统计张量确定”的使用方式
+- combine 不应把 `A` 误认为本次一定收到的实际 token 数
+- `epSendCounts` 记录的是按 rank 维组织的回传 token 数；阅读实现时，需要额外确认代码如何从这组计数推导本轮总发送任务数，再切到各核
+- 实际本地聚合 token 集通常由 `xActiveMask`、special expert 过滤以及其他有效项统计共同决定
+
+## 本页只保留的物理语义
+
+- combine 若采用“回来源 token 槽位”的协议，window 数据区应按 `token -> slot` 理解，而不是按“收到多少条就线性追加多少条”理解
+- 一个常见 token 区域包含 `K + sharedExpertNum` 个槽位：前 `K` 个槽位对应 moe expert，后续槽位对应 shared expert；是否存在 zero/copy/const 等额外路径，不改变 `expandIdx` 对 moe/shared 主路径槽位的定位语义
+- `expandIdx = [srcRank, srcTokenIdx, srcTopKIdx]` 的作用，是把某个 `expandX` 条目恢复到来源 rank 的 token 槽位；这决定了回传写入顺序和后续等待粒度
+- 若采用 ready 状态协议，状态区与数据区保持同一套 `token -> slot` 逻辑索引；等待按 token 粒度判断是否“所需槽位都已到齐”，而不是对整块状态区做统一 barrier
+- ready 的最小语义只要求能区分“未就绪 / 已就绪”；更具体的字节布局、地址公式和状态槽大小放到后续布局设计阶段统一处理
+
+## 最小路径
+
+1. 根据 `epSendCounts` 表示的各 rank 回传计数，先确定本轮总发送任务，再切出本核负责的发送任务区间
+2. 从 `expandIdx` 读取 `[srcRank, srcTokenIdx, srcTopKIdx]`，把 `expandX` 写回来源 rank 的对应 window 槽位
+3. 每写完一个槽位，再把对应状态槽置 ready
+4. 来源侧按 token 粒度轮询本地状态区，直到该 token 需要的 moe/shared expert 槽位就绪
+5. 清该 token 状态槽，按 `expertScales` 聚合 moe expert 结果
+6. 若命中特殊专家路径，再追加 zero/copy/const/shared expert 的对应处理
+7. 把最终结果写回 `XOut`；若启用性能信息，再额外写 `performanceInfo`
+
+## 常见特殊路径
+
+- `zero expert`：该 expert 不贡献任何数值，只影响等待目标与分支选择
+- `copy expert`：直接读取 `oriX`，乘以对应 `expertScale` 后累加
+- `const expert`：先读取 `oriX`，再用 `constExpertAlpha1/2` 和 `constExpertV` 计算混合结果后累加
+- `shared expert`：从 shared expert 对应 window 槽直接读取并累加；若 `hasSharedExpertX_` 打开，还会额外加上 `sharedExpertX`
+- `expert mask / token mask`：会改变有效 token 集和等待目标数，必须参与状态目标值判断
+- `performanceInfo`：不是功能输出，而是等待时间统计输出
+
+## 常见预留能力
+
+- 有些实现会预留 Add / RMSNorm / residual 融合辅助函数，但主路径未必真的启用
+- `residualX`、`gamma` 等输入即使已经进入 kernel 签名，也不代表当前主路径已经完成“聚合 + 残差 + RMSNorm”融合
+- 描述 combine 时，应把这类项标成“接口已预留 / 路径可选”，不要直接写成“当前主流程已经完成融合”
+
+## 必答项
+
+- `epSendCounts` 是否与 dispatch 的 `epRecvCounts` 保持同构，即“按 rank 维组织的回传 token 数量”
+- 代码是如何从这组按 rank 的计数推导出总发送任务数和本核发送区间的
+- `expandIdx` 是否固定为 `[srcRankId, srcTokenIdx, srcTopKIdx]`
+- 当前代码是“先二次 dispatch 回来源 window，再本地等待聚合”，还是其他协议
+- 每个 token 在 window / 状态区里是否固定有 `(K + sharedExpertNum)` 个槽位，还是使用其他槽位组织方式
+- 聚合是否先 cast 到 float，再做按 expertScale 的累加
+- zero/copy/const/shared expert 哪些路径启用，是否侵入主热路径
+- `performanceInfo`、量化路径、mask 路径是否启用
+- `residualX` / `gamma` 是当前主流程真实使用，还是仅为预留融合路径
+
+## 下一跳
+
+- dispatch / combine 中间量契约：`../api-rules/dispatch-combine-contracts.md`
+- 同步与可见性规则：`../api-rules/sync-and-visibility.md`
+- 分核改造：`../tiling-scheme/split-core-design.md`