我把 315 个初中数学知识点连成了一张先修图,这张 README 里藏着不少值得抄的做法

给初中数学知识点建一张带先修关系的图,再配一个能顺着答错的题往上找根因的诊断工具,这件事的难点不在画图,在于数据从哪来、谁说了算、怎么防错。本文基于 cn-math-taxonomy 项目的 README,拆解它的数据结构、先修边处理、课标对齐、诊断算法和题库核验流程,所有数字和判断都来自项目文档本身。

项目规模与数据从哪来

这个图谱一共 333 个节点,其中 315 个是正式知识点,另外 18 个是小学先修节点(id 以 cnm_ext_* 命名),后者只作为图的根,不展开内部结构。正式知识点按领域分,数与代数 142 个、图形与几何 117 个、统计与概率 43 个、综合与实践 13 个;按册次分,七上 61、七下 58、八上 57、八下 57、九上 49、九下 33。
教材对齐用的是人民教育出版社 2024 年审定的新版目录。七上到九上这五册的目录页都核对过,九下是个例外。2024 版九下教材预计 2027 年春季学期才投入使用,人教社官方没有发布对应目录页,项目里九下的章名(第三十一章相似、第三十二章锐角三角函数、第三十三章投影与视图、第三十四章随机事件的概率)是综合知乎专栏、LibreMath、21cnjy 三个第三方来源推定的,README 里明确标了“非官方、待核”。有个细节能看出作者查证时的判断过程,电子课本网标着“2024 审定版”的九下页面列的是反比例函数在第二十六章,但同站自己的九上 2024 页已经把反比例函数放在第二十七章,两个页面互相矛盾,于是判定为误标的旧版目录,直接不采用。这种把来源冲突写进文档的做法,比只给一个结论有用得多。

topics.json 里每个知识点长什么样

数据格式参考了 Marble 的 os-taxonomy 项目(topics 加 dependencies 两个文件),但本项目的文件顶层是裸 JSON 数组,没有 version 或 topicCount 的包装,id 用 cnm_NNN 形式。
一个正式知识点带这些字段:

字段 内容
id 稳定 id,如 cnm_001
name / domain / grade / semester / chapter 名称、四大领域之一、年级、上下册、人教版章节定位
type conceptual / procedural / reasoning / application / modeling 五选一
description 一到两句通俗说明
mastery_criteria 两到三条掌握标准,对应 Marble 的 evidence
diagnostic_question 一道诊断题,对应 assessmentPrompt
standards 课标映射数组,元素形如 {"id": "cms-2022:4.NA.17", "confidence": "exact"}
字段含义有个明确的对应关系,mastery_criteria 对应 Marble 的 evidence,diagnostic_question 对应 assessmentPrompt,但本项目没有搬 centrality、ageRange 这类字段。外部小学节点只有六个基本字段,grade 固定填字符串 "小学",standards 是空数组,因为第三学段的课标条目没有建。
领域划分上有两个容易纠结的点,文档直接定了规矩。函数归“数与代数”,点的坐标、图形变换归“图形与几何”,这和课标领域划分一致。教材里的主题活动(比如设计学校田径运动会比赛场地)按 modeling 类型处理,诊断题只检查活动里的某一个数学要点。

先修边的 hard/soft 区分和传递约简规则

dependencies.json 里每条边长这样。

{"topicId": "A", "prerequisiteId": "B", "strength": "hard", "reason": "一句中文理由"}

方向是 A 依赖 B,学 A 之前需要先会 B。hard 表示不会 B 基本无法学 A,soft 表示会 B 有明显帮助但没有硬门槛。README 自己承认这个区分是 AI 的主观判断,没经过审核,这也是整个项目反复强调的短板。
约简规则值得单独说,因为它决定了你看到“缺边”时该怎么理解。只保留直接先修关系,生成时剔除了 90 条冗余边,但两种强度的删除标准不同。hard 边只在存在另一条全 hard 路径时才删,soft 边只要存在任何其他路径就删。所以图上某条边不见了,不代表这个依赖关系被否认了,通常意味着它已经能由更近的先修推出。
整体边数 616 条,hard 497、soft 119,其中 53 条指向小学外部节点,正式知识点平均 1.92 条先修。图里没有被任何知识点依赖的末端节点有 63 个。每个非外部节点要么有先修边,要么必须填 root_reason 字段,但这一版每个正式知识点最终都能追溯到至少一个小学节点,所以没有节点真正用到这个字段。

