algonotes_rag/docs/ARCHITECTURE.md

🏗️ AlgoNotes RAG 架构文档

📁 项目目录结构

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                   # 交互式问答

🔧 模块依赖关系

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 模型调用封装

📚 相关文档

• 三层存储详解 — 文件层、关系层、向量层的设计与 API
• RAG 查询管线 — Agent 驱动的查询理解、检索、生成流程