kp-graph-408

面向计算机考研 408 的考点图谱与教学诊断记忆层：提供细粒度考点编号体系、题目—考点映射、带置信度的跨科关系、答题轨迹 schema 与诊断查询。

不提供刷题界面、RAG、向量库、题库正文、教材正文。前端与检索层可由使用者自行搭配或替换。

中立声明：本项目不包含、不分发、不引导获取任何第三方题库、教材或真题内容。仓库内不含题库下载链接、爬虫、破解或绕过付费/DRM 的代码。导入器只接受使用者自备的合法数据，导入数据的合法性由使用者负责。详见 DATA-LICENSE.md。

这个项目提供什么

• 细粒度考点编号体系（kp_code）

• 题目—考点多对多映射 schema

• 考点之间的跨科关系 schema（带 origin / confidence）

• 答题轨迹与考点级错因 schema

• 诊断查询（broken_links）

• MCP 工具契约

Related MCP server: relation-net

这个项目解决什么

市面上的 408 工具大多停在「问了有答案、刷了有对错」。它们缺的是下面这一层：

• 一个稳定编号的考点体系（不是按章节标题，而是可被程序引用的 kp_code）

• 题目到考点的多对多映射，带主次权重与置信度

• 考点之间的跨科关系（Cache ↔ TLB、页表 ↔ 映射方式、调度队列 ↔ 队列结构），且关系本身带来源与置信度

• 答题轨迹里考点级的错因，而不是只有对错

• 由此才能得出的结论：「你 A 掌握了，但没迁移到 B」

最后一条是整个项目的验收标准。它在 diagnose.broken_links() 里。

包结构

同一仓库发布两个包，职责不重叠：

tutor_memory 只是 kp_graph 的协议外壳，不含独立数据逻辑。单独用 kp_graph（写脚本、做批处理）完全可行；只想接 Agent 时用 tutor_memory。

kp_graph 内部分层：diagnose（诊断：断链/弱点/下一步）与 explain（讲解：生活类比）职责分开——一个回答「哪里塌了」，一个回答「该怎么讲」，都输出纯数据、不调 LLM。 抽取链同样分层：exam_pdf（PDF → 文本块 + 图）→ exam（文本 → 题目，纯函数）→ importer（题目 → 库），textmatch 是 migrate_legacy 与 exam 共用的打分层。

MCP 部分只做 manifest + stdio server 骨架，mcp[cli] 为可选依赖：未安装时 --manifest 仍可打印全部工具契约，server.py 单文件、无硬依赖，全部逻辑在 tools.py（纯函数，可单测）。

快速开始

python -m kp_graph.cli seed --dir examples/seed
python -m kp_graph.cli validate
python -m kp_graph.cli coverage
python examples/simulate_student.py
python -m kp_graph.cli diagnose --student S-001
python -m kp_graph.cli analogy --kp DS-08-01-03   # 把考点讲成生活场景

在真实考纲考点表（387 条）上跑跨科诊断：

python scripts/build_kp_ds.py && python scripts/build_kp_co.py
python scripts/build_kp_os.py && python scripts/build_kp_cn.py
python scripts/build_cross_relation.py
python examples/simulate_cross_subject.py

simulate_student.py 造一个在「Cache 映射」上全对、在跨科同构的「页表与地址转换」上全错的学生，输出：

关系置信度 >= 0.9：
1. [high] OS-03-02-01  (broken_link)
   CO「Cache 映射方式」正确率 100%（3 题），OS「页表与地址转换」仅 0%（3 题），
   二者关系为 analogous：概念已具备但未迁移

历史数据导入与错因补判（只有对错、没有错因的老数据走这条路径）：

python -c "from kp_graph import db, importer; c=db.init_db(); importer.record_attempt(c, {'student_id':'S-002','question_id':'q-OS-0002','chosen':'D','is_correct':False,'defer_diagnosis':True})"
python -m kp_graph.cli pending
python -m kp_graph.cli resolve --attempt 1 --kp OS-03-02-01 --error-type knowledge_gap

测试与 MCP：

