# CodeReviewForWebHook

**Repository Path**: ldr123/CodeReviewForWebHook

## Basic Information

- **Project Name**: CodeReviewForWebHook
- **Description**: 监听webhook启动代码审查
- **Primary Language**: Python
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2025-11-13
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeReviewForWebHook

基于Webhook的自动化代码审查系统，集成AI代码审查工具（Claude Code等），使用SQLite数据库存储任务和配置。

> ⚠️ **平台支持说明**：本项目目前仅在 **Gitea** 平台测试通过并稳定运行。虽然代码中包含GitHub和GitLab的Webhook解析器，但尚未经过完整测试验证，不保证兼容性。如需在其他平台使用，请自行测试并反馈问题。

## ✨ 功能特性

- 🔗 **Gitea Webhook集成** - 专为Gitea平台优化，支持动态Webhook路径配置
- 🤖 **AI代码审查** - 集成Claude Code等AI审查工具，自动分析代码质量
- ⏱️ **智能Commit排序** - 按timestamp自动排序commits，确保切换到最新代码状态
- 📋 **审查规则管理** - Web界面管理审查规则，AI自动整理生成规则文档
- 📢 **飞书通知集成** - 按committer自动发送审查结果到飞书，支持抄送配置和PDF附件
- 📄 **PDF报告生成** - 可选的PDF报告生成功能，支持飞书附件发送（需安装WeasyPrint）
- 🗄️ **SQLite数据库** - 使用SQLite存储任务队列和CLI配置，支持并发查询
- 🔐 **安全认证** - 基于Session的登录认证，支持游客模式（只读访问）和管理员模式（完整权限）
- 👁️ **游客模式** - 无需登录即可浏览审查列表和报告，写操作需要管理员权限
- 🎨 **Dark主题界面** - 精美的深色主题Web界面，提供优雅的用户体验
- 📊 **实时任务监控** - 实时查看审查队列状态、执行进度和日志
- 🔧 **动态CLI配置** - Web界面管理多个CLI工具，支持在线切换
- 🏗️ **验证器插件系统** - 支持Unity、dotnet等验证器，可配置门禁模式（失败终止）或监控模式（失败继续）
- 💾 **报告压缩存储** - 使用LZMA极致压缩存储报告到数据库，永久保留数据
- 🔄 **智能报告恢复** - 本地文件被清理后自动从数据库恢复，无缝访问
- 🚀 **启动状态管理** - 友好的启动页面，实时显示后台任务进度
- 📁 **按日期归档** - 自动按日期组织审查报告，便于管理和检索
- 🧹 **自动清理** - 定期清理过期的审查报告和会话文件，数据库永久保留
- 🔒 **URL安全设计** - 使用16位hash作为文件标识，防止路径猜测

## 🚀 快速开始

详细安装步骤请参阅 **[安装指南](docs/INSTALLATION.md)**。

### 最简安装

```bash
# 1. 克隆项目
git clone <repository_url>
cd CodeReviewForWebHook

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置系统
cp config.yaml.example config.yaml
python tools/generate_password_hash.py  # 生成密码hash

# 4. 启动服务
python app.py
```

访问: `http://localhost:10810`（默认账号: `admin`）

## 🏗️ 技术架构

### 系统组成

CodeReviewForWebHook采用轻量级架构，所有组件运行在单个Python进程中：

