企业官网建设流程全解析

HCCL 的 RFC 机制：从方案对齐到代码落地的技术决策流程与实践指南

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl

HCCL（Huawei Collective Communication Library）在docs/en/rfcs/目录下维护了一套面向技术方案设计的 RFC（Request for Comments）机制，用于在编码实现之前对齐解决方案、记录设计决策。本文以该目录的 README.md 为核心骨架，结合 RFC 模板、编号注册表、三个已合并的 RFC 实例以及仓库源码，完整讲解 HCCL 的 RFC 编号规则、两级 PR 流程、文档生命周期、模板写作要求，以及 RFC 与experimental/目录代码落地的衔接方式。读完本文，你将掌握为 HCCL 提交一个 RFC 从需求发起、编号抢占、文档评审到最终合并的完整路径，并能对照仓库中的真实 RFC 理解其设计深度。

一、为什么 HCCL 需要 RFC 机制

集合通信库的每一次演进都牵动算子算法、拓扑适配、资源调度等多层代码。若无前置的方案对齐，容易出现两种问题：一是实现完成后才发现设计方向错误，返工成本极高；二是多人并行开发时对关键术语、接口契约的理解不一致，导致评审和联调困难。

RFC 机制正是为化解这些风险而设：它在编码实现之前，用一份结构化的文档把"做什么、为什么这样做、接口契约是什么、影响范围有多大"固定下来，作为后续代码实现的契约。从 CONTRIBUTING_en.md 的贡献流程图可以看到，新增特性（New Feature）的必经路径是：提交 Requirement Issue → SIG 决策 → 设计系统方案 → 编写/修改 RFC → 提交 RFC 文档 PR → Maintainer 评审 → 合并 RFC → 再进入代码实现。也就是说，RFC 合并是代码 PR 的前置门槛，合并后的 RFC 方案即成为代码实现必须遵循的合同。

当前docs/en/rfcs/目录中已有 3 个 RFC 完成合并并进入代码落地阶段，分别对应三种典型的演进诉求（详见第七节）：新算法引入（BIRS）、自定义算法扩展框架（HCCL-ALGO-Plugin）、执行器架构重构（recursive_executor）。

二、RFC 目录结构与文件命名规则

HCCL 的 RFC 文档全部存放在 docs/en/rfcs/ 目录，分为三类文件：

RFC 文件的命名格式为：

{4-digit number}-{short description}.md

例如0001-add-new-feature.md。具体约束如下：

• 编号：4 位数字、零填充，范围0001到9999；
• 描述：英文小写、短横线分隔、简洁明了。

仓库中的真实命名示例：

• 0001-add-batch-invariant-reducescatter.md—— BIRS 算法 RFC
• 0002-HCCL-ALGO-Plugin.md—— 自定义算法扩展框架 RFC
• 0003-executor-template-refactor.md—— 执行器模板重构 RFC

这种"编号 + 语义化短描述"的命名方式，让开发者仅凭文件名即可快速判断某个 RFC 的主题，同时保证编号可作为唯一索引在INDEX.md中登记和追溯。

三、编号机制（核心）：两级 PR、最小号优先、永不回收

RFC 编号的分配是整套机制的核心，采用number-claiming PR（轻量）+ RFC document PR（重量）的两级流程，把"占号"和"写文档"解耦：

1. Number-claiming PR（轻量）：只修改 INDEX.md，新增一行占位记录，为编号预留名额。该 PR 只包含 INDEX.md 的一行更新，评审成本极低，目的就是尽早把编号锁定，避免后续文档写完后才发现编号冲突。
2. RFC document PR（重量）：编写 RFC 文档并提交评审。此时编号已通过 number-claiming PR 锁定，无需再担心被别人抢占。

编号分配遵循三条硬性规则：

• 顺序分配，最小未用编号优先：新编号取当前已分配的最大编号 + 1（或表中最小的空缺号）；
• 永不回收：即使某个 RFC 后来被取代（superseded），其编号也绝不回收复用；
• 冲突解决：若两人同时抢占同一编号，后提交者必须 rebase 并改用新的最小编号。

对应地，INDEX.md 中的状态字段定义了三种取值：

截至当前仓库，编号注册表 INDEX.md 已登记0001（BIRS for A3，状态accepted，对应 PR #1440），其余编号按规则依次可分配给后续需求。

四、RFC 生命周期：七阶段全流程

README.md 将 RFC 的生命周期划分为七个阶段，与 CONTRIBUTING_en.md 中的贡献流程一一对应：

阶段 1：需求发起（Requirement phase）提交 Requirement 类型的 Issue，等待 SIG 组接受。只有被 SIG 接受的需求（Issue 打上accepted标签）才能进入 RFC 流程。这一步是"值得不值得做"的关口，避免资源浪费在低价值需求上。

阶段 2：编号抢占 PR（Number-claiming PR）在 INDEX.md 中按"最小未用编号"规则新增一行占位记录，状态置为reserved，提交 number-claiming PR。标题和作者可以先用占位符。

阶段 3：占号 PR 合并编号被锁定（状态保持reserved），此时可以开始编写 RFC 文档。

