@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/samples/dispatch-dataflow.md

@@ -0,0 +1,128 @@
+# MoE Dispatch 数据流
+
+这个页面承接 dispatch 的阶段控制流、接口语义和输出闭环；不展开 window 字节布局、地址公式和 UB 大小计算。
+
+## 最小阶段划分
+
+| 阶段 | 输入 | 产出 | 本阶段只回答什么 |
+| --- | --- | --- | --- |
+| 初始化 | EP 参数、`mc2Context`、输出张量 | 上下文、数据/状态区基址、window 参数、分核边界 | 上下文和基础地址从哪里来 |
+| token 发送 | `x` `expertIds` | 远端 window 中的通信 token | `dstRank/localExpert/dstSlot` 和发送地址如何求 |
+| 状态写入 | 各 `dstRank x localExpert` 的发送计数 | 远端 `localExpert x sourceRank` 状态 slot，slot 内写入 `flag` 和 `tokenCount` | 何时可以发布远端 ready 状态 |
+| 接收等待 | 本地状态区 | `expertRecvCounts`、`epRecvCounts`、`expertTokenNums` | 何时认为所有来源 rank 的状态都已收齐 |
+| 本地回搬 | 本地 window、接收统计 | `expandX` `expandIdx`，以及按需输出统计 | 如何按接收顺序把通信 token 还原成真实输出 |
+
+阶段附加约束：
+
+- SHMEM 库内部同步资源在 init 阶段自动清零；用户通信窗口（含状态区）需在 host 侧 `aclrtMemset` 显式清零后再传入 kernel
+- `Init()` 阶段不要手动清状态
+- `epRecvCounts` 和 `expertTokenNums` 是状态矩阵读取后的聚合结果，不是等待阶段的原始真值
+
+## 真实接口参数
+
+### 输入参数
+
+| 参数 | 含义 / 用意 | 逻辑维度 / shape | dtype | 关键约束 |
+| --- | --- | --- | --- | --- |
+| `x` | 本卡待发送的 token 特征输入 | 2D，通常为 `(Bs, H)` | `FLOAT16` / `BFLOAT16` / 其他实现指定类型 | 第 0 维与 token 维一致；第 1 维为单 token 特征长度 |
+| `expertIds` | 指定每个 token 的 topK 路由目标 | 2D，通常为 `(Bs, K)` | `INT32` | `expertIds[b, k]` 给出第 `b` 个 token 的第 `k` 个路由 expert |
+| `scales` | 平滑或量化路径使用的缩放参数 | 与量化/平滑路径绑定 | 路径相关 | 非量化路径可为空；量化路径必须与 `quantMode`、`expandScales` 闭环 |
+| `xActiveMask` | 描述哪些 token 或路由项有效 | 1D 或 2D mask，依实现而定 | `BOOL` | 当前常见路径可不启用；启用时必须同时约束有效 routed token 数 |
+| `expertScales` | 每个 token-topK 路由项对应的权重 | 通常为 `(Bs, K)` | `FLOAT` | combine 聚合权重的直接来源；dispatch 若消费，必须保持与 `expertIds` 同步 |
+| `groupEp` | EP 通信域标识 | 标量属性 | - | 专家并行域 |
+| `epWorldSize` | EP 域内 rank 总数 | 标量属性 | `INT64` / `INT32` | EP 域大小 |
+| `epRankId` | 当前卡在 EP 域中的 rank 编号 | 标量属性 | `INT64` / `INT32` | 范围 `[0, epWorldSize)` |
+| `moeExpertNum` | 全局 MoE expert 总数 | 标量属性 | `INT64` / `INT32` | 总 expert 数；与 `epWorldSize`、`sharedExpertRankNum` 一起决定路由划分 |
+| `expertShardType` | 共享专家卡的部署方式 | 标量属性 | `INT64` / `INT32` | 共享专家部署方式 |
+| `sharedExpertNum` | 共享专家数量 | 标量属性 | `INT64` / `INT32` | 共享专家数量 |
+| `sharedExpertRankNum` | 承载共享专家的 rank 数 | 标量属性 | `INT64` / `INT32` | 共享专家使用的 rank 数 |
+| `quantMode` | 通信与输出使用的量化模式 | 标量属性 | `INT64` / `INT32` | `0` 非量化；其他值需与量化输出闭环 |
+| `globalBs` | EP 域视角下的全局 batch 上界 | 标量属性 | `INT64` / `INT32` | EP 域全局 batch size |
+| `expertTokenNumsType` | 指定 `expertTokenNums` 输出语义 | 标量属性 | `INT64` / `INT32` | `0` 前缀和；`1` token 数量 |
+
+### 输出参数
+
+记号约定：
+
+- `A` 表示本卡可能接收的最大 token 数，是接口要求预留的容量上界，不是实际收到的 token 数
+- `R_actual` 表示本次 dispatch 在本卡实际收到并写入的有效 routed item 数，满足 `R_actual <= A`
+- `H_expand` 表示 `expandX` 的单行存储宽度，即真正写入 `expandX` 的特征长度。对普通 dtype，`H_expand = H`；对 `fp4x2` 这类打包存储类型，`H_expand = ceil(H / 2)`
+
+`A` 的取值约束来自接口文档：
+
+- 共享专家场景：`A = Bs * epWorldSize * sharedExpertNum / sharedExpertRankNum`
+- MoE 专家场景：
+  - `globalBs = 0` 时，`A >= Bs * epWorldSize * min(localExpertNum, K)`
+  - `globalBs != 0` 时，`A >= globalBs * min(localExpertNum, K)`
+
+其中 `localExpertNum` 表示本卡专家数：
+
+- 共享专家卡：`localExpertNum = 1`
+- MoE 专家卡：`localExpertNum = moeExpertNum / (epWorldSize - sharedExpertRankNum)`
+
+| 参数 | 含义 / 用意 | 逻辑维度 / shape | dtype | 关键约束 |
+| --- | --- | --- | --- | --- |
+| `expandX` | 保存 dispatch 后本卡接收到的展开 token 特征，供 expert 计算或 combine 输入使用 | 2D，按最大容量预留，推荐按 `(A, H_expand)` 理解 | `ExpandXOutType` | 只有前 `R_actual` 行有效；`H_expand` 不包含三元组附加信息 |
+| `dynamicScales` | 量化路径下与 `expandX` 对应的动态 scale | 与量化路径绑定，按最大容量预留 | 量化类型相关 | 仅量化路径有效；有效长度与 `expandX` 已写入部分对齐 |
+| `expandIdx` | 描述每个有效接收条目的来源位置，供 combine 原路返回 | 2D 逻辑上按 `(A, 3)` 预留；线性存储时长度至少为 `A * 3` | `INT32` | 每个有效条目固定三元组 `[srcEpRankId, srcTokenIndex, srcTopKIndex]`；有效条目数由实际接收量决定 |
+| `expertTokenNums` | 描述本卡各 expert 实际收到的 token 数量 | 1D；按本卡 expert 维度预留 | `INT64` | `expertTokenNumsType=1` 时表示数量；`expertTokenNumsType=0` 时表示前缀和语义 |
+| `epRecvCounts` | 描述本卡从 EP 通信域各来源 rank 实际收到的 token 数量 | 1D；按 EP rank 维度预留，常见为 `(epWorldSize,)` | `INT32` | 按来源 rank 维组织；combine 直接作为 `epSendCounts` 输入 |
+| `expandScales` | 保存有效接收条目对应的权重或量化相关 scale | 1D；按最大容量预留，常见为 `(A)` | `FLOAT` | combine 中与有效 routed item 同步消费 |
+
+## 输出闭环要求
+
+- `expandX`、`expandIdx`、`expandScales` 都按最大容量预留，实际有效长度由本次 dispatch 实际接收量决定
+- `expandX` 的第 1 维表示纯特征载荷宽度；附加三元组信息单独写入 `expandIdx`，不进入 `expandX`
+- `expandX` 有序地记录本卡所收到的所有 token，先按专家，再按来源 rank，连续分布
+- HCCL window 中传输的不是纯 `expandX` 行，而是通信 token；通信 token 由 `payload + triple` 组成，回搬阶段再拆成 `expandX` 与 `expandIdx`
+- 接收侧写真实输出时，收到的 token 按接收顺序连续写入 `expandX[0..R_actual)`；对应三元组按完全相同的顺序连续写入 `expandIdx[0..R_actual)`，二者必须一一对应
+- `expandIdx[i]` 必须能够唯一定位有效 `expandX` 条目的来源 `(epRankId, tokenIndex, topKIndex)`
+
+## 通信 token 与顺序规则
+
+dispatch 最小路径固定采用：
+
+1. `expertId -> dstRank, localExpert`
+2. 统计 `curExpertCnt`，得到 `dstSlot`
+3. 组织通信 token：`Align(payload, 32B) + [srcEpRankId, srcTokenIdx, srcTopKIdx]`
+
+## `curExpertCnt` 默认实现
+
+默认用：`在线计数 + 向量化比较归约`
+
+实现规则：
+
+1. 固定全局发送序：`index = tokenIdx * K + topkIdx`
+2. 分核切连续区间 `[startIndex, endIndex)`
+3. 对当前 `index`，取前缀区间 `[0, index)` 的 `expertIds`
+4. 在 UB 中构造常量向量 `dstExpertId`，对前缀做比较与归约
+5. 得到 `curOtherExpertCnt` 后，计算
+
+$$
+curExpertCnt = index - curOtherExpertCnt
+$$
+
+6. 用 `curExpertCnt` 作为 `dstSlot` 发窗
+
+向量化步骤：
+
+1. `Duplicate(dstExpIdTensor_, dstExpertId, index)`
+2. `Sub(subExpIdTensor_, expertIdsTensor_, dstExpIdTensor_, index)`
+3. `Abs(...)`
+4. `Mins(..., 1, index)`
+5. `ReduceSum(...) -> curOtherExpertCnt`
+6. `curExpertCnt = index - curOtherExpertCnt`
+
+## 本页只保留的物理语义
+
+- token 发送阶段写入的是完整通信 token，而不是纯 `expandX` 行；通信 token 由特征载荷和来源三元组组成，回搬阶段再拆成 `expandX` 与 `expandIdx`
+- dispatch 数据区的逻辑组织按 `sourceRank -> localExpert -> tokenSlot` 理解；`dstRank`、`localExpert` 和 `dstSlot` 的推导属于发送语义的一部分，但字节级布局和地址公式留到后续布局设计阶段统一处理
+- dispatch 状态区的逻辑组织按 `localExpert -> sourceRank -> stateSlot` 理解；等待阶段读取的是完整的 `expert x sourceRank` 状态矩阵，而不是只读聚合后的 rank 总数
+- `expertRecvCounts`、`epRecvCounts`、`expertTokenNums` 都是在等待阶段从状态矩阵聚合得到，不是状态区中的原始存储对象
+- 状态区在 host 侧 `aclrtMemset` 显式清零后传入 kernel，`Init()` 阶段不要额外手动清状态；状态复位发生在一轮等待成功、数据消费完成之后
+
+## 下一跳
+
+- 同步与可见性规则：`../api-rules/sync-and-visibility.md`
+- dispatch / combine 中间量契约：`../api-rules/dispatch-combine-contracts.md`
+- 分核改造：`../tiling-scheme/split-core-design.md`

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

