# 考研数学辅导系统 v1 设计

最后更新: 2026-05-28
目标: 数学二 / 目标 120 分 / 距考试 200 天

---

## 一句话

TG 是接口，Claude Code 是大脑，错题本是 markdown 文件，自我迭代是即时可改的指挥棒。

## 核心原则（硬约束 MUST）

1. **解题不归我管** —— 用户已有小程序拿标准答案；我的价值是"记录 + 串联 + 扩展 + 讲透"
2. **GLM/Hermes 不讲题** —— 智力降级红线；Hermes 只做 router，所有讲解走 Claude Code
3. **WORKFLOW.md 是流程 single source of truth** —— Hermes math-tutor skill 启动时读、Claude Code 启动时也读，两边共享同一份指挥棒
4. **狠改不留兼容** —— 起步阶段历史包袱轻，发现更好的形态立刻改，不为兼容性妥协
5. **Source of truth = Mac** —— 所有数据真理在 Mac `~/MyProjects/compass/math/`，HK 是 git mirror

## 默认建议（SHOULD，违反需理由）

- 错题一题一文件（不是一章一文件）
- markdown + frontmatter（不是 SQLite/JSON）
- 知识点 taxonomy 用文件夹路径（天然多级）
- 知识点按需创建（不预建数二全考纲空壳）
- SRS 用 Leitner 盒（简单可靠，不上 Anki SM-2）

---

## 架构

```
你 (手机)
  │ 拍照 + "这题我错了，哪步开始懵..."
  ▼
TG @nate_hermes_001_bot
  │
  ▼
┌──────────────────────────────────────────────────────────┐
│  HK 149.104.29.83 — Hermes Agent (GLM-5.1)               │
│  └─ skill: learning/math-tutor (新写, profile-scoped)     │
│     ├─ 收图 → 存 /opt/share/math/inbox/                   │
│     ├─ 触发 autonomous-ai-agents/claude-code skill:       │
│     │    ssh nate@<mac> "claude -p '处理 inbox 新题' \    │
│     │                    --workdir ~/MyProjects/compass/math │
│     │                    --allowedTools Read,Edit,Bash"   │
│     ├─ 拿回 Claude 回答 → 转发到 TG                       │
│     ├─ Mac 不在线 → "Claude 不在，先存着等回来"             │
│     └─ 识别到 #改 hashtag → 走自我迭代流（见下）           │
└──────────────────────┬───────────────────────────────────┘
                       │ git push/pull (Mac 是 source of truth)
                       ▼
┌──────────────────────────────────────────────────────────┐
│  Mac ~/MyProjects/compass/math/  ← 真正干活的地方         │
│  └─ Claude Code (我)                                      │
│     ├─ 识别题面（OCR + 兜底反问澄清）                       │
│     ├─ 讲解（断点 + 错因分析 + 易混点）                     │
│     ├─ 归档错题到 mistakes/YYYY/MM/MMDD-XXX.md            │
│     ├─ 挂知识点 + 错因 tag                                │
│     ├─ 更新对应知识点页的反向引用                          │
│     ├─ git commit & push → HK                            │
│     └─ HK post-receive hook → checkout /opt/share/math/   │
│                                                          │
│  浏览入口：https://share.rusti.cc/math/ (自动索引)         │
└──────────────────────────────────────────────────────────┘
```

---

## 目录结构

```
~/MyProjects/compass/math/
├── DESIGN.md           # 本文件（一次性架构设计）
├── WORKFLOW.md         # 当前流程版本（活的，会被反馈改）
├── CHANGELOG.md        # 流程改动日志
├── README.md           # share.rusti.cc/math/ 着陆页
│
├── inbox/              # HK 拉过来的待处理原图（处理完移走）
│
├── mistakes/           # 错题本（一题一文件）
│   └── 2026/
│       └── 05/
│           ├── 0528-001.md
│           └── 0528-001.jpg
│
├── kp/                 # 知识点 taxonomy（按需创建）
│   ├── INDEX.md        # 数二全考纲骨架（含未建节点）
│   ├── 高数/
│   │   ├── 极限.md
│   │   └── 不定积分/换元积分法.md
│   └── 线代/
│       └── 特征值.md
│
└── dashboard.md        # 进度看板 (v0.2 加)
```

