# PRSentinelAI

**Repository Path**: chazzorg/pr-sentinel

## Basic Information

- **Project Name**: PRSentinelAI
- **Description**: PR Sentinel 是一个面向 Pull Request / Merge Request 的自动代码评审服务。它的重点不是替代人工 Review，而是把一些容易漏掉、容易重复检查的风险点提前标出来，并尽量把评审过程做得可追踪、可重试、可接入现有合并流程。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 3
- **Created**: 2025-09-07
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# PR Sentinel

PR Sentinel 是一个面向 Pull Request / Merge Request 的自动代码评审服务。它通过 Webhook 接收 Gitee、GitHub、GitLab 的变更事件，调用 AI 生成审查结果，再把结论回写到 PR 评论和提交状态里。

它的重点不是替代人工 Review，而是把一些容易漏掉、容易重复检查的风险点提前标出来，并尽量把评审过程做得可追踪、可重试、可接入现有合并流程。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178c6?logo=typescript&logoColor=white)](#) [![Node](https://img.shields.io/badge/Node-24+-339933?logo=nodedotjs&logoColor=white)](#) [![pnpm](https://img.shields.io/badge/pnpm-11.7-F69220?logo=pnpm&logoColor=white)](#) [![React](https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=black)](#) [![Fastify](https://img.shields.io/badge/Fastify-5-000000?logo=fastify&logoColor=white)](#) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#)

---

## 这是什么

很多 AI 代码评审工具的问题，不是“模型不会看代码”，而是评审结果很难放心接进流程：有时 diff 不完整，有时平台返回空 patch，有时模型会把没看到的上下文也说得很确定。PR Sentinel 更关注这些工程边界。

它会把一次评审拆成几步处理：

- 平台适配负责验签、解析事件、拉取变更。
- 评审任务会入队并落库，避免重复触发，也方便失败后排查。
- AI 负责生成结构化发现项。
- 策略引擎根据覆盖范围、敏感路径和风险规则给出最终状态。
- 最终结果会回写到 PR 评论和提交状态。

这样做的目的很朴素：AI 可以帮忙发现问题，但合并流程需要的是稳定、可解释、能复盘的结论。

## 主要能力

### 接入现有开发流程

- PR 打开、重新打开、更新时自动触发评审。
- 支持在评论里发送 `/pr-sentinel` 或 `/review-again` 手动重审。
- 评审结果会同时写入 PR 评论和 commit status。
- 结论分为 `pass`、`warn`、`block`，可以配合分支保护或合并门禁使用。
- Worker 队列、失败记录、重试退避和看板接口可以帮助排查运行状态。

### 多平台统一处理

- 支持 Gitee PR、GitHub PR、GitLab MR。
- 三个平台的 API、签名、diff 格式分别封装在 `skills/` 目录下。
- 服务内部只处理统一后的事件、变更和投递结果。
- 新增平台时尽量只新增对应 skill，减少对核心逻辑的影响。

### 更保守的评审策略

- 明确区分 `complete`、`partial`、`degraded` 三种覆盖状态。
- 遇到空 patch、大变更截断、平台返回内容不足时，不会假装已经完整评审。
- 对配置、脚本、CI、数据库、权限、支付等敏感路径采用更保守的风险判断。
- AI 自评不会直接决定最终状态，最终 `pass` / `warn` / `block` 由策略引擎重新计算。

## 工作流程

一次完整评审大致如下：

1. 代码平台向 `/webhooks/{platform}` 推送事件。
2. 服务校验 Webhook 签名，并保存原始事件。
3. 对应平台 skill 解析 PR / MR 信息，拉取 diff 和必要的文件内容。
4. 服务按仓库、PR、提交和触发原因做幂等入队。
5. Worker 领取任务，调用 AI Provider 生成审查发现项。
6. 策略引擎根据发现项、覆盖范围和敏感路径计算最终结论。
7. 服务把评论和 commit status 回写到代码平台。
8. 任务、评审结果和投递记录保存在本地数据库中，便于查看和重试。

## 核心特性

- Gitee / GitHub / GitLab 三平台 Webhook 接入
- PR 评论与 commit status 回写
- `/pr-sentinel`、`/review-again` 评论命令重审
- `pass` / `warn` / `block` 三态结论
- `low` / `medium` / `high` / `critical` 风险等级
- `complete` / `partial` / `degraded` 覆盖状态
- 敏感路径保守兜底
- Gitee 小型新增文件 empty patch 源码补偿
- Worker 队列、失败记录、重试退避
- 幂等评论 marker，避免重复刷屏
- OpenAI 兼容 Provider
- 任务看板、筛选分页、评审详情和审计时间线

## 适用范围

适合：

- 常规业务代码 PR 的基础风险提示
- 配置、脚本、CI、数据库、权限、支付等敏感路径变更的提前提醒
- 多平台仓库接入同一套评审规则
- 希望把 AI Review 结果接入分支保护或合并门禁的团队

不适合单独处理：

- 高风险生产变更
- 数据库迁移
- 权限体系调整
- 支付链路改动
- 大规模重构
- 安全事故修复

这些场景仍然需要人工 Review。PR Sentinel 可以提前提示风险，但不应该作为唯一放行依据。

---

## 快速开始

```bash
# 1. 安装依赖
pnpm install

# 2. 配置环境变量
cp .env.example .env

# 3. 初始化数据库
pnpm db:migrate

# 4. 启动服务
pnpm dev:server

# 5. 验证
curl http://localhost:9002/health
```

最小可运行配置：

```env
APP_BASE_URL=https://pr.example.com
ALLOW_UNSIGNED_WEBHOOKS=false

AI_BASE_URL=https://api.example.com/v1
AI_API_KEY=你的 AI API Key
AI_MODEL=你的模型名

# 只需配置实际接入平台的 Token 与 Webhook Secret
GITEE_TOKEN=
WEBHOOK_SECRET_GITEE=
```

## 平台接入

三平台 Webhook 统一入口：

```text
https://你的域名/webhooks/{platform}
```

| 平台 | Webhook URL |
| --- | --- |
| Gitee | `https://你的域名/webhooks/gitee` |
| GitHub | `https://你的域名/webhooks/github` |
| GitLab | `https://你的域名/webhooks/gitlab` |

各平台环境变量、Token 权限、Webhook 配置步骤与签名校验，见 [docs/platform-integration.md](docs/platform-integration.md)。

## 评审结论

### 状态

| 状态 | 含义 |
| --- | --- |
| `pass` | 未发现阻断风险，可进入常规合并流程 |
| `warn` | 存在中等风险或覆盖不足，需要人工确认 |
| `block` | 存在阻断风险，不建议合并 |

### 风险等级

| 等级 | 含义 |
| --- | --- |
| `low` | 文档、测试数据、小范围非敏感变更 |
| `medium` | 覆盖不足、可维护性风险、需要人工确认的上下文缺失 |
| `high` | 可能影响稳定性、安全边界、数据一致性或发布流程 |
| `critical` | 已确认或高度疑似会造成凭证泄露、权限绕过、数据破坏、远程执行等严重问题 |

### 覆盖范围

| 覆盖状态 | 含义 |
| --- | --- |
| `complete` | 变更内容可见，评审已覆盖本次变更 |
| `partial` | 部分文件或上下文不可见，需要人工补充确认 |
| `degraded` | 平台返回内容不足、patch 为空、分页超限或大变更降级 |

## 敏感路径策略

以下路径或文件类型会被更保守地处理：

`scripts/` · `security/` · `infra/` · `deploy/` · `migration/` · `migrations/` · `auth/` · `permission/` · `permissions/` · `payment/` · `payments/` · `database/` · `db/` · `Dockerfile` · `docker-compose.*` · lockfile · `.sql` · `.yaml` · `.yml`

## 文档导航

| 文档 | 内容 |
| --- | --- |
| [接入文档](docs/platform-integration.md) | 三平台 Token 权限、Webhook 配置、签名校验 |
| [`.env.example`](.env.example) | 全量环境变量与默认值 |
| [License](LICENSE) | MIT |

## 路线图

已完成：

- [x] Gitee / GitHub / GitLab 三平台 webhook、变更拉取和评论投递
- [x] 覆盖状态标记：`complete` / `partial` / `degraded`
- [x] 策略引擎重新计算 AI 评审结论
- [x] 覆盖不足类风险封顶 medium
- [x] 敏感路径保守兜底与阻断
- [x] Gitee 小型新增文件 empty patch 源码补偿
- [x] 投递幂等与 reviewRun 复用
- [x] 任务看板筛选、分页、结论摘要和审计详情

计划：

- [ ] 真实 GitLab / GitHub / Gitee 测试仓库 smoke 验证
- [ ] 看板轻量视觉增强：平台图标、暗色模式、运行态微交互
- [ ] 大 PR 分片评审
- [ ] 评论命令队列化补偿
- [ ] 多实例 / 分布式部署支持

## 贡献

欢迎通过 Issue 和 PR 参与。

提交前建议运行：

```bash
pnpm test
pnpm typecheck
pnpm build
```

## 发布前检查清单

- [ ] 已运行 `pnpm db:migrate`
- [ ] 已配置 `APP_BASE_URL` 为外部可访问地址
- [ ] 已配置 AI Provider
- [ ] 已配置目标平台 Token 与 Webhook Secret
- [ ] `ALLOW_UNSIGNED_WEBHOOKS=false`
- [ ] 测试通过

## API

| 接口 | 说明 |
| --- | --- |
| `GET /health` | 健康检查 |
| `GET /api/jobs?limit=50&offset=0` | 任务列表，支持 `status`、`platform`、`q` 筛选 |
| `GET /api/jobs/:id/run` | 指定任务的评审详情 |
| `GET /api/jobs/:id/audit` | 指定任务的评审详情、触发事件摘要和审计时间线 |

## 已知边界

- 尚未实现大 PR 分片评审。
- 平台分页超过上限时会显式失败或降级。
- SQLite 更适合单机部署。
- 看板当前只提供只读排查能力，尚未提供手动重试、取消任务或实时推送。
- 本地测试通过不等于真实平台可用；上线前必须先在测试仓库完成端到端 smoke。

## License

[MIT](LICENSE) © 2025 望天小凶许