资治通鉴-文白对照数据-人工智能辅助理解-交互式史书

🚀 在线体验：资治通鉴交互探索

已上线前五卷完整解析（431 段），支持时间轴、人物关系、地点与地图探索。文白对照阅读保留原有地址。

更新记录

2026.10.18（前五卷上线）
- GitHub Pages 同时发布交互探索与文白对照阅读；无需内网转发或自建服务器。
- Haoduotoken GPT-6 Astra / high 与更严格的证据提示词；保留 Terra 基线和独立费用账本。
- 跨卷人物链接自动切换范围，支持别名与浏览器返回；国家、组织不再混入人物按钮。
- 回溯旧事及相对日期不再被强行归到段落年份；未消歧称谓、使者及泛指群体按来源保留。
- 人物原文依据附文言对照；五处译文缺字“孔”按原文“子思”修正派生展示。
- 地点列表与详情可打开现代位置参考；参考点与已核验古址明确区分。
2026.1.17
- 前端可视化（visualization）
  - URL 全局状态同步与历史语义（更稳定的跳转/回退体验）
  - 范围驱动视图（按卷/年份范围过滤事件、地点等），详情交互增强
  - 新增“地图”Tab（Leaflet + OpenStreetMap），地点可一键在地图中查看并高亮定位；地点列表支持搜索
  - 时间轴重构为“时间点列表 + 右侧事件列表”，更适配事件密集年份
  - 关系网络详情增强：人物详情/关系详情中展示“相关事件”，点击可直接打开事件卡片
  - 顶部增加 GitHub 入口与 Star 数展示（更方便关注/收藏）
  - 构建验证步骤补充（任务完成后可复现验证）
- 数据与流水线
  - 统一知识库与类型定义完善（canonical artifact / unified KB types）
  - 地点地理编码：高德(Amap)缓存与回填坐标流程
- 工程化与文档
  - 多处结构/可读性重构与健壮 JSON 解析复用
  - 任务地图与 UX 规范补充与更新；README 增加地图 Demo 截图

效果预览（阶段性成果）

主界面（时间轴）	核心能力：人物关系网

时间轴：事件密集时自动聚类；支持缩放/平移/搜索
人物关系网：点击人物/关系查看详情与交互事件（体现结构化的核心成果）
地点：地点列表与详情，串起相关人物与事件

GitHub Pages 部署

交互探索位于 /zizhitongjian/explore/，原有阅读页面及章节地址保持不变。浏览器直接读取公开 JSON，浏览时不调用模型或高德 API；地图使用 Leaflet 与 OpenStreetMap，当前坐标为现代位置参考，尚未核验为古址。

仓库的 Settings → Pages → Source 使用 GitHub Actions。提交到 main 后，部署工作流会校验公开数据、运行前端测试与构建，再合并 mdBook 阅读站点发布。也可以在 Actions 页面手动运行。

公开快照保存在 visualization/snapshot/。本地更新知识库后，在仓库根目录执行：

python scripts/export_public_snapshot.py
python scripts/validate_artifacts.py --data-dir visualization/snapshot

检查并提交这三个快照文件（两个数据 JSON 和 manifest.json）即可触发发布。导出器目前要求前五卷完整，扩展卷数时需同步调整覆盖范围校验。快照采用字段白名单并记录 SHA-256，构建时验证大小与校验值；模型密钥、高德 Key、费用账本和本地缓存不进入发布包。

新克隆仓库无需 API Key 即可预览已有快照：

python scripts/build_pages.py --install-snapshot
cd visualization
npm ci
npm run dev

复现完整发布包需 Node.js 22、Python 3.12 和 mdBook 0.4.36：先安装快照，以 VITE_BASE_PATH=/zizhitongjian/explore/ 构建前端，再从仓库根目录运行 python scripts/build_pages.py。合并产物在 .pages-build/site/；工作流中包含完整命令。

现成数据下载（无需跑模型）

前五卷 431 段的公开快照已随仓库提交，也可直接下载：

文件	下载	仓库版本
`unified_knowledge.json`	下载知识库	查看文件
`juan_year_index.json`	下载卷年索引	查看文件
`manifest.json`	下载覆盖范围与校验值	查看文件