python -m unittest discover -s tests -v
python -m tutor_memory.server --manifest
pip install "mcp[cli]"   # 可选；安装后 python -m tutor_memory.server 即 stdio MCP server

导出教学记忆，并推送到任意记忆层（换记忆层只改 --backend，不改代码）：

python -m kp_graph.cli export-memory --student S-001                        # 只打印 JSON
python -m kp_graph.cli export-memory --student S-001 --backend json --dry-run  # 看要写什么
python -m kp_graph.cli export-memory --student S-001 --backend json --push    # 真写入

# 内置：none（默认）/ memory / json / eraherm；第三方用 module:factory
# 也可用环境变量 KP408_MEMORY_BACKEND 指定

tutor_memory/memory_backend.py 定义了 MemoryBackend 协议（remember / recall / supersede / capabilities / health，user_id 贯穿全部方法）。新增一家记忆层只需实现这五个方法 并暴露一个工厂函数，本项目零改动 —— 不支持纠正的后端会自动降级成「正文标记旧判断作废」的追加写入。

真题 PDF → 题库（抽取链路）

extract_exam 把 PDF 变成 importer 能直接吃的题目 JSON，中间不做任何「猜」：

# 1. 只抽不写库（题 + 图 + 文本块）
python -m kp_graph.cli extract --pdf 2024年408真题.pdf --out-dir extracted/2024

# 2. 一条命令跑到底：抽取 → 入库 → 规则候选 → 覆盖统计
python -m kp_graph.cli --db all.sqlite3 import-exam --pdf 2024年408真题.pdf

# 3. 看还差哪些考点的题
python -m kp_graph.cli --db all.sqlite3 coverage --missing 40

产出两个文件：

三层职责不混：

• exam_pdf 只把 PDF 变成「文本块 + 裁好的图」，图按 y 坐标挂到上方最近的题号

• exam 只把文本块变成「题号 / 题干 / 选项 / 答案 / 解析」，不碰 PDF，因此可以纯文本单测

• importer 只把结构化 JSON 写库，不做语义判断

默认不替你拍板，这是与「一键生成题库」最大的差别：

• suggest_kp 的候选分数硬封顶 0.85，落库阈值默认 0.9 —— 题干提到某个术语不等于这题考它，导入后 question_kp 一定是空的

• 想让规则先垫一层必须显式降阈值：--min-confidence 0.8，且写入的 method='rule'

• 没抽到答案的题直接拒绝并列出原因，不伪造字段（question.answer 是 NOT NULL）

• 题号落不进任何科目区间的题同样拒绝：subject 有 CHECK 约束，猜一个比丢掉更糟

卷面结构（题号 → 科目）

syllabus/exam_spans.json 只登记公开的卷面结构（题型、题号跨度），years 里没登记的年份回落到 default， 并在结果里标 span_source=default(entity=default) —— 科目是推断出来的，这件事必须留痕。用 --structure <json> 可覆盖。

扫描件

无文本层的 PDF 走降级路径：整页渲染成 pNN_scan.png，文字靠人工转录；加 --ocr 才调 Tesseract （需要系统装 tesseract 且有 chi_sim 语言包，只 pip install 是不够的）。 缺 Tesseract 时只报错不抛异常 —— 不能因为没装 OCR 就让整份卷子作废。

扫描件上的图没法单独裁出来：一页就是一张位图，文字与图形不可分离。这是该路径的硬限制，不是待办事项。

已知边界

• 综合题的答案与解析在卷面上通常不分离，抽取结果里会合并进 answer 并标 warning

• 抽取出的题一律标 source 为「PDF 抽取，需人工校对」，license_status=user_supplied

• 试卷排版差异大（选项并排、跨页题干、答案夹注），正则覆盖不到的地方靠 warnings/rejected 暴露，不静默丢弃

Agent 侧（任意支持 MCP 的客户端）

这五个工具专门给 Agent 用 —— 人的「复核」环节正好由模型判断承担：

整条链不依赖任何外部题库，Agent 只需要使用者自备的 PDF。

接进 MCP 客户端（Claude Desktop / Cursor / Hermes / OpenClaw 都是同一套 mcpServers 的变体，字段名以各自文档为准）：

