Code Review Assistant

Overview

提供结构化的代码审核工作流程，支持两种审核模式：

本地 Git 模式

• 审核当前最新 commit

• 审核暂存的修改 (git add 的文件)

• 审核未暂存的修改（工作区变更）

• 审核指定 commit 的 diff

Gerrit Review 模式

• 通过 Gerrit Change ID 进行代码审核

• 自动获取 Change 详情和文件变更

• 支持自动发布评审到 Gerrit

支持的语言：

• Golang（完整支持）

• Qt/C++（完整支持）

• Ansible（完整支持）

Review 评分规则

问题类型 建议 Score 说明

无问题 +1 代码质量优秀

仅有 Nice to Have -1 有改进空间但不影响功能

有 Should Fix -2 应该修复的问题

有 Must Fix -2 必须修复的严重问题

使用方式

本地 Git 审核用例

/code-review-assistant HEAD # 审核最新 commit /code-review-assistant --staged # 审核暂存的修改 /code-review-assistant --unstaged # 审核未暂存的修改 /code-review-assistant HEAD~1 # 审核上一个 commit /code-review-assistant abc1234 # 审核指定 commit hash

Gerrit Review 用例

/code-review-assistant <change_id> # 审核 Gerrit Change

自动发布评论（仅 Gerrit 模式）

如果用户提示词中包含明确的发布请求（如"发布评论"、"提交评审"、"post review"、"发布到 Gerrit"等关键词），skill 会自动使用 Gerrit MCP 工具发布带评分的评论。

审核范围规范

支持的本地 Git 审核范围

用例 Git 命令 说明

最新 commit HEAD

审核最新的提交记录

上一个 commit HEAD~1 或 HEAD^

审核倒数第二次提交

指定 commit <commit_hash>

审核指定的某次提交

暂存的修改 --staged 或 --cached

审核已 git add 但未提交的变更

未暂存的修改 --unstaged 或 --working

审核工作区的变更

两次 commit 之间 <commit_a>...<commit_b>

审核两个 commit 之间的差异

不支持的审核范围

以下范围不支持，需要提醒用户提供更准确的范围：

• 多个 commit：如 最近的5次提交 、最近10次commit 、所有提交

• 指定范围的多次提交：如 HEAD~5..HEAD (除非用户明确表示可以接受)

• 整个仓库历史：如 整个分支 、所有变更

• 大量的连续 commits

范围验证流程

当用户给出审核范围时：

• 识别审核模式：是本地 Git 还是 Gerrit Change ID

• 验证范围有效性：

• 本地 Git：检查是否为 commit hash、HEAD 、--staged 、--unstaged 等

• Gerrit：检查是否为有效的 Change ID 格式

• 检查范围大小：

• 如果检测到多个 commit（如 HEAD~10 ），提醒用户建议审核单个 commit 或差异范围

• 如果范围过大，提示用户缩小范围

• 执行审核：验证通过后开始审核流程

范围不合理的提示模板：

检测到您要求审核范围较大：{用户输入的范围}

建议使用以下更精确的范围：

• HEAD # 审核最新一次 commit
• HEAD~1 # 审核上一次 commit
• --staged # 审核暂存的修改
• --unstaged # 审核未暂存的修改
• abc1234 # 审核指定 commit hash

请选择一个合适的范围，或者明确输入具体的 commit hash。

完整工作流程

阶段 1: 模式识别与获取变更

识别审核模式：

• 如果输入是有效的 Git commit hash 或 HEAD 、~ 相关表达式 → 本地 Git 模式

• 如果输入包含 --staged 、--unstaged 、--cached 、--working → 本地 Git 模式

• 如果输入是 Gerrit Change ID 格式 → Gerrit 模式

• 如果范围不合理，提示用户提供更精确的范围

获取变更信息：

• 本地 Git 模式：使用 git 命令获取

• git show --stat <ref>

• 获取 commit 信息和变更文件列表

• git show <ref> -- <file> 或 git diff <ref~1> <ref> -- <file>

• 获取文件差异

• git diff --cached

• 暂存区差异

• git diff

• 工作区差异

• Gerrit 模式：使用 Gerrit MCP 工具获取

• get_change_details

• 获取变更详情

• list_change_files

• 获取修改的文件列表

• get_commit_message

• 获取提交信息

阶段 2: 代码获取与解析（含自我审阅触发判断）

重要说明：本地 Git 模式会在阶段 4.5 执行自我审阅，通过读取源文件上下文验证发现的问题是否准确。

对每个修改的文件：

• 获取文件的差异内容（diff）

• 识别文件类型（.go、.cpp、.hpp、.yml、.yaml 等）

• 应用排除规则（vendor、generated 等目录）

• 将文件分发给对应语言的分析器

阶段 3: 语言专项检查

Golang 分析器

检查规则详见 references/golang-checks.md。