下载前两个文件，保持文件名不变，放入 visualization/public/data/ 即可供前端使用。已克隆仓库时，优先运行 python scripts/build_pages.py --install-snapshot，它会校验后自动复制这三个文件，不需要 Python 第三方依赖或 API Key。模型结果仍需核对原文；这不是全书的结构化知识库。

供 Agent 使用的 Skill

zizhitongjian-history 提供全书文本检索、前五卷实体/事件检索、关系查询与文白对照出处。查询脚本只需 Python 3.11+，无需安装数据流水线依赖、运行模型或配置 Key。

python skills/zizhitongjian-history/scripts/query.py coverage
python skills/zizhitongjian-history/scripts/query.py search 陈庄 --kind entity
python skills/zizhitongjian-history/scripts/query.py neighbors 陈庄
python skills/zizhitongjian-history/scripts/query.py passage 3-11-4

Agent 可直接读取该 SKILL.md。若使用 Codex，也可把整个 skills/zizhitongjian-history 文件夹复制到 $CODEX_HOME/skills/（未设置时为 ~/.codex/skills/），重新加载后用 $zizhitongjian-history 调用。复制安装后，查询时在子命令前添加 --repo <克隆仓库的绝对路径>；不要只复制 SKILL.md 而遗漏脚本。其他支持 SKILL.md 的 Agent 可按其技能目录约定安装。当前交付为 Skill 和本地 JSON 查询接口，不是 MCP 服务器。

简介

项目地址：zizhitongjian

这个仓库是有关资治通鉴-文白对照的可供人类和机器阅读阅读并进行相关数据研究的项目。

本项目中的文本格式按照原书的卷进行整理，chapters目录下按照[0-9]+_资治通鉴卷名.md进行分别存储：

chapters
├── 001_资治通鉴第一卷(周纪).md
├── 002_资治通鉴第二卷(周纪).md
├── 003_资治通鉴第三卷(周纪).md
...

每一卷的内容格式如下（*表示在部分卷中可能不存在的内容）：

[卷名]*

[时间原文]
[时间译文]

[空白][空白][原文]
[空白][空白][译文]

[空白][空白][原文]
[空白][空白][译文]

[时间原文]
[时间译文]

[空白][空白][原文]
[空白][空白][译文]

结构化数据

结构化数据已由model.py生成，其中的数据结构及生成过程可见于model.py。结构化数据保存于data.json（结构化数据文件）。数据读取和使用样例请见data_usage_demo_visualization.ipynb（结构化数据使用样例）。

资治通鉴数据应用样例：交互式历史可视化系统

本项目新增了基于 React + D3.js 的现代化交互式可视化系统，位于 visualization 目录下。该系统提供了更加流畅、直观的历史数据探索体验，帮助读者从时间、空间、人物关系等多个维度深入理解《资治通鉴》。

主要功能展示

1. 交互式历史事件时间轴 (Interactive Timeline)

全新的时间轴组件支持智能聚类、缩放平移、全局概览及实时搜索。

主界面与时间轴概览：
时间轴细节交互：

2. 复杂人物关系网络 (Relation Network)

通过力导向图展示人物之间的复杂关系，支持点击节点查看人物详情，点击连线查看具体交互事件。

关系网络全景：
人物详情查看：
关系细节查看：

3. 历史地理与地点 (Historical Locations)

展示历史地名及其相关事件，支持查看地点详情。

地点列表：
地点详情：
地图模式（OpenStreetMap）：

本地启动方法

环境要求：Python 3.11+（本地验证使用 3.12）、Node.js 22.13+。干净克隆中包含 294 卷文本和前五卷已发布的模型抽取快照。默认使用现成快照，不需要 uv、Python 第三方依赖或 API 密钥：

python scripts/build_pages.py --install-snapshot
cd visualization
npm ci
npm run dev -- --host 127.0.0.1

打开 http://127.0.0.1:5173/，默认展示前五卷，包含时间轴、关系网络、地点和现代位置参考。只有需要开发或运行 Python 数据流水线时，才需在根目录运行 uv sync --locked --python 3.12。 Windows 上若 uv 未加入 PATH，可使用 python -m uv。

旧的 scripts/prepare_demo.py 仍用于最小样例调试；它不含完整事件和地图数据，不应替代上述公开快照。样例卷号只是展示分组，不可用于历史研究。

