基于 gh CLI 的 AI 代码评审全流程Opik 仓库review-github-pr命令深度解析【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读本文以 Opikcomet-llm仓库中的 Agent 命令规范 .agents/commands/comet/review-github-pr.md 为核心完整拆解cursor review-github-pr命令的九步执行流水线从ghCLI 预检、PR 定位与 diff 拉取到基于 Opik 领域知识的分类评审、四档严重级别分级、用户逐条审批再到以单次批量 review 形式回帖并附 AI 水印。读完本文你将掌握一套AI 生成评审意见、人类掌控发布权、绝不替代正式审批的可复用 PR 评审自动化方案并理解它与address-github-pr-comments命令如何组成提出评审—响应评审的闭环。1. 命令定位生成评审意见而非响应评审意见在 Opik 仓库的 Agent 体系.agents/目录中review-github-pr与address-github-pr-comments是一对互补命令review-github-pr.md给定 PR 编号/URL或从当前分支自动探测拉取comet-ml/opik的 PR diff执行代码评审向用户展示发现并在用户批准后将评审评论直接发布到 PR 上。它生成评审反馈。address-github-pr-comments.md反向操作——收集当前分支 PR 上尚未处理的评审意见逐条提出应对方案修复 / 跳过 / 回复并发布带 *Reply posted via /address-github-pr-comments*标记的回复。它响应评审反馈。该命令与 code-reviewer.md Agent 的定位也有明确分工code-reviewer面向开发者本地git diff的质量门禁式自查涵盖安全、多租户隔离、正确性等清单而review-github-pr面向 PR 生命周期中把评审结果写回 GitHub这一发布动作两者共享同一套 Opik 领域知识库。执行模型每次调用都从零开始Always runs from scratch每次执行都会重新拉取 PR、重新分析 diff、重新生成发现不做状态缓存ghCLI 是唯一硬性依赖GitHub MCP 仅用于更丰富的读取若不可用则全程降级到ghCLI无需任何额外配置永不提交正式评审结论只通过event: COMMENT发布单条评论绝不发送 approve 或 request changes正式审批必须由人类评审者完成幂等安全每次完整重跑但会基于path start_line line与已发布的 AI 评论去重同一 PR 上重复运行只会发布新增发现。2. 输入与预检环境就绪检查2.1 输入输入说明PR 编号纯数字例如5395PR 完整 URL例如https://github.com/comet-ml/opik/pull/5395从中提取编号省略从当前 Git 分支自动探测对应 PR2.2 预检Step 1校验ghCLI读取和发布都依赖它必须已安装且已认证gh auth status若未认证命令直接停止并提示Please rungh auth loginfirst.探测 GitHub MCP可选若可用则用于获取更丰富的 PR 数据如结构化文件信息不可用则全程回退到ghCLI。仓库根目录的 .agents/mcp.json 集中声明了 Agent 体系可用的 MCP 服务器这也是address-github-pr-comments命令把GitHub MCP 不可用当作硬性停止条件的依据它需要 MCP 读取而本命令只需gh。3. 定位 PR 并获取元数据Step 2定位策略分两种情况有参数时——数字直接作为 PR 编号URL 则提取编号。无参数时——检查当前 Git 分支并在comet-ml/opik中查找该分支的开放 PRgh pr list --repo comet-ml/opik --head branch-name --state open --json number,title,url若未找到提示No open PR found for this branch. Enter a PR number or URL:随后拉取 PR 元数据标题、描述、作者、基线分支、状态gh pr view {pr_number} --repo comet-ml/opik --json title,body,author,baseRefName,state,headRefOid若 PR 已合并或关闭打印警告并询问用户是否仍要继续评审draft 状态的 PR 同样给出警告但允许继续。领域背景仓库的分支命名遵循 git-workflow.mdc 中的{username}/{ticket}-{summary}约定例如andrescrz/OPIK-2180-add-feature因此从分支名即可提取 ticket keyheadRefOid用于后续批量 review 的commit_id字段。4. 拉取 diff、变更文件与既有评审记录Step 34.1 读取既有评审评论去重基础在分析前先收集本命令此前在该 PR 上发布过的评论用于第 6 步去重gh api repos/comet-ml/opik/pulls/{pr_number}/comments --paginate过滤出包含 *Review posted via /review-github-pr*标记的评论并以path start_line line为键建立索引单行评论中start_line等于line。这样当命令在同一 PR 上重复运行时不会重复发布相同的评论。4.2 获取变更文件与完整 diff# 仅文件名 gh pr diff {pr_number} --repo comet-ml/opik --name-only # 完整 diff gh pr diff {pr_number} --repo comet-ml/opik若 GitHub MCP 可用可用get_pull_request_files获取结构化的文件数据增删行数、patch。4.3 按领域对文件分类这是领域感知Domain-aware评审的核心——不同的代码域套用不同的评审标准领域路径模式关注点Backendapps/opik-backend/**Java、API、services、DAOs、migrationsFrontendapps/opik-frontend/**React、TypeScript、components、hooksPython SDKsdks/python/**Python SDK 模式TypeScript SDKsdks/opik-typescript/**TypeScript SDK 模式E2E Teststests_end_to_end/**Playwright 测试Docs*.md、docs/**文档Config/InfraDocker、CI/CD、配置文件基础设施跳过二进制文件和 lock 文件标记敏感文件——匹配.env、.pem、.key、credentials.*、*.secret等模式的文件要被标记发布评论时不得引用其中的原始内容只能发布不引用敏感值的高层提示。5. 领域感知的 diff 分析Step 4分析基于.agents/skills/与.agents/rules/中的 Opik 专属规则skills/README.md 是技能目录索引按 PR 触及的领域套用相应标准。通用标准所有文件安全SQL 注入、XSS、硬编码密钥、边界输入校验错误处理错误是否正确传播、是否有被吞掉的异常命名变量/函数/类命名是否清晰一致逻辑off-by-one、null/undefined 处理、竞态条件测试新代码路径是否被测试覆盖。Backendapps/opik-backend/**架构分层Resource → Service → DAO → Models 模式对应 opik-backend/SKILL.md 中Layered: Resource → Service → DAO (never skip layers)的约定SQL参数化查询、正确的事务处理APIRESTful 约定、正确的 HTTP 状态码、输入校验Migrations向后兼容的 schema 变更、支持回滚日志合适的日志级别、日志中不出现敏感数据。这里尤其值得展开的是 SQL 查询构造规则。仓库的 security.mdc 与 opik-backend/SKILL.md 都明确规定禁止用 Java 字符串运算拼 SQL不允许、String.format/.formatted(...)、StringBuilder、MessageFormat、String.join查询声明为一次性的 text block变体只通过两种机制什么在变机制值id、name、timestamp、id 列表:placeholder.bind(placeholder, value)片段谓词、排序子句、投影列、CTEStringTemplateif(x)…endif、else、xtemplate.add(...)原因是插值值会形成 SQL 注入面插值片段会让 DAO 实际执行的查询变得不可读。如果片段确实无法在模板中枚举如用户选择的排序字段必须由白名单构建器SortingQueryBuilder、FilterQueryBuilder生成绝不从原始请求字符串拼接。评审时即使被拼接的片段当前是常量只要 diff新增或修改了此类查询就要标记——下一个调用者正是让它变得可注入的元凶diff 未触及的存量问题属于已知技术债不算 finding。Frontendapps/opik-frontend/**组件React 模式是否正确、hook 依赖、必要的 memoization状态状态管理是否恰当、避免 props drilling类型TypeScript 类型安全、避免不必要的any性能不必要的重渲染、大体积 bundle 导入可访问性正确的 ARIA 属性、键盘导航。SDKssdks/**API 兼容性破坏性变更必须标记错误处理清晰的错误消息、合理的异常层级文档公共 API 方法有完整文档。佐证code-reviewerAgent.agents/agents/code-reviewer.md为上述前端/SDK 检查补充了更细的清单——TanStack Query 而非 useEffect、Zustand selector 具体化、useMemo/useCallback、Lodash 直接导入而非 barrel 导入、测试中flush()先于断言等可作为评审发现的参考来源。6. 生成分级评审发现Step 5严重级别级别图标含义blocker合并前必须修复——bug、安全问题、数据丢失风险suggestion建议改进——更佳模式、性能、可读性nit次要风格/偏好——命名、格式、小简化question❓需要澄清——意图不明、缺少上下文、设计决策每条发现的结构文件与行范围问题在 diff 中的位置类别Security、Logic、Performance、Style、Architecture、Testing 等严重级别blocker / suggestion / nit / question描述问题的清晰说明建议可选使用 GitHub suggestion 语法给出的具体代码建议。7. 去重、展示与用户审批Step 6去重将新发现与第 3 步拉取的既有/review-github-pr评论对比若某条发现命中相同path start_line line标记为 already posted 并从列表剔除。若全部都是重复项打印 All findings were already posted in a previous run. 并停止。展示摘要按严重级别汇总例如Found 2 blockers, 3 suggestions, 1 nit, 1 question — 1 already posted, skipped。逐条展示每条发现展示diff 中的相关代码片段、将要发布的评审评论、代码建议如有。用户决策选项Post all发布全部发现Post blockers only只发布 blocker 级发现Post all except nits发布 blocker、suggestion、questionCherry-pick逐条选择——每条可Post原样发布、Edit修改评论文本后发布、Skip不发布。设计原则没有任何内容会在未经用户明确同意的情况下发布Nothing is posted without explicit user consent这是命令的硬性约束之一。8. 发布评审评论Step 78.1 主路径单次批量 review所有获批准的评论收集为一个 JSON payload以一次 review 提交无论多少条评论作者只收到一次通知gh api repos/comet-ml/opik/pulls/{pr_number}/reviews \ --input - EOF { commit_id: head_sha, event: COMMENT, comments: [ { path: file_path, line: line_number, side: RIGHT, body: comment text with AI marker }, { path: file_path, start_line: start_line, line: end_line, start_side: RIGHT, side: RIGHT, body: multi-line comment text with AI marker } ] } EOF要点event恒为COMMENT绝不 approve / request changes多行评论用start_lineline表示范围commit_id来自第 2 步的headRefOid。8.2 回退路径逐条评论若批量 review 失败例如某条评论引用了 diff 中不存在的行识别失败的评论将有效的逐条发布gh api repos/comet-ml/opik/pulls/{pr_number}/comments \ -f bodycomment text \ -f pathfile_path \ -f commit_idhead_sha \ -F lineline_number \ -f sideRIGHT逐条仍然失败的如行不在 diff 中降级为 PR 级普通评论并记录日志。8.3 代码建议语法需要给出具体改法时在评论正文中使用 GitHub suggestion 语法作者可一键应用description of the suggestion suggestion replacement code 8.4 非行级评论PR 级针对整体架构、缺失测试等不绑定具体行的评论发布为 issue 评论无法纳入批量 review需单独发布gh api repos/comet-ml/opik/issues/{pr_number}/comments \ -f bodycomment text8.5 密钥净化Secret Sanitization发布前必须扫描评论正文中的常见密钥模式API keys、bearer tokens、私钥块、长 hex/base64 字符串、export VARvalue赋值。检测到的值一律替换为[REDACTED]。对第 3 步标记的敏感文件评论正文中绝不包含原始内容——只引用文件与行范围。这与 security.mdc 中Never: Hardcode secrets… Log sensitive data的要求一脉相承。8.6 AI 水印所有发布的评论必须包含页脚标记用于与人类评论区分 *Review posted via /review-github-pr*8.7 示例评论 **blocker** | Security This query concatenates user input directly. Use parameterized queries instead. suggestion String query SELECT * FROM traces WHERE id ?; jdbi.withHandle(h - h.createQuery(query).bind(0, traceId).mapTo(Trace.class).one()); *Review posted via /review-github-pr* **suggestion** | Performance Consider using batch insert here to avoid N1 queries. *Review posted via /review-github-pr* **nit** | Style This variable name could be more descriptive. *Review posted via /review-github-pr*❓ **question** | Architecture Is this intentionally bypassing the service layer? The other endpoints go through SpanService first. *Review posted via /review-github-pr*9. 生成并审批总结评论Step 8行内评论处理完毕后生成一条 PR 级总结评论给作者一个高层视角。内容四要素正面观察Always lead with these指出 PR 做得好的地方——清晰的架构、良好的测试覆盖、清晰的命名、聪明的抽象、周全的错误处理、结构良好的 migration 等。要具体且真诚不虚构赞美方案评估对 PR 整体的简要诚实评价——方案是否合理范围是否恰当是否有行内评论未覆盖的结构性问题发现回顾一行概括行内标记内容如 Left 2 suggestions and 1 nit — nothing blocking语气支持性、建设性让作者感到工作被看见、被重视同时诚实指出改进点。格式模板 **Review summary** **What looks good** - specific positive observation - another positive observation **Overall** 1–3 sentences on the PR as a solution **Inline comments**: count by severity, e.g., 2 suggestions, 1 nit (or None — looks clean! if no findings were posted) *Review posted via /review-github-pr*审批与去重发布前向用户展示提供Post / Edit / Skip三选项去重先检查是否存在同时包含 **Review summary**与 AI 标记的历史总结评论若存在则提示 A summary comment was already posted in a previous run. 并跳过本步。发布命令gh api repos/comet-ml/opik/issues/{pr_number}/comments \ -f bodysummary comment10. 本地总结与成功标准10.1 本地总结Step 9所有发布完成后在本地而非 GitHub 上向用户展示已发布的行内评论总数按严重级别跳过的行内评论总数总结评论是发布、编辑还是跳过PR 链接提醒This review does not constitute an approval. A human reviewer should still approve the PR.10.2 成功标准Success Criteria命令在以下全部满足时才算成功✅ghCLI 可用且已认证✅ PR 已定位且元数据已获取✅ PR diff 与变更文件已获取✅ 使用领域知识完成变更分析✅ 发现已按严重级别与类别向用户展示✅ 用户批准了要发布的发现✅ 获批的行内评论已带 AI 标记发布✅ 总结评论已展示给用户并获得批准后发布若获批✅ 本地总结已展示发布/跳过数量。11. 错误处理全景阶段错误场景处理策略CLI 认证gh未安装停止并提供安装指引CLI 认证gh未认证停止并指示运行gh auth loginPR 发现未找到 PR提示手动输入或停止PR 发现PR 编号/URL 非法展示期望格式并重新提示PR 发现PR 为 draft警告但允许继续diff 获取diff 过大分批评审文件警告可能遗漏上下文diff 获取二进制文件跳过并记录diff 获取API 限流等待重试或给出指引后停止评论发布行不在 diff 中降级为 PR 级普通评论评论发布权限拒绝检查仓库访问权限与gh认证评论发布API 错误展示错误详情、跳过该评论、继续其余部分12. 设计要点与边界约束Notes汇总命令文档末尾的 Notes它们是这套流程区别于通用 PR 评审工具的关键仓库固定始终针对comet-ml/opikghCLI 是唯一硬性依赖GitHub MCP 可选仅用于更丰富的读取所有操作均可仅凭ghCLI 完成不提交正式评审只以event: COMMENT提交永不 approve / request changes人类评审者必须正式批准与address-github-pr-comments互补一个生成评审反馈一个响应评审反馈两者都通过gh api发布带 AI 标记的评论AI 标记必带每条评论都必须带 *Review posted via /review-github-pr*页脚绝不遗漏领域感知使用 .agents/skills/ 与 .agents/rules/ 中的 Opik 专属规则提供项目特有的反馈而非泛泛而谈用户控制每条发现发布前都要经过批准未经明确同意不发布任何内容幂等每次完整重跑分析但按path start_line line与既有/review-github-pr评论去重可安全重复运行只发布新发现严重级别驱动发现按严重级别组织帮助用户优先处理关键问题代码建议使用 GitHub suggestion 语法作者可一键应用修复刻意不做正式审批命令被刻意限制为不能提交正式评审代码评审的批准必须保留人在回环human-in-the-loop只增不删命令只创建内容从不删除文件、评论或其他内容。13. 从评审到回应的完整闭环将本文主题与姊妹命令串联起来就构成了一条完整的 PR 评审自动化流水线cursor review-github-pr生成并发布带 AI 水印的评审评论 *Review posted via /review-github-pr*开发者按 suggestion 修复或回应每条评论cursor address-github-pr-comments重新拉取三类反馈源pulls/{N}/comments行内评论、issues/{N}/commentsissue 线程评论、pulls/{N}/reviewsPR 级 review body识别尚未处理的项逐条选择修复/跳过/回复发布带 *Reply posted via /address-github-pr-comments*标记的回复并可选择性地解析已处理的 review threads两条命令都通过相同的gh api通道、相同的 AI 标记约定、相同的先征求用户批准原则工作任何一方都不会代表人类做出最终批准决定。这套设计保证了AI 负责繁重的 diff 分析与初稿生成人类保留对发什么、何时发、是否批准的完整控制权——这正是生产级代码仓库中引入 AI 评审的稳妥形态。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 gh CLI 的 AI 代码评审全流程：Opik 仓库 `review-github-pr` 命令深度解析
基于 gh CLI 的 AI 代码评审全流程Opik 仓库review-github-pr命令深度解析【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读本文以 Opikcomet-llm仓库中的 Agent 命令规范 .agents/commands/comet/review-github-pr.md 为核心完整拆解cursor review-github-pr命令的九步执行流水线从ghCLI 预检、PR 定位与 diff 拉取到基于 Opik 领域知识的分类评审、四档严重级别分级、用户逐条审批再到以单次批量 review 形式回帖并附 AI 水印。读完本文你将掌握一套AI 生成评审意见、人类掌控发布权、绝不替代正式审批的可复用 PR 评审自动化方案并理解它与address-github-pr-comments命令如何组成提出评审—响应评审的闭环。1. 命令定位生成评审意见而非响应评审意见在 Opik 仓库的 Agent 体系.agents/目录中review-github-pr与address-github-pr-comments是一对互补命令review-github-pr.md给定 PR 编号/URL或从当前分支自动探测拉取comet-ml/opik的 PR diff执行代码评审向用户展示发现并在用户批准后将评审评论直接发布到 PR 上。它生成评审反馈。address-github-pr-comments.md反向操作——收集当前分支 PR 上尚未处理的评审意见逐条提出应对方案修复 / 跳过 / 回复并发布带 *Reply posted via /address-github-pr-comments*标记的回复。它响应评审反馈。该命令与 code-reviewer.md Agent 的定位也有明确分工code-reviewer面向开发者本地git diff的质量门禁式自查涵盖安全、多租户隔离、正确性等清单而review-github-pr面向 PR 生命周期中把评审结果写回 GitHub这一发布动作两者共享同一套 Opik 领域知识库。执行模型每次调用都从零开始Always runs from scratch每次执行都会重新拉取 PR、重新分析 diff、重新生成发现不做状态缓存ghCLI 是唯一硬性依赖GitHub MCP 仅用于更丰富的读取若不可用则全程降级到ghCLI无需任何额外配置永不提交正式评审结论只通过event: COMMENT发布单条评论绝不发送 approve 或 request changes正式审批必须由人类评审者完成幂等安全每次完整重跑但会基于path start_line line与已发布的 AI 评论去重同一 PR 上重复运行只会发布新增发现。2. 输入与预检环境就绪检查2.1 输入输入说明PR 编号纯数字例如5395PR 完整 URL例如https://github.com/comet-ml/opik/pull/5395从中提取编号省略从当前 Git 分支自动探测对应 PR2.2 预检Step 1校验ghCLI读取和发布都依赖它必须已安装且已认证gh auth status若未认证命令直接停止并提示Please rungh auth loginfirst.探测 GitHub MCP可选若可用则用于获取更丰富的 PR 数据如结构化文件信息不可用则全程回退到ghCLI。仓库根目录的 .agents/mcp.json 集中声明了 Agent 体系可用的 MCP 服务器这也是address-github-pr-comments命令把GitHub MCP 不可用当作硬性停止条件的依据它需要 MCP 读取而本命令只需gh。3. 定位 PR 并获取元数据Step 2定位策略分两种情况有参数时——数字直接作为 PR 编号URL 则提取编号。无参数时——检查当前 Git 分支并在comet-ml/opik中查找该分支的开放 PRgh pr list --repo comet-ml/opik --head branch-name --state open --json number,title,url若未找到提示No open PR found for this branch. Enter a PR number or URL:随后拉取 PR 元数据标题、描述、作者、基线分支、状态gh pr view {pr_number} --repo comet-ml/opik --json title,body,author,baseRefName,state,headRefOid若 PR 已合并或关闭打印警告并询问用户是否仍要继续评审draft 状态的 PR 同样给出警告但允许继续。领域背景仓库的分支命名遵循 git-workflow.mdc 中的{username}/{ticket}-{summary}约定例如andrescrz/OPIK-2180-add-feature因此从分支名即可提取 ticket keyheadRefOid用于后续批量 review 的commit_id字段。4. 拉取 diff、变更文件与既有评审记录Step 34.1 读取既有评审评论去重基础在分析前先收集本命令此前在该 PR 上发布过的评论用于第 6 步去重gh api repos/comet-ml/opik/pulls/{pr_number}/comments --paginate过滤出包含 *Review posted via /review-github-pr*标记的评论并以path start_line line为键建立索引单行评论中start_line等于line。这样当命令在同一 PR 上重复运行时不会重复发布相同的评论。4.2 获取变更文件与完整 diff# 仅文件名 gh pr diff {pr_number} --repo comet-ml/opik --name-only # 完整 diff gh pr diff {pr_number} --repo comet-ml/opik若 GitHub MCP 可用可用get_pull_request_files获取结构化的文件数据增删行数、patch。4.3 按领域对文件分类这是领域感知Domain-aware评审的核心——不同的代码域套用不同的评审标准领域路径模式关注点Backendapps/opik-backend/**Java、API、services、DAOs、migrationsFrontendapps/opik-frontend/**React、TypeScript、components、hooksPython SDKsdks/python/**Python SDK 模式TypeScript SDKsdks/opik-typescript/**TypeScript SDK 模式E2E Teststests_end_to_end/**Playwright 测试Docs*.md、docs/**文档Config/InfraDocker、CI/CD、配置文件基础设施跳过二进制文件和 lock 文件标记敏感文件——匹配.env、.pem、.key、credentials.*、*.secret等模式的文件要被标记发布评论时不得引用其中的原始内容只能发布不引用敏感值的高层提示。5. 领域感知的 diff 分析Step 4分析基于.agents/skills/与.agents/rules/中的 Opik 专属规则skills/README.md 是技能目录索引按 PR 触及的领域套用相应标准。通用标准所有文件安全SQL 注入、XSS、硬编码密钥、边界输入校验错误处理错误是否正确传播、是否有被吞掉的异常命名变量/函数/类命名是否清晰一致逻辑off-by-one、null/undefined 处理、竞态条件测试新代码路径是否被测试覆盖。Backendapps/opik-backend/**架构分层Resource → Service → DAO → Models 模式对应 opik-backend/SKILL.md 中Layered: Resource → Service → DAO (never skip layers)的约定SQL参数化查询、正确的事务处理APIRESTful 约定、正确的 HTTP 状态码、输入校验Migrations向后兼容的 schema 变更、支持回滚日志合适的日志级别、日志中不出现敏感数据。这里尤其值得展开的是 SQL 查询构造规则。仓库的 security.mdc 与 opik-backend/SKILL.md 都明确规定禁止用 Java 字符串运算拼 SQL不允许、String.format/.formatted(...)、StringBuilder、MessageFormat、String.join查询声明为一次性的 text block变体只通过两种机制什么在变机制值id、name、timestamp、id 列表:placeholder.bind(placeholder, value)片段谓词、排序子句、投影列、CTEStringTemplateif(x)…endif、else、xtemplate.add(...)原因是插值值会形成 SQL 注入面插值片段会让 DAO 实际执行的查询变得不可读。如果片段确实无法在模板中枚举如用户选择的排序字段必须由白名单构建器SortingQueryBuilder、FilterQueryBuilder生成绝不从原始请求字符串拼接。评审时即使被拼接的片段当前是常量只要 diff新增或修改了此类查询就要标记——下一个调用者正是让它变得可注入的元凶diff 未触及的存量问题属于已知技术债不算 finding。Frontendapps/opik-frontend/**组件React 模式是否正确、hook 依赖、必要的 memoization状态状态管理是否恰当、避免 props drilling类型TypeScript 类型安全、避免不必要的any性能不必要的重渲染、大体积 bundle 导入可访问性正确的 ARIA 属性、键盘导航。SDKssdks/**API 兼容性破坏性变更必须标记错误处理清晰的错误消息、合理的异常层级文档公共 API 方法有完整文档。佐证code-reviewerAgent.agents/agents/code-reviewer.md为上述前端/SDK 检查补充了更细的清单——TanStack Query 而非 useEffect、Zustand selector 具体化、useMemo/useCallback、Lodash 直接导入而非 barrel 导入、测试中flush()先于断言等可作为评审发现的参考来源。6. 生成分级评审发现Step 5严重级别级别图标含义blocker合并前必须修复——bug、安全问题、数据丢失风险suggestion建议改进——更佳模式、性能、可读性nit次要风格/偏好——命名、格式、小简化question❓需要澄清——意图不明、缺少上下文、设计决策每条发现的结构文件与行范围问题在 diff 中的位置类别Security、Logic、Performance、Style、Architecture、Testing 等严重级别blocker / suggestion / nit / question描述问题的清晰说明建议可选使用 GitHub suggestion 语法给出的具体代码建议。7. 去重、展示与用户审批Step 6去重将新发现与第 3 步拉取的既有/review-github-pr评论对比若某条发现命中相同path start_line line标记为 already posted 并从列表剔除。若全部都是重复项打印 All findings were already posted in a previous run. 并停止。展示摘要按严重级别汇总例如Found 2 blockers, 3 suggestions, 1 nit, 1 question — 1 already posted, skipped。逐条展示每条发现展示diff 中的相关代码片段、将要发布的评审评论、代码建议如有。用户决策选项Post all发布全部发现Post blockers only只发布 blocker 级发现Post all except nits发布 blocker、suggestion、questionCherry-pick逐条选择——每条可Post原样发布、Edit修改评论文本后发布、Skip不发布。设计原则没有任何内容会在未经用户明确同意的情况下发布Nothing is posted without explicit user consent这是命令的硬性约束之一。8. 发布评审评论Step 78.1 主路径单次批量 review所有获批准的评论收集为一个 JSON payload以一次 review 提交无论多少条评论作者只收到一次通知gh api repos/comet-ml/opik/pulls/{pr_number}/reviews \ --input - EOF { commit_id: head_sha, event: COMMENT, comments: [ { path: file_path, line: line_number, side: RIGHT, body: comment text with AI marker }, { path: file_path, start_line: start_line, line: end_line, start_side: RIGHT, side: RIGHT, body: multi-line comment text with AI marker } ] } EOF要点event恒为COMMENT绝不 approve / request changes多行评论用start_lineline表示范围commit_id来自第 2 步的headRefOid。8.2 回退路径逐条评论若批量 review 失败例如某条评论引用了 diff 中不存在的行识别失败的评论将有效的逐条发布gh api repos/comet-ml/opik/pulls/{pr_number}/comments \ -f bodycomment text \ -f pathfile_path \ -f commit_idhead_sha \ -F lineline_number \ -f sideRIGHT逐条仍然失败的如行不在 diff 中降级为 PR 级普通评论并记录日志。8.3 代码建议语法需要给出具体改法时在评论正文中使用 GitHub suggestion 语法作者可一键应用description of the suggestion suggestion replacement code 8.4 非行级评论PR 级针对整体架构、缺失测试等不绑定具体行的评论发布为 issue 评论无法纳入批量 review需单独发布gh api repos/comet-ml/opik/issues/{pr_number}/comments \ -f bodycomment text8.5 密钥净化Secret Sanitization发布前必须扫描评论正文中的常见密钥模式API keys、bearer tokens、私钥块、长 hex/base64 字符串、export VARvalue赋值。检测到的值一律替换为[REDACTED]。对第 3 步标记的敏感文件评论正文中绝不包含原始内容——只引用文件与行范围。这与 security.mdc 中Never: Hardcode secrets… Log sensitive data的要求一脉相承。8.6 AI 水印所有发布的评论必须包含页脚标记用于与人类评论区分 *Review posted via /review-github-pr*8.7 示例评论 **blocker** | Security This query concatenates user input directly. Use parameterized queries instead. suggestion String query SELECT * FROM traces WHERE id ?; jdbi.withHandle(h - h.createQuery(query).bind(0, traceId).mapTo(Trace.class).one()); *Review posted via /review-github-pr* **suggestion** | Performance Consider using batch insert here to avoid N1 queries. *Review posted via /review-github-pr* **nit** | Style This variable name could be more descriptive. *Review posted via /review-github-pr*❓ **question** | Architecture Is this intentionally bypassing the service layer? The other endpoints go through SpanService first. *Review posted via /review-github-pr*9. 生成并审批总结评论Step 8行内评论处理完毕后生成一条 PR 级总结评论给作者一个高层视角。内容四要素正面观察Always lead with these指出 PR 做得好的地方——清晰的架构、良好的测试覆盖、清晰的命名、聪明的抽象、周全的错误处理、结构良好的 migration 等。要具体且真诚不虚构赞美方案评估对 PR 整体的简要诚实评价——方案是否合理范围是否恰当是否有行内评论未覆盖的结构性问题发现回顾一行概括行内标记内容如 Left 2 suggestions and 1 nit — nothing blocking语气支持性、建设性让作者感到工作被看见、被重视同时诚实指出改进点。格式模板 **Review summary** **What looks good** - specific positive observation - another positive observation **Overall** 1–3 sentences on the PR as a solution **Inline comments**: count by severity, e.g., 2 suggestions, 1 nit (or None — looks clean! if no findings were posted) *Review posted via /review-github-pr*审批与去重发布前向用户展示提供Post / Edit / Skip三选项去重先检查是否存在同时包含 **Review summary**与 AI 标记的历史总结评论若存在则提示 A summary comment was already posted in a previous run. 并跳过本步。发布命令gh api repos/comet-ml/opik/issues/{pr_number}/comments \ -f bodysummary comment10. 本地总结与成功标准10.1 本地总结Step 9所有发布完成后在本地而非 GitHub 上向用户展示已发布的行内评论总数按严重级别跳过的行内评论总数总结评论是发布、编辑还是跳过PR 链接提醒This review does not constitute an approval. A human reviewer should still approve the PR.10.2 成功标准Success Criteria命令在以下全部满足时才算成功✅ghCLI 可用且已认证✅ PR 已定位且元数据已获取✅ PR diff 与变更文件已获取✅ 使用领域知识完成变更分析✅ 发现已按严重级别与类别向用户展示✅ 用户批准了要发布的发现✅ 获批的行内评论已带 AI 标记发布✅ 总结评论已展示给用户并获得批准后发布若获批✅ 本地总结已展示发布/跳过数量。11. 错误处理全景阶段错误场景处理策略CLI 认证gh未安装停止并提供安装指引CLI 认证gh未认证停止并指示运行gh auth loginPR 发现未找到 PR提示手动输入或停止PR 发现PR 编号/URL 非法展示期望格式并重新提示PR 发现PR 为 draft警告但允许继续diff 获取diff 过大分批评审文件警告可能遗漏上下文diff 获取二进制文件跳过并记录diff 获取API 限流等待重试或给出指引后停止评论发布行不在 diff 中降级为 PR 级普通评论评论发布权限拒绝检查仓库访问权限与gh认证评论发布API 错误展示错误详情、跳过该评论、继续其余部分12. 设计要点与边界约束Notes汇总命令文档末尾的 Notes它们是这套流程区别于通用 PR 评审工具的关键仓库固定始终针对comet-ml/opikghCLI 是唯一硬性依赖GitHub MCP 可选仅用于更丰富的读取所有操作均可仅凭ghCLI 完成不提交正式评审只以event: COMMENT提交永不 approve / request changes人类评审者必须正式批准与address-github-pr-comments互补一个生成评审反馈一个响应评审反馈两者都通过gh api发布带 AI 标记的评论AI 标记必带每条评论都必须带 *Review posted via /review-github-pr*页脚绝不遗漏领域感知使用 .agents/skills/ 与 .agents/rules/ 中的 Opik 专属规则提供项目特有的反馈而非泛泛而谈用户控制每条发现发布前都要经过批准未经明确同意不发布任何内容幂等每次完整重跑分析但按path start_line line与既有/review-github-pr评论去重可安全重复运行只发布新发现严重级别驱动发现按严重级别组织帮助用户优先处理关键问题代码建议使用 GitHub suggestion 语法作者可一键应用修复刻意不做正式审批命令被刻意限制为不能提交正式评审代码评审的批准必须保留人在回环human-in-the-loop只增不删命令只创建内容从不删除文件、评论或其他内容。13. 从评审到回应的完整闭环将本文主题与姊妹命令串联起来就构成了一条完整的 PR 评审自动化流水线cursor review-github-pr生成并发布带 AI 水印的评审评论 *Review posted via /review-github-pr*开发者按 suggestion 修复或回应每条评论cursor address-github-pr-comments重新拉取三类反馈源pulls/{N}/comments行内评论、issues/{N}/commentsissue 线程评论、pulls/{N}/reviewsPR 级 review body识别尚未处理的项逐条选择修复/跳过/回复发布带 *Reply posted via /address-github-pr-comments*标记的回复并可选择性地解析已处理的 review threads两条命令都通过相同的gh api通道、相同的 AI 标记约定、相同的先征求用户批准原则工作任何一方都不会代表人类做出最终批准决定。这套设计保证了AI 负责繁重的 diff 分析与初稿生成人类保留对发什么、何时发、是否批准的完整控制权——这正是生产级代码仓库中引入 AI 评审的稳妥形态。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考