algonotes_rag/docs/ARCHITECTURE.md

# 🏗️ AlgoNotes RAG 架构文档

## 📁 项目目录结构

```tree
algonotes_rag/
├── .env                          # 环境变量（不提交 Git）
├── .env.example                  # 环境变量模板
├── .gitignore
├── .python-version               # Python 版本锁定
├── LICENSE                       # MIT 许可
├── pyproject.toml                # 项目元数据 + 依赖（uv 管理）
├── README.md                     # 项目介绍与快速开始
├── config.toml                   # 主配置文件（TOML + ${VAR} 语法）
│
├── docs/                         # 文档
│   ├── ARCHITECTURE.md           # 架构说明（宏观）
│   ├── CONFIG.md                 # 配置说明
│   ├── ROADMAP.md                # 项目路线图
│   ├── STORE.md                  # 三层存储详解（文件/关系/向量）
│   ├── RAG.md                    # RAG 查询管线详解
│   ├── cli/                      # CLI 命令行工具文档
│   │   ├── README.md             # CLI 概览
│   │   ├── ingest.md             # 导入命令（增）
│   │   ├── update.md             # 更新命令（改）
│   │   ├── delete.md             # 删除命令（删）
│   │   └── query.md              # 查询命令（查）
│   └── mcp/                      # MCP Server 文档
│       ├── README.md             # MCP 概览
│       ├── ingest.md             # 导入工具
│       ├── update.md             # 更新工具
│       ├── delete.md             # 删除工具
│       ├── search.md             # 搜索工具
│       ├── metadata.md           # 元数据工具
│       └── export.md             # 导出工具
│
├── logs/                         # 日志输出目录（自动生成）
│
├── data/                         # 数据存储（自动生成）
│   ├── files/                    # 原始笔记文件（.md 保存于此）
│   ├── sql_db/                   # 关系型数据库（SQLite，记录笔记索引信息）
│   └── chroma_db/                # Chroma 向量库持久化
│
├── prompts/                      # LLM Prompt 模板
│   ├── agent_system.md           # RAG Agent 系统提示词
│   ├── clean.md                  # 文本清洗模板
│   └── tagger.md                 # 标签提取模板
│
├── src/                          # 核心源码
│   ├── __init__.py
│   │
│   ├── config.py                 # Pydantic 配置模型 + 环境变量替换
│   ├── logger.py                 # 日志系统（JSON Lines 格式）
│   │
│   ├── ingestion/                # 数据摄入管线
│   │   ├── __init__.py
│   │   ├── loader.py             # 文档加载（Web / 本地文件）
│   │   ├── cleaner.py            # LLM 清洗网页文本
│   │   ├── splitter.py           # 分块策略（标题 + 递归）
│   │   └── tagger.py             # 给文档打标签，存储在 sql 中
│   │
│   ├── store/                    # 三层存储
│   │   ├── __init__.py
│   │   ├── sql/                  # SQL schema 与查询模板
│   │   │   ├── schema.sql        # 笔记元数据表 DDL
│   │   │   └── queries.sql       # 命名 SQL 查询模板（参考用）
│   │   ├── file_store.py         # 文件层：原始 .md 笔记的保存与读取
│   │   ├── sql_store.py          # 关系层：笔记索引、关键词、上传时间等
│   │   ├── vector_store.py       # 向量层：Chroma 向量库封装
│   │   └── vector_metadata.py    # Metadata 规范与校验
│   │
│   ├── rag/                      # RAG 查询管线
│   │   ├── __init__.py
│   │   ├── agent.py              # RAG Agent（含查询理解 Prompt + 工具编排）
│   │   ├── retriever.py          # 内部工具：检索器（向量 + SQL）
│   │   └── generation.py         # 内部工具：重排序 + 答案生成 + 溯源引用
│   │
│   ├── api/                      # API 客户端层
│   │   ├── __init__.py
│   │   ├── llm_client.py         # LLM 客户端封装
│   │   ├── embedding_client.py   # Embedding 客户端封装
│   │   └── reranker_client.py    # Reranker 客户端封装
│   │
│   └── mcp/                      # MCP 服务器层
│       ├── __init__.py
│       ├── __main__.py           # python -m src.mcp 入口
│       ├── server.py             # MCP Server 核心（组件初始化）
│       └── tools.py              # 工具实现（薄包装层）
│
├── scripts/                      # CLI 入口脚本
│   ├── cli.py                    # algonotes 统一入口
│   ├── ingest.py                 # 导入笔记
│   ├── update.py                 # 更新笔记
│   ├── delete.py                 # 删除笔记
│   ├── query.py                  # 查询笔记
│   ├── rag.py                    # RAG 问答
│   └── chat.py                   # 交互式问答
```