{
  "mcpServers": {
    "kp-graph-408": {
      "command": "python",
      "args": ["-m", "tutor_memory.server", "--db", "<绝对路径>/all.sqlite3"],
      "cwd": "<绝对路径>/kp-graph-408"
    }
  }
}

先用 python -m tutor_memory.server --manifest 确认 18 个工具都列得出来 —— 没装 mcp[cli] 也能打印， 所以配置排错了能一眼分清是「没装依赖」还是「路径错」。

本项目不绑定任何 Agent，也不绑定任何记忆层。 是否需要再接一层长期记忆、接哪一家，由使用者自己选； 选型标准、可插拔边界与踩坑清单见 AGENT-MEMORY.md。

考点编号规则

SUBJECT[-NN]...        例: DS-08-01-03
  depth 1 = 章   2 = 节   3 = 考点   4 = 子考点 / 题型细分

四条硬规则，validate 强制检查：前缀与 subject 一致、depth 等于编号级数、非章级必须挂 parent、parent 不得跨科。

编号体系的来源与许可证

本项目的考点编号体系为原创：按 408 考试大纲的章节结构自行编码，kp_code 只承诺结构稳定，不复刻任何第三方材料的小节标题。

• 不从任何第三方材料的清洗整理稿提取编号或标题。标题一律使用考纲通用术语（如「Cache 映射方式」「页表与地址转换」），不使用某本教材的独有表述。

• kp.origin 记录每行产出方式：syllabus（考纲）/ manual（人工）/ llm（模型生成，必须人工复核）。origin='llm' 且 confidence<0.8 的行会被校验器 warn。

• 若将来确需引入第三方来源，必须在 DATA-LICENSE.md 逐条登记来源、授权方式、覆盖范围、引入日期，不得静默混入。

上一代 284 条知识点通过 kp_legacy_map 保留可回溯映射，不直接改 code。一条旧知识点可映射到多个新考点，未人工确认的多元映射会被标 warn。

跨科关系与置信度闸门

关系类型：prereq 依赖 / analogous 类比 / contrast 易混 / compose 组成。

kp_relation 带 origin 与 confidence，这是诊断可信度的闸门：

broken_links 默认只消费 confidence >= 0.6 的边（--min-confidence 可调），未复核关系不会进入诊断结论。示例数据里留了一条 origin=llm, confidence=0.3 的边，validate 会同时报 rel.low_confidence 与 rel.llm_unreviewed。

边端点的正确率按子树聚合（rollup），这是一个容易踩空的坑：真实关系常挂在章或节上（OS-03-02 --analogous--> CO-03-06），而题目与作答只发生在考点级（OS-03-02-01）。只比边端点自身的正确率，两端都查不到记录，跨科断链在真实数据上恒为空。实测：子考点作答时，rollup=False 输出 0 条，rollup=True 输出 1 条。--no-rollup 可关闭对照。

gap 相同的多条断链按 weak_depth 降序，让建议落到具体考点而不是整个章节。

诊断查询本身不调用 LLM，可复现、可审计。但诊断质量由关系图谱的构建质量决定——「不需要 LLM」不等于「关系数据天然可信」，这也是关系必须带置信度的原因。

生活类比：解释层，不是定义层

抽象概念挂在 kp 上是一句话（「Cache 和主存之间的映射方式」），学生看不懂的不是这句话，是它背后的机制。kp_analogy 把考点映射到学习者已经熟悉的场景：抽屉与档案室、食堂餐盘堆、酒店超售。

每条类比必须写 breaks_at。 这不是装饰字段：任何类比都有失效边界，「内存像桌面」会让学生以为内存断电不丢东西、「出队像排队」解释不了循环队列。「不标边界的类比比不讲类比更糟」是这张表的设计前提，validate 会对空 breaks_at 报 analogy.no_breakpoint。

闸门与 kp_relation 一致：

一个考点可以挂多个类比；查叶子考点时默认沿 parent 链继承上级章节的通用类比（自身的最先返回），--no-ancestors 可关闭。

# 把考点讲成生活场景（含失效边界）
python -m kp_graph.cli --db all.sqlite3 analogy --kp CO-03-06-02