@@ -0,0 +1,98 @@
+# MoE Dispatch/Combine Samples
+
+这个专题模块承接算子生成中的 `samples` 路径，负责沉淀 sample 可复用的工程 blueprint：host 侧多卡调用方式、工程编译方式、算子验证链路，以及这些职责对应的文件落点。
+
+## 适用场景
+
+- 还没补齐芯片、EP、expert、quant 和关键输出中间量规格
+- 还没决定工程采用什么目录分层、编译入口和文件落点
+- 还没说明 host 侧如何初始化多卡环境、创建通信资源并在多卡上调用 kernel
+- 还没说明工程如何编译、如何做结果校验、如何组织验证链路
+- 还在梳理 dispatch / combine 的阶段语义、接口参数和中间量闭环
+- 需要对照默认样例工程，确定哪些文件要参考、哪些文件要改
+
+## 不适用场景
+
+- `DataCopyPad`、`SetValue/GetValue`、状态发布/等待和 cache 可见性细节问题：`../api-rules/index.md`
+- window 物理布局、状态槽切分、workspace 组织和分核边界问题：`../tiling-scheme/index.md`
+
+dispatch/combine 的整体设计背景、阶段协作关系和方案动机说明见 `../reading/design-overview.md`。
+
+## 进入条件
+
+本模块的前置条件不包含单核实现或分核设计完成；其进入条件是当前内容仍处于规格补齐、工程对齐、接口语义对齐或文件落点判断阶段。
+
+## 在三部分中的位置
+
+生成路径默认拆成三部分：
+
+1. `samples`：给出样例工程可复用的工程 blueprint，包括 host 多卡调用方式、构建方式、验证链路、接口语义和改动落点
+2. `api-rules`：补齐 MoE 场景下的 API 约束、共享访问和状态协议规则
+3. `tiling-scheme`：设计 window 布局、分阶段分核、共享 workspace 和跨核统计方案
+
+本模块只覆盖第 1 部分；API 细节归入 `../api-rules/index.md`，分核方案设计归入 `../tiling-scheme/index.md`。
+
+## 工程起点
+
+- `moe_dispatch_direct_invoke_sample/` 主要作为工程 blueprint 参考，尤其用于说明 host 多卡调用方式、编译入口和验证链路
+- 不要回退到通用单文件 `.asc` 模板
+- 工程实现既可在现有项目中增量修改，也可按目标需求独立组织
+
+## 这个 blueprint 要说明什么
+
+`samples` 路径记录的是工程 blueprint，而不是代码阅读提示。该路径覆盖的工程事实包括：
+
+1. host 侧如何初始化设备、多卡通信域、stream 和通信资源，并把 `mc2Context` 传给 kernel
+2. kernel 入口、tiling 数据、通信上下文、主流程代码分别落在哪些文件
+3. 工程如何通过 `CMakeLists.txt`、`build.sh` 和依赖库完成编译
+4. 验证链路如何组织，包括 host 测试、结果校验脚本和 README 中的运行说明
+
+这四项共同构成 `samples` 路径的职责边界。
+
+## 工程形态
+
+- 允许并推荐 `host cpp + kernel h + include + test + scripts` 多文件结构
+- 不按通用 `add.asc` 样例审查工程
+- 可以参考样例工程现有命名和分层，例如 `moe_dispatch.cpp`、`kernel/moe_dispatch.h`、`kernel/mte_dispatch_comm.h`、`include/tiling_data.h`、`test/test_moe_dispatch.cpp`、`scripts/verify_dispatch.py`，并按当前实现需求抽取合适的组织方式
+
+## 编译与交付口径
+
+- host 侧 launch 路径、多卡通信初始化、`CMakeLists.txt` / `build.sh` 以及 ACL/HCCL 依赖属于本路径的编译说明范围
+- 验证链路包括 host 测试入口、校验脚本和运行时依赖
+- 不要为了套通用工作流，强行改造成单文件 `.asc` 编译路径
+- 交付件至少检查：构建文件、kernel 主流程、通信/tiling 头文件、host 测试或 launch、结果校验脚本、README/说明文档
+
+## 本模块只回答四件事
+
+1. 先看 `spec-template.md`，补齐芯片、EP、expert、quant、输出中间量（`expandIdx`、`epRecvCounts`、`epSendCounts`、`expertTokensCountPerRank`）
+2. host 侧多卡通信域初始化、通信资源创建、`mc2Context` 传递和 kernel launch 路径；工程结构与编译细节见 `build-framework.md`
+3. 目录分层、构建方式、验证链路和关键文件落点；接口语义和中间量闭环分别见 `dispatch-dataflow.md` 或 `combine-dataflow.md`
+4. sample 内 helper 分层、职责和文件落点见 `sample-helper-map.md`；API 规则见 `../api-rules/index.md`；分核方案见 `../tiling-scheme/index.md`
+
+## 详细页面
+
+- 编译框架特需说明（mc2 特有依赖、通信资源创建、平台宏）：`build-framework.md`
+- 规格模板：`spec-template.md`
+- dispatch 流程说明：`dispatch-dataflow.md`
+- combine 流程说明：`combine-dataflow.md`
+- sample helper 分层与查找：`sample-helper-map.md`
+- 改动定位：`change-routing.md`
+
+## Review 口径
+
+- 文件扩展名、命名形式等规范问题可以按 MoE 特殊性处理
+- 配置参数、算法逻辑、通信资源、输出布局、结果校验一致性必须严格验证
+- 对代码做修改后，注释和文档也应同步更新，确保反映当前实现
+
+## 不要做的事
+
+- 不要完全脱离已有参考工程和编译链路，直接按通用 `.asc` 模板生造 dispatch/combine 工程
+- 不将 `samples` 路径退化为纯代码阅读入口；host 调用方式、编译方式和验证链路均属于该路径的显式知识范围
+- 不要一开始同时重写 host、上下文辅助层、comm、kernel 全链路
+
+## 下一跳
+
+- 进入 API 细节：`../api-rules/index.md`
+- 进入分核方案：`../tiling-scheme/index.md`
+- 生成受阻时补背景：`../reading/design-overview.md`
+- 阅读已有实现：`../reading/`

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

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.16)
+project(moe_dispatch_direct_invoke)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Build type Release/Debug (default Debug)" FORCE)
+endif()
+
+set(SOC_VERSION "ascend950pr_957c" CACHE STRING "system on chip type")
+
+if(DEFINED ENV{ASCEND_HOME_PATH})
+    set(ASCEND_CANN_PACKAGE_PATH $ENV{ASCEND_HOME_PATH})
+else()
+    message(FATAL_ERROR "ASCEND_HOME_PATH not set, please configure CANN environment first")
+endif()
+
+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()
+if(NOT EXISTS "${ASCENDC_CMAKE_DIR}")
+    message(FATAL_ERROR "ascendc_kernel_cmake not found, check CANN at: ${ASCEND_CANN_PACKAGE_PATH}")
+endif()
+include("${ASCENDC_CMAKE_DIR}/ascendc.cmake")
+
+set(INCLUDE_DIRS
+    ${CMAKE_CURRENT_SOURCE_DIR}/kernel
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+ascendc_library(ascendc_kernels SHARED ${CMAKE_CURRENT_SOURCE_DIR}/moe_dispatch.cpp)
+ascendc_include_directories(ascendc_kernels PRIVATE ${INCLUDE_DIRS})
+
+add_executable(test_moe_dispatch ${CMAKE_CURRENT_SOURCE_DIR}/test/test_moe_dispatch.cpp)
+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}")
+target_include_directories(test_moe_dispatch PRIVATE
+    ${ASCEND_CANN_PACKAGE_PATH}/pkg_inc
+    ${ASCEND_CANN_PACKAGE_PATH}/include
+    ${INCLUDE_DIRS}
+)
+target_link_libraries(test_moe_dispatch PRIVATE
+    ascendc_kernels
+    tiling_api
+    platform
+    pthread
+    hccl
+    hccl_fwk
+    hcomm
+)

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

