🔄 ConvergeLoop

让 AI 一次性把任何代码项目修到商业级标准
终结"AI 修了又坏、坏了又修"的死循环

你只需要对 AI 说一句话："帮我把项目修复到完整版"，ConvergeLoop 就会自动驱动 AI 反复检查、修复、验证，直到项目真正达到可上线标准——不是 AI 自己说"修好了"，而是通过真实编译、测试、安全扫描验证过的"真完美"。

你说"修到完整版" → ConvergeLoop 分析项目 → 生成检查任务 → AI 执行修复
       ↑                                              ↓
       └── 越修越乱？自动回滚 ← 真实测试验证 ← 6级质量门控 ←┘

✨ 核心亮点

🎯 11 维度成熟度评分 — 0-100 分量化"修好了"的标准，不再靠感觉
🛡️ 7 条防欺骗铁律 — 强制找问题、突袭验证、魔鬼代言人…让 AI 不敢说假话
🔴🔵 红蓝对抗机制 — 红队（17+角色）攻击，蓝队（8类工程师）修复，交叉验证
🧪 真实执行验证 — 不是 AI 声称"测试通过"，而是真实编译 + 跑测试 + 安全扫描
🔄 收敛判定引擎 — 连续 N 轮无新问题即收敛，知道什么时候该停
⏮️ 自动回滚止损 — 越修越乱时自动回滚到最近稳定版本，不怕改坏
🤖 多 IDE 支持 — CatPaw、Trae、Cursor、Claude Desktop、Windsurf 等 8 种 IDE
🧩 零配置识别 — 自动识别项目技术栈，无需手写配置文件

🎯 解决什么问题

传统 AI 修代码的痛点：

痛点	表现	ConvergeLoop 的解法
修了又坏	AI 修好 A 模块，却弄坏了 B 模块	修复后强制真实编译+测试，坏了立即回滚
假完美	AI 说"已经完整了"，再问一次又说有问题	7 条防欺骗铁律 + 交叉验证 + 突袭检查
无标准	"修好了"到底什么标准？无法量化	11 维度成熟度评分（0-100 分），目标可设
无止境	不知道什么时候该停	收敛判定引擎：连续 N 轮无新问题即收敛
怕回滚	AI 改坏了无法恢复	Git 快照 + 原子批处理 + 退化自动回滚

适合谁用：

🔧 后端/前端开发者：在 IDE 里说一句话就修复项目
🚀 DevOps 工程师：CI/CD 集成自动化质量门控
🤖 AI 工程师：作为 MCP Server 集成到任意 IDE

🏗️ 架构总览

┌─────────────────────────────────────────────────────────────────────┐
│  第七层：商业就绪裁决层                                              │
│  11维度成熟度评分 + 6级质量门控全通过 = 商业上线 ready                 │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第六层：收敛裁决层                                                  │
│  状态指纹 + 交叉一致性 + 回归验证 + 突袭验证 + 魔鬼代言人             │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第五层：红蓝对抗层                                                  │
│  红队攻击 → 蓝队修复 → 裁判仲裁 → 止损回滚                          │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第四层：多角色矩阵层                                                │
│  红队（17+角色）发现问题 → 蓝队（8类工程师）修复问题                  │
│  每个角色独立会话，结果交叉比对，防止单一AI的确认偏误                 │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第三层：智能提示语引擎（PromptForge）                                │
│  8种对抗性模板，根据项目类型/轮次/角色/历史动态生成                   │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第二层：项目感知引擎（Project Sense）                                │
│  零配置识别：文件结构、依赖、代码特征、配置文件                       │
└─────────────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────────────┐
│  第一层：执行引擎层                                                  │
│  构建系统适配器 + Docker 沙箱 + AST 感知修复 + 修复冲突管理           │
│  → 质量门控基于真实执行结果，不是 AI 声称的结果                       │
└─────────────────────────────────────────────────────────────────────┘

📋 前置环境要求

组件	最低版本	推荐版本	说明
Python	3.10	3.12	源码运行必需
pip	23.0	最新版	安装依赖
Git	2.30	最新版	快照/回滚功能必需
Docker	24.0	最新版	安全沙箱执行（可选）

🚀 快速开始（5分钟跑起来）

第 1 步：下载代码

git clone https://gitee.com/suoten/convergeloop.git
cd ConvergeLoop

第 2 步：安装依赖

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

第 3 步：验证安装

convergeloop --help
# 应输出 CLI 帮助信息

第 4 步：在 IDE 中使用（推荐）

配置 MCP 后，在 IDE 对话中直接说：

@convergeloop 帮我把当前项目修复到完整版

💡 详细的 IDE 配置步骤见下方 IDE 集成指南

第 5 步：或通过 CLI 使用