# 按某个学生的弱考点批量看类比
python -m kp_graph.cli --db all.sqlite3 analogy --student S-001

# 诊断输出默认附一条弱端的类比，--no-analogy 关掉
python -m kp_graph.cli --db all.sqlite3 diagnose --student S-001

# 导入（自己写或模型起草后人工过一遍）
python -m kp_graph.cli --db all.sqlite3 import --analogy examples/analogy_sample.json

examples/seed/analogy.json（7 条，四科齐全，含一条故意留空边界的 LLM 草稿用于演示闸门）随 seed 一起导入；examples/analogy_sample.json 面向 387 条真实考纲库。MCP 侧对应 get_kp_analogy 工具。

validate 的类比相关告警：analogy.no_breakpoint / analogy.bad_mapping / analogy.unreviewed / analogy.low_confidence（后两者聚合成一条，不刷屏）。

数据表

错因与 pending 过渡态

错因枚举：concept_confusion / calculation / misread / forgetting / knowledge_gap / none / pending。

• 实时作答：答错不给 diagnoses 直接抛错，宁可失败不写脏数据

• 历史数据导入：显式传 defer_diagnosis=True，为该题所有考点写 pending，attempt.diagnosis_status='pending'

• pending 不参与正确率统计（v_kp_accuracy 显式过滤），避免把「未判定」当「答错」

• 补判用 resolve_diagnosis / python -m kp_graph.cli resolve，该 attempt 的 pending 清零后自动转 complete

为什么错因挂在考点而不是题目上：同一道综合题两道小问可能分别塌在不同考点。只记题目对错，诊断层拿不到任何可用信号。

teaching_memory 的归属边界

这张表在本项目中只是 schema 规范 + 本地工作副本，不是跨项目记忆主存储。

本项目不承担记忆治理职责：不做分层淘汰、不做跨科目聚合、不做跨会话召回。这些是记忆层的职责 —— EraHerm-Memory（MIT，© 2026 杨文华）是其中一例，换成 Zep / Mem0 / 自建表同样成立。把记忆主存储绑在单个学科项目里，换个科目就是孤岛。

已实现的一个适配器在 tutor_memory/eraherm_bridge.py（面向 EraHerm-Memory，尚未抽象成通用接口），核心映射：

导出的 content 刻意保留 kp_code 与考点标题原文：EraHerm 的召回是语义 + 词法混合，术语写全比写得漂亮更有用。

408 题型约束

408 统考只有单选题与综合应用题。schema 中保留 multi 仅为未来扩展到非 408 科目，校验器会对 408 科目下的 multi 报 warn，示例数据也不含多选。

示例数据的边界

examples/seed/ 只放自编示例数据，规模固定：

• 22 条示例考点

• 5 道自编示例题（题干、选项、答案、解析均为原创或通用表述）

• 关系与旧编号映射仅用于演示闸门效果

tests/test_smoke.py 中有断言锁定这两个数字，防止示例数据膨胀成事实上的题库。

data/、*.sqlite、*.db、用户导入文件一律由 .gitignore 排除，不进入版本库。

真实考纲目录（四科全部落地）

考纲的章节层级是公开发布的官方文件结构，属于「原材料」；本项目做的是「加工」——给每一级分配稳定的 kp_code 与 depth，并校验编号规则能否覆盖官方层级。不涉及任何教材或题库正文。

examples/seed/ 受 22 条上限约束，所以真实目录放在独立的 syllabus/ 目录，不影响示例数据边界。

syllabus/kp_DS.json            71 条：7 章 / 40 节 / 24 三级 /  0 四级
syllabus/kp_CO.json           102 条：6 章 / 30 节 / 59 三级 /  7 四级
syllabus/kp_OS.json           104 条：5 章 / 18 节 / 62 三级 / 19 四级
syllabus/kp_CN.json           110 条：6 章 / 32 节 / 69 三级 /  3 四级
                              合计 387 条考点