```
┌─────────────────────────────────────────────────────────────┐
│                     Flask Web Server                        │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │  Webhook    │  │  Web UI      │  │  API Endpoints   │    │
│  │  Receiver   │  │  (Templates) │  │  (JSON REST)     │    │
│  └─────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                ┌─────────────┼─────────────┐
                ▼             ▼             ▼
        ┌────────────┐ ┌────────────┐ ┌───────────────┐
        │   SQLite   │ │   Queue    │ │   Scheduler   │
        │  Database  │ │  Manager   │ │   (Cleanup)   │
        │  (WAL)     │ │ (Thread)   │ │   (Timer)     │
        └────────────┘ └────────────┘ └───────────────┘
                              │
                              ▼
                    ┌────────────────────┐
                    │     AI Reviewer    │
                    │Claude/Codex/iFlow等│
                    └────────────────────┘
                              │
                ┌─────────────┼─────────────┐
                ▼             ▼             ▼
        ┌────────────┐ ┌────────────┐ ┌───────────────┐
        │    Git     │ │  Markdown  │ │    Feishu     │
        │ Operations │ │ Processor  │ │  Notifier     │
        └────────────┘ └────────────┘ └───────────────┘
```

### 核心技术栈

- **Web框架**：Flask 3.0 + Waitress（生产级WSGI服务器）
- **数据库**：SQLite 3（WAL模式，支持并发读取）
- **任务队列**：自研单线程队列管理器（数据库驱动，避免Git冲突）
- **文档处理**：Mistune 3.0（Markdown→HTML）+ Pygments 2.17（代码高亮）
- **Git操作**：subprocess调用Git命令（diff、reset、clean等）
- **AI审查**：支持多种CLI工具（Claude Code、Codex、iFlow等），同时仅能激活一个工具
- **通知推送**：飞书开放平台API（OAuth 2.0）

### 数据流转

1. **Webhook → 任务入队**
   ```
   Gitea Push → /webhook → SourcePlatformManager → TaskDB.add_task() → PENDING
   ```

2. **后台处理 → 审查执行**
   ```
   Queue Thread → TaskDB.get_next_pending_task() → RUNNING
   → GitOperations → AIReviewer → ResultProcessor → COMPLETED
   ```

3. **报告生成 → 通知发送**
   ```
   report.md → Markdown→HTML → Pygments高亮 → 保存HTML
   → FeishuNotifier → 飞书API → 用户收到通知
   ```

### 文件存储结构

```
CodeReviewForWebHook/
├── data/                          # 数据目录
│   ├── codereview.db              # SQLite数据库
│   ├── user_rules.md              # AI整理的审查规则
│   └── backups/                   # 备份目录
│       └── database/              # 数据库备份
├── reviews/                       # 审查报告目录
│   └── YYYYMMDD/                  # 按日期分目录
│       ├── Report_hash.html       # HTML报告文件
│       └── Report_hash.pdf        # PDF报告文件（可选，需安装WeasyPrint）
├── CodeReviewSessions/            # 审查会话目录
│   └── session_hash/              # 单个会话目录
│       ├── Request.md             # 任务描述
│       ├── report.md              # AI输出
│       ├── raw_messages.txt       # 原始commit messages
│       └── raw_diffs.txt          # 原始diffs
├── tools/                         # 工具脚本目录
│   ├── test_feishu.py             # 飞书接口测试工具
│   ├── backup_db.py               # 数据库备份工具
│   └── ...                        # 其他工具脚本
└── logs/                          # 日志目录
    ├── YYYYMMDD/                  # 按日期分目录
    │   └── HH/                    # 按小时分目录
    │       └── app.log            # 系统日志
    └── review_current.log         # 审查统一日志
```

## 📸 功能展示

### 启动与认证

![命令行启动](imgs/s1.png)

**系统启动** - 使用`python app.py`启动服务。启动时会自动初始化数据库、加载配置、启动后台任务队列和清理调度器。

![游客模式](imgs/s2.png)

**游客浏览** - 系统支持游客模式，无需登录即可浏览审查列表和查看审查报告，方便团队成员快速查阅。

![登录页面](imgs/s3.png)

**安全登录** - 写操作需要管理员权限。默认用户名为`admin`，密码通过`tools/generate_password_hash.py`工具生成。

![管理员审查列表](imgs/s4.png)

**审查管理** - 管理员登录后可进行完整操作：查看任务详情、删除任务、重试失败任务等。列表实时显示任务状态、结果、分支、作者等信息。

