# PRSentinelAI **Repository Path**: chazzorg/pr-sentinel ## Basic Information - **Project Name**: PRSentinelAI - **Description**: 基于 Claude AI 的智能化代码评审系统。系统集成 MCP Gitee 工具,提供全自动化的 Pull Request 评审流程,支持语言特定评审标准、智能风险评估、自动合并决策和钉钉实时通知。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 2 - **Created**: 2025-09-07 - **Last Updated**: 2025-12-02 ## Categories & Tags **Categories**: ai **Tags**: None ## README # PR Sentinel - PR 自动化评审系统 基于 Claude AI 的智能化代码评审系统。系统集成 MCP 工具,提供全自动化的 Pull Request 评审流程,支持语言特定评审标准、智能风险评估、自动合并决策和钉钉实时通知。 ## 系统架构 **PR Sentinel** 采用事件驱动的异步处理架构: 1. **Webhook 监听层** - Go 服务器接收 PR 事件 2. **评审引擎层** - Claude AI + MCP 工具智能分析代码变更 3. **决策控制层** - 多维度风险评估与自动合并判断 4. **通知推送层** - 钉钉机器人实时状态更新 5. **数据存储层** - 结构化日志记录与评分统计 ## 核心特性 ### 🤖 智能评审引擎 - **Claude AI 集成** - 基于 MCP 工具的深度代码分析 - **多维度评审标准** - 自动加载 review 目录下所有标准文件进行全面分析 - **三级风险评估** - 低风险🟢 / 中等风险🟡 / 高风险🔴 智能分级 ### ⚡ 自动化工作流 - **条件化自动合并** - 低风险 PR 满足条件时自动合并 - **敏感路径保护** - 通过正则表达式阻止关键目录自动合并 - **多重安全检查** - 合并冲突检测、测试验证、草稿状态过滤 ### 📊 数据洞察系统 - **评分算法** - 基于风险等级、文件数量、测试状态的0-100分评分 - **历史追踪** - 按日期记录评审历史,支持统计分析 - **结构化日志** - Webhook数据、评审结果、验证日志分类存储 ### 🔒 企业级安全 - **HMAC-SHA256签名** - 防重放攻击的webhook鉴权机制 - **多层权限控制** - 脚本执行权限自动管理 - **配置隔离** - 敏感信息通过环境变量管理 ### 🌐 中文本土化 - **全中文输出** - 评审评论、通知消息、日志记录 - **钉钉深度集成** - 支持群机器人实时推送 - **时区适配** - 按中国时区记录时间戳 ## 快速开始 ### 选择部署方式 PR Sentinel 提供多种部署方式,推荐使用 Docker 部署以获得最佳体验。 ### 方式一:Docker 部署(推荐)🚀 Docker 部署优势: - ✅ 一键启动,无需手动安装依赖 - ✅ 环境隔离,避免系统污染 - ✅ 快速更新,支持热更新配置 - ✅ 更安全,非 root 用户运行 - ✅ 支持多项目部署,通过 PROJECT_NAME 实现实例隔离 #### 1. 准备环境配置 ```bash # 克隆项目 git clone https://github.com/chazzorg/pr-sentinel.git cd pr-sentinel # 复制环境变量模板 cp .env.example .env # 编辑 .env 文件,设置必需的配置 vim .env ``` 必需配置项: - `ANTHROPIC_AUTH_TOKEN` 或 `CLAUDE_API_KEY`:从 https://console.anthropic.com/account/keys 获取 - `MCP_TOKEN`:从 https://gitee.com/profile/personal_access_tokens 获取 多项目部署配置(可选): - `PROJECT_NAME`:项目唯一标识符(默认:pr-sentinel) - `LISTEN_PORT`:监听端口(默认:9002) ##### 安装 Docker 如果系统尚未安装 Docker,请按以下步骤安装: **Ubuntu/Debian 系统:** ```bash # 更新包索引 sudo apt-get update # 安装必要的依赖 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密钥(使用国内镜像) sudo mkdir -p /etc/apt/keyrings curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/docker.gpg # 设置 Docker 仓库(使用阿里云镜像) echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 启动 Docker 服务 sudo systemctl start docker sudo systemctl enable docker ``` **CentOS/RHEL/Fedora 系统:** ```bash # 安装必要的依赖 sudo yum install -y yum-utils # 添加 Docker 仓库(使用阿里云镜像) sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo # 安装 Docker Engine sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 启动 Docker 服务 sudo systemctl start docker sudo systemctl enable docker ``` **配置 Docker 镜像加速(推荐):** ```bash # 创建 Docker 配置目录 sudo mkdir -p /etc/docker # 配置镜像加速器 sudo tee /etc/docker/daemon.json <<-'EOF' { "registry-mirrors": [ "https://docker.m.daocloud.io", "https://docker.rainbond.cc", "https://dockerhub.icu" ] } EOF # 重启 Docker 服务 sudo systemctl daemon-reload sudo systemctl restart docker # 验证安装 docker version docker run hello-world ``` ##### 配置非 root 用户使用 Docker 为了安全和便利,建议配置普通用户无需 sudo 即可使用 Docker: ```bash # 创建 docker 用户组(如果不存在) sudo groupadd docker # 将当前用户添加到 docker 组 sudo usermod -aG docker $USER # 激活组变更(或者注销后重新登录) newgrp docker # 验证无需 sudo 可以运行 docker docker ps # 如果遇到权限问题,修复 docker.sock 权限 sudo chmod 666 /var/run/docker.sock ``` **注意事项:** - 将用户添加到 docker 组后,该用户将获得等同于 root 的权限 - 生产环境建议使用 rootless Docker 或 Podman 以提高安全性 - 组变更需要重新登录才能完全生效 #### 2. 使用部署脚本 ```bash # 赋予脚本执行权限 chmod +x docker-deploy.sh # 构建镜像(包含自动权限修复) ./docker-deploy.sh build # 启动服务 ./docker-deploy.sh up # 查看状态 ./docker-deploy.sh status # 查看日志 ./docker-deploy.sh logs --follow ``` #### 3. Docker 部署脚本命令 | 命令 | 说明 | 示例 | |------|------|------| | `build` | 构建Docker镜像 | `./docker-deploy.sh build` | | `up` | 启动容器服务 | `./docker-deploy.sh up` | | `down` | 停止并删除容器 | `./docker-deploy.sh down` | | `restart` | 重启容器 | `./docker-deploy.sh restart` | | `logs` | 查看容器日志 | `./docker-deploy.sh logs --tail 100 --follow` | | `debug` | 查看错误日志和诊断信息 | `./docker-deploy.sh debug` | | `status` | 查看容器状态和健康检查 | `./docker-deploy.sh status` | | `shell` | 进入容器shell | `./docker-deploy.sh shell` | | `update` | 快速更新入口脚本(无需重新构建) | `./docker-deploy.sh update` | | `clean` | 清理所有容器、镜像和卷 | `./docker-deploy.sh clean --force` | | `backup` | 备份数据(日志和评分) | `./docker-deploy.sh backup` | | `restore` | 恢复备份数据 | `./docker-deploy.sh restore` | ### 方式二:本地部署 #### 1. 环境准备 ```bash # 克隆项目 git clone https://github.com/chazzorg/pr-sentinel.git cd pr-sentinel # 配置环境变量 cp .env.example .env vim .env # 编辑配置文件 ``` #### 2. 安装依赖 ##### Go 依赖 ```bash cd webhook-runner go mod download cd .. ``` 如果下载失败,使用国内镜像: ```bash go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.google.cn go clean -modcache # 清理缓存(可选) go mod download ``` ##### Claude CLI ```bash # 安装 Claude CLI npm install -g @anthropic-ai/claude-code # API 密钥会从环境变量自动读取 ``` #### 3. 启动服务 ```bash # 使用便捷脚本(推荐,包含权限修复和MCP配置) ./run.sh # 或手动运行 cd webhook-runner go build -o webhook-runner cd .. ./webhook-runner/webhook-runner ``` ## 环境变量配置 ### 必需配置 | 变量名 | 说明 | 获取方式 | |--------|------|----------| | `ANTHROPIC_AUTH_TOKEN` 或 `CLAUDE_API_KEY` | Claude AI API密钥(设置其中一个即可) | [Anthropic Console](https://console.anthropic.com/account/keys) | | `MCP_TOKEN` | Gitee访问令牌(用于所有MCP服务) | [Gitee 私人令牌](https://gitee.com/profile/personal_access_tokens) | ### MCP 服务配置 PR Sentinel 使用统一的 MCP Token 管理系统,支持多种 MCP 服务: | 变量名 | 说明 | 可选值 | |--------|------|--------| | `MCP_SERVICE` | MCP服务类型 | `mcp-gitee`(默认)
`mcp-gitee-ent`(企业版) | | `MCP_TOKEN` | 统一的访问令牌 | 适用于所有MCP服务 | #### 切换 MCP 服务 ```bash # 使用个人版(默认) export MCP_SERVICE=mcp-gitee export MCP_TOKEN=your_personal_token # 切换到企业版 export MCP_SERVICE=mcp-gitee-ent export MCP_TOKEN=your_enterprise_token ``` #### MCP 服务管理命令 ```bash # 查看可用的 MCP 服务 ./mcp/mcp-manager.sh list # 查看服务详情 ./mcp/mcp-manager.sh info mcp-gitee # 测试 MCP 连接 ./mcp/mcp-manager.sh test ``` ### 项目标识配置(多项目部署) | 变量名 | 说明 | 默认值 | |--------|------|--------| | `PROJECT_NAME` | 项目唯一标识符,用于容器、网络、卷等资源命名 | `pr-sentinel` | | `LISTEN_PORT` | Webhook 监听端口 | `9002` | **说明**:通过设置不同的 `PROJECT_NAME` 和 `LISTEN_PORT`,可以在同一服务器上部署多个独立的 PR Sentinel 实例。 ### 可选配置 | 变量名 | 说明 | 默认值 | |--------|------|--------| | **通知配置** | | | | `ENABLE_DINGTALK_NOTIFY` | 启用钉钉通知 | `true` | | `DINGTALK_WEBHOOK_URL` | 钉钉机器人Webhook | - | | **安全配置** | | | | `WEBHOOK_SECRET` | Webhook鉴权密钥 | - | | `USE_SIGNATURE` | 启用HMAC-SHA256签名验证 | `false` | | `MAX_TIMESTAMP_AGE_MS` | 签名时间戳有效期(毫秒) | `300000` | | **服务配置** | | | | `LISTEN_ADDR` | 监听地址 | `0.0.0.0` | | `LISTEN_PORT` | 监听端口 | `9002` | | `JOB_TIMEOUT_SEC` | 脚本超时时间(秒) | `900` | | **自动合并配置** | | | | `AUTO_MERGE_IF_LOW_RISK` | 低风险自动合并 | `true` | | `MERGE_METHOD` | 合并方式 | `squash` | | `MAX_LINES_FOR_AUTO_MERGE` | 自动合并最大行数 | `800` | | `BLOCK_PATH_PATTERNS` | 敏感路径正则 | `^infra/\|^deploy/` | | **评审配置** | | | | `ENABLE_REVIEW_STANDARDS` | 启用评审标准加载 | `true` | | `REVIEW_STANDARDS_DIR` | 评审标准目录 | `./review` | | `ENABLE_SCORE_RECORDING` | 启用评分记录 | `true` | | `SCORE_DIR` | 评分记录目录 | `./score` | ## 配置 Gitee Webhook 1. 进入 Gitee 仓库设置 2. 选择 "Webhooks" -> "添加 Webhook" 3. 配置以下信息: - **URL**: `http://your-server:9002/gitee-webhook` - **密钥**: 与 `.env` 中 `WEBHOOK_SECRET` 一致 - **事件**: 选择 "Pull Request" 相关事件 注意:系统只处理 `open` 和 `reopen` 事件,其他事件会被忽略。 ## Docker 部署详解 ### 容器配置 #### 端口映射 - 默认端口:`9002` - 可通过环境变量 `LISTEN_PORT` 修改 #### 数据持久化 - `/app/logs`: 日志目录(映射到 `./logs`) - `/app/score`: 评分记录(映射到 `./score`) - `/app/review`: 评审标准(映射到 `./review`) #### 资源限制 - CPU: 最大2核心,预留0.5核心 - 内存: 最大2GB,预留512MB #### 健康检查 - 端点:`http://localhost:${LISTEN_PORT}/health`(根据配置端口自动适配) - 间隔:30秒 - 超时:5秒 - 重试:3次 ### 常用操作 #### 快速更新(无需重新构建) ```bash # 修改入口脚本 vim docker-entrypoint.sh # 快速应用更改 ./docker-deploy.sh update # 验证更新 ./docker-deploy.sh logs --tail 30 ``` #### 日志管理 ```bash # 实时查看日志 ./docker-deploy.sh logs --follow # 查看最后100行 ./docker-deploy.sh logs --tail 100 # 查看错误日志 ./docker-deploy.sh debug ``` #### 容器调试 ```bash # 进入容器shell ./docker-deploy.sh shell # 以root用户进入(高级调试) docker exec -u root -it pr-sentinel /bin/bash # 检查MCP配置 docker exec pr-sentinel /bin/bash -c "cd /app && ./mcp/mcp-manager.sh list" ``` ### 故障排查 #### 容器无法启动 ```bash # 使用调试命令诊断 ./docker-deploy.sh debug # 检查环境变量 docker exec pr-sentinel env | grep -E "CLAUDE|MCP|ANTHROPIC" # 验证配置文件 cat .env | grep -E "^[^#].*=" ``` #### 健康检查失败 ```bash # 测试健康检查端点(根据配置的端口) curl http://localhost:${LISTEN_PORT:-9002}/health # 检查端口占用 lsof -i :${LISTEN_PORT:-9002} # 查看容器内部日志 docker exec pr-sentinel cat /app/logs/debug/*.log ``` #### 权限问题 ```bash # 修复日志目录权限 sudo chown -R 1001:1001 ./logs ./score # 或使用当前用户 sudo chown -R $USER:$USER ./logs ./score ``` #### MCP 服务配置问题 ```bash # 进入容器检查MCP配置 docker exec -it pr-sentinel /bin/bash # 查看可用MCP服务 ./mcp/mcp-manager.sh list # 查看服务详情 ./mcp/mcp-manager.sh info $MCP_SERVICE # 测试MCP连接 echo 'mcp__gitee__get_user_info' | claude ``` #### 网络冲突问题 ```bash # 使用简化配置避免网络冲突 ./docker-deploy.sh --simple up # 清理旧网络 docker network prune -f ``` ## 多项目部署 PR Sentinel 支持在同一服务器上部署多个独立实例,通过 `PROJECT_NAME` 环境变量实现完全的资源隔离。 ### 实现原理 当设置 `PROJECT_NAME` 环境变量后,所有 Docker 资源将自动使用该名称作为前缀: - **容器名称**:`${PROJECT_NAME}` - **镜像标签**:`${PROJECT_NAME}:latest` - **网络名称**:`${PROJECT_NAME}-network` - **存储卷**:`${PROJECT_NAME}-logs`、`${PROJECT_NAME}-score` ### 部署示例 #### 1. 准备多个项目目录 ```bash # 创建项目目录 mkdir -p /opt/pr-sentinel/project-a mkdir -p /opt/pr-sentinel/project-b # 复制代码到各目录 cp -r /path/to/pr-sentinel/* /opt/pr-sentinel/project-a/ cp -r /path/to/pr-sentinel/* /opt/pr-sentinel/project-b/ ``` #### 2. 配置项目 A ```bash cd /opt/pr-sentinel/project-a cp .env.example .env # 编辑 .env 设置唯一标识 PROJECT_NAME=pr-sentinel-proj-a LISTEN_PORT=9002 # 其他配置... ``` #### 3. 配置项目 B ```bash cd /opt/pr-sentinel/project-b cp .env.example .env # 编辑 .env 设置唯一标识 PROJECT_NAME=pr-sentinel-proj-b LISTEN_PORT=9003 # 其他配置... ``` #### 4. 分别启动项目 ```bash # 启动项目 A cd /opt/pr-sentinel/project-a ./docker-deploy.sh build ./docker-deploy.sh up # 启动项目 B cd /opt/pr-sentinel/project-b ./docker-deploy.sh build ./docker-deploy.sh up ``` ### 验证部署 ```bash # 查看所有容器 docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" # 输出示例: # NAMES STATUS PORTS # pr-sentinel-proj-a Up 5 minutes 0.0.0.0:9002->9002/tcp # pr-sentinel-proj-b Up 3 minutes 0.0.0.0:9003->9002/tcp # 测试健康检查 curl http://localhost:9002/health # 项目 A curl http://localhost:9003/health # 项目 B ``` ### 管理命令 每个项目独立管理,进入对应目录执行: ```bash ./docker-deploy.sh status # 查看状态 ./docker-deploy.sh logs # 查看日志 ./docker-deploy.sh restart # 重启服务 ./docker-deploy.sh down # 停止服务 ``` ### 注意事项 1. **端口唯一性**:每个项目必须使用不同的 `LISTEN_PORT` 2. **项目名称唯一性**:`PROJECT_NAME` 在服务器上必须全局唯一 3. **资源监控**:多项目运行时注意监控服务器CPU和内存使用 4. **独立备份**:各项目的日志和评分数据独立存储,需分别备份 详细的多项目部署指南请参考 [MULTI_PROJECT_DEPLOYMENT.md](MULTI_PROJECT_DEPLOYMENT.md)。 ## 升级流程 ### 完整升级(代码更新) ```bash # 1. 备份当前数据 ./docker-deploy.sh backup # 2. 拉取最新代码 git pull # 3. 重新构建镜像 ./docker-deploy.sh build # 4. 重启服务 ./docker-deploy.sh restart # 5. 验证服务 ./docker-deploy.sh status ``` ### 快速更新(仅配置更新) ```bash # 编辑配置文件 vim docker-entrypoint.sh # 快速应用更改 ./docker-deploy.sh update # 验证更新 ./docker-deploy.sh logs --tail 30 ``` ## 使用说明 ### 自动触发 当 Gitee 仓库有新的 PR 或 PR 重新打开时,系统会自动: 1. 接收 Webhook 事件 2. 执行代码评审 3. 发布评审评论 4. 低风险 PR 自动合并(如启用) 5. 发送钉钉通知(如配置) ### 手动测试 ```bash # 手动触发评审(需要配置 MCP_TOKEN) ./start_review.sh --repo owner/repo --pr 123 # 使用 curl 测试 webhook curl -X POST http://localhost:9002/gitee-webhook \ -H "Content-Type: application/json" \ -d '{"action":"open","pull_request":{"number":1,"base":{"repo":{"path_with_namespace":"owner/repo"}}}}' ``` ## 评审标准 ### 自定义评审标准 在 `review/` 目录下创建 `.md` 文件,系统会自动加载所有评审标准: ```bash # 创建自定义评审标准 cat > review/security.md << EOF # 安全评审标准 ## 检查项 - 不允许硬编码密钥 - 必须进行输入验证 - SQL查询必须使用参数化 EOF ``` ### 内置评审维度 系统默认从以下维度进行评审: - 代码质量和可维护性 - 安全性和潜在风险 - 性能影响 - 测试覆盖度 - 文档完整性 ## 评分系统 ### 评分算法 - **基础分数**: - 低风险🟢:90分 - 中等风险🟡:70分 - 高风险🔴:50分 - **扣分项**: - 文件数量过多:-5到-10分 - 大规模变更:根据行数扣分 - **加分项**: - 成功自动合并:+10分 - 测试通过:+5分 ### 统计分析 ```bash # 查看评分统计 ./scripts/score_stats.sh # 查看所有评分记录 cat score/all_reviews.txt ``` ## 日志管理 ### 日志结构 ``` logs/ ├── webhooks/ # Webhook原始数据 ├── reviews/ # 评审详细日志 └── debug/ # 调试信息 ``` ### 日志清理 ```bash # 清理7天前的日志(默认) ./scripts/clean_logs.sh # 清理30天前的日志 ./scripts/clean_logs.sh 30 ``` ## 生产环境建议 ### 1. 使用密钥管理服务 - 不要将敏感信息硬编码在 .env 文件中 - 考虑使用 Docker Secrets 或外部密钥管理服务 ### 2. 配置反向代理 - 使用 Nginx/Traefik 作为反向代理 - 配置 SSL/TLS 证书 - 添加速率限制 ### 3. 监控和告警 - 集成 Prometheus/Grafana 监控 - 配置日志聚合(ELK Stack) - 设置健康检查告警 ### 4. 备份策略 ```bash # 定期备份(crontab) 0 2 * * * /path/to/docker-deploy.sh backup ``` ### 5. 使用 systemd 服务(本地部署) 创建服务文件 `/etc/systemd/system/pr-sentinel.service`: ```ini [Unit] Description=PR Sentinel Webhook Service After=network.target [Service] Type=simple User=your-user WorkingDirectory=/path/to/pr-sentinel ExecStart=/path/to/pr-sentinel/webhook-runner/webhook-runner Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target ``` 启动服务: ```bash sudo systemctl daemon-reload sudo systemctl enable pr-sentinel sudo systemctl start pr-sentinel ``` ## MCP 服务扩展 ### 添加新的 MCP 服务 1. 创建服务配置文件 `mcp/services/mcp-new-service.json`: ```json { "name": "mcp-new-service", "description": "New MCP Service", "install": { "mcpServers": { "new-service": { "command": "npx", "args": ["-y", "@vendor/mcp-new-service@latest"], "env": { "API_TOKEN": "${MCP_TOKEN}" } } } }, "env": { "API_TOKEN": "${MCP_TOKEN}" }, "prefix": "mcp__new__", "commands": { "command1": "actual_command1", "command2": "actual_command2" } } ``` 2. 使用新服务: ```bash export MCP_SERVICE=mcp-new-service export MCP_TOKEN=your_token ./run.sh ``` ## 常见问题 ### Q: 如何获取 Claude API 密钥? A: 访问 https://console.anthropic.com/account/keys 创建 API 密钥。 ### Q: 如何获取 Gitee Token? A: 登录 Gitee → 设置 → 私人令牌,生成新令牌时勾选 `repo` 和 `pull_request` 权限。 ### Q: 为什么 PR 没有被自动合并? A: 检查以下条件: - PR 必须是低风险 - 不能是草稿状态 - 没有合并冲突 - 测试必须通过 - 变更行数小于配置的最大值 - 路径不匹配敏感路径模式 ### Q: 如何禁用某些功能? A: 通过环境变量控制: - 禁用钉钉通知:`ENABLE_DINGTALK_NOTIFY=false` - 禁用自动合并:`AUTO_MERGE_IF_LOW_RISK=false` - 禁用评分记录:`ENABLE_SCORE_RECORDING=false` ### Q: Docker 和本地部署有什么区别? A: Docker 部署: - ✅ 环境隔离,更安全 - ✅ 一键部署,无需安装依赖 - ✅ 支持快速更新 - ❌ 需要 Docker 环境 本地部署: - ✅ 更灵活的调试 - ✅ 更低的资源占用 - ❌ 需要手动安装依赖 - ❌ 可能有环境兼容问题 ## 技术支持 - **问题反馈**:[GitHub Issues](https://github.com/chazzorg/pr-sentinel/issues) - **功能建议**:欢迎提交 Pull Request - **技术交流**:在 Issues 中讨论 ## 许可证 MIT License - 详见 [LICENSE](LICENSE) 文件 ## 贡献指南 欢迎贡献代码、文档或建议!提交 PR 前请确保: - 代码符合项目规范 - 添加必要的测试 - 更新相关文档