🧠 AlgoNotes RAG - 个人算法竞赛笔记智能助手

🎯 定位：面向 OI/ICPC 等算法竞赛生的 个人笔记外置大脑。
基于 RAG + MCP 架构，实现个人题解/代码/推导笔记的语义检索、竞赛场景下的问答与结构化输出。
与公共题库系统形成互补，专注还原个人认知路径与复健轨迹。

---

📖 项目背景：从“算力奢侈品”到“个人外置大脑”

回到项目发起人（即笔者 fangtianchen）学习信息学奥赛（OI）的“前 AI 时代”，那时学习路径高度依赖博客笔记、碎片化题解与反复试错。那时，DeepSeek R1 尚未问世，GPT 等大语言模型对中学生而言仍是遥不可及的“算力奢侈品”。每一位选手都在黑暗中独自摸索：手写推导、整理错题、反复调试，知识沉淀缓慢且极易断层。笔者在经历了高三的题海与模考的挫折后，许多本可结构化的认知轨迹，最终散落在 cnblogs、洛谷提交记录与本地文件夹中，这让高考后复健算法准备 ICPC 遇到困难。

如今，AI 技术普惠与国产算力崛起正在重塑这一切。沐曦 GPU、Gitee.AI 等国产基础设施的成熟，让“每个人都能拥有专属 AI 助手”从愿景走向现实。然而，市面上的竞赛辅助工具多聚焦于“公共题库检索”或“通用代码生成”，却忽略了竞赛生最核心的资产——个人在实战中沉淀的认知路径。

AlgoNotes RAG 正是在此背景下诞生。它不追求替代人类的思考，而是致力于成为 OI/ICPC 选手的“私有外置大脑”：

• 🇨🇳 全栈国产算力落地：推理依赖沐曦 GPU + 开源模型（Qwen/DeepSeek），零国外商业 API 依赖
• 🔒 隐私优先的个人知识库：笔记本地解析、向量化与存储，数据不出域，支持离线演进
• 🧭 懂你的竞赛语境：内置代码习惯审查/复杂度推导等 Prompt，输出带溯源引用的结构化答案
• 🤝 MCP / CLI 双接口：增/删/改/查四类操作同时支持 MCP 协议与命令行工具，可无缝接入 Claude Code / OpenClaw / 各类 AI Agent 前端

本项目是国产 AI 算力在垂直教育场景的一次轻量级验证。我们以 MVP 闭环证明技术可行性，以开源姿态拥抱社区，希望向更多选手传递一个信念：在算法竞赛与个性化学习领域，中国开发者完全有能力用本土算力构建高质量工具。

从“算力奢侈品”到“普惠外置大脑”，变的是工具，不变的是对问题本质的追问与对代码的敬畏。
"Don't stop. Don't hide. Follow the light, and you'll find tomorrow."
—— 致每一位在调试中逼近真相的算法探索者，与国产 AI 生态共同前行的同路人。

---

📊 核心差异化：为什么需要它？

维度	公共题库知识图谱系统 (如 CPGraph)	🌟 AlgoNotes RAG (本项目)
数据源	网络题解 / 公开题库	用户私有笔记 (cnblogs / 洛谷 / 本地 Markdown)
核心价值	“找题”：相似推荐 / 题意查重 / 题单生成	“懂我”：个人思路还原 / 代码习惯审查 / 复健进度追踪
技术架构	Neo4j + FAISS 双层图向量库，部署重	Chroma + SQLite + 文件系统三层轻量存储，uv sync 零依赖启动
交互范式	结构化实体检索	自然语言问答 + 溯源引用 + 竞赛语境 Prompt 约束

✅ 场景互补：本项目不替代公共知识图谱，而是通过两者配合使用，以填补 “个人碎片化知识管理” 空白。适合高三后复健、省选/NOIP 备赛阶段的私有化认知加固。

---

🏗️ MVP 架构设计（v1.0 已实现）

当前版本聚焦 可验证的核心闭环，采用轻量级架构确保比赛周期内稳定交付：

graph LR
    A[原始笔记] --> B(Ingestion Pipeline)
    B -->|1. 存原始文件| C[(data/files/)]
    B -->|2. 记笔记索引| D[(data/sql_db/)]
    B -->|3. 分块向量化| E[(data/chroma_db/)]
    F[用户提问] --> G[RAG Agent]
    G -->|1. 查询理解| G
    G -->|2. 路由工具| H{工具选择}
    H -->|search_notes| E
    H -->|search_by_tags| D
    H -->|get_file_content| C
    E --> G
    D --> G
    C --> G
    G -->|3. generation 后处理| I[重排序 + 去重]
    I -->|4. 生成答案| J[答案 + 溯源引用]

模块	职责	实现方式
📥 Ingestion Pipeline	解析原始笔记 → 存原始文件 → 记笔记索引 → 分块打标 → 向量化入库	MarkdownHeaderTextSplitter 按标题分块 + RecursiveCharacterTextSplitter 大块二次分割 + 自动注入 source/type/ingested_at 元数据 + Chroma add_documents()
💾 三层存储	原始文件（data/files/）+ 关系索引（data/sql_db/）+ 向量库（data/chroma_db/）	文件原样保留 + SQLite 记录文件名/时间/关键词 + Chroma 持久化 · 详见 STORE.md
📝 RAG AGENT	理解问题，基于知识库检索并重排序，生成竞赛友好答案，强制溯源引用，支持流式输出	系统提示词规定流程 + tools 传入 + chain.stream()
📊 Performance Log	记录全链路耗时、Token 消耗、显存占用、检索命中率	logging 模块 + JSON Lines 格式 + LangSmith Trace 集成 + 自动计时器（time.perf_counter()）
🌐 MCP Server	暴露 ingest/update/delete/search 四类工具，供 AI 前端调用	src/mcp/ 模块，MCP 协议标准接口
📟 CLI	命令行工具集，覆盖笔记管理、语义查询、交互问答、MCP 启动	scripts/ 模块，argparse + Textual TUI

