CANN runtime 仓库 AI 化代码审查规则详解：从规范加载到 Error Message 专项检视-平芜编程栈

CANN runtime 仓库 AI 化代码审查规则详解：从规范加载到 Error Message 专项检视

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本指南系统解读 CANN / runtime 仓库中面向 AI Agent 与自动化工具的统一代码审查规则（.agents/skills/runtime-code-review/review-rules.md），涵盖审查前置约束、规范加载策略、八大审查维度、严重程度分级与结构化输出格式，并结合仓库内error_code.json、error_code_meta.h与 UT 用例给出 Error Message 专项检视的源码级依据。读完本文，你将掌握如何在 runtime 仓库中执行一次符合仓库规范、可复现、可发布的 AI 代码审查。

一、这套规则解决什么问题

runtime 仓库代码规模庞大（src/、include/、pkg_inc/、tests/、docs/等多类目录并存），人工审查难以覆盖全部规范；而 AI / 工具审查又容易出现两个极端：要么只凭主观感受输出一堆低信号意见，要么在用户没有授权的情况下擅自向代码托管平台写评论。review-rules.md正是为解决这两类问题而设计的统一规则文件：

为 AI 审查定义必须加载的规范文档清单与按文件类型分流的加载策略；
为问题分级定义高信号优先原则与三级严重程度（[必须修改]/[建议修改]/[仅供参考]）；
为输出定义按文件组织、含维度与行号的结构化格式，以及最终的审查总结格式；
为对外交互划定不可逾越的红线：未获用户明确授权，绝不向 GitCode 发布任何评论。

该文件被runtime-code-reviewskill 的两种工作模式（本地检视 local-review.md 与 PR 检视 pr-review.md）共同引用，是整套审查能力的行为基准。

二、最高优先级约束：禁止自动发布评论

规则文件开篇即声明一条绝对约束：审查完成后，绝对不能自动向 GitCode 发布评论。这既是安全底线，也是用户体验底线。

2.1 禁止事项

在用户没有明确要求时，AI / 工具不得执行任何以下操作：

向 GitCode PR 发布 summary comment；
向 GitCode PR 发布行内评论（inline comments）；
使用任何 GitCode API 执行 POST/DELETE 评论操作；
调用 scripts/post_pr_summary_comment.py 或 scripts/post_pr_inline_comment.py；
使用--comment或--post-inline-comments参数运行脚本。

规则特别点出几个常见的"危险想法"并逐一击破：不能因为"审查完成了"就认为应该发布，不能把发布当成"流程的最后一步"，不能因为"用户之前做过类似操作"就默认本次也授权，更不能因为"脚本支持--comment参数"就认为应当使用。发布属于外部系统写操作，会改变 PR 状态、触发通知、影响他人工作流，必须由用户显式控制。

2.2 触发条件与正确流程

只有当用户说出"发布评论""提交审查结果""post review""把审查结果发到 GitCode""发 inline comments"等明确指令时，才允许发布。审查完成后的正确响应是：

审查已完成。发现： - [问题统计] 是否需要将审查结果发布到 GitCode？

然后等待用户回复：用户回复"是""可以""发布""提交"才执行；回复"不用"则直接结束；无回复或答复含糊时应再次询问或直接结束，绝不能默认默许。在 pr-review.md 中，这一约束进一步落实为发布前检查清单：用户消息含明确关键词、已展示审查摘要、用户已确认、且不是在审查完成后的首次响应——任一条件不满足都必须 STOP 并询问。

三、输入规则：先加载规范，再开始审查

规则要求审查启动前必须先完成规范加载，避免"无规范可依"的随意评审：

必须先读取 docs/zh/guidelines/coding-guidelines.md，将其作为基础规范来源；
必须扫描变更文件和 diff 内容是否命中 Error Message 信号；命中时读取 docs/zh/guidelines/error_message_guide/README.md 并执行 Error Message 专项检视；
当变更涉及设计、接口、测试或文档时，还应结合 docs/zh/guidelines/design_document_template.md 和 docs/zh/guidelines/dt_guide 下的相关文档。

审查对象由调用方模式提供，可以是本地 diff（git diff origin/master...HEAD），也可以是 GitCode PR diff。从实现看，PR diff 的拉取与元信息获取分别由 scripts/fetch_pr_meta.py（调用 GitCode API 获取标题、描述、状态、base/head sha）和 scripts/fetch_pr_files.py（获取文件列表与 diff refs）完成，二者均要求环境变量GITCODE_API_TOKEN已配置。

四、文件分类与规范加载策略

