做中文历史类应用的开发者大概都遇到过这个场景:想查汉武帝在位多少年,要么翻维基百科手抄,要么爬百科站点担心版权,要么去用学术库被它的格式劝退。
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 | 史记集解引皇甫谧等说 |
| 李世民 | 生年 | 598 | 599 | 旧唐书推算的另一说 |
| 曹叡 | 生年 | 206 | 204 | 据母甄氏归曹时间推算 |
| 铁木真 | 生年 | 1162 | 1155 | 另一说 |
| 刘询 | 卒年 | 前 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/370 | 94%,可接外部知识图谱 |
| 人工核验 | 0 | verified_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 条。
如果这三条铁律听起来像正确的方向,但你认为实现方式有问题,欢迎直接反驳。我特别想知道两件事:
- 出处强制只验形式不验内容,这个漏洞有没有更好的工程手段缓解?
- 对于史料本身记载简略的时间(比如陈朝诸帝),你们希望数据层给一个整数,还是给一个区间?
事实数据 CC0,工具链 MIT,描述文本 CC BY-SA 4.0。