agent_management/agent_templates/agents/code_ai_agent/PROJECT_STRUCTURE.md

项目结构说明

📁 目录结构

Pydantic-ai/
├── src/                          # 源代码目录
│   ├── __init__.py              # 包初始化文件
│   ├── server/                  # 服务器模块
│   │   ├── __init__.py          # 导出服务器相关功能
│   │   ├── mcp_server.py        # MCP 服务器（MCP 协议）
│   │   └── api_server.py        # HTTP API 服务器（FastAPI）
│   └── client/                  # 客户端模块
│       ├── __init__.py
│       └── mcp_client.py        # MCP 客户端示例
│
├── tests/                        # 测试目录
│   ├── __init__.py
│   ├── test_agent.py             # Agent 功能测试
│   └── test_mcp_server.py       # MCP 服务器测试
│
├── docs/                         # 文档目录
│   ├── API_DOCUMENTATION.md     # API 接口文档
│   ├── DEPLOYMENT.md             # 部署指南
│   └── README_API.md             # API 快速开始
│
├── run_api_server.py             # HTTP API 服务器启动脚本
├── run_mcp_server.py             # MCP 服务器启动脚本
│
├── requirements.txt              # Python 依赖
├── Dockerfile                    # Docker 镜像配置
├── docker-compose.yml            # Docker Compose 配置
├── .dockerignore                 # Docker 构建忽略文件
├── README.md                     # 项目说明
└── PROJECT_STRUCTURE.md          # 本文件

📝 文件说明

源代码 (src/)

src/server/

• mcp_server.py: MCP 服务器实现，包含所有工具函数和 Agent 配置
• api_server.py: HTTP API 服务器，将 MCP 工具包装为 REST API

src/client/

• mcp_client.py: MCP 客户端示例，演示如何通过 MCP 协议调用服务

测试 (tests/)

• test_agent.py: 直接测试 Agent 功能
• test_mcp_server.py: 测试 MCP 服务器工具函数

文档 (docs/)

• API_DOCUMENTATION.md: 完整的 API 接口文档
• DEPLOYMENT.md: 部署指南和配置说明
• README_API.md: API 快速开始指南

启动脚本

• run_api_server.py: 启动 HTTP API 服务器的入口脚本
• run_mcp_server.py: 启动 MCP 服务器的入口脚本

🔧 导入路径

在项目内部导入

# 从服务器模块导入工具函数
from src.server.mcp_server import (
    generate_code,
    refactor_code,
    review_code,
    # ...
)

# 或者使用 __init__.py 中的导出
from src.server import (
    generate_code,
    refactor_code,
    # ...
)

在测试中导入

import sys
from pathlib import Path

# 添加项目根目录到路径
project_root = Path(__file__).parent.parent
sys.path.insert(0, str(project_root))

from src.server.mcp_server import code_assistant_agent

🚀 运行方式

本地运行

# 启动 HTTP API 服务器
python run_api_server.py

# 启动 MCP 服务器
python run_mcp_server.py

# 运行测试
python -m pytest tests/
# 或
python tests/test_agent.py

Docker 运行

# 构建镜像
docker build -t code-assistant-agent .

# 运行容器
docker run -p 8000:8000 code-assistant-agent

# 或使用 Docker Compose
docker-compose up -d

📦 模块组织原则

1. 按功能分类: 服务器、客户端、测试分别放在不同目录
2. 清晰的导入路径: 使用 src.server、src.client 等清晰的模块路径
3. 统一的入口: 使用根目录的启动脚本，方便运行
4. 文档集中: 所有文档放在 docs/ 目录

🔄 导入关系

run_api_server.py
    └─> src.server.api_server
            └─> src.server.mcp_server (工具函数)

run_mcp_server.py
    └─> src.server.mcp_server

src.client.mcp_client
    └─> (通过命令行调用) src.server.mcp_server

tests/test_*.py
    └─> src.server.mcp_server

✅ 重构完成检查清单

• 创建目录结构
• 移动文件到对应目录
• 更新所有导入语句
• 创建 __init__.py 文件
• 更新 Dockerfile 路径
• 创建启动脚本
• 更新测试文件导入
• 更新客户端文件路径引用

---

最后更新: 2025-01-08