一天一个开源项目(第263篇):江山时序 —— 纯静态的中国历史交互地图,从三家分晋拖到今天,还能让 AI 查地名

引言

「某某古城、古战场如今在地图哪里?」

这是「一天一个开源项目」系列的第 263 篇 。今天的项目是 DeanChensj 的 江山时序 · Chronicles of the Realm (仓库名 jiangshan-map)。

读史、读诗的时候,几乎每个人都问过同一类问题:李白出蜀,一路经过的那些地名,现在是哪里?赤壁之战到底在今天的什么位置?长安历代叫什么名字?这些问题靠翻文字注释很费劲,靠一张死图又看不出「变化」。

江山时序的做法是把它做成一张会动的地图 :拖动时间轴,疆域、政区、河流、长城、运河随年代变化;点一座古城,看它在 18 个时期里的沿革;搜一个人,看他一路的行迹。它是纯静态网站,不需要后端。更特别的是,它还给 AI 准备了入口:本地 MCP Server、Agent Skill 和 llms.txt。

本文基于 README 和仓库目录整理。我没有部署运行,也没有逐项核对地图上的历史数据是否准确。

你将学到什么

  • 江山时序能回答哪几类历史地理问题
  • 时间轴、点地溯源、点人溯事、点事溯局这几种交互是怎么用的
  • 怎么本地运行,或者用 Docker 部署
  • 怎么通过 MCP、Skill 和 URL 协议让 AI 来查询它
  • 它的数据来源与许可,特别是哪些数据不适用 GPL

前置知识

  • 对中国历史有基本兴趣即可
  • 本地运行需要会用 Python 的 http.server,或会用 Docker
  • 可选:了解 MCP 与 Agent Skill

项目背景

项目简介

README 的定位是:一个纯静态的中国历史交互舆图网站,覆盖从公元前 403 年(三家分晋)到今天的约 2,400 年,旨在回答读史读诗时常有的疑问,比如「某某古城、古战场如今在地图哪里」「疆域怎样一步步变迁」「长安历代叫什么」。在线地址是 https://deanchen.me/jiangshan-map/。

项目数据

  • ⭐ GitHub Stars:约 7,301
  • 🍴 Forks:约 875
  • 💻 语言:JavaScript
  • 📅 创建时间:2026-07-23,最近一次推送为 2026-11-16,仍在活跃更新
  • 📄 许可证:GPL-3.0(仅针对代码和自绘数据,详见下文「数据来源与许可」)
  • 👤 作者:DeanChensj
  • 🌐 在线地址:deanchen.me/jiangshan-map
  • 🌏 提供简体中文、繁体中文、日文和英文的 README

关于规模,仓库的 About 描述写的是「18 个朝代、198 个疆域快照,以及古今地名谱系和古典诗词路线」。README 正文只明确给出 18 个历史时期和 2,400 余年,没有给出地名数、诗词数之类的汇总数字,所以本文不写这些数。


主要功能

它解决的问题

复制代码
读史读诗时:
  文字注释里的地名 → 不知道今天在哪
  疆域变迁 → 一张静态图看不出过程
  同一座城 → 历代名字不同,容易混

江山时序:
  拖动时间轴 → 疆域、政区、水系随年代变化
  点古城 → 看历代沿革
  搜人物 → 看一路行迹

核心能力

功能 说明
时间轴 可拖动、可缩放(向内拖两端手柄放大短朝代,双击复原);显示当年在位帝王与年号;空格自动播放,左右键跳阶段(加 Shift 跳 10 年),支持语音讲解
多政权同屏与分阶段疆域 用高对比的宣纸设色呈现政权,悬停图例高亮,点击打开政权档案;切换阶段时会显示上一阶段的朱砂虚线残影
图例与政区 「现代省界」「现代省名」可对照古今;悬停州郡可查沿革;黄河改道、古湖消长、长城、运河、丝路、郑和航线、古海岸线随年代变化
点地溯源 点击古城或名关(或双击地图),出现名城题记、18 个时期的沿革和定点大事;「史事纪要」可筛选有事件的朝代,点击事件可「穿越」到该年
点人溯事 搜索人物,逐站查看行迹并同步年份、帝王和版图;内置秦始皇、张骞、诸葛亮、玄奘、李白、苏轼、王阳明等;支持多人同看(如 李白 杜甫 高适),并标出「同途」交汇点
点事溯局 楚汉之争、安史之乱、靖康之变,每个事件 10 个节点,分三幕
彩蛋 「舆图寻址 · 古地名小试」,10 道题,按得分授予「太史令 · 舆图大家」等官阶

