cfix

v1.0.2

Published

2 months ago

AI 自动代码修复 CLI 工具

0High
0Medium
0Low

lhb2526

cfix codefix ai auto-fix claude zhipu glm automation task-queue cli

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. 安装依赖

cd claude-auto-fix
npm install

2. 配置环境变量

复制 .env.example 为 .env，并根据实际情况修改：

cp .env.example .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:

# 赋予执行权限
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:

# 启动服务（后台运行）
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）

方式二：直接运行

# 生产模式（前台运行）
npm start

# 开发模式（自动重启）
npm run dev

服务将在 http://localhost:3000 启动。

📖 API 使用说明

认证说明

如果配置了 API_KEY 环境变量，需要在请求头中添加：

X-API-Key: your-secret-api-key-here

1. 健康检查（增强版）

GET /health

响应示例：

{
  "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. 性能监控指标

GET /api/metrics

响应示例：

{
  "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. 配置信息（需要认证）

GET /api/config
X-API-Key: your-secret-api-key-here

响应示例：

{
  "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 新增）

查看项目锁状态和等待队列信息。

GET /api/project-locks/stats

响应示例：

{
  "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. 自动修复（完整流程）

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 - 使用本地项目：

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 - 克隆远程仓库：

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 - 指定基准分支和自动合并：

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 - 直接在基准分支上开发（不创建新分支）：

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 - 创建新分支并指定用户名：

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（谨慎使用）：

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 操作（推荐）：

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 状态，此时可以：

# 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 - 跳过确认，自动执行（适合简单修复）：

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，任务在后台异步执行。

{
  "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} 查询任务，当任务完成后返回：

{
  "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": "发送成功通知"
    }
  }
}

失败响应示例：

{
  "success": false,
  "error": "项目路径不存在且未提供仓库地址",
  "projectPath": null,
  "branch": null
}

3. 测试接口（仅 Claude 修复）

用于测试 Claude 修复功能，不进行 Git 操作。

POST /api/test
Content-Type: application/json

请求示例：

curl -X POST http://localhost:3000/api/test \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "e:\\demo\\my-project",
    "requirement": "优化首页加载速度"
  }'

💾 任务持久化

服务支持任务历史记录持久化，所有任务数据会自动保存到本地文件，即使服务重启也能查询历史记录。

存储位置

任务数据存储在 data/tasks.json 文件中。

功能特点

自动保存：任务创建、更新、完成时自动保存
启动加载：服务启动时自动加载历史任务
自动清理：保留最近 100 条任务记录，自动清理旧记录
完整信息：保存任务的完整状态、进度、结果等信息

查询历史任务

# 基本查询（默认第 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 - 失败

任务列表响应示例：

{
  "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 文件中配置允许的来源：

# 允许所有来源（开发环境）
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 队列模式（推荐生产环境）

优势：

持久化任务数据
支持分布式部署
任务优先级管理
自动失败重试
更好的性能监控

使用方式：

# 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 故障时自动降级

使用方式：

# 不配置 REDIS_HOST 或 USE_REDIS_QUEUE=false
npm start

队列配置

# 队列配置
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 查看队列状态：

GET /api/queue/stats

响应示例（Redis 模式）：

{
  "success": true,
  "stats": {
    "queueType": "redis",
    "waiting": 5,
    "active": 2,
    "completed": 120,
    "failed": 3,
    "total": 130
  }
}

响应示例（本地模式）：

{
  "success": true,
  "stats": {
    "queueType": "local",
    "waiting": 5,
    "active": 2,
    "completed": 0,
    "failed": 0,
    "total": 7,
    "maxConcurrent": 3
  }
}

自动降级机制

服务启动时会自动检测 Redis 可用性：

Redis 可用 → 使用 Redis 队列
Redis 不可用 → 自动降级到本地队列
未配置 Redis → 直接使用本地队列

降级过程完全透明，不影响业务功能。

并发控制

通过 QUEUE_MAX_CONCURRENT 控制同时执行的最大任务数：

默认值：3
推荐配置：
- 开发环境：1-2
- 小型服务器（2-4 核）：3-5
- 中型服务器（8 核）：5-10
- 大型服务器（16+ 核）：10-20

# 示例：限制最多同时执行 5 个任务
QUEUE_MAX_CONCURRENT=5

🔔 WebSocket 实时通知

服务内置 WebSocket 支持，可实时推送任务状态和进度。

启用 WebSocket

# 1. 安装 WebSocket 依赖
npm run install:ws

# 2. 启动服务（自动启用 WebSocket）
npm start

WebSocket 服务地址：ws://localhost:3008/ws

使用 Web 监控面板

打开浏览器访问监控面板：

http://localhost:3008/monitor.html

WebSocket 连接示例

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 文件存储，提供更高效的查询和分析能力。

启用数据库

# 1. 安装数据库依赖
npm run install:db

# 2. 从 JSON 迁移到数据库
npm run migrate

迁移过程

$ npm run migrate

> [email protected] 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 | | 数据统计 | ❌ 需手动计算 | ✅ 内置聚合函数 | | 并发访问 | ❌ 可能冲突 | ✅ 事务支持 | | 数据分析 | ❌ 困难 | ✅ 简单 | | 性能 | 任务多时变慢 | 任务多时保持快速 |

数据库表结构

-- 任务表
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 文件：

# 使用备份文件恢复
cp data/tasks.json.backup.* data/tasks.json

📋 日志系统

服务使用 Winston 进行日志管理，支持控制台和文件双输出。

日志配置

在 .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]: ✅ 任务完成

查看日志

# 查看实时日志
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 后，服务会在以下时机发送通知：

✅ 任务开始
✅ 任务成功完成
❌ 任务失败

通知示例：

## ✅ 自动修复任务完成

**项目名称**: 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. 创建新分支（默认）

{
  "createNewBranch": true,  // 默认值
  "username": "zhangsan",
  "baseBranch": "develop",
  "requirement": "修复bug"
}

从基准分支创建新的功能分支
分支命名遵循上述规则
适合大多数开发场景

2. 直接在基准分支开发

{
  "createNewBranch": false,
  "baseBranch": "develop",
  "requirement": "修复配置文件拼写错误"
}

直接切换到指定的基准分支
不创建新分支，直接在该分支上提交
适合简单修改或配置更新

基准分支

默认情况下，服务会自动从 main 或 master 分支创建功能分支。你可以通过 baseBranch 参数指定其他基准分支：

{
  "baseBranch": "develop",
  "requirement": "修复bug"
}

自动合并

服务支持在修复完成后自动合并到指定的目标分支。通过以下参数控制：

mergeToAlpha: 合并到 alpha 分支（测试环境）
mergeToBeta: 合并到 beta 分支（预发布环境）
mergeToMaster: 合并到 master 分支（生产环境）

合并流程：

切换到目标分支
拉取最新代码
执行非快进合并（--no-ff）
推送到远程仓库
返回源分支

合并失败处理：

如果合并冲突，会自动中止合并
合并结果会在响应的 mergeResults 字段中返回
日志中会详细记录每个分支的合并状态

使用场景

// 场景 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 时要特别注意，确认基准分支是正确的

⚠️ 注意事项

Claude CLI 配置：确保已正确安装和配置 Claude CLI
安全性：
- 不要将 .env 文件提交到版本控制
- 保护好 API Key 和 Webhook 地址
- 建议在内网环境运行
测试：重要项目建议开启 runTests 参数
审核：建议先创建 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

curl -X POST http://localhost:3000/api/fix-bug \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "e:\\demo\\my-app",
    "requirement": "修复用户注册页面的邮箱验证正则表达式，应该支持 .com.cn 域名"
  }'

场景 2：批量文案修改

curl -X POST http://localhost:3000/api/fix-bug \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/myteam/website.git",
    "requirement": "将所有页面中的「登陆」改为「登录」，「註冊」改为「注册」"
  }'

