kaoyan-mcp

把「知识库 + 间隔复习 + 出卷打印 + 学习算法」封装成 MCP 工具，任何支持 MCP 的 AI 客户端（Claude Desktop、Cursor、Codex 等）都能直接调用。

它要解决的是陪学 AI 最要命的那个毛病：聊完就忘。这次讲明白了，下次它并不知道你哪块虚。 这个服务把学习状态落到你本地的文件里，AI 每次通过工具读状态、写判定，于是「越用越准」是能被回测验证的，而不是嘴上说说。

零第三方依赖（只用 Python 标准库，Python 3.9+ 即可），内容与个人数据都在你自己的目录里，默认不出本地。

仓库自带的内容包目前覆盖 11408（考研数学一 + 408），知识库随仓库一起分发；换考试方向只要换一个内容包，引擎不用动。

目录

• 它由什么组成

• 快速开始

• 内容包（知识库随包分发）

• 接到 AI 客户端

• 没有打印机也能用

• 工具清单

• 工作区布局

• 知识库格式契约

• 质量门禁

• 学习算法

• 配置

• 开发

• 许可

Related MCP server: fakao-mcp

它由什么组成

四层，都能单独用：

1. 知识库：一章一个 markdown 文件，里面两张表——原子表（最小可得分单元）与组合表（考点怎么拼成一道题）。带出处页锚、掌握状态与证据。

2. 复习调度：遗忘曲线档位 1/2/4/7/15/30/60 天，分 A/B/C 三层并限每日配额，按分值档 → 弱度 → 逾期排序取用。

3. 出卷与交付：题目与答案分离；卷面渲染成 A4/A5/Letter 的 HTML，再按本机能力交付——能打印就打印，不能就退成 PDF、HTML、纯文本。

4. 学习算法：能力与难度做 MAP 拟合，参数化到「原子 / 档位 / 科目 / 遗忘 / 同日复测」；预测先写日志、答完做走前回测，另有混淆模式风险、讲法排名与模型变体消融。

快速开始

需要 Python 3.9 或更新版本。

git clone https://github.com/hanserdesu/kaoyan-mcp.git
cd kaoyan-mcp
pip install -e .

铺一个空工作区：

python -m kaoyan_mcp init ./我的备考
cd 我的备考

再把自带的内容包装进来（不装也能跑，只是知识库是空的，见下一节）：

python -m kaoyan_mcp pack list                         # 看仓库自带哪些内容包
python -m kaoyan_mcp pack install 11408 --into .       # 把 11408 知识包装进当前工作区

看看这台机器能干什么、知识库健不健康：

python -m kaoyan_mcp capabilities          # 打印机 / 浏览器 / 可用通道
python -m kaoyan_mcp overview              # 科目、章节、原子、状态分布
python -m kaoyan_mcp validate              # 质量门禁
python -m kaoyan_mcp due                   # 今天到期的复习项
python -m kaoyan_mcp plan                  # 今日计划

工作区不用每次指定：从当前目录逐级向上找 kaoyan.config.json 或 知识库 目录；也可以用 --root 或环境变量 KAOYAN_ROOT 指定。

内容包（知识库随包分发）

引擎、内容、个人数据是三样东西：kaoyan_mcp 是引擎，packs/<名字>/ 是内容包，学习状态存在你自己的工作区里。换考试方向等于换包，代码不动。

仓库自带一个包：

出处一律用教材 PDF 页锚，状态全部从 ⬜ 起步——个人掌握进度不进包，你在自己的工作区里积累。

python -m kaoyan_mcp pack list                    # 列出自带包（含 schema_version）
python -m kaoyan_mcp pack install 11408 --into ./我的备考
python -m kaoyan_mcp pack verify 11408            # 只读门禁：FAIL / WARN 逐条列出

装包做两件事：把 packs/<名字>/ 复制进工作区，并把 kaoyan.config.json 的 pack 指向它。包里的 kb_dir 声明知识库位置，于是知识库随包走；个人数据（状态、复习队列、事件流、试卷）留在工作区，不会被包覆盖。

工作区里已经写过章节时默认拒绝装包：加 --force 才覆盖，或在配置里用 dirs.kb 指定自己的知识库目录。

加一个方向不用改引擎，照这个契约放一份目录就行：