syllabus/kp_*_relation.json    58 条科内先修关系
syllabus/kp_cross_relation.json 10 条跨科关系
syllabus/legacy_from_demo.json 示例编号 → 考纲编号的迁移映射
scripts/outline_common.py      公共构建器（编号/depth/parent/syllabus_ref 推导）
scripts/build_kp_{ds,co,os,cn}.py  各科结构数据
scripts/build_cross_relation.py    跨科关系

python scripts/build_kp_ds.py && python scripts/build_kp_co.py
python scripts/build_kp_os.py && python scripts/build_kp_cn.py
python scripts/build_cross_relation.py

python -m kp_graph.cli --db all.sqlite3 import \
    --kp syllabus/kp_DS.json --kp syllabus/kp_CO.json \
    --kp syllabus/kp_OS.json --kp syllabus/kp_CN.json

每个脚本自带结构断言（章/节/三级/四级的数量），数字对不上就退出非零——这不是装饰：OS 与 CN 首次生成时正是靠它抓到我自己手算错了四级条目数。

实测：387 条考点，0 错误。warn 全部是 kp.no_question（尚无题目）与 legacy.ambiguous，属于预期。

旧编号 → 考纲编号：只出候选，不替你拍板

旧条目和考纲条目常常不是一词之差（「顺序表」→「顺序存储」、「内部排序」→ 10 条平铺条目）。 词法相似度算不出来的部分必须交给人——硬猜出来的映射会污染整条诊断链路。

# 1. 出报告（只读，不写库）
python scripts/migrate_legacy.py --db all.sqlite3 --legacy examples/legacy_sample.json

# 2. 产出候选文件，逐条人工复核
python scripts/migrate_legacy.py --db all.sqlite3 --legacy examples/legacy_sample.json \
    --out syllabus/legacy_candidates.json

# 3. 人工确认的一对多映射写进 alias，再落库
python scripts/migrate_legacy.py --db all.sqlite3 --legacy examples/legacy_sample.json \
    --alias examples/legacy_alias_sample.json --apply

分档规则：>= 0.90 可直接采用，0.60 ~ 0.90 进人工复核桶，< 0.60 记为未匹配。 只有「完全相同」和「人工确认」才可能落库；包含/词形相似一律封顶在复核区间。 落库前会校验 kp_code 是否存在，写错的编号会整体拒绝而不是留半条脏数据。

syllabus_ref 采用「章.节.子项」的阿拉伯数字路径，与大纲 PDF 的章序一致：

核对记录（数据结构）

初版 117 条按教材体例组织，与官方大纲有 10 处结构性偏差，已全部推翻重建。其中 4 处是漏条目或错条目：

拿到官方大纲 PDF 后，又修正了 9 处逐字抄录层面的偏差（这类偏差不会报错，但会让 kp 与原文对不上）：

syllabus/ 中全部节点 origin='syllabus'。唯一一个 confidence=0.9 的是 DS-06-05-01：大纲 PDF 该处字形不清（可能是「二叉搜索树」也可能是「二叉树搜索树」），按标准术语记为前者并降置信度留痕，待原文核对后再提为 1.0。

核对记录（组成原理）

按官方大纲 PDF 逐条抄录，共六章 30 节 59 三级 7 四级。四级只集中在两处：

• 3.7.2 页式虚拟存储器 → 「基本原理、页表、地址转换、TLB(快表)」

• 6.3 I/O方式 → 程序中断方式下 4 项、DMA方式下 2 项

核对记录（操作系统）

共五章 18 节 62 三级 19 四级。四级分布较散（进程通信、调度实现、互斥实现、银行家算法、页面置换、文件操作、I/O 各层等），是四科中层级最深的一科。

有一处需要判断的是「进程管理」的组织方式。大纲 PDF 中：

• CPU调度与上下文切换 下挂着 调度的基本概念 / 调度的目标 / 调度的实现

• 而 CPU调度算法 / 多处理机调度 / 上下文及其切换机制 在下一页以同级项目符号出现

若按后者也判为二级，则「CPU调度与上下文切换」与「上下文及其切换机制」语义重复，不像官方体例。结合《考试大纲解析》目录对进程管理的描述（「进程与线程、CPU调度、进程同步、死锁」四个节级），判定这三个条目是 CPU调度与上下文切换 下的三级：