阶段 4：写作阶段（Writing phase）严格依照 RFC 模板 编写系统方案。模板的各章节要求详见第五节。

阶段 5：评审阶段（Review phase）提交 RFC 文档 PR 进行评审，根据反馈持续修改方案。评审在 PR 评论区进行（三个已合并 RFC 均遵循此惯例，详见其文档末尾的 Review Records 章节）。

阶段 6：决策阶段（Decision phase）

• 合并（Merged）：Maintainer 通过评审，打上/lgtm和/approve标签后合并；随后将 INDEX.md 中对应行状态更新为accepted，RFC 正式生效。
• 关闭（Closed）：评审未通过，PR 被关闭。编号保持reserved且不回收，作者可重新发起评审流程。

阶段 7：实现阶段（Implementation phase）合并后的 RFC 作为实现契约，后续代码 PR 必须遵循 RFC 方案。这也是 RFC 与 CONTRIBUTING_en.md 中"RFC 合并 → 软件实现 → 代码评审合并"流程的衔接点。

五、RFC 模板解析：一份合格方案文档的必备章节

RFC 模板 是 RFC 文档的写作规范，任何新 RFC 都必须遵循。模板头部要求填写三个元信息字段：

• Start Date：起始日期（YYYY-MM-DD 格式）；
• RFC PR Number：关联的 PR 号；
• Related Issue：关联的需求 Issue 号。

正文部分定义了以下章节，每个章节都有明确的写作意图：

以仓库中的实际 RFC 为例可以直观看到模板的落地效果：

• 0001 BIRS RFC 完整覆盖了 Summary、Background（含行业确定性通信需求的多场景论证）、Detailed Design（逻辑 2D 拓扑、Scratch 内存布局、3 线程模型、主通信循环伪代码、FinalStep 树形归约）、Compatibility（平台/rankSize/对齐约束表）、Test Plan、Risk Assessment；
• 0002 HCCL-ALGO-Plugin RFC 额外使用了 mermaid 时序图描述自定义算法调用的三阶段流程，并给出完整的 C 接口定义（HcclAlgoPlugin_t函数表、HcclAlgoPluginParamABI 结构、REGISTER_HCCL_ALGO宏）；
• 0003 executor-template-refactor RFC 包含了类图、流程图、时序图与大量可编译的 C++ 代码片段，并给出了新旧架构的代码量对比表。

六、Supersession：RFC 被取代时的处理规范

当某个 RFC 的实现被后续 RFC 取代时，按以下规则处理（对应 README.md 的 Supersession 章节和 INDEX.md 的编号规则）：

1. 在被取代的 RFC 文档末尾追加一行标注：> Superseded by 00NN；
2. 将 INDEX.md 中对应行状态从accepted更新为superseded；
3. 不修改原始编号——编号一经分配永不回收，保证历史可追溯。

这套规范保证了 RFC 编号作为稳定标识符的语义完整性：即使方案被演进取代，研究者依然可以通过编号定位到原始设计文档，并通过Superseded by标注追踪演进脉络。

七、已落地 RFC 实例：从方案到代码的三种范式

RFC 的生命力在于落地。当前仓库的三个 RFC 均已进入实现阶段，且代码位置与 RFC 中声明的目录一一对应，可以作为"RFC 方案 → 代码契约"的实证样本：

7.1 0001 BIRS：新增算法与编译/运行时双门控

0001 RFC 提出 BIRS（Batchsize Invariant ReduceScatter）算法，针对昇腾 A3 服务器 SIO + HCCS 混合互联拓扑，在保证确定性归约顺序（bit 级可复现）的前提下提升大消息场景带宽利用率。其代码落地遵循 RFC 声明的隔离策略：

• 新增experimental/ops/reduce_scatter/birs/目录承载算法实现（executor 层、executor 基类、核心算法模板reduce_scatter_birs.cc/.h、中间结果处理reduce_scatter_birs_inter.cc/.h）；
• 通过编译选项ENABLE_EXPERIMENTAL（构建命令bash build.sh --pkg --full --experimental）与运行时环境变量HCCL_BIRS_ENABLE实现双重门控，默认关闭、对既有 ReduceScatter 行为零影响；
• 用户侧 API 不变，仍调用标准HcclReduceScatter()，算法选择完全由环境变量控制。

RFC 中还明确了适用约束：仅限 A3 平台、rankSize 必须为偶数（典型值 4/8/16）、切片需满足HCCL_MIN_SLICE_ALIGN_910B对齐要求；不满足条件时由MatchBIRS()检查自动回退到既有算法。

7.2 0002 HCCL-ALGO-Plugin：自定义算法动态库扩展框架

0002 RFC 设计了一套"零侵入"的自定义算法扩展框架，解决既有算法添加时面临的代码侵入、构建耦合、发布依赖与选择逻辑封闭四大问题。其代码落地于 src/algo_plugin/：