排除规则：

• vendor/ 目录及其所有文件不进行审核

• 不提示关于 vendor 目录存储方式的改进建议

按严重程度分类：

• 🔴 Must Fix (-2): 错误处理缺失、SQL 注入、竞态条件、资源泄漏、空指针解引用

• 🟡 Should Fix (-2): 命名规范、函数过长、魔法数字、缺少注释、过度嵌套

• 🔵 Nice to Have (-1): 可用 stdlib、未使用变量/导入、可简化拼接

Qt/C++ 分析器

检查规则详见 references/cpp-checks.md

排除规则：

• vendor/ 、third_party/ 、3rdparty/ 目录

• 自动生成的文件（moc_.cpp 、ui_.h 、qrc_*.cpp ）

Ansible 分析器

检查规则详见 references/ansible-checks.md

排除规则：

• galaxy_roles/ 、collections/ 、vendor/ 第三方目录

• 主机清单文件（inventory/ 、hosts ）的敏感内容

阶段 4: 问题聚合与分级

• 将各语言检查结果汇总

• 按严重程度分类（Must Fix / Should Fix / Nice to Have）

• 去重和优先级排序

• 计算 Review 评分：

• 有 Must Fix 或 Should Fix → -2

• 仅有 Nice to Have → -1

• 无问题 → +1

阶段 4.5: 自我审阅（仅本地 Git 模式）

目的：减少误判，确保审核发现的每个问题都是真实存在且准确的。

触发条件：仅在本地 Git 模式下执行。

执行步骤：

检查是否处于项目源码目录：

• 判断当前目录是否包含项目结构（如 go.mod 、CMakeLists.txt 、main.yml 等）

• 如果不是项目目录，跳过自我审阅阶段

对每个发现的问题进行上下文验证：

• 使用 Read 工具读取问题所在文件的完整代码

• 根据问题报告的文件路径和行号，定位到具体代码位置

• 结合 git diff 的变更上下文，重新分析问题是否确实存在

审阅重点：

问题类型 审阅策略

Must Fix 严格验证 - 必须确认问题真实存在，否则移除或降级

Should Fix 适度验证 - 结合完整代码确认问题合理性

Nice to Have 轻量验证 - 确认建议确实可改进

审阅操作：

• 确认问题真实：保留原问题，标记"✓ 已验证"

• 问题不存在：从问题列表中移除，记录"✗ 误判 - 原因"

• 需要降级：调整问题等级（如 Must Fix → Should Fix），添加说明

• 需要调整描述：优化问题描述，使其更准确

更新统计：

• 根据审阅后的最终问题列表重新计算各等级数量

• 相应调整最终的 Review 推荐分数

自我审阅模板记录：

[自我审阅]

• 审阅文件数：N 个
• 原发现问题数：M 个
• 移除误判：A 个
• 降级调整：B 个
• 最终确认：M-A 个

重要原则：

• 只在能读取到项目源码时执行自我审阅

• 审阅是为了减少误判，不是为了减少问题

• 对于不确定的问题，倾向于保留而不是移除

• 自我审阅的结果应当体现专业性，提高审核可信度

阶段 5: 生成输出

生成 Markdown 审核报告，格式见下方"输出格式"章节。

注：最终报告中的问题数量和评分应为阶段 4.5 自我审阅后的结果。

阶段 6: 条件性发布评审（仅 Gerrit 模式）

检测用户意图：检查用户提示词是否包含以下关键词之一：

• "发布评论"

• "提交评审"

• "post review"

• "发布到 Gerrit"

• "submit review"

定位策略：确定评论发布位置

• 优先定位：第一个 Must Fix 问题的文件路径和行号

• 备选方案：如果无 Must Fix，使用第一个 Should Fix 问题

• 兜底方案：如果无问题（Score +1），使用第一个修改文件的第一行

如明确要求，使用 Gerrit MCP 工具发布：

使用 post_review_comment 工具在选定的位置发布评审，file_path 和 line_number 用于确定评论在 Gerrit 界面中的显示位置：

参数 值 说明

change_id

Change ID Gerrit Change 的标识符

file_path

定位的文件路径 问题所在文件

line_number

定位的行号 问题所在行号

message

评论内容 完整的评论文本，格式见下方

labels.Code-Review

-2 / -1 / +1

根据审核结果计算的评分

unresolved

true

保持为未解决状态

重要提醒：

• 发布一次评论，使用选定的文件和行号作为定位点

• Review Summary 和逐条问题说明都包含在同一条 message 中

• file_path 和 line_number 用于确定评论显示位置，不要求逐一条目独立评论

• 每次调用 post_review_comment 时，必须设置 labels.Code-Review

• 分数根据汇总 Summary 计算

• Verified 字段不设置，由 Gerrit 默认处理

输出格式

审核输出说明