课标条目怎么挂到知识点上

课标对齐用教育部《义务教育数学课程标准(2022 年版)》第四学段的内容要求,拆成 157 条机器可读条目存在 data/cn-curriculum-standards.json,id 形如 cms-2022:4.NA.01,四个领域的分布是数与代数 49、图形与几何 92、统计与概率 13、综合与实践 3。
每个正式知识点通过 standards 数组挂 1 到 3 条,全项目共 383 条映射。confidence 只有 exact 和 inferred 两档,exact 表示条款正文直接点名了这个知识点,inferred 表示是前提、特例、延伸或教材细化,后者必须写 note 说明理由。
覆盖率 313 除以 315,约 99.4%,只有两个点没映射上,cnm_130 辅助线与模型、cnm_192 折叠与动点问题,这两个都是按题型归并的知识点,课标里自然找不到对应条文。反方向也有缺口,15 条课标条款没有对应知识点,多数是作图、欣赏类和选学内容,清单列在 docs/standards-mapping.md 里。校验脚本会把“正式知识点 standards 为空”当成警告打印(至多 30 个),要把它升级成错误得设 STRICT_STANDARDS=1 再跑。

自适应诊断的算法逻辑

diagnose/ 是个纯静态可离线的页面,选一个目标知识点或整个章节,按先修关系自适应出题。算法规则用几句话就能讲完,但每一条都对应一个真实的诊断场景。

  1. 每个知识点最多问 2 题。第一题答对,视为掌握,直接跳过它的全部祖先。
  2. 第一题答错,再出一道同级或更容易的题。第二题也错才算薄弱,沿着先修边回溯找根因,回溯时 hard 边优先于 soft。
  3. 第二题答对,标为「不稳」,不回溯,但会出现在结果里。
    这个“第二题兜底”的设计解决的是单题误判的问题。一次算错可能是笔误,两次都错在同一个点上,才值得顺边往回找。诊断结果会给薄弱根因、不稳的知识点、按拓扑序排列的学习路径、相关课标条目原文和一张纯 SVG 路径图,每题作答后立刻显示解析和参考答案。
    进度存 localStorage,可以导出 JSON 或直接打印。核心算法和判题在 diagnose/engine.js 里,写成纯函数,浏览器和 Node 通用,所以能用 node tests/test_engine.js 跑测试。URL 支持直达演示,比如 ?target=cnm_221&demo=1 就是配方法诊断的演示入口。README 强调了一句话,每个知识点最多问 2 题,诊断结果只是线索,不能当完整测评用。

1407 道题怎么验答案

题库在 data/questions.json,给 315 个正式知识点各建 4 到 5 题,共 1407 题。topics.json 里原有的 diagnostic_question 迁移成了每个点的第 1 题(id 后缀 _q1),原字段保留没动。
按题型分,numeric 903、choice 475、short 23、self 6,前两类占 97.9%。这个分布是刻意的,数字题和选择题能被脚本自动判。按难度分,basic 591、standard 537、advanced 279,每个知识点都保证含 basic 和 standard 两档。
核验分两道工序。第一道是 scripts/verify_questions.py 的受限表达式自动求值,875 题有 verify 表达式可跑,全部通过,mismatch 为 0,剩下 532 题主要是文字选项的选择题,机器验不了。第二道是独立第二遍复核,让解题者对 1401 题盲解比对,原始不一致 3 处,查下来全是解题者自己算错,真正的答案错误为 0;顺带改了 4 处含糊题干和 1 处错误解析。裁决和修正记录存在 data/second_pass_log.json,解题者的原始推导放在 data/_second_pass/ 目录。README 里有句坦白话,复核者和出题者是同一模型家族,这个交叉验证的独立性有限。

本地跑起来和发布上线

