EduKB · 教育数据知识引擎

中国中小学全量名录 + 全球高校排名 + 专业目录；同一份数据同时供人查、供机器调、供智能体用。

1. 数据覆盖与来源

数据	规模	来源	更新	授权
中国中小学（含幼儿园）名录	203,431（全国口径）	学生体质健康网学籍学校代码库	跟随学籍库，脚本可日更	内部/查询用途；对外分发需确认
全球高校 + 综合排名	2,000（CWUR 2026）	cwur.org	年更	公开可下载，转载须注明来源
中国高校名录（教育部）	3,196（本科 1,412 / 专科 1,540 / 成人 244）	教育部全国高等学校名单（互动查询接口）	年更，新增院校随批复入库	政府公开信息，可引用
专业目录	91 专业类 / 839 专业（2025；另 6 个军事学门类专业未公开）	教育部《本科专业目录》	年更	公开政策文件

未收录：QS / THE / US News / 软科明细（闭源，禁止商业再分发）。如需并排名次，只保留名次与自算指标，并在界面标注来源。

2. REST 接口

当前版本 v1.1.4：门户支持深浅双主题，首屏分布条随 tab 切换（学校=省份×学段 / 排名=名次分档 / 高校=办学层次 / 专业=学科门类），点条形即按该维度检索；手机端（≤720px）完成整段适配；名次分档点击按真实名次区间过滤（rank_min / rank_max）；新增 CSV 导出 /api/export.csv。

GET  /api/stats                                         覆盖度、来源、最近同步
GET  /api/schools?q=&province=&level=&limit=&offset=     学校检索（name/code 模糊）
GET  /api/schools/{code}                                学校详情（10位学校代码）
GET  /api/universities?q=&country=&level=&source=moe&limit=  高校检索（带 CWUR 名次；source=moe 只看教育部名录）
GET  /api/universities/{slug}                           高校详情 + 全部榜单成绩
GET  /api/rankings?source=cwur&year=&top=&country=&q=   榜单查询
GET  /api/majors?q=&level=&category=&discipline=      专业检索（category=专业类，discipline=学科门类）
GET  /api/grid?level=                                   省份×学段 交叉分布（不传 level 返回各段合计）
GET  /api/rank_stats?country=CN                         排名分档分布 + 上榜国家前十
POST /api/employee/ask  {"q":"福建有多少所小学"}            数字员工（结论+证据链）
POST /mcp                                                MCP JSON-RPC（智能体）
GET  /openapi.json                                       OpenAPI 3.1 规格

3. 智能体接入（MCP）

# 1) 握手
curl -X POST /mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 2) 列工具
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

# 3) 调用
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"edu_search_schools",
           "arguments":{"province":"福建","level":"小学","limit":5}}}

工具	用途
edu_search_schools	按名称/省市/学段检索中小学，返回学校代码
edu_get_school	按学校代码取档案
edu_search_universities	检索全球高校（带最新名次）
edu_ranking	某榜单某年前 N 名，可按国家过滤
edu_university_detail	高校详情 + 各榜单成绩
edu_coverage	覆盖度与同步记录（判断可信度优先调它）

4. 同步任务

python ingest/k12.py  --db data/edukb.db --workers 12      # 全国 20 万条学校，约 15-25 分钟
python ingest/cwur.py --db data/edukb.db --year 2026       # 2000 所高校，秒级
python ingest/moe.py  --db data/edukb.db --listid 10000101 # 教育部普通高校 2952 条，约 2 分钟
python ingest/moe.py  --db data/edukb.db --listid 10000022 --job moe_adult  # 成人高校 244 条
python ingest/moe_reconcile.py --db data/edukb.db          # 与榜单实体去重合并（同校只留一条）

K12 接口有 Referer 校验：缺 Referer 会返回 200 但内容为空（静默失败），脚本已内置；同时必须带省市锚点参数才会返回列表。教育部名单走 hudong.moe.gov.cn 的 getMoDataIndex.jsp 分页（每页 5 条），moe.gov.cn 的静态页一律 403。

5. 公开访问策略

限流：单 IP 每分钟 120 次（EDUKB_RATE_LIMIT 可调，0=关闭），超限返回 429 + Retry-After
缓存：GET /api/* 结果缓存 30 秒（EDUKB_CACHE_TTL 可调），响应头 X-Cache: HIT 表示命中
静态：Cache-Control: public, max-age=30

两部分都是进程内实现，零第三方依赖；nginx 侧如需更强防护可再加 limit_req / proxy_cache。

5. 学校代码规则（用于地区/学段解析）

10 位学校代码：第 3-4 位 = 省级行政区划码（11 北京 / 35 福建 …）
例：2111000346 → 北京；学段按校名关键词推断，字段 level_inferred=1 表示推断值

K12 源接口只返回「学校名称 + 学校代码」两列，没有市/县字段，故 schools.city / county 保持为空——这是源数据口径，不是遗漏；需要市/县级定位时按代码 3-4 位取省、再按校名与代码段细分。