RustFS PR 审查提交指南基于 GitHub API 的 Inline Review 发布与提交绑定【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs本文是一篇面向 RustFS 仓库贡献者与 AI 审查代理的实操指南围绕仓库内 Inline PR Review Submission 参考文档展开完整讲解如何通过 GitHub REST API 将逐行inline评审意见绑定到已审查的提交上并发布为正式 Review。读完本文你将掌握内联评论的 JSON 载荷结构、gh api --input的提交命令、发布前对 PR Head 与评审提交的核对流程以及如何与 RustFS 仓库自身的风险分级、CI 检查与 PR 生命周期规则衔接。一、何时使用 Inline Review授权与场景边界原文档开篇即设定了一个硬性前提Read only when an inline review is authorized. Recheck the PR head before posting and bind the review to the reviewed commit.这意味着内联评审的发布不是默认动作而是有明确授权边界的行为RustFS 根目录 AGENTS.md 明确规定Inquiry, diagnosis, review, and planning tasks are read-only unless the user explicitly requests changes查询、诊断、评审与规划类任务默认为只读。因此只有用户在对话中明确授权发布/提交评审时才允许向 GitHub 写入 Review。技能说明 pr-review/SKILL.md 进一步细化普通评审请求是只读的除非对话同时授权了发布posting或修复fixes已给出的授权可以复用无需反复询问但在请求缺失的发布许可之前应当先把已授权的评审结果准备好。任何技能或参考文档本身都不能扩大用户请求的范围或授予授权AGENTS.md。在授权成立后Inline Review 适用于需要在特定代码行上逐条指出问题的场景——例如某个函数在某一行可能触发并发竞争、某个配置项在具体行上语义错误等。若评审结论只是整体性意见而不涉及具体行号则更适合使用gh pr review --comment/--approve/--request-changes这类整体评审方式详见第五节。二、发布在整体流程中的位置pr-review 技能七步工作流posting.md是 pr-review 技能 的配套参考属于其第 6 步Post the review的专项展开。完整工作流如下步骤动作关键命令 / 产物1收集 PR 上下文gh pr view N --repo owner/repo --json ...、gh pr diff ... --name-only2拉取 diff 并按风险分级git fetch remote baseRef refs/pull/N/head、git diff baseRefOid...headRefOid --stat3分组评审变更行为按功能域追踪调用方与不变量产出带file:line的 finding4检查 CI 状态gh pr checks N --repo owner/repo5汇总结论输出 P0–P3 分级 findings 与 verdictAPPROVE/REQUEST_CHANGES/COMMENT6发布评审整体评审用gh pr review --body-file行内评审用本文的gh api --input7跟进处理按 PR 生命周期 处理后续变更风险分级决定了评审形态adversarial-validation.md文档/注释类为Exempt重命名、测试/工具链改动为Mechanical跑正确性与简洁性视角局部行为变更为Standard涉及锁、纠删码/仲裁/自愈、复制、multipart、RPC、生命周期/分层、持久化/fsync、IAM/KMS/认证、密码学、磁盘/线上格式、S3 可见语义的为High risk需要两个独立评审者分工或两次独立串行 pass。风险分级结果要一并写进最终评审总结。三、发布前的关键校验刷新 PR Head 并绑定评审提交原文档强调两个发布前置动作二者缺一不可Recheck the PR head重新核对 PR Head发布前必须重新拉取并确认 PR 当前 head 仍是评审时使用的那个提交。技能工作流第 2 步要求记录确切的 base/head若拉取过程中任一引用发生移动必须先刷新快照再评审SKILL.md。Bind the review to the reviewed commit把评审绑定到被审提交载荷中的commit_id必须填写实际被评审的 head SHA即reviewed-head-sha而不是当时看起来最新的引用。这与 GitHub Review API 的语义一致Review 是附着在具体 commit 上的评论的行号以该 commit 的 diff 为准。若核对发现 head 已变化正确做法是先评审增量delta再更新 verdict最后才发布SKILL.md。绝不能把旧结论贴到新提交上也不能用未重新拉取的origin/pull/N/head引用作为证据SKILL.md。四、Inline 评论的 JSON 载荷结构原文档给出了完整的请求体示例这是整份参考的核心逐字段说明如下字段类型说明commit_idstring被评审的 head 提交 SHAreviewed-head-sha用于把整个 Review 绑定到该提交bodystringReview 的总体评论文本review bodyeventstring评审结论事件示例为REQUEST_CHANGES同一接口还支持APPROVE与COMMENT与技能中gh pr review的三种模式对应commentsarray行内评论列表每条包含以下三个核心字段comments[].pathstring评论目标文件在仓库中的路径如crates/foo/src/bar.rscomments[].lineinteger评论在 PR diff 中对应的行号如42comments[].bodystring该行问题的具体描述finding description完整请求体原样继承自 posting.mdcat /tmp/pr_review.json EOF { commit_id: reviewed-head-sha, body: review body, event: REQUEST_CHANGES, comments: [ { path: crates/foo/src/bar.rs, line: 42, body: finding description } ] } EOF gh api --method POST /repos/{owner}/{repo}/pulls/N/reviews --input /tmp/pr_review.json使用要点line必须是该 commit diff 中实际存在的行否则接口会报错或产生无效定位多行评论场景可进一步使用start_line/side等字段单行场景下pathlinebody即可满足大部分诉求。comments与commit_id是配套的行号语义依赖提交因此刷新 head 后若提交变化所有行号都必须重新核对这正是先核对、后发布的原因。body中的总评文字应遵循 RustFS 仓库约定源注释、提交、PR 标题与 PR body 均使用英文pull-requests.md即使对话语言是中文评审内容也应保持英文SKILL.md。五、发布命令为什么必须用--input而不是--body原文档的提交命令使用gh api --method POST ... --input /tmp/pr_review.json这一选择与仓库的硬性规范完全一致SKILL.md 明确要求Always use--body-fileor--input, never inline multiline--body——多行内容一律通过文件传入禁止在命令行内联多行--body以避免 shell 转义与换行符被破坏。pull-requests.md 规定PR/Issue/Discussion 内容中不得出现字面量\n序列也不得包含本地绝对路径或工具特定标签/前缀heredoc 写文件的方式天然规避了这两类问题。因此cat /tmp/pr_review.json EOF ... EOF这一步不是可有可无的铺垫而是保证载荷完整性的标准姿势先落盘、再以--input上传。对于不需要行内定位的整体评审同一授权下可使用 CLI 封装命令SKILL.md# 请求变更 gh pr review N --repo owner/repo --request-changes --body-file /tmp/pr_review.md # 批准 gh pr review N --repo owner/repo --approve --body-file /tmp/pr_review.md # 仅评论不下结论 gh pr review N --repo owner/repo --comment --body-file /tmp/pr_review.md六、写什么内容Finding 的证据标准与风险分级发布只是最后一公里行内评论的内容质量由仓库的证据标准约束每个 finding 必须给出具体的失败场景 file:line没有问题时直接给出No findings即可——没有 finding 配额No findings是完整结论AGENTS.md。报告候选 finding 前应先检查调用方、不变量与既有测试排除能证伪它的证据缺失的必需测试属于验证缺口不能当作运行时缺陷来报AGENTS.md。可选风格偏好、重构建议不应塞进缺陷 finding除非用户明确要求该评审视角AGENTS.md。High-risk PR 需要在 PR body 中为每个覆盖的视角记录一条简洁 verdictAGENTS.md。因此comments[].body的推荐写法是file:line 位置 触发条件与失败场景 建议修复三段式例如crates/foo/src/bar.rs:42处在并发路径上未加锁可能触发什么竞争、何种输入可复现、应如何修复。七、发布之后线程解析与 PR 生命周期行内评论发布后后续处理遵循 pull-requests.md 的 PR 生命周期规则解析线程底层问题修复后才可 resolve review thread若拒绝某条建议需用简短、基于证据的理由回复pull-requests.md。跟进监控PR 打开后若用户要求监控按事件驱动或有限等待进行只报告状态变化、可操作的失败或显著延迟后续要重新拉取新 head并与已记录的 reviewed SHA 比对重新检查受影响的调用方与 findingsSKILL.md。更新评审只能在既有授权范围内更新已发布的 Review 或 resolve 被指出的线程不得擅自扩大范围。合并纪律未经必需的 reviewer 批准或明确授权绝不合并观察到合并后验证提交已到达 base再安全清理任务 worktree/分支pull-requests.md。此外创建/更新 PR 本身的格式要求英文 Conventional Commit 标题、≤72 字符、保留 .github/pull_request_template.md 的全部标题、用--body-file传多行内容同样适用于评审后作者侧的补丁提交评审者可以在跟进中据此把关。八、常见陷阱与最佳实践清单陷阱正确做法未核对 head 就发布发布前重新 fetchrefs/pull/N/head并与已记录 SHA 比对commit_id未绑定被审提交填入实际评审的reviewed-head-sha而非当前最新引用line不在该 commit 的 diff 中行号必须存在于commit_id对应 diffhead 变动后全部重新核对命令行内联多行--body一律--body-file整体评审或--inputAPI 载荷内容含字面量\n、本地绝对路径使用 heredoc 写文件保持内容纯净pull-requests.md无授权就发布发布仅限被明确授权时执行技能与参考文档本身不授予发布权无证据的 style nit 凑数没有问题时输出No findingsfinding 必须带file:line与失败场景附录仓库内相关文件索引核心参考.agents/skills/pr-review/references/posting.md本文主体技能工作流.agents/skills/pr-review/SKILL.md七步流程、发布与跟进Git 与 PR 规则.agents/references/pull-requests.md生命周期、--body-file、线程解析风险分级与评审形态.agents/references/adversarial-validation.md仓库总则AGENTS.md授权边界、finding 证据标准、验证分级PR 模板.github/pull_request_template.mdRelated Issues / Summary / Verification / Impact 四段式GitHub 工作流细则.github/AGENTS.md--body-file规范归属、actionlint 门禁按上述流程操作即可在 RustFS 仓库中稳定、合规地完成先核对 head、绑定提交、JSON 落盘、gh api --input发布的完整 Inline PR Review 提交链路。【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考