仓库里还有一个 topics/ 目录,下面是单独的专题页,比如赤壁、长平、淝水之战,以及李白、苏轼、王阳明、玄奘等人的行迹,以及各朝代页面。

快速开始

本地运行(它是纯静态站点,任何静态服务器都行):

bash 复制代码
git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000

然后打开 http://localhost:8000。

Docker 部署:

bash 复制代码
docker compose up -d --build

访问 http://localhost:8008。README 注明镜像基于 nginx:alpine,没有发布到镜像仓库,需要自己构建。

嵌入到别的页面 :在链接后加 &embed=1,再放进 iframe;可以配合 from、to 限定时间轴范围,用 lock=1 锁定,用 autoplay=1 自动播放。README 说明微信公众号、知乎、小红书不支持嵌入。


项目详细剖析

给 AI 准备的三个入口

这是我觉得这个项目最有意思的一点:它不只给人看,还专门给 AI 留了接口。

1. MCP Server :scripts/mcp_server.js,README 称零第三方依赖,提供三个工具:

工具 用途
inspect_place 查询某个地点
inspect_person 查询某个人物
search_atlas 在舆图里搜索

2. Agent Skill :skills/jiangshan-atlas/SKILL.md,附带命令行脚本 skills/jiangshan-atlas/scripts/jiangshan.py,可以用 --year、--place、--out 参数出图。

3. llms.txt 和 URL 协议 :llms.txt 是机器可读的说明;URL 协议支持单点、同年多站,以及跨年多站(年份与地点按顺序对应)。浏览器端还有 window.atlasAPI(locate、inspect、resolvePlace、openPerson、search)和 WebMCP。

这三条路径对应三种用法:让 Agent 直接调用工具;让 Agent 生成一张指定年份、指定地点的图;或者让 Agent 拼一个 URL 发给你,你点开就能看到定位好的地图。具体的调用效果我没有实测,上面都是按 README 和目录整理的。

数据来源与许可:这一节请认真读

项目的许可证是 GPL-3.0,但并不是所有数据都适用 GPL。README 的说明如下:

数据 来源 许可
代码与自绘数据 项目自己 GPL-3.0
政权轮廓 以 aourednik/historical-basemaps 为起点手工重绘 项目自绘部分按 GPL-3.0
郡、州、府边界 源自 CHGIS V6 与 Hartwell GIS 不适用 GPL,仅限学术、非商业使用,不得再分发
现代省界 DataV GeoAtlas 见其来源
河流湖泊 公有领域
地形 基于 AWS Terrain Tiles(SRTM、GMTED2010、ETOPO1) 见其来源

几点实际影响:

  • 商用或再分发前要先看数据来源:代码是 GPL-3.0,不等于里面的所有数据都能随便用于商业场景
  • 导出 GeoJSON 时,郡州府边界默认不导出 ,需要加 --with-prefectures 才会导出,这是项目有意设置的保护
  • GeoJSON 导出范围是公元前 403 年到 1948 年,不含现代省界
  • 复用时需要注明「江山时序 Jiangshan Atlas」及原仓库链接;引用 CHGIS 时的格式是 CHGIS, Version: 6. © Fairbank Center ..., 2016.

准确性:它自己怎么说

这是做历史地图最容易被追问的地方。README 的说法很明确:

  • 历史疆域与政区边界均为示意性近似,不是测绘成果,不宜作为权威边界依据
  • 早期一级政区的原始来源未记录

也就是说,它适合用来理解变迁的大势和地点的沿革,而不适合用来做严肃的边界考证,更不适合拿来当争议问题的依据。

