withmarbleapp/os-taxonomy · 上手攻略

仓库：withmarbleapp/os-taxonomy
链接：https://github.com/withmarbleapp/os-taxonomy
分类：教育科技 / 知识图谱
作者：Tom
更新：2026-07-14

这是什么

os-taxonomy（Marble Skill Taxonomy）是一个开放的小学阶段全科学习知识图谱，由教育科技公司 Marble 于 2025 年中开源发布。它把一个孩子小学期间（大约 5~12 岁）要学的内容拆成了 1,590 个极细粒度的「微主题」（micro-topics），再通过 3,221 条有向无环图（DAG）边把它们串联起来——每条边标注了「硬依赖」还是「软依赖」，并附一句理由。

核心数据结构就是四个 JSON 文件：

文件	内容
`data/topics.json`	1,590 个微主题节点（名称、描述、年龄范围、学科、类型、评估标准等）
`data/dependencies.json`	3,221 条依赖有向边（`topicId` 依赖 `prerequisiteId`）
`data/curriculum-standards.json`	原始课程标准映射（NGSS、Common Core、UK National Curriculum 等）
`data/clusters.json`	183 个家长友好型领域摘要

数据覆盖 8 个学科：科学（547）、数学（503）、英语（286）、历史（90）、个人与社会发展（88）、生活技能（37）、计算（21）、学会学习（18）。

解决什么问题： 大多数课程数据要么是平铺的课标清单，要么锁在某个商业产品里。os-taxonomy 第一次把小学全科做成了一个可计算的、有方向性的知识图谱——你输入任意一个知识点，可以自动追溯它所有的先修内容，或者推导出学习路径。

快速安装 / 获取数据

这是一个纯数据项目，没有运行时依赖，直接 clone 即可：

git clone https://github.com/withmarbleapp/os-taxonomy.git
cd os-taxonomy

数据路径：

os-taxonomy/
├── data/
│   ├── topics.json              # 微主题节点
│   ├── dependencies.json        # 依赖关系有向边
│   ├── curriculum-standards.json
│   ├── clusters.json
│   └── manifest.json            # 各文件 SHA-256 校验和
├── schema/                      # JSON Schema（供验证用）
├── scripts/
│   └── validate.mjs            # 结构 + 引用完整性验证脚本
└── media/                       # 可视化素材

验证数据完整性：

node scripts/validate.mjs

也可以用 Python 加载（或其他任意语言）：

import json

with open("data/topics.json", encoding="utf-8") as f:
    topics_data = json.load(f)

with open("data/dependencies.json", encoding="utf-8") as f:
    deps_data = json.load(f)

# topics_data["topics"] 是列表
# deps_data["dependencies"] 是列表
print(f"共 {len(topics_data['topics'])} 个主题，{len(deps_data['dependencies'])} 条依赖边")

核心用法

1. 构建主题 ID 映射

import topics from './data/topics.json' with { type: 'json' };
import deps from './data/dependencies.json' with { type: 'json' };

const byId = new Map(topics.topics.map(t => [t.id, t]));

2. 查询某个主题的所有前置依赖

// 找出 "Building sentences" (id: mt_N8CpN1EJrP) 的所有直接先修主题
const prereqs = deps.dependencies
  .filter(d => d.topicId === 'mt_N8CpN1EJrP')
  .map(d => byId.get(d.prerequisiteId).name);

console.log(prereqs);
// 输出类似: ["Understanding that words combine to make sentences", ...]

3. 递归查找完整上游链

function getAllPrereqs(topicId, deps, byId, visited = new Set()) {
  if (visited.has(topicId)) return [];
  visited.add(topicId);

  const directPrereqs = deps.dependencies
    .filter(d => d.topicId === topicId)
    .map(d => d.prerequisiteId);

  let result = [];
  for (const pid of directPrereqs) {
    result.push(pid);
    result = result.concat(getAllPrereqs(pid, deps, byId, visited));
  }
  return result;
}