# 分析项目
convergeloop analyze /path/to/your/project

# 一键修复
convergeloop fix /path/to/your/project --threshold 3 --max-rounds 20

💻 IDE 集成指南

ConvergeLoop 基于 MCP（Model Context Protocol） 协议，支持集成到任何 MCP 兼容的 AI IDE。以下是两种配置方式。

方式一：一键自动安装（推荐）

# 自动扫描已安装的 IDE，交互式选择配置
convergeloop install

# 安装到所有检测到的 IDE
convergeloop install --all

# 安装到指定 IDE
convergeloop install --ide trae,cursor,catpaw

方式二：手动配置

根据你使用的 IDE，找到对应的配置文件并添加 ConvergeLoop MCP Server 配置。

🐱 CatPawAI

配置文件路径：

Windows: %APPDATA%\CatPawAI\User\globalStorage\mt-idekit.mt-idekit-code\settings\mcopilot_mcp_settings.json
macOS/Linux: ~/.catpaw/globalStorage/mt-idekit.mt-idekit-code/settings/mcopilot_mcp_settings.json

配置内容：

{
  "mcpServers": {
    "convergeloop": {
      "command": "E:\\硕腾网络\\ConvergeLoop\\start_mcp.bat"
    }
  }
}

⚠️ Windows 用户请将路径替换为你的实际安装路径，注意双反斜杠 \\

🔮 Trae（中文版）

配置文件路径：

Windows: %APPDATA%\Trae\mcp.json
macOS/Linux: ~/.trae/mcp.json

配置内容：

{
  "mcpServers": {
    "convergeloop": {
      "command": "python",
      "args": ["-m", "convergeloop.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/ConvergeLoop",
        "PYTHONUTF8": "1"
      }
    }
  }
}

🌐 Trae（国际版）

配置文件路径：

Windows: %APPDATA%\TraeIntl\mcp.json
macOS/Linux: ~/.trae-intl/mcp.json

配置内容同 Trae 中文版。

🖱️ Cursor

配置文件路径：

Windows: %USERPROFILE%\.cursor\mcp.json
macOS/Linux: ~/.cursor/mcp.json

配置内容：

{
  "mcpServers": {
    "convergeloop": {
      "command": "python",
      "args": ["-m", "convergeloop.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/ConvergeLoop"
      }
    }
  }
}

🤖 Claude Desktop

配置文件路径：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

配置内容：

{
  "mcpServers": {
    "convergeloop": {
      "command": "python",
      "args": ["-m", "convergeloop.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/ConvergeLoop"
      }
    }
  }
}

🌊 Windsurf

配置文件路径：

Windows: %USERPROFILE%\.codeium\windsurf_config.json
macOS/Linux: ~/.codeium/windsurf_config.json

配置内容同 Claude Desktop。

📼 VS Code + Cline

配置文件路径：

Windows: %APPDATA%\Code\User\settings.json
macOS/Linux: ~/.vscode/settings.json

配置内容：

{
  "cline.mcpServers": {
    "convergeloop": {
      "command": "python",
      "args": ["-m", "convergeloop.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/ConvergeLoop"
      }
    }
  }
}

⚠️ VS Code + Cline 使用 cline.mcpServers 而非 mcpServers

🏗️ CodeArts Agent

配置文件路径：

Windows: %APPDATA%\CodeArts\mcp.json
macOS/Linux: ~/.codearts/mcp.json

配置内容同 Trae。

Windows 用户快捷配置（start_mcp.bat）

如果你在 Windows 上从源码运行，可以直接使用 start_mcp.bat 启动脚本，它自动检测 Python 环境并设置所有必要的环境变量：

{
  "mcpServers": {
    "convergeloop": {
      "command": "E:\\path\\to\\ConvergeLoop\\start_mcp.bat"
    }
  }
}

start_mcp.bat 会自动：

定位项目根目录
检测 Python 解释器（venv > system > py launcher）
设置 PYTHONPATH、PYTHONUTF8、CL_ALLOW_SELF_FIX
启动 MCP Server

macOS / Linux 用户配置

将 start_mcp.bat 替换为直接调用 Python：

{
  "mcpServers": {
    "convergeloop": {
      "command": "python3",
      "args": ["-m", "convergeloop.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/ConvergeLoop",
        "PYTHONUTF8": "1"
      }
    }
  }
}

在 IDE 中使用

集成完成后，在 IDE 对话中输入：

@convergeloop 帮我把当前项目修复到完整版

ConvergeLoop 会自动：

📊 分析项目技术栈和风险域
🎯 生成多角色对抗性检查提示语
⏳ 等待 IDE 的 AI 执行修复
🧪 真实编译 + 测试验证修复结果
🔄 循环直到达到目标成熟度