• HcclAlgoPluginMgr（hccl_algo_plugin_mgr.cc）作为单例嵌入 HCCL 主库，通过dlopen加载 PluginBroker 动态库并持有其函数表指针；
• 自定义算法通过 SDK 宏REGISTER_HCCL_ALGO(algName, soPath, fnSymbol)注册为全局静态对象，加载时由构造函数自动写入私有注册表；
• 算法选择与执行分别经SelectAlg()/ExecuteAlg()接口路由，无自定义算法匹配时自动回退到原始选择逻辑。

该框架以 CMake 选项ENABLE_HCCL_ALGO_PLUGIN（默认 OFF）编译门控，以环境变量HCCL_ALGO_PLUGIN_PATH（PluginBroker 路径）与HCCL_PLUGIN_ALG_DIR（自定义算法根目录）运行时控制，未配置时所有新分支直接跳过，HCCL 行为完全不变。

7.3 0003 recursive_executor：执行器架构重构与插件式集成

0003 RFC 提出以HcclAlgorithm（静态算法描述）、OpsExecutor（通用解释器）、Template（单层执行单元）、CommPlanner（通信计划生成器）四层结构统一算法编排，将 53 个专用 Executor 合并为 1 个通用执行器。其代码落地于 experimental/ops/op_common/recursive_executor/，目录结构与 RFC 声明完全一致：

• inc/algo_desc.h：HcclAlgorithm/AlgoExecDesc/TemplateExecDesc三层描述结构；
• executor/：AdaptorExecutor（桥接 src 的InsCollAlgBase）与OpsExecutor（递归编排）；
• selector/alg_selector.cc：算法注册表，按算法名查询HcclAlgorithm；
• template/aicpu/与template/comm_planners/：AllGather Mesh/NHR 模板与通信计划器；
• topo/topo_match_four_level.cc：四级拓扑匹配器。

该重构遵循 experimental/README_en.md 的运行时开关规范：REGISTER_ALG宏在静态初始化时被IsRecursiveExecutorEnabled()守卫，编译期常量recursiveExecutorEnabled默认false，环境变量HCCL_EXPERIMENTAL_RECURSIVE_EXECUTOR=true仅在常量开启后才生效，确保实验代码不会误入主链路。对应测试位于 test/ut/recursive_executor/（algo_desc_test.cc及配套 stub）。

八、RFC 与代码落地的衔接：experimental/ 目录与运行时开关

RFC 机制与experimental/贡献目录构成了 HCCL 社区"方案先行、原型验证、成熟合入"的完整闭环。从 experimental/README_en.md 可以看到两者在制度上的呼应：

而 CONTRIBUTING_en.md 进一步规定：社区贡献的新算子、新算法或扩展特性原则上必须提交到experimental/目录，尽量避免修改src/下的稳定代码；确需修改时必须说明理由与影响范围并获得 Committer 评审。此外，实验特性必须提供运行时开关以便快速回滚，开关命名为HCCL_EXPERIMENTAL_<NAME>=true，并遵循IsXxxEnabled()的标准实现模式（编译期常量优先、默认关闭）。

这一制度的实际效果可以从三个 RFC 的落地方案中看到共性模式：

1. 编译期隔离：实验代码置于独立目录，通过 CMake 选项（ENABLE_EXPERIMENTAL、ENABLE_HCCL_ALGO_PLUGIN）或 OBJECT 库方式控制是否参与编译；
2. 运行时门控：默认关闭的环境变量开关（HCCL_BIRS_ENABLE、HCCL_ALGO_PLUGIN_PATH、HCCL_EXPERIMENTAL_RECURSIVE_EXECUTOR）；
3. 用户 API 不变：算法选择对用户透明，不引入新的对外接口；
4. 自动回退：条件不满足或插件未匹配时，自动回退到原始算法选择与执行逻辑。

九、给贡献者的实践要点

综合 RFC 目录 README、编号注册表 与 贡献指南，为 HCCL 提交一个 RFC 的核心检查清单如下：

1. 先提需求 Issue：提交 Requirement 类型 Issue 并等待 SIG 接受，避免方案未获认可就投入写作；
2. 尽早占号：SIG 接受后立即提交只含 INDEX.md 一行更新的 number-claiming PR，锁定最小未用编号（状态reserved）；
3. 严格按模板写作：以 RFC 模板 为骨架，重点写透 Summary（30 秒可读完核心决策）、Architecture and Interface Contract、Impact Analysis、Compatibility Considerations 与 Test Plan；
4. 评审充分迭代：RFC 文档 PR 的评审在评论区进行，根据反馈持续修改，合并需 Maintainer 打/lgtm与/approve；
5. 合并后更新状态：RFC 合并后立即将 INDEX.md 对应行状态改为accepted；
6. 实现遵循契约：代码 PR 必须遵循已合并 RFC 的方案，实验代码落在experimental/目录并提供运行时开关；
7. 被取代时规范标注：如方案被后续 RFC 取代，在原文档末尾添加> Superseded by 00NN并将注册表状态更新为superseded，编号永不回收。

通过这套机制，HCCL 将"设计决策"沉淀为可检索、可追溯、可引用的文档资产——任何一个新特性从立项到落地都有据可查，这正是大型基础设施项目在快速演进中保持架构一致性的关键保障。

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl