# 上级顾问 MCP (Aurai Advisor) - 开发文档
> **版本**: v2.1 | **完成度**: 100% | **更新日期**: 2026-01-21
**面向**: 开发者、接手项目的下一任 AI
---
## 📖 目录
1. [项目架构](#1-项目架构)
2. [核心模块](#2-核心模块)
3. [测试框架](#3-测试框架)
4. [部署指南](#4-部署指南)
5. [技术债务与未来](#5-技术债务与未来)
---
## 1. 项目架构
### 1.1 技术栈
**核心依赖**:
```toml
[project]
dependencies = [
"fastmcp>=0.1.0", # MCP 服务器框架
"pydantic>=2.0.0", # 数据验证
"python-dotenv>=1.0.0", # 环境变量
]
[project.optional-dependencies]
zhipu = ["zhipuai>=2.0.0"] # 智谱 AI
openai = ["openai>=1.0.0"] # OpenAI
anthropic = ["anthropic>=0.40.0"] # Claude
gemini = ["google-generativeai>=0.8.0"] # Gemini
gui = ["tkinter"] # Windows GUI
all-dev = [
"pytest>=8.0.0", # 测试框架
"pytest-asyncio>=0.24.0", # 异步测试
"pytest-cov>=5.0.0", # 测试覆盖率
]
```
**系统架构图**:
```
┌─────────────────────────────────────┐
│ Claude Code │
│ (MCP Client) │
└──────────────┬──────────────────────┘
│ stdio
▼
┌─────────────────────────────────────┐
│ MCP Server (FastMCP) │
│ ┌──────────────────────────────┐ │
│ │ 4 Tools: │ │
│ │ - consult_aurai │ │
│ │ - sync_context │ │
│ │ - report_progress │ │
│ │ - get_status │ │
│ └──────────────────────────────┘ │
│ │
│ 对话历史: 内存 + 文件持久化 │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ AI Client (5 Providers) │
│ ┌──────────────────────────────┐ │
│ │ zhipu / openai / anthropic │ │
│ │ / gemini / custom │ │
│ └──────────────────────────────┘ │
│ │
│ 功能: │
│ - 动态模型获取 │
│ - 聊天请求 │
│ - 超时保护 │
└──────────────┬──────────────────────┘
│ HTTP
▼
┌─────────────────────────────────────┐
│ AI Provider APIs │
└─────────────────────────────────────┘
```
### 1.2 项目结构
```
C:\Users\29493\Desktop\mcp-aurai-server/
├── src/mcp_aurai/ # 源代码
│ ├── server.py # MCP 服务器 (557 行)
│ ├── llm.py # AI 客户端 (557 行)
│ ├── config.py # 配置管理 (152 行)
│ ├── prompts.py # 提示词模板 (181 行)
│ └── __init__.py
│
├── tests/ # 测试
│ ├── test_config.py # 配置测试 (171 行)
│ ├── test_llm.py # 客户端测试 (171 行)
│ └── test_custom_api.py # 自定义 API 测试
│
├── tools/ # 工具
│ └── config_gui.py # GUI 配置工具 (620 行)
│
├── scripts/ # 脚本
│ ├── backup_project.py # Python 备份 (102 行)
│ └── run_backup.bat # 启动器
│
├── docs/ # 文档
│ ├── 用户手册.md # 用户指南
│ ├── 开发文档.md # 本文件
│ └── README.md # 项目说明
│
├── pyproject.toml # 项目配置
├── .env.example # 环境变量示例
└── README.md # 主文档
```
### 1.3 数据流
**consult_aurai 完整流程**:
```
1. Claude Code 调用工具
↓
2. MCP Server 接收请求
↓
3. 从内存获取最近 5 轮历史
↓
4. 构建提示词 (prompts.build_consult_prompt)
↓
5. 调用 AI Client.chat()
↓
6. 根据提供商路由到对应方法
├─► zhipu → _chat_zhipu()
├─► openai → _chat_openai()
├─► anthropic → _chat_anthropic()
├─► gemini → _chat_gemini()
└─► custom → _chat_custom()
↓
7. 发送 HTTP 请求到 AI API (超时: 30s 连接, 60s 读取)
↓
8. 清理响应内容 (_clean_response)
↓
9. 解析 JSON 返回结果
↓
10. 添加到对话历史
↓
11. 保存到文件 (_save_history_to_file)
↓
12. 返回结果给 Claude Code
```
**对话历史持久化**:
```
写入流程:
每次 consult_aurai 调用后
↓
添加到内存列表 (_conversation_history.append)
↓
检查历史数量 (超过 50 则删除最早的)
↓
序列化为 JSON (json.dumps)
↓
写入文件 (open(path, 'w'))
读取流程:
MCP Server 启动时
↓
检查历史文件是否存在
↓
存在 → 读取并解析 JSON (json.load)
↓
加载到内存 (_conversation_history = data)
↓
不存在 → 创建空历史
```
---
## 2. 核心模块
### 2.1 MCP 服务器 (`server.py`)
**核心类和函数**:
```python
# 全局变量
mcp = FastMCP("上级顾问")
client = None
_conversation_history = []
config = get_aurai_config()
# 核心工具
@mcp.tool()
async def consult_aurai(
problem_type: str,
error_message: str,
code_snippet: str | None,
context: dict | None,
attempts_made: str | None,
is_new_question: bool = False, # v2.1 新增：新问题检测
) -> dict[str, Any]:
"""请求上级 AI 指导
新增功能（v2.1）:
- is_new_question: 下级AI可显式标注新问题，清空历史
- 自动检测: 当resolved=true时自动清空历史
- 历史限制: 通过AURAI_MAX_HISTORY控制最大保存数
"""
@mcp.tool()
async def sync_context(
operation: str,
files: list[str] | None,
project_info: dict | None,
) -> dict[str, Any]:
"""同步代码上下文"""
@mcp.tool()
async def report_progress(
actions_taken: str,
result: str,
new_error: str | None,
feedback: str | None,
) -> dict[str, Any]:
"""报告执行进度"""
@mcp.tool()
async def get_status() -> dict[str, Any]:
"""获取当前状态"""
# 历史管理
def _load_history_from_file():
"""启动时加载历史"""
def _save_history_to_file():
"""保存历史到文件"""
def _get_history(count: int = 5) -> list:
"""获取最近 N 轮对话"""
def _add_to_history(entry: dict):
"""添加新对话到历史"""
```
**关键代码位置**:
- MCP 工具定义: 第 120-342 行
- 新问题检测: 第 240-265 行（自动+手动清空逻辑）
- 历史管理: 第 33-44 行（内存），50-90 行（文件加载），92-118 行（文件保存）
### 2.2 AI 客户端 (`llm.py`)
**核心类**:
```python
class AuraiClient:
def __init__(self, provider: str | None = None):
"""初始化 AI 客户端"""
self.provider = provider or config.provider
self.config = get_aurai_config()
# 根据提供商初始化
if self.provider == "zhipu":
self._init_zhipu()
elif self.provider == "openai":
self._init_openai()
elif self.provider == "anthropic":
self._init_anthropic()
elif self.provider == "gemini":
self._init_gemini()
elif self.provider == "custom":
self._init_custom()
async def chat(
self,
messages: list[dict],
system_prompt: str | None = None
) -> dict:
"""发送聊天请求"""
def get_models(
provider: str,
api_key: str,
base_url: str = ""
) -> list[str]:
"""动态获取模型列表"""
```
**提供商初始化**:
| 提供商 | 方法 | SDK | 关键代码 |
|--------|------|-----|----------|
| zhipu | `_init_zhipu()` | zhipuai | `zhipuai.ZhipuAI(api_key=api_key)` |
| openai | `_init_openai()` | openai | `openai.OpenAI(api_key=api_key)` |
| anthropic | `_init_anthropic()` | anthropic | `anthropic.Anthropic(api_key=api_key)` |
| gemini | `_init_gemini()` | google.generativeai | `genai.configure(api_key=api_key)` |
| custom | `_init_custom()` | openai | `openai.OpenAI(api_key=api_key, base_url=base_url)` |
**动态模型获取**:
```python
def get_models(provider, api_key, base_url="") -> list[str]:
"""
统一接口，动态获取模型列表
支持情况:
- zhipu: 通过 API 获取
- openai: 通过 API 获取
- custom: 通过 API 获取
- anthropic: SDK 限制，返回常用模型列表
- gemini: 通过 API 获取（过滤聊天模型）
返回示例:
- custom: ["deepseek-v3-1-250821", "gpt-4o", ...] (131 个)
- gemini: ["gemini-2.0-flash-exp", "gemini-1.5-pro", ...]
"""
```
**关键代码位置**:
- 客户端初始化: 第 28-115 行
- 动态模型获取: 第 118-267 行
- 聊天方法: 第 269-373 行
### 2.3 配置管理 (`config.py`)
**核心类**:
```python
class AuraiConfig(BaseModel):
provider: Literal["zhipu", "openai", "anthropic", "gemini", "custom"] = "zhipu"
api_key: str
base_url: str | None = None
model: str = "glm-4-flash"
max_iterations: int = 10
temperature: float = 0.7
max_tokens: int = 4096
@field_validator('api_key')
@classmethod
def validate_api_key(cls, v: str) -> str:
"""验证 API 密钥"""
if len(v) < 10:
raise ValueError("API密钥长度不能少于10个字符")
if re.search(r'[\s\n\r\t]', v):
raise ValueError("API密钥不能包含空格或控制字符")
return v
@field_validator('base_url')
@classmethod
def validate_base_url(cls, v: str | None) -> str | None:
"""验证 Base URL"""
if v and not v.startswith(('http://', 'https://')):
raise ValueError("Base URL 必须以 http:// 或 https:// 开头")
return v
class ServerConfig(BaseModel):
max_history: int = 50 # v2.1: 历史记录最大保存数
history_path: str = "~/.mcp-aurai/history.json" # v2.1: 默认用户目录
log_level: str = "INFO"
enable_persistence: bool = True # v2.1: 是否启用持久化
```
**环境变量映射**:
```python
def get_aurai_config() -> AuraiConfig:
"""从环境变量读取配置"""
return AuraiConfig(
api_key=os.getenv("AURAI_API_KEY"),
provider=os.getenv("AURAI_PROVIDER", "zhipu"),
model=os.getenv("AURAI_MODEL", "glm-4-flash"),
base_url=os.getenv("AURAI_BASE_URL"),
max_iterations=int(os.getenv("AURAI_MAX_ITERATIONS", "10")),
temperature=float(os.getenv("AURAI_TEMPERATURE", "0.7")),
max_tokens=int(os.getenv("AURAI_MAX_TOKENS", "4096")),
)
def get_server_config() -> ServerConfig:
"""从环境变量读取服务器配置"""
return ServerConfig(
max_history=int(os.getenv("AURAI_MAX_HISTORY", "50")), # v2.1
enable_persistence=os.getenv("AURAI_ENABLE_PERSISTENCE", "true").lower() == "true", # v2.1
history_path=os.getenv("AURAI_HISTORY_PATH", str(Path.home() / ".mcp-aurai" / "history.json")), # v2.1
log_level=os.getenv("AURAI_LOG_LEVEL", "INFO"),
)
```
**关键代码位置**:
- 配置类定义: 第 11-86 行
- 验证器: 第 35-62 行
- 环境变量加载: 第 89-152 行
### 2.4 提示词模板 (`prompts.py`)
**核心函数**:
```python
def build_consult_prompt(
problem_type: str,
error_message: str,
code_snippet: str | None,
context: dict | None,
history: list,
current_iteration: int,
max_iterations: int,
) -> str:
"""
构建请求上级 AI 指导的提示词
包含:
1. 系统提示词 (SYSTEM_PROMPT)
2. 问题类型和描述
3. 代码片段
4. 上下文信息
5. 已尝试的方案
6. 对话历史（最近 5 轮）
7. 当前迭代次数
"""
```
**系统提示词结构**:
```
你是一位经验丰富的编程专家，擅长分析和解决各种编程问题。
你的任务是指导本地 AI 解决遇到的编程难题。
要求:
1. 深入分析问题的根本原因
2. 提供清晰、可操作的指导建议
3. 以 JSON 格式返回结构化响应
4. 明确指出问题是否已解决，或是否需要进一步迭代
返回格式:
{
"analysis": "问题根因分析",
"guidance": "详细指导建议",
"action_items": ["步骤1", "步骤2"],
"code_changes": ["代码修改建议"],
"needs_another_iteration": false,
"resolved": true
}
```
---
## 3. 测试框架
### 3.1 测试结构
```
tests/
├── test_config.py # 配置测试 (16 个测试)
├── test_llm.py # 客户端测试 (11 个测试)
└── test_custom_api.py # 自定义 API 测试
```
**测试统计**:
- 总测试数: 27 个
- 通过率: 100% ✅
- 覆盖率: 核心模块 100%
### 3.2 配置测试 (`test_config.py`)
```python
class TestAuraiConfig:
def test_default_values(self)
def test_provider_validation(self)
def test_api_key_from_env(self, monkeypatch)
def test_custom_api_base_url(self, monkeypatch)
def test_missing_api_key_raises_error(self, monkeypatch)
def test_api_key_too_short(self)
def test_api_key_with_spaces(self)
def test_base_url_without_http(self)
def test_all_providers_valid(self)
class TestServerConfig:
def test_default_max_history(self)
def test_custom_max_history(self)
def test_history_path_default(self)
def test_custom_history_path(self, monkeypatch)
def test_log_levels(self)
def test_invalid_log_level(self)
```
**关键测试**:
- API 密钥验证（长度、空格）
- Base URL 格式验证
- 环境变量加载
- 提供商类型验证
### 3.3 客户端测试 (`test_llm.py`)
```python
class TestAuraiClient:
def test_init_with_default_provider(self, monkeypatch)
def test_init_with_custom_provider(self, monkeypatch)
def test_init_zhipu_client(self, monkeypatch)
def test_init_openai_client(self, monkeypatch)
def test_init_custom_client(self, monkeypatch)
def test_init_anthropic_client(self, monkeypatch)
def test_init_gemini_client(self, monkeypatch)
def test_get_models_for_custom_provider(self)
def test_chat_with_custom_api(self)
def test_network_timeout_configuration(self)
```
**关键测试**:
- 5 种提供商初始化
- 动态模型获取
- 实际 API 调用（custom 提供商）
- 网络超时配置
### 3.4 运行测试
```bash
# 运行所有测试
pytest tests/ -v
# 运行特定测试文件
pytest tests/test_config.py -v
# 运行特定测试函数
pytest tests/test_config.py::TestAuraiConfig::test_default_values -v
# 查看测试覆盖率
pytest tests/ --cov=src/mcp_aurai --cov-report=html
# 输出示例:
# ========== 27 passed in 2.34s ==========
```
### 3.5 测试最佳实践
**使用 pytest fixtures**:
```python
@pytest.fixture
def reset_config():
"""每个测试前重置配置"""
# 保存原始环境变量
original_env = os.environ.copy()
yield
# 恢复环境变量
os.environ.clear()
os.environ.update(original_env)
```
**使用 monkeypatch**:
```python
def test_api_key_from_env(self, monkeypatch):
monkeypatch.setenv("AURAI_API_KEY", "test-api-key-123456789")
config = AuraiConfig()
assert config.api_key == "test-api-key-123456789"
```
**异步测试**:
```python
@pytest.mark.asyncio
async def test_chat_with_custom_api(self):
client = AuraiClient(provider="custom")
result = await client.chat([{"role": "user", "content": "Hi"}])
assert "content" in result
```
---
## 4. 部署指南
### 4.1 开发环境
**系统要求**:
- Python 3.9+
- Windows 10/11（GUI 工具）
- 100 MB 磁盘空间
**安装步骤**:
```bash
# 1. 创建虚拟环境
python -m venv venv
# 2. 激活虚拟环境（Windows）
venv\Scripts\activate
# 3. 升级 pip
pip install --upgrade pip
# 4. 安装依赖
pip install -e ".[all-dev]"
# 5. 验证安装
pytest tests/ -v
```
### 4.2 生产环境
**作为 MCP 服务器运行**:
1. **配置 Claude Code**
```bash
claude mcp add aurai-advisor \
-e AURAI_API_KEY="your-api-key" \
-e AURAI_PROVIDER="custom" \
-e AURAI_BASE_URL="https://www.chatgtp.cn/v1" \
-e AURAI_MODEL="deepseek-v3-1-250821" \
-- "C:\Users\29493\Desktop\mcp-aurai-server/venv/Scripts/python.exe" -m mcp_aurai.server
```
2. **验证配置**
```bash
claude mcp list
claude mcp get aurai-advisor
```
3. **测试工具**
- 在 Claude Code 对话中直接提问
- AI 会自动调用 `consult_aurai` 工具
### 4.3 备份和恢复
**创建备份**:
```bash
# Python 备份脚本
venv\Scripts\python scripts\backup_project.py
# 备份位置: D:\backups\mcp-aurai-advisor-TIMESTAMP.zip
```
**恢复项目**:
```bash
# 1. 解压备份
unzip D:\backups\mcp-aurai-advisor-20260116.zip -d C:\Users\29493\Desktop\mcp-aurai-server
# 2. 重新创建虚拟环境
cd C:\Users\29493\Desktop\mcp-aurai-server
python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"
# 3. 恢复配置
copy .env.example .env
notepad .env
# 4. 运行测试
pytest tests/ -v
```
### 4.4 监控和日志
**日志级别**:
```bash
# 设置环境变量
set AURAI_LOG_LEVEL=DEBUG
# 运行服务器
python -m mcp_aurai.server
```
**日志重定向**:
```bash
# Windows CMD
python -m mcp_aurai.server > logs\mcp_server.log 2>&1
# PowerShell
python -m mcp_aurai.server *> logs\mcp_server.log
```
**查看日志**:
```bash
# 查看错误
findstr /C:"ERROR" logs\mcp_server.log
# 统计 API 调用
findstr /C:"api_call" logs\mcp_server.log | find /c /v ""
```
---
## 5. 技术债务与未来
### 5.1 当前状态
**完成度**: 100% ✅
**已实现**:
- ✅ 5 种 AI 提供商支持
- ✅ 动态模型获取
- ✅ 对话历史持久化
- ✅ 配置验证
- ✅ 网络超时保护
- ✅ 完整测试覆盖（27 个测试）
- ✅ GUI 配置工具
**无关键问题**:
- [OK] 无已知缺陷
- [OK] 无明显技术债务
- [OK] 无性能瓶颈
**v2.1 更新**:
- [OK] 新增 is_new_question 参数，支持手动清空对话历史
- [OK] 实现自动检测机制（resolved=true时自动清空）
- [OK] 修复对话历史传递bug（上级AI现在能看到完整历史）
- [OK] 优化 sync_context 工具（支持读取.txt和.md文件）
- [OK] 添加 AURAI_MAX_HISTORY 环境变量支持
- [OK] 改进日志和文档（移除emoji，避免终端显示问题）
### 5.2 可选增强
#### 优先级: 高
**1. 模型列表缓存**
- **问题**: 每次刷新模型都调用 API
- **方案**: 添加 TTL 缓存（1 小时）
- **预估**: 1 天
**2. 流式响应支持**
- **问题**: 需要等待完整响应
- **方案**: 实现 SSE 流式响应
- **预估**: 2-3 天
**3. CI/CD 配置**
- **问题**: 无自动化测试
- **方案**: GitHub Actions
- **预估**: 1-2 天
#### 优先级: 中
**4. 多模态支持**
- **方案**: 支持图像输入
- **预估**: 3-5 天
**5. 监控和日志**
- **方案**: 结构化日志 + 性能监控
- **预估**: 2-3 天
**6. 上下文记忆增强**
- **方案**: 跨会话持久化重要上下文
- **预估**: 2-3 天
#### 优先级: 低
**7. 插件化架构**
- **方案**: 支持动态加载提供商插件
- **预估**: 5-7 天
**8. 并发请求支持**
- **方案**: 支持同时处理多个 consult
- **预估**: 2-3 天
### 5.3 创新方向
**1. AI 能力自诊断**
- 自动评估自己的能力边界
- 智能路由到最合适的模型
**2. 跨模型协作**
- 使用多个模型协作解决问题
- 主模型 + 审核模型 + 补充模型
**3. 学习型上下文**
- 从历史对话中学习
- 自动优化提示词
### 5.4 不建议
- ❌ 微服务架构（当前规模不需要）
- ❌ 跨平台 GUI（工作量较大）
- ❌ 数据库存储（JSON 文件已足够）
---
## 附录
### A. 关键代码位置索引
| 功能 | 文件 | 行号 |
|------|------|------|
| MCP 工具定义 | server.py | 120-577 |
| 新问题检测逻辑 | server.py | 240-265 |
| consult_aurai 工具 | server.py | 120-342 |
| 历史管理（内存） | server.py | 33-44 |
| 历史管理（文件） | server.py | 50-118 |
| 配置类 | config.py | 13-168 |
| API 密钥验证 | config.py | 61-78 |
| Base URL 验证 | config.py | 80-106 |
| max_history 配置 | config.py | 119-124 |
| 客户端初始化 | llm.py | 28-115 |
| 对话历史传递 | llm.py | 127, 154-192 |
| 动态模型获取 | llm.py | 118-267 |
| 聊天方法 | llm.py | 269-373 |
| 提示词构建 | prompts.py | 28-115 |
### B. 环境变量完整列表
```bash
# 必需
AURAI_API_KEY=xxx # API 密钥
# 基础配置
AURAI_PROVIDER=zhipu # 提供商
AURAI_MODEL=glm-4-flash # 模型
AURAI_BASE_URL=https://... # Base URL
# 高级配置
AURAI_MAX_ITERATIONS=10 # 最大迭代
AURAI_TEMPERATURE=0.7 # 温度
AURAI_MAX_TOKENS=4096 # 最大 tokens
AURAI_HISTORY_PATH=xxx.json # 历史路径
AURAI_LOG_LEVEL=INFO # 日志级别
```
### C. API 接口文档
**consult_aurai**:
```python
def consult_aurai(
problem_type: str, # runtime_error/syntax_error/design_issue/other
error_message: str, # 错误描述
code_snippet: str | None, # 代码片段
context: dict | None, # 上下文
attempts_made: str | None, # 已尝试的方案
is_new_question: bool = False, # [v2.1] 是否为新问题
) -> dict:
"""返回: {analysis, guidance, action_items, code_changes, resolved, hint}"""
```
**get_models**:
```python
def get_models(
provider: str, # zhipi/openai/anthropic/gemini/custom
api_key: str, # API 密钥
base_url: str = "" # Base URL（custom 需要）
) -> list[str]:
"""返回模型列表"""
```
### D. 快速命令参考
```bash
# 安装
python -m venv venv && venv\Scripts\activate
pip install -e ".[all-dev]"
# 测试
pytest tests/ -v
pytest tests/ --cov=src/mcp_aurai
# 运行
python -m mcp_aurai.server
python tools/config_gui.py
# 备份
venv\Scripts\python scripts\backup_project.py
# 日志
set AURAI_LOG_LEVEL=DEBUG
python -m mcp_aurai.server > logs\server.log 2>&1
```
---
**版本**: v1.4 | **更新日期**: 2026-01-16 | **项目状态**: 100% 完成 ✅
**下一任 AI 接手指南**: 1. 阅读 README.md 2. 阅读 docs/用户手册.md 3. 阅读本文档 4. 运行 tests/ 验证环境 5. 开始开发
