# Workflow: PR Review（代码审查辅助）

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **AI Agent 工作流**：此工作流专为 AI Agent 设计，用于辅助代码审查。

AI Agent 获取 PR 变更内容，分析代码质量，自动添加 Review 评论，提高代码审查效率。

## 工作流概述

PR Review 工作流通过分析 Pull Request 的代码变更，自动识别潜在问题、提出改进建议，并生成结构化的审查意见。

## 适用场景

- **代码审查**：自动化 PR 初步审查
- **质量检查**：检查代码质量和规范合规性
- **安全审查**：识别潜在的安全问题
- **性能分析**：评估性能相关代码变更
- **文档检查**：验证代码注释和文档完整性

## 工作流步骤

### 步骤 1：获取 PR 详情

```bash
# 获取 PR 基本信息
gitlink-cli pr +view --id 42 --format json

# 提取关键信息
PR_INFO=$(gitlink-cli pr +view --id 42 --format json | jq '.data')
PR_TITLE=$(echo "$PR_INFO" | jq -r '.title')
PR_AUTHOR=$(echo "$PR_INFO" | jq -r '.author.login')
SOURCE_BRANCH=$(echo "$PR_INFO" | jq -r '.head_ref')
TARGET_BRANCH=$(echo "$PR_INFO" | jq -r '.base_ref')
```

### 步骤 2：获取变更文件列表

```bash
# 获取 PR 变更的文件列表
gitlink-cli pr +files --id 42 --format json

# 分析文件变更
FILES_CHANGED=$(gitlink-cli pr +files --id 42 --format json | \
  jq '.data.files[] |
      {filename: .filename,
       status: .status,
       additions: .additions,
       deletions: .deletions}')
```

### 步骤 3：获取代码差异

```bash
# 获取 PR 的完整代码差异
gitlink-cli pr +diff --id 42 --format json

# 提取特定文件的差异
gitlink-cli pr +diff --id 42 --format json | \
  jq '.data.diff | split("diff --git")'
```

### 步骤 4：代码质量分析

分析代码变更的多个维度：

**安全性分析**：
```bash
# 检查敏感信息泄露
if echo "$DIFF" | grep -iE "password|secret|api_key|token"; then
    SECURITY_ISSUES+=("可能包含敏感信息")
fi

# 检查 SQL 注入风险
if echo "$DIFF" | grep -iE "SELECT.*FROM.*WHERE.*\$"; then
    SECURITY_ISSUES+=("可能的 SQL 注入风险")
fi
```

**代码规范检查**：
```bash
# 检查代码风格
if echo "$DIFF" | grep -P "\t"; then
    STYLE_ISSUES+=("包含 Tab 字符，建议使用空格")
fi

# 检查长行
if echo "$DIFF" | grep ".\{120,\}"; then
    STYLE_ISSUES+=("包含超过 120 字符的长行")
fi
```

**性能分析**：
```bash
# 检查可能的性能问题
if echo "$DIFF" | grep -iE "N\+1|SELECT.*\*|foreach.*query"; then
    PERF_ISSUES+=("可能的 N+1 查询问题")
fi
```

### 步骤 5：生成 Review 评论

```bash
# 生成结构化的 Review 评论
REVIEW_BODY="# 🔍 代码审查结果

## ✅ 优点
- 代码结构清晰
- 逻辑正确
- 遵循项目规范

## ⚠️ 需要改进
${STYLE_ISSUES[@]+($(printf -- "- %s\n" "${STYLE_ISSUES[@]}"))}

## 🔒 安全问题
${SECURITY_ISSUES[@]+($(printf -- "- %s\n" "${SECURITY_ISSUES[@]}"))}

## 🚀 性能建议
${PERF_ISSUES[@]+($(printf -- "- %s\n" "${PERF_ISSUES[@]}"))}

## 📝 总体评价
代码整体质量良好，建议修改上述问题后合并。"

# 添加 Review 评论
gitlink-cli api POST /:owner/:repo/pulls/42/reviews --body \
  "{\"body\":\"$REVIEW_BODY\",\"event\":\"COMMENT\"}"
```

## 完整工作流示例

