┌───────────────────────────────────────────────────────┐
│         Vue3 前端 (localhost:5173)                    │
│  流式对话 · 检索可视化 · 文档管理 · API Key 管理       │
└──────────────────────┬────────────────────────────────┘
                       │ REST / SSE（JWT 鉴权）
┌──────────────────────▼────────────────────────────────┐
│                FastAPI 服务层 (:8000)                  │
│  /api/v1/search · /chat · /documents · /auth          │
│  ─────────────────────────────────────────────        │
│  鉴权(JWT+API Key) · 数据管线(队列/状态机/去重)       │
│  可观测(structlog+Langfuse) · 后台摄入 Worker         │
└──────────────────────┬────────────────────────────────┘
                       │ 进程内直连
┌──────────────────────▼────────────────────────────────┐
│                RAG 引擎层                              │
│  loader → splitter → embedder → vectorstore           │
│  (向量+BM25 混合检索 → RRF 融合 → 重排 → 缓存)         │
└───────────────────────────────────────────────────────┘
                       ▲
                       │ MCP 协议 (stdio)
┌──────────────────────┴────────────────────────────────┐
│   MCP 客户端（Cherry Studio / Claude Desktop）         │
│   search_knowledge · ingest_document · list_docs      │
│   delete_document · web_search · get_time             │
└───────────────────────────────────────────────────────┘

数据存储：Chroma 向量库 · SQLite(注册表/用户) · FAISS(语义缓存)
质量门禁：RAGAS 评估 → GitHub Actions CI

git clone https://github.com/<your-username>/mcp-rag-assistant.git
cd mcp-rag-assistant
pip install -r requirements.txt

# 前端
cd frontend && npm install

cp .env.example .env
# 编辑 .env：
#  - LLM_API_KEY / LLM_API_BASE    必填（对话与评估）
#  - JWT_SECRET                    建议配置（否则重启后 token 全部失效）
#  - AUTH_ENABLED                  鉴权开关（默认开启）
#  - LANGFUSE_PUBLIC_KEY/SECRET_KEY 可选（配置后启用 Tracing）

uvicorn api.main:app --host 0.0.0.0 --port 8000

cd frontend && npm run dev

python -m mcp_server.server

python -m evaluation            # RAGAS 评估 + 质量门禁（exit 1 拦截）
python -m evaluation --no-gate  # 仅评估，不拦截

# 注册（首个用户为 admin）
curl -X POST :8000/api/v1/auth/register -d '{"username":"admin","password":"your-pass"}'
# 登录换 JWT
curl -X POST :8000/api/v1/auth/token -d '{"username":"admin","password":"your-pass"}'
# 业务调用
curl -H "Authorization: Bearer <jwt>" :8000/api/v1/search ...

mcp-rag-assistant/
├── config.py                 # 全局配置（含评估阈值/鉴权开关）
├── requirements.txt
├── .env.example              # 环境变量模板
├── rag_engine/               # RAG 引擎层
│   ├── loader.py             # 多格式文档加载
│   ├── splitter.py           # 递归切分
│   ├── embedder.py           # 向量化（BGE，离线加载）
│   ├── vectorstore.py        # Chroma 向量库
│   ├── retriever.py          # 混合检索 + RRF + 重排
│   └── cache.py              # LRU + FAISS 语义缓存
├── api/                      # FastAPI 服务层
│   ├── main.py               # 入口：lifespan 预热 + 中间件
│   ├── schemas.py            # Pydantic 请求/响应模型
│   ├── deps.py               # 引擎单例依赖注入
│   ├── services.py           # 服务层：异步化 + AsyncOpenAI
│   ├── auth.py               # JWT + API Key 鉴权核心
│   ├── dedup.py              # 双重去重索引（文件级/片段级）
│   ├── registry.py           # SQLite 文档状态机
│   ├── worker.py             # 摄入任务队列（后台线程）
│   ├── observability.py      # structlog + 请求ID + Langfuse
│   └── routers/
│       ├── search.py         # 检索接口
│       ├── chat.py           # 对话接口（含 SSE 流式）
│       ├── documents.py      # 文档管理接口
│       └── auth.py           # 认证接口
├── frontend/                 # Vue3 前端
│   └── src/
│       ├── api/              # axios 封装 + SSE 流式解析
│       ├── stores/           # Pinia（JWT 状态）
│       └── views/            # Chat / SearchViz / Documents / ApiKeys
├── evaluation/               # RAGAS 评估 + 质量门禁
│   └── runner.py             # 25 题测试集 → 四指标 → 门禁
├── mcp_server/               # MCP Server 层
│   ├── server.py             # 6 个 MCP 工具注册
│   └── tools/external.py     # 联网搜索等外部工具
├── web_ui/                   # Streamlit 前端（旧版，保留）
├── mcp_client_config/        # MCP 客户端配置示例
├── .github/workflows/ci.yml  # CI：lint + RAGAS 评估门禁
├── docs/                     # 文档（开发问题全记录等）
└── data/                     # 运行时数据（gitignore）
    ├── chroma/               # 向量库
    ├── docs/                 # 上传文档 + 示例文档
    ├── registry.db           # 文档注册表
    └── auth.db               # 用户与 API Key

用户提问
   │
   ├─→ 缓存命中检查（LRU 精确 + FAISS 语义近似，0.3ms）
   │        └─ 命中 → 直接返回
   │
   ├─→ 向量检索（BGE Embedding + Chroma）
   ├─→ BM25 关键词检索（jieba 分词）
   │
   ├─→ RRF 融合（Reciprocal Rank Fusion）
   ├─→ CrossEncoder 重排
   │
   └─→ 写入缓存 → 返回 Top-K