多智能体代码追溯辩论系统 (Multi-Agent Traceability Debate System)

项目简介

本项目是一个基于多智能体辩论框架的软件需求-代码追溯关系判定系统。通过模拟辩护者、攻击者、调查员和法官四个角色的辩论过程，利用大语言模型（LLM）自动判断需求文档与代码实现之间的追溯关系，输出置信度评分并沉淀可复用的推理规则。

系统架构

┌─────────────────────────────────────────────────────────────┐
│                     输入层                                   │
│  ┌──────────┐    ┌──────────┐    ┌─────────────────────┐   │
│  │ 需求文档 │    │ 代码文件 │    │ 候选追溯对(CSV)     │   │
│  └──────────┘    └──────────┘    └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   多智能体辩论引擎                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ 辩护者   │  │ 攻击者   │  │ 调查员   │  │ 法官     │   │
│  │(Defender)│  │(Attacker)│  │(Invest.) │  │(Judge)   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│       ↓              ↓              ↓              ↓        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              原则进化池 (Principle Pool)             │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     输出层                                   │
│  ┌──────────┐    ┌──────────┐    ┌─────────────────────┐   │
│  │ 评分结果 │    │ 辩论记录 │    │ 评估报告(CSV)       │   │
│  └──────────┘    └──────────┘    └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

核心功能

1. 多智能体辩论流程

角色	职责
辩护者	论证需求与代码之间存在追溯关系
攻击者	质疑和反驳追溯关系的有效性
调查员	分析争议焦点，动态调取相关代码证据
法官	综合辩论内容，给出最终评分和推理规则

2. 关键机制

• 极速早停：辩护者直接认输时提前终止辩论
• 动态证据调取：调查员可请求补充相关代码文件
• 自洽性投票：灰度区间触发多温度采样，取最稳定结果
• 原则进化：每累积10条经验规则，自动提炼为结构化推理链

3. 支持的功能

• 批量处理多个CSV候选对
• 辩论记录持久化（JSON + Markdown）
• 评估指标计算（Precision、Recall、F1-Score）
• LLM调用日志记录
• 断点续传（缓存机制）

项目结构

MultiAgent/
├── asyncio-TraceabilityDebateSystem.py   # 异步多智能体主程序
├── TraceabilityDebateSystem.py           # 多智能体主程序
├── single_agent_traceability.py          # 单智能体对比实验
├── dataset_manager.py                    # 数据集管理模块
├── claude_llm_client.py                  # Claude LLM客户端
├── qwenLLMClient.py                      # Qwen LLM客户端
├── common_fun.py                         # 通用工具函数
├── prompts/                              # 提示词模板目录
│   ├── DefenderAgent-system-prompt.txt
│   ├── AttackerAgent-system-prompt.txt
│   ├── Investigator-prompt.txt
│   ├── judge-prompt.txt
│   ├── principle_summarizer_prompt.txt
│   └── single_agent_prompt.txt
└── datasets/                             # 数据集目录
    ├── eANCI/
    ├── eTour/
    ├── iTrust/
    └── ...

环境要求

• Python 3.8+
• 依赖库：
  • aiohttp (异步HTTP请求)
  • pandas (数据处理和CSV输出)
  • asyncio (并发控制)

快速开始

1. 克隆项目

git clone <repository-url>
cd MultiAgent

2. 配置LLM API密钥

编辑 claude_llm_client.py 或 qwenLLMClient.py，填入有效的API密钥：

api_key = "your-api-key-here"

3. 数据集

数据集目录结构示例：

datasets/
└── eANCI/
    ├── code/           # 代码文件目录
    ├── req/            # 需求文件目录
    ├── links.txt       # 真实追溯关系
    ├── all_req_filenames.txt
    ├── all_code_filenames.txt

4. 运行辩论系统

# 运行多智能体版本
python TraceabilityDebateSystem.py

# 运行单智能体对比版本
python single_agent_traceability.py

5. 配置参数

在主函数中调整以下参数：

DATASET_NAME = "eANCI"      # 数据集名称: eANCI, eTour, iTrust
FRAMEWORK_NAME = "FTLR"     # 框架名称: FTLR, LISSA
THRESHOLD = 0.4             # 判定阈值
max_concurrent = 8          # 最大并发辩论数

输出说明

辩论记录

• JSON格式：debate_{req}_VS_{code}_{timestamp}.json - 完整结构化数据
• Markdown格式：便于人工阅读的辩论过程记录

输出路径：datasets/{dataset}/{framework}_TraceLink/debate_records/

评估报告

CSV格式，包含：

• 每个候选对的预测结果和真实标签
• 整体评估指标（Precision、Recall、F1-Score）

输出路径：datasets/{dataset}/{framework}_TraceLink/evaluation_results/

原则进化记录

JSONL格式，记录每次规则凝练的输入输出

输出路径：datasets/{dataset}/{framework}_TraceLink/condense_history.json

核心类说明

TraceabilityDebateSystem

多智能体辩论系统主类

方法	说明
run_debate()	执行一对需求-代码的完整辩论
generate_debates()	批量生成辩论记录（支持并发）
evaluate_debates()	评估辩论结果
_add_principle()	添加经验规则到池子
_condense_principles()	凝练规则为推理链

DatasetManager

数据集管理类

方法	说明
load_dataset()	加载需求文件和代码文件
load_req_code_links()	加载真实追溯关系
get_tracelink_csv_files()	获取框架生成的CSV文件
load_tracelink_pairs()	加载待辩论对

扩展开发

添加新的LLM客户端

继承现有客户端模式，实现 query_llm() 方法：

class NewLLMClient:
    async def query_llm(self, prompt, system_prompt, temperature):
        # 实现API调用
        return response_text, usage_dict

自定义提示词

所有提示词模板存放在 prompts/ 目录，可根据需要修改：

• DefenderAgent-system-prompt.txt - 辩护者角色定义
• AttackerAgent-system-prompt.txt - 攻击者角色定义
• judge-prompt.txt - 法官裁决模板

实验对比

项目包含单智能体版本 single_agent_traceability.py，用于对比多智能体辩论框架的效果。两者的评估结果会分别保存在不同目录。

许可证

本项目仅可用于开源学习目的。

联系方式

如有问题或建议，请联系：shiluoyuan1995@126.com

---

引用

如果您在研究中使用了本项目，请引用：

@misc{multiagent_traceability,
  author = {Shi Luoyuan},
  title = {Multi-Agent Traceability Debate System},
  year = {2026},
  email = {shiluoyuan1995@126.com}
}