内容
# AnNuMa 学习伴侣
一款基于 AI 的学习代理，通过 **主动回忆** 的方式，对学生进行 **AnNuMa**（分析与数值数学）测验，题目均来自 **已验证的讲义材料**，而非模型自身的记忆。代理可以读取学习材料，但结构上被阻止修改。
为 *Agents for Good* 赛道而建：改善教育。
---
## 为什么存在
两个问题使得使用普通聊天机器人进行考试准备存在风险：
1. **幻觉**。对于数学考试，一个编造的公式是有害的。普通的聊天机器人无法保证其答案与您的课程匹配。
2. **被动复习效果差**。重新阅读总结会导致记忆效果不佳。学习科学表明，**主动回忆**（从记忆中检索答案）比被动复习更有效。
AnNuMa 学习伴侣解决了这两个问题：它通过 **主动回忆** 的方式进行测验，仅使用从已验证的知识库中检索的内容（无幻觉），并且无法损坏该知识库（仅可读）。
---
## 展示的课程概念
该项目展示了四个课程概念，每个概念都是承载而非装饰性的：
| # | 概念 | 位置 |
| - | ------- | ----- |
| 1 | **MCP 服务器** | `mcp_server.py` 将知识库暴露给代理，提供两个工具：`list_topics` 和 `query_annuma`。 |
| 2 | **安全 / 限制** | `is_read_only()` 拒绝任何非 `SELECT` 查询。代理可以读取但无法 `INSERT`、`UPDATE`、`DELETE` 或 `DROP`。 |
| 3 | **代理技能** | `skills/active-recall/SKILL.md` 定义了回忆循环和严格的接地规则（问题和判断仅使用检索的材料）。 |
| 4 | **LLM 作为裁判** | 网页应用通过数学含义而非精确字符串匹配来评估输入答案，返回判决、分数和接地反馈。 |
概念 1-3 是核心课程要求；**LLM 作为裁判** 是第四个超越最低要求的概念。
---
## 架构
```
┌─────────────────────────┐
│ knowledge.db (SQLite) │ 55 个子主题，V1–V19
│ 由 build_db.py 构建 │ (德语学习内容 +
└────────────┬────────────┘ 英语 Q/A 每行)
│ 每个访问都是 SELECT-only
┌─────────────┴──────────────┐
│ is_read_only() 限制 │ 共享安全规则
└─────────────┬──────────────┘
┌──────────┴───────────┐
│ │
┌────────┴────────┐ ┌────────┴─────────┐
│ mcp_server.py │ │ app.py │
│ (代理层) │ │ (网页层) │
│ │ │ │
│ list_topics │ │ Flask + LLM 作为 │
│ query_annuma │ │ 裁判 + KaTeX + │
│ → 任意 MCP 主机 │ │ 连击 / 经验 │
└─────────────────┘ └──────────────────┘
```
两个接口都通过相同的 `is_read_only()` 限制读取 **相同的** `knowledge.db`，因此安全保证无论如何访问知识库都成立。
---
## 仓库布局
```
annuma-study-companion/
├── build_db.py # 构建 knowledge.db（55 个子主题，V1–V19）
├── knowledge.db # 预建的 SQLite 知识库
├── mcp_server.py # MCP 服务器：list_topics + query_annuma（只读）
├── app.py # Flask 网页应用（LLM 作为裁判，连击/经验，复习模式）
├── templates/
│ └── index.html # 单页网页 UI（KaTeX 数学渲染）
├── skills/
│ └── active-recall/
│ ├── SKILL.md # 主动回忆代理技能
│ └── scripts/
│ └── format_flashcard.py
└── spec.md # 规格优先设计文档（Gherkin 场景）
```
---
## 快速开始
### 0. 要求
- Python 3.10+（`mcp` 包需要；推荐 3.12）
- 终端
克隆，创建虚拟环境，并构建知识库：
```bash
git clone https://github.com/AlirezaFakari/annuma-study-companion.git
cd annuma-study-companion
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt # 或：pip install flask google-genai python-dotenv mcp
python build_db.py # 创建 knowledge.db（打印 55 个主题）
```
---
### A. 运行网页应用（推荐 — 最容易试用）
网页应用有两种模式，**可降级**，因此无论是否有 API 密钥，都可以正常运行。
#### 智能模式（使用免费的 Gemini API 密钥）
1. 在 <https://aistudio.google.com/apikey> 获取免费密钥。
2. 在项目根目录下创建 `.env` 文件：
```bash
echo "GEMINI_API_KEY=YOUR_KEY_HERE" > .env
```
3. 运行：
```bash
python app.py
```
4. 打开 <http://127.0.0.1:5001>。
您将看到 **AI 辅导：开启**。选择一个主题；辅导员会根据已验证的材料编写问题，您输入答案（用普通语言），然后由 **LLM 作为裁判** 进行评估，返回判决、分数和接地反馈。数学由 KaTeX 渲染。正确答案会建立 **连击** 和 **经验**；错误答案会进入 **“复习弱项”** 队列。
#### 静态模式（无需密钥）
只需跳过 `.env` 步骤并运行 `python app.py`。徽章显示 **静态模式**：每个主题都会显示一个存储的问题，提交后会显示参考答案以进行自我评估。这保证了项目始终可运行，即使没有密钥。
> 注意：免费的 Gemini 层有每分钟限制，偶尔会忙碌（HTTP 429/503）。应用会检测到此情况并显示清晰的 **AI 辅导忙碌** 消息以及参考答案，而不是失败。
---
### B. 运行 MCP 服务器（代理层）
MCP 服务器将知识库暴露给任何 MCP 兼容的主机（例如代理 CLI）。在主机配置文件中注册它，指向虚拟环境中的 Python 解释器：
```json
{
"mcpServers": {
"annuma-study-companion": {
"command": "/absolute/path/to/annuma-companion/venv/bin/python",
"args": ["/absolute/path/to/annuma-companion/mcp_server.py"]
}
}
}
```
然后，在代理中，询问它使用工具 — 例如：
> *"使用 annuma-study-companion 工具，测验我关于几何级数的知识。首先检索材料，然后问我一个问题，并等待我的答案。"*
代理将调用 `query_annuma`（只读 `SELECT`），提出一个基于检索内容的接地问题，等待并评估您的答案。
---
## 只读保证（如何验证）
限制是安全核心。任何非 `SELECT` 查询在到达数据库之前都会被拒绝：
```python
def is_read_only(query: str) -> bool:
return query.strip().upper().startswith("SELECT")
```
您可以确认：通过任一接口，`SELECT` 返回行，而 `DROP TABLE knowledge`、`DELETE ...` 或 `UPDATE ...` 被拒绝，数据库保持不变。
---
## 知识库
`knowledge.db` 包含 **55 个聚焦的子主题**，涵盖整个课程（讲座 **V1–V19**）：逻辑和集合、序列和级数及其收敛准则、指数函数、连续性、微分和积分、复数、机器数和误差分析、插值和样条曲线，以及函数级数（泰勒、傅里叶、DFT/FFT）。
每一行存储德语学习内容（与课程相同）以及回忆问题和答案。将每个讲座分成聚焦的子主题，让代理可以提出精确的问题而不是模糊的问题。
要重建或扩展它，请编辑 `build_db.py` 并重新运行 `python build_db.py`。
---
## 设计笔记
- **自包含数据**。选择 SQLite 而不是实时笔记连接，以便项目可以被审查者完全复制，而无需外部账户。
- **规格优先**。`spec.md` 描述了问题、三个概念和四个 Given/When/Then 场景，这些场景是实现遵循的。
- **接地高于一切**。每个问题和判断都基于检索的内容。如果知识库缺乏某些内容，代理会说明，而不是编造答案。
---
## 许可证
为 capstone 提交提供。学习内容源自作者自己的 AnNuMa 课程笔记。
