┌─────────────────────────────────────────────────────────────────────────┐
│                        Modular RAG MCP Server                           │
│                                                                          │
│  ┌──────────────────────────────┐    ┌──────────────────────────────┐   │
│  │  离线 Ingestion 链路（摄取）    │    │  在线 Query 链路（查询）       │   │
│  │                              │    │                              │   │
│  │  ① 文件完整性检查 (SHA256)     │    │  ① MCP 工具调用 (stdio)       │   │
│  │  ② PDF 解析 (MarkItDown)      │    │  ② 查询预处理 (jieba 分词)    │   │
│  │  ③ 递归分块 (chunk=1000)      │    │  ③ 并行混合检索 (Dense+Sparse)│   │
│  │  ④ 变换管线 (Refine+Enrich+   │    │  ④ RRF 融合排序 (k=60)        │   │
│  │     Caption)                  │    │  ⑤ 可选 Rerank               │   │
│  │  ⑤ 向量编码 (Dense+Sparse)    │    │  ⑥ 响应构建 (Markdown+引用+   │   │
│  │  ⑥ 多路存储 (3 个后端)         │    │     图片)                     │   │
│  └──────────────────────────────┘    └──────────────────────────────┘   │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │  存储层：ChromaDB（稠密向量）+ BM25 Index（稀疏索引）               │   │
│  │          + ImageStorage（图片索引）+ SQLite（摄取历史/幂等）         │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

   ┌──────────────────────────────────────────────────────────┐
   │   AI 助手（Claude / Copilot / Cursor 等 MCP Client）        │
   └──────────────────────────┬───────────────────────────────┘
                              │ MCP Protocol (stdio JSON-RPC 2.0)
   ┌──────────────────────────▼───────────────────────────────┐
   │  src/mcp_server/    【协议服务层】                          │
   │  server.py → protocol_handler.py → tools/（3 个 Tool）     │
   └──────────────────────────┬───────────────────────────────┘
                              │ 调用
   ┌────────────┬─────────────▼─────────────┬─────────────────┐
   │            │                           │                 │
   │ src/       │ src/core/query_engine/    │ src/            │
   │ ingestion/ │ 【检索引擎层】             │ observability/  │
   │ 【业务管道】│ HybridSearch → RRF →      │ 【可观测性层】   │
   │ Pipeline   │ Rerank → Response         │ Dashboard +     │
   │ 6 阶段     │                           │ Evaluation      │
   └────────────┴─────────────┬─────────────┴─────────────────┘
                              │ 依赖抽象
   ┌──────────────────────────▼───────────────────────────────┐
   │  src/libs/   【可插拔库层】                                 │
   │  LLM | Embedding | Loader | Splitter | VectorStore        │
   │  | Reranker | Evaluator（Base 类 + Factory 模式）           │
   └──────────────────────────┬───────────────────────────────┘
                              │ 读写
   ┌──────────────────────────▼───────────────────────────────┐
   │  src/core/    【基础设施层】                                │
   │  settings.py | types.py | trace/（配置 + 数据类型 + 追踪）  │
   └──────────────────────────────────────────────────────────┘

MCP Client (stdio)
  └─ tools/call: query_knowledge_hub
      └─ QueryProcessor      → jieba 分词 + 停用词过滤 + 过滤语法解析
      └─ HybridSearch        → DenseRetriever + SparseRetriever 并行（ThreadPool）
      └─ RRFFusion (k=60)    → Σ 1/(k + rank_i)，排名级融合，无需分数归一化
      └─ Reranker（可选）     → Cross-Encoder / LLM 精排，失败保持原序
      └─ ResponseBuilder     → Markdown 内容 + [1][2] 引用标记 + 多模态图片
      └─ TraceCollector      → 写入 logs/traces.jsonl
      └─ MCP Response        → TextContent + 可选 ImageContent

