面向代码分析与修复的低开销多智能体协作系统

作品介绍PPT和展示视频：

通过网盘分享的文件：开源操作系统创新大赛链接: https://pan.baidu.com/s/1nTLuLsliTrtSOPns_R9udA?pwd=gb7d 提取码: gb7d –来自百度网盘超级会员v5的分享

1. 项目简介

代码分析与修复往往需要连续完成程序理解、缺陷定位、方案生成、补丁执行和结果审查。单一智能体在长链路任务中容易出现职责混杂和上下文负担过重；传统多智能体方案虽然能够分工协作，但反复使用自然语言传递任务状态、中间结果和历史经验，也会带来额外的消息、Token 与解析开销。

本项目围绕这些问题，构建了一套面向 Python 代码分析与修复的低开销多智能体协作系统。系统将任务编排、代码处理和结果审查划分为相互独立的职责，并遵循“智能推理与确定性执行分离”的设计原则：智能体负责理解问题、形成判断和协同决策，确定性服务负责代码读取、补丁应用、测试执行、状态管理、记忆检索和指标记录。

在此基础上，项目引入结构化通信、非文本状态传递和 Reviewer 门控共享记忆，减少重复文本交互，使中间状态能够被程序直接消费，并让经过审查的分析经验在关联任务之间受控复用。仓库同时提供实验评测框架和 CodeFix 交互前端，覆盖从机制验证到实际操作的完整链路。

2. 核心能力

多智能体协作：由编排、代码工程和结果审查职责共同完成任务规划、代码处理与质量复核。
代码分析与修复：支持程序理解、缺陷定位、原因分析、候选补丁生成和测试验证。
低开销状态传递：使用结构化协议传递确定性信息，并通过非文本状态机制管理机器可消费的中间数据。
受控共享记忆：只有经过 Reviewer 审查的结论才能进入记忆库，并在作用域约束下供后续关联任务检索和采用。
确定性执行与审计：补丁在隔离候选副本中应用，测试、状态流转、记忆使用和运行指标均可记录和追踪。
分层对照实验：基于 QuixBugs 任务比较不同协作模式，验证通信开销、状态传递和记忆复用机制。

3. 项目组成

仓库由 OS3 实验与评测框架、CodeFix 交互前端两部分组成。前者用于运行受控实验、采集指标并验证协作机制，后者将底层能力封装为可直接使用的终端应用。两部分面向不同使用场景，但共享多智能体代码分析与修复的总体设计。

.
├── src/os3/       # OS3 运行时、协议、记忆、工作流和评测核心
├── codefix/       # CodeFix 交互式代码分析与修复前端
├── configs/       # 开发、冻结、Online 和记忆验证配置
├── data/          # 实验任务目录、固定划分及运行清单
├── scripts/       # 模型服务、健康检查和实验执行脚本
└── tests/         # OS3 功能与实验边界回归测试

CodeFix 的交互命令、协作模式和内部运行机制见 codefix/README.md。

4. 快速开始

4.1 使用 CodeFix

如果希望直接体验代码分析与修复功能，可先创建独立的 Python 3.12 环境：

cd codefix
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

确认 config/models.yml 指向可用的 OpenAI 兼容模型服务后，启动 CodeFix：

./codefix

CodeFix 支持自然语言任务、代码粘贴、@文件 引用和工作区切换。所有候选修改均在隔离副本中完成，最终结果会展示补丁差异和验证结论，不会直接覆盖原始工作区。

如需在本机启动 vLLM，可在另一个终端执行：

cd codefix
export CODEFIX_ENV_PREFIX="$PWD/.venv"
export CODEFIX_MODEL_PATH="$PWD/models/qwen-coder-flash"
export CUDA_VISIBLE_DEVICES=0,1
./run_vllm.sh

4.2 运行 OS3 实验

OS3 实验框架使用 Python 3.11。推荐通过 Conda 创建可复现环境：

conda env create -f environment.yml
conda activate os3
python -m pip install -e .
cp .env.example .env

根据本机环境完成 .env 配置后，依次启动服务、检查接口并运行实验：

bash scripts/start_vllm.sh
bash scripts/healthcheck_vllm.sh
bash scripts/run_experiment.sh
bash scripts/stop_vllm.sh

5. 配置说明

项目不在代码中固化模型目录、数据集目录或访问凭据。本地资源通过环境变量和配置文件注入，便于在不同机器及 openEuler 环境中部署。

使用范围	配置入口	说明
OS3 实验框架	根目录 `.env`	配置模型服务、模型资产和数据集位置，可从 `.env.example` 创建
CodeFix 前端	`codefix/config/models.yml`	配置模型名称、兼容 OpenAI 协议的服务地址及运行限制
CodeFix 启动脚本	`CODEFIX_*` 环境变量	覆盖 Python、环境目录、模型目录、vLLM 程序和服务端口
GPU 运行环境	`CUDA_VISIBLE_DEVICES`	指定本地模型服务可见的 GPU

CodeFix 常用环境变量包括 CODEFIX_PYTHON、CODEFIX_ENV_PREFIX、CODEFIX_MODEL_PATH、CODEFIX_VLLM_BIN 和 CODEFIX_VLLM_PORT。.env、真实密钥和本机专用路径仅应保存在本地，不应提交到仓库。

6. 验证与测试

项目测试分为两层：不依赖模型服务的单元与回归测试用于验证协议、工具、调度和安全边界；接口、链路及正式实验用于验证真实模型条件下的完整运行过程。

运行 OS3 测试：

pytest -q

运行 CodeFix 测试：

cd codefix
pytest -q tests

执行接口、链路或实验测试前，应先确认模型服务地址、模型名称和当前配置一致。正式实验使用固定任务、配置和运行标识保存工件，避免将不同运行结果续接或合并。

7. 模型与数据

模型权重体积较大，不随代码仓库发布。CodeFix 默认从 codefix/models/ 查找本地模型，也可以通过 CODEFIX_MODEL_PATH 或 config/models.yml 指向其他本地模型及兼容服务；OS3 使用的模型和数据集位置由根目录 .env 定义。

仓库中的 codefix/datasets/QuixBugs/ 用于缺陷分析、代码修复和对照验证，并保留其原始许可证与来源说明。实验运行时会隔离评估专用内容，避免正确答案进入智能体工作区。