本地运行只需要一个静态服务器,因为浏览页通过 fetch 读 data/*.json,直接用 file:// 打开会被浏览器拦。

python3 -m http.server 8000
# 访问 http://localhost:8000/ ,诊断页在 /diagnose/
node tests/test_engine.js      # 诊断引擎测试,无依赖
node scripts/screenshot.js     # 无头 Chrome 冒烟测试与截图
python3 scripts/validate.py    # 数据校验
python3 scripts/verify_questions.py   # 题库答案核验,写 verification_report.json

校验脚本只用标准库,检查项覆盖 JSON 合法性、id 唯一、必填字段、domain/type/strength 取值、边两端节点存在、无自环无重复边、无环(有环会打印环路)、孤立节点。第三轮起又加了课标相关检查,standards 引用的课标 id 必须存在于课标文件,confidence 只能是两档合法值,还要检查课标文件自身 id 格式与编号连续性。全过输出 VALIDATION PASSED 且退出码为 0。
生产站部署在 Cloudflare Pages,项目名 cn-math-taxonomy,主域名 math.pansgo.com。仓库更新后在本机执行一次 ./scripts/deploy-cf.sh,脚本会打包 index.html、diagnose/ 和 data/ 里页面用到的文件,推到 main 生产分支,全程不碰 VPS 和 Caddy。

第二轮迭代动过什么

第二轮(2026-10-17)的改动集中在三处,能看出数据维护的实际节奏。
九下章目核实后,去掉所有“(暂拟)”标记,22 个原有知识点的 id 全部不变,章名从“概率初步”改为“随机事件的概率”,概率各点补上 34.1.1/34.1.2/34.2/34.3 的小节号,另外新增两个章末综合与实践节点(cnm_290 停车设计问题、cnm_291 建筑中的数学)。统计与概率领域从 20 个正式点加厚到 43 个(新增 23),分布是七下 17、八下 12、九下 14,七上、八上、九上在新教材里没有统计与概率章,所以没有硬凑。边则新增 50 条、删 1 条冗余(cnm_288←cnm_106,因为经新增的 cnm_297 已可达),另有 366 条理由从短语改写成完整一句话,最短的也有 9 个汉字以上。
这个迭代里有一条原则贯穿始终,id 不动、只改内容和边,保证外部引用不失效,这也是 cnm_NNN 这种不带语义的稳定 id 存在的意义。

操作清单速览

  • •
    克隆仓库后先跑 python3 scripts/validate.py,全过会输出 VALIDATION PASSED 且退出码 0
  • •
    要让“standards 为空”变成报错,用 STRICT_STANDARDS=1 python3 scripts/validate.py
  • •
    本地浏览用 python3 -m http.server 8000,访问 http://localhost:8000/
  • •
    诊断演示直达 http://localhost:8000/diagnose/?target=cnm_221&demo=1
  • •
    改完数据跑 python3 scripts/verify_questions.py,mismatch 为 0 才算过
  • •
    引擎改动后跑 node tests/test_engine.js
  • •
    发布上线执行 ./scripts/deploy-cf.sh,推到 Cloudflare Pages 的 main 分支
  • •
    浏览页支持 hash 直达,如 #cnm_219

FAQ

先修边上的 hard 和 soft 有什么实际差别?
hard 表示不会前置点基本无法学当前点,诊断回溯时 hard 边优先被沿路径检查;soft 表示有帮助但不是硬门槛。两者的划分目前是 AI 的主观判断,未经教师审核。
图上某两个点之间明明有依赖关系,为什么看不到那条边?
传递约简删掉了冗余边,hard 边在存在全 hard 路径时被删,soft 边在存在任何其他路径时被删。缺边通常意味着能由更近的先修推出,生成时共删了 90 条。
诊断时第二题答对了为什么不回溯?
第二题是对第一题答错的兜底。第二题答对说明知识点可能掌握了,标记为「不稳」,不触发回溯;两次都错才判定薄弱并沿先修边找根因。
题库答案的可信度怎么验证的?
两道工序,875 题用受限表达式自动求值全部通过,另外 1401 题做了独立第二遍盲解比对,未发现答案错误。局限在于复核者与出题者是同一模型家族,且全部未经人工逐题复核。
九下的章节信息可靠吗?
非官方、待核。2024 版九下教材 2027 年春季才投入使用,官方没有目录页,当前章名来自三个第三方来源的交叉推定,电子课本网上互相矛盾的旧版目录已被排除。
知识点的 standards 映射没覆盖到 100%,缺口在哪?
315 个正式知识点里 313 个有映射,未映射的是按题型归并的 cnm_130 辅助线与模型和 cnm_192 折叠与动点问题。另有 15 条课标条款没有对应知识点,多为作图、欣赏类和选学内容,清单在 docs/standards-mapping.md。
这套数据能直接商用吗?
不能。项目采用 CC BY-NC 4.0 协议,个人学习、教学、研究可免费使用并修改,商用(付费课程、付费 App、售卖题库等)需单独授权,联系方式见 README 的许可证一节。