HCCL 仓库 AI Agent 协作与开发指南从架构约束到构建测试的完整实战解析【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl本文基于 CANN/HCCL 仓库的治理主入口文档 AGENTS.md系统讲解面向 AI 编程工具与开发者的 HCCL 协作规则仓库定位、目录结构、软件架构分层与四大硬性约束、构建测试命令、编码规范与贡献流程。读完本文你将掌握在 HCCL 仓库中安全改动的边界尤其是不得违反分层依赖、不得引入对 HCOMM 的编译期硬依赖等铁律并能独立完成源码构建、UT/ST 验证与从 Issue 到 PR 合入的完整链路。1. 仓库定位HCCL 与 HCOMM 的双子仓结构HCCLHuawei Collective Communication Library是 CANN 的核心集合通信库为昇腾 AI 处理器集群提供高性能、高可靠的集合通信与点对点通信能力。其核心能力包括集合通信原语AllReduce、Broadcast、AllGather、ReduceScatter、AlltoAll 等点对点通信Send/Recv、BatchSendRecv执行模式单算子模式与图模式支撑对象对上支持 AI 框架对下通过 HCOMM 通信基础库使能昇腾 NPU。一个容易被忽略但非常关键的事实是HCCL 并非单仓单体而是双子仓结构。按 AGENTS.md 第 1 节的表述HCCL HCCL 集合通信算子库本仓cann/hccl HCOMM 通信基础库cann/hcomm两仓通过dlsym动态加载解耦可以独立编译、独立版本演进。这一点是整个仓库所有架构约束的源头后续第 3 节的硬性约束几乎都围绕它展开。总体概况可进一步参考 README.md 与架构权威文档 docs/zh/architecture/architecture-brief.md。2. 目录结构一眼定位官方算子与试验代码AGENTS.md 第 2 节给出了仓库的目标目录结构与 README.md 及架构文档中的 目标目录结构 保持一致src/ ├── ops/ # 集合通信算子实现all_reduce/all_gather/broadcast/reduce_scatter/send/recv/... │ └── op_common/ # 公共组件algorithm/{executor,template,topo_match} selector topo_info inc └── common/ # 通用逻辑adapter_acl/alg_env_config/log/param_check/sal/hcomm_dlsym/op_graph/utils/hccl_mc2 experimental/ # 社区贡献的试验性代码当前尚未完全与 src 对齐含 ops/不保证兼容性不编入商用版本 include/ # 对外头文件hccl.h算子 API、hccl_mc2.hMC2 自定义算子框架 test/ # ut / st docs/ # 资料文档 build.sh # 一键编译脚本对照当前仓库实际内容可以验证src/ops/下确实按算子分目录组织all_reduce、all_gather、broadcast、reduce_scatter、send、recv、all_to_all_v、barrier、batch_send_recv 等每个算子目录统一为algorithm/selector/op_graph/结构src/ops/op_common/则是公共组件层包含algorithm/executor/template/topo_match、selector/、topo_info/、inc/等子目录。理解这条目录结构的意义在于在 HCCL 中代码落在哪个目录本身就是一种架构声明。官方新算子必须落在src/ops/op/社区试验算子必须落在experimental/ops/op/二者都遵循selectoralgorithm/{executor,template}的组织方式禁止散落到其他目录详见第 3 节约束 4。3. 软件架构与四大硬性约束核心章节3.1 软件分层AGENTS.md 第 3 节以表格形式给出软件分层与架构文档 docs/zh/architecture/architecture-brief.md 的「3 软件分层逻辑」一节互为印证软件层次仓位置HCCL 集合通信算子coll_comm_opsL1本仓cann/hcclHCOMM 集合通信域管理HCCML2cann/hcommHCOMM 基础通信L3cann/hcomm依赖方向自上而下、单向流动coll_comm_opsHCCL → coll_communicator_mgr → base_comm后两者在 HCOMM 仓3.2 四大架构约束硬性不可违反AGENTS.md 用 ⭐ 标注以下约束为硬性要求任何改动尤其是src/、include/下的代码改动都必须逐条对照约束AI Agent 行为要求分层依赖方向上层依赖下层下层不能反向依赖上层HCOMM 的base_comm↛coll_communicator_mgr↛coll_comm_opsHCCL 不得被 HCOMM 反向依赖HCCL 算子通过 dlsym 调 HCOMM不得要求 HCOMM 反向 include HCCL 头控制面/数据面分离资源管理、拓扑查询控制面与数据搬运/同步数据面接口独立演进HCCL 算子属数据面消费方不得在算子层引入对 HCOMM 控制面内部实现的耦合HCCL 与 HCOMM 解耦HCCL 算子通过dlsym动态加载 HCOMM 接口两仓独立编译、独立版本演进HCCL 不得#includeHCOMM 私有头不得引入对cann/hcomm的编译期硬依赖跨仓调用走src/common/hcomm_dlsym/的符号表 dlsym新算子落标准结构官方新算子落src/ops/op/社区贡献的试验性新算子落experimental/ops/op/结构与src一致不保证兼容性、不编入商用版本。均按selectoralgorithm/{executor,template}组织新算子须提供 selector算法选择与 template引擎模板aicpu/aiv/ccu官方算子落src/ops/社区试验算子落experimental/ops/禁止散落其他目录源码级佐证dlsym 解耦的实现落点HCCL 与 HCOMM 解耦不是一句口号而是有具体代码支撑的。跨仓调用的实现集中在 src/common/hcomm_dlsym/ 目录该目录以*_dl.cc/*_dl.h形式为每类 HCOMM 接口维护独立的动态加载封装如hccl_dl.cc、hccl_res_dl.cc、hccl_rank_graph_dl.cc、hcomm_primitives_dl.cc、hcomm_diag_dl.cc、hcomm_device_profiling_dl.cc等。以最基础的加载入口为例src/common/hcomm_dlsym/hccl_dl.cc 中可以看到对dlopen/dlsym的直接封装void* __HcclDlsym(void* handle, const char* funcName) { return dlsym(handle, funcName); } void* __HcclDlopen(const char* libName, int mode) { return dlopen(libName, mode); }而 src/common/hcomm_dlsym/dlsym_common.h 则展示了另一层关键细节跨版本兼容。它通过 CANN 版本号宏如CANN_VERSION(9, 0, 0)在编译期判断当前 CANN 版本对 9.0.0、9.1.0 等边界版本缺少的类型如HcclCommStatus、ThreadHandle做条件桩定义从而保证同一份 HCCL 源码可以跨多个 CANN 版本动态加载 HCOMM 接口——这正是独立编译、独立版本演进得以成立的技术基础。这也解释了为什么 build.sh 中会存在hccl_compat.map、hccl_kernel_compat.map等符号兼容映射文件位于 src/common/hcomm_dlsym/。3.3 对外 API 分层AGENTS.md 第 3 节同时给出了对外 API 的层次划分层次头文件面向L1 算子include/hccl.hAI 框架适配层AllReduce/Broadcast/AllGather/ReduceScatter/AlltoAll/Send/Recv 等MC2 自定义算子include/hccl_mc2.h自定义通信算子开发者KfcOpArgs/OpResCtx 等在 include/hccl.h 中可以确认 L1 算子接口的真实签名例如HcclAllReduce(void* sendBuf, void* recvBuf, uint64_t count, HcclDataType dataType, HcclReduceOp op, HcclComm comm, aclrtStream stream)HcclBroadcast(void* buf, uint64_t count, HcclDataType dataType, uint32_t root, HcclComm comm, aclrtStream stream)HcclSend/HcclRecv、HcclAllGather、HcclReduceScatter、HcclAlltoAll、HcclAlltoAllV、HcclAlltoAllVC、HcclBatchSendRecv等一应俱全均以extern C导出以兼容框架层 C 接口调用。关键要求是include/变更需向后兼容——这是对外的契约任何接口签名调整都必须考虑存量 AI 框架适配层的影响。更完整的 API 分层关系L1/L2-comm/L2-res-rank_graph/L3-prim/L3-res见 docs/zh/architecture/architecture-brief.md 的「3.3 对外API分层关系」一节。4. 构建与测试build.sh 全参数实战AGENTS.md 第 4 节给出了最常用的构建与测试命令本文结合 build.sh 实际源码将其展开为完整参数说明。4.1 核心命令速查bash build.sh --pkg # 编译 host 包默认 bash build.sh -u # 编译并运行 UT bash build.sh -s # 编译并运行 ST bash build.sh --static # 静态库构建 bash build.sh --asan # 启用 AddressSanitizer bash build.sh --custom_ops_pathPATH # 自定义算子工程 bash build.sh -j64 # 并行编译4.2 参数全表依据 build.sh usage 展开从 build.sh 的usage()函数可提取完整参数语义参数含义备注-h, --help打印使用说明—--asan启用 AddressSanitizer内部追加-DENABLE_ASANON运行测试时还会按架构自动设置libasan.so的LD_PRELOAD--build-typeTYPE构建类型Release / Debug默认 Release脚本内CMAKE_BUILD_TYPE初始为 Debug最终由该参数决定-jN编译并行线程数默认按 CPU 核数 ×2 自动计算也可显式-j64--pkg-typeTYPE打包类型run / rpm / deb / all默认 run非法值直接报错退出--cann_3rd_lib_pathPATH昇腾第三方依赖包安装路径默认./output/third_party-p, --package-path PATHCANN 软件包安装路径默认/usr/local/Ascend/cann脚本会按-p→ASCEND_HOME_PATH→ASCEND_OPP_PATH→ 默认安装目录的顺序自动探测--sign-script PATH/--enable-sign签名脚本路径 / 使能签名商用包签名用--version VERSION签名版本号默认从 version.cmake 的VERSION字段读取当前为 9.2.0--custom_ops_pathPATH/--opsOPS/--vendorVENDOR自定义算子工程路径、算子名、vendor三者任一带上即进入自定义算子编译分支--experimental使能试验特性追加-DENABLE_EXPERIMENTALON--static静态库构建模式走build_staticpackage_static_tar流程产出libhccl_static.a与cann-hccl-static_VERSION_linux-arch.tar.gz-s, --st运行全部系统测试ST设置ENABLE_TESTon、ENABLE_STon--st_opsOPS1,OPS2,...运行指定 ST 算子用例支持 scatter、all_reduce、all_gather、reduce_scatter、broadcast、alltoall、alltoallv、alltoallvc 等--cov使能代码覆盖率插桩ST 场景下会生成 lcov 覆盖率报告--noexec只构建测试不执行—--aicpu/--full编译设备侧 AICPU 内核--full同时置位ENABLE_BUILD_DEVICE4.3 环境准备与前置依赖完整构建流程的前置依赖见 docs/zh/build/build.md「前置依赖」节python 3.7.0、pip3 20.3.0gcc g7.3.0 至 14.2.xcmake 3.16.0ccache可选提高二次编译速度googletest仅执行 UT 时依赖建议 release-1.14.0。同时需安装 CANN Toolkit 开发套件包并正确source set_env.sh例如source CANN安装路径/cann/set_env.sh。NPU 驱动、固件和 CANN ops 算子包为运行态依赖仅编译源码可不安装但运行或上板测试前必须安装。官方推荐优先使用 Docker 构建镜像镜像内预装构建工具及 CANN 软件或宿主机部署两种方式详见 docs/zh/build/build.md。4.4 静态库构建的 8 步流水线bash build.sh --static是一条值得单独说明的复杂链路。从 build.sh 的build_static()函数可以看到它实际是一条多阶段流水线初始化交叉编译工具链init_toolchainaarch64 场景使用aarch64-target-linux-gnu-*工具链构建设备端 AICPU 包产出aicpu_hccl.tar.gz构建主机端静态库libhccl_static.a并同步构建 AIV 设备 kernelaiv_all_targets产出hccl_aiv_*_op_910_95.o/hccl_aiv_*_op_960.o用ar -x解压静态库为.o文件用ld -r -b binary将 AICPU tar 包转为二进制对象aicpu_hccl_tar.o将 AIV kernel.o转成 binary embed 对象并注入_binary_..._start/end/size符号将全部.o打包为最终静态库libhccl_static_final.a复制到标准输出位置libhccl_static.a清理临时目录随后package_static_tar打出cann-hccl-static_VERSION_linux-arch.tar.gz。这解释了为何静态库能同时包含 host 端算子逻辑、AICPU 内核与 AIV 内核——它们以二进制嵌入对象的形式被打包进同一个.a文件。该能力对应 README 中Ascend950 通信算子支持静态库的发布特性。4.5 推送前验证AGENTS.md 明确建议推送前优先本地验证--pkg--ut--st三件套。UT 用例位于 test/ut如 alltoall_hier、recursive_executor、reduce_scatter_birs、common 等目录ST 用例位于 test/st/algorithmtestcase utils 双层结构通过 CTest 并发执行、单用例超时 350s、失败即停。5. 编码规范从命名到 CI 静态检查AGENTS.md 第 5 节定义了仓库级编码规范本文对照根目录 .clang-format 实际配置做进一步确认命名类/函数 PascalCase成员变量camelCase_小驼峰 后缀下划线常量与宏UPPER_SNAKE_CASE风格遵循根目录.clang-format。实测关键配置项为ColumnLimit: 120120 列、IndentWidth: 44 空格缩进、PointerAlignment: Left指针左对齐、Standard: Latest大括号采用 KRBreakBeforeBraces: Custom语言标准为 C14静态告警代码须通过 CANN 静态检查要求CI codecheck 阶段校验编译无告警pre-commitclang-format v18.1.8 OAT 合规检查新增源文件须带 CANN-2.0 许可头。关于许可头OAT.xml 中配置了policyitem typelicense nameCANN-2.0 path.*的默认许可策略即仓库内所有文件默认要求 CANN-2.0 许可头。以 include/hccl.h 文件头为例可以直观看到标准许可头模板的格式Copyright © 2025 Huawei Technologies Co., Ltd. CANN Open Software License Agreement Version 2.0 声明新增源文件应与此保持逐字节一致。相关规范参考 CANN 编码规范外部社区仓按需查阅与仓内 docs/zh/build/pre-commit-guide.md。6. 文档编写规范两条特殊规则AGENTS.md 第 6 节给出了文档目录组织与产品名称的硬性规则目录组织docs/zh/中文与docs/en/英文分开存放API 文档使用 PascalCase如HcclAllReduce.md环境变量文档使用 UPPER_SNAKE_CASE如HCCL_ALGO.md。对照当前仓库 docs/zh 目录api_ref/comm_op_interface/下的HcclAllReduce.md、HcclAllGather.md等确实遵循 PascalCase而user_guide/hccl_env/下的HCCL_ALGO.md、HCCL_BUFFSIZE.md等遵循 UPPER_SNAKE_CASE验证了这一规则已被严格执行。产品名称特殊规则单位与数字、中文与英文之间不加空格如50m、昇腾AI处理器但产品名称内部允许保留空格如Ascend 950PR/Ascend 950DT、Atlas A3 训练系列产品以保持官方产品标识的完整性和可读性。7. 贡献流程从 Issue 到 PR 合入的端到端链路AGENTS.md 第 7 节按问题类型区分了两条贡献路径简单问题Issue → 认领 → PR → Committer 检视 →/lgtm/approve合入新功能Requirement Issue → SIG 决策 →docs/zh/rfcs/RFC 评审 → 实现含 UTST→ 检视合入。仓库内 docs/zh/rfcs 目录已有 3 篇 RFC0001-add-batch-invariant-reducescatter.md、0002-HCCL-ALGO-Plugin.md、0003-executor-template-refactor.md可作为新功能 RFC 的格式参考。所有 PR 必须关联 Issue描述按.gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md填写。更完整的贡献规范见 CONTRIBUTING.md。7.1 仓内自动化 skillhccl-contribute 与 hccl-reviewAGENTS.md 特别指出从代码获取到 PR 合入的贡献链路操作代码同步、Issue 查重创建、PR 提交触发 CI、CI 轮询与失败修复、检视意见处置应使用仓内贡献流程 skill——.agents/skills/hccl-contribute/开发提交自检与检视他人 PR 使用 .agents/skills/hccl-review/。从 .agents/skills/hccl-contribute/SKILL.md 可以看到该 skill 的完整工作流Step 1 代码获取与更新 → Step 2 依赖环境确认 → Step 3 本地构建与测试 ↓ Step 8 检视意见处置 ← Step 7 CI 失败修复 ← Step 6 CI 监控 ← Step 5 PR 创建与提交 ↑ Step 4 Issue 查重与创建每个子流程可独立运行例如只修 CI 从 Step 7 起步、只处理检视意见从 Step 8 起步。核心命令统一为python3 .agents/skills/hccl-contribute/scripts/contribute.py支持--sync-repo代码同步/worktree 隔离、--issue-ensureIssue 查重与创建、--submit-prPR 提交等子命令提交 PR 场景需要 GitCode tokenexport GITCODE_TOKENtoken且 commit 的git user.email必须与 CLA 签署邮箱一致否则 PR 会被打cann-cla/no。8. Agent 工作原则安全改动十诫AGENTS.md 第 8 节面向 AI Agent 定义了行为边界这些原则对任何在 HCCL 仓库中做自动化改动的开发者同样适用优先小而可审查的变更除非用户明确要求避免大范围重构编辑前先定位文件用 3-6 条说明计划不确定 API、配置、路径或事实时先搜索仓库或查证不要臆造改动src/前先对照第 3 节架构约束是否违反分层依赖是否引入对cann/hcomm的编译期硬依赖应走 dlsym新算子是否落src/ops/标准结构严禁把密钥、token、密码、私钥、.env值或凭据写入代码、日志或回复除非用户要求不新增遥测、分析上报或额外网络调用行为变更应在项目已有测试体系下补充或更新测试优先跑最快相关验证涉及src/目录重命名/移动时同步检查CMakeLists.txt、测试 include 路径、#include相对路径并清理 build 目录后重新验证破坏性命令、git commit、git push必须得到用户明确许可默认用中文解释输出保持简洁、具体、可复制。9. 快速上手指南给初次接触 HCCL 的 Agent结合以上全部规则给初次接触本仓库的 AI Agent 一套最小可执行路径读文档先读本文对应的 AGENTS.md硬约束与入口再读架构权威来源 docs/zh/architecture/architecture-brief.md尤其「3 软件分层逻辑」与末尾「软件架构约束说明」定位代码按第 2 节目录结构快速定位算子src/ops/op/、公共组件src/ops/op_common/、对外接口include/、跨仓解耦src/common/hcomm_dlsym/环境准备按 docs/zh/build/build.md 安装 CANN Toolkit 并source set_env.sh构建验证bash build.sh --pkg出包bash build.sh -u/-s跑 UT/ST推送前完成三件套验证提交 PR遵循第 7 节贡献流程借助 .agents/skills/hccl-contribute/ 自动化链路所有 PR 关联 Issue编码遵循第 5 节规范含 CANN-2.0 许可头与 OAT 合规检查。一句话总结HCCL 仓库的 AI Agent 治理核心就是分层解耦 标准落位——算子走 dlsym 调 HCOMM、新算子落标准结构、改动先对照架构约束理解了这三点就能在保证架构合规的前提下安全、高效地为 HCCL 贡献代码。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HCCL 仓库 AI Agent 协作与开发指南：从架构约束到构建测试的完整实战解析
HCCL 仓库 AI Agent 协作与开发指南从架构约束到构建测试的完整实战解析【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl本文基于 CANN/HCCL 仓库的治理主入口文档 AGENTS.md系统讲解面向 AI 编程工具与开发者的 HCCL 协作规则仓库定位、目录结构、软件架构分层与四大硬性约束、构建测试命令、编码规范与贡献流程。读完本文你将掌握在 HCCL 仓库中安全改动的边界尤其是不得违反分层依赖、不得引入对 HCOMM 的编译期硬依赖等铁律并能独立完成源码构建、UT/ST 验证与从 Issue 到 PR 合入的完整链路。1. 仓库定位HCCL 与 HCOMM 的双子仓结构HCCLHuawei Collective Communication Library是 CANN 的核心集合通信库为昇腾 AI 处理器集群提供高性能、高可靠的集合通信与点对点通信能力。其核心能力包括集合通信原语AllReduce、Broadcast、AllGather、ReduceScatter、AlltoAll 等点对点通信Send/Recv、BatchSendRecv执行模式单算子模式与图模式支撑对象对上支持 AI 框架对下通过 HCOMM 通信基础库使能昇腾 NPU。一个容易被忽略但非常关键的事实是HCCL 并非单仓单体而是双子仓结构。按 AGENTS.md 第 1 节的表述HCCL HCCL 集合通信算子库本仓cann/hccl HCOMM 通信基础库cann/hcomm两仓通过dlsym动态加载解耦可以独立编译、独立版本演进。这一点是整个仓库所有架构约束的源头后续第 3 节的硬性约束几乎都围绕它展开。总体概况可进一步参考 README.md 与架构权威文档 docs/zh/architecture/architecture-brief.md。2. 目录结构一眼定位官方算子与试验代码AGENTS.md 第 2 节给出了仓库的目标目录结构与 README.md 及架构文档中的 目标目录结构 保持一致src/ ├── ops/ # 集合通信算子实现all_reduce/all_gather/broadcast/reduce_scatter/send/recv/... │ └── op_common/ # 公共组件algorithm/{executor,template,topo_match} selector topo_info inc └── common/ # 通用逻辑adapter_acl/alg_env_config/log/param_check/sal/hcomm_dlsym/op_graph/utils/hccl_mc2 experimental/ # 社区贡献的试验性代码当前尚未完全与 src 对齐含 ops/不保证兼容性不编入商用版本 include/ # 对外头文件hccl.h算子 API、hccl_mc2.hMC2 自定义算子框架 test/ # ut / st docs/ # 资料文档 build.sh # 一键编译脚本对照当前仓库实际内容可以验证src/ops/下确实按算子分目录组织all_reduce、all_gather、broadcast、reduce_scatter、send、recv、all_to_all_v、barrier、batch_send_recv 等每个算子目录统一为algorithm/selector/op_graph/结构src/ops/op_common/则是公共组件层包含algorithm/executor/template/topo_match、selector/、topo_info/、inc/等子目录。理解这条目录结构的意义在于在 HCCL 中代码落在哪个目录本身就是一种架构声明。官方新算子必须落在src/ops/op/社区试验算子必须落在experimental/ops/op/二者都遵循selectoralgorithm/{executor,template}的组织方式禁止散落到其他目录详见第 3 节约束 4。3. 软件架构与四大硬性约束核心章节3.1 软件分层AGENTS.md 第 3 节以表格形式给出软件分层与架构文档 docs/zh/architecture/architecture-brief.md 的「3 软件分层逻辑」一节互为印证软件层次仓位置HCCL 集合通信算子coll_comm_opsL1本仓cann/hcclHCOMM 集合通信域管理HCCML2cann/hcommHCOMM 基础通信L3cann/hcomm依赖方向自上而下、单向流动coll_comm_opsHCCL → coll_communicator_mgr → base_comm后两者在 HCOMM 仓3.2 四大架构约束硬性不可违反AGENTS.md 用 ⭐ 标注以下约束为硬性要求任何改动尤其是src/、include/下的代码改动都必须逐条对照约束AI Agent 行为要求分层依赖方向上层依赖下层下层不能反向依赖上层HCOMM 的base_comm↛coll_communicator_mgr↛coll_comm_opsHCCL 不得被 HCOMM 反向依赖HCCL 算子通过 dlsym 调 HCOMM不得要求 HCOMM 反向 include HCCL 头控制面/数据面分离资源管理、拓扑查询控制面与数据搬运/同步数据面接口独立演进HCCL 算子属数据面消费方不得在算子层引入对 HCOMM 控制面内部实现的耦合HCCL 与 HCOMM 解耦HCCL 算子通过dlsym动态加载 HCOMM 接口两仓独立编译、独立版本演进HCCL 不得#includeHCOMM 私有头不得引入对cann/hcomm的编译期硬依赖跨仓调用走src/common/hcomm_dlsym/的符号表 dlsym新算子落标准结构官方新算子落src/ops/op/社区贡献的试验性新算子落experimental/ops/op/结构与src一致不保证兼容性、不编入商用版本。均按selectoralgorithm/{executor,template}组织新算子须提供 selector算法选择与 template引擎模板aicpu/aiv/ccu官方算子落src/ops/社区试验算子落experimental/ops/禁止散落其他目录源码级佐证dlsym 解耦的实现落点HCCL 与 HCOMM 解耦不是一句口号而是有具体代码支撑的。跨仓调用的实现集中在 src/common/hcomm_dlsym/ 目录该目录以*_dl.cc/*_dl.h形式为每类 HCOMM 接口维护独立的动态加载封装如hccl_dl.cc、hccl_res_dl.cc、hccl_rank_graph_dl.cc、hcomm_primitives_dl.cc、hcomm_diag_dl.cc、hcomm_device_profiling_dl.cc等。以最基础的加载入口为例src/common/hcomm_dlsym/hccl_dl.cc 中可以看到对dlopen/dlsym的直接封装void* __HcclDlsym(void* handle, const char* funcName) { return dlsym(handle, funcName); } void* __HcclDlopen(const char* libName, int mode) { return dlopen(libName, mode); }而 src/common/hcomm_dlsym/dlsym_common.h 则展示了另一层关键细节跨版本兼容。它通过 CANN 版本号宏如CANN_VERSION(9, 0, 0)在编译期判断当前 CANN 版本对 9.0.0、9.1.0 等边界版本缺少的类型如HcclCommStatus、ThreadHandle做条件桩定义从而保证同一份 HCCL 源码可以跨多个 CANN 版本动态加载 HCOMM 接口——这正是独立编译、独立版本演进得以成立的技术基础。这也解释了为什么 build.sh 中会存在hccl_compat.map、hccl_kernel_compat.map等符号兼容映射文件位于 src/common/hcomm_dlsym/。3.3 对外 API 分层AGENTS.md 第 3 节同时给出了对外 API 的层次划分层次头文件面向L1 算子include/hccl.hAI 框架适配层AllReduce/Broadcast/AllGather/ReduceScatter/AlltoAll/Send/Recv 等MC2 自定义算子include/hccl_mc2.h自定义通信算子开发者KfcOpArgs/OpResCtx 等在 include/hccl.h 中可以确认 L1 算子接口的真实签名例如HcclAllReduce(void* sendBuf, void* recvBuf, uint64_t count, HcclDataType dataType, HcclReduceOp op, HcclComm comm, aclrtStream stream)HcclBroadcast(void* buf, uint64_t count, HcclDataType dataType, uint32_t root, HcclComm comm, aclrtStream stream)HcclSend/HcclRecv、HcclAllGather、HcclReduceScatter、HcclAlltoAll、HcclAlltoAllV、HcclAlltoAllVC、HcclBatchSendRecv等一应俱全均以extern C导出以兼容框架层 C 接口调用。关键要求是include/变更需向后兼容——这是对外的契约任何接口签名调整都必须考虑存量 AI 框架适配层的影响。更完整的 API 分层关系L1/L2-comm/L2-res-rank_graph/L3-prim/L3-res见 docs/zh/architecture/architecture-brief.md 的「3.3 对外API分层关系」一节。4. 构建与测试build.sh 全参数实战AGENTS.md 第 4 节给出了最常用的构建与测试命令本文结合 build.sh 实际源码将其展开为完整参数说明。4.1 核心命令速查bash build.sh --pkg # 编译 host 包默认 bash build.sh -u # 编译并运行 UT bash build.sh -s # 编译并运行 ST bash build.sh --static # 静态库构建 bash build.sh --asan # 启用 AddressSanitizer bash build.sh --custom_ops_pathPATH # 自定义算子工程 bash build.sh -j64 # 并行编译4.2 参数全表依据 build.sh usage 展开从 build.sh 的usage()函数可提取完整参数语义参数含义备注-h, --help打印使用说明—--asan启用 AddressSanitizer内部追加-DENABLE_ASANON运行测试时还会按架构自动设置libasan.so的LD_PRELOAD--build-typeTYPE构建类型Release / Debug默认 Release脚本内CMAKE_BUILD_TYPE初始为 Debug最终由该参数决定-jN编译并行线程数默认按 CPU 核数 ×2 自动计算也可显式-j64--pkg-typeTYPE打包类型run / rpm / deb / all默认 run非法值直接报错退出--cann_3rd_lib_pathPATH昇腾第三方依赖包安装路径默认./output/third_party-p, --package-path PATHCANN 软件包安装路径默认/usr/local/Ascend/cann脚本会按-p→ASCEND_HOME_PATH→ASCEND_OPP_PATH→ 默认安装目录的顺序自动探测--sign-script PATH/--enable-sign签名脚本路径 / 使能签名商用包签名用--version VERSION签名版本号默认从 version.cmake 的VERSION字段读取当前为 9.2.0--custom_ops_pathPATH/--opsOPS/--vendorVENDOR自定义算子工程路径、算子名、vendor三者任一带上即进入自定义算子编译分支--experimental使能试验特性追加-DENABLE_EXPERIMENTALON--static静态库构建模式走build_staticpackage_static_tar流程产出libhccl_static.a与cann-hccl-static_VERSION_linux-arch.tar.gz-s, --st运行全部系统测试ST设置ENABLE_TESTon、ENABLE_STon--st_opsOPS1,OPS2,...运行指定 ST 算子用例支持 scatter、all_reduce、all_gather、reduce_scatter、broadcast、alltoall、alltoallv、alltoallvc 等--cov使能代码覆盖率插桩ST 场景下会生成 lcov 覆盖率报告--noexec只构建测试不执行—--aicpu/--full编译设备侧 AICPU 内核--full同时置位ENABLE_BUILD_DEVICE4.3 环境准备与前置依赖完整构建流程的前置依赖见 docs/zh/build/build.md「前置依赖」节python 3.7.0、pip3 20.3.0gcc g7.3.0 至 14.2.xcmake 3.16.0ccache可选提高二次编译速度googletest仅执行 UT 时依赖建议 release-1.14.0。同时需安装 CANN Toolkit 开发套件包并正确source set_env.sh例如source CANN安装路径/cann/set_env.sh。NPU 驱动、固件和 CANN ops 算子包为运行态依赖仅编译源码可不安装但运行或上板测试前必须安装。官方推荐优先使用 Docker 构建镜像镜像内预装构建工具及 CANN 软件或宿主机部署两种方式详见 docs/zh/build/build.md。4.4 静态库构建的 8 步流水线bash build.sh --static是一条值得单独说明的复杂链路。从 build.sh 的build_static()函数可以看到它实际是一条多阶段流水线初始化交叉编译工具链init_toolchainaarch64 场景使用aarch64-target-linux-gnu-*工具链构建设备端 AICPU 包产出aicpu_hccl.tar.gz构建主机端静态库libhccl_static.a并同步构建 AIV 设备 kernelaiv_all_targets产出hccl_aiv_*_op_910_95.o/hccl_aiv_*_op_960.o用ar -x解压静态库为.o文件用ld -r -b binary将 AICPU tar 包转为二进制对象aicpu_hccl_tar.o将 AIV kernel.o转成 binary embed 对象并注入_binary_..._start/end/size符号将全部.o打包为最终静态库libhccl_static_final.a复制到标准输出位置libhccl_static.a清理临时目录随后package_static_tar打出cann-hccl-static_VERSION_linux-arch.tar.gz。这解释了为何静态库能同时包含 host 端算子逻辑、AICPU 内核与 AIV 内核——它们以二进制嵌入对象的形式被打包进同一个.a文件。该能力对应 README 中Ascend950 通信算子支持静态库的发布特性。4.5 推送前验证AGENTS.md 明确建议推送前优先本地验证--pkg--ut--st三件套。UT 用例位于 test/ut如 alltoall_hier、recursive_executor、reduce_scatter_birs、common 等目录ST 用例位于 test/st/algorithmtestcase utils 双层结构通过 CTest 并发执行、单用例超时 350s、失败即停。5. 编码规范从命名到 CI 静态检查AGENTS.md 第 5 节定义了仓库级编码规范本文对照根目录 .clang-format 实际配置做进一步确认命名类/函数 PascalCase成员变量camelCase_小驼峰 后缀下划线常量与宏UPPER_SNAKE_CASE风格遵循根目录.clang-format。实测关键配置项为ColumnLimit: 120120 列、IndentWidth: 44 空格缩进、PointerAlignment: Left指针左对齐、Standard: Latest大括号采用 KRBreakBeforeBraces: Custom语言标准为 C14静态告警代码须通过 CANN 静态检查要求CI codecheck 阶段校验编译无告警pre-commitclang-format v18.1.8 OAT 合规检查新增源文件须带 CANN-2.0 许可头。关于许可头OAT.xml 中配置了policyitem typelicense nameCANN-2.0 path.*的默认许可策略即仓库内所有文件默认要求 CANN-2.0 许可头。以 include/hccl.h 文件头为例可以直观看到标准许可头模板的格式Copyright © 2025 Huawei Technologies Co., Ltd. CANN Open Software License Agreement Version 2.0 声明新增源文件应与此保持逐字节一致。相关规范参考 CANN 编码规范外部社区仓按需查阅与仓内 docs/zh/build/pre-commit-guide.md。6. 文档编写规范两条特殊规则AGENTS.md 第 6 节给出了文档目录组织与产品名称的硬性规则目录组织docs/zh/中文与docs/en/英文分开存放API 文档使用 PascalCase如HcclAllReduce.md环境变量文档使用 UPPER_SNAKE_CASE如HCCL_ALGO.md。对照当前仓库 docs/zh 目录api_ref/comm_op_interface/下的HcclAllReduce.md、HcclAllGather.md等确实遵循 PascalCase而user_guide/hccl_env/下的HCCL_ALGO.md、HCCL_BUFFSIZE.md等遵循 UPPER_SNAKE_CASE验证了这一规则已被严格执行。产品名称特殊规则单位与数字、中文与英文之间不加空格如50m、昇腾AI处理器但产品名称内部允许保留空格如Ascend 950PR/Ascend 950DT、Atlas A3 训练系列产品以保持官方产品标识的完整性和可读性。7. 贡献流程从 Issue 到 PR 合入的端到端链路AGENTS.md 第 7 节按问题类型区分了两条贡献路径简单问题Issue → 认领 → PR → Committer 检视 →/lgtm/approve合入新功能Requirement Issue → SIG 决策 →docs/zh/rfcs/RFC 评审 → 实现含 UTST→ 检视合入。仓库内 docs/zh/rfcs 目录已有 3 篇 RFC0001-add-batch-invariant-reducescatter.md、0002-HCCL-ALGO-Plugin.md、0003-executor-template-refactor.md可作为新功能 RFC 的格式参考。所有 PR 必须关联 Issue描述按.gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md填写。更完整的贡献规范见 CONTRIBUTING.md。7.1 仓内自动化 skillhccl-contribute 与 hccl-reviewAGENTS.md 特别指出从代码获取到 PR 合入的贡献链路操作代码同步、Issue 查重创建、PR 提交触发 CI、CI 轮询与失败修复、检视意见处置应使用仓内贡献流程 skill——.agents/skills/hccl-contribute/开发提交自检与检视他人 PR 使用 .agents/skills/hccl-review/。从 .agents/skills/hccl-contribute/SKILL.md 可以看到该 skill 的完整工作流Step 1 代码获取与更新 → Step 2 依赖环境确认 → Step 3 本地构建与测试 ↓ Step 8 检视意见处置 ← Step 7 CI 失败修复 ← Step 6 CI 监控 ← Step 5 PR 创建与提交 ↑ Step 4 Issue 查重与创建每个子流程可独立运行例如只修 CI 从 Step 7 起步、只处理检视意见从 Step 8 起步。核心命令统一为python3 .agents/skills/hccl-contribute/scripts/contribute.py支持--sync-repo代码同步/worktree 隔离、--issue-ensureIssue 查重与创建、--submit-prPR 提交等子命令提交 PR 场景需要 GitCode tokenexport GITCODE_TOKENtoken且 commit 的git user.email必须与 CLA 签署邮箱一致否则 PR 会被打cann-cla/no。8. Agent 工作原则安全改动十诫AGENTS.md 第 8 节面向 AI Agent 定义了行为边界这些原则对任何在 HCCL 仓库中做自动化改动的开发者同样适用优先小而可审查的变更除非用户明确要求避免大范围重构编辑前先定位文件用 3-6 条说明计划不确定 API、配置、路径或事实时先搜索仓库或查证不要臆造改动src/前先对照第 3 节架构约束是否违反分层依赖是否引入对cann/hcomm的编译期硬依赖应走 dlsym新算子是否落src/ops/标准结构严禁把密钥、token、密码、私钥、.env值或凭据写入代码、日志或回复除非用户要求不新增遥测、分析上报或额外网络调用行为变更应在项目已有测试体系下补充或更新测试优先跑最快相关验证涉及src/目录重命名/移动时同步检查CMakeLists.txt、测试 include 路径、#include相对路径并清理 build 目录后重新验证破坏性命令、git commit、git push必须得到用户明确许可默认用中文解释输出保持简洁、具体、可复制。9. 快速上手指南给初次接触 HCCL 的 Agent结合以上全部规则给初次接触本仓库的 AI Agent 一套最小可执行路径读文档先读本文对应的 AGENTS.md硬约束与入口再读架构权威来源 docs/zh/architecture/architecture-brief.md尤其「3 软件分层逻辑」与末尾「软件架构约束说明」定位代码按第 2 节目录结构快速定位算子src/ops/op/、公共组件src/ops/op_common/、对外接口include/、跨仓解耦src/common/hcomm_dlsym/环境准备按 docs/zh/build/build.md 安装 CANN Toolkit 并source set_env.sh构建验证bash build.sh --pkg出包bash build.sh -u/-s跑 UT/ST推送前完成三件套验证提交 PR遵循第 7 节贡献流程借助 .agents/skills/hccl-contribute/ 自动化链路所有 PR 关联 Issue编码遵循第 5 节规范含 CANN-2.0 许可头与 OAT 合规检查。一句话总结HCCL 仓库的 AI Agent 治理核心就是分层解耦 标准落位——算子走 dlsym 调 HCOMM、新算子落标准结构、改动先对照架构约束理解了这三点就能在保证架构合规的前提下安全、高效地为 HCCL 贡献代码。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考