## 错题文件 schema

```markdown
---
id: 0528-001
date: 2026-05-28
kp: [高数/不定积分/换元积分法/三角代换]
errors: [思路错]        # 概念错 / 思路错 / 计算错 / 表达错
srs: { box: 1, next: 2026-05-30 }   # v0.2 加
source: 张宇1000题 P45 第3题
related: [0521-003]     # 双链到相似题
image: 0528-001.jpg
---

## 题面
（OCR + 我修正后的文本）

## 你的做法
（你的解题步骤）

## 错在哪
（具体哪一步、为什么错）

## 正确思路
（关键转折点 + 完整推导）

## 易混点 / 同类题
（这道题踩的坑 / 历史相似错题链接）
```

## 知识点页 schema

```markdown
---
name: 换元积分法
parent: 高数/不定积分
related: [高数/不定积分/分部积分法, 高数/定积分/换元法]
---

## 核心要点
（一句话总结这章是干啥的、和别的方法的边界）

## 常见考点
- 三角代换（√(a²-x²), √(a²+x²), √(x²-a²)）
- 倒代换
- ...

## 错题反向引用（自动维护）
- [[0528-001]] 三角代换符号搞错
- [[0521-003]] 倒代换没想到
```

---

## 核心循环

### 主循环：拍题 → 讲 → 归档

1. **你 TG 拍题** + 一两句话（"这题我做完对答案错了，从第二步开始懵"）
2. **Hermes 收图存** `/opt/share/math/inbox/<timestamp>.jpg` + 你的描述存同名 `.txt`
3. **Hermes ssh Mac**：`claude -p "inbox 里有新题，按 WORKFLOW.md 处理" --workdir ~/MyProjects/compass/math`
4. **Mac Claude Code**（我）：
   - 读 inbox 新文件
   - OCR 题面 → 不清楚就让 Hermes 反问你（"第三行那个分式分子是 x² 还是 x³？"）
   - 读你的描述 → 定位错因类型（概念/思路/计算/表达）
   - 写 `mistakes/YYYY/MM/MMDD-XXX.md`
   - 创建/更新对应 `kp/` 知识点页 + 反向引用
   - 找历史相似题（grep frontmatter 的 kp + errors）
   - 把题从 inbox 移到 `mistakes/YYYY/MM/` 旁边
   - git add + commit
   - 输出给 Hermes：讲解 + "这块薄了，相关错题还有 N 道：[link]" + "已归档"
5. **Hermes** push → HK + 把讲解转回 TG
6. **HK post-receive hook** checkout 到 `/opt/share/math/`（自动）

### 自我迭代循环：TG 反馈 → 流程演化

1. 你 TG 发 `#改 以后讲完先标知识点再写讲解` 或 `#改：错因分类加一档"审题错"`
2. Hermes 识别 hashtag → 触发 Mac Claude Code 处理反馈
3. Claude Code（我）：
   - 读 `WORKFLOW.md` 当前内容
   - 理解反馈意图，改 `WORKFLOW.md`（或 Hermes skill prompt，必要时）
   - append 一条到 `CHANGELOG.md`：日期 + 反馈原文 + diff 摘要
   - git commit + push
   - 输出 diff 给 Hermes → 转回 TG："已改，diff:[link]，明天起按新流程跑"
4. 你 review，不行就再发 `#改 撤销` 或 `#改 这样改：...`

### Mac 离线兜底

- Hermes 试 ssh Mac，5 秒超时 → 标记 Mac offline
- 图片仍存 inbox + 描述存同名 .txt
- TG 回："Claude 不在，已存第 N 题待回。在线后会主动通知。"
- Mac 上线后：Claude Code 启动时（你 `cd math/ && claude` 或日常用 Claude Code）扫 inbox，发现待处理的题就提示你"有 N 道待处理"，你 yes 就批量过