本地开发

这个仓库主要分为两层：

文本与数据流水线：Markdown 卷册、结构化书籍 JSON、抽取模型、数据产物构建脚本。
可视化前端：位于 visualization/，读取 visualization/public/data/ 中的运行时 JSON。

Python 检查

uv run pytest -q
uv run python scripts/validate_segment_year_index.py --fail

前端检查

cd visualization
npm ci
npm test
npm run lint
npm run build

运行时数据

前端需要以下文件：

visualization/public/data/unified_knowledge.json
visualization/public/data/juan_year_index.json

这些运行时文件不纳入 Git。使用已发布的数据时，从 visualization/snapshot/ 安装即可；只有重新抽取或扩充数据时，才需要以下流水线。

构建正式数据

将 .env.sample 复制为 .env，填写 DEEPSEEK_API_KEY，按实际可用模型设置 DEEPSEEK_MODEL。
先查看待抽取范围，再运行小批量请求：

uv run python knowledge_extraction.py --dry-run --juan-start 1 --juan-end 1
uv run python knowledge_extraction.py --juan-start 1 --juan-end 1 --limit 5
uv run python scripts/build_data.py --publish-frontend

抽取命令会调用收费 API；默认仅处理 1 个未完成片段，默认 4 个工作线程，单次请求超时 120 秒。可用 --limit N 限制批量，或显式使用 --all 处理所选卷范围内的全部待处理片段。已保存片段会跳过，失败时命令返回非零退出码，重跑可继续。请求并发执行，缓存由主线程串行保存。

全书原始分段共有 30,758 个句子片段；请先验证小批量质量再扩大范围。 build_data.py --publish-frontend 会验证并用正式产物替换前端样例。需要地图坐标时，配置 AMAP_KEY 后加 --geocode。仅重建年份索引可用 uv run python scripts/build_data.py --skip-resolve；此命令不会凭空生成缺失的知识库。

本地 API 密钥

Haoduotoken / GPT Terra 预算抽取

在 .env 配置 HAODUOTOKEN_API_KEY 和 HAODUOTOKEN_BASE_URL，然后使用 scripts/run_budgeted_extraction.py。这个入口默认选择 gpt-5.6-terra、medium 推理、4 个并发请求，每次最多 8,192 输出 token，SDK 重试关闭。收到完整但校验失败的答案时，最多附带具体校验反馈纠正一次，两次请求分别计费；网络断连或用量不明不自动重试。scripts/replay_extraction_responses.py 可离线恢复已付费但未入库的完整响应；无从核实的原文引句留空，并写入 quality_notes。

以下是 2026-10-18 本次运行的 30 元上限命令；单价按当时 ByteToken Codex Pro 分组报价核对，输入采用包含缓存写入的保守上限，单位是元/百万 token。未来运行须重新核对服务商分组、价格和币种，不要将这个快照当成长期价格表。

.\.venv\Scripts\python.exe scripts\run_budgeted_extraction.py --budget-cny 30 --input-cny-per-million 0.075 --output-cny-per-million 0.36 --limit 3 --workers 1

删除 --limit 3 --workers 1 后会逐卷继续，直到预算不足以预留下一次请求、全部完成、连续运行中累计 5 个校验失败，或遇到服务商/用量/价格异常。首次运行和每次发布会核验公开价格契约；每 100 个成功片段以及正常结束时，重新合并并验证知识库后发布到本地前端。刷新页面即可查看最新快照。

预算账本保存在 data/runs/terra-budget.sqlite3，状态摘要在同名 .json；重启继续使用同一账本，不会重置 30 元额度。请求先预留 UTF-8 字节上限加完整输出上限的费用，再按返回的实际 token 数保守结算，不扣缓存折扣；异常、断线或用量不明时保留全额预留。思考 token 包含在输出用量中。已付费响应保存到 data/runs/responses/，便于离线排查，避免重复付费。摘要中的 accounted_cny 是保守预算占用，服务商实扣须另按请求日志对账。

需要停止时创建 data/runs/terra-budget.stop；当前请求会完成并落盘，之后不再发起新请求。删除此停止文件，再运行同一命令可续跑。不要删除或更换账本来续跑同一预算任务。