不同文件适用不同的规范深度，规则将变更文件分为四类，并分别规定"必须读取"或"建议读取"的规范文档：

文件类别	典型路径	必须/建议读取的规范
源码文件	`src/`、`include/`、`pkg_inc/`、`cmake/`	coding-guidelines.md；命中 Error Message 信号时追加读取 error_message_guide 系列
UT 文件	`tests/*`、`_utest`、`_unittest*`	coding-guidelines.md（重点"通用 C/C++ 编码规范"）、ut-coding-guidelines.md、dt_guide/ut_case_development_guide.md
文档文件	`docs/**`	建议读取 design_document_template.md 与 coding-guidelines.md
其他文件	`scripts/**`、根目录配置文件等	建议读取 coding-guidelines.md

4.1 Error Message 相关变更的识别信号

源码文件中，命中以下任一信号就必须执行 Error Message 专项检视：

识别标志	说明
调用 macro-selection-guide.md 中列出的宏	Error Message 错误上报点
error_code.json 新增条目，或 error_code_meta.h 新增 X-Macro 行	新增错误码
新增`#define`（经宏展开链追踪确认为上报宏，定义参考 macro-selection-guide.md）	新增上报宏

命中后必须先读取 docs/zh/guidelines/error_message_guide/README.md，再按问题类型选择专题文档：错误码选择看 error-code-guide.md，宏选择/签名/参数数量看 macro-selection-guide.md，文案/模板/翻译口径看 message-examples.md，整改边界/参数来源/第一现场/防御性编程/重复上报看 rectification-principles.md。

五、审查优先级与高信号原则

规则明确要求优先标记高信号问题——即能够清楚说明"为什么这是问题"的缺陷，并给出了可判定的优先级条件：

应当优先输出的问题（满足至少一类）：

代码无法编译或解析；
无论输入如何，代码都必然产生错误结果；
明确、无歧义地违反仓库规范，且能指出具体规则；
明确的兼容性破坏、资源泄漏或文档同步缺失。

不应优先输出的内容：

主观风格偏好；
需要大量上下文才能成立的猜测性问题；
可由通用 lint 自动发现、且不影响正确性的低信号问题。

如果对某个问题是否成立没有足够把握，就不要将其标为高优先级。这条原则配合 scripts/should_skip_pr_review.py（对已关闭、draft、标题带wip/[wip]/draft:的 PR 直接建议跳过审查）共同保证了审查资源的有效投入。

六、八大审查维度

规则定义了覆盖代码质量全要素的八个审查维度，PR 模式下每个维度都会落到可执行的检查动作上。

A. 功能正确性

检查变更逻辑是否符合预期意图；是否遗漏分支、边界条件或异常路径；是否与设计文档、接口约束和测试预期一致。

B. 日志合理性

检查日志级别与热路径开销是否合理；日志内容是否具备足够上下文且不泄露敏感信息；格式化字符串和错误日志宏使用是否正确。

C. 公共 API 兼容性

检查公开头文件修改是否保持向后兼容；是否发生 breaking change；废弃接口、枚举和公开边界处理是否符合规范。

D. 文档同步

修改公开接口或错误码时，是否同步更新了对应文档。这一维度与仓库中docs/zh/guidelines/error_message_guide/README.md的"维护原则"相互呼应：修改错误码、宏或文案规范时须同步更新对应文档与error-code-guide.md/macro-selection-guide.md。

E. 软件架构

是否破坏既有目录边界、平台隔离边界或组件职责边界；是否违反src/runtime中api与非api目录之间的调用边界。

F. 构建规范

重点检查src/runtime目录是否新增了不允许的编译宏。

G. UT 规范

测试代码是否满足断言、mock 清理和状态恢复要求；是否存在不必要的私有成员访问、SetChipType使用或测试隔离问题。仓库 UT 中大量用例遵循GlobalMockObject::verify()式清理模式（参见 tests/ut/runtime/runtime/test/rt_error_code_test.cc 的TearDown），可作为该维度的直观参照。

H. Error Message 规范（专项）

当变更命中 Error Message 信号时，必须执行本维度检视，检查项多达 10 条，下一节详述。

七、Error Message 专项检视：双源同步与参数完备性

Error Message 维度是 runtime 仓库审查中最具特色的部分，其核心是围绕JSON 数据源 + X-Macro 头文件 + UT 校验三条链路的完备性检查。

7.1 检视要点（10 项）

