forked from Gitlink/gitlink-cli
285 lines
8.0 KiB
Markdown
285 lines
8.0 KiB
Markdown
---
|
||
name: gitlink-code-review
|
||
version: 1.0.0
|
||
description: "智能代码审查：自动分析 PR 代码变更，进行多维度代码质量检查，生成结构化审查报告并自动添加评论。当用户需要对 GitLink PR 进行代码审查时触发。"
|
||
metadata:
|
||
requires:
|
||
bins: ["gitlink-cli"]
|
||
cliHelp: "gitlink-cli pr --help"
|
||
---
|
||
|
||
# gitlink-code-review（智能代码审查）
|
||
|
||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 和 [`../gitlink-pr/SKILL.md`](../gitlink-pr/SKILL.md)
|
||
|
||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||
|
||
本技能提供 AI 驱动的自动化代码审查功能，帮助开发者和 Reviewers 快速分析 PR 代码质量。
|
||
|
||
## 🎯 核心功能
|
||
|
||
| 功能 | 说明 | 需要认证 |
|
||
|------|------|----------|
|
||
| `代码变更分析` | 获取 PR 的文件列表和 diff 内容 | 否（公开项目） |
|
||
| `代码质量检查` | 检查代码复杂度、命名规范、注释完整性 | 否 |
|
||
| `安全性检查` | 检查 SQL 注入、XSS、敏感信息泄露等 | 否 |
|
||
| `性能检查` | 识别性能反模式和资源泄漏 | 否 |
|
||
| `可维护性检查` | 检查代码重复和职责单一原则 | 否 |
|
||
| `审查报告生成` | 生成结构化的审查报告（JSON/Markdown） | 否 |
|
||
| `自动评论` | 将审查意见自动添加为 PR 评论 | 是 |
|
||
|
||
## 📊 审查维度
|
||
|
||
### 1. 代码质量（Code Quality）
|
||
|
||
检查项：
|
||
- **代码复杂度**：圈复杂度、嵌套层级、函数长度
|
||
- **命名规范**：变量/函数/类的命名是否清晰
|
||
- **注释完整性**：复杂逻辑是否有注释说明
|
||
- **代码格式**：缩进、空行、代码组织
|
||
|
||
### 2. 安全性（Security）
|
||
|
||
检查项：
|
||
- **SQL 注入**：字符串拼接 SQL 语句
|
||
- **XSS 漏洞**：未转义的用户输入输出
|
||
- **敏感信息**：硬编码的密码/密钥/Token
|
||
- **认证问题**：权限检查、会话管理
|
||
- **输入验证**：用户输入是否充分验证
|
||
|
||
### 3. 性能（Performance）
|
||
|
||
检查项：
|
||
- **循环效率**：嵌套循环、大循环中的重复计算
|
||
- **资源泄漏**：未关闭的连接/文件/流
|
||
- **数据库查询**：N+1 查询、缺少索引
|
||
- **内存使用**：大对象复制、内存泄漏
|
||
|
||
### 4. 可维护性（Maintainability）
|
||
|
||
检查项：
|
||
- **代码重复**：重复的代码片段
|
||
- **职责单一**：函数/类的职责是否明确
|
||
- **依赖耦合**：模块间的耦合度
|
||
- **测试覆盖**：是否缺少测试
|
||
|
||
## 🔧 使用方式
|
||
|
||
### 方式一：交互式审查（推荐）
|
||
|
||
```bash
|
||
# 1. 获取 PR 详情
|
||
gitlink-cli pr +view --id <pr_id> --format json
|
||
|
||
# 2. 获取变更文件列表
|
||
gitlink-cli pr +files --id <pr_id> --format json
|
||
|
||
# 3. 获取 diff 内容
|
||
gitlink-cli pr +diff --id <pr_id> --format json
|
||
|
||
# 4. AI 分析代码并生成审查报告（手动或自动）
|
||
# 5. （可选）添加审查评论
|
||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"审查意见...","event":"COMMENT"}'
|
||
```
|
||
|
||
### 方式二：完整审查工作流
|
||
|
||
详见 [`examples/comprehensive-review-workflow.md`](examples/comprehensive-review-workflow.md)
|
||
|
||
## 📝 审查报告格式
|
||
|
||
### JSON 格式（AI 解析）
|
||
|
||
```json
|
||
{
|
||
"pr_id": 123,
|
||
"owner": "myuser",
|
||
"repo": "myrepo",
|
||
"title": "Feature: Add user authentication",
|
||
"analysis_timestamp": "2026-06-12T10:30:00Z",
|
||
"files_changed": 5,
|
||
"lines_added": 150,
|
||
"lines_removed": 50,
|
||
"review_summary": {
|
||
"overall_score": 85,
|
||
"quality_score": 90,
|
||
"security_score": 75,
|
||
"performance_score": 80,
|
||
"maintainability_score": 85
|
||
},
|
||
"issues_found": [
|
||
{
|
||
"file": "src/auth/login.go",
|
||
"line": 45,
|
||
"severity": "HIGH",
|
||
"category": "security",
|
||
"rule": "敏感信息泄露",
|
||
"description": "硬编码的密钥不应出现在代码中",
|
||
"suggestion": "使用环境变量或配置文件存储密钥"
|
||
},
|
||
{
|
||
"file": "src/auth/login.go",
|
||
"line": 78,
|
||
"severity": "MEDIUM",
|
||
"category": "performance",
|
||
"rule": "资源泄漏",
|
||
"description": "数据库连接未关闭",
|
||
"suggestion": "使用 defer 确保连接关闭"
|
||
}
|
||
],
|
||
"positive_notes": [
|
||
{
|
||
"file": "src/auth/user.go",
|
||
"line": "120,
|
||
"description": "优秀的错误处理"
|
||
}
|
||
],
|
||
"recommendations": [
|
||
"建议添加单元测试覆盖登录逻辑",
|
||
"建议使用参数化查询防止 SQL 注入"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Markdown 格式（人类阅读）
|
||
|
||
```markdown
|
||
# 代码审查报告
|
||
|
||
## PR 信息
|
||
- **PR ID**: 123
|
||
- **标题**: Feature: Add user authentication
|
||
- **作者**: @developer
|
||
- **变更文件**: 5 个文件
|
||
- **代码行**: +150 / -50
|
||
|
||
## 总体评分: 85/100 ⭐⭐⭐⭐
|
||
|
||
- 代码质量: 90/100
|
||
- 安全性: 75/100 ⚠️
|
||
- 性能: 80/100
|
||
- 可维护性: 85/100
|
||
|
||
## 🔴 高优先级问题（2）
|
||
|
||
### 1. 敏感信息泄露
|
||
- **文件**: `src/auth/login.go:45`
|
||
- **类别**: security
|
||
- **问题**: 硬编码的密钥不应出现在代码中
|
||
- **建议**: 使用环境变量或配置文件存储密钥
|
||
|
||
### 2. 资源泄漏
|
||
- **文件**: `src/auth/login.go:78`
|
||
- **类别**: performance
|
||
- **问题**: 数据库连接未关闭
|
||
- **建议**: 使用 defer 确保连接关闭
|
||
|
||
## ⭐ 优秀实践（1）
|
||
|
||
### 1. 优秀的错误处理
|
||
- **文件**: `src/auth/user.go:120`
|
||
- **描述**: 完善的错误处理和日志记录
|
||
|
||
## 💡 改进建议
|
||
|
||
1. 建议添加单元测试覆盖登录逻辑
|
||
2. 建议使用参数化查询防止 SQL 注入
|
||
3. 建议添加输入验证中间件
|
||
|
||
## 📊 详细分析
|
||
|
||
[详细的逐文件分析...]
|
||
```
|
||
|
||
## 🤖 AI Agent 使用
|
||
|
||
AI Agent 可以通过以下步骤自动审查 PR：
|
||
|
||
1. **获取 PR 信息**
|
||
```bash
|
||
gitlink-cli pr +view --id <pr_id> --format json
|
||
```
|
||
|
||
2. **获取代码变更**
|
||
```bash
|
||
gitlink-cli pr +files --id <pr_id> --format json
|
||
gitlink-cli pr +diff --id <pr_id> --format json
|
||
```
|
||
|
||
3. **AI 分析代码**（Claude 分析 diff 内容）
|
||
|
||
4. **生成审查报告**（结构化 JSON/Markdown）
|
||
|
||
5. **（可选）添加评论**
|
||
```bash
|
||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
|
||
"body": "<审查报告内容>",
|
||
"event": "COMMENT"
|
||
}'
|
||
```
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 审查时机
|
||
|
||
- **PR 创建后**：立即进行初步审查，快速发现问题
|
||
- **PR 更新后**：审查新增的代码变更
|
||
- **合并前**：最终审查确认代码质量
|
||
|
||
### 审查重点
|
||
|
||
根据 PR 类型调整审查重点：
|
||
- **功能 PR**：关注代码质量和可维护性
|
||
- **Bug 修复 PR**：关注修复是否完整、测试是否充分
|
||
- **重构 PR**：关注性能改进和代码简化
|
||
- **文档 PR**：关注文档完整性和准确性
|
||
|
||
### 评论规范
|
||
|
||
- **建设性**：提供具体的修改建议，而非仅指出问题
|
||
- **礼貌友好**：使用积极的语言，避免负面批评
|
||
- **解释原因**：说明为什么需要修改，帮助开发者理解
|
||
- **认可优点**：及时指出代码中的优秀实践
|
||
|
||
### 自动化审查
|
||
|
||
可以配置 CI/CD 流程自动触发代码审查：
|
||
- PR 创建时自动审查
|
||
- 审查失败时阻止合并
|
||
- 审查通过后允许人工审查
|
||
|
||
## 📚 相关文档
|
||
|
||
- [PR 基础操作](../gitlink-pr/SKILL.md)
|
||
- [详细操作参考](references/)
|
||
- [工作流示例](examples/)
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 如何提高审查的准确性？
|
||
|
||
A:
|
||
1. 提供完整的 diff 内容，而非仅文件列表
|
||
2. 根据项目类型调整审查规则（如前端/后端/移动端）
|
||
3. 结合项目上下文进行分析（如代码规范文档）
|
||
|
||
### Q: 如何处理误报？
|
||
|
||
A:
|
||
1. AI 审查可能产生误报，需要人工验证
|
||
2. 可以配置白名单忽略特定规则
|
||
3. 提供反馈改进审查规则
|
||
|
||
### Q: 审查报告是否可以作为合并条件？
|
||
|
||
A:
|
||
1. 可以将审查评分设置为合并门禁
|
||
2. 建议设置最低评分要求（如 70 分以上）
|
||
3. 高优先级问题必须修复后才能合并
|
||
|
||
## 🔗 参考资源
|
||
|
||
- [gitlink-pr/SKILL.md](../gitlink-pr/SKILL.md) - PR 操作指南
|
||
- [gitlink-workflow/SKILL.md](../gitlink-workflow/SKILL.md) - AI 工作流
|
||
- [代码审查最佳实践](https://google.github.io/eng-practices/review/) - Google 代码审查指南
|