diff --git a/.gitignore b/.gitignore index c54d799..90640fc 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ dist/ .env kubernetes.yaml config-overrides.json +.sisyphus/ +e2e/.env.e2e diff --git a/README.md b/README.md index 87942a1..5c33231 100644 --- a/README.md +++ b/README.md @@ -1,416 +1,180 @@ -# Gitea Assistant +# Gitea AI Assistant -Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码审查等增强功能。本工具通过Webhook与Gitea集成，自动对Pull Request和提交进行代码审查，并提供智能化的代码质量分析。 +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -## 功能特点 +AI-powered code review assistant for Gitea. Automatically reviews Pull Requests and commits using OpenAI, providing intelligent code quality analysis with both summary comments and line-level feedback. -- ✅ 自动对Gitea Pull Request进行代码审查 -- ✅ 自动对成功状态的单个提交进行代码审查 -- ✅ 使用OpenAI API进行代码分析 -- ✅ 提供总体代码审查评论 -- ✅ 支持代码行级别评论 -- ✅ 安全的Webhook验证 -- ✅ 飞书通知集成 -- ✅ 异步处理机制 -- ✅ 智能PR关联分析 -- ✅ 灵活的审查规则配置 -- ✅ **后台管理页面**: 提供UI界面，用于自动配置项目的Webhook。 +**[中文文档](./docs/README.zh-CN.md)** -## 架构设计 +## Features -### 核心组件 +- 🤖 **AI Code Review** - Automatic review of PRs and commits using OpenAI models +- 📝 **Line-Level Comments** - Precise feedback on specific code changes +- 🔄 **Dual Review Engines** - Legacy (simple) or Agent-based (multi-agent) review modes +- 🔔 **Feishu Notifications** - Integrated notification system for PR events +- 🎛️ **Admin Dashboard** - Web UI for managing repository webhooks and configuration +- 🔐 **Secure Webhooks** - HMAC-SHA256 signature verification -1. **Webhook处理层** - - 统一的Webhook端点处理 - - 事件类型自动识别 - - 请求签名验证 - - 异步处理机制 +## Architecture -2. **代码审查引擎** - - 差异分析 - - 文件变更追踪 - - 智能PR关联 - - 审查结果格式化 - -3. **AI集成层** - - OpenAI API集成 - - 可配置的提示模板 - - 结果解析和格式化 - - 错误处理和重试机制 - -4. **通知系统** - - 飞书Webhook集成 - - 多类型通知支持 - - 通知模板配置 - - 失败重试机制 - -### 安全特性 - -- Webhook请求签名验证 -- 环境变量配置管理 -- 敏感信息保护 -- 开发环境安全控制 -- 防时序攻击保护 - -### 性能优化 - -- 异步处理机制 -- 批量处理优化 -- 缓存策略 -- 资源使用监控 -- 错误重试机制 - -### 扩展性 - -- 模块化设计 -- 插件化架构 -- 配置驱动 -- 自定义审查规则 -- 多通知渠道支持 - -## 技术栈 - -- Bun -- TypeScript -- Hono (轻量级Web框架) -- OpenAI API -- Gitea API - -## 安装 - -1. 克隆仓库 - - ```bash - git clone - cd ai-review - ``` - -2. 安装依赖 - - ```bash - bun install - ``` - -3. 配置环境变量 - - 复制.env.example文件为.env并填写必要配置： - - ```bash - cp .env.example .env - ``` - - 编辑.env文件，填写Gitea和OpenAI相关配置。 - -## 配置项 - -- `GITEA_API_URL`: Gitea API URL (例如: `http://your-gitea-instance.com/api/v1`) -- `GITEA_ACCESS_TOKEN`: 用于代码审查的 Gitea 访问令牌 (需要仓库读权限和评论权限)。 -- `GITEA_ADMIN_TOKEN`: **(可选)** 用于后台管理的 Gitea 管理员令牌 (需要仓库读写及 Webhook 管理权限)。若不提供，则使用 `GITEA_ACCESS_TOKEN`。 -- `OPENAI_BASE_URL`: OpenAI 请求地址 -- `OPENAI_API_KEY`: OpenAI API密钥 -- `OPENAI_MODEL`：OpenAI 使用模型 -- `CUSTOM_SUMMARY_PROMPT`: 自定义总结审查提示 (可选) -- `CUSTOM_LINE_COMMENT_PROMPT`: 自定义行评论提示 (可选) -- `REVIEW_ENGINE`: 审查引擎模式，`legacy` 或 `agent` (默认: `legacy`) -- `REVIEW_WORKDIR`: Agent 本地仓库 mirror/worktree 工作目录 -- `REVIEW_MODEL_PLANNER`: Agent 规划模型 -- `REVIEW_MODEL_SPECIALIST`: 专家子代理模型 -- `REVIEW_MODEL_JUDGE`: Judge 聚合模型 -- `REVIEW_MAX_PARALLEL_RUNS`: 单机并发审查任务上限 -- `REVIEW_MAX_FILES_PER_RUN`: 单次审查最多处理文件数 -- `REVIEW_MAX_FILE_CONTENT_CHARS`: 单文件上下文最大字符数 -- `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE`: 自动发布评论最小置信度 -- `REVIEW_ENABLE_HUMAN_GATE`: 是否启用人工审批队列 -- `REVIEW_ALLOWED_COMMANDS`: 本地审查沙箱命令白名单 -- `REVIEW_COMMAND_TIMEOUT_MS`: 单条本地命令超时 -- `PORT`: 应用监听端口 (默认: 3000) -- `WEBHOOK_SECRET`: Webhook秘钥，用于验证请求来源 -- `FEISHU_WEBHOOK_URL`: 飞书Webhook地址，用于发送通知 -- `FEISHU_WEBHOOK_SECRET`: 飞书Webhook秘यो (可选) -- `ADMIN_PASSWORD`: 后台管理页面的登录密码 (默认: `password`) -- `JWT_SECRET`: 用于签发后台登录Token的秘钥 (默认会使用一个安全字符串) - -## 使用方法 - -1. 启动服务 - - ```bash - bun run dev # 开发模式 - # 或 - bun run start # 生产模式 - ``` - -2. **(新)** 访问后台管理页面自动配置 - - 启动服务后，直接在浏览器中访问 `http://your-server:3000`。您会看到一个登录页面。 - - **登录**: 使用您在环境变量中设置的 `ADMIN_PASSWORD` 进行登录。 - - **管理仓库**: 登录后，您将看到 Gitea 实例上的仓库列表。 - - **一键启用/停用**: 点击每行最右侧的按钮，即可为该仓库自动创建或删除 AI 代码审查所需的 Webhook。 - - > 强烈推荐使用此方法来代替手动配置，它更简单、更不容易出错。 - -3. 在Gitea仓库中**手动**配置Webhook - - 如果您不想使用后台管理功能，也可以继续手动配置。在Gitea仓库设置中添加Webhook: - - **统一Webhook端点**: - - URL: `http://your-server:3000/webhook/gitea` - - 内容类型: `application/json` - - 秘钥: 设置为与`WEBHOOK_SECRET`环境变量相同的值 - - 触发事件: 选择"Pull Request"和"Status"事件 - - > 注意: 系统使用统一的webhook端点处理所有事件类型，包括Pull Request和Commit Status事件。 - -### Webhook签名验证 - -为确保请求安全，系统使用Gitea的Webhook签名验证机制： - -1. 设置环境变量`WEBHOOK_SECRET`为一个安全的随机字符串 -2. 在Gitea的Webhook配置中，使用相同的字符串作为"秘钥" -3. 每次请求时，系统会验证请求头中的`X-Gitea-Signature` -4. 如果签名验证失败，请求会被拒绝处理 -5. 在开发环境下（`NODE_ENV=development`），如果没有提供签名，系统会跳过验证 - -验证方法使用SHA-256哈希算法，在处理高负载的情况下这能防止恶意请求并保证请求来源的真实性。 - -## 功能说明 - -### PR代码审查 - -当PR被创建或更新时，系统会自动进行代码审查，提供总体评价和行级评论。 - -### PR通知功能 - -系统支持通过飞书发送PR相关的通知： - -1. **PR创建通知** - - 当PR被创建且有指定审阅者时 - - 通知内容包括PR标题和链接 - - 通知会发送给所有指定的审阅者 - -2. **PR审阅者指派通知** - - 当有新的审阅者被指派到PR时 - - 通知内容包括PR标题和链接 - - 通知会发送给新指派的审阅者 - -### 单个提交审查 - -当提交状态变为"success"（如CI通过）时，系统会： - -1. 对该提交进行代码审查 -2. 提供总体评价作为提交评论 -3. 尝试找到关联的PR，添加行级评论 - -这对于增量工作尤其有用，可以只对最新的变更进行审查，避免重复评审已审查过的代码。 - -### Agent 审查模式（新） - -当 `REVIEW_ENGINE=agent` 时，系统会启用 Agent 编排流程： - -1. Webhook 事件先入队（支持幂等去重） -2. Worker 在后台拉取任务并执行 -3. 基于本地 clone（mirror + worktree）构建上下文 -4. 多专家代理并行生成 findings -5. Judge 聚合后按策略自动发布/进入人工审批 - -管理后台新增审查任务查看接口： - -- `GET /admin/api/review/runs` -- `GET /admin/api/review/runs/:runId` - -## 代码审查规则 - -### 总体评价规则 - -系统会从以下几个方面对代码进行总体评价： - -1. **代码质量** - - 代码结构是否清晰 - - 命名是否规范 - - 代码是否易于维护 - - 是否有重复代码 - -2. **潜在问题** - - 是否存在明显的逻辑错误 - - 是否有未处理的异常情况 - - 是否有边界条件未考虑 - -3. **性能考虑** - - 是否存在性能瓶颈 - - 是否有不必要的计算或循环 - - 内存使用是否合理 - -4. **安全性** - - 是否有潜在的安全漏洞 - - 敏感信息处理是否安全 - - 输入验证是否充分 - -5. **最佳实践** - - 是否符合语言/框架的最佳实践 - - 是否遵循设计模式 - - 是否有适当的注释和文档 - -### 行级评论规则 - -系统只会在以下情况下对特定代码行提供评论： - -1. **严重问题** - - 明显的bug或逻辑错误 - - 可能导致系统崩溃的代码 - - 严重的安全漏洞 - -2. **性能问题** - - 明显的性能瓶颈 - - 不必要的高复杂度操作 - - 资源使用不当 - -3. **数据一致性问题** - - 可能导致数据不一致的操作 - - 并发访问问题 - - 事务处理不当 - -4. **代码规范问题** - - 严重违反代码规范的情况 - - 可能导致维护困难的结构 - -> 注意：系统默认采用保守策略，不会对没有明显问题的代码行提供评论，以避免产生过多的噪音。 - -## 开发 - -- `bun run dev`: 开发模式运行 -- `bun run build`: 构建项目 -- `bun run start`: 生产模式运行 -- `bun run lint`: 运行代码风格检查 - -## 许可证 - -MIT - -## 自定义AI审查提示 - -默认情况下，AI代码审查工具配置为只对明显的bug和严重问题进行评论。你可以通过环境变量自定义AI使用的提示： - -### 自定义总结提示 - -设置`CUSTOM_SUMMARY_PROMPT`环境变量来自定义代码审查总结。你可以在提示中使用以下变量，它们会在运行时被自动替换： - -- `${context.diffContent}` - 代码差异内容 -- `${JSON.stringify(fileInfo, null, 2)}` - 变更文件的完整信息 - -### 自定义行评论提示 - -设置`CUSTOM_LINE_COMMENT_PROMPT`环境变量来自定义行级评论生成。你可以在提示中使用以下变量： - -- `${file.path}` - 当前文件路径 -- `${fileContent}` - 文件的完整内容 -- ```${file.changes.map(c => `${c.lineNumber}: ${c.content} (${c.type === 'add' ? '新增' : '上下文'})`).join('\n')}``` - 变更行的上下文 - -请确保你的自定义提示返回正确的格式，特别是对于行评论，必须返回有效的JSON数组。 - -## 部署 - -### Docker部署 - -1. 构建Docker镜像 - - ```bash - docker build -t gitea-assistant . - ``` - -2. 运行容器 - - ```bash - docker run -d \ - --name gitea-assistant \ - -p 3000:3000 \ - --env-file .env \ - gitea-assistant - ``` - -### Kubernetes部署 - -1. 使用提供的kubernetes.yaml模板 - - ```bash - cp kubernetes.yaml.template kubernetes.yaml - ``` - -2. 编辑kubernetes.yaml，更新环境变量和配置 - -3. 部署到Kubernetes集群 - - ```bash - kubectl apply -f kubernetes.yaml - ``` - -## 监控和日志 - -- 应用日志可以通过Docker或Kubernetes的标准日志收集机制获取 -- 建议配置日志聚合服务（如ELK、Grafana Loki等）进行日志管理 -- 关键操作（如代码审查、Webhook处理）都会记录详细日志 -- 错误和异常会被记录并包含堆栈跟踪信息 - -## 故障排除 - -### 常见问题 - -1. **Webhook验证失败** - - 检查`WEBHOOK_SECRET`环境变量是否与Gitea配置匹配 - - 确保请求头中的`X-Gitea-Signature`正确传递 - -2. **OpenAI API调用失败** - - 验证`OPENAI_API_KEY`是否正确设置 - - 检查网络连接和API端点可访问性 - - 确认API配额是否充足 - -3. **Gitea API调用失败** - - 验证`GITEA_ACCESS_TOKEN`是否有效 - - 检查Gitea实例是否可访问 - - 确认令牌权限是否足够 - -### 调试模式 - -在开发环境中，可以设置以下环境变量启用调试模式： - -```bash -DEBUG=true -NODE_ENV=development +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ Gitea Server │────▶│ Gitea Assistant │────▶│ OpenAI API │ +│ (Webhooks) │ │ (Hono + Bun) │ │ │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + │ + ▼ + ┌──────────────────┐ + │ Admin Dashboard │ + │ (React SPA) │ + └──────────────────┘ ``` -## 贡献指南 +### Review Engines -### 开发流程 +| Engine | Description | Use Case | +|--------|-------------|----------| +| `legacy` | Single-pass AI review with summary + line comments | Simple, fast reviews | +| `agent` | Multi-agent orchestration with specialists, reflection, and debate | Deep, comprehensive analysis | -1. Fork项目并创建特性分支 -2. 提交变更并编写测试 -3. 确保代码通过lint检查 -4. 提交Pull Request +## Quick Start -### 代码规范 +### Prerequisites -- 使用TypeScript编写代码 -- 遵循项目中的tslint配置 -- 编写清晰的注释和文档 -- 保持代码风格一致 +- [Bun](https://bun.sh/) >= 1.2.5 +- Gitea instance with API access +- OpenAI API key -### 测试 +### Installation -- 编写单元测试覆盖新功能 -- 确保现有测试通过 -- 测试Webhook处理逻辑 -- 验证AI审查功能 +```bash +git clone https://github.com/user/gitea-ai-assistant.git +cd gitea-ai-assistant +bun install +cp .env.example .env +``` -## 版本历史 +### Configuration -- v1.0.0: 初始版本发布 - - 基础代码审查功能 - - Webhook集成 - - OpenAI集成 - - 飞书通知支持 +Edit `.env` with your settings: -## 社区支持 +```bash +# Gitea +GITEA_API_URL=https://your-gitea-instance.com/api/v1 +GITEA_ACCESS_TOKEN=your_gitea_token -- 提交Issue报告问题 -- 参与讨论和功能建议 -- 贡献代码和文档 -- 分享使用经验 +# OpenAI +OPENAI_API_KEY=your_openai_key +OPENAI_MODEL=gpt-4o-mini + +# Security +WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 + +# Admin Dashboard +ADMIN_PASSWORD=your_admin_password +``` + +See [Configuration Reference](#configuration-reference) for all options. + +### Running + +```bash +bun run dev # Development mode +bun run start # Production mode +``` + +### Setting Up Webhooks + +**Option 1: Admin Dashboard (Recommended)** + +1. Access `http://your-server:3000` +2. Log in with `ADMIN_PASSWORD` +3. Click "Enable" on repositories to auto-configure webhooks + +**Option 2: Manual Configuration** + +In Gitea repository settings, add a webhook: +- **URL**: `http://your-server:3000/webhook/gitea` +- **Content Type**: `application/json` +- **Secret**: Same as `WEBHOOK_SECRET` +- **Events**: "Pull Request" and "Status" + +## Configuration Reference + +### Core Settings + +| Variable | Description | Default | +|----------|-------------|---------| +| `GITEA_API_URL` | Gitea API endpoint | Required | +| `GITEA_ACCESS_TOKEN` | Token for code review (read + comment permissions) | Required | +| `GITEA_ADMIN_TOKEN` | Token for webhook management (optional) | - | +| `OPENAI_BASE_URL` | OpenAI API base URL | `https://api.openai.com/v1` | +| `OPENAI_API_KEY` | OpenAI API key | Required | +| `OPENAI_MODEL` | Model to use | `gpt-4o-mini` | +| `PORT` | Server port | `3000` | +| `WEBHOOK_SECRET` | Webhook signature secret | Required | + +### Custom Prompts + +| Variable | Description | +|----------|-------------| +| `CUSTOM_SUMMARY_PROMPT` | Override the default summary review prompt | +| `CUSTOM_LINE_COMMENT_PROMPT` | Override the default line comment prompt | + +### Admin Dashboard + +| Variable | Description | Default | +|----------|-------------|---------| +| `ADMIN_PASSWORD` | Dashboard login password | `password` | +| `JWT_SECRET` | JWT signing secret | Auto-generated | + +### Feishu Integration + +| Variable | Description | +|----------|-------------| +| `FEISHU_WEBHOOK_URL` | Feishu bot webhook URL | +| `FEISHU_WEBHOOK_SECRET` | Feishu webhook secret (optional) | + +### Agent Review Engine + +Enable with `REVIEW_ENGINE=agent` for advanced multi-agent reviews: + +| Variable | Description | Default | +|----------|-------------|---------| +| `REVIEW_ENGINE` | Engine mode (`legacy` or `agent`) | `legacy` | +| `REVIEW_WORKDIR` | Working directory for repo clones | `/tmp/gitea-assistant` | +| `REVIEW_MODEL_PLANNER` | Planner model | `gpt-4o-mini` | +| `REVIEW_MODEL_SPECIALIST` | Specialist model | `gpt-4o-mini` | +| `REVIEW_MODEL_JUDGE` | Judge model | `gpt-4o-mini` | +| `REVIEW_MAX_PARALLEL_RUNS` | Max concurrent tasks | `2` | +| `REVIEW_MAX_FILES_PER_RUN` | Max files per review | `200` | +| `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | Min confidence for auto-publish | `0.8` | +| `REVIEW_ENABLE_HUMAN_GATE` | Enable human approval | `true` | + +### Memory & Learning (Experimental) + +| Variable | Description | Default | +|----------|-------------|---------| +| `QDRANT_URL` | Qdrant vector database URL | - | +| `ENABLE_MEMORY` | Enable memory system | `false` | +| `ENABLE_REFLECTION` | Enable self-critique | `false` | +| `ENABLE_DEBATE` | Enable multi-agent debate | `false` | + +## Deployment + +### Docker + +```bash +docker build -t gitea-assistant . +docker run -d -p 3000:3000 --env-file .env gitea-assistant +``` + +### Docker Compose + +```bash +docker-compose up -d +``` + +## License + +MIT License diff --git a/docs/ADMIN_UI_DESIGN.md b/docs/ADMIN_UI_DESIGN.md deleted file mode 100644 index eae53df..0000000 --- a/docs/ADMIN_UI_DESIGN.md +++ /dev/null @@ -1,93 +0,0 @@ -# Gitea AI Assistant 后台管理页面设计方案 - -## 1. 总体目标 - -构建一个简单、安全的后台管理界面，允许管理员浏览 Gitea 上的代码仓库，并为选定的仓库一键“开启”或“关闭” AI 代码审查的 Webhook。此功能旨在替代当前繁琐的手动配置过程，简化新项目的接入流程。 - -## 2. 技术选型 - -- **后端增强**: 继续使用 **Hono** 框架，在现有应用中开辟一组新的 API 路由。 -- **前端框架**: **React (Vite + TypeScript)**，用于快速构建现代化交互界面。 -- **UI 组件库**: **shadcn/ui** 配合 **Tailwind CSS**，以实现专业且美观的界面。 -- **状态管理**: **React Query (TanStack Query)**，用于高效管理服务器状态和数据缓存。 -- **认证机制**: **JSON Web Tokens (JWT)**，实现安全无状态的登录认证。 - -## 3. 架构设计 - -采用前后端分离的架构。 - -- **后端 (Backend)**: - - 在 Hono 应用中新增路由组 `/admin/api`，提供 RESTful API。 - - 通过一个新的管理员级别 Gitea Token 与 Gitea API 交互，该 Token 需具备读写仓库和 Webhook 的权限。 - - 所有 `/admin/api` 路由都将受到 JWT 中间件的保护。 - -- **前端 (Frontend)**: - - 在项目根目录创建新的 `frontend` 文件夹，存放所有前端代码。 - - 前端为单页面应用 (SPA)，负责登录、展示仓库列表和提供 Webhook 管理操作。 - -- **部署 (Deployment)**: - - 采用多阶段 `Dockerfile` 进行构建。 - - 第一阶段构建前端静态文件。 - - 第二阶段构建后端服务。 - - 最终镜像将前端静态文件集成到后端服务中，由 Hono 统一提供服务，实现单容器部署。 - - 相应更新 `kubernetes.yaml.template` 文件。 - -## 4. 核心功能模块设计 - -### A. 认证流程 - -1. **访问**: 用户访问管理页面，若无本地有效 JWT，则跳转至登录页。 -2. **登录**: 用户输入在环境变量中配置的 `ADMIN_PASSWORD`。 -3. **验证**: 前端调用 `POST /admin/api/login`，后端验证密码。 -4. **Token 生成**: 验证成功后，后端使用 `JWT_SECRET` 生成一个有时效性的 JWT 并返回给前端。 -5. **存储**: 前端将 JWT 存储在 `localStorage` 中。 -6. **请求**: 后续所有对 `/admin/api` 的请求均在 `Authorization` 请求头中携带 `Bearer `。 - -### B. 后端 API 设计 (`/admin/api`) - -- **`POST /admin/api/login`** (公开) - - **功能**: 用户登录。 - - **请求体**: `{ password: "..." }` - - **响应**: `{ token: "jwt_token" }` 或认证失败错误。 - -- **`GET /admin/api/repositories`** (需认证) - - **功能**: 获取 Gitea 实例上管理员可见的所有仓库列表，并附带其 Webhook 状态。 - - **逻辑**: 调用 Gitea API 获取仓库列表，并对每个仓库检查是否存在由本应用创建的 Webhook。 - - **返回**: `[{ name: "owner/repo", webhook_status: "active" | "inactive" }]` - -- **`POST /admin/api/repositories/{owner}/{repo}/webhook`** (需认证) - - **功能**: 为指定仓库创建 AI Review 的 Webhook。 - - **逻辑**: 调用 Gitea API 创建 Webhook，目标 URL 指向本服务的 `/api/webhook`。 - - **返回**: `{ success: true }` - -- **`DELETE /admin/api/repositories/{owner}/{repo}/webhook`** (需认证) - - **功能**: 删除为 AI Review 创建的 Webhook。 - - **逻辑**: 调用 Gitea API 查找并删除与本服务相关的 Webhook。 - - **返回**: `{ success: true }` - -### C. 前端页面设计 - -- **登录页**: 一个居中的表单，包含密码输入框和“登录”按钮。 -- **管理主页 (Dashboard)**: - - 顶部标题和刷新按钮。 - - 仓库列表，支持按名称搜索/筛选。 - - 列表项包括： - - 仓库名称 (`owner/repo`)。 - - Webhook 状态标识 (例如，彩色的图标和文字)。 - - 操作按钮 (例如，“启用”或“停用”)。 - -## 5. 环境变量配置 - -需要新增以下环境变量： - -- `ADMIN_PASSWORD`: 后台管理页面的登录密码。 -- `JWT_SECRET`: 用于签发和验证 JWT 的密钥。 -- `GITEA_ADMIN_TOKEN`: 一个拥有 Gitea 管理权限的 Token，用于 API 调用。 - -## 6. 实施步骤规划 - -1. **项目初始化**: 创建 `frontend` 目录并初始化 Vite (React+TS) 项目，配置 UI 库。 -2. **后端开发**: 实现 `/admin/api` 路由组，包括登录、JWT 中间件和 Webhook 管理逻辑。 -3. **前端开发**: 创建登录页和管理主页，实现与后端 API 的交互。 -4. **容器化**: 更新 `Dockerfile` 为多阶段构建，并调整 `kubernetes.yaml.template`。 -5. **文档更新**: 在 `README.md` 中说明新功能的使用和配置方法。 diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md new file mode 100644 index 0000000..b561482 --- /dev/null +++ b/docs/README.zh-CN.md @@ -0,0 +1,180 @@ +# Gitea AI Assistant + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +基于 AI 的 Gitea 代码审查助手。自动审查 Pull Request 和提交，使用 OpenAI 提供智能代码质量分析，支持总体评论和行级反馈。 + +**[English Documentation](../README.md)** + +## 功能特点 + +- 🤖 **AI 代码审查** - 使用 OpenAI 模型自动审查 PR 和提交 +- 📝 **行级评论** - 针对具体代码变更的精确反馈 +- 🔄 **双引擎模式** - Legacy（简单）或 Agent（多代理）审查模式 +- 🔔 **飞书通知** - PR 事件通知集成 +- 🎛️ **管理后台** - 用于管理仓库 Webhook 和配置的 Web 界面 +- 🔐 **安全验证** - HMAC-SHA256 签名验证 + +## 架构设计 + +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ Gitea 服务器 │────▶│ Gitea Assistant │────▶│ OpenAI API │ +│ (Webhooks) │ │ (Hono + Bun) │ │ │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + │ + ▼ + ┌──────────────────┐ + │ 管理后台 │ + │ (React SPA) │ + └──────────────────┘ +``` + +### 审查引擎对比 + +| 引擎 | 描述 | 适用场景 | +|------|------|----------| +| `legacy` | 单次 AI 审查，生成总结和行级评论 | 简单、快速的审查 | +| `agent` | 多代理编排，支持专家、反思和辩论 | 深度、全面的分析 | + +## 快速开始 + +### 环境要求 + +- [Bun](https://bun.sh/) >= 1.2.5 +- 可访问的 Gitea 实例 +- OpenAI API 密钥 + +### 安装步骤 + +```bash +git clone https://github.com/user/gitea-ai-assistant.git +cd gitea-ai-assistant +bun install +cp .env.example .env +``` + +### 配置说明 + +编辑 `.env` 文件： + +```bash +# Gitea +GITEA_API_URL=https://your-gitea-instance.com/api/v1 +GITEA_ACCESS_TOKEN=your_gitea_token + +# OpenAI +OPENAI_API_KEY=your_openai_key +OPENAI_MODEL=gpt-4o-mini + +# 安全 +WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 + +# 管理后台 +ADMIN_PASSWORD=your_admin_password +``` + +完整配置项请参阅 [配置参考](#配置参考)。 + +### 启动服务 + +```bash +bun run dev # 开发模式 +bun run start # 生产模式 +``` + +### 配置 Webhook + +**方式一：管理后台（推荐）** + +1. 在浏览器中访问 `http://your-server:3000` +2. 使用 `ADMIN_PASSWORD` 登录 +3. 点击仓库对应的「启用」按钮自动配置 Webhook + +**方式二：手动配置** + +在 Gitea 仓库设置中添加 Webhook： +- **URL**: `http://your-server:3000/webhook/gitea` +- **内容类型**: `application/json` +- **密钥**: 与 `WEBHOOK_SECRET` 相同 +- **触发事件**: 「Pull Request」和「Status」 + +## 配置参考 + +### 核心配置 + +| 变量 | 描述 | 默认值 | +|------|------|--------| +| `GITEA_API_URL` | Gitea API 地址 | 必填 | +| `GITEA_ACCESS_TOKEN` | 代码审查令牌（需要读取和评论权限） | 必填 | +| `GITEA_ADMIN_TOKEN` | Webhook 管理令牌（可选） | - | +| `OPENAI_BASE_URL` | OpenAI API 基础地址 | `https://api.openai.com/v1` | +| `OPENAI_API_KEY` | OpenAI API 密钥 | 必填 | +| `OPENAI_MODEL` | 使用的模型 | `gpt-4o-mini` | +| `PORT` | 服务端口 | `3000` | +| `WEBHOOK_SECRET` | Webhook 签名验证密钥 | 必填 | + +### 自定义提示词 + +| 变量 | 描述 | +|------|------| +| `CUSTOM_SUMMARY_PROMPT` | 自定义总结审查提示词 | +| `CUSTOM_LINE_COMMENT_PROMPT` | 自定义行级评论提示词 | + +### 管理后台 + +| 变量 | 描述 | 默认值 | +|------|------|--------| +| `ADMIN_PASSWORD` | 后台登录密码 | `password` | +| `JWT_SECRET` | JWT 签名密钥 | 自动生成 | + +### 飞书集成 + +| 变量 | 描述 | +|------|------| +| `FEISHU_WEBHOOK_URL` | 飞书机器人 Webhook 地址 | +| `FEISHU_WEBHOOK_SECRET` | 飞书 Webhook 密钥（可选） | + +### Agent 审查引擎 + +设置 `REVIEW_ENGINE=agent` 启用多代理审查： + +| 变量 | 描述 | 默认值 | +|------|------|--------| +| `REVIEW_ENGINE` | 引擎模式（`legacy` 或 `agent`） | `legacy` | +| `REVIEW_WORKDIR` | 仓库克隆工作目录 | `/tmp/gitea-assistant` | +| `REVIEW_MODEL_PLANNER` | 规划模型 | `gpt-4o-mini` | +| `REVIEW_MODEL_SPECIALIST` | 专家模型 | `gpt-4o-mini` | +| `REVIEW_MODEL_JUDGE` | 判断模型 | `gpt-4o-mini` | +| `REVIEW_MAX_PARALLEL_RUNS` | 最大并发任务数 | `2` | +| `REVIEW_MAX_FILES_PER_RUN` | 单次审查最大文件数 | `200` | +| `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | 自动发布最小置信度 | `0.8` | +| `REVIEW_ENABLE_HUMAN_GATE` | 启用人工审批 | `true` | + +### 记忆与学习（实验性） + +| 变量 | 描述 | 默认值 | +|------|------|--------| +| `QDRANT_URL` | Qdrant 向量数据库地址 | - | +| `ENABLE_MEMORY` | 启用记忆系统 | `false` | +| `ENABLE_REFLECTION` | 启用自我批评 | `false` | +| `ENABLE_DEBATE` | 启用多代理辩论 | `false` | + +## 部署指南 + +### Docker + +```bash +docker build -t gitea-assistant . +docker run -d -p 3000:3000 --env-file .env gitea-assistant +``` + +### Docker Compose + +```bash +docker-compose up -d +``` + +## 许可证 + +MIT 许可证