420 lines
15 KiB
Markdown
420 lines
15 KiB
Markdown
# 多 Agent 智能软件开发平台 —— 架构设计文档
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 目标
|
||
|
||
在软件工程任务场景下，构建一个**可灵活定义和编排多 Agent 的实验平台**，支持多种协作/竞争方案的快速切换与对比，最终通过系统性评测验证出性能最优的 Agent 交互方案。
|
||
|
||
### 1.2 核心研究问题（来自 GQM v2）
|
||
|
||
| 编号 | 问题 |
|
||
|------|------|
|
||
| Q1 | 多智能体是否提升了任务完成质量，并保持跨层表示一致性？ |
|
||
| Q2 | 协作是否真的有效？ |
|
||
| Q3 | 协作结构是否影响性能？ |
|
||
| Q4 | 不同交互机制（协作/竞争）如何影响探索、适应、冲突处理与系统稳定性？ |
|
||
| Q5 | 人类介入是否带来可接受的成本，并提升系统可靠性？ |
|
||
|
||
---
|
||
|
||
## 2. 系统整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 实验平台 (Platform Layer) │
|
||
│ │
|
||
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
|
||
│ │ 方案配置层 │ │ 运行调度层 │ │ 评测采集层 │ │
|
||
│ │ Scheme DSL │ │ Orchestrator│ │ Metrics │ │
|
||
│ └─────────────┘ └──────────────┘ └─────────────┘ │
|
||
│ │ │ │ │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ Agent Runtime │ │
|
||
│ │ Agent A ←→ Agent B ←→ Agent C ... │ │
|
||
│ │ ↕ (Human-in-the-loop) │ │
|
||
│ │ Human Intervention Gate │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ Task & Environment Layer │ │
|
||
│ │ SWE-bench / HumanEval / 自定义任务集 │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心模块设计
|
||
|
||
### 3.1 Agent 定义层（Agent Definition）
|
||
|
||
每个 Agent 通过配置文件（YAML / Python dataclass）定义：
|
||
|
||
```yaml
|
||
agent:
|
||
id: "dev_agent_01"
|
||
role: developer # roles: analyst | developer | tester | reviewer | human
|
||
model: claude-sonnet-4-6
|
||
system_prompt: "..."
|
||
tools:
|
||
- code_edit
|
||
- file_search
|
||
- run_tests
|
||
memory:
|
||
type: shared | private # 共享记忆 or 私有记忆
|
||
interaction_mode: cooperative | competitive
|
||
```
|
||
|
||
**例子：**
|
||
|
||
| 角色 | 职责 |
|
||
|------|------|
|
||
| Analyst（需求分析） | 解析自然语言需求，输出形式化规格 |
|
||
| Developer（开发） | 根据规格生成/修改代码 |
|
||
| Reviewer（审查） | 审查代码质量、一致性 |
|
||
| Tester（测试） | 生成测试用例，执行验证 |
|
||
| Human Gate | 人类介入检查点，可接受/驳回/修改 Agent 输出 |
|
||
|
||
### 3.2 方案编排层（Scheme Orchestrator）
|
||
|
||
支持通过配置描述 Agent 之间的拓扑与交互方式：
|
||
|
||
```yaml
|
||
scheme:
|
||
name: "requirements-dev-human-test"
|
||
topology: pipeline # pipeline | star | debate | parallel
|
||
steps:
|
||
- agent: analyst
|
||
input: raw_requirement
|
||
output: formal_spec
|
||
- agent: developer
|
||
input: formal_spec
|
||
output: code_patch
|
||
- agent: human_gate
|
||
trigger: always # always | on_failure | on_low_confidence
|
||
actions: [approve, reject, modify]
|
||
- agent: tester
|
||
input: code_patch
|
||
output: test_result
|
||
```
|
||
|
||
**支持的拓扑结构：**
|
||
|
||
- `pipeline`：线性流水线，每步输出作为下步输入
|
||
- `star`：中心协调者分发任务给多个 worker agent
|
||
- `debate`：多 agent 对同一问题给出方案并投票/仲裁
|
||
- `parallel`：多 agent 并行执行后 merge
|
||
- `graph`：任意有向图
|
||
|
||
### 3.3 运行时引擎（Agent Runtime）
|
||
|
||
负责：
|
||
- Agent 实例化与生命周期管理
|
||
- 消息路由（Agent 间通信）
|
||
- 工具执行（代码运行、文件操作、测试调用）
|
||
- 全程日志采集（供评测层使用）
|
||
|
||
```
|
||
Task Input
|
||
│
|
||
▼
|
||
Orchestrator.run(scheme, task)
|
||
│
|
||
├── spawn agents
|
||
├── route messages per topology
|
||
├── invoke tools
|
||
├── check human gate (if configured)
|
||
└── collect metrics at each step
|
||
│
|
||
▼
|
||
Task Output + Metrics Log
|
||
```
|
||
|
||
### 3.4 Agent 间通信机制（MessageBus）
|
||
|
||
**拓扑决定路由规则，不决定通信接口。** Agent 只调用 `send` / `receive`，由 Orchestrator 持有路由表按拓扑转发，Agent 本身不感知自己处于哪种拓扑。
|
||
|
||
#### 统一消息结构
|
||
|
||
```python
|
||
@dataclass
|
||
class Message:
|
||
id: str
|
||
from_agent: str
|
||
to_agent: str # 单播；广播由 Orchestrator 展开为多条单播
|
||
msg_type: str # task | result | critique | approval | human_input
|
||
content: str
|
||
metadata: dict # round, confidence, milestone 等附加信息
|
||
```
|
||
|
||
#### MessageBus 实现
|
||
|
||
每个 Agent 拥有独立的 inbox 队列，Orchestrator 负责将消息投递到正确的队列：
|
||
|
||
```python
|
||
class MessageBus:
|
||
def __init__(self):
|
||
self.queues: dict[str, asyncio.Queue] = {}
|
||
|
||
async def send(self, msg: Message):
|
||
await self.queues[msg.to_agent].put(msg)
|
||
|
||
async def receive(self, agent_id: str) -> Message:
|
||
return await self.queues[agent_id].get()
|
||
```
|
||
|
||
#### 不同拓扑下的路由规则
|
||
|
||
拓扑的差异只体现在 Orchestrator 如何填写 `to_agent`，消息格式和队列机制完全相同：
|
||
|
||
| 拓扑 | 路由规则 |
|
||
|------|---------|
|
||
| pipeline | 按顺序转发，to_agent 固定为下一个节点 |
|
||
| star | Coordinator 广播任务给所有 worker；收集全部 result 后合并 |
|
||
| debate | 每轮将所有 Agent 的输出广播给其他所有 Agent |
|
||
| parallel | Orchestrator 同时广播，等 all result 到齐后 merge |
|
||
|
||
#### Human Gate 作为特殊 Agent
|
||
|
||
Human Gate 实现与普通 Agent 完全相同的 `receive` / `send` 接口，内部不调用 LLM，而是阻塞等待人类输入：
|
||
|
||
```python
|
||
class HumanGateAgent:
|
||
async def run(self, msg: Message) -> Message:
|
||
if not self.should_trigger(msg): # 触发条件由 Orchestrator 在路由时判断
|
||
return Message(msg_type="approval", content="auto_approved")
|
||
|
||
display(msg.content) # 展示给人类（CLI 或 Web UI）
|
||
action, feedback = await self.wait_for_human_input() # 阻塞等待
|
||
return Message(msg_type=action, content=feedback)
|
||
```
|
||
|
||
触发条件判断在 Orchestrator 路由层完成——不满足则跳过 Human Gate 节点，满足才投递消息到其 inbox。这样 Human Gate 可以插入任意拓扑的任意位置，不影响其他 Agent 的通信逻辑。
|
||
|
||
### 3.5 评测采集层（Metrics Collector）
|
||
|
||
自动从运行日志中计算 GQM 定义的 23 项指标：
|
||
|
||
**Q1 质量指标：**
|
||
- M1: Task Success Rate（SWE-bench）
|
||
- M2: Code Correctness pass@k（HumanEval）
|
||
- M3: Requirement Formalization Consistency（TVR tuple-level F1 + CPR）
|
||
- M4: Verification Alignment（STC + ABC）?
|
||
- M5: Implementation Alignment（Recall/Precision on changed files）
|
||
|
||
**Q2 协作有效性：**
|
||
- M6: Milestone KPI = n_j / M
|
||
- M7: Communication Score（LLM-as-a-judge，0-5）
|
||
- M8: Planning Score（LLM-as-a-judge，0-5）
|
||
- M9: Collaboration Efficiency = 任务成功 / CoordinationCost
|
||
|
||
**Q3 拓扑结构：**
|
||
- M10: Topology Efficiency（各拓扑成功率对比）
|
||
- M11: Convergence Speed（首次成功平均轮数）
|
||
- M12: Scalability（不同 agent 数量下的性能变化 SG）
|
||
- M13: Structural Coordination Cost（Redundancy + Latency + Cost）
|
||
|
||
**Q4 交互机制：**
|
||
- M14: Competitive Success Rate
|
||
- M15: Strategy Adaptation（ESA）
|
||
- M16: Conflict Resolution Rate（CRR）
|
||
- M17: Mechanism Gap（协作 vs 竞争性能差）
|
||
- M18: Stability（Var(performance)）
|
||
- M19: Robustness（Drop 值）
|
||
|
||
**Q5 人类介入：**
|
||
- M20: Human Intervention Frequency（HIF）
|
||
- M21: Human Time Cost（HTC）
|
||
- M22: Human Edit Ratio（HER）
|
||
- M23: Acceptance Rate（AR + ValueRate）
|
||
|
||
---
|
||
|
||
## 4. 协作方案设计
|
||
|
||
### 方案 A：需求→开发→人工→测试 Pipeline
|
||
|
||
```
|
||
需求输入 → [Analyst] → 形式化规格
|
||
→ [Developer] → 代码补丁
|
||
→ [Human Gate] → 审核/修改
|
||
→ [Tester] → 测试结果 → 循环或完成
|
||
```
|
||
|
||
特点：人类介入在开发之后，可在最关键的代码产出环节把关。
|
||
|
||
### 方案 B：多 Developer 竞争 + Reviewer 仲裁
|
||
|
||
```
|
||
需求输入 → [Analyst]
|
||
→ [Developer×N] 并行生成 N 个方案
|
||
→ [Reviewer] 评分选优 or 融合
|
||
→ [Tester] → 验证
|
||
```
|
||
|
||
对应 M14（竞争成功率）、M17（机制差距）研究。
|
||
|
||
### 方案 C：Debate 迭代精炼
|
||
|
||
```
|
||
需求输入 → [Analyst]
|
||
→ [Developer] 初版 → [Reviewer] 批评
|
||
→ [Developer] 修改 → [Reviewer] 再批评
|
||
→ ... （多轮）
|
||
→ [Human Gate]（可选）→ [Tester]
|
||
```
|
||
|
||
对应 M11（收敛速度）、M15（策略适应）研究。
|
||
|
||
### 方案 D：星型（Star）中心协调
|
||
|
||
```
|
||
需求输入 → [Coordinator]
|
||
├→ [Dev-Frontend]
|
||
├→ [Dev-Backend]
|
||
└→ [Dev-Database]
|
||
→ Coordinator 合并 → [Tester]
|
||
```
|
||
|
||
对应 M10（拓扑效率）、M12（规模扩展性）研究。
|
||
|
||
### 方案 E：单 Agent 基线
|
||
|
||
```
|
||
需求输入 → [Single LLM Agent] → 代码 → [Tester]
|
||
```
|
||
|
||
作为对照组（baseline），与所有多 agent 方案对比。
|
||
|
||
---
|
||
|
||
## 5. 数据输入与指标采集实现
|
||
|
||
### 5.1 统一任务输入格式（TaskInput）
|
||
|
||
不同数据集在加载时统一转换为同一结构，Agent 只看到 `TaskInput`，不感知数据集来源：
|
||
|
||
```python
|
||
@dataclass
|
||
class TaskInput:
|
||
task_id: str # 唯一标识，如 "HumanEval/42" 或 "MBPP/301"
|
||
description: str # 自然语言问题描述（作为 Agent 的输入）
|
||
source: str # "humaneval" | "mbpp"
|
||
```
|
||
|
||
### 5.2 数据集加载器
|
||
|
||
```python
|
||
# HumanEval：从 openai/human-eval 官方格式加载
|
||
class HumanEvalLoader:
|
||
def load(self) -> list[TaskInput]:
|
||
# 读取 HumanEval.jsonl
|
||
# 字段映射：prompt→description, entry_point→entry_point, test→tests
|
||
...
|
||
|
||
# MBPP：从 google-research/mbpp 官方格式加载
|
||
class MBPPLoader:
|
||
def load(self, split="test") -> list[TaskInput]:
|
||
# 读取 mbpp.jsonl，split=test 取 500 题
|
||
# 字段映射：text→description, test_list→tests（3条）
|
||
...
|
||
```
|
||
|
||
### 5.3 代码执行沙箱
|
||
|
||
Agent 生成的代码需在隔离环境中执行，避免副作用：
|
||
|
||
```
|
||
生成代码
|
||
│
|
||
▼
|
||
SandboxRunner
|
||
├── 写入临时文件
|
||
├── docker run --rm --network none --memory 256m
|
||
│ python -c "执行代码 + 测试"
|
||
├── 捕获 stdout / stderr / exitcode
|
||
└── 返回 ExecutionResult(passed, error, runtime_ms)
|
||
```
|
||
|
||
**pass@k 计算：** 对同一题目生成 n 个候选解，记录通过数 c，按公式计算：
|
||
|
||
```
|
||
pass@k = 1 - C(n-c, k) / C(n, k)
|
||
```
|
||
|
||
对于单 agent 方案（每题只输出 1 个解）直接报 pass@1；多 agent / debate 方案天然产生多个候选，可报 pass@k（k=1,3,5）。
|
||
|
||
### 5.4 运行日志结构（EventLog）
|
||
|
||
运行时引擎在每个关键节点写入结构化事件，是所有指标的数据来源：
|
||
|
||
```jsonc
|
||
{
|
||
"task_id": "MBPP/301",
|
||
"scheme": "debate",
|
||
"round": 2,
|
||
"event": "agent_output", // agent_output | tool_call | human_action | test_result
|
||
"agent_id": "developer_01",
|
||
"timestamp": 1713500000.123,
|
||
"tokens_in": 512,
|
||
"tokens_out": 384,
|
||
"content": "...", // Agent 输出文本 / 代码
|
||
"metadata": {
|
||
"confidence": 0.82, // Agent 自评置信度（用于 on_low_confidence 触发）
|
||
"milestone": "code_generated" // 里程碑标记，用于 M6 KPI 计算
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.5 指标采集流水线（MetricsCollector）
|
||
|
||
实验结束后，从 EventLog 批量计算各项指标：
|
||
|
||
```
|
||
EventLog（JSONL 文件）
|
||
│
|
||
▼
|
||
MetricsCollector.compute(log_path, task_results)
|
||
│
|
||
├── pass@k ← 从 ExecutionResult 汇总
|
||
├── M6 KPI ← 统计各 agent 参与的 milestone 数
|
||
├── M7 CScore ← 抽样消息 → LLM-as-a-judge 评分（0-5）
|
||
├── M8 PScore ← 同上，针对规划消息
|
||
├── M9 CollabEff ← pass@1 / CoordinationCost
|
||
│ CoordinationCost = α·msg数 + β·tokens + γ·API调用数 + δ·时间
|
||
├── M11 CS ← 每题首次通过时的 round 数均值
|
||
├── M12 SG ← 跨实验对比（agent 数量 1/3/5/7 的 pass@1 变化率）
|
||
├── M13 Cost ← 汇总 tokens + API calls + 总时长
|
||
├── M18 Stability ← 同一方案多次运行的 Var(pass@1)
|
||
└── M20-M23 ← 从 human_action 事件统计 HIF / HTC / HER / AR
|
||
│
|
||
▼
|
||
metrics.json（每次实验一份，写入 SQLite 汇总表）
|
||
```
|
||
|
||
**LLM-as-a-judge 实现（M7/M8）：**
|
||
从 EventLog 中提取 Agent 间消息，批量发送给裁判 LLM（与实验用 LLM 隔离，避免自评偏差），按评分 rubric 返回 0-5 分。为控制成本，每次实验对消息随机抽样 20% 打分。
|
||
|
||
### 5.6 数据集规格
|
||
|
||
| 数据集 | 规模 | 用途 | 对应指标 |
|
||
|--------|------|------|----------|
|
||
| HumanEval（OpenAI 2021） | 164 题 | 函数级代码生成，对标 SOTA | M2 pass@k、M1 |
|
||
| MBPP（Google 2021） | 500 题（test split） | 每题 3 条单元测试，题量充足支撑 ablation | M2 pass@k、M1 |
|
||
|
||
---
|
||
|
||
## 6. 技术选型
|
||
|
||
| 模块 | 选型 |
|
||
|------|------|
|
||
| Agent 框架基础 | 自研（参考 AutoGen 设计，保留最大灵活性） |
|
||
| LLM 调用 | 待定|
|
||
| 工具执行沙箱 | Docker 容器隔离 |
|
||
| 消息传递 | 内存队列（单机）|
|
||
| 指标存储 | SQLite（实验记录）+ JSON log |
|
||
| 评测脚本 | Python，对接 SWE-bench / HumanEval 官方评测接口 |
|
||
| 可视化（可选） | cli |
|
||
|