```bash
#!/bin/bash

# PR Review 自动化脚本

PR_ID=$1
OWNER="myuser"
REPO="myproject"

echo "开始审查 PR #$PR_ID..."

# 1. 获取 PR 详情
PR_INFO=$(gitlink-cli pr +view --owner $OWNER --repo $REPO --id $PR_ID --format json)
PR_TITLE=$(echo "$PR_INFO" | jq -r '.data.title')
PR_AUTHOR=$(echo "$PR_INFO" | jq -r '.data.author.login')
ADDITIONS=$(echo "$PR_INFO" | jq -r '.data.additions')
DELETIONS=$(echo "$PR_INFO" | jq -r '.data.deletions')

echo "PR 标题: $PR_TITLE"
echo "PR 作者: $PR_AUTHOR"
echo "代码变更: +$ADDITIONS -$DELETIONS"

# 2. 获取变更文件
FILES=$(gitlink-cli pr +files --owner $OWNER --repo $REPO --id $PR_ID --format json)

# 3. 获取代码差异
DIFF=$(gitlink-cli pr +diff --owner $OWNER --repo $REPO --id $PR_ID --format json | \
  jq -r '.data.diff')

# 4. 分析代码
ISSUES=()
SUGGESTIONS=()

# 安全性检查
if echo "$DIFF" | grep -iE "password|secret|api_key|token.*="; then
    ISSUES+=("🔒 安全：可能包含硬编码的敏感信息")
fi

# 代码规范检查
if echo "$DIFF" | grep -P "\t"; then
    SUGGESTIONS+=("📝 规范：建议使用空格代替 Tab")
fi

# 性能检查
if echo "$DIFF" | grep -iE "SELECT.*\*.*FROM"; then
    SUGGESTIONS+=("🚀 性能：建议明确指定字段而不是使用 *")
fi

# 5. 生成 Review 评论
if [ ${#ISSUES[@]} -eq 0 ] && [ ${#SUGGESTIONS[@]} -eq 0 ]; then
    REVIEW_BODY="# ✅ 审查通过

代码质量良好，没有发现明显问题。可以合并。"
    EVENT="APPROVE"
else
    REVIEW_BODY="# 🔍 代码审查结果

## PR 信息
- **标题**: $PR_TITLE
- **作者**: $PR_AUTHOR  
- **变更**: +$ADDITIONS -$DELETIONS 行

## ❌ 需要修复
$(printf -- "- %s\n" "${ISSUES[@]}")

## 💡 改进建议
$(printf -- "- %s\n" "${SUGGESTIONS[@]}")

## 📋 后续步骤
1. 修复上述问题
2. 确保所有测试通过
3. 更新相关文档"
    EVENT="REQUEST_CHANGES"
fi

# 6. 提交 Review
echo "提交 Review 评论..."
gitlink-cli api POST "/$OWNER/$REPO/pulls/$PR_ID/reviews" --body \
  "{\"body\":\"$REVIEW_BODY\",\"event\":\"$EVENT\"}"

echo "审查完成！"
```

## AI Agent 集成示例

Claude Code 等 AI Agent 可以深度集成此工作流：

```python
# AI Agent 执行 PR Review
def pr_review(owner, repo, pr_id):
    """AI Agent 自动代码审查"""
    
    # 1. 获取 PR 信息
    pr_info = get_pr_details(owner, repo, pr_id)
    files_changed = get_pr_files(owner, repo, pr_id)
    diff_content = get_pr_diff(owner, repo, pr_id)
    
    # 2. AI 分析代码
    review_results = {
        'security': analyze_security(diff_content),
        'performance': analyze_performance(diff_content),
        'style': analyze_code_style(diff_content),
        'documentation': analyze_documentation(files_changed),
        'testing': analyze_test_coverage(files_changed)
    }
    
    # 3. 生成审查意见
    review_comment = generate_review_comment(pr_info, review_results)
    
    # 4. 提交 Review
    submit_review(owner, repo, pr_id, review_comment, review_results)
    
def analyze_security(diff_content):
    """AI 安全性分析"""
    issues = []
    
    # 检查常见安全问题
    security_patterns = {
        'hardcoded_secrets': r'password\s*=\s*["\'].*["\']',
        'sql_injection': r'SELECT.*FROM.*WHERE.*\${',
        'xss_risk': r'innerHTML\s*=',
        'command_injection': r'system\(|exec\(.*\$'
    }
    
    for issue_name, pattern in security_patterns.items():
        if re.search(pattern, diff_content, re.IGNORECASE):
            issues.append({
                'type': 'security',
                'severity': 'high',
                'issue': issue_name,
                'description': f'检测到 {issue_name} 风险'
            })
    
    return issues

def generate_review_comment(pr_info, review_results):
    """AI 生成结构化审查意见"""
    comment = f"""# 🔍 AI 代码审查报告

## PR 概览
- **标题**: {pr_info['title']}
- **作者**: {pr_info['author']}
- **变更**: +{pr_info['additions']} -{pr_info['deletions']} 行
- **文件数**: {len(pr_info['files'])}

## 🔒 安全审查
"""
    
    if review_results['security']:
        for issue in review_results['security']:
            comment += f"- ❌ **{issue['issue']}**: {issue['description']}\n"
    else:
        comment += "✅ 未发现安全问题\n"
    
    comment += "\n## 🚀 性能审查\n"
    # 类似地添加其他审查结果...
    
    return comment
```

