WebAgent

Web 研究助手：LangGraph + 向量 RAG + 网页抓取 + 记忆。

功能演示

常识库 RAG

提问基础概念，Agent 检索本地向量库并回答；点击 + 可展开 Agent 步骤（常识库 RAG 检索详情）。

贴链接读页

在输入框添加 URL，Agent 通过 MCP 抓取页面正文并总结。

Agent 步骤（Workflow）

每轮回复可展开查看完整 workflow：MCP 网页抓取 → 列出已抓页面 → 阅读页面内容。

模型与存储

组件	方案
对话 / Agent	DeepSeek
Embedding	本地 BGE（默认 `bge-small-zh-v1.5`，512 维，~100 MB）
网页抓取	MCP Fetch（stdio 子进程，失败回退 httpx）
向量库	Milvus Lite（默认）或 PostgreSQL pgvector

一键启动（推荐）

cd D:\pythonProject\WebAgent
pip install -r requirements.txt

# 配置 .env 中的 DEEPSEEK_API_KEY 后：
.\scripts\run_server.ps1

启动脚本会按顺序自动完成：

检查旧进程 — 避免端口 / Milvus 锁争抢
下载 Embedding 模型 — 首次从魔搭拉取 bge-small-zh-v1.5（约 100 MB）
构建 RAG 索引 — 若尚未建过或与当前模型配置不一致
启动 Agent 服务 — http://127.0.0.1:8000

常用参数：

.\scripts\run_server.ps1 -Force          # 结束旧服务后重启
.\scripts\run_server.ps1 -Reload         # 开发模式：代码变更自动重载
.\scripts\run_server.ps1 -RebuildIndex    # 强制重建向量索引

等价 Python 命令：

python scripts/start.py --force

环境变量

DEEPSEEK_API_KEY=sk-...
EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
EMBEDDING_DOWNLOAD=modelscope
VECTOR_STORE=milvus
MCP_FETCH_ENABLED=true

更换 Embedding 模型后，执行 .\scripts\run_server.ps1 -RebuildIndex。

消息回溯（Checkpointer）

对话状态持久化在 data/checkpoints.db（LangGraph AsyncSqliteSaver）
刷新页面后自动恢复同一 thread_id 的历史消息
每条用户消息旁的 「回溯」：回到该轮之前继续聊（LangGraph checkpoint 分叉）

API：

GET /api/v1/chat/history?thread_id=...
POST /api/v1/chat/rewind — { "thread_id", "user_turn_index" }
回溯后发消息需带 checkpoint_id（前端自动处理）

单独建索引（可选）

python scripts/build_kb_index.py

一般不需要手动执行，启动脚本会自动处理。

测试

$env:PYTHONPATH="D:\pythonProject\WebAgent\backend\src"
python -m pytest tests/ -v

E2E 测试需配置 DEEPSEEK_API_KEY。

Session 日志

每轮对话日志结构（与前端 Agent 步骤一致）：

{"event": "chat.start", "thread_id": "...", "message": "光合作用是什么", "urls": null}
{"event": "workflow.step", "step": 1, "category": "rag", "tool": "search_knowledge_base", "label": "常识库 RAG", "backend": "local", "detail": "..."}
{"event": "chat.done", "assistant_message": "...", "workflow": {"used_rag": true, "used_mcp": false, "used_fetch": false, "step_count": 1, "steps": [...]}}

category 含义：rag 常识库 · mcp MCP 网页抓取 · read 读页 · memory 记忆

MCP 网页抓取

内置 Python MCP Server（webagent.mcp.server_fetch），通过 stdio 子进程通信，Agent 调 fetch_page 时走 MCP；失败自动回退 httpx。配置见 config/mcp.json，可用 MCP_FETCH_ENABLED=false 关闭。

colayear/WebAgent

README