Checklist

• 已检索 HyperParallel 现有 ISSUE，未发现相同问题。
• 已通过门禁构建日志和锁定源码定位根因。
• 已确认 SHMEM 上游后续提交中的修复方向。

问题描述

HyperParallel 的 symmetric memory 和 multicore native 组件共享 CANN SHMEM SDK。当前依赖锁定到
SHMEM v1.6.0（commit aee374a396b389626f68fab74ec8c555e18978a7）。在 CANN 9.2 环境编译时，
SHMEM host 兼容层无法获得 HcommChannelDesc 声明，导致两个组件均无法构建。

该问题在 HyperParallel Gate 8051 中稳定复现：

• CANN：9.2.0-beta.2

• 构建命令：

  bash build.sh --multicore mindspore --shmem all --custom-ops on --strict off
  

• 关键错误：

  src/host/utils/under_api/hcomm_entity_compat.h:
  error: use of undeclared identifier 'HcommChannelDesc'
  error: unknown type name 'HcommChannelDesc'
  

构建使用 --strict off 时，optional 组件失败不会阻止 wheel 输出，因此最终会生成不包含
symmetric memory 和 multicore payload 的 wheel；custom ops 组件可以独立构建成功。

失败日志：https://log-build.mindspore.cn/job/Hyper-parallel_Atomgit_Gate/8051

根因

SHMEM v1.6.0 的 hcomm_entity_compat.h 根据 CANN 头文件是否存在选择兼容分支：

1. CANN 9.1 环境没有 hcomm/hcomm_res_entity_defs.h，代码进入旧的兼容分支，并可通过
   hcomm_res.h 获得 HcommChannelDesc。
2. CANN 9.2 新增了 hcomm/hcomm_res_entity_defs.h，__has_include 命中新分支；该头文件不再提供
   SHMEM 当前代码所需的 HcommChannelDesc，同时 SHMEM 自身的 ABI 兼容声明被关闭。
3. 因此失败发生在 SHMEM v1.6.0 host 兼容层与 CANN 9.2 HCOMM 头文件的组合，而不是
   HyperParallel 的 CANN 路径发现或版本解析。

SHMEM 上游 commit
d30702bb
已调整该实现：host 编译不再直接包含 CANN HCOMM 头文件，而是在 SHMEM 内维护用于 dlopen/dlsym
调用的 ABI 形状声明，从而避免该头文件差异。该提交晚于 v1.6.0，目前 SHMEM release 页面尚无包含该修复的
新正式版本。

影响范围

• CANN 9.1 + SHMEM v1.6.0：现有编译路径可通过。
• CANN 9.2 + SHMEM v1.6.0：symmetric memory 编译失败。
• multicore 复用同一 SHMEM SDK，因此随之编译失败。
• --strict off 仍会输出 wheel，但上述 optional native 组件缺失，相关 Level1 用例应负责发现该问题。

建议方案

1. 不在 HyperParallel 中维护针对 SHMEM 源码的本地 patch。
2. 评估将 SHMEM 精确依赖更新到 d30702bb 或其后经验证的官方 commit；若上游发布包含修复的新版本，
   优先切换到正式 release。
3. 依赖更新后同时验证 CANN 9.1 和 CANN 9.2，避免修复新环境后破坏当前基线。
4. 覆盖 910B/910C、wheel/PYTHONPATH、symmetric memory、multicore 和 HyperMegaMoe 正反向路径。
5. 验证完成前，不宣称当前 SHMEM v1.6.0 组合支持 CANN 9.2。

验收标准

• CANN 9.1 和 CANN 9.2 下 SHMEM SDK、symmetric memory、multicore 均可完成编译。
• wheel 包含相应 native payload，PYTHONPATH 本地构建路径可正常加载。
• symmetric memory ST、HyperMegaMoe forward/grad ST 在 910B 和 910C 上通过。
• 依赖仍由统一 lock 文件精确记录，源码树不引入 SHMEM 兼容 patch。

关联：#333