---

## v1 / v1.x 边界

### v1（一次做完）

- TG → inbox → Mac Claude Code 主循环
- `mistakes/` + `kp/` 文件结构 + 错题/知识点 schema
- `WORKFLOW.md` 作为流程指挥棒（Hermes skill + Mac Claude Code 都读）
- git Mac ↔ HK 同步 + share.rusti.cc/math/ 浏览
- 自我迭代即时反馈流（`#改` hashtag）
- Mac 离线兜底
- HK 上 mirror `claude-code` skill 到 telegram_bot profile
- HK 上写新 skill `learning/math-tutor`

### v1.x 之后（独立可分批做）

- **v1.1 SRS 提醒**：独立 cron 任务，扫 frontmatter 的 srs.next，到点 TG 推"今天复习 N 道"
- **v1.2 进度看板**：聚合脚本生成 dashboard.md（最近 7/30 天错题分布、薄弱章节排行、错因 trend）
- **v1.3 Hindsight 索引**：归档时 hook 一条 POST 到 hindsight bank=`math`，跨 TG 对话向量检索"我以前问过类似题没"
- **v1.4 定期复盘 subagent**：每周末 / 每 N 道题，subagent 扫 mistakes + 反馈历史，产 `reviews/YYYY-MM-DD.md` 提改进点，你 review

---

## 数据流与权威

| 数据 | 权威位置 | 副本 | 同步机制 |
|------|---------|------|---------|
| 错题 markdown + 原图 | Mac `~/MyProjects/compass/math/mistakes/` | HK `/opt/share/math/mistakes/` | Mac git push → HK post-receive checkout |
| 知识点 taxonomy | Mac `kp/` | HK `kp/` | 同上 |
| WORKFLOW.md / CHANGELOG.md | Mac | HK + Hermes skill 启动时读 | 同上 |
| 待处理原图 | HK `/opt/share/math/inbox/` | Mac inbox/ | Mac 主动 ssh 拉（处理完删 HK 原件） |
| Hermes skill（math-tutor） | HK `/root/.hermes/profiles/telegram_bot/skills/learning/math-tutor/` | Mac `hermes-skills/learning/math-tutor/` 镜像 | Mac 改完 scp 推 + ssh restart 服务 |

---

## 不做的（YAGNI）

- 真题/模拟题/习题分层 → 等真要分了再加 frontmatter 字段
- 整卷模式 → 一题一图按顺序拍就行
- 讲解档位（只要思路 / 详细推导 / 拓展）→ 你需要时直接说"再展开"，不需要预设档位
- 学习计划/排课 → 你的备考节奏自己定，我不当班主任
- 卡壳点 vs 会但算错分离 → 错因 4 分类已经覆盖（思路错 vs 计算错）
- 公开题库爬取 → 版权 + 不可控，永远不做

---

## 开放问题（v1 实施时还要确认）

- HK 上 git 远端形态：bare repo `/opt/git/math.git` + post-receive hook checkout 到 `/opt/share/math/`？还是 `/opt/share/math/` 直接是 working tree？前者干净，后者省一步。
- Mac ssh 通路：用 Tailscale IP（如果 Mac 有 Tailscale）还是公网 + 端口转发？影响 Hermes skill 里的 ssh 配置。需要查 Mac 的 Tailscale 状态。
- `claude -p` 是否支持图片输入：如果支持，可以不传 inbox 路径直接传 base64；如果不支持，必须走文件系统中转（推荐方案）。需要查 Claude Code 文档。
- 自我迭代改 Hermes skill 时：Mac 改完 push → HK pull → restart hermes-gateway-telegram_bot。这条链谁执行？放在 Mac Claude Code 的"改完自动执行"，还是 Hermes 收到反馈后自己 pull？前者简单。

这些不阻塞 design 通过，写 implementation plan 时再敲定。