const allPrereqIds = getAllPrereqs('mt_N8CpN1EJrP', deps, byId);
const allPrereqNames = allPrereqIds.map(id => byId.get(id)?.name).filter(Boolean);

4. 按学科 + 年龄筛选主题

// 找出 8~10 岁数学主题
const mathTopicsAged8to10 = topics.topics.filter(t =>
  t.subject === 'Mathematics' &&
  t.ageRangeStart <= 10 &&
  t.ageRangeEnd >= 8
);

console.log(mathTopicsAged8to10.map(t => t.name));

5. 找出一条学习路径（拓扑排序）

function topologicalSort(topicId, deps, byId) {
  const sorted = [];
  const visited = new Set();

  function visit(id) {
    if (visited.has(id)) return;
    visited.add(id);
    const prereqs = deps.dependencies
      .filter(d => d.topicId === id)
      .map(d => d.prerequisiteId);
    for (const p of prereqs) visit(p);
    sorted.push(id);
  }

  visit(topicId);
  return sorted.reverse().map(id => byId.get(id)?.name).filter(Boolean);
}

const path = topologicalSort('mt_N8CpN1EJrP', deps, byId);
console.log(path);

典型适用场景

场景	说明
自适应学习应用	给定学生当前水平，自动计算下一步最应该学什么
课程规划工具	家长/老师了解某知识点需要哪些前置，避免跳步讲解
AI Tutor / 智能助教	注入知识图谱约束，防止 LLM 给出超出学生认知水平的解释
教育资源推荐	基于知识缺口推荐练习、教材、视频
课程对比研究	NGSS vs Common Core vs UK NC 的覆盖范围差异分析
游戏化学习	构建技能树，把依赖关系做成「解锁」机制

坑与注意

数据许可证分层：数据库结构（ID、图关系）用 ODbL 1.0（商业可用，但衍生数据库必须开源）；Marble 原创文字内容（描述、评估标准、理由）用 CC BY-SA 4.0；上游课标各自另有版权。使用前务必读完 LICENSE 和 PROVENANCE.md。
依赖方向的直觉陷阱：dependencies.json 里 topicId depends on prerequisiteId，即边方向是「谁需要谁」——要得到「解锁」关系需要反向。上面的代码示例中已体现这点。
循环依赖不存在，但软/硬依赖使用需谨慎：数据本身是 DAG，但 strength: "soft" 的边表示「有帮助但不是必须的」，在严格的学习路径计算中可以考虑忽略或降低权重。
assessmentPrompt 含 {{name}} 占位符：直接展示给用户前需要替换成学生姓名，或者 strip 掉。
主题 ID 不是自增数字（mt_ 前缀 + 随机字符串），不要硬编码或猜测，需要通过遍历或建 Map 来查询。
仅覆盖小学阶段：K~8（大约 5~12 岁），初中、高中内容不在其中，不适合做中学课程规划。

与同类对比

项目	类型	规模	许可证	特点
os-taxonomy	知识图谱	1,590 节点 / 3,221 边	ODbL + CC BY-SA	开放、细粒度、有向无环图、跨课标对齐
Khan Academy 知识图谱	视频/练习映射	~10 万节点	专有	绑定平台，非开放数据
Wikidata / DBpedia	通用知识图谱	亿级	CC0	过于宽泛，不专注基础教育
Common Sense Media	教育评估框架	千级概念	部分开放	偏社会情感，非学科知识
OpenStax 教科书	教材内容	章节级	CC BY	无依赖关系，非图结构

os-taxonomy 的核心优势是第一个把小学全科做成可计算的开放 DAG，且同时对齐了多个国家课标。

一句话推荐结论

如果你在构建任何涉及「孩子应该先学什么、再学什么」的教育类应用，os-taxonomy 是目前质量最高、规模最大、许可证最友好的免费开放知识图谱，直接用 JSON 加载即可，无需任何运行时依赖。