内容
# ⚡ Zetabot — 基于MCP的深度研究代理
<div align="center">
**Zetabot** (源自希腊语“zetesis”——探究的行为) 是一个人工智能驱动的深度研究代理，它将每一步研究视为一个模块化的MCP工具，由具有生产级上下文工程的LangGraph代理编排，以实现多步推理。
[功能](#-功能) • [架构](#-架构) • [上下文工程](#-上下文工程) • [MCP工具](#-mcp-工具清单) • [设置](#-设置) • [用法](#-用法) • [Docker](#-docker) • [阶段](#-项目阶段)
> *Zetesis (ζήτησις) — 希腊语：寻求、调查、研究的行为.*
</div>
---
## ✨ 功能
| 功能 | 描述 |
|---|---|
| 🔧 **MCP原生工具** | 每个研究步骤都是一个具有严格JSON模式的独立MCP工具，位于 `manifest.json` 中 |
| 🤖 **LangGraph编排** | 状态化的4节点代理：规划器 → 工具调用者 → 内存聚合器 → 终结器 |
| 🔁 **多步推理** | 代理循环遍历计划步骤，在最多5个推理步骤中累积上下文 |
| 🧠 **上下文工程** | `ContextBuilder` 提供针对每个LLM调用的、具有预算和相关性排名的动态上下文 |
| 💾 **共享内存** | `ResearchMemory` 在步骤之间持久化搜索结果、抓取的页面、摘要和错误日志 |
| 🌐 **实时网络搜索** | Tavily API返回具有相关性评分的排名靠前的最新结果 |
| 📄 **智能抓取** | BeautifulSoup优先处理 `<main>`、`<article>` 内容，并去除广告/导航/模板 |
| ✍️ **聚焦摘要** | GPT-4o生成具有可配置焦点区域和置信度评分的事实密集型摘要 |
| 🗂️ **语义聚类** | TF-IDF + K-Means对发现结果进行分组；余弦相似度按查询相关性排名 |
| 📊 **结构化报告** | 3种输出格式：Markdown简报、比较表、洞察报告 |
| ⚡ **实时流媒体** | FastAPI SSE将工具调用、步骤和状态实时流式传输到React仪表板 |
| 🖥️ **React仪表板** | 具有轨迹查看器、统计信息和Markdown报告渲染器的深色玻璃形态UI |
| 🐳 **Docker就绪** | 完整的Docker Compose栈，支持一键部署 |
---
## 🏗️ 架构
```
┌──────────────────────────────────────────────────────────────────┐
│ React前端 (Vite) │
│ 查询输入 → SSE流 → 工具轨迹 → 统计信息 → 报告查看器 │
└───────────────────────────┬──────────────────────────────────────┘
│ HTTP POST + SSE (端口 8080)
┌───────────────────────────▼──────────────────────────────────────┐
│ FastAPI后端 (api.py) │
│ /research/stream /report/{id} /reports /health │
└───────────────────────────┬──────────────────────────────────────┘
│ Python调用
┌───────────────────────────▼──────────────────────────────────────┐
│ LangGraph代理 (agent/) │
│ │
│ ┌──────────┐ ┌─────────────┐ ┌───────────────────────┐ │
│ │ 规划器 │───▶│ 工具调用者 │───▶│ 内存聚合器 │ │
│ │ (LLM) │ │ (MCP循环) │ │ (自动摘要) │ │
│ └──────────┘ └──────┬──────┘ └──────────┬────────────┘ │
│ ↑ 循环│ │ │
│ └──────────────────┘ ▼ │
│ ┌─────────────┐ │
│ 研究内存 (跨步骤共享) │ 终结器 │ │
│ ├── 搜索结果[] │ (LLM报告)│ │
│ ├── 抓取的页面[] └─────────────┘ │
│ ├── 摘要[] + 置信度评分[] ↑ │
│ ├── 错误日志[] │ │
│ └── 工具调用日志[] 上下文构建器 (agent/context.py) │
└──────────────────────────────────────────────────────────────────┘
│ MCP客户端调度
┌───────────────────────────▼──────────────────────────────────────┐
│ MCP服务器 (mcp_server/) │
│ │
│ 🔍 搜索网络 🕷️ 抓取内容 ✍️ 摘要 │
│ 🗂️ 聚类和排名 📋 生成报告 │
└──────────────────────────────────────────────────────────────────┘
```
---
## 🧠 上下文工程
该代理的核心原则是**上下文工程**——确保每个LLM调用都获得恰到好处的信息：不多不少。这由 `agent/context.py`（`ContextBuilder`）处理，它取代了朴素的临时提示程序。
### 已解决问题
| # | 问题（之前） | 解决方案（之后） |
|---|---|---|
| 1 | 工具调用者只能看到最近抓取的页面的最后500个字符 | `build_tool_caller_context()` 注入完整的工具历史、所有找到的URL、最新的摘要预览和累积的错误 |
| 2 | 终结者接收到无边界的摘要转储（无令牌上限） | `build_finalizer_context()` 按查询重叠对摘要进行关键词评分，并在5,000令牌预算内选择前N个 |
| 3 | 所有系统提示都是静态字符串，无会话感知 | 所有节点使用动态提示，注入跳跃预算、工具列表、进度计数和战略提示 |
| 4 | `messages` 列表是只写的；无会话连续性 | 工具调用者将 `state["messages"][-4:]` 注入每个LLM调用 |
| 5 | 单个 `error: str` 字段被静默覆盖每个跳跃 | `AgentState` 中的 `errors: list[str]` 使用LangGraph减少器追加——保留完整的错误历史 |
| 6 | 无摘要的逐跳质量信号 | `confidence_scores: list[float]` 记录 alongside 每个摘要；终结者可以按置信度加权 |
### 工作原理
```
ContextBuilder(query, max_hops, max_tokens=5000)
│
├── build_planner_system_prompt(available_tools)
│ → 将MAX_HOPS + 实时工具列表注入规划器的系统消息
│
├── build_tool_caller_system_prompt(memory)
│ → 注入剩余跳跃次数、进度计数、战略提示
│ ("PRIORITIZE summarization" 当跳跃次数 ≤ 2)
│
├── build_tool_caller_context(memory)
│ → 丰富的上下文块：工具历史（最近5次跳跃，150字符预览）、
│ 所有找到的URL（避免重复）、最新摘要、错误日志
│
├── build_finalizer_system_prompt(memory)
│ → 根据数据丰富程度调整深度/角色
│ （如果 ≥8 个数据点，则全面；如果 <3，则诚实地说明差距）
│
└── build_finalizer_context(memory)
→ 按查询重叠度对摘要进行关键词评分
→ 在 5,000 字符预算内选择 top 摘要
→ 返回精选的来源块（按搜索排名前 5 名）
```
### 关键文件变更
| 文件 | 变更 |
|---|---|
| `agent/context.py` *(新增)* | `ContextBuilder` — 所有上下文组装逻辑 |
| `agent/memory.py` | 添加了 `error_log`、`confidence_scores`、`get_relevant_summaries()`、`get_top_sources()` |
| `agent/state.py` | `error: str` → `errors: Annotated[list[str], _accumulate_errors]` |
| `agent/nodes.py` | 所有4个节点使用 `ContextBuilder`；会话内存；置信度评分 |
| `api.py` | `initial_state` 使用 `errors: []`；报告存储公开 `error_log` |
| `run_agent.py` | 详细模式打印累积的错误日志 |
---
## 🔧 MCP工具清单
所有工具都在 `mcp_server/manifest.json` 中定义，包含完整的JSON模式。
| 工具 | 描述 | 关键参数 |
|---|---|---|
| `search_web` | Tavily API网络搜索 | `query`、`max_results`、`search_depth` |
| `scrape_content` | BeautifulSoup内容提取 | `url`、`max_chars` |
| `summarize` | GPT-4o聚焦摘要 | `text`、`focus`、`max_length` |
| `cluster_and_rank` | TF-IDF + K-Means + 余弦排名 | `summaries`、`query`、`num_clusters` |
| `generate_report` | 3种格式的结构化报告 | `findings`、`query`、`format` |
---
## 📁 项目结构
```
Zetabot/
│
├── mcp_server/ # FastMCP服务器
│ ├── server.py # 通过@mcp.tool()注册所有工具
│ ├── manifest.json # 工具模式（JSON模式）
│ └── tools/
│ ├── search_web.py # Tavily搜索
│ ├── scrape_content.py # BeautifulSoup抓取器
│ ├── summarize.py # OpenAI摘要器
│ ├── cluster_and_rank.py # TF-IDF + K-Means聚类
│ └── generate_report.py # 3种格式的报告生成器
│
├── agent/ # LangGraph编排
│ ├── graph.py # 带有条件路由的StateGraph
│ ├── nodes.py # 4个代理节点（上下文工程感知）
│ ├── memory.py # 研究内存：结果、摘要、错误日志、置信度评分
│ ├── context.py # ContextBuilder：预算令牌、相关性排名、动态提示
│ ├── mcp_client.py # 进程内MCP工具调度器
│ └── state.py # AgentState TypedDict（累积错误列表）
│
├── frontend/ # React + TypeScript + Vite
│ ├── src/
│ │ ├── App.tsx # 主组件（SSE + UI）
│ │ └── index.css # 设计系统（玻璃形态，暗色模式）
│ ├── Dockerfile.frontend
│ └── nginx.conf # SPA路由 + API代理
│
├── tests/
│ ├── test_tools.py # 第1阶段CLI测试运行器
│ └── test_advanced_tools.py # 第3阶段测试运行器
│
├── examples/
│ └── sample_report_llm_reasoning.md # 示例代理输出
│
├── api.py # FastAPI后端（SSE流式传输）
├── run_agent.py # CLI入口点
├── requirements.txt
├── docker-compose.yml
├── Dockerfile.api
├── .env.example
└── README.md
```
---
## 🚀 设置
### 先决条件
- Python 3.11+
- Node.js 18+（前端）
- OpenAI API密钥 → [platform.openai.com](https://platform.openai.com)
- Tavily API密钥 → [tavily.com](https://tavily.com) *(免费层可用)*
### 1. 克隆和配置
```bash
git clone https://github.com/Rishabhpm23/Zetabot.git
cd Zetabot
cp .env.example .env
# 编辑.env并添加您的API密钥
```
### 2. Python环境
```bash
python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt
```
### 3. 前端
```bash
cd frontend
npm install
cd ..
```
---
## 💻 用法
### 选项A — CLI研究代理
从终端运行完整的研究查询：
```bash
# 基本查询
python run_agent.py --query "人工智能推理的最新进展是什么？"
# 带有详细工具轨迹 + 累积错误日志
python run_agent.py --query "比较GPT-4o vs Claude 3.5 Sonnet" --verbose
# 将报告保存到自定义目录
python run_agent.py --query "2024年人工智能安全研究" --output ./my-reports/
```
### 选项B — 完整栈（API + 前端）
**终端1 — 启动FastAPI后端：**
```bash
uvicorn api:app --reload --port 8080
```
**终端2 — 启动React前端：**
```bash
cd frontend
npm run dev
```
打开 [http://localhost:5173](http://localhost:5173) 在浏览器中。
### 选项C — 测试单个工具
```bash
# 测试所有第1阶段工具
python tests/test_tools.py
# 测试特定工具
python tests/test_tools.py --tool search_web --query "transformer架构"
python tests/test_tools.py --tool scrape_content --url "https://en.wikipedia.org/wiki/GPT-4"
# 测试第3阶段高级工具
python tests/test_advanced_tools.py
```
---
## 🐳 Docker
使用单个命令运行完整的栈：
```bash
# 构建并启动所有服务
docker-compose up --build
# 在后台运行
docker-compose up -d --build
```
| 服务 | URL |
|---|---|
| React前端 | [http://localhost:3000](http://localhost:3000) |
| FastAPI后端 | [http://localhost:8080](http://localhost:8080) |
| API文档 | [http://localhost:8080/docs](http://localhost:8080/docs) |
**停止：**
```bash
docker-compose down
```
---
## ⚙️ 配置
所有设置都通过 `.env` 控制：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OPENAI_API_KEY` | — | **必填.** OpenAI API密钥 |
| `TAVILY_API_KEY` | — | **必填.** Tavily搜索API密钥 |
| `OPENAI_MODEL` | `gpt-4o` | 要使用的LLM模型 |
| `MAX_HOPS` | `5` | 每个查询的最大推理跳跃次数 |
| `MAX_SEARCH_RESULTS` | `5` | 每次 `search_web` 调用的结果数 |
| `MAX_SCRAPE_CHARS` | `8000` | 每次 `scrape_content` 调用的字符数 |
| `NUM_CLUSTERS` | `3` | `cluster_and_rank` 的聚类数 |
| `REPORT_FORMAT` | `markdown_brief` | 默认输出格式 |
| `REPORTS_OUTPUT_DIR` | `./reports` | CLI保存报告的目录 |
---
## 📊 报告格式
| 格式 | 描述 | 最适合 |
|---|---|---|
| `markdown_brief` | 高管摘要 + 关键发现 + 分析 + 来源 | 一般研究 |
| `insight_report` | 具有趋势、挑战、建议的详细叙述 | 深入研究 |
| `comparison_table` | 比较来源/方法的结构化表格 | 竞争分析 |
参见 [`examples/sample_report_llm_reasoning.md`](examples/sample_report_llm_reasoning.md) 获取完整示例输出。
---
## 🗺️ 项目阶段
| 阶段 | 状态 | 描述 |
|---|---|---|
| **阶段1** | ✅ 完成 | MCP服务器 + `search_web`、`scrape_content`、`summarize` 工具 |
| **阶段2** | ✅ 完成 | LangGraph代理 + MCP客户端 + 共享内存 + CLI |
| **阶段3** | ✅ 完成 | `cluster_and_rank` + `generate_report` 高级工具 |
| **阶段4** | ✅ 完成 | 具有实时SSE流的React仪表板 |
| **阶段5** | ✅ 完成 | Docker Compose + 最终README + 示例输出 |
| **阶段6** | ✅ 完成 | 上下文工程 — `ContextBuilder`、动态提示、预算令牌、累积错误日志、置信度评分 |
---
## 🛠️ 技术栈
| 层 | 技术 |
|---|---|
| **MCP服务器** | FastMCP 2.x（Python MCP SDK） |
| **代理框架** | LangGraph 1.x（有状态StateGraph） |
| **上下文工程** | 自定义 `ContextBuilder`（令牌预算、相关性排名、动态提示） |
| **LLM** | OpenAI GPT-4o（可配置） |
| **网络搜索** | Tavily Python SDK |
| **网页抓取** | httpx + BeautifulSoup4 + lxml |
| **聚类** | scikit-learn（TF-IDF、K-Means、余弦相似度） |
| **API后端** | FastAPI + uvicorn + SSE |
| **前端** | React 19 + TypeScript + Vite 6 |
| **UI** | Vanilla CSS（玻璃形态，暗色模式） |
| **容器化** | Docker Compose |
---
## 🔌 API参考
### `POST /research/stream`
启动研究会话。返回服务器发送事件流。
**请求体：**
```json
{
"query": "您的研究问题",
"format": "markdown_brief",
"max_hops": 5
}
```
**SSE事件类型：
| 类型 | 描述 |
|---|---|
| `status` | 代理状态更新（规划、搜索等） |
| `tool_calls` | 调用了特定的MCP工具 |
| `hop` | 完成了一个推理跳跃 |
| `report` | 最终报告就绪（包括完整的Markdown） |
| `error` | 流式处理级别的错误发生 |
| `done` | 会话完成 |
### `GET /report/{session_id}`
通过会话ID检索已完成的报告。响应包括 `report`、`stats`、`tool_calls` 和 `errors`（累积错误日志）。
### `GET /reports`
列出当前会话的所有报告。
### `GET /health`
健康检查端点。
<div align="center">
由 [Rishabhpm23](https://github.com/Rishabhpm23) 构建 ❤️
⭐ 如果Zetabot帮助您了解MCP代理和上下文工程，请给它一个星标！
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器