### 源平台配置

![源平台界面](imgs/s5.png)

**源平台配置** - 配置Git仓库来源平台（Gitea/GitHub/GitLab），包括Webhook URL、仓库路径、认证信息等。

![编辑源平台](imgs/s6.png)

**编辑配置** - 可自定义Webhook后缀路径、过滤规则（Merge Commits、文件类型）、排除路径等高级选项。

### 验证器配置

![验证器界面](imgs/s7.png)

**验证器管理** - 支持配置多个预审查验证器（Unity、dotnet等）。可通过拖动左侧图标调整执行顺序，支持门禁模式（失败终止）和监控模式（失败继续）。

![添加验证器](imgs/s8.png)

**添加验证器** - 配置验证器命令、参数、正则匹配模式、超时时间等。支持环境变量和导出文件配置。

### 审查规则

![审查规则](imgs/s9.png)

**规则编辑** - 管理AI审查的所有提示词和规则，包括固定提示词、SystemPrompt、ReviewRules、ProjectRules。用户可直接编辑，支持AI润色功能。

### CLI工具配置

![CLI工具配置](imgs/s10.png)

**工具管理** - 管理多个AI审查CLI工具（Claude Code、Codex等），显示激活状态、健康状态、版本信息。同一时刻仅能激活一个工具。

![添加CLI工具](imgs/s11.png)

**添加工具** - 配置工具名称、可执行文件、命令行参数、扩展提示词、安装命令等。添加后自动执行健康检查。

### 通知器配置

![通知器配置](imgs/s12.png)

**通知器管理** - 配置审查完成后的通知渠道（飞书、邮件、Webhook），支持多通知器并行发送。

![添加通知器菜单](imgs/s17.png)

**添加通知器** - 点击"添加通知器"按钮弹出下拉菜单，可选择飞书、邮件或Webhook类型。

![邮件通知器配置](imgs/s18.png)

**邮件通知器** - 配置邮件SMTP服务器、端口、用户名密码等信息，实现邮件通知功能。

![编辑通知器](imgs/s13.png)

**通知器设置** - 配置飞书App ID/Secret、邮件SMTP信息、Webhook URL等，支持启用/禁用控制。

![接收人映射](imgs/s14.png)

**接收人管理** - 为每个通知器配置committer到接收人的映射关系，实现审查结果精准推送。

![飞书机器人消息](imgs/s16.png)

**飞书机器人消息效果** - 审查完成后飞书机器人发送的实际消息。消息中包含审查报告链接，点击可直接跳转查看详细报告。

### 系统配置

![系统配置](imgs/s15.png)

**系统设置** - 配置全局开关、清理策略、日志保留、健康检查间隔等系统级参数。

## 📚 相关文档

### 用户文档
- **[安装指南](docs/INSTALLATION.md)**：环境要求、安装步骤、Gitea集成配置
- **[CLI工具配置](docs/CLI_TOOLS.md)**：AI审查工具安装、管理、飞书通知配置
- **[常见问题](docs/FAQ.md)**：故障排查、数据管理、清理策略

### 开发者文档
- **[插件开发指南](docs/PLUGIN_DEVELOPMENT.md)**：Source Platform、Executor、Receiver、CLI Tool插件开发
- **CLAUDE.md**：技术实现文档（供开发者和AI参考）
- **config.yaml.example**：配置模板和说明
- **requirements.txt**：Python依赖列表

## 📄 许可证

本项目使用MIT许可证。详见LICENSE文件。

## 🤝 贡献

欢迎提交Issue和Pull Request！在提交前请：

1. 运行`python tools/validate_config.py`验证配置
2. 确保代码符合PEP 8规范
3. 添加必要的注释和文档

## 💬 支持

如有问题或建议，请：

- 提交GitHub Issue
- 发送邮件至项目维护者
- 查看CLAUDE.md了解技术细节

---

**版本**：1.5.0
**最后更新**：2025-12-02