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 下的相关文档。审查对象由调用方模式提供可以是本地 diffgit 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这套分类逻辑在仓库中有直接实现scripts/classify_review_files.py 通过正则.*_utest\.(cc|cpp|cxx|c)$、.*_unittest\.(cc|cpp|cxx|c)$及前缀判断docs/→ 文档、tests/→ UT、src|include|pkg_inc|cmake→ 源码其余归入 other输出四类分组 JSON。PR 模式下该脚本由总控脚本 scripts/run_pr_review.py 自动调用分类结果随后交给 scripts/prepare_pr_review_context.py 聚合为审查上下文。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.mdJSON 条目完整性error_code.json 中的errClass、errTitle、ErrCode、ErrMessage、Arglist、suggestionX-Macro 表行error_code_meta.hUT 数据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. ErrorCodeEE1003.\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::vectorCodeInfo 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_castint(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_statsmust_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 shafetch_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），仅供参考