企业官网建设流程全解析

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 的"双子仓"结构

HCCL（Huawei 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.h（MC2 自定义算子框架） 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>/，二者都遵循selector+algorithm/{executor,template}的组织方式，禁止散落到其他目录（详见第 3 节约束 4）。

3. 软件架构与四大硬性约束（核心章节）

3.1 软件分层

AGENTS.md 第 3 节以表格形式给出软件分层，与架构文档 docs/zh/architecture/architecture-brief.md 的「3 软件分层逻辑」一节互为印证：

依赖方向自上而下、单向流动：

coll_comm_ops（HCCL） → coll_communicator_mgr → base_comm（后两者在 HCOMM 仓）

3.2 四大架构约束（硬性，不可违反）

AGENTS.md 用 ⭐ 标注以下约束为硬性要求，任何改动（尤其是src/、include/下的代码改动）都必须逐条对照：

源码级佐证：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 的层次划分：

在 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_path=<PATH> # 自定义算子工程 bash build.sh -j64 # 并行编译

4.2 参数全表（依据 build.sh usage 展开）

从 build.sh 的usage()函数可提取完整参数语义：

4.3 环境准备与前置依赖

完整构建流程的前置依赖（见 docs/zh/build/build.md「前置依赖」节）：

• python >= 3.7.0、pip3 >= 20.3.0；
• gcc & g++：7.3.0 至 14.2.x；
• cmake >= 3.16.0；
• ccache（可选，提高二次编译速度）；
• 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()函数可以看到，它实际是一条多阶段流水线：

1. 初始化交叉编译工具链（init_toolchain，aarch64 场景使用aarch64-target-linux-gnu-*工具链）；
2. 构建设备端 AICPU 包，产出aicpu_hccl.tar.gz；
3. 构建主机端静态库libhccl_static.a，并同步构建 AIV 设备 kernel（aiv_all_targets，产出hccl_aiv_*_op_910_95.o/hccl_aiv_*_op_960.o）；
4. 用ar -x解压静态库为.o文件；
5. 用ld -r -b binary将 AICPU tar 包转为二进制对象（aicpu_hccl_tar.o），将 AIV kernel.o转成 binary embed 对象并注入_binary_..._start/end/size符号；
6. 将全部.o打包为最终静态库libhccl_static_final.a；
7. 复制到标准输出位置libhccl_static.a；
8. 清理临时目录，随后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/algorithm（testcase + utils 双层结构，通过 CTest 并发执行、单用例超时 350s、失败即停）。

5. 编码规范：从命名到 CI 静态检查

AGENTS.md 第 5 节定义了仓库级编码规范，本文对照根目录 .clang-format 实际配置做进一步确认：

• 命名：类/函数 PascalCase；成员变量camelCase_（小驼峰 + 后缀下划线）；常量与宏UPPER_SNAKE_CASE；
• 风格：遵循根目录.clang-format。实测关键配置项为ColumnLimit: 120（120 列）、IndentWidth: 4（4 空格缩进）、PointerAlignment: Left（指针左对齐）、Standard: Latest，大括号采用 K&R（BreakBeforeBraces: Custom）；语言标准为 C++14；
• 静态告警：代码须通过 CANN 静态检查要求（CI codecheck 阶段校验），编译无告警；
• pre-commit：clang-format v18.1.8 + OAT 合规检查；新增源文件须带 CANN-2.0 许可头。

关于许可头，OAT.xml 中配置了policyitem type="license" name="CANN-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 评审 → 实现（含 UT+ST）→ 检视合入。

仓库内 docs/zh/rfcs 目录已有 3 篇 RFC（0001-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 仓内自动化 skill：hccl-contribute 与 hccl-review

AGENTS.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-ensure（Issue 查重与创建）、--submit-pr（PR 提交）等子命令；提交 PR 场景需要 GitCode token（export GITCODE_TOKEN=<token>），且 commit 的git user.email必须与 CLA 签署邮箱一致，否则 PR 会被打cann-cla/no。

8. Agent 工作原则：安全改动十诫

AGENTS.md 第 8 节面向 AI Agent 定义了行为边界，这些原则对任何在 HCCL 仓库中做自动化改动的开发者同样适用：

1. 优先小而可审查的变更；除非用户明确要求，避免大范围重构；
2. 编辑前先定位文件，用 3-6 条说明计划；
3. 不确定 API、配置、路径或事实时，先搜索仓库或查证，不要臆造；
4. 改动src/前先对照第 3 节架构约束：是否违反分层依赖？是否引入对cann/hcomm的编译期硬依赖（应走 dlsym）？新算子是否落src/ops/标准结构？
5. 严禁把密钥、token、密码、私钥、.env值或凭据写入代码、日志或回复；
6. 除非用户要求，不新增遥测、分析上报或额外网络调用；
7. 行为变更应在项目已有测试体系下补充或更新测试，优先跑最快相关验证；
8. 涉及src/目录重命名/移动时，同步检查CMakeLists.txt、测试 include 路径、#include相对路径，并清理 build 目录后重新验证；
9. 破坏性命令、git commit、git push必须得到用户明确许可；
10. 默认用中文解释；输出保持简洁、具体、可复制。

9. 快速上手指南：给初次接触 HCCL 的 Agent

结合以上全部规则，给初次接触本仓库的 AI Agent 一套最小可执行路径：

1. 读文档：先读本文对应的 AGENTS.md（硬约束与入口），再读架构权威来源 docs/zh/architecture/architecture-brief.md（尤其「3 软件分层逻辑」与末尾「软件架构约束说明」）；
2. 定位代码：按第 2 节目录结构快速定位算子（src/ops/<op>/）、公共组件（src/ops/op_common/）、对外接口（include/）、跨仓解耦（src/common/hcomm_dlsym/）；
3. 环境准备：按 docs/zh/build/build.md 安装 CANN Toolkit 并source set_env.sh；
4. 构建验证：bash build.sh --pkg出包，bash build.sh -u/-s跑 UT/ST，推送前完成三件套验证；
5. 提交 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