用户错误 / 内部错误分类是否正确，按 rectification-principles.md 中"用户错误与内部错误""参数来源判断"两节执行；
错误码选择是否匹配场景，Arglist 数量与顺序是否与 error_code.json 及 error_code_meta.h 匹配，须按 error-code-guide.md 与对应分类的决策树逐项判断；
新增错误码的完备性——缺少以下任一项即判定不完整，推荐使用errmsg-codegenskill 更新并刷新 error-code-guide.md：
- JSON 条目完整性：error_code.json 中的errClass、errTitle、ErrCode、ErrMessage、Arglist、suggestion；
- X-Macro 表行：error_code_meta.h；
- UT 数据：rt_error_code_test.cc的allCodes数组；
宏与错误码、控制流、参数传递风格是否匹配，是否误用_INNER/_OUTER系列宏，按 macro-selection-guide.md 判断；
涉及新增宏时须同步更新 macro-selection-guide.md；
错误文案是否包含参数名、参数值、期望值或 Reason，是否可定位、可自闭环、句式完整、无语法错误；
是否存在重复结构化上报，按 rectification-principles.md 检查同一次 ErrMsg 输出及其调用栈；
Error Message 整改是否误改业务逻辑、返回值、条件判断或普通日志级别；
公开 API 参数错误是否漏报必要结构化错误；
是否满足整改边界，按 rectification-principles.md 判断。

7.2 源码证据：双源如何同步

JSON 侧（面向文档化与错误码字典）：error_code.json 中每个错误码包含errClass、errTitle、ErrCode、ErrMessage、Arglist、suggestion六个字段。例如：

{ "errClass": "RTS Errors", "errTitle": "Invalid_Argument", "ErrCode": "EE1001", "ErrMessage": "The argument is invalid. Reason: %s", "Arglist": "extend_info", "suggestion": { "Possible Cause": "N/A", "Solution": "1. Check the input parameter range of the function. 2. Check the function invocation relationship." } }

X-Macro 侧（面向编译期校验与日志生成）：error_code_meta.h 通过RUNTIME_ERROR_CODE_TABLE(X)定义每行格式为X(ErrorCode枚举名, 字符串名称, (参数名列表), 完整消息模板, 日志级别)。例如：

/* EE1003 - Invalid_Argument */ X(EE1003, "EE1003", ("func", "value", "param", "expect"), "%s failed because value %s for parameter %s is invalid. " "Expected value: %s. ErrorCode=EE1003.\n", DLOG_ERROR)

这里EE1003的 Arglist 为 4 个参数，与 JSON 中"Arglist": "func, value, param, expect"一一对应，%s占位符数量也必须与之严格一致——这正是"Arglist 数量与顺序匹配"检查的落点。

UT 侧（机器可验证的守卫）：tests/ut/runtime/runtime/test/rt_error_code_test.cc 中ErrorCodeTableParamCountMatchesMessageFormat用例以allCodes数组逐项断言每个错误码的参数数量与GetParamNames(info.code)返回一致：

std::vector<CodeInfo> allCodes = { {ErrorCode::EE1001, 1}, {ErrorCode::EE1002, 1}, {ErrorCode::EE1003, 4}, {ErrorCode::EE1004, 2}, {ErrorCode::EE1005, 1}, {ErrorCode::EE1006, 3}, {ErrorCode::EE1007, 2}, {ErrorCode::EE1009, 2}, ... }; for (const auto& info : allCodes) { auto names = GetParamNames(info.code); EXPECT_EQ(names.size(), info.expectedParamCount) << "Param count mismatch for code " << static_cast<int>(info.code); }

这意味着：新增错误码时，若只改 JSON 和 X-Macro 表而未同步更新allCodes数组，UT 会直接失败。规则第 3 条要求的三处同步（JSON 条目、X-Macro 行、UT 数据）由此获得了可自动验证的强制力。

7.3 严重程度判定

Error Message 维度的严重程度单独细化：

[必须修改]：用户错误和内部错误分类明显错误；错误码明显选错；Arglist 数量或顺序与error_code.json/error_code_meta.h不匹配；一次 ErrMsg 输出中存在完全相同或实质相同的结构化消息；删除或迁移上报导致本应结构化上报的路径漏报；Error Message 整改引入业务逻辑、返回值、条件判断、清理顺序或日志级别变化；公开 API 参数错误漏报必要结构化错误。
[建议修改]：宏可工作但不是推荐专用宏；文案不够自闭环；Reason、Expected、参数名或参数值表达不清；第一现场日志上下文不足；调用栈中存在可由首错点和 acl/rt 接口层完整覆盖的冗余中间层上报。
[仅供参考]：非关键措辞优化，或不影响定位的问题说明。

八、通用严重程度定义与输出格式