审核工作完成后生成两种输出：

• Markdown 审核报告（始终生成）：在本地终端完整展示，适用于本地代码审核

• Gerrit Review 评论（可选，仅在 Gerrit 模式且用户明确要求时发布）：发布到 Gerrit Change

Markdown 审核报告（本地输出）

适用于本地 Git 模式或 Gerrit 模式，作为完整的技术审核报告。

Code Review Report

Metadata

• Review Type: Local Git / Gerrit
• Commit/Change: xxx
• Author: xxx
• Subject: xxx
• Files Changed: xx (xx insertions, xx deletions)

Summary

总问题数: N (Must Fix: A, Should Fix: B, Nice to Have: C)

推荐 Score: -2 / +1

[可选] 正面评价: • 添加了完整的测试用例 • 使用接口抽象依赖

📌 Must Fix (-2) - A items

[app/api/service/eia.go:239] 日志中使用未定义的变量

问题描述: departmentIDs 在内部作用域定义但最后被引用，会导致编译错误。

代码片段:

if len(departmentIDs) > 0 {
    // ... departmentIDs 在此作用域
}
// 最后的 log 引用了 departmentIDs - 错误!
log.Info("...", log.Any("departmentIDs", departmentIDs))

Suggestion: 修复日志语句，移除或使用正确的变量。

📌 Should Fix (-2) - B items

[pkg/middleware/auth.go:45] 命名不符合规范

问题描述: 函数名使用匈牙利命名法，不符合 Go 命名约定。

Suggestion: 改用驼峰命名，如 getAuthToken → GetAuthToken 。

📌 Nice to Have (-1) - C items

[main.go:120] 可使用标准库功能

问题描述: 自定义的字符串分割函数可被 strings.Split 替代。

Suggestion: 直接使用 strings.Split 。

✅ 无问题

代码质量优秀，以上仅列出改进建议。

Gerrit Review 评论格式（发布到 Gerrit）

仅在 Gerrit 模式下，当用户明确要求（如"发布评论"、"post review"等）时，将审核结果发布为 Change 级别评论。

设计原则：简明扼要，重点突出，便于在 Gerrit Web 界面快速阅读。

=== Code Review Summary ===

Found Issues: 🔴 Must Fix: 3 items 🟡 Should Fix: 1 items 🔵 Nice to Have: 2 items Recommended Score: -2 (需修复严重问题后合并)

Positive Points: • 添加了完整的测试用例覆盖新增功能 • 使用接口抽象依赖，便于测试和维护 • 密码修改流程有完整的降级机制 • 日志记录详尽，便于排查问题

Must Fix Issues

[app/api/service/eia.go:239] 日志中使用未定义变量 departmentIDs

Suggestion: 修复日志语句，移除或使用正确的变量。

[app/api/service/uim_client.go:57] 全局变量缺少并发安全保护

var globalEIAAuthChecker EIAAuthChecker = NewEIAAuthChecker()

Suggestion: 使用 sync.RWMutex 保护访问，或使用 atomic.Value 。

[app/web/handler/user.go:1227] 用户 ID 检查逻辑不正确 Suggestion: 修复 ID 验证逻辑，添加边界检查。

Should Fix Issues

• [pkg/middleware/auth.go:45] 函数命名不符合 Go 规范 Suggestion: 使用驼峰命名 getAuthToken → GetAuthToken 。

Nice to Have Issues

[main.go:120] 可使用标准库 strings.Split 替代自定义实现

[utils/string.go:78] 删除未使用的辅助函数

格式规范：

与 Markdown 报告的区别：

检查规则参考

• references/golang-checks.md - Golang 检查规则
• references/cpp-checks.md - Qt/C++ 检查规则
• references/ansible-checks.md - Ansible 检查规则

Golang 检查项索引

🔴 Must Fix (-2)

🟡 Should Fix (-2)

🔵 Nice to Have (-1)

Qt/C++ 检查项索引

🔴 Must Fix (-2)

🟡 Should Fix (-2)

🔵 Nice to Have (-1)

Ansible 检查项索引

🔴 Must Fix (-2)

🟡 Should Fix (-2)

🔵 Nice to Have (-1)

扩展指南

添加新的检查规则

在对应语言的 references 文件中添加检查项，格式：

### [检查ID] 检查名称

- **描述**: 检查项的详细描述
- **严重程度**: Must Fix / Should Fix / Nice to Have
- **检测方式**: 如何通过代码分析发现此问题
- **示例**:
  ```go
  // Bad
  // ...
  // Good
  // ...

- 建议修改: 具体的修改建议

### 添加新语言支持

1. 创建 `references/<lang>-checks.md` 文件
2. 按三级分类组织检查项
3. 更新本文档"阶段 3: 语言专项检查"部分
4. 在"检查规则参考"章节添加该语言的检查项索引