基于 GitCode API 的 PR 代码审查自动化实战：解析 amct 仓库 review.md Agent 技能-北京尧图网络

基于 GitCode API 的 PR 代码审查自动化实战解析 amct 仓库 review.md Agent 技能【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct导读本文围绕 CANN/amct 仓库内.agents/skills/gitcode-pr/commands/review.md这份 Agent 技能文档展开系统讲解如何在 GitCode 平台上通过 API 完成 Pull Request 的自动化代码审查从前置检查、变更获取、精确行号定位到高信号 Bug 筛选、问题验证过滤再到行内评论发布的全流程。读者完成本文后将掌握一套可直接复用的 PR 审查方法论与 GitCode APIv4/v5 双风格的调用规范能够在自己或团队的开源仓库中落地 Agent 化代码审查。一、技能定位review.md 在 amct 仓库 Agent 体系中的角色在 CANN/amct 仓库的.agents目录下维护着一套面向开源协作的 Agent 技能体系.agents/README.md。其中gitcode-pr技能.agents/skills/gitcode-pr/SKILL.md负责 GitCode 平台上 Pull Request合并请求的创建、评论获取与审查而本文的主角 commands/review.md 正是该技能中PR 代码审查子流程的完整操作手册。从 SKILL.md 的触发条件看当用户发出检视 PR审查 PRreview PR给 PR 提意见等指令时Agent 会先通过 Read 工具读取commands/review.md获取审查流程再逐条执行其中的步骤。该文档具有以下设计特点标准化的九步流程从前置检查到评论发布每一步都有明确的判定条件与终止分支双 API 风格并存既支持 GitHub 兼容的 v5 API/repos/${owner}/${repo}/...也支持 GitLab API v4 格式/projects/${encoded_repo}/merge_requests/...以高信号问题为核心明确区分值得标记与不要标记的问题类型将误报率控制在可接受范围。此外仓库提供了配套的评估用例 evals/evals.json用真实 PR 验证该技能的有效性本文末尾会展开分析。二、审查流程总览九步标准化流水线review.md将一次 PR 审查拆解为 9 个顺序步骤任何一步都有明确的产出物或终止条件步骤名称核心产出 / 终止条件1前置检查任一条件成立则停止执行2获取项目规范上下文规范文件路径列表不含内容3获取 PR 变更摘要PR 信息、文件列表、diff3.1确定问题代码的准确行号目标文件精确行号4代码审查高信号问题列表5验证问题每个问题经实证确认6过滤问题最终高信号问题列表7输出审查摘要终端输出评论发布决策8准备评论列表仅自检不对外发布9发布行内评论通过 GitCode API 写入 PR该流程还隐含两条贯穿始终的原则文档开头的Agent 假设不测试工具假定所有工具均正常不做探索性调用每次工具调用都应有明确目的子 Agent 信息同步每个启动的子 agent 都需清楚上述假设且在审查阶段需被告知 PR 的标题与描述以理解作者意图。三、步骤 1前置检查——四类直接终止的情况审查开始前必须先检查以下四个条件任一成立则立即停止不进入后续步骤PR 已关闭closedPR 处于草稿状态draftPR 不需要代码审查例如自动化 PR、明显正确的微小变更Claude 已在此 PR 上评论过通过 GitCode API 检查 PR 评论历史避免重复劳动。其中有一条特别豁免由 ClaudeAgent自己生成的 PR 仍然需要审查。这意味着自动化提交的代码同样纳入质量管控只是跳过是否已评论等常规去重判断。四、步骤 23获取规范上下文与 PR 变更摘要4.1 项目规范上下文返回所有相关规范文件的文件路径列表不含内容来源有两类仓库根目录的规范文件如CONTRIBUTING.md、CODE_STYLE.md等PR 修改文件所在目录中的规范文件后续评估规范合规性时只考虑该文件路径或父目录中的规范文件。在 amct 仓库中根目录即存在 CONTRIBUTING.md 与 CONTRIBUTING_en.md 等协作规范文件属于此步骤会收集的对象。4.2 获取 PR 信息与变更通过 GitCode 的 GitHub 兼容 APIv5拉取 PR 元数据、文件列表与 diff# 获取 PR 信息 curl -s https://gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{pr_number} \ -H Authorization: Bearer $GITCODE_TOKEN # 获取 PR 变更文件列表 curl -s https://gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{pr_number}/files \ -H Authorization: Bearer $GITCODE_TOKEN # 获取 PR diff curl -s https://gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{pr_number} \ -H Authorization: Bearer $GITCODE_TOKEN \ -d difftrue结合 references/gitcode_api.md 的说明{owner}/{repo}应从当前仓库的远程 URL 动态提取git remote get-url origin后通过sed解析 SSH 或 HTTPS 两种格式而不是硬编码——这一点对 fork 场景尤其重要。五、步骤 3.1确定问题代码的准确行号发布行内评论的前提是拿到准确的行号。文档提供了两种方法方法 1从 PR Diff 的 hunk header 推算GET .../pulls/PR_NUMBER/files返回的patch.diff字段包含 hunk header -old_start,old_count new_start,new_count -old_start,old_count原文件的起始行和变更行数new_start,new_count新文件的起始行和新增行数。注意hunk header 只给出起始行号仍需根据 diff 内容逐行累计计算实际行号手动计算易出错。方法 2从 Raw 文件验证推荐直接查询 PR head commit 对应的 raw 文件用grep -n精确落点curl -s https://raw.gitcode.com/${owner}/${repo}/raw/HEAD_SHA/path/to/file.cc | grep -n 问题代码模式文档给出的真实示例curl -s https://raw.gitcode.com/${owner}/${repo}/raw/358192edfc1809f6fe17b0da0b1b8efd9880a52f/hcom_graph_optimizer.cc \ | grep -n if (it 输出844: if (it (itMap-second).end()) {最佳实践先用 diff 定位大致范围通过 PR diff 找到变更的代码块再用 raw 文件确认精确行号避免手动计算偏差发布评论前验证确保行号对应的确实是问题代码。这一流程的有效性在 evals/evals.json 的line-number-accuracy用例中得到了验证使用技能时准确锁定第 844 行耗时约 126 秒而评估结论也提示用 raw 文件验证或 grep -n是标准做法。六、步骤 4代码审查——只标记高信号问题6.1 三个审查维度维度检查内容规范合规性审查变更是否符合项目规范只参考该文件路径或父目录中的规范文件Bug 扫描只关注 diff 本身不读取额外上下文只标记显著 Bug忽略细微问题与疑似误报代码问题检查安全问题、逻辑错误等变更代码范围内的新引入问题6.2 高信号问题的判定标准标记以下类型的问题代码无法编译或解析语法错误、类型错误、缺少导入、未解析引用无论输入如何代码肯定产生错误结果明显的逻辑错误明确、无歧义的规范违反可以引用被违反的具体规则。不要标记代码风格或质量问题依赖特定输入或状态的潜在问题主观建议或改进意见。文档特别强调如果你不确定某个问题是否真实存在不要标记它。误报会损害信任并浪费审查者时间。这条原则与后续的验证—过滤两步骤形成闭环保证最终进入评论阶段的问题都是经过实证的高置信度问题。七、步骤 56验证问题与过滤问题步骤 5验证问题对步骤 4 发现的每个问题结合 PR 标题、描述与问题描述进行确信验证。例如标记了变量未定义需确认代码中确实如此规范合规问题需确认被违反的规则确实适用于该文件且确实被违反。步骤 6过滤问题过滤掉未通过验证的问题得到最终的高信号问题列表。两个步骤共同构成提出—验证—收敛的质量闸门是避免噪音评论的关键设计。八、步骤 7输出审查摘要与评论决策在终端输出审查结果摘要如果发现问题列出每个问题及简要描述如果未发现问题输出未发现问题。已检查 Bug 和规范合规性。随后根据--comment参数分派三种分支场景行为未提供--comment停止不发布任何 GitCode 评论提供--comment且未发现问题用 GitCode API 发布摘要评论并停止提供--comment且发现问题继续步骤 8、9其中无问题时的摘要评论有固定格式以 Markdown 分隔线包裹--- ## 代码审查未发现问题。已检查 Bug 和规范合规性。 ---九、步骤 89发布行内评论9.1 准备评论列表步骤 8 仅用于自检创建计划发布的所有评论清单确认内容满意但不在任何地方发布。9.2 创建 Discussion 发布行内评论推荐步骤 9 推荐通过 GitLab API v4 格式的 discussions 端点发布行内评论curl -s -X POST \ -H PRIVATE-TOKEN: $GITCODE_API_TOKEN \ -H Content-Type: application/json \ https://api.gitcode.com/api/v4/projects/${encoded_repo}/merge_requests/PR_NUMBER/discussions \ -d { repoId: ${encoded_repo}, iid: PR_NUMBER, body: 评论内容, line_types: new, position: { base_sha: base_commit_sha, start_sha: start_commit_sha, head_sha: head_commit_sha, position_type: text, old_path: 文件路径, new_path: 文件路径, old_line: null, new_line: 结束行号, start_old_line: null, start_new_line: 起始行号, ignore_whitespace_change: false }, assignee_id: 用户ID, proposer_id: 用户ID, severity: suggestion }9.3 参数说明参数说明必需body评论内容✅line_typesnew选择新代码右侧old选择旧代码左侧✅position.base_shabase 提交 SHA✅position.start_shastart 提交 SHA✅position.head_shahead 提交 SHA✅position.new_path文件相对路径✅position.new_line结束行号✅position.start_new_line起始行号多行选择多行时severity严重程度suggestion、warning❌多行选择说明start_new_line为选中起始行号new_line为选中结束行号单行评论时两者设为相同值。9.4 评论内容规范每个评论提供问题的简要描述对于小型、自包含的修复包含可提交的建议代码块对于较大修复6 行以上、结构性变更或跨多个位置描述问题与建议修复方式不包含建议代码块永远不要发布可提交建议除非提交该建议能完全修复问题如需后续步骤则不留下可提交建议每个唯一问题只发布一条行内评论严禁重复。十、误报列表明确不标记的六类情况review.md专门维护了一份误报列表用于步骤 4 和 5 的评估判据已存在的问题pre-existing看起来是 Bug 但实际上是正确的代码高级工程师不会标记的吹毛求疵Linter 会捕获的问题不要运行 Linter 验证一般代码质量问题如缺乏测试覆盖、一般安全问题除非规范中明确要求规范中提到但在代码中明确静默的问题如通过 lint ignore 注释。这份清单有效约束了 Agent 的标记行为防止将审查退化为噪音制造工具。十一、注意事项链接格式与 API 交互纪律11.1 行内评论中的代码链接格式在行内评论中链接代码时必须严格遵循以下格式否则 Markdown 预览无法正确渲染https://gitcode.com/{owner}/{repo}/blob/{full_git_sha}/path/to/file#L{start}-L{end}要点需要完整的 git sha类似$(git rev-parse HEAD)的替换在评论中不起作用仓库名必须与正在审查的仓库一致文件名后使用#行范围格式为L[start]-L[end]在评论行前后至少提供 1 行上下文如评论第 5-6 行应链接到 L4-L7。11.2 其他纪律使用 GitCode API 与 GitCode 交互获取 PR、创建评论不要使用网页抓取开始前创建待办列表to-do list每个问题必须在行内评论中引用并链接引用规范文件时包含指向它的链接。十二、GitCode API 参考双风格认证与快速检索表review.md明确指出GitCode 使用 GitLab API v4 格式认证头使用PRIVATE-TOKEN。这与 GitHub 兼容的 v5 风格并存references/gitcode_api.md 给出了对比API 风格认证头端点格式GitLab API v4推荐PRIVATE-TOKEN: token/api/v4/projects/encoded_path/...GitHub 兼容Authorization: Bearer token/api/v5/repos/path/...其中项目路径需编码owner/repo→owner%2Frepo可用printf %s owner/repo | jq -sRr uri。快速参考表操作API 端点获取 PR 信息GET /projects/${encoded_repo}/merge_requests/PR_NUMBER获取 PR 变更GET /projects/${encoded_repo}/merge_requests/PR_NUMBER/changes获取 PR 评论GET /projects/${encoded_repo}/merge_requests/PR_NUMBER/discussions发布普通评论POST /projects/${encoded_repo}/merge_requests/PR_NUMBER/notes发布行内评论POST /projects/${encoded_repo}/merge_requests/PR_NUMBER/discussions基本调用格式curl -s -H PRIVATE-TOKEN: $GITCODE_API_TOKEN \ https://api.gitcode.com/api/v4/projects/${encoded_repo}/merge_requests/PR_NUMBER/discussions十三、配套资源与效果验证围绕review.mdgitcode-pr 技能还提供了完整的配套资源均可从仓库根目录相对路径进入SKILL.md技能总入口涵盖令牌获取GITCODE_API_TOKEN环境变量、远程仓库 owner/repo 提取脚本、fork 原仓库查询、评论类型DiffNote行内 /DiscussionNote普通、创建/回复/删除评论、PR 创建流程与 Conventional Commits 标题规范等。其中获取真正的数字 ID一节值得注意POST 创建评论立即返回的是哈希字符串作为discussion_id删除评论等后续操作必须先从列表接口拿到数字id且不能用宽泛的contains(.body)匹配他人评论。references/gitcode_api.md完整 API 参考包含删除评论的状态码200成功 /401未授权 /403无权限 /404不存在、每页 100 条的分页参数、raw 文件获取方式等。evals/evals.json3 个评估用例——basic-pr-review识别it end()后解引用it-second的逻辑 Bug、line-number-accuracy精确到 844 行、review-and-comment发布[TEST]前缀评论并清理。从基准数据看使用技能时with_skill_avg_duration_ms约 149.8 秒明显快于未使用技能的约 215.8 秒且行号定位与 Bug 识别均通过断言评估同时记录了两项待改进点使用技能时发现的问题数量偏少1 个 vs 5 个、评论发布用例需在测试环境运行。结语从文档到可落地的审查能力commands/review.md的价值在于把代码审查这一高度依赖经验的协作行为抽象成了 Agent 可执行、可验证、可度量的标准化流程。其核心方法论——前置门禁、diff 聚焦、高信号筛选、实证验证、过滤收敛、精确定位、规范发布——不仅适用于 GitCode 平台也可以迁移到任何提供 PR API 的代码托管平台。对于 amct 这类持续演进的开源仓库这样的技能文档正是保障社区协作质量与效率的基础设施。文中涉及的所有流程细节与 API 参数均可在仓库 .agents/skills/gitcode-pr 目录下按上述相对路径查阅原文与配套资源。【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

基于 GitCode API 的 PR 代码审查自动化实战：解析 amct 仓库 review.md Agent 技能

相关推荐

5个真实场景告诉你：mermaid-ascii终端图表在哪里大显身手

React Native鸿蒙Button组件适配与优化实践

dlt 数据伪匿名化实战：使用 add_map 与加盐哈希隐藏 PII 列

更多资讯

电视盒子变Linux服务器一步到位：S905L3-B Armbian完整安装手册

Rivet Actors 实时聊天室实战：Actor 状态管理、事件广播与多房间隔离完整实现

GEO技术如何重塑商业生态与竞争格局

PostHog ReviewHog 验证器模型评估：Sonnet 5 @ xhigh 评分表深度解读——“全量保留“背后的 50% 精确率

SpringBoot+Vue社区医疗系统开发实战

Spring Boot 3.x与Flowable 7.x集成实战与优化

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？