packs/<名字>/
  pack.json      # schema_version / name / title / exam / subjects / books / kb_dir
  kb/            # 知识库：一章一个 markdown，格式见下文

schema_version 是留给以后换版的兼容位：引擎读得懂自己支持的版本；遇到比它新的包会直接报错让你升级引擎，而不是猜着读。目前 11408 是唯一随仓库分发的包。

接到 AI 客户端

服务走 MCP 的 stdio 传输。典型配置：

{
  "mcpServers": {
    "kaoyan": {
      "command": "python",
      "args": ["-m", "kaoyan_mcp", "serve", "--root", "/绝对路径/我的备考"]
    }
  }
}

Windows 上把 python 换成 python.exe 的绝对路径更稳；也可以不写 --root，改成给客户端设一个 KAOYAN_ROOT 环境变量。

除了工具，服务还带 4 段提示词（teaching / grading / modeling / paper），客户端支持提示词时可以直接取用——里面写的是教学与判卷的口径，比如「先考后讲、逐点推进」「按过程判、断哪讲哪」「出处必须可定位」。

没有打印机也能用

同一个出卷工具，按本机探测到的能力自动选通道。交付策略写在配置里：

通道与探测方式：

capabilities 会把探测结果和「这条通道为什么不可用」一次说清，例如缺少 SumatraPDF 时会直接告诉你装什么，而不是静默失败。

打印的两条硬规矩：一是虚拟打印机不算打印机——OneNote、Microsoft Print to PDF、Fax 这类设备出不了纸，不会被自动选中，机器上只有这类设备时 capabilities 会直接说明，你要用就自己在 config 里写 deliver.printer；二是页数超估算不出纸——渲染出来比版面预算多页，就先退回 PDF 让你压缩书写区，不浪费纸（print_strict 下直接报错）。

工具清单

同一个引擎也有一套等价的命令行入口，方便不开客户端时直接跑，或写进脚本：

python -m kaoyan_mcp search 分布函数法
python -m kaoyan_mcp chapter 概率论 第02讲
python -m kaoyan_mcp grade GL-02-021 ✅ --mode CM-02
python -m kaoyan_mcp predict --next
python -m kaoyan_mcp paper 卷子.json --policy html
python -m kaoyan_mcp report --write
python -m kaoyan_mcp pack list
python -m kaoyan_mcp pack install 11408 --into ./我的备考
python -m kaoyan_mcp pack verify 11408

工作区布局

kaoyan_mcp init 会铺出这样一套目录，每一块的职责都不重叠：

知识包和个人数据是分开的：包可以分享给别人，个人数据（状态、队列、事件流）默认留在本地。

知识库格式契约

原子表按最小可得分单元切分，组合表记录考点是怎么拼成题的：

| ID | 原子知识点 | 档 | 得分范式 | 出处 | 状态 | 证据 / 备注 |
|---|---|---|---|---|---|---|
| GL-02-001 | 分布函数法：F_Y(y)=P(g(X) ≤ y) | S | M-构造 | §2.4@p57 | ⚠️ | 【实测 2026-09-13】方向反，已直讲 |

| ID | 组合模式 | 原子链 | 题目形态 | 断点 | 真题锚点 |
|---|---|---|---|---|---|
| C-GL-02-01 | C2 多考点串联 | GL-02-001 → GL-02-002 | 解答题 | GL-02-001（翻译即错） | 2015 真题 |

• ID 命名：原子 <科目码>-(NN|AP)-<三位序号>，组合 C-<科目码>-(NN|AP)-<两位序号>。删除即作废、留「作废」字样，不用改号补位。

• 档位：S / A / B（高频深度 / 常规 / 边角），决定复习配额与出卷优先级。

• 状态：✅ 掌握 / ⚠️ 不稳 / ❌ 薄弱 / ⬜ 未考察。

• 出处：统一用 PDF 页锚 @pNNN，可加节号；不写「大概某页」。

• 证据纪律：【实测】 与 【建模推演】 分开标；没实测过的不许写「已掌握」。写「已讲未验收」这类免责说明的记录，状态仍应是 ⬜。

• 得分范式：数学用 M-*，408 用 S-*，门禁会检查范式前缀与学科是否匹配。

质量门禁