---

🚀 5分钟快速开始

1️⃣ 环境准备

git clone https://gitlink.org.cn/fangtianchen/algonotes_rag.git
cd algonotes_rag
uv sync

2️⃣ 配置沐曦算力 (Gitee.AI)

复制 .env.example 为 .env，填入 API Key，编辑 config.toml：

[llm]
model = "Qwen3-Next-80B-A3B-Instruct"     # 或 DeepSeek-R1，需要支持 function_call 的 llm
base_url = "https://ai.gitee.com/v1"
api_key = "${GITEE_API_KEY}"       # 不建议硬编码，建议引用 .env 中的变量

[embedding]
model = "Qwen3-Embedding-4B"
base_url = "https://ai.gitee.com/v1"
api_key = "${GITEE_API_KEY}"

💡 敏感信息不建议硬编码，可以在 config.toml 中使用 ${VAR} 语法动态替换。

3️⃣ 使用 CLI 或运行 MCP 服务

使用本项目，运行本项目 MCP 服务的方法：

# 导入笔记（从本地目录）
algonotes ingest -i ./my_notes/

# 更新笔记
algonotes update fenwick.md --file ./updated_fenwick.md

# 删除笔记
algonotes delete fenwick.md

# 查询笔记
algonotes query list

# 交互式问答
algonotes chat

# 启动 MCP 服务（供 AI 前端调用）
algonotes mcp

运行公开题库知识图谱 MCP 服务：

• CPGraph
• 或直接使用 https://mcp.cpgraph.top/mcp，见其官网文档

把两个 MCP 服务添加到你的 AI 前端（如 VS Code/Claude Code/Open Code/Codex），开始你的个人笔记管理之旅。

---

🤖 MCP 服务封装（比赛核心交付）

项目内置标准 MCP Server，按逻辑分类暴露以下四类工具供 AI Agent 调用（每类下可注册多个具体工具，具体见 mcp 文档）：

架构模块	MCP 工具分类	职责边界	前端 AI 调用时机
📥 Ingestion Pipeline	ingest	原始文本 → 存 data/files/ → 记索引到 data/sql_db/ → 分块/打标 → 入库 data/chroma_db/	用户导入新笔记时触发
📥 Ingestion Pipeline	update	定位旧笔记 → 覆盖文件/索引 → 删除旧向量 → 重新分块入库	用户修改推导过程、补充边界提示后触发
📥 Ingestion Pipeline	delete	从三层存储中同步删除文件/索引/向量	用户清理过期笔记、误导入内容后触发
🧠 RAG AGENT	search/ask/show/list/export	语义搜索 / RAG 问答 / 查看原文 / 列出笔记 / 导出笔记（不修改存储层）	用户提问、检索、查看、导出时触发

CLI 的使用方法与其类似，具体见文档。

---

📈 性能与验证数据

全程基于 沐曦 GPU (Gitee.AI) 真实调用，内置自动化日志收集，使用 LangSmith 观测数据：

指标	实测值 (v1.0)	记录方式
检索延迟	待测试	待记录
LLM 首字延迟	待测试	待记录
吞吐量	待测试	待记录
显存占用	待测试	待记录

📄 详细性能测试报告见 docs/PERFORMANCE_REPORT.md

---

🗺️ Roadmap：从 MVP 到个人知识引擎

本项目采用 分阶段交付 策略，确保核心价值先行，架构能力持续演进：

阶段	核心功能	状态	价值跃迁
v1.0 (MVP)	笔记摄取 + 知识图谱搜索 → 混合检索 → RAG 问答闭环 + CLI / MCP 封装	✅ 已实现	证明技术可行性，满足比赛可运行要求
v2.0 (Personalization)	TUI 交互界面、遗忘曲线、知识图谱可视化	规划中	从"问答工具"升级为"个人认知操作系统"

📖 完整 Roadmap 详见 docs/ROADMAP.md

---

📚 文档目录

文档	说明
ARCHITECTURE.md	架构说明与模块职责
CONFIG.md	配置文件说明
STORE.md	三层存储详解
RAG.md	RAG 查询管线详解
ROADMAP.md	项目路线图
cli/README.md	CLI 命令行工具

---

🤝 参考声明与合规说明

本项目严格遵守 CCF 开源创新大赛 规则，在以下方面参考了开源项目：

• 📖 参考 CPGraph 的 MCP 工具定义范式、工作流拆解思路与领域建模方法。
• 🔧 场景改造：从“公共题库管理”转向“个人笔记私有化问答”。
• 🛠️ 功能扩展：新增竞赛语境 Prompt 约束、代码规范审查模块、复健进度追踪接口。
• ⚖️ 架构简化：由于个人笔记的结构相对简单，用 Chroma 向量库 + SQLite 索引 + 文件系统三层轻量存储替代 Neo4j 图数据库，降低部署门槛，确保比赛环境零依赖可运行。

本项目所有核心代码（摄取/检索/生成/MCP封装）均为原创实现，仅借鉴架构思想与接口契约。

---

📜 License

MIT License. 欢迎 Fork、Issue、PR。
竞赛生专属优化建议请直接提交 Issue，我们将优先排期。

---

📺 演示视频

待录制