我把中华五千年做成了一个数据库:266 位帝王、154 个事件、62 件海外珍宝,全部开源

54 阅读7分钟

做中文历史类应用的开发者大概都遇到过这个场景:想查汉武帝在位多少年,要么翻维基百科手抄,要么爬百科站点担心版权,要么去用学术库被它的格式劝退。

chinese-poetry 用 53k star 证明了「JSON 分发的开放数据库」这条路在古诗词领域完全走得通。我试着把同一套思路搬到历史数据上,项目叫 chinese-history。

真正做起来才发现,历史数据和诗词数据根本不是一类问题。诗词是文本,错了就是错了,改就行。历史是断言,每条数据背后都有一句「据某某书卷几」,而这些书之间经常互相矛盾。

下面记录三个建模决策,以及每一个付出的代价。有些代价直到我跑统计才发现,比预想的大。

决策一:出处强制,没有 sources 就过不了 CI

诗词库最常被吐槽的是数据错了很久没人发现。历史数据如果也这样,后果更严重:一个错的生卒年会被下游应用一路引用下去,而且没人能追溯错在哪。

所以我把出处做成了硬约束。校验器里这段逻辑很短:

python

def check_sources(where, sources):
    if not isinstance(sources, list) or len(sources) == 0:
        err(where, "sources 必须是非空数组(无出处的数据不允许合并)")
        return
    for i, s in enumerate(sources):
        if not s.get("title"):
            err(where, f"sources[{i}] 缺少 title")
        if s.get("type") not in SOURCE_TYPES:
            err(where, f"sources[{i}].type 必须是 {sorted(SOURCE_TYPES)} 之一")

sources 为空就直接进错误列表,python3 tools/validate.py 退出码非 0,CI 变红,PR 合不进来。type 限定在 primary / secondary / reference / institutional / archaeological 五种,至少能区分「这条引自正史原文」还是「这条引自二手转述」。

一条记录长这样:

json

{
  "id": "person.han.liubang",
  "name": "刘邦",
  "birth": {
    "year": -256,
    "circa": true,
    "original": "沛丰邑中阳里人",
    "disputed": [{"year": -247, "source": "史记集解引皇甫谧等说"}]
  },
  "sources": [
    {"title": "史记·高祖本纪", "type": "primary", "ref": "卷八"},
    {"title": "汉书·高帝纪", "type": "primary"},
    {"title": "Wikidata Q7210", "type": "reference"}
  ]
}

代价一:出处能强制,出处对不对强制不了。

这是我最想写清楚的一点。校验器只能检查 sources 数组非空、title 存在、type 合法。它完全无法验证「《史记·高祖本纪》卷八里到底有没有这句话」。

也就是说,一条记录只要编一个看起来合理的书名和卷次,就能通过 CI。出处强制挡住的是「懒得写出处」这种偷懒,挡不住「出处本身是编的」这种造假。

这个区别决定了后面所有事:出处字段管理的是可追溯性,不是正确性。  把它当正确性保证来宣传,就是在骗人。

代价二:每条数据都要人工读一遍原书,这个工作量是线性的,不会因为工具变好而变少。

我统计了一下当前 1224 条记录的人工核验状态,结果是 0 条被人工逐条核对过。

更尴尬的是,_meta 里实际只有这么几个字段:

json

"_meta": {
  "created_by": "ai-pipeline",
  "model": "kimi-k3",
  "prompt_version": "seed-v1",
  "version": 1
}

没有 verified_by 这个键。  早期文档里写过「_meta.verified_by 为空表示未人工核验」,但那个字段从来就没实现过。这是一处文档与实现不一致,我把它当作待修的 bug 记下来,而不是继续用一句好听的话糊过去。

真实情况是:这些数据是 AI 按提示词生成的,抽查过一部分,但没有系统性的逐条核对。任何要拿去做生产应用的人,都应该自己去核 sources。

决策二:学术争议多值并存,不投票

刘邦生年,《史记》体系下一般算前 256 年,但《史记集解》引皇甫谧的说法是前 247 年。两种说法都有文献依据,学术界没有定论。

