┌──────────────────────────────────────────────────────────────────┐
│                  用户 / Claude Desktop / CLI                      │
└───────────────────┬──────────────────────┬───────────────────────┘
                    │ MCP JSON-RPC 2.0     │ Streamlit Dashboard
                    ▼                      ▼
        ┌─────────────────┐    ┌────────────────────────────────┐
        │   MCP Server    │    │        可观测性管理平台          │
        │ (stdio 传输)    │    │  系统总览 · Agent 对话 · 知识库  │
        │ query_knowledge │    │  摄取管理 · 导入追踪 · 评估面板  │
        │ list_collections│    └────────────────────────────────┘
        │ get_doc_summary │
        └────────┬────────┘
                 │
                 ▼
        ┌────────────────────────────────────────────────────┐
        │                    ReAct Agent                     │
        │                                                    │
        │  ┌────────────┐  Thought/Action/Observation        │
        │  │  LLM 推理  │◄──────────────────────────────┐   │
        │  └────────────┘                               │   │
        │  ┌────────────┐                    ┌──────────▼─┐ │
        │  │SelfChecker │  幻觉检测 · 置信度   │ToolRegistry│ │
        │  └────────────┘  打分（0.0–1.0）    │ 5 个工具   │ │
        │  ┌────────────┐                    └────────────┘ │
        │  │ 多轮对话记忆│  滑动窗口历史管理                   │
        │  └────────────┘                                   │
        └────────┬───────────────────────────────────────────┘
                 │
                 ▼
        ┌────────────────────────────────────────────────────┐
        │                  混合检索引擎                        │
        │   Query Processor（jieba 分词 + 语义过滤）            │
        │          │                     │                   │
        │   ┌──────▼──────┐     ┌────────▼──────┐           │
        │   │ Dense 检索   │     │  Sparse 检索   │           │
        │   │ BGE-m3 向量  │并行  │   BM25 倒排    │           │
        │   │ + ChromaDB  │     │  + jieba 分词  │           │
        │   └──────┬──────┘     └────────┬──────┘           │
        │          └──────────┬───────────┘                  │
        │                     ▼                              │
        │              RRF 融合（k=60）                       │
        │                     ▼                              │
        │         Cross-Encoder 精排（可插拔，可选）            │
        └────────────────────────────────────────────────────┘
                 ▲
                 │ 数据摄取（6 阶段流水线）
        ┌────────────────────────────────────────────────────┐
        │ ①完整性校验 → ②PDF解析 → ③智能分块                  │
        │ → ④LLM增强Transform → ⑤双路编码 → ⑥存储            │
        └────────────────────────────────────────────────────┘
                 │
                 ▼
        ┌────────────────────────────────────────────────────┐
        │               可插拔 Provider 层                    │
        │  LLM:       OpenAI · Azure · DeepSeek · Ollama     │
        │  Embedding: OpenAI · SiliconFlow · Azure · Ollama   │
        │  VectorStore: ChromaDB（Qdrant / Milvus 规划中）    │
        └────────────────────────────────────────────────────┘

Thought → Action → Observation → Thought → ... → Final Answer
              ↑每步 yield，Dashboard 实时刷新↑

①完整性校验  →  ②PDF解析  →  ③递归分块  →  ④Transform  →  ⑤双路编码  →  ⑥存储
SHA256幂等        MarkItDown      chunk_size      ChunkRefiner     Dense+Sparse    ChromaDB
hash guard       → Markdown       =1000          MetadataEnricher  并行批处理      + BM25索引
                 图像提取占位符    overlap=200    ImageCaptioner               + ImageStore

// claude_desktop_config.json 添加一行即可接入
{ "mcpServers": { "rag": { "command": "python", "args": ["-m", "main"] } } }

💭 THOUGHT: 需要先搜索 BM25 的相关内容...       ← Turn 1 完成
⚡ ACTION:  hybrid_search  ● 工具执行中…
────────────────────────────────────────
💭 THOUGHT: 找到了相关定义，再补充对比信息...    ← Turn 2 推理中...
⚡ ACTION:  semantic_search  ● 工具执行中…
         ↓  done 事件到达
[最终答案] · [置信度 0.87] · [2 轮] · [1.3s]

# 切换 LLM Provider：只改 settings.yaml，零代码修改
llm:
  provider: "DeepSeek"     # openai / azure / deepseek / ollama
  model: "deepseek-v4-flash"
  api_key: "sk-..."

# Factory Pattern：新增 Provider 3 步完成
class MoonshotLLM(BaseLLM):
    def chat(self, messages): ...           # Step 1: 实现接口

LLMFactory.register_provider("moonshot", MoonshotLLM)  # Step 2: 注册