@@ -0,0 +1,131 @@
+# MoE Dispatch 单算子直调工程
+
+这个 sample 提供一个独立的 MoE Dispatch 算子，通过 `<<<>>>` 内核调用方式实现多卡 token 分发。
+
+## 核心特性
+
+- **Host 侧**：通过 `HcclCommInitAll` 初始化多卡 HCCL comm，用 `Mc2CcTilingConfig` 组 tiling，用 `HcclAllocComResourceByTiling` 创建通信资源 context
+- **Kernel 侧**：解析 host 传入的 `mc2Context`，直接读取 tiling 中的 `epWorldSize`
+- **通信方式**：走 MTE Win Area，不走 `aclnn`
+- **状态同步**：使用按 `expert x srcRank` 分槽的 32B 状态区设计，并基于该二维统计收口 `epRecvCounts` 与 `expertTokenNums`
+
+## 当前架构
+
+当前 sample 可以按 4 层理解：
+
+1. **Host 启动层**：`test/test_moe_dispatch.cpp` 负责建卡、建流、组 tiling、申请 `mc2Context`、准备输入输出并 launch kernel。
+2. **通信上下文与兼容层**：`include/tiling_data.h` 和 `include/moe_dispatch_base_compat.h` 负责定义通信资源结构体和基础地址 helper 语义。
+3. **通信搬运层**：`kernel/mte_dispatch_comm.h` 负责 window/status 布局、远端状态发布、本地状态等待。
+4. **算子编排层**：`kernel/moe_dispatch.h` 负责路由、slot 计算、发窗、回搬和输出统计。
+
+如果后续要基于 sample 改新算子，通常优先先改 host 与 comm 两层，再改 kernel 编排层。
+
+## 简化约束
+
+当前 sample 只保留最小可运行版本：
+
+- `expertId` 直接等于 `dstRank`
+- `moeExpertNum = epWorldSize`
+- 每个 rank 只有 1 个 local expert
+- `K=1`，无量化，无 shared expert
+- 单 AIV 核处理完整数据路径
+- 硬编码为单核处理，缺乏多核并行能力
+
+## 为什么当前 sample 还不是真正的分核设计
+
+当前 sample 虽然已经把 Host、Comm、Kernel 结构拆开，并且在代码里预留了 `GetBlockIdx()`、`InitBlockRange()`、`usedCores` 一类入口，但它仍然只是单核基线，不应直接视为完整的多核实现模板。
+
+原因主要有四点：
+
+1. 现在的分核控制主要还是围绕一个全局 token 区间展开，不能覆盖发送、状态、回搬、统计这些不同阶段的工作项差异。
+2. 状态区处理天然更适合按 `expert` 或 `expert x srcRank` 分槽切分，而不是继续复用 token 维度的区间。
+3. 输出回搬最终要服从 `expandX` / `expandIdx` 的输出顺序，真正做多核时通常还需要 prefix sum、偏移计算或按输出段切分，当前 sample 还没有补齐这部分设计。
+4. 统计输出如 `sendCounts`、`recvCounts`、`expertTokenNums` 涉及核间合并，当前 sample 还没有实现“核内统计 + 核间归并”的完整闭环。
+
+因此，当前 sample 更准确的定位是：
+
+- 它是一个可以验证数据流、通信地址、状态协议和最小输出闭环的单核基线。
+- 它可以作为多核改造的起点，但不能把“把 `usedCores` 改大”视为完成了真正的分核设计。
+
+## 目录结构
+
+```text
+moe_dispatch_direct_invoke_sample/
+├── CMakeLists.txt
+├── README.md
+├── build.sh
+├── moe_dispatch.cpp              # Kernel 入口
+├── run.sh
+├── run_multi_data_test.sh
+├── include/
+│   ├── tiling_data.h             # Tiling 数据结构
+│   └── utils.h
+├── kernel/
+│   ├── mte_dispatch_comm.h       # 通信辅助层
+│   └── moe_dispatch.h            # Dispatch 算子实现
+├── scripts/
+│   └── verify_dispatch.py        # 输出验证脚本
+└── test/
+    └── test_moe_dispatch.cpp     # Host 测试程序
+```
+
+## 快速开始
+
+### 1. 环境准备
+
+```bash
+export ASCEND_HOME_PATH=/path/to/cann
+source ${ASCEND_HOME_PATH}/set_env.sh
+```
+
+### 2. 编译
+
+```bash
+bash build.sh
+```
+
+### 3. 运行
+
+```bash
+BS=4 H=16 RANK_SIZE=2 bash run.sh
+```
+
+## 状态区设计
+
+### 布局
+
+- 按 **先分 expert，再分 srcRank** 的方式组织
+- 每个 slot 占用 32 字节（8 个 int32_t），满足硬件对齐要求
+- slot 内容：`[flag, token_count, padding]`
+  - flag: 0=未就绪，1=就绪
+  - token_count: 该 srcRank 发给此 expert 的 token 数量
+- `WaitRemoteStatus` 会先读取完整的 `expert x srcRank` 状态矩阵，再聚合出按 rank 的 `recvCounts`
+
+### 同步流程
+
+1. **SetRemoteStatus**：对每个 `dstRank x expert` slot 先写 `token_count`，最后写 `flag=1`
+2. **WaitRemoteStatus**：轮询所有 `expert x srcRank` slot，全部就绪后生成 `expertRecvCounts` 和按 rank 聚合后的 `recvCounts`
+3. **ClearLocalStatus**：等待成功后立即把本地状态区复位为 0，避免下一轮误读旧状态
+
+## 输出文件
+
+每个 rank 会在输出目录中生成：
+
+- `input_rankX.bin`
+- `expert_ids_rankX.bin`
+- `expand_x_rankX.bin`
+- `expand_idx_rankX.bin`
+- `expert_token_nums_rankX.bin`
+- `ep_recv_counts_rankX.bin`
+- `summary_rankX.txt`
+
+使用 `scripts/verify_dispatch.py` 验证输出结果。
+
+## 扩展方向
+
+当前 sample 支持以下扩展：
+
+1. **多 local expert**：修改 `localExpertNum_`，状态区会自动按 expert 分区
+2. **多 topK**：需要修改路由和 expandIdx 逻辑
+3. **shared expert**：需要在状态区中增加 shared expert 分区
+4. **多核并行**：需要把发送、状态、回搬、统计按阶段分别设计分核，不能只放大当前 sample 的单一 token 区间切分

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