很多数据集的处理方式是选一个「主流值」,把另一个丢掉。我选择两个都存:主值放在 birth.year,被质疑的值和它的依据放进 disputed[],各自保留出处。

理由是下游的立场不一样。做儿童科普需要给一个确定数字,做学术工具需要知道这里存在分歧。我在数据层不替任何人做这个决定。

代价三:disputed[] 这个设计,目前几乎是空的。

这是扩写这篇文章时跑统计才发现的落差。当前 370 位人物里,birth 或 death 带非空 disputed 的只有 9 条:

人物字段主值争议值依据
刘邦生年前 256前 247史记集解引皇甫谧等说
李世民生年598599旧唐书推算的另一说
曹叡生年206204据母甄氏归曹时间推算
铁木真生年11621155另一说
刘询卒年前 48前 49按黄龙元年未跨年计

(其余 4 条为陈朝诸帝的推算差,来源标注为「部分年表推算」)

9 条 / 370 人,这个比例说明 disputed[] 更像一个已经建好、但还没真正填进去的容器。Schema 设计得再漂亮,数据没进去就是空转。

而且这 9 条里,像「另一说」「部分年表推算」这种来源标注也太弱了,没有具体到书名卷次,跟「出处强制」的标准是不匹配的。

这是我目前最需要帮忙的地方。  如果你熟悉某一段历史,知道某个人的生卒年存在学术分歧,欢迎带着具体书目来提 PR。一条数据一个 PR,条件是出处要能核。

决策三:时间双轨,原文纪年和公历并存

中文原始史料记时间用年号纪年,比如「秦始皇三十七年七月丙寅」。这个字符串对机器不友好,直接丢给读者又需要一层换算。

所以每条时间字段存两份:original 保留史料原文,year 存归一化公历整数,公元前用负数。551 条年号表单独建了一张表,负责「建元(前 140)→ 宣统(1912)」的换算。

代价四:归一化一定会丢信息。

把「秦始皇三十七年七月丙寅」压成一个 -210,丢掉的是月份、干支日,以及年号纪年本身携带的正统性信息。所以我加了两个补丁字段:circa: true 表示这是约数而非精确值,original 字段保证原文不丢。

这仍然只是缓解。比如陈朝几位皇帝的推算差,本质原因是史料本身记载简略,你压成一个整数就是在假装自己知道得比史料多。真正诚实的做法是让 circa 和 disputed 同时为真,而不是二选一。

现在这套东西的实际状态

不夸大的版本:

维度数量状态
人物370帝王 260 + 后妃/宗室等 monarch 类 14 + 名臣将相等 96
事件154多数带正史卷次出处
年号551建元至宣统,可做换算
文物62大都会/史密森尼/克利夫兰 CC0;大英博物馆 NC 仅放链接
朝代/政权49含十六国、十国、西夏、大理
Wikidata 对齐348/37094%,可接外部知识图谱
人工核验0verified_by 字段未实现

工程侧:零依赖校验器(仅 Python 标准库)+ 引用完整性检查 + 图片许可规则检查,python3 tools/build_sqlite.py 能出单文件 SQLite,打 tag 后 CI 自动构建并发布到 Release。

三条命令上手:

bash

git clone https://github.com/anthonyhann/chinese-history.git
cd chinese-history
python3 tools/validate.py && python3 tools/build_sqlite.py

最后

这个项目现在的状态是:结构比数据成熟。

Schema 里的出处强制、争议多值、时间双轨是认真设计的,校验器也真的在跑。但数据侧的两个窟窿我如实写在这里:disputed[] 只有 9 条,人工核验 0 条。

如果这三条铁律听起来像正确的方向,但你认为实现方式有问题,欢迎直接反驳。我特别想知道两件事:

  1. 出处强制只验形式不验内容,这个漏洞有没有更好的工程手段缓解?
  2. 对于史料本身记载简略的时间(比如陈朝诸帝),你们希望数据层给一个整数,还是给一个区间?

项目地址:github.com/anthonyhann…

事实数据 CC0,工具链 MIT,描述文本 CC BY-SA 4.0。