# settings.yaml: provider: "moonshot"      # Step 3: 配置

tests/
├── unit/               # 快速，纯 Python，无外部依赖
│   ├── test_rrf_fusion.py         # RRF 算法正确性验证
│   ├── test_react_agent.py        # Agent 循环（Mock LLM + Mock 工具）
│   ├── test_conversation_memory.py
│   └── test_self_checker.py
│
├── integration/        # 需要 ChromaDB / LLM API
│   ├── test_ingestion_pipeline.py
│   ├── test_hybrid_search.py
│   └── test_mcp_server.py
│
└── e2e/                # 完整业务流程验证
    ├── test_data_ingestion.py     # 上传 → 检索 → 验证
    ├── test_mcp_client.py         # 真实 MCP 协议调用
    └── test_recall.py             # Golden Set 召回率回归

pytest tests/unit -v                         # 仅单元测试（秒级）
pytest tests/ -m "not llm" -v               # 跳过需要 API 的测试
pytest tests/ --cov=src --cov-report=html   # 生成覆盖率报告

# 1. 克隆并安装
git clone <repo-url>
cd <project-dir>
pip install uv && uv sync

# 2. 配置 API Key
cp config/settings.yaml config/settings.local.yaml
# 编辑 llm.api_key 和 embedding.api_key

# 3. 摄取文档
python scripts/ingest.py --source path/to/your/docs

# 4. 启动 Streamlit 管理平台
python scripts/start_dashboard.py

# 5. 命令行单次查询
python scripts/query.py "RRF 算法的原理是什么？"

# 6. 命令行多轮 Agent 对话
python scripts/agent.py

# 7. 运行检索评测基准
python scripts/run_benchmark.py

# 8. 接入 Claude Desktop（MCP 模式）
# claude_desktop_config.json 添加：
# {"mcpServers": {"rag": {"command": "python", "args": ["-m", "main"]}}}
python -m main

src/
├── agent/              # ReAct Agent 核心
│   ├── react_agent.py  # 主循环（run / run_stream）
│   ├── tool_registry.py
│   ├── tools/          # 5 个 RAG 工具实现
│   ├── memory/         # ConversationMemory
│   └── reflection/     # SelfChecker（LLM 幻觉检测）
│
├── core/
│   ├── query_engine/   # HybridSearch · DenseRetriever · SparseRetriever · RRF
│   ├── response/       # 答案组装 · Citation 生成
│   ├── trace/          # TraceContext · TraceCollector
│   ├── types.py        # 全项目数据契约（Document / Chunk / RetrievalResult）
│   └── settings.py     # YAML 配置加载与验证
│
├── ingestion/          # 6 阶段摄取流水线
│   ├── pipeline.py     # IngestionPipeline.run()
│   ├── chunking/       # RecursiveCharacterTextSplitter 适配
│   ├── embedding/      # Dense + Sparse 双路批处理
│   ├── storage/        # ChromaDB · BM25 Index · Image Store
│   └── transform/      # ChunkRefiner · MetadataEnricher · ImageCaptioner
│
├── libs/               # 可插拔抽象层
│   ├── llm/            # BaseLLM + OpenAI/Azure/Ollama/DeepSeek 实现
│   ├── embedding/      # BaseEmbedding + 各 Provider 实现
│   ├── reranker/       # BaseReranker + Cross-Encoder / LLM Rerank
│   ├── splitter/       # BaseSplitter + RecursiveSplitter
│   ├── vector_store/   # BaseVectorStore + ChromaDB 实现
│   ├── evaluator/      # BaseEvaluator + Ragas / Custom / Composite
│   └── loader/         # PDF 解析 · 文件完整性校验
│
├── mcp_server/         # MCP Server 实现
│   ├── server.py       # stdio 传输入口
│   ├── protocol_handler.py
│   └── tools/          # query_knowledge_hub / list_collections / get_doc_summary
│
└── observability/      # 可观测性层
    ├── logger.py        # 结构化日志
    ├── evaluation/      # Ragas + Custom 评估运行器
    └── dashboard/       # Streamlit 7 页面管理平台

scripts/
├── ingest.py            # 文档摄取 CLI
├── query.py             # 单次查询 CLI
├── agent.py             # 多轮 Agent 对话 CLI
├── run_benchmark.py     # 4 模式检索基准测试
└── evaluate.py          # Ragas 评估运行器

config/
├── settings.yaml        # 全局配置（LLM · Embedding · 检索 · Agent）
└── prompts/
    └── react_agent.txt  # ReAct Prompt 模板（外置，支持热更新）

tests/
├── unit/                # 单元测试（无外部依赖）
├── integration/         # 集成测试（需 ChromaDB / LLM API）
└── e2e/                 # 端到端测试（完整业务流程）