cfix 1.0.0

package/README.md

@@ -0,0 +1,1590 @@
+# Claude CLI 自动修复服务
+
+基于 Claude CLI 的自动化代码修复服务，支持通过 HTTP 接口触发自动修复、提交和推送。
+
+## ✨ 特性
+
+### 核心功能
+- 🤖 使用 Claude Sonnet 4.5 进行智能代码修复
+- 🔧 支持多种工具调用（读文件、写文件、搜索代码等）
+- 📦 自动 Git 操作（创建分支、提交、推送）
+- 📢 企业微信通知集成
+- 🧪 可选的测试验证
+- 🌐 RESTful API 接口（基于 Koa 框架）
+- 💾 任务持久化存储（重启服务后仍可查询历史任务）
+- 🌍 支持跨域访问（CORS）
+- ⚡ 高性能异步架构
+
+### 安全与监控（v2.1 新增）
+- 🔐 **API 认证**：支持 API Key 和 IP 白名单
+- 🛡️ **输入验证**：防止命令注入、路径遍历等安全漏洞
+- ⏱️ **请求频率限制**：防止 API 滥用
+- 📊 **性能监控**：实时收集任务执行指标
+- 🔍 **请求追踪**：每个请求自动分配唯一 ID
+- 📝 **结构化日志**：支持开发和生产环境格式切换
+- ⚙️ **配置管理**：集中化配置验证和访问
+- 🔄 **错误重试**：Git 操作自动重试机制
+- 🌿 **分支冲突检测**：自动处理分支名称冲突
+- ✅ **分支名称验证**：确保符合 Git 规范
+
+### 任务队列（v2.2 新增）
+- 🚀 **智能队列管理**：支持 Redis 队列和本地队列自动降级
+- 🔄 **并发控制**：可配置最大并发任务数，防止资源耗尽
+- 📈 **自动重试**：任务失败自动重试（最多 3 次）
+- 💪 **高可用性**：Redis 不可用时自动降级到本地队列
+- 📊 **队列监控**：实时查看队列状态和任务数量
+
+### WebSocket 实时通知（v2.3 新增）
+- 🔔 **实时推送**：任务状态变更即时通知
+- 📈 **进度追踪**：实时查看任务执行进度
+- 🎯 **订阅机制**：按需订阅感兴趣的任务
+- 💻 **Web 监控面板**：可视化监控界面
+- ❤️ **心跳检测**：自动检测连接状态
+
+### 数据库支持（v2.3 新增）
+- 💾 **SQLite 数据库**：替代 JSON 文件存储
+- 🔍 **高效查询**：支持复杂查询和索引
+- 📊 **数据分析**：任务统计和性能分析
+- 🔄 **无缝迁移**：一键从 JSON 迁移到数据库
+- 📦 **自动备份**：迁移前自动备份原数据
+
+### 项目锁管理（v2.5 新增）
+- 🔒 **智能锁机制**：防止同一项目的并发 Git 冲突
+- ⏳ **自动排队**：同一项目的任务自动排队执行
+- ⚡ **并行执行**：不同项目的任务可以并行执行
+- 📊 **锁统计**：实时查看项目锁状态和等待队列
+- 🔍 **详细日志**：锁的获取、等待、释放全程记录
+- 🛡️ **健壮性强**：确保锁一定被释放，避免死锁
+
+### 人工确认机制（v2.6 新增）
+- ✅ **手动审查**：AI 修复完成后，开发者可先查看修改再决定是否提交
+- 🔍 **差异对比**：查看每个文件的 Git diff，了解具体修改内容
+- ✋ **灵活控制**：支持确认或拒绝 AI 修改，完全掌控代码质量
+- ⚙️ **可配置**：可选择需要确认或自动执行，适应不同场景
+- 📊 **详细信息**：查看修改摘要、文件列表、对话轮次等完整信息
+
+## 📋 前置要求
+
+- Node.js >= 14.x
+- Git
+- Claude CLI (需要在系统中已安装并配置)
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd claude-auto-fix
+npm install
+```
+
+### 2. 配置环境变量
+
+复制 `.env.example` 为 `.env`，并根据实际情况修改：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件：
+
+```env
+# 工作目录
+WORK_DIR=e:\\demo\\projects
+
+# 服务端口
+PORT=3000
+
+# CORS 跨域配置（可选）
+# * 表示允许所有来源，生产环境建议指定具体域名
+CORS_ORIGIN=*
+
+# 安全配置（可选）
+# API 认证密钥
+API_KEY=your-secret-api-key-here
+# IP 白名单（逗号分隔）
+ALLOWED_IPS=127.0.0.1,192.168.1.100
+
+# 企业微信机器人 Webhook（可选）
+WECOM_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY
+
+# Claude 模型
+CLAUDE_MODEL=claude-sonnet-4-5-20250929
+
+# 最大对话轮次
+MAX_CONVERSATION_TURNS=20
+
+# 日志级别
+LOG_LEVEL=info
+
+# 任务队列配置（可选）
+# Redis 配置（未配置时自动使用本地队列）
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=your-redis-password
+
+# 队列并发控制
+QUEUE_MAX_CONCURRENT=3  # 最大并发任务数
+USE_REDIS_QUEUE=false   # 是否强制使用 Redis（需要先安装 ioredis 和 bull）
+```
+
+### 3. 启动服务
+
+#### 方式一：使用服务管理脚本（推荐）
+
+**Linux/Mac:**
+
+```bash
+# 赋予执行权限
+chmod +x service.sh
+
+# 启动服务（后台运行）
+./service.sh start
+
+# 查看实时日志
+./service.sh logs
+
+# 查看服务状态
+./service.sh status
+
+# 停止服务
+./service.sh stop
+
+# 重启服务
+./service.sh restart
+
+# 查看错误日志
+./service.sh errors
+
+# 清理日志文件
+./service.sh clean
+
+# 查看帮助
+./service.sh help
+```
+
+**Windows:**
+
+```bash
+# 启动服务（后台运行）
+service.bat start
+
+# 查看实时日志
+service.bat logs
+
+# 查看服务状态
+service.bat status
+
+# 停止服务
+service.bat stop
+
+# 重启服务
+service.bat restart
+
+# 查看错误日志
+service.bat errors
+
+# 清理日志文件
+service.bat clean
+
+# 查看帮助
+service.bat help
+```
+
+**特点**:
+- ✅ 后台运行，不占用终端
+- ✅ 自动管理进程 PID
+- ✅ 日志文件记录（`logs/service.log`）
+- ✅ 实时日志查看（`logs` 命令）
+- ✅ 优雅启动/停止（SIGTERM → SIGKILL）
+
+#### 方式二：直接运行
+
+```bash
+# 生产模式（前台运行）
+npm start
+
+# 开发模式（自动重启）
+npm run dev
+```
+
+服务将在 `http://localhost:3000` 启动。
+
+## 📖 API 使用说明
+
+### 认证说明
+
+如果配置了 `API_KEY` 环境变量，需要在请求头中添加：
+
+```bash
+X-API-Key: your-secret-api-key-here
+```
+
+### 1. 健康检查（增强版）
+
+```bash
+GET /health
+```
+
+**响应示例：**
+```json
+{
+  "status": "ok",
+  "service": "claude-auto-fix",
+  "timestamp": "2026-01-03T10:00:00.000Z",
+  "uptime": 3600,
+  "memory": {
+    "rss": 52428800,
+    "heapTotal": 20971520,
+    "heapUsed": 15728640,
+    "external": 1048576
+  },
+  "metrics": {
+    "tasks": {
+      "total": 10,
+      "completed": 8,
+      "failed": 1,
+      "cancelled": 1
+    },
+    "performance": {
+      "avgTaskDuration": 45000,
+      "avgResponseTime": 120,
+      "successRate": 80
+    }
+  }
+}
+```
+
+### 2. 性能监控指标
+
+```bash
+GET /api/metrics
+```
+
+**响应示例：**
+```json
+{
+  "success": true,
+  "metrics": {
+    "tasks": {
+      "total": 10,
+      "completed": 8,
+      "failed": 1,
+      "cancelled": 1
+    },
+    "performance": {
+      "avgTaskDuration": 45000,
+      "avgResponseTime": 120,
+      "successRate": 80
+    },
+    "ai": {
+      "success": 8,
+      "failure": 2,
+      "totalTime": 360000,
+      "avgTime": 45000
+    },
+    "git": {
+      "pushSuccess": 8,
+      "pushFailure": 0,
+      "mergeSuccess": 3,
+      "mergeFailure": 0
+    },
+    "http": {
+      "total": 50,
+      "errors": 2,
+      "errorRate": 4
+    }
+  },
+  "timestamp": "2026-01-03T10:00:00.000Z"
+}
+```
+
+### 3. 配置信息（需要认证）
+
+```bash
+GET /api/config
+X-API-Key: your-secret-api-key-here
+```
+
+**响应示例：**
+```json
+{
+  "success": true,
+  "config": {
+    "server": {
+      "port": 3008,
+      "workDir": "e:\\demo\\projects"
+    },
+    "ai": {
+      "defaultEngine": "claude-cli",
+      "zhipu": {
+        "model": "glm-4-plus",
+        "maxTurns": 20,
+        "configured": false
+      },
+      "claude": {
+        "model": "claude-sonnet-4-5-20250929",
+        "maxTurns": 20,
+        "configured": true
+      }
+    },
+    "security": {
+      "corsOrigin": "*",
+      "rateLimit": {
+        "windowMs": 900000,
+        "max": 20
+      },
+      "apiKeyConfigured": true
+    }
+  }
+}
+```
+
+### 4. 项目锁统计（v2.5 新增）
+
+查看项目锁状态和等待队列信息。
+
+```bash
+GET /api/project-locks/stats
+```
+
+**响应示例：**
+```json
+{
+  "success": true,
+  "stats": {
+    "totalLocks": 156,
+    "currentLocks": 3,
+    "waitingTasks": 5,
+    "maxWaitTime": 45000,
+    "activeLocks": 3,
+    "locks": [
+      {
+        "projectKey": "e:/demo/projects/insai",
+        "taskId": "task-1767443950266-abc",
+        "waitingCount": 3,
+        "duration": 12500
+      },
+      {
+        "projectKey": "/home/user/projects/demo",
+        "taskId": "task-1767443950267-xyz",
+        "waitingCount": 2,
+        "duration": 8300
+      }
+    ]
+  }
+}
+```
+
+**字段说明：**
+- `totalLocks`: 累计锁获取次数
+- `currentLocks`: 当前活跃锁数量
+- `waitingTasks`: 当前等待任务数量
+- `maxWaitTime`: 最大等待时间（毫秒）
+- `activeLocks`: 活跃锁数量
+- `locks`: 详细的锁信息列表
+  - `projectKey`: 标准化的项目路径
+  - `taskId`: 持有锁的任务ID
+  - `waitingCount`: 等待队列中的任务数量
+  - `duration`: 锁持有时长（毫秒）
+
+**使用场景：**
+- 查看哪些项目正在被锁定
+- 查看等待队列长度
+- 监控任务等待时间
+- 调试并发任务问题
+
+### 5. 自动修复（完整流程）
+
+```bash
+POST /api/fix-bug
+Content-Type: application/json
+X-API-Key: your-secret-api-key-here  # 如果启用了认证
+```
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `projectPath` | string | 否* | 本地项目路径 |
+| `repoUrl` | string | 否* | 远程仓库地址 |
+| `requirement` | string | 是 | 修复需求描述 |
+| `runTests` | boolean | 否 | 是否运行测试，默认 `false` |
+| `autoPush` | boolean | 否 | 是否自动推送，默认 `true` |
+| `aiEngine` | string | 否 | AI 引擎，可选 `claude-cli`、`zhipu`、`claude` |
+| `baseBranch` | string | 否 | 基准分支，默认自动查找 `main`/`master` |
+| `createNewBranch` | boolean | 否 | 是否创建新分支，默认 `true` |
+| `username` | string | 否 | 用户名（用于分支命名），默认 `system` |
+| `mergeToAlpha` | boolean | 否 | 是否合并到 alpha 分支，默认 `false` |
+| `mergeToBeta` | boolean | 否 | 是否合并到 beta 分支，默认 `false` |
+| `mergeToMaster` | boolean | 否 | 是否合并到 master 分支，默认 `false` |
+| `needsApproval` | boolean | 否 | 是否需要人工确认后才执行 Git 操作，默认 `true` |
+
+\* `projectPath` 和 `repoUrl` 必须提供其中之一
+
+**请求示例 1 - 使用本地项目：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-secret-api-key-here" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "修复登录按钮点击无反应的问题，应该调用 handleLogin 函数",
+    "runTests": false,
+    "autoPush": true
+  }'
+```
+
+**请求示例 2 - 克隆远程仓库：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repoUrl": "https://github.com/username/repo.git",
+    "requirement": "将所有的 console.log 改为使用统一的 logger 工具"
+  }'
+```
+
+**请求示例 3 - 指定基准分支和自动合并：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "更新 API 接口的错误处理逻辑",
+    "baseBranch": "develop",
+    "mergeToAlpha": true,
+    "mergeToBeta": true,
+    "autoPush": true
+  }'
+```
+
+**请求示例 4 - 直接在基准分支上开发（不创建新分支）：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "修复配置文件中的拼写错误",
+    "baseBranch": "develop",
+    "createNewBranch": false,
+    "username": "zhangsan",
+    "autoPush": true
+  }'
+```
+
+**请求示例 5 - 创建新分支并指定用户名：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "优化数据库查询性能",
+    "baseBranch": "develop",
+    "createNewBranch": true,
+    "username": "lisi",
+    "autoPush": true
+  }'
+```
+
+**请求示例 6 - 直接合并到 master（谨慎使用）：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "修复紧急安全漏洞",
+    "baseBranch": "master",
+    "mergeToMaster": true,
+    "runTests": true
+  }'
+```
+
+**请求示例 7 - 需要人工确认后再执行 Git 操作（推荐）：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "重构用户认证模块",
+    "needsApproval": true,
+    "username": "zhangsan"
+  }'
+```
+
+AI 修复完成后，任务会暂停在 `waiting_approval` 状态，此时可以：
+
+```bash
+# 1. 查看修改内容
+curl http://localhost:3000/api/tasks/task-xxx/changes
+
+# 2. 确认修改（执行 Git 操作）
+curl -X POST http://localhost:3000/api/tasks/task-xxx/approve
+
+# 或者拒绝修改
+curl -X POST http://localhost:3000/api/tasks/task-xxx/reject \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "修改范围过大，需要更细致的调整"}'
+```
+
+**请求示例 8 - 跳过确认，自动执行（适合简单修复）：**
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "修复 README 中的拼写错误",
+    "needsApproval": false,
+    "username": "zhangsan"
+  }'
+```
+
+**异步响应示例（立即返回）：**
+
+接口会立即返回任务 ID，任务在后台异步执行。
+
+```json
+{
+  "success": true,
+  "id": "task-1735819200-abc123",
+  "taskId": "task-1735819200-abc123",
+  "message": "任务已创建，正在后台处理",
+  "statusUrl": "/api/tasks/task-1735819200-abc123"
+}
+```
+
+**说明**：
+- `id` / `taskId`：任务唯一标识（两个字段值相同，保持兼容性）
+- `statusUrl`：查询任务状态的 URL
+- 使用 `GET /api/tasks/{id}` 查询任务执行状态和结果
+
+**任务完成后的结果示例：**
+
+通过 `GET /api/tasks/{id}` 查询任务，当任务完成后返回：
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "task-1735819200-abc123",
+    "status": "completed",
+    "requirement": "修复登录按钮问题",
+    "projectPath": "e:\\demo\\my-project",
+    "createdAt": "2026-01-02T10:00:00.000Z",
+    "startedAt": "2026-01-02T10:00:01.000Z",
+    "completedAt": "2026-01-02T10:00:15.000Z",
+    "result": {
+      "success": true,
+      "projectName": "my-project",
+      "projectPath": "e:\\demo\\my-project",
+      "branch": "fix/auto-1735819200000",
+      "baseBranch": "develop",
+      "changedFiles": [
+        "src/components/Login.js",
+        "src/utils/logger.js"
+      ],
+      "summary": "已完成修复，修改了登录组件...",
+      "conversationTurns": 5,
+      "testsPassed": true,
+      "pushed": true,
+      "mergeResults": {
+        "alpha": true,
+        "beta": true
+      }
+    },
+    "progress": {
+      "step": "sending_success_notification",
+      "message": "发送成功通知"
+    }
+  }
+}
+```
+
+**失败响应示例：**
+
+```json
+{
+  "success": false,
+  "error": "项目路径不存在且未提供仓库地址",
+  "projectPath": null,
+  "branch": null
+}
+```
+
+### 3. 测试接口（仅 Claude 修复）
+
+用于测试 Claude 修复功能，不进行 Git 操作。
+
+```bash
+POST /api/test
+Content-Type: application/json
+```
+
+**请求示例：**
+
+```bash
+curl -X POST http://localhost:3000/api/test \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-project",
+    "requirement": "优化首页加载速度"
+  }'
+```
+
+## 💾 任务持久化
+
+服务支持任务历史记录持久化，所有任务数据会自动保存到本地文件，即使服务重启也能查询历史记录。
+
+### 存储位置
+
+任务数据存储在 `data/tasks.json` 文件中。
+
+### 功能特点
+
+- **自动保存**：任务创建、更新、完成时自动保存
+- **启动加载**：服务启动时自动加载历史任务
+- **自动清理**：保留最近 100 条任务记录，自动清理旧记录
+- **完整信息**：保存任务的完整状态、进度、结果等信息
+
+### 查询历史任务
+
+```bash
+# 基本查询（默认第 1 页，每页 20 条）
+curl http://localhost:3000/api/tasks
+
+# 分页查询
+curl http://localhost:3000/api/tasks?page=2&pageSize=50
+
+# 按状态过滤（pending, running, waiting_approval, completed, failed）
+curl http://localhost:3000/api/tasks?status=completed
+
+# 按仓库地址过滤（模糊匹配）
+curl http://localhost:3000/api/tasks?repoUrl=github.com/myorg
+
+# 按项目路径过滤（模糊匹配）
+curl http://localhost:3000/api/tasks?projectPath=demo
+
+# 组合查询
+curl "http://localhost:3000/api/tasks?status=waiting_approval&page=1&pageSize=10"
+
+# 查询特定仓库的已完成任务
+curl "http://localhost:3000/api/tasks?status=completed&repoUrl=myproject"
+
+# 查询特定任务
+curl http://localhost:3000/api/tasks/task-1735819200-abc123
+```
+
+**查询参数说明：**
+
+| 参数 | 类型 | 说明 | 默认值 |
+|------|------|------|--------|
+| `page` | number | 页码（从 1 开始） | 1 |
+| `pageSize` | number | 每页数量（最大 100） | 20 |
+| `status` | string | 任务状态过滤 | - |
+| `repoUrl` | string | 仓库地址过滤（模糊匹配，不区分大小写） | - |
+| `projectPath` | string | 项目路径过滤（模糊匹配，不区分大小写） | - |
+
+**任务状态值：**
+- `pending` - 等待执行
+- `running` - 执行中
+- `waiting_approval` - 等待人工确认
+- `completed` - 已完成
+- `failed` - 失败
+
+**任务列表响应示例：**
+
+```json
+{
+  "success": true,
+  "pagination": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 45,
+    "totalPages": 3,
+    "hasNextPage": true,
+    "hasPrevPage": false
+  },
+  "filters": {
+    "status": "completed",
+    "repoUrl": null,
+    "projectPath": null
+  },
+  "stats": {
+    "total": 50,
+    "pending": 0,
+    "running": 2,
+    "waiting_approval": 3,
+    "completed": 45,
+    "failed": 0
+  },
+  "tasks": [
+    {
+      "id": "task-1735819200-abc123",
+      "status": "completed",
+      "requirement": "修复登录按钮问题",
+      "projectPath": "e:\\demo\\my-project",
+      "repoUrl": null,
+      "runTests": false,
+      "autoPush": true,
+      "aiEngine": "claude-cli",
+      "baseBranch": "develop",
+      "mergeToAlpha": true,
+      "mergeToBeta": false,
+      "mergeToMaster": false,
+      "createdAt": "2026-01-02T10:00:00.000Z",
+      "startedAt": "2026-01-02T10:00:01.000Z",
+      "completedAt": "2026-01-02T10:00:15.000Z",
+      "duration": "14.25s",
+      "result": {
+        "success": true,
+        "projectName": "my-project",
+        "branch": "fix/auto-1735819200",
+        "changedFiles": ["src/components/Login.js"],
+        "summary": "修复了登录按钮点击无反应的问题",
+        "conversationTurns": 3,
+        "testsPassed": true,
+        "pushed": true,
+        "mergeResults": { "alpha": true }
+      },
+      "error": null,
+      "progress": {
+        "step": "sending_success_notification",
+        "message": "发送成功通知"
+      },
+      "isRunning": false,
+      "isCompleted": true,
+      "isFailed": false,
+      "isPending": false,
+      "isWaitingApproval": false
+    }
+  ]
+}
+```
+
+**字段说明：**
+
+**响应结构字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `pagination` | object | 分页信息 |
+| `pagination.page` | number | 当前页码 |
+| `pagination.pageSize` | number | 每页数量 |
+| `pagination.total` | number | 过滤后的任务总数 |
+| `pagination.totalPages` | number | 总页数 |
+| `pagination.hasNextPage` | boolean | 是否有下一页 |
+| `pagination.hasPrevPage` | boolean | 是否有上一页 |
+| `filters` | object | 当前应用的过滤条件 |
+| `stats` | object | 全局任务统计（不受过滤影响） |
+| `tasks` | array | 任务列表 |
+
+**任务对象字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 任务唯一标识 |
+| `status` | string | 任务状态：`pending`/`running`/`waiting_approval`/`completed`/`failed` |
+| `requirement` | string | 修复需求描述 |
+| `projectPath` | string | 本地项目路径 |
+| `repoUrl` | string | 远程仓库地址 |
+| `runTests` | boolean | 是否运行测试 |
+| `autoPush` | boolean | 是否自动推送 |
+| `aiEngine` | string | 使用的 AI 引擎 |
+| `baseBranch` | string | 基准分支 |
+| `createNewBranch` | boolean | 是否创建新分支 |
+| `username` | string | 用户名（用于分支命名） |
+| `mergeToAlpha` | boolean | 是否合并到 alpha |
+| `mergeToBeta` | boolean | 是否合并到 beta |
+| `mergeToMaster` | boolean | 是否合并到 master |
+| `createdAt` | string | 创建时间（ISO 8601） |
+| `startedAt` | string | 开始时间（ISO 8601） |
+| `completedAt` | string | 完成时间（ISO 8601） |
+| `duration` | string | 执行耗时（如：`14.25s`） |
+| `result` | object | 执行结果（仅 completed 状态） |
+| `error` | string | 错误信息（仅 failed 状态） |
+| `progress` | object | 当前进度信息 |
+| `isRunning` | boolean | 便捷字段：是否正在运行 |
+| `isCompleted` | boolean | 便捷字段：是否已完成 |
+| `isFailed` | boolean | 便捷字段：是否失败 |
+| `isPending` | boolean | 便捷字段：是否等待中 |
+| `isWaitingApproval` | boolean | 便捷字段：是否等待人工确认 |
+
+## 🌍 跨域支持（CORS）
+
+服务已启用 CORS 跨域支持，允许前端应用从不同域名访问 API。
+
+### 配置方式
+
+在 `.env` 文件中配置允许的来源：
+
+```env
+# 允许所有来源（开发环境）
+CORS_ORIGIN=*
+
+# 允许特定域名（生产环境推荐）
+CORS_ORIGIN=https://example.com
+
+# 允许多个域名（逗号分隔）
+CORS_ORIGIN=http://localhost:3000,https://example.com,https://admin.example.com
+```
+
+### 支持的方法
+
+- GET
+- POST
+- PUT
+- DELETE
+- OPTIONS（预检请求）
+
+### 允许的请求头
+
+- Content-Type
+- Authorization
+
+## 🔧 工作流程
+
+```
+1. 接收 HTTP 请求
+   ↓
+2. 检查项目是否存在
+   ├─ 存在 → 拉取最新代码
+   └─ 不存在 → 克隆远程仓库
+   ↓
+3. 创建功能分支或切换到基准分支
+   ├─ 创建新分支（createNewBranch = true，默认）
+   │   └─ 分支命名: fix_[username]_[taskid]_[timestamp]
+   │       例如: fix_zhangsan_task-1735819200-abc123_1735819200000
+   └─ 直接使用基准分支（createNewBranch = false）
+       └─ 切换到指定的 baseBranch 或 main/master
+   ↓
+4. Claude 使用工具进行代码修复
+   ├─ list_files: 了解项目结构
+   ├─ search_code: 查找相关代码
+   ├─ read_file: 读取需要修改的文件
+   └─ write_file: 完成代码修改
+   ↓
+5. 运行测试（可选）
+   ↓
+6. 提交更改
+   ↓
+7. 推送到远程仓库（可选）
+   ↓
+8. 合并到目标分支（可选）
+   ├─ 合并到 alpha（如果 mergeToAlpha = true）
+   ├─ 合并到 beta（如果 mergeToBeta = true）
+   └─ 合并到 master（如果 mergeToMaster = true）
+   ↓
+9. 发送企业微信通知
+```
+
+## 📁 项目结构
+
+```
+claude-auto-fix/
+├── src/
+│   ├── index.js              # 主服务入口（Koa 框架）
+│   ├── claude-cli-service.js # Claude CLI 集成
+│   ├── git-service.js        # Git 操作封装
+│   ├── wechat-notifier.js    # 企业微信通知
+│   ├── task-manager.js       # 异步任务管理（带持久化）
+│   ├── logger.js             # 日志系统配置
+│   ├── config/
+│   │   └── index.js          # 配置管理器
+│   ├── queue/
+│   │   └── task-queue.js     # 任务队列（支持 Redis 和本地降级）
+│   ├── metrics/
+│   │   └── collector.js      # 指标收集器
+│   ├── middleware/
+│   │   ├── auth.js           # 认证中间件
+│   │   └── rate-limit.js     # 频率限制
+│   └── utils/
+│       ├── retry.js          # 重试工具
+│       └── sanitizer.js      # 输入清理
+├── logs/                     # 日志文件目录（自动生成）
+│   ├── combined-YYYY-MM-DD.log  # 综合日志
+│   └── error-YYYY-MM-DD.log     # 错误日志
+├── data/                     # 数据存储目录（自动生成）
+│   └── tasks.json               # 任务历史记录
+├── .env                      # 环境变量配置
+├── .env.example              # 环境变量示例
+├── .gitignore
+├── package.json
+└── README.md
+```
+
+## 🚦 任务队列系统
+
+服务内置智能任务队列，支持 Redis 队列和本地队列自动降级。
+
+### 队列模式
+
+**1. Redis 队列模式（推荐生产环境）**
+
+优势：
+- 持久化任务数据
+- 支持分布式部署
+- 任务优先级管理
+- 自动失败重试
+- 更好的性能监控
+
+使用方式：
+```bash
+# 1. 安装 Redis 依赖
+npm install ioredis bull
+
+# 2. 配置环境变量
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=your-password
+USE_REDIS_QUEUE=true
+
+# 3. 启动服务（自动连接 Redis）
+npm start
+```
+
+**2. 本地队列模式（默认）**
+
+优势：
+- 零依赖，开箱即用
+- 无需额外配置
+- 适合开发和小规模部署
+- Redis 故障时自动降级
+
+使用方式：
+```bash
+# 不配置 REDIS_HOST 或 USE_REDIS_QUEUE=false
+npm start
+```
+
+### 队列配置
+
+```env
+# 队列配置
+QUEUE_MAX_CONCURRENT=3      # 最大并发任务数（默认 3）
+USE_REDIS_QUEUE=false       # 是否强制使用 Redis
+
+# Redis 配置（可选）
+REDIS_HOST=127.0.0.1        # Redis 主机（不配置则使用本地队列）
+REDIS_PORT=6379             # Redis 端口
+REDIS_PASSWORD=             # Redis 密码（可选）
+```
+
+### 队列监控
+
+通过 API 查看队列状态：
+
+```bash
+GET /api/queue/stats
+```
+
+**响应示例（Redis 模式）：**
+```json
+{
+  "success": true,
+  "stats": {
+    "queueType": "redis",
+    "waiting": 5,
+    "active": 2,
+    "completed": 120,
+    "failed": 3,
+    "total": 130
+  }
+}
+```
+
+**响应示例（本地模式）：**
+```json
+{
+  "success": true,
+  "stats": {
+    "queueType": "local",
+    "waiting": 5,
+    "active": 2,
+    "completed": 0,
+    "failed": 0,
+    "total": 7,
+    "maxConcurrent": 3
+  }
+}
+```
+
+### 自动降级机制
+
+服务启动时会自动检测 Redis 可用性：
+
+1. **Redis 可用** → 使用 Redis 队列
+2. **Redis 不可用** → 自动降级到本地队列
+3. **未配置 Redis** → 直接使用本地队列
+
+降级过程完全透明，不影响业务功能。
+
+### 并发控制
+
+通过 `QUEUE_MAX_CONCURRENT` 控制同时执行的最大任务数：
+
+- **默认值**：3
+- **推荐配置**：
+  - 开发环境：1-2
+  - 小型服务器（2-4 核）：3-5
+  - 中型服务器（8 核）：5-10
+  - 大型服务器（16+ 核）：10-20
+
+```env
+# 示例：限制最多同时执行 5 个任务
+QUEUE_MAX_CONCURRENT=5
+```
+
+## 🔔 WebSocket 实时通知
+
+服务内置 WebSocket 支持，可实时推送任务状态和进度。
+
+### 启用 WebSocket
+
+```bash
+# 1. 安装 WebSocket 依赖
+npm run install:ws
+
+# 2. 启动服务（自动启用 WebSocket）
+npm start
+```
+
+WebSocket 服务地址：`ws://localhost:3008/ws`
+
+### 使用 Web 监控面板
+
+打开浏览器访问监控面板：
+
+```
+http://localhost:3008/monitor.html
+```
+
+### WebSocket 连接示例
+
+**JavaScript 客户端**：
+
+```javascript
+// 连接 WebSocket（可选 API Key）
+const ws = new WebSocket('ws://localhost:3008/ws?apiKey=your-api-key');
+
+ws.onopen = () => {
+  console.log('WebSocket 已连接');
+
+  // 订阅特定任务
+  ws.send(JSON.stringify({
+    type: 'subscribe',
+    taskId: 'task-1735819200-abc123'
+  }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+
+  switch (data.type) {
+    case 'task_status':
+      console.log(`任务 ${data.taskId} 状态: ${data.status}`);
+      break;
+
+    case 'task_progress':
+      console.log(`任务 ${data.taskId} 进度: ${data.message} (${data.percent}%)`);
+      break;
+
+    case 'task_complete':
+      console.log(`任务 ${data.taskId} 完成:`, data.result);
+      break;
+
+    case 'task_failed':
+      console.error(`任务 ${data.taskId} 失败:`, data.error);
+      break;
+
+    case 'queue_stats':
+      console.log('队列统计:', data.stats);
+      break;
+  }
+};
+
+// 取消订阅
+ws.send(JSON.stringify({
+  type: 'unsubscribe',
+  taskId: 'task-1735819200-abc123'
+}));
+```
+
+### 支持的消息类型
+
+| 客户端发送 | 说明 |
+|----------|------|
+| `subscribe` | 订阅任务状态更新 |
+| `unsubscribe` | 取消订阅 |
+| `ping` | 心跳检测 |
+
+| 服务端推送 | 说明 |
+|----------|------|
+| `connected` | 连接成功 |
+| `task_status` | 任务状态变更 |
+| `task_progress` | 任务进度更新 |
+| `task_complete` | 任务完成 |
+| `task_failed` | 任务失败 |
+| `queue_stats` | 队列统计 |
+
+## 💾 数据库支持
+
+服务支持使用 SQLite 数据库替代 JSON 文件存储，提供更高效的查询和分析能力。
+
+### 启用数据库
+
+```bash
+# 1. 安装数据库依赖
+npm run install:db
+
+# 2. 从 JSON 迁移到数据库
+npm run migrate
+```
+
+### 迁移过程
+
+```bash
+$ npm run migrate
+
+> ai-auto-fix@2.3.0 migrate
+> node src/database/migration.js
+
+开始数据迁移...
+找到 120 条任务记录
+✅ JSON 文件已备份: data/tasks.json.backup.2026-01-03T10-00-00-000Z
+✅ 数据迁移完成: 成功 120 条, 失败 0 条
+
+迁移验证:
+  JSON 文件任务数: 120
+  数据库任务总数: 120
+✅ 验证通过：任务数量一致
+
+✅ 迁移成功并已验证
+```
+
+### 数据库优势
+
+| 特性 | JSON 文件 | SQLite 数据库 |
+|------|----------|-------------|
+| **查询速度** | 慢（需全文件读取） | 快（索引支持） |
+| **复杂查询** | ❌ 不支持 | ✅ 支持 SQL |
+| **数据统计** | ❌ 需手动计算 | ✅ 内置聚合函数 |
+| **并发访问** | ❌ 可能冲突 | ✅ 事务支持 |
+| **数据分析** | ❌ 困难 | ✅ 简单 |
+| **性能** | 任务多时变慢 | 任务多时保持快速 |
+
+### 数据库表结构
+
+```sql
+-- 任务表
+CREATE TABLE tasks (
+  id TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  requirement TEXT NOT NULL,
+  project_path TEXT,
+  -- ... 其他字段
+  created_at TEXT NOT NULL
+);
+
+-- 任务结果表
+CREATE TABLE task_results (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id TEXT NOT NULL,
+  success BOOLEAN NOT NULL,
+  -- ... 其他字段
+  FOREIGN KEY (task_id) REFERENCES tasks(id)
+);
+
+-- 任务进度表
+CREATE TABLE task_progress (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id TEXT NOT NULL,
+  step TEXT NOT NULL,
+  message TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+-- 性能指标表
+CREATE TABLE metrics (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  metric_type TEXT NOT NULL,
+  metric_key TEXT NOT NULL,
+  metric_value REAL NOT NULL,
+  created_at TEXT NOT NULL
+);
+```
+
+### 迁移回滚
+
+如果迁移后发现问题，可以回滚到 JSON 文件：
+
+```bash
+# 使用备份文件恢复
+cp data/tasks.json.backup.* data/tasks.json
+```
+
+## 📋 日志系统
+
+服务使用 Winston 进行日志管理，支持控制台和文件双输出。
+
+### 日志配置
+
+在 `.env` 文件中配置日志级别：
+
+```env
+# 日志级别：error, warn, info, debug
+LOG_LEVEL=info
+```
+
+### 日志文件
+
+日志文件自动按天轮转，存储在 `logs/` 目录：
+
+- **combined-{日期}.log**: 包含所有级别的日志
+- **error-{日期}.log**: 仅包含错误日志
+
+### 日志保留策略
+
+- 综合日志：保留 14 天
+- 错误日志：保留 30 天
+- 单个日志文件最大 20MB
+
+### 日志格式
+
+```
+[2026-01-02 10:00:00] [INFO] [Task: task-1735819200-abc123]: 🚀 开始任务 task-1735819200-abc123
+[2026-01-02 10:00:01] [INFO] [Task: task-1735819200-abc123]: 📋 需求: 修复登录按钮问题
+[2026-01-02 10:00:15] [INFO] [Task: task-1735819200-abc123]: ✅ 任务完成
+```
+
+### 查看日志
+
+```bash
+# 查看实时日志
+tail -f logs/combined-$(date +%Y-%m-%d).log
+
+# 查看错误日志
+tail -f logs/error-$(date +%Y-%m-% d).log
+
+# 搜索特定任务的日志
+grep "task-1735819200-abc123" logs/combined-*.log
+```
+
+## 🛠️ Claude 可用工具
+
+Claude 在修复过程中可以使用以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `read_file` | 读取文件内容 |
+| `write_file` | 写入/修改文件 |
+| `list_files` | 列出目录中的文件 |
+| `search_code` | 在项目中搜索代码 |
+| `run_command` | 执行 shell 命令（谨慎使用） |
+
+## 📢 企业微信通知
+
+配置 `WECOM_WEBHOOK` 后，服务会在以下时机发送通知：
+
+- ✅ 任务开始
+- ✅ 任务成功完成
+- ❌ 任务失败
+
+**通知示例：**
+
+```markdown
+## ✅ 自动修复任务完成
+
+**项目名称**: my-project
+**分支**: `fix/auto-1735819200000`
+**修改文件数**: 2
+
+### 修改的文件
+- src/components/Login.js
+- src/utils/logger.js
+
+### 修改说明
+已完成修复，修改了登录组件...
+
+**完成时间**: 2026-01-02 10:00:00
+```
+
+## 🌿 分支管理策略
+
+### 分支命名规则
+
+服务支持灵活的分支命名策略：
+
+**新分支命名格式**：`fix_[username]_[taskid]_[timestamp]`
+
+- `username`: 用户名，通过 `username` 参数指定，默认为 `system`
+- `taskid`: 任务 ID，自动生成（格式：`task-{timestamp}-{random}`）
+- `timestamp`: 创建时间戳（毫秒）
+
+**示例分支名称**：
+- `fix_zhangsan_task-1735819200-abc123_1735819200000`
+- `fix_system_task-1735820000-xyz456_1735820000000`
+
+### 分支创建模式
+
+服务支持两种分支管理模式：
+
+**1. 创建新分支（默认）**
+
+```json
+{
+  "createNewBranch": true,  // 默认值
+  "username": "zhangsan",
+  "baseBranch": "develop",
+  "requirement": "修复bug"
+}
+```
+
+- 从基准分支创建新的功能分支
+- 分支命名遵循上述规则
+- 适合大多数开发场景
+
+**2. 直接在基准分支开发**
+
+```json
+{
+  "createNewBranch": false,
+  "baseBranch": "develop",
+  "requirement": "修复配置文件拼写错误"
+}
+```
+
+- 直接切换到指定的基准分支
+- 不创建新分支，直接在该分支上提交
+- 适合简单修改或配置更新
+
+### 基准分支
+
+默认情况下，服务会自动从 `main` 或 `master` 分支创建功能分支。你可以通过 `baseBranch` 参数指定其他基准分支：
+
+```json
+{
+  "baseBranch": "develop",
+  "requirement": "修复bug"
+}
+```
+
+### 自动合并
+
+服务支持在修复完成后自动合并到指定的目标分支。通过以下参数控制：
+
+- `mergeToAlpha`: 合并到 alpha 分支（测试环境）
+- `mergeToBeta`: 合并到 beta 分支（预发布环境）
+- `mergeToMaster`: 合并到 master 分支（生产环境）
+
+**合并流程**：
+1. 切换到目标分支
+2. 拉取最新代码
+3. 执行非快进合并（`--no-ff`）
+4. 推送到远程仓库
+5. 返回源分支
+
+**合并失败处理**：
+- 如果合并冲突，会自动中止合并
+- 合并结果会在响应的 `mergeResults` 字段中返回
+- 日志中会详细记录每个分支的合并状态
+
+### 使用场景
+
+```json
+// 场景 1: 创建新分支进行开发（推荐）
+{
+  "baseBranch": "develop",
+  "createNewBranch": true,
+  "username": "zhangsan",
+  "autoPush": true,
+  "requirement": "添加新功能"
+}
+
+// 场景 2: 直接在基准分支修改（简单修改）
+{
+  "baseBranch": "develop",
+  "createNewBranch": false,
+  "requirement": "修复配置文件拼写错误"
+}
+
+// 场景 3: 快速修复并发布到测试环境
+{
+  "baseBranch": "develop",
+  "createNewBranch": true,
+  "username": "lisi",
+  "mergeToAlpha": true,
+  "requirement": "修复测试环境发现的bug"
+}
+
+// 场景 4: 紧急修复，逐步发布
+{
+  "baseBranch": "master",
+  "createNewBranch": true,
+  "username": "wangwu",
+  "mergeToAlpha": true,
+  "mergeToBeta": true,
+  "runTests": true,
+  "requirement": "修复紧急安全漏洞"
+}
+```
+
+**⚠️ 重要提示**：
+- 生产环境合并（`mergeToMaster`）应谨慎使用
+- 建议配合 `runTests: true` 确保代码质量
+- 对于重要修改，建议先推送分支，通过 PR 审核后再手动合并
+- 使用 `createNewBranch: false` 时要特别注意，确认基准分支是正确的
+
+## ⚠️ 注意事项
+
+1. **Claude CLI 配置**：确保已正确安装和配置 Claude CLI
+2. **安全性**：
+   - 不要将 `.env` 文件提交到版本控制
+   - 保护好 API Key 和 Webhook 地址
+   - 建议在内网环境运行
+3. **测试**：重要项目建议开启 `runTests` 参数
+4. **审核**：建议先创建 PR 由人工审核，而非直接合并到主分支
+
+## 🐛 故障排查
+
+### 1. Claude CLI 调用失败
+
+**问题**：Claude CLI 命令执行失败
+
+**解决**：
+- 确保已安装 Claude CLI：`npm install -g @anthropic-ai/claude`
+- 检查 Claude CLI 配置是否正确
+- 验证 Claude CLI 权限设置
+
+### 2. Git 操作失败
+
+**问题**：`git: command not found` 或权限错误
+
+**解决**：
+- 确保已安装 Git 并在 PATH 中
+- 检查项目目录的读写权限
+- 验证 Git 仓库的访问权限（SSH key 或 token）
+
+### 3. 企业微信通知未收到
+
+**问题**：通知未发送
+
+**解决**：
+- 检查 `WECOM_WEBHOOK` 是否正确配置
+- 验证 Webhook 地址是否有效
+- 查看服务日志中的错误信息
+
+### 4. 分支合并失败
+
+**问题**：自动合并到目标分支失败
+
+**解决**：
+- 检查目标分支是否存在（alpha/beta/master）
+- 查看日志中的合并冲突详情
+- 验证是否有权限推送到目标分支
+- 如有冲突，建议手动解决或先不使用自动合并功能
+- 检查 `mergeResults` 字段查看具体哪个分支合并失败
+
+## 📝 示例场景
+
+### 场景 1：修复简单 Bug
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\my-app",
+    "requirement": "修复用户注册页面的邮箱验证正则表达式，应该支持 .com.cn 域名"
+  }'
+```
+
+### 场景 2：批量文案修改
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repoUrl": "https://github.com/myteam/website.git",
+    "requirement": "将所有页面中的「登陆」改为「登录」，「註冊」改为「注册」"
+  }'
+```
+
+### 场景 3：代码重构
+
+```bash
+curl -X POST http://localhost:3000/api/fix-bug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectPath": "e:\\demo\\api-server",
+    "requirement": "将 src/utils 目录下所有使用 var 声明的变量改为 const 或 let",
+    "runTests": true
+  }'
+```
+
+## 🔄 集成到现有工作流
+
+### 与 JIRA 集成
+
+通过 JIRA Webhook 触发自动修复：
+
+```javascript
+// jira-webhook-handler.js
+app.post('/webhook/jira', async (req, res) => {
+  const { issue } = req.body;
+
+  if (issue.labels.includes('auto-fix')) {
+    await axios.post('http://localhost:3000/api/fix-bug', {
+      projectPath: 'e:\\demo\\my-project',
+      requirement: issue.fields.description
+    });
+  }
+
+  res.sendStatus(200);
+});
+```
+
+### 与 GitLab CI 集成
+
+在 `.gitlab-ci.yml` 中：
+
+```yaml
+auto-fix:
+  stage: fix
+  only:
+    - labels:
+      - auto-fix
+  script:
+    - |
+      curl -X POST http://fix-service:3000/api/fix-bug \
+        -H "Content-Type: application/json" \
+        -d "{
+          \"repoUrl\": \"$CI_REPOSITORY_URL\",
+          \"requirement\": \"$ISSUE_DESCRIPTION\"
+        }"
+```
+
+## 📚 详细文档
+
+- [SERVICE_MANAGEMENT.md](SERVICE_MANAGEMENT.md) - 服务管理脚本使用指南
+- [MANUAL_APPROVAL_WORKFLOW.md](MANUAL_APPROVAL_WORKFLOW.md) - 人工确认机制实现文档
+- [PROJECT_LOCK_IMPLEMENTATION.md](PROJECT_LOCK_IMPLEMENTATION.md) - 项目锁实现文档
+- [TASK_QUEUE_INTEGRATION.md](TASK_QUEUE_INTEGRATION.md) - 任务队列集成文档
+- [WEBSOCKET_INTEGRATION.md](WEBSOCKET_INTEGRATION.md) - WebSocket 实时通知集成文档
+- [DATABASE_MIGRATION.md](DATABASE_MIGRATION.md) - 数据库迁移指南
+- [SMART_PROJECT_PREPARATION.md](SMART_PROJECT_PREPARATION.md) - 智能项目准备机制文档
+- [TASK_CANCELLATION_IMPLEMENTATION.md](TASK_CANCELLATION_IMPLEMENTATION.md) - 任务取消实现文档
+
+## 📄 License
+
+MIT
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！