@@ -0,0 +1,56 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+
+#!/bin/bash
+set -e
+
+# ============================================================================
+# Ascend C MoE Dispatch 单算子直调工程编译脚本
+#
+# 用法：bash build.sh
+#
+# 前置条件：
+#   export ASCEND_HOME_PATH=/path/to/CANN
+#
+# 产物：
+#   build/lib/libascendc_kernels.so  — Kernel 共享库
+#   build/test_moe_dispatch          — 多 rank 测试可执行文件
+# ============================================================================
+
+echo "Setting up environment..."
+[ -n "${ASCEND_HOME_PATH:-}" ] || { echo "ERROR: ASCEND_HOME_PATH 未设置，请先配置 CANN 环境" >&2; exit 1; }
+source "${ASCEND_HOME_PATH}/set_env.sh" || { echo "ERROR: set_env.sh 执行失败" >&2; exit 1; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "Building in: $SCRIPT_DIR/build"
+rm -rf build
+mkdir -p build
+cd build
+
+echo "Running CMake..."
+cmake ..
+
+echo "Compiling..."
+make -j$(nproc)
+
+if [ -f "lib/libascendc_kernels.so" ] && [ -f "test_moe_dispatch" ]; then
+	echo ""
+	echo "Build successful!"
+	echo "  Kernel library: $(pwd)/lib/libascendc_kernels.so"
+	echo "  Test binary:    $(pwd)/test_moe_dispatch"
+	echo ""
+	ls -lh lib/libascendc_kernels.so test_moe_dispatch
+else
+	echo "Build failed!"
+	exit 1
+fi

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/samples/moe_dispatch_direct_invoke_sample/include/moe_dispatch_base_compat.h

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+ * CANN Open Software License Agreement Version 2.0 (the "License").
+ * Please refer to the License for details. You may not use this file except in compliance with the License.
+ * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+ * See LICENSE in the root of the software repository for the full text of the License.
+ */
+
+/*!
+ * \file moe_dispatch_base_compat.h
+ * \brief
+ */
+#ifndef MOE_DISPATCH_BASE_COMPAT_H
+#define MOE_DISPATCH_BASE_COMPAT_H
+
+#include "basic_api/kernel_basic_intf.h"
+#include "tiling_data.h"
+
+namespace Mc2Kernel {
+
+using namespace AscendC;
+
+constexpr uint64_t A5_MTE_STATE_WIN_SIZE = 1024UL * 1024UL;
+
+struct HcclRankRelationResV2 {
+    uint32_t remoteUsrRankId;
+    uint32_t remoteWorldRank;
+    uint64_t windowsIn;
+    uint64_t windowsOut;
+    uint64_t windowsExp;
+};
+
+#if defined(__NPU_ARCH__) && (__NPU_ARCH__ == 3510)
+using HcclOpParam = MoeDispatchImpl::HcclA5OpResParam;
+
+__aicore__ inline uint32_t GetRankId(__gm__ HcclOpParam *winContext)
+{
+    return winContext->rankId;
+}
+
+__aicore__ inline uint32_t GetRankDim(__gm__ HcclOpParam *winContext)
+{
+    return winContext->rankDim;
+}
+
+__aicore__ inline uint64_t GetWinSize(__gm__ HcclOpParam *winContext)
+{
+    return winContext->winSize;
+}
+
+__aicore__ inline GM_ADDR GetStatusDataSpaceGm(__gm__ HcclOpParam *winContext)
+{
+    return (GM_ADDR)(winContext->windowsIn[winContext->rankId]);
+}
+
+__aicore__ inline GM_ADDR GetBaseWindAddrByRankId(__gm__ HcclOpParam *winContext,
+    const int32_t rankId, const int32_t curRankId)
+{
+    return (GM_ADDR)(winContext->windowsIn[rankId] + A5_MTE_STATE_WIN_SIZE);
+}
+
+__aicore__ inline GM_ADDR GetBaseWindStateAddrByRankId(__gm__ HcclOpParam *winContext,
+    const int32_t rankId, const int32_t curRankId)
+{
+    return (GM_ADDR)(winContext->windowsIn[rankId]);
+}
+#else
+using HcclOpParam = MoeDispatchImpl::HcclA3OpResParam;
+
+__aicore__ inline uint32_t GetRankId(__gm__ HcclOpParam *winContext)
+{
+    return winContext->localUsrRankId;
+}
+
+__aicore__ inline uint32_t GetRankDim(__gm__ HcclOpParam *winContext)
+{
+    return winContext->rankSize;
+}
+
+__aicore__ inline uint64_t GetWinSize(__gm__ HcclOpParam *winContext)
+{
+    return winContext->winSize;
+}
+
+__aicore__ inline GM_ADDR GetStatusDataSpaceGm(__gm__ HcclOpParam *winContext)
+{
+    return (GM_ADDR)(winContext->localWindowsExp);
+}
+
+__aicore__ inline GM_ADDR GetBaseWindAddrByRankId(__gm__ HcclOpParam *winContext,
+    const int32_t rankId, const int32_t curRankId)
+{
+    if (rankId == curRankId) {
+        return (GM_ADDR)(winContext->localWindowsIn);
+    }
+    return (GM_ADDR)(((HcclRankRelationResV2 *)(winContext->remoteRes[rankId].nextDevicePtr))->windowsIn);
+}
+
+__aicore__ inline GM_ADDR GetBaseWindStateAddrByRankId(__gm__ HcclOpParam *winContext,
+    const int32_t rankId, const int32_t curRankId)
+{
+    if (rankId == curRankId) {
+        return (GM_ADDR)(winContext->localWindowsExp);
+    }
+    return (GM_ADDR)(((HcclRankRelationResV2 *)(winContext->remoteRes[rankId].nextDevicePtr))->windowsExp);
+}
+#endif
+
+} // namespace Mc2Kernel
+
+#endif // MOE_DISPATCH_BASE_COMPAT_H

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/samples/moe_dispatch_direct_invoke_sample/include/tiling_data.h

@@ -0,0 +1,100 @@
+/**
+ * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+ * CANN Open Software License Agreement Version 2.0 (the "License").
+ * Please refer to the License for details. You may not use this file except in compliance with the License.
+ * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+ * See LICENSE in the root of the software repository for the full text of the License.
+ */
+
+/*!
+ * \file tiling_data.h
+ * \brief
+ */
+#ifndef MOE_DISPATCH_TILING_DATA_H
+#define MOE_DISPATCH_TILING_DATA_H
+
+#include <stdint.h>
+#include <kernel_tiling/kernel_tiling.h>
+
+namespace MoeDispatchImpl {
+
+// 最大 rank 数量和 expert 数量（用于 kernel 栈空间分配）
+constexpr static int64_t MAX_RANK_NUM = 64;
+constexpr static int64_t MAX_EXPERT_NUM = 8;
+
+// HCCL 相关常量
+constexpr uint32_t HCCL_MTE_MAX_RANK_NUM = 64;
+constexpr uint32_t AICPU_MAX_RANK_NUM = 128 * 1024;
+
+/**
+ * @brief HCCL A5 通信资源参数
+ *
+ * 可由 HcclAllocComResourceByTiling 返回，包含 window 地址等信息
+ */
+struct HcclA5OpResParam {
+    uint64_t workSpace;
+    uint64_t workSpaceSize;
+    uint32_t rankId;
+    uint32_t rankDim;
+    uint64_t winSize;
+    uint64_t windowsIn[HCCL_MTE_MAX_RANK_NUM];
+    uint64_t windowsOut[HCCL_MTE_MAX_RANK_NUM];
+    uint64_t xnAddr;
+    uint64_t ckeAddr;
+    uint64_t msAddr;
+    uint64_t msSize;
+};
+
+struct RemoteResPtr {
+    uint64_t nextHostPtr;
+    uint64_t nextDevicePtr;
+};
+
+/**
+ * @brief HCCL A3 通信资源参数
+ *
+ * 可由 HcclAllocComResourceByTiling 返回，包含 window 地址等信息
+ */
+struct HcclA3OpResParam {
+    uint32_t localUsrRankId;
+    uint32_t rankSize;
+    uint64_t winSize;
+    uint64_t localWindowsIn;
+    uint64_t localWindowsOut;
+    uint64_t winExpSize;
+    uint64_t localWindowsExp;
+    uint32_t remoteResNum;
+    RemoteResPtr remoteRes[AICPU_MAX_RANK_NUM];
+};
+
+/**
+ * @brief Tiling 信息结构体
+ *
+ * 包含 dispatch 算子所需的基本参数
+ */
+struct MoeDispatchTilingInfo {
+    uint64_t bs;            // 每个 rank 的 token 数量
+    uint64_t h;             // 每个 token 的特征维度
+    uint64_t epWorldSize;   // EP 并行的 rank 数量
+    uint64_t aivNum;        // 使用的 AIV 核数量
+    uint64_t maxRecvTokens; // 最大接收 token 数量
+    uint64_t totalWinSize;  // 总 window 大小
+    uint64_t topK;          // 每个 token 路由的 expert 数量
+};
+
+/**
+ * @brief 完整的 Tiling 数据结构体
+ *
+ * 包含 MC2 通信所需的 tiling 信息和算子参数
+ */
+struct MoeDispatchTilingData {
+    Mc2InitTiling mc2InitTiling;
+    Mc2CcTiling mc2CcTiling;
+    MoeDispatchTilingInfo tilingInfo;
+};
+
+} // namespace MoeDispatchImpl
+
+#endif // MOE_DISPATCH_TILING_DATA_H