kb_validate 把「写得对不对、引用通不通、账对不对得上」变成可执行判据，并且只读——修不修、怎么修由你决定。分两级：

FAIL（结构契约被破坏）：kb.dir 目录缺失、id.format / combo.id ID 不合规范、id.duplicate ID 重复、tier.illegal 档位非法、paradigm.illegal / paradigm.subject 范式非法或与学科不符、status.illegal 状态非法、combo.chain 原子链为空、combo.ref 引用了不存在的原子、index.mismatch / index.summary_mismatch 统计与章节实际对不上。

WARN（规格建议未满足）：source.page 缺页锚、source.range 页锚超出该书页数、evidence.missing 有状态无实测标记、evidence.unjudged 未考察却带实测记录、id.sequence 段内编号断档且无作废留痕、chapter.empty 没解析出原子、combo.mode / combo.breakpoint 组合信息缺失、coverage.s_tier S 档原子没被任何组合引用（背了不考）、table.stray_pipe 单元格里混进裸竖线、index.missing / index.row_missing 账目缺行。

账目对不上时用 kb_reconcile 按章节文件重算回写，而不是手改统计表——手改迟早再漂一次。

学习算法

模型在 logit 尺度上做 MAP 拟合：

$$ \operatorname{logit} P(\text{流畅通过}) = \theta + \theta_{\text{subj}} - d(a) - \gamma \cdot dt + \delta_{\text{retry}} \cdot \text{retry} $$

$$ d(a) = \mu_{\text{tier}} + \Delta_a $$

先验（冷启动不胡说）：能力基座 N(0.9, 1.5²)，科目偏置 N(0, 0.6²)，档位均值按 S/A/B 给先验再各自收 N(·, 0.5²)，原子偏离 N(上次判定修正, 0.6²)，同日复测项 N(0, 0.5²)；遗忘常数 gamma 默认固定 ln2/10（10 天半衰期），样本足够时才自由拟合。

优化用全批梯度加 Armijo 回溯线搜索，所以「收没收敛」是可判定、可复现、可报告的：每次报告都给出迭代次数、梯度无穷范数与目标值。先验在拟合前按事件顺序回溯算好，既没有未来信息泄漏，也把每次迭代从 O(n²) 降到 O(n)。

预测纪律：先预测、后作答——答题前 learn_predict 把 P(流畅通过) 与 90% 区间写进 分析/预测日志.csv；答完 learn_report 用走前回测（第 k 条只用前 k-1 条）算 Brier、LogLoss、基线 Brier 与 ECE，并按预测区间给出可靠性表。还有三样：

• 模式风险：按混淆模式码做 Beta 后验并按时近加权（默认 14 天半衰期），估计「这个坑再踩的概率」。

• 讲法排名：把直讲事件的讲法码归因到该原子后面那次判定上，比各种讲法的一次通过率（Wilson 区间）。

• 变体消融：legacy / pooled / pooled_retry / full 四个变体在同一事件流上跑走前回测对比，Brier 最低者优先；样本不到 20 条时明确告诉你差异不显著、先按默认。

判定少于 20 条时所有数字只当方向看，别当结论。

配置

工作区根目录放 kaoyan.config.json，全部字段可选：

{
  "root": ".",
  "pack": "demo",
  "dirs": { "kb": "知识库", "queue": "复习" },
  "deliver": { "policy": "auto", "printer": "", "paper": "A4", "copies": 1 },
  "learn": { "fit_gamma": "auto" }
}

环境变量：KAOYAN_ROOT（工作区根目录，KB_BASE 是同义别名）、KAOYAN_BROWSER（浏览器可执行文件路径）。

内容包清单 pack.json 可以声明学科、书目页数与自带知识库目录：

{
  "name": "demo",
  "title": "演示内容包",
  "kb_dir": "kb",
  "subjects": { "示例数学": { "kind": "math", "paradigm": "M" } },
  "books": { "示例教材": { "pages": 200 } }
}

books 里的页数用于校验出处页锚是否超出教材范围。

开发

pip install -e ".[dev]"
python -m pytest -q

测试全部在临时工作区里跑（复制 examples/demo-workspace），不会碰真实数据。改完知识库相关逻辑，建议按「门禁 → 对账 → 测试」的顺序过一遍。

许可

MIT，见 LICENSE。