仓库的 scripts/ 下有一批审计和校验脚本,比如 validate_atlas.js、audit_sources.js、audit_topology.js、check_sources.js,说明作者在做数据校验。但这些脚本具体检查了什么、通过率如何,我没有去读,也没有运行。

仓库结构

  • index.html、css/、js/:前端本体
  • data/:舆图数据,下分 atlas 和 sources
  • geojson/:GeoJSON 的示例与定位脚本
  • topics/:专题页
  • scripts/:构建、校验、导出和 MCP Server
  • skills/:Agent Skill
  • workers/:目录下有一个 stats,我没有读它,不确定具体用途(如果你在意隐私,可以自己看一下)
  • Dockerfile、docker-compose.yml:容器化部署

局限与注意事项

  1. 边界是示意性的:README 明确声明,不能当作权威依据
  2. 部分数据有使用限制:郡州府边界仅限学术非商业,且不能再分发
  3. 导出范围有限:GeoJSON 只到 1948 年,不含现代省界
  4. 嵌入平台受限:微信公众号、知乎、小红书不支持嵌入
  5. Docker 镜像要自己构建:没有发布到镜像仓库
  6. 年轻项目:2026 年 7 月创建,没有看到稳定版承诺,使用前自己评估成熟度

项目地址与资源

  • 🌟 GitHub :github.com/DeanChensj/...
  • 🌐 在线地址 :deanchen.me/jiangshan-m...
  • 🤝 贡献 :仓库内的 CONTRIBUTING_ZH.md;数据纠错可以提交 Issue 模板,最好附出处
  • 📄 许可证:代码与自绘数据 GPL-3.0;郡州府数据另有限制

总结与展望

核心要点回顾

  1. 定位:纯静态的中国历史交互地图,约 2,400 年、18 个历史时期,拖动时间轴看变迁
  2. 交互丰富:点地溯源、点人溯事、点事溯局,多人行迹还能标出「同途」
  3. 对 AI 友好 :本地 MCP Server、Agent Skill、llms.txt 和 URL 协议
  4. 数据要看许可:代码 GPL-3.0,但郡州府边界仅限学术非商业、不得再分发
  5. 边界是示意的:适合理解大势,不适合当权威考证依据

适用人群

  • 读史、读诗时想直观看地理变迁的人
  • 历史课程、科普内容的创作者,需要可嵌入的互动地图
  • 想研究「如何让一个静态网站对 AI 友好」的开发者,这套 MCP、Skill、llms.txt 的组合值得参考

学习建议

先在线打开,试几个入口:拖一遍时间轴,点一座你熟悉的古城,再搜「李白 杜甫」看同途标注。想看技术细节,读 scripts/mcp_server.js 和 skills/jiangshan-atlas/SKILL.md,它们展示了怎么把一个网站变成 AI 能调用的工具。如果打算商用或再分发,先把 README 里的数据来源与许可那一节读完。


欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场,所有内容均经过真实企业级工作流验证。没有噱头,只有真正有效的东西。

更多实用知识和有趣产品,欢迎访问我的个人主页

相关推荐
wflynn1 小时前
GitHub 日榜趋势速报 | 2026-11-18
开源·github
Pniubi3 小时前
SoduWork开源贡献日记——开源贡献入门教程
开源
Yeautumn5 小时前
给 Antigravity 搓了个「主 Carbon + 副 Neon」混合编排插件:让顶配模型当包工头,快手模型并发干活
开源
阿里云云原生8 小时前
云原生开源项目周报(2026 / 11.09 — 11.16)
云原生·开源
Bigger11 小时前
我扒了 GitHub Trending 前 20,8 个在做同一件事:给 Coding Agent 造基础设施
开源·github·ai编程
openUBMC11 小时前
从带外管理到开源共建:openUBMC 走进华南高校
开源
wflynn13 小时前
GitHub 今日推荐|rust-anything:录制真实输入输出,渐进式重写热点函数到 Rust
rust·开源·github·cli·claude-code·agent-skills
wflynn14 小时前
GitHub 日榜趋势速报 | 2026-11-17
开源·github
一只爱撸猫的程序猿1 天前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源