gitlink-cli/skills/gitlink-code-review/README.md

# gitlink-code-review - 智能代码审查 Skill

[![GitLink](https://img.shields.io/badge/GitLink-gitlink--cli-green)](https://www.gitlink.org.cn/zzx-coder/gitlink-cli)
[![Skill Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](SKILL.md)
[![AI Agent Ready](https://img.shields.io/badge/AI_Access-Ready-success.svg)](SKILL.md)

欢迎使用 **gitlink-code-review** Skill！这是一个 AI 驱动的自动化代码审查工具，帮助开发者和 Reviewers 快速分析 GitLink PR 的代码质量。

## 🎯 功能特性

### 核心功能

- ✅ **自动代码分析**：获取 PR 的文件列表和 diff 内容
- ✅ **多维度审查**：代码质量、安全性、性能、可维护性
- ✅ **结构化报告**：生成 JSON/Markdown 格式的审查报告
- ✅ **智能建议**：提供具体的代码修改建议
- ✅ **自动评论**：将审查意见自动添加为 PR 评论
- ✅ **AI 驱动**：基于 Claude 的代码理解能力

### 审查维度

| 维度 | 检查项 | 说明 |
|------|--------|------|
| **代码质量** | 复杂度、命名规范、注释完整性 | 确保代码清晰易读 |
| **安全性** | SQL 注入、XSS、敏感信息泄露 | 发现安全漏洞 |
| **性能** | 资源泄漏、循环效率、数据库查询 | 优化性能问题 |
| **可维护性** | 代码重复、职责单一、测试覆盖 | 提高代码可维护性 |

## 🚀 快速开始

### 前置条件

1. **安装 gitlink-cli**
   ```bash
   npm install -g @gitlink-ai/cli
   ```

2. **配置认证**
   ```bash
   gitlink-cli auth login
   ```

3. **验证安装**
   ```bash
   gitlink-cli pr +list
   ```

### 基础使用

#### 1. 获取 PR 信息

```bash
# 查看 PR 详情
gitlink-cli pr +view --id 123 --format json

# 获取变更文件列表
gitlink-cli pr +files --id 123 --format json

# 获取 diff 内容
gitlink-cli pr +diff --id 123 --format json
```

#### 2. 进行代码审查

**AI Agent 方式**（推荐）：

```
用户: "帮我审查 PR #123，检查代码质量、安全性和性能问题"

AI Agent 将：
1. 获取 PR 的代码变更
2. 分析代码质量和潜在问题
3. 生成结构化的审查报告
4. （可选）自动添加审查评论
```

**手动方式**：

```bash
# 获取 diff 并分析
gitlink-cli pr +diff --id 123 --format json > pr_diff.json

# 使用 AI 工具分析 pr_diff.json
# 生成审查报告

# （可选）添加评论到 PR
gitlink-cli api POST /:owner/:repo/pulls/123/reviews --body '{
  "body": "审查报告内容...",
  "event": "COMMENT"
}'
```

### 完整工作流示例

详见 [`examples/comprehensive-review-workflow.md`](examples/comprehensive-review-workflow.md)

## 📊 审查报告示例

### 简化版报告

```markdown
# 代码审查报告

## 总体评分: 85/100 ⭐⭐⭐⭐

## 🔴 高优先级问题（2）

1. **敏感信息泄露** - `src/auth/login.go:45`
   - 硬编码的密钥不应出现在代码中
   - 建议：使用环境变量存储密钥

2. **资源泄漏** - `src/auth/login.go:78`
   - 数据库连接未关闭
   - 建议：使用 defer 确保连接关闭

## ⭐ 优秀实践（1）

1. **优秀的错误处理** - `src/auth/user.go:120`
```

### 完整版报告

完整版报告包含：
- PR 基本信息
- 各维度详细评分
- 按优先级排序的问题列表
- 具体的代码位置和修改建议
- 优秀实践和改进建议
- 逐文件的详细分析

## 🎯 使用场景

### 场景 1：开发者自审

开发者在提交 PR 前进行自审：
```bash
# 获取 PR diff
gitlink-cli pr +diff --id 123 --format json

# AI 分析并生成报告
# 修复发现的问题
```

### 场景 2：Reviewers 辅助审查

Reviewers 使用 AI 辅助审查：
```bash
# 快速获取审查报告
gitlink-cli pr +view --id 123 --format json
gitlink-cli pr +diff --id 123 --format json

# AI 生成报告，Reviewers 参考
# 专注于业务逻辑和架构设计
```

### 场景 3：CI/CD 集成

在 CI/CD 流程中自动审查：
```yaml
# .gitlab-ci.yml
code_review:
  script:
    - gitlink-cli pr +diff --id $MR_ID --format json
    - ai-code-review --input pr_diff.json --output report.json
    - check-score --min 70 report.json
```

### 场景 4：新贡献者指导

为新贡献者的 PR 提供详细指导：
```bash
# 全面审查新贡献者的 PR
# 提供详细的代码指导
# 帮助改进代码质量
```

## 📚 文档导航

- **[SKILL.md](SKILL.md)** - 技能总览和完整功能说明
- **[REFERENCE.md](REFERENCE.md)** - API 详细参考
- **[references/](references/)** - 详细操作指南
- **[examples/](examples/)** - 工作流示例

### 快速查找

- **我想了解基本用法**: [SKILL.md](SKILL.md#使用方式)
- **我想看审查维度**: [SKILL.md](SKILL.md#审查维度)
- **我想看工作流示例**: [examples/comprehensive-review-workflow.md](examples/comprehensive-review-workflow.md)
- **我想了解 API 细节**: [REFERENCE.md](REFERENCE.md)

## 🤖 AI Agent 使用

Claude Code 和其他 AI Agent 可以直接使用此 Skill：

```
用户请求: "审查 PR #123"
    ↓
AI 读取 gitlink-code-review/SKILL.md
    ↓
AI 执行: 
  1. gitlink-cli pr +view --id 123 --format json
  2. gitlink-cli pr +files --id 123 --format json
  3. gitlink-cli pr +diff --id 123 --format json
    ↓
AI 分析代码变更
    ↓
AI 生成结构化审查报告
    ↓
AI （可选）添加评论到 PR
    ↓
完成！
```

### 典型 AI 对话

**用户**: "帮我审查一下 PR #123，重点关注安全性问题"

**AI Agent**:
```
我来帮您审查 PR #123，重点关注安全性问题。

[获取 PR 信息...]
[分析代码变更...]

发现以下安全问题：

🔴 高优先级（1）:
1. SQL 注入风险 - src/auth/login.go:45
   - 直接拼接用户输入到 SQL 语句
   - 建议：使用参数化查询

⚠️ 中优先级（1）:
1. 缺少输入验证 - src/auth/login.go:30
   - 未验证用户名长度和格式
   - 建议：添加输入验证中间件

总体评分：70/100
安全性评分：60/100 ⚠️

需要我详细说明修复方法吗？
```

## 🎓 最佳实践

### 审查时机

1. **PR 创建后**：立即进行初步审查
2. **PR 更新后**：审查新增的代码变更
3. **合并前**：最终审查确认代码质量

### 审查重点

根据 PR 类型调整审查重点：
- **功能 PR**：代码质量 + 可维护性
- **Bug 修复**：修复完整性 + 测试覆盖
- **重构 PR**：性能改进 + 代码简化
- **文档 PR**：文档完整性 + 准确性

### 评论规范

- ✅ **建设性**：提供具体的修改建议
- ✅ **礼貌友好**：使用积极的语言
- ✅ **解释原因**：说明为什么需要修改
- ✅ **认可优点**：指出优秀实践

### 自动化审查

配置 CI/CD 自动审查：
```yaml
# 合并门禁示例
if (review_score < 70) {
  block_merge("代码审查评分低于 70 分")
}
if (high_priority_issues > 0) {
  block_merge("存在高优先级问题")
}
```

## 📊 质量标准

### 审查评分体系

| 分数范围 | 等级 | 说明 |
|---------|------|------|
| 90-100 | ⭐⭐⭐⭐⭐ 优秀 | 代码质量高，可以直接合并 |
| 75-89 | ⭐⭐⭐⭐ 良好 | 代码质量良好，小幅改进后可合并 |
| 60-74 | ⭐⭐⭐ 一般 | 存在一些问题，建议改进后合并 |
| < 60 | ⭐⭐ 较差 | 存在严重问题，必须修复 |

### 问题优先级

| 优先级 | 图标 | 说明 | 是否阻止合并 |
|--------|------|------|--------------|
| HIGH | 🔴 | 安全漏洞、严重性能问题 | 是 |
| MEDIUM | ⚠️ | 代码质量问题、潜在风险 | 建议 |
| LOW | ℹ️ | 代码风格、轻微改进 | 否 |

## ❓ 常见问题

### Q: 如何提高审查准确性？

**A**:
1. 提供完整的 diff 内容
2. 根据项目类型调整审查规则
3. 结合项目上下文分析
4. 定期更新审查规则

### Q: 如何处理误报？

**A**:
1. AI 审查可能产生误报，需要人工验证
2. 可以配置白名单忽略特定规则
3. 提供反馈改进审查规则

### Q: 审查报告可以作为合并条件吗？

**A**:
1. 可以将审查评分设置为合并门禁
2. 建议设置最低评分（如 70 分）
3. 高优先级问题必须修复后才能合并

### Q: 如何集成到 CI/CD？

**A**:
参考 [`examples/ci-integration.md`](examples/ci-integration.md) 中的配置示例

## 🔗 相关资源

- [gitlink-cli 主项目](https://www.gitlink.org.cn/zzx-coder/gitlink-cli)
- [gitlink-pr Skill](../gitlink-pr/SKILL.md) - PR 操作指南
- [gitlink-workflow Skill](../gitlink-workflow/SKILL.md) - AI 工作流
- [代码审查最佳实践](https://google.github.io/eng-practices/review/)

## 📈 更新日志

### v1.0.0 (2026-06-12)

- ✅ 初始版本发布
- ✅ 支持代码质量、安全性、性能、可维护性审查
- ✅ 生成结构化审查报告
- ✅ AI Agent 集成
- ✅ 完整文档和示例

## 🤝 贡献

欢迎贡献！如果你有改进建议或发现问题，请：

1. 创建 Issue 描述问题或建议
2. 提交 Pull Request 改进 Skill
3. 分享你的使用经验

## 📞 获取帮助

- **查看文档**: [SKILL.md](SKILL.md)
- **查看示例**: [examples/](examples/)
- **提交问题**: [GitLink Issues](https://www.gitlink.org.cn/zzx-coder/gitlink-cli/issues)

---

**祝你审查愉快！🚀**

如有问题，请查看 [SKILL.md](SKILL.md) 或 [examples/](examples/) 中的详细示例。