## 🔧 模块依赖关系

```mermaid
graph TD
    subgraph frontend[前端入口]
        cli[cli.py<br/>统一入口]
        rag[rag.py]
        chat[chat.py]
        mcp_server[MCPServer<br/>server.py]
        mcp_tools[MCP Tools<br/>tools.py]
        mcp_server --> mcp_tools
    end

    subgraph ingestion[src/ingestion]
        loader[loader.py]
        cleaner[cleaner.py]
        splitter[splitter.py]
        loader --> cleaner --> splitter
    end

    subgraph rag[src/rag]
        rag_agent[agent.py<br/>RAG Agent<br/>内嵌查询理解 Prompt]
        retriever[retriever.py<br/>内部工具]
        generation[generation.py<br/>内部工具]
        rag_agent --> retriever
        rag_agent --> generation
    end

    subgraph store[src/store]
        fs[file_store.py<br/>原始 .md 文件]
        ss[sql_store.py<br/>笔记索引]
        vs[vector_store.py<br/>Chroma 向量]
    end

    subgraph data[data/]
        df[data/files/]
        ds[data/sql_db/]
        dc[data/chroma_db/]
    end

    subgraph api[src/api]
        llm[llm_client.py]
        emb[embedding_client.py]
        rrk[reranker_client.py]
    end

    config[src/config.py + config.toml]

    cli --> ingestion
    cli --> rag
    chat --> rag
    mcp_tools --> ingestion
    mcp_tools --> rag
    ingestion --> store
    rag --> store
    fs --> df
    ss --> ds
    vs --> dc
    store --> api
    api --> config
```

## 📦 各模块职责

| 模块 | 文件 | 职责 |
| ------ | ------ | ------ |
| **配置管理** | `config.toml` + `src/config.py` | Pydantic 模型校验，`${VAR}` 语法引用环境变量 |
| **日志系统** | `src/logger.py` | JSON Lines 格式，必含 `timestamp`/`level`/`logger`/`message`，可选 `latency_ms`/`tokens` |
| **文件存储** | `src/store/file_store.py` | 原始 .md 笔记的保存、读取、删除 |
| **关系存储** | `src/store/sql_store.py` | SQLite 笔记索引（文件名、上传时间、关键词、文件路径等） |
| **向量存储** | `src/store/vector_store.py` | Chroma 封装，metadata 扁平化校验 |
| **数据摄入** | `src/ingestion/` | 文档加载 → LLM 清洗 → 标题+递归分块 → 入库 |
| **RAG Agent** | `src/rag/agent.py` | 内嵌查询理解 Prompt，编排检索与生成工具 |
| **检索器** | `src/rag/retriever.py` | 内部工具：向量检索 + SQL 过滤 |
| **答案生成** | `src/rag/generation.py` | 内部工具：重排序 + 竞赛语境生成 + 溯源引用 |
| **RAG 问答** | `scripts/rag.py` | 单次 RAG 问答，直接输出答案 |
| **MCP Server** | `src/mcp/` | 暴露 ingest/update/delete/query 四类工具，MCP 协议对外服务 |
| **LLM 客户端** | `src/api/llm_client.py` | OpenAI 兼容接口的统一调用层 |
| **Embedding 客户端** | `src/api/embedding_client.py` | Embedding 模型调用封装 |
| **Reranker 客户端** | `src/api/reranker_client.py` | Reranker 模型调用封装 |

## 📚 相关文档

- [三层存储详解](STORE.md) — 文件层、关系层、向量层的设计与 API
- [RAG 查询管线](RAG.md) — Agent 驱动的查询理解、检索、生成流程