chore: 补充项目cursor rules

2026-03-27 10:05:50 +00:00 · 2025-04-23 13:54:10 +08:00
parent e9d4f6776c
commit 2b088a653d
8 changed files with 626 additions and 1 deletions
--- a/.cursor/rules/01-project-structure.mdc
+++ b/.cursor/rules/01-project-structure.mdc
@@ -0,0 +1,34 @@
 ---
 description:
 globs:
 alwaysApply: false
 ---
 # Project Structure
 ## Main Entry Points
 The application entry point is [src/index.ts](mdc:src/index.ts), which sets up the Hono web server and defines the main routes.
 ## Core Directories
 - **src/**: Contains all source code
  - **controllers/**: Route handlers and business logic
  - **services/**: Service layer for external API interactions
  - **config/**: Configuration management
  - **utils/**: Utility functions
 ## Configuration Files
 - [package.json](mdc:package.json): Project dependencies and scripts
 - [tsconfig.json](mdc:tsconfig.json): TypeScript compiler configuration
 - [Dockerfile](mdc:Dockerfile): Container configuration
 - [kubernetes.yaml](mdc:kubernetes.yaml): Kubernetes deployment configuration
 ## Build and Deployment
 The project uses Bun for development and production:
 - `bun run dev`: Development mode with watch
 - `bun run build`: Build production assets
 - `bun run start`: Run in production
 Docker and Kubernetes configurations are available for containerized deployment.
--- a/.cursor/rules/02-architecture-and-features.mdc
+++ b/.cursor/rules/02-architecture-and-features.mdc
@@ -0,0 +1,71 @@
 ---
 description:
 globs:
 alwaysApply: false
 ---
 # Architecture and Features
 ## Core Features
 This application is a Gitea Assistant that provides AI-driven code review capabilities for Gitea repositories. Key features include:
 - AI code review for Pull Requests
 - AI code review for successful commit statuses
 - Integration with OpenAI API for code analysis
 - Both summary and line-level code comments
 - Secure webhook validation
 - PR notification system via Feishu
 ## Architecture
 The application follows a clean, layered architecture:
 1. **Controller Layer** ([src/controllers/review.ts](mdc:src/controllers/review.ts))
   - Handles webhook requests from Gitea
   - Processes different event types (PR events, status events)
   - Manages PR notification triggers
 2. **Service Layer**
   - [src/services/gitea.ts](mdc:src/services/gitea.ts): Interacts with Gitea API
   - [src/services/ai-review.ts](mdc:src/services/ai-review.ts): Manages AI code review logic
   - [src/services/feishu.ts](mdc:src/services/feishu.ts): Handles Feishu notifications
     - PR creation notifications
     - Reviewer assignment notifications
     - Error handling and retry mechanisms
 3. **Configuration Layer** ([src/config/index.ts](mdc:src/config/index.ts))
   - Centralizes application configuration from environment variables
   - Manages Feishu webhook configurations
 4. **Utilities**
   - [src/utils/logger.ts](mdc:src/utils/logger.ts): Custom logging utilities
 ## Webhook Flow
 1. Gitea sends webhook events to `/webhook/gitea`
 2. Signature verification ensures request authenticity
 3. Events are processed based on their type:
   - Pull Request events:
     - Trigger code review on the PR
     - Send notifications to reviewers (if applicable)
   - Status events trigger code review on successful commits
 ## Notification Flow
 1. **PR Creation Flow**
   - PR webhook event received
   - Event validated and processed
   - If reviewers are assigned:
     - Feishu notification prepared with PR details
     - Notification sent to all assigned reviewers
 2. **Reviewer Assignment Flow**
   - PR review_requested event received
   - New reviewer information extracted
   - Feishu notification sent to newly assigned reviewer
   - Notification includes PR title and direct link
 3. **Error Handling**
   - Failed notifications are logged but don't block the review process
   - Automatic retry mechanism for failed notifications
   - Errors are captured and logged for monitoring
--- a/.cursor/rules/03-tech-stack-and-dependencies.mdc
+++ b/.cursor/rules/03-tech-stack-and-dependencies.mdc
@@ -0,0 +1,45 @@
 ---
 description:
 globs:
 alwaysApply: true
 ---
 # Technology Stack and Dependencies
 ## Core Technologies
 - **Runtime**: Bun (JavaScript/TypeScript runtime)
 - **Language**: TypeScript
 - **Framework**: Hono (lightweight web framework)
 - **API Integration**: OpenAI API, Gitea API
 - **Containerization**: Docker, Kubernetes
 ## Key Dependencies
 From [package.json](mdc:package.json):
 ### Production Dependencies
 - **hono**: Lightweight, ultrafast web framework
 - **@hono/zod-validator**: Schema validation for Hono
 - **zod**: TypeScript-first schema validation
 - **openai**: OpenAI API client
 - **axios**: HTTP client for API requests
 - **dotenv**: Environment variable management
 - **lodash-es**: Utility library
 ### Development Dependencies
 - **typescript**: TypeScript compiler and type definitions
 - **tslint**: Code linting
 - **@types/node**: Node.js type definitions
 - **@types/lodash-es**: Type definitions for lodash-es
 ## Environment Configuration
 The application uses environment variables for configuration, which are processed in [src/config/index.ts](mdc:src/config/index.ts). Key configurations include:
 - Gitea API settings
 - OpenAI API settings
 - Custom prompts for AI review
 - Server configuration
 - Webhook security
--- a/.cursor/rules/04-ai-code-review.mdc
+++ b/.cursor/rules/04-ai-code-review.mdc
@@ -0,0 +1,54 @@
 ---
 description:
 globs:
 alwaysApply: true
 ---
 # AI Code Review System
 ## Overview
 The AI Code Review system is the core feature of this application. It automatically analyzes code changes in Pull Requests and commits, providing insightful feedback using OpenAI's language models.
 ## Key Components
 - **Review Controller**: [src/controllers/review.ts](mdc:src/controllers/review.ts)
  - Handles webhook events from Gitea
  - Routes events to appropriate handlers
 - **AI Review Service**: [src/services/ai-review.ts](mdc:src/services/ai-review.ts)
  - Contains the core logic for AI-powered code review
  - Generates both summary comments and line-level feedback
  - Customizable prompts for different review contexts
 - **Gitea Service**: [src/services/gitea.ts](mdc:src/services/gitea.ts)
  - Fetches code diffs and file contents from Gitea API
  - Posts review comments back to Gitea
 ## Review Workflow
 1. **Trigger**:
   - Pull Request created/updated or
   - Commit status changes to "success"
 2. **Code Analysis**:
   - Fetch diff content from Gitea
   - Process and analyze changes
   - Generate AI prompts with context
 3. **AI Review**:
   - Send processed data to OpenAI API
   - Generate summary feedback
   - Generate line-level comments
 4. **Feedback Delivery**:
   - Post summary comment to PR or commit
   - Add line comments to specific code sections
   - Apply formatting for better readability
 ## Customization
 The system supports customizable prompts through environment variables:
 - `CUSTOM_SUMMARY_PROMPT`: For overall review summaries
 - `CUSTOM_LINE_COMMENT_PROMPT`: For line-specific comments
 Default prompts are designed to focus on bugs and serious issues rather than style or minor concerns.
--- a/.cursor/rules/05-deployment-and-configuration.mdc
+++ b/.cursor/rules/05-deployment-and-configuration.mdc
@@ -0,0 +1,69 @@
 ---
 description:
 globs:
 alwaysApply: false
 ---
 # Deployment and Configuration
 ## Environment Variables
 The application is configured through environment variables, defined in [src/config/index.ts](mdc:src/config/index.ts):
 - **Gitea Configuration**:
  - `GITEA_API_URL`: Gitea API endpoint URL
  - `GITEA_ACCESS_TOKEN`: Access token for Gitea API
 - **OpenAI Configuration**:
  - `OPENAI_BASE_URL`: OpenAI API base URL
  - `OPENAI_API_KEY`: API key for OpenAI
  - `OPENAI_MODEL`: Model to use (e.g., "gpt-4o")
 - **Server Configuration**:
  - `PORT`: Server port (default: 3000)
  - `WEBHOOK_SECRET`: Secret for webhook verification
 - **Custom Prompts**:
  - `CUSTOM_SUMMARY_PROMPT`: Custom prompt for summary reviews
  - `CUSTOM_LINE_COMMENT_PROMPT`: Custom prompt for line comments
 ## Deployment Options
 ### Local Development
 ```bash
 # Development mode with hot reload
 bun run dev
 # Production mode
 bun run build
 bun run start
 ```
 ### Docker Deployment
 The [Dockerfile](mdc:Dockerfile) provides containerization support:
 ```bash
 # Build the Docker image
 docker build -t gitea-assistant:latest .
 # Run the container
 docker run -p 3000:3000 --env-file .env gitea-assistant:latest
 ```
 ### Kubernetes Deployment
 The [kubernetes.yaml](mdc:kubernetes.yaml) and [kubernetes.yaml.template](mdc:kubernetes.yaml.template) files provide Kubernetes deployment configuration.
 Deployment can be managed using:
 ```bash
 # Apply configuration
 kubectl apply -f kubernetes.yaml
 ```
 ### Webhook Setup
 Configure Gitea webhooks to point to the `/webhook/gitea` endpoint with:
 - Content type: application/json
 - Secret: matching WEBHOOK_SECRET environment variable
 - Events: Pull Request and Status events
--- a/.cursor/rules/06-contribution-guidelines.mdc
+++ b/.cursor/rules/06-contribution-guidelines.mdc
@@ -0,0 +1,49 @@
 ---
 description:
 globs:
 alwaysApply: false
 ---
 # Contribution Guidelines
 ## Code Style and Standards
 This project follows TypeScript best practices and uses TSLint for code style enforcement:
 - Configuration: [tslint.json](mdc:tslint.json)
 - TypeScript settings: [tsconfig.json](mdc:tsconfig.json)
 - Editor config: [.editorconfig](mdc:.editorconfig)
 Run the linter to check code style:
 ```bash
 bun run lint
 ```
 ## Project Structure Conventions
 When contributing to this project, adhere to these structural guidelines:
 1. **Controller Layer**:
   - Business logic should be delegated to services
   - Controllers should focus on request handling and response formatting
   - Keep route handlers in the [controllers/](mdc:src/controllers) directory
 2. **Service Layer**:
   - External API interactions belong in the [services/](mdc:src/services) directory
   - Each service should have a clear, single responsibility
 3. **Configuration**:
   - Environment-based configurations go in [config/index.ts](mdc:src/config/index.ts)
   - Use environment variables for configurable values
 4. **Utils**:
   - Reusable utility functions belong in [utils/](mdc:src/utils)
   - Logging should use the custom logger from [utils/logger.ts](mdc:src/utils/logger.ts)
 ## Pull Request Guidelines
 When submitting Pull Requests:
 1. Include a clear description of changes
 2. Ensure code passes linting checks
 3. Keep changes focused on a single concern
 4. Test your changes locally before submitting
--- a/.cursor/rules/07-pr-notification.mdc
+++ b/.cursor/rules/07-pr-notification.mdc
@@ -0,0 +1,66 @@
 ---
 description:
 globs:
 alwaysApply: false
 ---
 # PR 通知功能
 ## 概述
 系统通过飞书（Feishu）实现 PR 相关的通知功能，主要包括 PR 创建通知和审阅者指派通知。核心实现在 [src/services/feishu.ts](mdc:src/services/feishu.ts) 中。
 ## 主要功能
 ### PR 创建通知
 当 PR 被创建且有指定审阅者时，系统会自动发送通知：
 - 触发条件：PR 创建事件 + 存在指定审阅者
 - 通知对象：所有指定的审阅者
 - 通知内容：PR 标题和链接
 - 实现位置：[src/controllers/review.ts](mdc:src/controllers/review.ts) 中的 `handlePullRequestEvent` 函数
 ### 审阅者指派通知
 当新的审阅者被指派到 PR 时，系统会发送通知：
 - 触发条件：PR review_requested 事件
 - 通知对象：新指派的审阅者
 - 通知内容：PR 标题和链接
 - 实现位置：同样在 `handlePullRequestEvent` 函数中
 ## 配置要求
 使用通知功能需要配置以下环境变量：
 1. **必需配置**
   - `FEISHU_WEBHOOK_URL`：飞书 Webhook 地址
 2. **可选配置**
   - `FEISHU_WEBHOOK_SECRET`：飞书 Webhook 密钥（可选，用于加强安全性）
 ## 实现细节
 1. **通知处理流程**
   - Webhook 事件由 [src/controllers/review.ts](mdc:src/controllers/review.ts) 接收和处理
   - 通知发送由 [src/services/feishu.ts](mdc:src/services/feishu.ts) 实现
   - 使用飞书的消息 API 发送通知
 2. **错误处理**
   - 通知发送失败不会影响代码审查流程
   - 所有错误都会被记录但不会中断主流程
   - 支持失败重试机制
 3. **通知格式**
   - PR 创建通知：使用 🔄 表情符号
   - 审阅者指派通知：使用 👀 表情符号
   - 包含 PR 标题和可点击的链接
 ## 最佳实践
 1. **配置建议**
   - 建议配置 `FEISHU_WEBHOOK_SECRET` 以增强安全性
   - 确保飞书机器人有足够的权限发送消息
 2. **使用注意**
   - 避免过于频繁的通知以防打扰
   - 确保 PR 标题清晰以便接收者快速理解
   - 合理使用审阅者指派功能，避免过多人员参与
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Gitea Assistant
-Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码审查等增强功能。
+Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码审查等增强功能。本工具通过Webhook与Gitea集成，自动对Pull Request和提交进行代码审查，并提供智能化的代码质量分析。
 ## 功能特点
@@ -10,6 +10,62 @@ Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码
 - ✅ 提供总体代码审查评论
 - ✅ 支持代码行级别评论
 - ✅ 安全的Webhook验证
 - ✅ 飞书通知集成
 - ✅ 异步处理机制
 - ✅ 智能PR关联分析
 - ✅ 灵活的审查规则配置
 ## 架构设计
 ### 核心组件
 1. **Webhook处理层**
   - 统一的Webhook端点处理
   - 事件类型自动识别
   - 请求签名验证
   - 异步处理机制
 2. **代码审查引擎**
   - 差异分析
   - 文件变更追踪
   - 智能PR关联
   - 审查结果格式化
 3. **AI集成层**
   - OpenAI API集成
   - 可配置的提示模板
   - 结果解析和格式化
   - 错误处理和重试机制
 4. **通知系统**
   - 飞书Webhook集成
   - 多类型通知支持
   - 通知模板配置
   - 失败重试机制
 ### 安全特性
 - Webhook请求签名验证
 - 环境变量配置管理
 - 敏感信息保护
 - 开发环境安全控制
 - 防时序攻击保护
 ### 性能优化
 - 异步处理机制
 - 批量处理优化
 - 缓存策略
 - 资源使用监控
 - 错误重试机制
 ### 扩展性
 - 模块化设计
 - 插件化架构
 - 配置驱动
 - 自定义审查规则
 - 多通知渠道支持
 ## 技术栈
@@ -55,6 +111,8 @@ Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码
 - `CUSTOM_LINE_COMMENT_PROMPT`: 自定义行评论提示 (可选)
 - `PORT`: 应用监听端口 (默认: 3000)
 - `WEBHOOK_SECRET`: Webhook秘钥，用于验证请求来源
 - `FEISHU_WEBHOOK_URL`: 飞书Webhook地址，用于发送通知
 - `FEISHU_WEBHOOK_SECRET`: 飞书Webhook秘钥 (可选)
 ## 使用方法
@@ -96,6 +154,20 @@ Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码
 当PR被创建或更新时，系统会自动进行代码审查，提供总体评价和行级评论。
 ### PR通知功能
 系统支持通过飞书发送PR相关的通知：
 1. **PR创建通知**
   - 当PR被创建且有指定审阅者时
   - 通知内容包括PR标题和链接
   - 通知会发送给所有指定的审阅者
 2. **PR审阅者指派通知**
   - 当有新的审阅者被指派到PR时
   - 通知内容包括PR标题和链接
   - 通知会发送给新指派的审阅者
 ### 单个提交审查
 当提交状态变为"success"（如CI通过）时，系统会：
@@ -106,6 +178,63 @@ Gitea功能增强助手，基于Bun和TypeScript开发，提供AI驱动的代码
 这对于增量工作尤其有用，可以只对最新的变更进行审查，避免重复评审已审查过的代码。
 ## 代码审查规则
 ### 总体评价规则
 系统会从以下几个方面对代码进行总体评价：
 1. **代码质量**
   - 代码结构是否清晰
   - 命名是否规范
   - 代码是否易于维护
   - 是否有重复代码
 2. **潜在问题**
   - 是否存在明显的逻辑错误
   - 是否有未处理的异常情况
   - 是否有边界条件未考虑
 3. **性能考虑**
   - 是否存在性能瓶颈
   - 是否有不必要的计算或循环
   - 内存使用是否合理
 4. **安全性**
   - 是否有潜在的安全漏洞
   - 敏感信息处理是否安全
   - 输入验证是否充分
 5. **最佳实践**
   - 是否符合语言/框架的最佳实践
   - 是否遵循设计模式
   - 是否有适当的注释和文档
 ### 行级评论规则
 系统只会在以下情况下对特定代码行提供评论：
 1. **严重问题**
   - 明显的bug或逻辑错误
   - 可能导致系统崩溃的代码
   - 严重的安全漏洞
 2. **性能问题**
   - 明显的性能瓶颈
   - 不必要的高复杂度操作
   - 资源使用不当
 3. **数据一致性问题**
   - 可能导致数据不一致的操作
   - 并发访问问题
   - 事务处理不当
 4. **代码规范问题**
   - 严重违反代码规范的情况
   - 可能导致维护困难的结构
 > 注意：系统默认采用保守策略，不会对没有明显问题的代码行提供评论，以避免产生过多的噪音。
 ## 开发
 - `bun run dev`: 开发模式运行
@@ -137,3 +266,111 @@ MIT
 - ```${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
 ```
 ## 贡献指南
 ### 开发流程
 1. Fork项目并创建特性分支
 2. 提交变更并编写测试
 3. 确保代码通过lint检查
 4. 提交Pull Request
 ### 代码规范
 - 使用TypeScript编写代码
 - 遵循项目中的tslint配置
 - 编写清晰的注释和文档
 - 保持代码风格一致
 ### 测试
 - 编写单元测试覆盖新功能
 - 确保现有测试通过
 - 测试Webhook处理逻辑
 - 验证AI审查功能
 ## 版本历史
 - v1.0.0: 初始版本发布
  - 基础代码审查功能
  - Webhook集成
  - OpenAI集成
  - 飞书通知支持
 ## 社区支持
 - 提交Issue报告问题
 - 参与讨论和功能建议
 - 贡献代码和文档
 - 分享使用经验