限定本次前五卷（共 431 个片段）并续跑已有数据：

$env:NO_PROXY='byte.haoduotoken.com,restapi.amap.com'
.\.venv\Scripts\python.exe scripts\run_budgeted_extraction.py --budget-cny 30 --input-cny-per-million 0.075 --output-cny-per-million 0.36 --juan-end 5 --workers 8 --effort low --stream --timeout-sec 300 --max-output-tokens 16384 --publish-every 40
.\.venv\Scripts\python.exe scripts\audit_extraction.py --juan-end 5
.\.venv\Scripts\python.exe scripts\reconcile_extraction_cost.py

--stream 请求最终用量，并在结束后组装完整答案；缺少用量或完成标记时仍保留费用预留并停机。 NO_PROXY 仅对本次进程指定的两个服务直连，适用于本地代理出现 TLS 断连时；不修改系统代理。时间轴不会把段落记载年份自动当成所引用旧事的发生年份。未明确到年的事件单列为“年份待核验”。审计结果写入 data/runs/first-five-audit.json，检查片段覆盖、原文一致性、模型、来源和引用。金额对账只按本任务请求匹配服务商日志，未匹配请求继续保守计入预算。

前端“前五卷”快捷按钮可直接打开本次范围；顶部逐卷显示实际完成数量。同名事件按原文年段分开，别名不重复计提及次数；尚未消歧的“秦王”“公子”等称谓按原文片段保留。关系按真实发生记录筛选，地点按原文出现年份筛选。人物详情可展开“原文依据”进行复核。这些校验不代表人物背景、史论或古今地名已经完成历史审校。

本次升级：GPT-6 Astra / high

本地当前任务总预算仍为 30 元。Terra 基线占用上界为 0.54367064 元，其停止文件 data/runs/terra-budget.stop 已保留；Astra 的新账本上限为 29 元。两个上限合计不超过 30 元，不能删除停止文件并同时启用旧账本继续花费。本次 431 个片段已全部完成；累计匹配服务商实扣 1.849202 元，连同旧版未匹配请求的全额预留，保守占用 2.039424765 元。完整记录见本地 data/runs/astra-v2/run-summary.json。这次数据包括 25 个现代参考点，均不代表已核验古址。这些是本任务验证过的 Haoduotoken 账户组价格，不是 OpenAI 官方价格。每次启动会重新核验服务商价格契约，发生变化即停止。

新版结果存放在 data/store-astra-v2，基线仍在 data/store。仅补跑缺失片段，使用原账本与相同提示词：

$env:NO_PROXY='byte.haoduotoken.com,restapi.amap.com'
.\.venv\Scripts\python.exe scripts/run_budgeted_extraction.py --model gpt-6-astra --prompt prompts/extraction_grounded_v2.md --budget-cny 29 --input-cny-per-million 0.375 --output-cny-per-million 1.5 --ledger data/runs/astra-v2/budget.sqlite3 --store-dir data/store-astra-v2 --juan-end 5 --workers 12 --effort high --stream --timeout-sec 300 --max-output-tokens 32768 --no-publish
.\.venv\Scripts\python.exe scripts/audit_extraction.py --store-dir data/store-astra-v2 --model gpt-6-astra --juan-end 5 --out data/runs/astra-v2/audit.json
.\.venv\Scripts\python.exe scripts/reconcile_extraction_cost.py --ledger data/runs/astra-v2/budget.sqlite3

审计通过后，离线重建并发布（不调用模型）：

.\.venv\Scripts\python.exe -c "from pathlib import Path; from scripts.run_budgeted_extraction import publish; publish(Path('data/store-astra-v2'))"

data/runs/astra-v2/evaluation.json 记录八个定向样本的人工比较， audit.json 记录完整覆盖与结构检查，budget.reconciliation.json 按请求对账。定向样本不能代表全库准确率；新版同时更换模型和提示词，不能只把改进归因于模型。文言校正只修改派生展示，保留原始抽取、原文和付费响应供追溯。前五卷已核对的地点别称“蜀／蜀国／蜀地”“安邑／安邑城”“阳翟／阳翟城” 在地理视图中合并，国家实体仍按自身类型保留，不据此推断古代疆界或坐标。

