# A2A 平台建设计划

> 基于 ADK + MCP 的主从式智能体平台
> 主控：CodeBuddy ｜ 第一个子 Agent：全栈代码开发辅助

---

## 一、项目背景与目标

### 1.1 背景
- 使用 ADK (Agent Development Kit) 搭建子智能体
- 通过 LiteLlm 连接第三方 vLLM 端点：`https://9router.aqroid.cn/v1`
- 模型：`gikun1/gpt-5.6-luna`（OpenAI 兼容接口）
- **CodeBuddy 作为主控**，用户通过 CodeBuddy 调度子 agent 完成任务

### 1.2 目标
搭建主从式 A2A (Agent-to-Agent) 平台，支持：
- 用户只跟 CodeBuddy 交互，由 CodeBuddy 调度子 agent 执行具体任务
- 子 agent 通过 MCP HTTP 接口对外提供服务
- 异步任务模式，支持长时任务执行
- 可扩展多个子 agent（开发、测试、审查、运维等）

### 1.3 典型工作流

```
1. 用户向 CodeBuddy 描述需求（"给项目加个用户管理模块"）
2. CodeBuddy 拆解任务，制定方案
3. 用户确认方案
4. CodeBuddy 通过 MCP 调用子 Dev Agent 执行具体开发
5. CodeBuddy 轮询任务进度，阶段性反馈给用户
6. 子 agent 完成后，CodeBuddy 验收质量
7. 有问题 → CodeBuddy 提修改意见 → 子 agent 修改
8. 没问题 → 汇总结果给用户
```

---

## 二、架构总览

```
┌──────────────┐
│     用户      │
└──────┬───────┘
       │ 自然语言交互
       ▼
┌─────────────────────────────────────────────────┐
│            CodeBuddy（主控）                      │
│  • 理解需求                                       │
│  • 拆解任务 & 制定方案                             │
│  • 调度子 agent                                   │
│  • 质量验收 & 结果汇总                             │
└───────────┬──────────────────┬──────────────────┘
            │ MCP HTTP 调用     │ MCP HTTP 调用
            ▼                   ▼
┌──────────────────┐  ┌──────────────────┐
│  Dev Agent       │  │  Test Agent      │  ...更多子 agent
│  (全栈代码开发)   │  │  (测试编写执行)   │
│  - ADK + LiteLlm │  │  - ADK + LiteLlm │
│  - MCP Server    │  │  - MCP Server    │
└────────┬─────────┘  └────────┬─────────┘
         │ 内部工具              │ 内部工具
         ▼                       ▼
    ┌─────────┐            ┌─────────┐
    │ 文件系统 │            │  终端   │
    │  Git    │            │ 构建命令 │
    └─────────┘            └─────────┘
```

---

## 三、阶段规划

### 阶段一：加固代码辅助 Agent ✅

**目标：** 让 Dev Agent 具备完整的全栈代码开发能力（内部能力建设）

#### 1.1 接入文件系统工具 ✅
- 使用 `@modelcontextprotocol/server-filesystem`（Node.js MCP server）
- 能力：读取文件、写入文件、列出目录、搜索文件
- 配置：`StdioConnectionParams` + 30s 超时

#### 1.2 接入终端命令执行工具 ✅
- 实现方式：Python 原生 `FunctionTool` + `asyncio.create_subprocess_shell`
- 最初尝试 MCP server 但 Windows 下通信不稳定，改为直接函数工具
- 能力：执行 shell 命令（编译、构建、测试等），支持超时控制和输出截断

#### 1.3 优化 Agent 指令与角色 ✅
- 明确身份：全栈开发子 Agent，接受 CodeBuddy 调度
- 四大模块：工作流程 / 工作边界 / 编译构建守则 / 报告格式
- 上报机制：架构决策、依赖不兼容、环境问题、能力范围外
- 保护机制：连续修复 3 次仍失败则上报

**涉及文件：**
```
my_agent/
├── agent.py          # Dev Agent 主文件
├── .env              # 环境配置
└── __init__.py
mcp_tools/
└── command_executor/  # （备用，当前未使用）
    └── server.py
```

---

### 阶段二：Dev Agent 暴露为 MCP Server（HTTP/SSE）

