0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
Aaflyingtofix: use --body-file for long comments, --body only for short ones
7cb4cfe1创建于 20 天前历史提交

name: gitcode-pr-review description: | 对 GitCode PR 进行多维度代码评审，生成行内检视评论和整体 Review 报告。 支持代码质量、安全、架构、测试、文档同步、易用性等多维度分析， 并直接在 PR 评论区发布行内评论和整体评审意见。

TRIGGER when: 用户要求 review PR、评审代码、检查PR、PR检视、 代码评审、审查PR、分析PR变更、检查代码安全、评估PR风险、 或涉及 GitCode PR 的任何评审场景。只要是 PR 评审相关， 即使没有明确说 "review"，也应当触发此 skill。

GitCode PR 多维代码评审

对 GitCode Pull Request 进行系统化、多维度的代码评审，自动生成并发布行内检视评论和整体评审报告。

适用范围

  • GitCode 平台上的 Pull Request
  • 需要行内代码行级精确评论
  • 需要多维度审视：安全、架构、测试、文档、易用性
  • 需要直接发布评审意见到 PR 评论区

核心工作流

第一步：收集 PR 信息

一次性获取所有必要数据：

# PR 详情（JSON 便于解析元数据）
gc pr view <number> --json

# PR 代码差异（这是评审的核心材料）
gc pr diff <number>

# 已有评论（了解当前讨论上下文）
gc pr comments <number> --json

从 gc pr view --json 中提取：

  • 标题、描述、作者、状态（draft/ready）
  • base/head 分支名
  • 变更文件数和行数统计

从 gc pr diff 中提取：

  • 每个变更文件的完整 diff
  • 新增/删除的代码行
  • diff 中各文件的 hunks 和行号映射

第二步：独立验证（必须执行，不可跳过）

这是评审中最容易被忽略但最关键的一步。 PR 作者可能在描述中做出错误声明 — 例如 "遵循 XXX 模式" 但 XXX 根本不存在于代码库中。如果跳过验证直接评审，你的整个 分析可能建立在错误前提之上。

在阅读 PR diff 之前，必须完成以下验证：

1. 提取并验证 PR 描述中的所有技术声明

逐句检查 PR 标题和描述中涉及代码库事实的断言，对每一个执行代码搜索验证：

# 示例：PR 声称 "遵循 ListRepoIssuesAll 模式"
# → 必须验证该引用是否存在
grep -r "ListRepoIssuesAll" --include="*.go" .

# 如果搜索无结果 → 该声明为假，评审中必须指出
# 如果搜索有结果 → 阅读参考实现，用于后续对比分析

常见需要验证的声明类型：

  • "遵循 XXX 模式/实现" — 搜索 XXX 是否存在
  • "与 YYY 保持一致" — 对比 YYY 的实际行为
  • "修复了 ZZZ 问题" — 阅读关联 issue 确认根因
  • "沿用现有方案" — 确认现有方案确实存在且行为一致

2. 理解代码库上下文

# 搜索 PR 修改模块的已有实现（了解现有模式）
grep -r "ListIssueComments\|ListRepoIssues" --include="*.go" .

# 搜索调用方（理解变更影响范围）
grep -r "FuncName\|MethodName" --include="*.go" . | grep -v "_test.go"

# 了解现有测试风格
head -100 api/queries_issue_test.go

验证结果直接影响评审：

  • 声明为真 → 可作为评审参照基准
  • 声明为假 → 必须在评审报告中明确标注，这是重要发现
  • 声明无法验证 → 标注为 "未验证"，降低对其的依赖权重

完成以上验证后，再进入第三步分析。

第三步：多维度分析

逐文件、逐 hunk 分析代码变更，从以下维度审视：

1. 代码质量（代码行内检视）

这是最核心的维度 —— 针对具体代码行发现问题：

  • 逻辑正确性：边界条件、空值处理、错误处理是否完备
  • 代码可读性：命名是否清晰、函数是否过长、嵌套是否过深
  • 重复代码：是否有可提取的公共逻辑
  • 性能问题：不必要的循环、N+1 查询、内存泄漏风险
  • 并发安全：竞态条件、死锁风险、非线程安全的数据结构
  • 资源管理：连接/文件是否正确关闭，是否有泄漏风险

2. 安全审视

  • 注入风险：SQL/LDAP/命令注入点
  • 认证授权：权限检查是否遗漏、token/session 处理是否安全
  • 敏感数据：密钥/凭证是否硬编码、日志是否打印敏感信息
  • 输入校验：用户输入是否有校验、是否信任了客户端数据
  • 依赖安全：是否引入了已知漏洞的依赖版本

3. 架构审视

  • 设计模式：方案是否合理、是否过度设计或设计不足
  • 抽象层次：接口边界是否清晰、模块耦合度是否合适
  • 扩展性：新方案是否便于未来扩展
  • 一致性：是否与项目现有架构风格一致
  • 破坏性变更：API 签名变化是否向后兼容

4. 测试审视

  • 测试覆盖：是否为新代码添加了测试
  • 测试质量：测试是否覆盖了边界条件和异常路径
  • Mock 使用：Mock 是否合理、是否掩盖了真实问题
  • 测试可维护性：测试是否清晰、是否容易随代码演进

5. 文档同步审视

  • 接口文档：API 变更是否同步更新了文档
  • 配置说明：新增配置项是否有说明
  • 代码注释：关键逻辑是否有必要的注释
  • README/CHANGELOG：重要变更是否记录