┌───────────────────────────────────────────────────────────────┐
│  交互层：Streamlit（Dashboard）· MCP Protocol（JSON-RPC over  │
│          stdio）· Python 3.10+ · asyncio                       │
├───────────────────────────────────────────────────────────────┤
│  RAG 核心：                                                   │
│    检索     Dense: Qwen3-Embedding-4B（2560 维）              │
│             Sparse: 自实现 BM25（jieba 分词）                  │
│    融合     RRF（k=60，排名级融合）                             │
│    重排     Cross-Encoder / LLM Rerank（可插拔）               │
│    生成/变换 DeepSeek-V3.2 等（OpenAI 兼容）                    │
├───────────────────────────────────────────────────────────────┤
│  存储层：ChromaDB（向量）· BM25 JSON Index（稀疏）·            │
│          SQLite（图片索引 / 摄取历史）· 文件系统                │
├───────────────────────────────────────────────────────────────┤
│  可观测性：TraceContext · JSON Lines · Ragas · CustomEvaluator│
│             · pytest（三层测试）· Golden Test Set              │
└───────────────────────────────────────────────────────────────┘

MODULAR-RAG-MCP-SERVER/
├── config/
│   ├── settings.yaml              # 全局配置中心（LLM/Embedding/检索/摄取…）
│   └── prompts/                   # 各阶段 Prompt 模板（精炼/元数据/图片描述/重排）
├── documents/                     # 待摄取原始文档
├── data/db/                       # 运行时数据（chroma/ bm25/ 图片索引/ 摄取历史）
├── logs/traces.jsonl              # 全链路追踪 JSON Lines
├── scripts/                       # CLI 入口（ingest/query/evaluate/start_dashboard/探测脚本）
├── src/
│   ├── core/                      # 【基础设施层】settings、types、query_engine、response、trace
│   ├── ingestion/                 # 【业务管道层】pipeline、chunking、embedding、storage、transform
│   ├── libs/                      # 【可插拔库层】llm、embedding、loader、splitter、vector_store、reranker、evaluator
│   ├── mcp_server/                # 【协议服务层】server、protocol_handler、tools/
│   └── observability/             # 【可观测性层】logger、dashboard（6 页）、evaluation
├── tests/                         # unit / integration / e2e / fixtures（Golden Test Set）
├── DEV_SPEC.md                    # 开发规格文档
├── main.py                        # 项目主入口（注册为 mcp-server CLI）
└── pyproject.toml                 # 项目元数据与依赖

{
  "id": "F-005",
  "name": "VectorStore 抽象层",
  "description": "BaseVectorStore 抽象类 + VectorStoreFactory + ChromaStore 实现",
  "files": ["src/libs/vector_store/*.py"],
  "depends_on": ["F-001", "F-002"],
  "verification": "python -m pytest tests/unit/test_vector_store.py -v",
  "acceptance": "ChromaStore 可 upsert/query/delete/get_by_ids，cosine 排序正确"
}

┌──────────────────────────────────────────────────────────┐
│                   Coding Loop 单轮协议                     │
│                                                          │
│  ① 启动全新 Agent（无历史上下文）                           │
│  ② Agent 读取 3 个外部文件：                              │
│     - feature_list.json → 知道当前该做哪个 Feature        │
│     - progress.md      → 知道前面完成了什么、踩了什么坑     │
│     - 目标代码文件      → 了解当前代码状态                  │
│  ③ Agent 完成一个 Feature                                 │
│  ④ 确定性验证 Gate（不是 Agent 自评）：                    │
│     - pytest 必须 PASS                                    │
│     - mypy/pyright 类型检查必须 PASS                       │
│     - ruff lint 必须 PASS                                 │
│  ⑤ 验证通过后，由系统（非 Agent）更新状态：                 │
│     - feature_list.json: status → completed               │
│     - progress.md: 追加交接记录                            │
│     - git commit: 提交代码 + 验证结果                      │
│  ⑥ Agent 立即退出，下一轮由新 Agent 接力                   │
└──────────────────────────────────────────────────────────┘

# 1. 克隆并进入项目
git clone <repo-url>
cd MODULAR-RAG-MCP-SERVER

# 2. 安装依赖（Python 3.10+）
pip install -e ".[dev]"

# 3. 配置 API Key：从模板复制（config/settings.yaml 已被 git 忽略，请勿提交真实密钥）
cp config/settings.yaml.example config/settings.yaml
#   然后编辑 config/settings.yaml，填写 LLM / Embedding 的 API Key 与 base_url

# 4. 摄取文档：将 PDF 放入 documents/，执行
python scripts/ingest.py --path documents/ --collection knowledge_hub

# 5. 查询验证
python scripts/query.py --query "你的问题" --collection knowledge_hub

# 6. 启动 Dashboard
python scripts/start_dashboard.py

# 7. 启动 MCP Server（供 Claude / Copilot 等 Client 调用）
mcp-server