活书 huoshu 📚

把教材变成可交互知识图谱的自学工具 — Knowledge Graph × Adaptive Learning × RAG × Spaced Repetition

中文名「活书」：教材不再是线性翻页，而是可导航、可追问、可复习的活的知识网络。

🎯 项目简介

活书（huoshu）是一个把教材变成可交互知识图谱的自主学习工具。它将任意教材内容抽取为原子知识点，在知识图谱中建立前置/相关关系，结合 IRT 自适应掌握度模型、SM-2 间隔复习和 RAG 教材检索，实现个性化的 Socratic 式学习闭环。

核心理念

• 📚 教材是根：每个知识点锚定教材原文（页码/章节），LLM 解释但不凭空编造
• 🧭 图谱导航：前置依赖边告诉你先学什么，相关边帮你建立横纵联系
• 🧠 自适应掌握：IRT 2PL 模型追踪每个知识点的掌握度，黑箱（会用）vs 白箱（深入理解）区分要求
• 🔁 间隔复习：基于 SM-2 的智能复习调度，弱项回炉、强项长周期
• 🤖 LLM 教学：DeepSeek/OpenAI/Ollama 可配置，Socratic 引导优先，不灌答案

✨ 功能

🏗️ 架构

huoshu/
├── src/learning_agent/
│   ├── core/           # 数据层: 图谱加载/校验/导航, IRT 掌握度, SM-2 调度
│   │   ├── graph.py    # Bookmap 知识图谱
│   │   ├── mastery.py  # IRT 2PL 掌握度模型
│   │   └── scheduler.py # SM-2 间隔复习调度
│   ├── rag/            # RAG 教材检索
│   │   ├── ingest.py   # PDF 解析+分块+ChromaDB 入库
│   │   ├── retrieve.py # 语义检索+页码引用
│   │   └── cli.py      # CLI 验证入口
│   ├── ui/             # UI 层 (纯逻辑引擎 + Streamlit 页面)
│   │   ├── graph_renderer.py  # Bookmap → vis.js 转换
│   │   ├── study_engine.py    # 学习会话引擎
│   │   ├── review_engine.py   # 复习引擎
│   │   ├── pages_graph.py     # 图谱可视化页
│   │   ├── pages_study.py     # 学习会话页
│   │   ├── pages_search.py    # 教材检索页
│   │   └── pages_review.py    # 间隔复习页
│   ├── llm.py          # LLM 客户端 (DeepSeek/OpenAI/Ollama)
│   └── data/           # 数据工具
├── tests/              # 295 tests
├── examples/           # 示例图谱
└── pyproject.toml

🚀 快速开始

环境要求

• Python ≥ 3.12
• Ollama (本地 embedding/LLM，可选)

安装

git clone https://github.com/MXC-CKK/huoshu.git
cd huoshu
pip install -e .

配置 LLM（可选，用于 Socratic 教学和智能出题）

# DeepSeek（默认）
export LLM_API_KEY=sk-your-deepseek-key

# 或 OpenAI
export LLM_PROVIDER=openai
export LLM_API_KEY=sk-your-openai-key

# 或 Ollama 本地（无需 API key）
export LLM_PROVIDER=ollama

LLM 未配置时，学习和复习功能仍可用（自动降级为模板引导和关键词判分）。

启动

# 图谱可视化
streamlit run src/learning_agent/ui/pages_graph.py

# 学习会话
streamlit run src/learning_agent/ui/pages_study.py

# 间隔复习
streamlit run src/learning_agent/ui/pages_review.py

# PDF 入库 + 检索（CLI）
python -m learning_agent.rag.cli ingest textbook.pdf --name mybook
python -m learning_agent.rag.cli search "大数定律证明" --name mybook

# 教材检索页（Streamlit UI）
streamlit run src/learning_agent/ui/pages_search.py

运行测试

pip install -e ".[dev]"
pytest tests/ -v

📖 使用指南

1. 准备图谱文件

按照 bookmap-schema.json 格式创建知识图谱 JSON，或使用 examples/demo-math.json 快速体验。

2. 图谱浏览

打开图谱可视化页，选择 bookmap JSON 文件：

• 🟦 蓝色节点 = 白箱（深入理解），🟨 琥珀节点 = 黑箱（会用即可）
• 边框粗细 = 掌握度（越粗越稳）
• 搜索知识点 → 查看前置链、相关概念、教材锚点

3. 学习

在学习会话页中：

• 设定学习目标，系统推荐入口
• 下钻知识点时自动保存 breadcrumb，随时返回
• 提问时 LLM 用 Socratic 方法引导，锚定教材原文

4. 教材检索

在教材检索页中（需本地运行 Ollama）：

1. 将 PDF 教材放入 ~/.huoshu/pdf/（可通过 HUOSHU_PDF_DIR 环境变量修改）
2. 切换到「📥 入库」Tab，选择 PDF → 设置分块参数 → 点击入库
3. 切换到「🔍 检索」Tab，输入自然语言问题 → 查看原文段落及页码引用
4. 可在「🗂 集合管理」Tab 查看统计信息或删除不再需要的集合

5. 复习

在复习页中：

• 系统自动筛选到期知识点
• 按掌握度自适应出题（基础→理解→应用）
• 答题后自动更新掌握度并重排复习日期

🔬 技术选型

📸 截图

📝 待补充：图谱页、学习会话页、复习页运行截图。

📄 许可

MIT License — 详见 LICENSE。

🙏 致谢

• 参考设计：benkyo（MIT）
• 图谱格式受 learning-agent 启发