2.2 CPU调度与上下文切换
  2.2.1 调度的基本概念
  2.2.2 调度的目标
  2.2.3 调度的实现 → 调度器/调度程序(scheduler)、调度的时机和调度方式…
  2.2.4 CPU调度算法 → 先来先服务(FCFS)、短作业优先(SJF)、时间片轮转、优先级、高响应比、多级反馈队列
  2.2.5 多处理机调度
  2.2.6 上下文及其切换机制

这一判定同时被 tests/test_smoke.py::test_process_management_has_four_sections 与 test_scheduling_topics_are_third_level 锁定。

核对记录（计算机网络）

共六章 32 节 69 三级 3 四级。四级只有 3 处，都在介质访问控制下：信道划分、随机访问、轮询访问各自聚合的那一行明细。

跨科关系

kp_cross_relation.json 共 10 条，是本项目诊断能力的核心：

这些边让「在组成原理会、在操作系统不会」这种结论成为可能。实测（python examples/simulate_cross_subject.py）：

强端 CO-03-07-02-01  CO 基本原理、页表、地址转换、TLB(快表)   acc=100%
弱端 OS-03-02-02     OS 请求页式管理                        acc=0%
关系 analogous (confidence=0.95)  gap=1.00
→ CO「…TLB(快表)」正确率 100%，OS「请求页式管理」仅 0%：概念已具备但未迁移

单看任何一科的正确率都得不出这句话。

kp 表的 depth ≤ 4 约束覆盖了四科全部层级，无需放宽。

任何一科的目录修订都必须先做逐条核对——DS 初版的错误证明，凭印象写层级会系统性偏离官方体例。

许可证

• 代码：MIT（见 LICENSE）

• 考点编号体系、关系数据、schema 文档：CC BY 4.0（见 DATA-LICENSE.md）

• 不覆盖任何第三方教材、真题、题库内容

设计思路参考以下项目，但不包含其代码与数据的任何副本：

CacheFlow408     — MIT, Copyright (c) 2026 ya1u737
EraHerm-Memory   — MIT, © 2026 杨文华 (Wenhua Yang)

路线

• schema + 导入器 + 校验器 + 诊断查询 + 关系置信度闸门 + pending 过渡态

• MCP 工具契约（manifest + stdio 骨架，mcp[cli] 可选）

• 教学记忆导出格式

• 记忆层适配器协议（MemoryBackend）+ --push 落库，换记忆层只改配置

• 数据结构考纲目录落地并与官方大纲逐条核对（71 条，0 错误，syllabus_ref 已回填）

• 计算机组成原理考纲目录落地并与官方大纲逐条核对（102 条，0 错误）

• 操作系统考纲目录落地并与官方大纲逐条核对（104 条，0 错误）

• 计算机网络考纲目录落地并与官方大纲逐条核对（110 条，0 错误）

• 跨科关系 10 条，跨科断链诊断在真实考纲编号上跑通

• 真题 PDF → 题库：题/图结构化、选项与答案解析、扫描件 OCR 可选、一卷一命令（extract / import-exam）

• 题目→考点候选 + 复核回写 + 覆盖统计，全部暴露为 MCP 工具（Agent 直接可用）

• 扫描件上的配图单独切出（需要版面分析，OCR 解决不了）

• 284 条旧编号 → 考纲编号映射工具（规则候选 + 人工复核队列 + 覆盖率报告）

• 通用导入适配层：接受使用者自备的 JSON / SQLite（不内置任何来源）

• 错因自动判定（LLM 只产出候选，落库必须经人工或高置信度规则确认）

• 题目落地后跑 coverage，定位哪些叶子考点还没有任何题

四科落地情况

每科的落地流程固定为：先取官方大纲原文逐条抄录 → 写 scripts/build_kp_<科>.py → 生成 syllabus/kp_<科>.json → import → validate 必须 0 错误 → 补先修关系 → 加一组锁定测试。第一步不可跳过。

examples/seed/ 始终维持 22 条考点、5 道自编示例题不变，仅用于跑通链路；真实目录只进 syllabus/。