## 审查维度

### 1. 安全性审查
- **敏感信息泄露**：检查硬编码的密码、API 密钥
- **注入攻击**：SQL 注入、命令注入、XSS 风险
- **权限控制**：检查权限验证逻辑
- **数据验证**：输入验证和输出编码

### 2. 性能审查
- **数据库查询**：N+1 查询、缺少索引
- **内存使用**：内存泄漏、大对象处理
- **算法复杂度**：时间复杂度和空间复杂度
- **缓存策略**：缓存命中率和使用合理性

### 3. 代码质量审查
- **代码规范**：命名规范、格式风格
- **代码结构**：模块化、可读性、可维护性
- **错误处理**：异常处理完整性
- **注释文档**：代码注释和文档质量

### 4. 测试审查
- **测试覆盖**：单元测试和集成测试
- **测试质量**：测试用例的有效性
- **边界条件**：边界值和异常情况测试

### 5. 文档审查
- **API 文档**：接口文档完整性
- **用户文档**：用户指南更新
- **变更日志**：CHANGELOG 更新

## 审查决策

基于分析结果做出审查决策：

**APPROVE（通过）**：
- 无严重问题
- 建议性问题可接受
- 测试覆盖充分

**REQUEST_CHANGES（请求修改）**：
- 存在严重安全问题
- 重要功能缺失
- 测试覆盖不足

**COMMENT（评论）**：
- 一般性建议
- 文档改进
- 代码优化建议

## 自动化规则

常见问题的自动检测规则：

```python
AUTO_REVIEW_RULES = {
    'security': {
        'hardcoded_password': {
            'pattern': r'password\s*=\s*["\'][^"\']{8,}["\']',
            'severity': 'high',
            'message': '检测到硬编码密码，请使用环境变量或配置文件'
        },
        'sql_injection': {
            'pattern': r'SELECT.*FROM.*WHERE.*\$[a-z_]+',
            'severity': 'high', 
            'message': '可能的 SQL 注入风险，请使用参数化查询'
        }
    },
    'performance': {
        'n_plus_one': {
            'pattern': r'for\s+\$.*\{\s*.*SELECT',
            'severity': 'medium',
            'message': '可能的 N+1 查询问题，考虑使用预加载'
        },
        'missing_index': {
            'pattern': r'WHERE.*LIKE.*%.*%',
            'severity': 'low',
            'message': '前缀模糊搜索可能无法使用索引'
        }
    }
}
```

## 最佳实践

1. **逐步审查**：先检查严重问题，再检查一般问题
2. **建设性反馈**：提供具体的改进建议
3. **平衡严格**：平衡代码质量和开发效率
4. **学习改进**：从审查中学习，提高代码质量
5. **团队协作**：与开发者沟通，达成共识

## 质量保证

确保审查质量：

1. **双重检查**：重要 PR 进行二次审查
2. **审查标准**：建立统一的审查标准
3. **审查培训**：培训审查人员
4. **反馈收集**：收集对审查质量的反馈
5. **持续改进**：优化审查流程和规则

## References

- [workflow-issue-triage](workflow-issue-triage.md) — Issue 分类工作流
- [workflow-release-notes](workflow-release-notes.md) — Release Notes 生成
- [gitlink-workflow](../SKILL.md) — 工作流总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [pr +view](../../gitlink-pr/references/gitlink-pr-view.md) — 查看 PR
- [pr +files](../../gitlink-pr/references/gitlink-pr-files.md) — 查看 PR 文件变更