6. 易用性审视

  • API 易用性：接口是否直观、参数命名是否合理
  • 错误信息：错误消息是否对用户有帮助
  • 日志可观测性：关键路径是否有日志、日志级别是否合理
  • 迁移成本：是否有平滑的升级/迁移路径

第四步：生成评审内容

A. 行内评论（针对具体代码行）

对于需要精确指出代码问题的场景，使用行内评论。

确定行号的方法：

  1. 从 gc pr diff 输出中定位目标文件
  2. 在 diff 中找到对应的 hunk（@@ -old,count +new,count @@ 行）
  3. 从 hunk 行下方第一行开始数，第 N 行就是 position N
    • 上下文行（以空格开头）、新增行（以 + 开头）、删除行（以 - 开头）都算一行
    • diff 的文件头（---、+++ 等）和 hunk 头（@@ ... @@）不计入 position
    • 第一个 hunk 的第一行是 position 1
  4. 不确定时，先用 --body-file - 测试评论位置，或用整体评论代替

发布行内评论：

短评论直接用 --body：

gc pr comment <number> --path "path/to/file.go" --position <diff_line_number> --body "简短评论"

含代码示例的长评论用 --body-file（避免 shell 参数长度限制）：

cat > /tmp/inline-comment.md << 'COMMENT'
**[代码质量]**: 此处存在 XXX 问题

**建议**: 
```java
// 长代码示例 ...

COMMENT gc pr comment --path "path/to/file.go" --position <diff_line_number> --body-file /tmp/inline-comment.md


**行内评论格式**：

[维度]: 问题描述

问题: 具体说明代码有什么问题 建议: 如何修改解决


示例：

[安全]: 此处存在 SQL 注入风险

问题: 用户输入 status 直接拼接到 SQL 字符串中，未做参数化处理 建议: 使用参数化查询，将 status 作为 placeholder 参数传入


#### B. 整体评审报告

对于全局性问题、总结性意见，发布整体评论。

**发布整体评论**：
```bash
gc pr review <number> --comment-file review-report.md

或通过 --comment 直接传入简评：

gc pr review <number> --comment "LGTM"

整体报告结构：

## PR 评审报告

### 整体评价
[1-2 句话概括 PR 质量和主要结论]

### 变更摘要
- **类型**: [feature/fix/refactor/docs/test/config]
- **规模**: [small/medium/large] — X 文件, +Y/-Z 行
- **核心变更**: [一句话描述改了什么]

### 各维度评估

| 维度 | 评级 | 说明 |
|------|------|------|
| 代码质量 | ✅/⚠️/❌ | [简要] |
| 安全性 | ✅/⚠️/❌ | [简要] |
| 架构 | ✅/⚠️/❌ | [简要] |
| 测试 | ✅/⚠️/❌ | [简要] |
| 文档同步 | ✅/⚠️/❌ | [简要] |
| 易用性 | ✅/⚠️/❌ | [简要] |

### 关键发现

#### 🔴 阻塞问题（必须修改）
1. **[文件:行号] 问题描述** — 原因和建议

#### 🟡 建议改进（推荐修改）
1. **[文件:行号] 建议描述** — 改进方向

#### 🟢 优秀实践（值得肯定）
1. [指出做得好的地方]

### 测试建议
- 需新增的测试用例
- 需验证的边界条件
- 建议的手动验证步骤

### 最终建议
- [ ] 通过（可合并）
- [ ] 通过（有小建议，非阻塞）
- [ ] 需修改后再审
- [ ] 建议关闭/重新设计

第五步：发布评论

按以下顺序发布：

  1. 先发所有行内评论 —— 每个具体问题一行内评论，精确指向代码
  2. 再发整体报告 —— 作为综合性的总结评论

发布前与用户确认评论内容的合理性，尤其是阻塞性问题。

评审原则

  • 先验证再评论（最重要原则）：PR 描述中的技术声明必须通过代码库搜索独立验证。跳过这一步曾导致真实评审失败 —— 模型盲目相信了 PR 描述中的 "遵循 ListRepoIssuesAll 模式"，但该函数在代码库中根本不存在。如果你没有在 grep 中亲眼看到搜索结果，就当作它不存在
  • 具体优于笼统：行内评论必须精确指向代码行，整体评论需引用具体文件名和行号
  • 建议优于批评：每个问题都附带具体、可操作的修改建议
  • 理解上下文：先阅读已有评论，了解 PR 背景和讨论脉络
  • 分级清晰：区分阻塞问题（必须改）和建议改进（推荐改）
  • 肯定优点：做得好也要明确指出，营造正向评审氛围
  • 量体裁衣：小型 PR 精简评审，大型 PR 聚焦核心变更

注意事项

  • Draft PR 不需要完整评审，但可提供初步反馈
  • 大型 PR（>500 行变更）聚焦核心变更和高风险点，避免逐行评审
  • 发布评论前务必与用户确认，尤其是有 block 级别的评论
  • --position 是 diff 中的位置（从 1 开始），不是文件绝对行号
  • gc pr review --comment-file 从文件读取内容，适合长评论
  • 行内评论使用 gc pr comment --path --position，整体评论使用 gc pr review --comment
  • 如果 PR 已有他人评论，先阅读再补充，避免重复

示例用法

完整多维评审：

全面 review PR #42，包括安全、架构、测试、文档各方面

聚焦安全评审：

review PR #128，重点检查安全漏洞和敏感数据处理

快速检查：

快速扫一下 PR #15，看看有没有明显问题

生成评审报告（不发布）：

分析 PR #67 的变更，给我一份评审报告，先不要发布到 PR 上