场景 3：代码重构

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 触发自动修复：

// 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 中：

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 - 服务管理脚本使用指南
MANUAL_APPROVAL_WORKFLOW.md - 人工确认机制实现文档
PROJECT_LOCK_IMPLEMENTATION.md - 项目锁实现文档
TASK_QUEUE_INTEGRATION.md - 任务队列集成文档
WEBSOCKET_INTEGRATION.md - WebSocket 实时通知集成文档
DATABASE_MIGRATION.md - 数据库迁移指南
SMART_PROJECT_PREPARATION.md - 智能项目准备机制文档
TASK_CANCELLATION_IMPLEMENTATION.md - 任务取消实现文档

📄 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Claude CLI 自动修复服务

✨ 特性

核心功能

安全与监控（v2.1 新增）

任务队列（v2.2 新增）

WebSocket 实时通知（v2.3 新增）

数据库支持（v2.3 新增）

项目锁管理（v2.5 新增）

人工确认机制（v2.6 新增）

📋 前置要求

🚀 快速开始

1. 安装依赖

2. 配置环境变量

3. 启动服务

方式一：使用服务管理脚本（推荐）

方式二：直接运行

📖 API 使用说明

认证说明

1. 健康检查（增强版）

2. 性能监控指标

3. 配置信息（需要认证）

4. 项目锁统计（v2.5 新增）

5. 自动修复（完整流程）

3. 测试接口（仅 Claude 修复）

💾 任务持久化

存储位置

功能特点

查询历史任务

🌍 跨域支持（CORS）

配置方式

支持的方法

允许的请求头

🔧 工作流程

📁 项目结构

🚦 任务队列系统

队列模式

队列配置

队列监控

自动降级机制

并发控制

🔔 WebSocket 实时通知

启用 WebSocket

使用 Web 监控面板

WebSocket 连接示例

支持的消息类型

💾 数据库支持

启用数据库

迁移过程

数据库优势

数据库表结构

迁移回滚

📋 日志系统

日志配置

日志文件

日志保留策略

日志格式

查看日志

🛠️ Claude 可用工具

📢 企业微信通知

🌿 分支管理策略

分支命名规则

分支创建模式

基准分支

自动合并

使用场景

⚠️ 注意事项

🐛 故障排查

1. Claude CLI 调用失败

2. Git 操作失败

3. 企业微信通知未收到

4. 分支合并失败

📝 示例场景

场景 1：修复简单 Bug

场景 2：批量文案修改