地图底图使用 Leaflet + OpenStreetMap，不需要高德 Key。高德仅用于地点坐标解析，需要“Web 服务”类型的 AMAP_KEY。古地名对应今址、行政区中心和具体遗址不能混为一谈；候选坐标应审查后回填，未核验地点在页面中明确提示。

本地密钥只放在被忽略的 .env 中。复制 .env.sample 为 .env 后再填写本机配置：

cp .env.sample .env

DeepSeek 抽取入口需要设置 DEEPSEEK_API_KEY；Haoduotoken 入口使用自己的密钥变量。 knowledge_extraction.py 与单片段 smoke 脚本会自动加载仓库根目录的 .env；已设置的进程环境变量优先，命令行 --model 优先于 DEEPSEEK_MODEL。

只有运行地理编码时才需要设置 AMAP_KEY。地理编码脚本会自动加载 .env。不要提交 .env。

默认抽取模型是 deepseek-v4-flash。需要更强推理能力时，将 DEEPSEEK_MODEL 设为 deepseek-v4-pro。

工程文档

技术实现简述

为了支撑上述可视化系统，本项目构建了一套完整的知识提取与融合流程：

AI 知识提取 (Knowledge Extraction)
- 利用大语言模型对《资治通鉴》原文进行深度语义分析。
- 自动提取人物 (Roles)、地点 (Locations)、事件 (Events) 及人物关系 (Relations)。
实体消歧与融合 (Entity Resolution)
- 智能合并：通过 Union-Find 算法，将同一人物的不同称呼（如“赵籍”、“赵侯”）自动合并为统一实体。
- 防误触机制：内置黑名单机制，防止“王”、“臣”、“公子”等通用称谓导致错误合并。
- 人地分离：特殊处理逻辑区分人名与国名（如区分“赵籍”与“赵国”），确保关系网络准确性。
统一知识库 (Unified Knowledge Base)
- 将分散在各卷的碎片化信息重组为时空连贯的结构化数据，支持跨卷检索与分析。
地点地理编码 (Geocoding)
- 使用高德(Amap)为 data/unified_knowledge.json 的地点补全 WGS84 坐标（coordinates: [lng, lat]）。
- 配置：复制 .env.sample 为 .env，填入 AMAP_KEY。
- 运行：python scripts/geocode_locations_amap.py 生成候选缓存。即使高德只返回一个地址，也会标记 needs_review=true 并保留匹配地址、行政级别和候选坐标，避免把现代行政区中心误当成古址。
- 核验后在缓存 overrides 中记录该地点的 WGS84 coordinates: [经度, 纬度] 和 notes（依据）；python scripts/merge_geocoding_into_unified_kb.py 回填已核验坐标。抽取脚本发布数据时也会自动合并缓存，保留人工核验结果。
- 地图可显示匹配今地名的单一候选，使用橙色空心点标注“现代位置参考”。多候选、省级中心和未匹配今地名的结果不显示；候选不用于人物轨迹。
- 速率控制：默认每次请求间隔 0.25s（可用 --sleep 调整），避免触发限流。
- 无密钥也可预跑：不设置 AMAP_KEY 时会自动进入 --simulate（只写入 query/needs_review，不调用 API）。

项目进展

项目在持续更新，目前任务列表完成情况如下：

文本内容获取
格式化卷名，便于排序及查询
时间数据的译文格式保持和原文格式统一
去除不符合文白对照格式的空行、空格，使用统一的换行格式
文本内容程序化校对，定位残缺和错误内容
文本数据结构化，便于利用数据分析工具和可视化工具进行处理
结构化数据使用样例
AI辅助理解及可视化样例
AI辅助获取全书知识图谱（人物、事件及其关系，以及在格式化数据中的精确定位）
对话交互式资治通鉴
...

数据预处理的部分源码及说明在本项目的*.ipynb中存档及更新。

如果有任何感兴趣的、想要这个项目做的，请随时、尽情建议！

参与贡献

请随时、尽情在issue中提供任何意见建议，不限于文本内容、文本格式、数据结构、数据分析、数据可视化等任何主题；
文本中有[todo]的地方为分析过程中发现的内容残缺的部分，可以参与校对和修复:D

资治通鉴-文白对照