README.md

# AI 智能代码变更分析助手（ai-pr-analysis-companion）

## 📌 业务场景

团队开发者或技术负责人需要对 GitHub Pull Request 进行系统性评审，但人工 review 存在以下问题：
- PR 代码量大，人工精力有限，容易遗漏关键问题
- 改动涉及多模块，影响范围难以快速判断
- 新人不熟悉代码库，难以评估改动风险
- 评审没有统一标准，结果因人而异

## 😫 痛点分析

| 痛点 | 描述 |
|------|------|
| 评审效率低 | 大 PR 动辄几百行改动，人工逐行 review 耗时耗力 |
| 风险识别困难 | 关键风险（安全、并发、数据一致性）容易被忽略 |
| 标准不统一 | 不同人评审角度不同，缺乏结构化评审框架 |
| 技术债务积累 | 技术债务无法量化，长期积累导致代码难维护 |
| 知识传承难 | 新人或不熟悉代码的人参与 review 形同虚设 |

## 🧩 Skill 编排图谱

```
[用户输入 GitHub PR URL]
          │
          ▼
┌──────────────────────────────────────┐
│  Step 1: github                       │
│  抓取 PR 元数据：标题、描述、文件列表  │
│  抓取完整 diff 内容                   │
│  抓取历史评论和评审意见               │
└──────────────┬───────────────────────┘
               │ PR 元数据 + diff 内容
               ▼
┌──────────────────────────────────────┐
│  Step 2: summarize                   │
│  AI 结构化分析：                      │
│  - 改动类型识别（功能/修复/重构/依赖） │
│  - 影响范围评估（模块依赖关系）       │
│  - 高风险点识别（安全/并发/数据）     │
│  - 改动规模量化                      │
└──────────────┬───────────────────────┘
               │ 结构化分析结果
               ▼
┌──────────────────────────────────────┐
│  Step 3: code-review-skill           │
│  代码质量专项评审：                   │
│  - 代码风格与命名规范                │
│  - 潜在 Bug 与异常处理               │
│  - 测试覆盖度评估                    │
│  - 技术债务识别（重复代码/硬编码）    │
│  - 安全漏洞扫描                      │
└──────────────┬───────────────────────┘
               │ 代码评审结论
               ▼
┌──────────────────────────────────────┐
│  Step 4: feishu_doc                  │
│  生成结构化评审报告                   │
│  发布至飞书文档，支持协作评论         │
└──────────────────────────────────────┘
          │
          ▼
   [飞书评审报告文档]
```

## 🎯 核心价值

1. **效率提升**：原本 30 分钟的评审流程压缩到 5 分钟以内
2. **风险量化**：用结构化框架识别高风险改动，不遗漏关键问题
3. **标准统一**：所有 PR 使用同一套评审标准，输出稳定
4. **知识沉淀**：评审报告自动存档，新人可以参考学习
5. **技术债务可视化**：定期识别技术债务，推动代码持续健康

## 📝 使用示例

### 场景一：日常 PR 评审
```
用户：分析PR https://github.com/owner/repo/pull/123
AI：
  → Step 1: 抓取 PR #123 数据...
  → Step 2: 分析改动范围（3个模块，+200/-80行）...
  → Step 3: 发现 2 个中风险点，缺少测试覆盖...
  → Step 4: 生成评审报告 → 发布至飞书文档
  → 报告链接：[飞书文档链接]
```

### 场景二：新项目代码审查
```
用户：这个 PR 改动很大，帮我重点关注安全方面
AI：
  → 聚焦安全相关文件（认证、授权、数据加密）
  → 识别潜在安全漏洞：SQL 注入、XSS、敏感信息暴露
  → 生成安全专项报告
```

### 场景三：技术债务评估
```
用户：帮我看看这个 PR 有没有技术债务问题
AI：
  → 识别重复代码片段（2处）
  → 识别硬编码配置（3处）
  → 识别缺少注释的复杂逻辑（1处）
  → 输出技术债务清单与修复优先级
```

## 🔗 协同 Skill 详解

| Skill | 调用方式 | 职责 |
|-------|---------|------|
| **github** | `gh pr view` / `gh pr diff` | 获取 PR 完整信息 |
| **summarize** | URL / 文件内容摘要 | 结构化分析改动内容 |
| **code-review-skill** | 规则化代码评审 | 发现质量、风险、测试问题 |
| **feishu_doc** | 文档写入 | 生成并发布飞书报告 |

## ⚙️ 前置条件

1. `github` CLI 已配置：`gh auth login --hostname github.com`
2. 飞书机器人已配置文档写入权限
3. 待分析的 PR 需有读取权限（公开仓库或已授权私有仓库）