除 Error Message 专项外，规则给出了全局通用的三级严重程度：

[必须修改]：功能缺陷、安全漏洞、资源泄漏、兼容性破坏、缺失必要文档同步等必须修复的问题；
[建议修改]：编码风格、日志合理性、可维护性、测试完备性等建议改进的问题；
[仅供参考]：风格偏好、可选优化和低风险提醒。

输出按文件组织审查结果，每个问题包含严重程度、审查维度、行号、问题描述与修改建议：

### <文件路径> - **[严重程度]** <审查维度> | 行号：<行号> <问题描述> <修改建议>（如适用）

8.1 审查总结格式

所有文件审查完成后，必须输出三段式总结：

变更概要：本次变更的目的和范围；
问题统计：各严重程度的问题数量；
总体评价：代码质量评估及是否建议合入。

在 PR 模式下，这套总结可以通过 scripts/render_pr_review_summary.py 渲染为summary.md，并可（在用户授权后）由 scripts/post_pr_summary_comment.py 发布。

九、结构化审查结果的机器可读表达

对于希望将审查结果交给脚本自动渲染与发布（仅在授权时）的场景，review-result-schema.md 定义了--review-resultJSON 的结构。顶层包含change_summary（变更概要）、problem_stats（must_fix/suggested/reference计数）、overall_assessment（总体评价）和findings（逐问题明细）四个必需字段；每个 finding 至少含file、severity、dimension、summary，可选line、suggestion与inline_comment（内含path、position、start_position、body，供行内评论发布使用）。

scripts/run_pr_review.py 的validate_review_result函数会强校验：顶层四字段必须齐全、problem_stats三项必须存在、findings必须是数组且每个 finding 的severity只能是三个合法值之一；若inline_comment未提供body，脚本会依据severity、dimension、summary、suggestion自动拼装行内评论正文。整个校验链路保证了"结构化审查结果 → 可渲染摘要 → 可定位行内评论"的端到端一致性。

十、实战落地：一条完整的 PR 审查流水线

将上述规则落到仓库中，一次合规的 PR 审查遵循如下流水线（详见 pr-review.md）：

准备：确认GITCODE_API_TOKEN已配置（echo $GITCODE_API_TOKEN）；
拉取 PR 信息：fetch_pr_meta.py获取标题、描述、状态、base/head sha；fetch_pr_files.py获取文件列表与 diff refs；
前置检查：should_skip_pr_review.py判断 PR 是否已关闭、是否为 draft、是否无需审查；
读取共享规则：review-rules.md；
文件分类：classify_review_files.py按四类分组；
聚合上下文：prepare_pr_review_context.py汇总 PR 元信息、diff 与分类结果；
加载规范文档：按分类结果分别加载 coding-guidelines、error_message_guide 系列、ut-coding-guidelines、design_document_template；
逐文件审查并验证、过滤误报；
输出结果（默认必须执行，在终端完整输出；无问题时明确输出"未发现问题"）；
发布（仅用户明确要求）：先渲染 summary，再发布 summary comment，仅对高信号、可复现、可准确定位的少量问题发布行内评论，避免噪声过大。

单入口命令（仅编排，不代跑模型审查）：

python3 .agents/skills/runtime-code-review/scripts/run_pr_review.py \ --owner <owner> \ --repo <repo> \ --pr <number>

如需在已有结构化结果review-result.json的基础上渲染并发布（需用户确认授权）：

python3 .agents/skills/runtime-code-review/scripts/run_pr_review.py \ --owner <owner> --repo <repo> --pr <number> \ --review-result review-result.json --comment

行内评论发布前必须确认精确行号：先用 PR diff 定位 hunk，再用fetch_pr_raw_file.py获取 raw 文件，必要时以grep -n确认目标代码行号，避免仅凭 patch hunk 起始位置估算。本地场景则直接以 local-review.md 为流程基线，审查范围默认为git diff origin/master...HEAD涉及的本地改动。

十一、总结

review-rules.md的价值在于把"高质量代码审查"从经验行为固化为可执行、可验证的工程规范：以禁止自动发布守住外部交互边界，以分类加载规范保证审查依据充分，以高信号优先提升问题信噪比，以Error Message 双源同步 + UT 强制校验确保错误码体系不出错，最终以三级严重程度 + 结构化输出 + 三段式总结交付可读、可机器消费的审查产物。无论是人工 review 还是 AI 辅助审查，遵循这套规则都能让每次审查有据可依、结论可信、边界清晰。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CANN runtime 仓库 AI 化代码审查规则详解：从规范加载到 Error Message 专项检视