活书 huoshu 📚

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

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

📖 新手上路？先看 使用教程 — 5 分钟上手 + 完整功能指南 + 配置参考 + 常见问题

🎯 项目简介

活书（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 验证入口
│   ├── build/           # AI 图谱构建
│   │   └── graph_builder.py  # LLM 驱动的 PDF→bookmap 构建器
│   ├── ui/             # UI 层 (纯逻辑引擎 + Streamlit 页面)
│   │   ├── graph_renderer.py  # Bookmap → vis.js 转换
│   │   ├── study_engine.py    # 学习会话引擎
│   │   ├── review_engine.py   # 复习引擎
│   │   ├── pages_builder.py   # AI 建图谱页
│   │   ├── pages_graph.py     # 图谱可视化页
│   │   ├── pages_study.py     # 学习会话页
│   │   ├── pages_search.py    # 教材检索页
│   │   ├── pages_review.py    # 间隔复习页
│   │   └── pages_settings.py  # 模型设置页
│   ├── llm.py          # LLM 客户端 (DeepSeek/OpenAI/Ollama)
│   └── data/           # 数据工具
├── tests/              # 364 tests
├── examples/           # 示例图谱
└── pyproject.toml

🚀 快速开始

环境要求

• Python ≥ 3.12
• Ollama — 教材检索（embedding）与本地 LLM 需要；图谱/学习/复习页不依赖

安装（二选一）

方式 A：pip 安装（推荐，开箱即用）

pip install learning-agent

装好后 huoshu 命令直接可用。

方式 B：源码运行（开发者）

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

💡 Windows 用户：把 export 换成 set（PowerShell 用 $env:LLM_API_KEY="..."）。 更简单的方式：在应用内「⚙️ 模型设置」页填写，保存后立即生效，无需碰环境变量。

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

启动

huoshu

• 浏览器自动打开 http://localhost:8501（未自动打开则手动访问该地址）
• 端口被占用时指定端口：huoshu --server.port 8600
• 源码方式两条路都行：huoshu 或 streamlit run src/learning_agent/main.py
• 使用虚拟环境（venv/conda）的记得先激活：Linux/macOS source .venv/bin/activate；Windows .venv\Scripts\activate

启动后通过左侧边栏在 6 个页面间切换：

首次使用 Checklist

1. 配置 LLM（AI 建图谱必需）：设置页填 DeepSeek API Key + 测试连接；模型推荐 deepseek-chat（非推理，快且稳；推理模型如 deepseek-reasoner 建图谱会很慢）
2. 准备教材 PDF：打开检索页直接拖拽上传 PDF（推荐）；也可手动放入 ~/.huoshu/pdf/（Windows: C:\Users\<你>\.huoshu\pdf\）
3. 生成图谱：AI 建图谱页 → 选 PDF → 选目标 → 点生成（实时进度可见，生成前会预估调用次数）→ 校对 → 保存（图谱页/学习页/复习页立即可用）
4. Ollama 就绪（教材检索需要）：启动 Ollama 后运行 ollama pull nomic-embed-text

学习时补充图谱

基础图谱建好后，学习过程中遇到新概念：学习会话页 → 点「➕ 补充新知识点」→ 输入名称与描述、选择与当前知识点的关系 → AI 自动抽取结构化字段并加入图谱，保存后图谱页立即可见。图谱随学习持续完善，无需重新建整本。

单页独立启动（高级用法）

streamlit run src/learning_agent/ui/pages_builder.py  # AI 建图谱
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   # 间隔复习
streamlit run src/learning_agent/ui/pages_search.py   # 教材检索

CLI 操作（无需 UI 的 RAG 入库/检索）

python -m learning_agent.rag.cli ingest textbook.pdf --name mybook
python -m learning_agent.rag.cli search "大数定律证明" --name mybook

运行测试

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. 切换到「📥 入库」Tab → 拖拽上传 PDF（推荐），或从已放入 ~/.huoshu/pdf/ 的目录中选择
2. 设置集合名称和分块参数 → 点击入库（自动向量化存入 ChromaDB）
3. 切换到「🔍 检索」Tab，输入自然语言问题 → 查看原文段落及页码引用
4. 可在「🗂 集合管理」Tab 查看统计信息或删除不再需要的集合

5. 复习

在复习页中：

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

🔬 技术选型

📸 截图

📊 知识图谱

📖 学习会话

🔁 间隔复习

截图来自 v0.1.x；📖 教材检索页截图待补充。

📄 许可

MIT License — 详见 LICENSE。

🙏 致谢

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