修复目标级别：

调用方式	分数要求	适用场景
`@convergeloop 修复到正式版`	≥ 80 分	内部工具、Demo
`@convergeloop 修复到完整版`	≥ 90 分	商业产品、对外服务
`@convergeloop 修复到完美版`	≥ 95 分	金融/医疗/安全关键系统

多窗口同时使用

ConvergeLoop 支持多窗口、多项目同时运行。每个 IDE 窗口启动独立的 MCP Server 进程，通过会话级文件锁实现隔离，互不干扰。

🐳 Docker 部署

一键启动

# 准备配置
cp .env.example .env

# 构建并启动
docker compose up -d --build

# 验证服务
curl http://localhost:8080/ready
# 返回: {"status":"ready"}

挂载待分析项目

编辑 docker-compose.yml，取消注释并替换项目路径：

services:
  convergeloop:
    volumes:
      - /path/to/your/project:/workspace/project

资源限制

资源	限制值	说明
内存上限	2g	防止内存泄漏拖垮宿主机
CPU 上限	2.0 核	防止 CPU 打满影响其他服务
日志大小	10MB × 3	防止日志撑满磁盘

🔧 环境变量配置

cp .env.example .env

核心配置

变量名	含义	默认值	必填
`CONVERGELOOP_API_KEY`	API 鉴权密钥	未设置	生产必填
`CONVERGELOOP_API_HOST`	API 监听地址	`0.0.0.0`	否
`CONVERGELOOP_API_PORT`	API 监听端口	`8080`	否

AI 引擎配置（自主模式才需要，协作模式无需设置）

变量名	获取地址
`DEEPSEEK_API_KEY`	https://platform.deepseek.com/
`GLM_API_KEY`	https://open.bigmodel.cn/
`OPENAI_API_KEY`	https://platform.openai.com/
`ANTHROPIC_API_KEY`	https://console.anthropic.com/
`OLLAMA_BASE_URL`	http://localhost:11434

📦 项目结构

ConvergeLoop/
├── convergeloop/                   # 主源码包
│   ├── core/                       # 核心引擎（7层架构）
│   │   ├── adversarial_loop.py     #   对抗循环核心
│   │   ├── project_sense.py        #   项目感知引擎
│   │   ├── prompt_forge.py         #   智能提示语引擎
│   │   ├── role_matrix.py          #   角色矩阵（红队17+ + 蓝队8类）
│   │   ├── convergence_judge.py    #   收敛判定引擎
│   │   ├── maturity_scorer.py      #   11维度成熟度评分器
│   │   ├── quality_gates.py        #   6级质量门控
│   │   ├── build_adapter.py        #   构建系统适配器
│   │   ├── sandbox_manager.py      #   Docker 安全沙箱
│   │   ├── fix_applier.py          #   AST 感知修复引擎
│   │   └── rollback_manager.py     #   回滚管理器
│   ├── mcp_server.py               # MCP Server（FastMCP）
│   ├── cli.py                      # CLI 命令行入口
│   ├── installer.py                # IDE 自动检测与一键安装
│   └── server.py                   # API 服务入口
├── start_mcp.bat                   # Windows MCP 启动脚本
├── Dockerfile                      # 容器化部署
├── docker-compose.yml              # Docker Compose
├── pyproject.toml                  # Python 项目配置
└── .env.example                    # 环境变量模板

❓ 常见问题 FAQ

Q1: 安装报错 "Could not find a version"

Python 版本低于 3.10。请升级到 3.10+。

Q2: MCP Server 在 IDE 中无法连接

# 验证 MCP Server 可启动
python -m convergeloop.mcp_server --help

# 检查 IDE 配置中的 Python 路径
# 应指向虚拟环境中的 python，而非系统 python

Q3: Windows 下中文路径报错

set PYTHONUTF8=1
set PYTHONIOENCODING=utf-8

Q4: 修复过程中项目文件被误删

# ConvergeLoop 每轮修复前都会 git commit，不会丢失代码
git log --oneline -20
git reset --hard <commit-hash>

Q5: 多窗口使用报 "Connection closed"

确保使用最新版本（v1.2.0+），已修复多实例并发问题。每个窗口启动独立的 MCP Server 进程，通过会话级文件锁隔离。

Q6: 如何查看修复报告

convergeloop report <session_id>
convergeloop export <session_id> --format html --output report.html

⚙️ 高级配置

修复目标级别

MCP `target_level`	分数要求	适用场景
`release` (正式版)	≥ 80	内部工具、Demo
`commercial` (完整版)	≥ 90	商业产品、对外服务
`perfect` (完美版)	≥ 95	金融/医疗/安全关键

CLI 常用命令

