HCCL PR 检视规范PR 描述与测试完备性核查指南【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl导读本文面向向 CANN / hccl昇腾集合通信库提交代码的开发者与代码检视者系统讲解 HCCL 仓库在 PR 检视环节对「PR 描述、关联 Issue 与实现三者一致性」的核查规范。读完本文你将掌握如何判断一个 PR 是否声称了但没做或做了但没说、如何核验功能实现与调用方适配、UT/ST 测试完备性到什么程度才算达标以及接口/模块变更时文档同步的最低要求。文中所有规范均出自仓内检视规范 pr-completeness.md并辅以源码、CI 流水线与测试用例佐证。一、检视规范在 HCCL 治理体系中的位置HCCL 仓库为代码检视场景提供了完整的 Agent/人工检视技能包入口为 .agents/skills/hccl-review/SKILL.md其流程按「准备基线 → 读代码与行号实证 → 多维检视 → 汇总提交 → 清理」五步执行。检视规范按五类分档组织索引见 .agents/skills/hccl-review/references/README.md规范文档覆盖范围加载时机coding-and-security.md命名风格、内存/资源/并发/错误处理红线、工具验证纪律所有代码 PR 必读external-api.md对外头文件include/ 等C 接口、ABI、兼容性、模块变更PR 触碰 include/ 或新增类/文件/目录时architecture.md分层依赖、控制面/数据面分离、仓间解耦、legacy 约束PR 触碰 src/ 时pr-completeness.mdPR/Issue/实现三者吻合度、测试完备性、文档同步所有 PRgitcode-api.mdGitCode API 端点、认证、position 语义提交检视意见时其中 pr-completeness.md 是对所有 PR 通用的检视维度——无论代码改动规模大小PR 描述与实现的吻合度、测试覆盖、文档同步都是必查项。它在 SKILL.md 的「通用检视维度」中对应 测试覆盖生产代码变更是否补 UT/ST 与 PR/Issue 描述与实现的吻合度 两条。二、PR / Issue 与实现的吻合度核查2.1 双向核验防声称了但没做也防做了但没说规范要求检视者做双向比对描述 → diffPR 描述声称的每个改动点都能在 diff 中找到对应实现。这条防的是声称了但没做——例如描述里写新增了对 XX 场景的容错处理但 diff 里根本没有相关分支。diff → 描述diff 中的核心变更必须在描述中有交代。这条防的是做了但没说尤其是不在声称范围内的夹带修改——例如本来只修 bug却悄悄改了算法选择逻辑或日志级别这类变更必须显式声明。从检视工具链看pr_review.py 提供了辅助机制--pr N --meta可获取 PR 元数据title/body/head_sha/base_sha/changed_files--pr N --files取 GitCode API 的权威变更文件列表检视前还会做基线漂移核验check_baseline_drift当本地git diff的文件数远超 API 声明的 changed_files2 倍且多 5 个以上时直接拒绝检视防止把意见发到非本 PR 的代码上。2.2 关联 Issue 的逐条覆盖关联 Issue 的诉求逐条被实现覆盖且实现未超出Issue 范围引入无关变更PR 描述须按 .gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md 填写。该模板明确要求以下小节描述改动原因与所采取的方法关联的IssueIssue 链接不涉及则填 NA测试进行了哪些测试验证构造对应 xx 测试用例、二级冒烟、算子泛化等文档更新本次是否包含文档更新如更新了 README.md类型标签Bug修复 / 新特性 / 性能优化 / 文档更新 / 其他[x]表示选中。仓库级贡献规则AGENTS.md 第 7 节、CONTRIBUTING.md同样强调所有 PR 必须关联 Issue描述按 PR 模板填写新功能还要求先走 RFC 评审流程Requirement Issue → SIG 决策 → RFC 文档 PR 评审 → 合入后按 RFC 实现并提交 PR且必须包含对应 UT 与 ST。2.3 功能正确性读完整函数体而非只看 diff对照描述逐条核验实现逻辑是否达成目标。核心逻辑必须读完整函数体而不是只扫一眼 diff 片段因为 diff 只能看到改动行无法判断周边逻辑是否配套修改行为时同步核验调用方是否适配用grep找出所有调用点确认行为变更如返回值语义、参数约束、错误码变化不会破坏既有调用。这正对应 external-api.md 中头文件符号修改后 grep 全部引用点含 AI 框架适配层、MC2 自定义算子使用者同步更新防编译错误的要求。三、测试完备性UT / ST 的核查标准3.1 生产代码变更必须有测试对应生产代码变更src/须有对应 UT/ST 补充若test/目录在 PR 中无任何变更检视者必须在意见中质询测试覆盖——即生产改了但没补测试本身就是一个待解释项而不是默认放行。HCCL 的测试体系分两大类见 test/README.mdST系统测试test/st/下的算法分析器通过打桩stub模拟单算子运行流程采集所有 rank 的 Task 序列组成有向无环图再基于图算法做内存读写冲突校验与语义校验验证算法逻辑与内存操作的正确性UT单元测试test/ut/下的用例对具体函数/模块做行为断言。本地运行方式AGENTS.md 第 4 节bash build.sh --pkg # 编译 host 包 bash build.sh -u # 编译并运行 UT bash build.sh -s # 编译并运行 ST bash build.sh --ut # 与 -u 等价test/README.md 写法 bash build.sh --st # 与 -s 等价test/README.md 写法CI 侧.gitcode/workflows/ut_action.yml 展示了 PR 触发 UT 的标准流水线checkout PR merge 提交 → 下载 pr_filelist 与ut.sh→ 执行bash ut.sh ${ut_type}→ 上传覆盖率包ut_cov_*.tar.gz与测试日志。可见 UT 是 PR 合入前的强制关卡。3.2 UT 断言必须校验行为结果而非仅不崩溃规范明确UT 断言须校验行为结果而不是只验证不崩溃。以仓库中 test/ut/common/alg_parse/alg_parse_test.cc 为例真实用例对解析结果做了细粒度断言TEST_F(HcclAlgoParserTest, ParseCorrectCase1) { ... EXPECT_EQ(ret, HCCL_SUCCESS); EXPECT_EQ(parser.executorList.size(), 5u); EXPECT_EQ(parser.executorList[0].opType, allreduce); EXPECT_EQ(parser.executorList[0].executorType, sequence); EXPECT_EQ(parser.executorList[0].algoList.size(), 2u); EXPECT_EQ(parser.executorList[0].algoList[0].algoType, mesh2die); EXPECT_EQ(parser.executorList[0].algoList[1].algoType, nhrmultilink); EXPECT_TRUE(parser.executorList[0].enable); ... }从该用例可以提炼出 UT 完备性的三条实操标准校验返回值EXPECT_EQ(ret, HCCL_SUCCESS)成功/失败路径都要覆盖校验数据结构内容executorList.size()、opType、executorType、algoType、enable断言的是解析出的真实行为而不是函数没抛异常新增接口至少覆盖正常路径 关键错误路径只测 happy path 不测异常分支会被检视者打回。3.3 PR 描述的「测试」一节必须列出已执行用例与结果PR 模板中的「测试」小节不是可写可不写的占位规范要求列出已执行用例与结果。检视时会对照该节内容与 diff 中的测试文件判断声称跑了哪些用例如bash build.sh --ut或指定用例名用例与改动功能是否对应例如新增算法选择逻辑就应有对应 selector 的 UT是否包含回归测试CONTRIBUTING.md 对简单问题处理明确要求确保包含触发 Bug 的回归测试。四、文档同步接口与行为变更的资料闭环规范要求三类文档同步缺一不可4.1 接口/行为变更 → 同步 docs/接口/行为变更须同步更新docs/下的资料算子 API 文档docs/zh/api_ref/下的 HcclAllReduce.md、HcclAllGather.md 等与架构文档architecture-brief.md新增模块须在 architecture-brief 补充对应小节如适用。4.2 新增/变更软件模块 → 同步模块 README.md新增/变更软件模块须同步补充、更新该模块内的README.md模块职责、接口说明、与其他模块关系。这一点在 external-api.md 的「模块变更」条目中同样被列为必查项第 5 条仓库中的模块 README 示例test/st/algorithm/README.md算法分析器使用指南、test/README.md测试体系说明、experimental/README.md社区试验性代码规则等新增模块可参照其结构与详细程度补齐。4.3 对外头变更 → external-api.md 的资料同步条目若 PR 涉及include/对外头文件hccl.h 算子 API、hccl_mc2.h MC2 自定义算子框架须按 external-api.md 的规范逐条核查其中包括接口变更同步更新docs/zh/api_ref/资料注意include/变更必须向后兼容且对外 C 函数应返回错误码宏如HcclResult而非裸int32_t。五、与检视工具链的配合把完备性核查落到行上完备性检视最终要落到可执行、可追踪的行内意见上。HCCL 的检视工具链 pr_review.py 提供了对应的机制行号实证每条检视意见必须带code_snippet字段提交前用--verify-only验证行号与内容verify_line_number检查 head 版本文件的该行存在且包含片段防估算行号diff 位置计算find_diff_position只允许对 diff 中的新增()行挂行内评论行不在 diff 时自动回退为带 file:line前缀的 PR 评论——这正是描述声称了但没做/做了但没说这类跨文件、跨 diff意见的标准承载方式去重与汇总提交前自动与 PR 已有评论去重fileline 或标题指纹提交后--report生成按 CRITICAL/HIGH/MEDIUM/LOW 排序的检视汇总报告意见处置闭环修复检视意见后通过--dispose回复到原意见线程并 resolve 关闭且 SKILL.md 执行纪律明确代码变更后同步更新 PR 描述与关联 Issue保持描述与实现一致对照 pr-completeness.md 的吻合度要求——即完备性核查同样适用于检视意见修复后的增量提交。对检视者而言提交每条意见前应自问三句SKILL.md 第 4 步这是真实问题吗有无反例该行实际内容匹配吗——存疑则不发避免噪声意见稀释真正有价值的完备性结论。六、检视清单速查可直接用于评审综合 pr-completeness.md 全文可将完备性检视浓缩为以下清单适合作为 PR 评审的逐项核对表PR/Issue 与实现吻合度描述声称的每个改动点在 diff 中都有对应实现防声称了但没做diff 核心变更在描述中有交代无夹带修改防做了但没说关联 Issue 诉求逐条覆盖实现未超范围PR 描述按 .gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md 填写描述/变更类型/关联 Issue/测试/文档更新功能正确性逐条核验实现逻辑达成目标核心逻辑读了完整函数体而非仅 diff修改行为时 grep 调用点核验调用方适配测试完备性src/生产代码变更有对应 UT/STtest/无变更时质询测试覆盖UT 断言校验行为结果返回值 数据结构内容覆盖正常路径 关键错误路径PR 描述「测试」一节列出已执行用例与结果文档同步接口/行为变更同步docs/api_ref、架构文档新增模块补 architecture-brief 小节新增/变更软件模块同步更新模块内 README.md对外头变更符合 external-api.md 的资料同步条目总结PR 描述与测试完备性核查是 HCCL 所有 PR 的必检维度其本质是保证**描述 实现 测试 文档四者闭环**描述与实现双向吻合防止功能失真UT/ST 校验行为结果防止假通过文档同步防止接口漂移。配合 pr_review.py 的行号验证、diff position 计算与自动去重机制检视者可以将完备性问题以行内意见的形式精准落在 PR 上并借助--dispose形成提出 → 修复 → 回复关闭的完整闭环。开发者提交前对照上文清单自检可以显著降低被检视打回、返工的成本。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考