**目标：** 将 Dev Agent 包装为 MCP 服务器，CodeBuddy 可通过 HTTP 调用

#### 2.1 MCP Server（SSE 模式）
- 使用 `mcp` Python SDK 的 SSE server
- 通信协议：HTTP + Server-Sent Events
- 端口：可配置（默认 8001）

#### 2.2 异步任务接口
暴露以下 MCP 工具：

| 工具名 | 描述 | 参数 |
|--------|------|------|
| `submit_task` | 提交开发任务 | `description: str`, `project_path: str`, `requirements?: str` |
| `get_task_status` | 查询任务状态 | `task_id: str` |
| `get_task_result` | 获取任务结果 | `task_id: str` |
| `get_task_log` | 获取任务执行日志 | `task_id: str` |
| `cancel_task` | 取消任务 | `task_id: str` |
| `list_tasks` | 列出任务列表 | `status?: str` |

任务状态流转：`pending` → `running` → `completed` / `failed`

#### 2.3 任务管理器
- 内存中的任务队列（支持并发）
- 任务日志持久化（文件存储）
- 任务结果结构化返回

#### 2.4 CodeBuddy 接入验证
- CodeBuddy 配置 MCP 客户端连接 Dev Agent
- 验证：提交任务 → 轮询进度 → 获取结果 → 验收

**涉及文件：**
```
mcp_server/
├── __init__.py
├── server.py           # MCP SSE server 主入口
├── task_manager.py     # 异步任务管理器
├── agent_runner.py     # 封装 ADK agent 调用
└── task_store.py       # 任务持久化存储
```

---

### 阶段三：完善协作流程

**目标：** 优化 CodeBuddy 与子 agent 的协作效率

#### 3.1 任务描述规范
- 定义标准化的任务提交格式
- 包含：需求描述、项目路径、技术约束、验收标准

#### 3.2 增量修改支持
- 支持基于已有修改继续迭代（CodeBuddy 提修改意见 → agent 修改）
- 任务关联与版本管理

#### 3.3 错误处理与重试
- 子 agent 失败时的错误报告格式
- CodeBuddy 端的重试策略

---

### 阶段四：扩展更多子 Agent（远期）

| Agent | 职责 | 主要工具 |
|-------|------|----------|
| Dev Agent | 全栈代码开发 | 文件系统、终端、Git |
| Test Agent | 测试编写与执行 | 终端、覆盖率工具 |
| Review Agent | 代码审查 | 文件系统、静态分析 |
| DevOps Agent | 部署与运维 | 云平台、CI/CD |

---

## 四、技术栈

| 层级 | 技术 |
|------|------|
| 主控 | CodeBuddy（对话式调度） |
| 子 Agent 框架 | Google ADK (Python) |
| LLM 接入 | LiteLlm → vLLM 兼容端点 |
| MCP | `mcp` Python SDK（官方） |
| Agent 内部工具 | 文件系统 MCP Server + Python 原生 FunctionTool |
| 任务存储 | 本地 JSON 文件（初期） |
| 通信协议 | HTTP/SSE (MCP) |

---

## 五、实施路线

| 阶段 | 内容 | 状态 |
|------|------|------|
| 阶段一 | Dev Agent + 文件系统 + 终端工具 | ✅ 完成 |
| 阶段二 | MCP Server + 异步任务 | 🔄 进行中 |
| 阶段三 | 协作流程优化 | ⏳ 待开始 |
| 阶段四 | 扩展子 agent | ⏳ 待开始 |

---

## 六、项目结构

```
agent/
├── PLAN.md                 # 本文件
├── my_agent/               # Dev Agent
│   ├── agent.py            # Agent 定义（含文件系统 MCP + run_command 工具）
│   ├── .env                # 环境变量
│   └── __init__.py
├── mcp_server/             # MCP HTTP Server（阶段二）
│   ├── server.py           # MCP SSE server 主入口
│   ├── task_manager.py     # 异步任务管理器
│   ├── agent_runner.py     # 封装 ADK agent 调用
│   ├── task_store.py       # 任务持久化存储
│   └── __init__.py
├── mcp_tools/              # 自定义 MCP 工具（备用）
│   └── command_executor/
│       ├── server.py
│       └── __init__.py
└── .venv/                  # Python 虚拟环境
```