convergeloop fix /path/to/project                    # 一键修复
convergeloop analyze /path/to/project                # 仅分析
convergeloop score /path/to/project                  # 评分
convergeloop sessions                                # 查看运行中会话
convergeloop report <session_id>                     # 查看报告
convergeloop resume <session_id>                     # 恢复中断的会话
convergeloop install                                 # 一键安装到 IDE

📊 能力一览

11 维度成熟度评分

维度	权重	说明
🔒 安全等级	18%	依赖漏洞、输入验证、加密、认证授权
✅ 功能完整	16%	核心功能、边界场景、错误处理
🏃 可运行性	14%	能否启动、能否跑通核心流程
📦 可部署性	10%	Dockerfile、CI/CD、部署文档
📝 代码质量	10%	Lint通过、复杂度、命名规范
🏗️ 架构健康	8%	耦合度、扩展性、单点风险
🧪 测试覆盖	8%	单元测试、集成测试、E2E
🔗 端到端可用	6%	从部署到使用的完整流程
⚡ 性能表现	4%	响应时间、并发、缓存
📖 文档完整	4%	README、API文档、CHANGELOG
🔄 DevOps就绪	2%	监控、日志、告警

7 条防欺骗铁律

铁律	机制	说明
1. 强制找问题	"找不到N个问题算失败"	打破AI讨好倾向
2. 角色随机化	每轮打乱顺序	防止AI记住套路
3. 突袭验证	未使用过的最严苛角色突然提问	检测AI是否在"演戏"
4. 负向激励	说"没问题"触发更严苛审查	让AI不敢轻易说完美
5. 可执行性检查	修复必须有具体代码	过滤空话套话
6. 魔鬼代言人	专门反驳AI的结论	打破确认偏误
7. 状态指纹	AST + 哈希检测文件是否真正修改	防止文字游戏

性能参考

项目规模	首次分析	完整修复（预估）
小型（<1万行）	2-5分钟	15-30分钟
中型（1-10万行）	10-30分钟	1-3小时
大型（10-50万行）	30-60分钟	3-8小时

📜 License

MIT License - 详见 LICENSE

ConvergeLoop — 修到真完美，不是假完美

商业就绪 = 真实执行验证 × 深度分析(8层) × 多角色博弈 × 负向提问 × 交叉验证 × 红蓝对抗 × 质量门控(6级) × 收敛判定 × 成熟度评分(11维度) × 错误学习进化

Name		Name	Last commit message	Last commit date
Latest commit History 855 Commits
.github		.github
convergeloop		convergeloop
docs		docs
scripts		scripts
tests		tests
根目录残留14个测试/日志		根目录残留14个测试/日志
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MCP_CONFIG.md		MCP_CONFIG.md
MCP_SETUP.md		MCP_SETUP.md
README.md		README.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
conftest.py		conftest.py
docker-compose.yml		docker-compose.yml
main.py		main.py
mcp-config.json		mcp-config.json
pyproject.toml		pyproject.toml
requirements.lock		requirements.lock
requirements.txt		requirements.txt
run_pytest.py		run_pytest.py
start_mcp.bat		start_mcp.bat
start_mcp.ps1		start_mcp.ps1
start_mcp.sh		start_mcp.sh

Folders and files

Latest commit

History

Repository files navigation

🔄 ConvergeLoop

✨ 核心亮点

📑 目录

🎯 解决什么问题

🏗️ 架构总览

📋 前置环境要求

🚀 快速开始（5分钟跑起来）

第 1 步：下载代码

第 2 步：安装依赖

第 3 步：验证安装

第 4 步：在 IDE 中使用（推荐）

第 5 步：或通过 CLI 使用

💻 IDE 集成指南

方式一：一键自动安装（推荐）

方式二：手动配置

🐱 CatPawAI

🔮 Trae（中文版）

🌐 Trae（国际版）

🖱️ Cursor

🤖 Claude Desktop

🌊 Windsurf

📼 VS Code + Cline

🏗️ CodeArts Agent

Windows 用户快捷配置（start_mcp.bat）

macOS / Linux 用户配置

在 IDE 中使用

多窗口同时使用

🐳 Docker 部署

一键启动

挂载待分析项目

资源限制

🔧 环境变量配置

核心配置

AI 引擎配置（自主模式才需要，协作模式无需设置）

📦 项目结构

❓ 常见问题 FAQ

Q1: 安装报错 "Could not find a version"

Q2: MCP Server 在 IDE 中无法连接

Q3: Windows 下中文路径报错

Q4: 修复过程中项目文件被误删

Q5: 多窗口使用报 "Connection closed"

Q6: 如何查看修复报告

⚙️ 高级配置

修复目标级别

CLI 常用命令

📊 能力一览

11 维度成熟度评分

7 条防欺骗铁律

性能参考

📜 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages