跪拜 Guibai
← All articles
Open Source

Drag a Timeline Across 2,400 Years of Chinese History on This Static Map

By 冬奇Lab ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

The project demonstrates how a static site can expose AI-queryable interfaces without a backend, and its license split shows that open-source code does not mean open data. Developers reusing the map need to check per-dataset restrictions before commercial use or redistribution.

Summary

Jiangshan Chronicles (jiangshan-map) is a pure static interactive atlas that lets you drag a timeline from 403 BC, the year the Jin state split into three, all the way to today. The map redraws territories, rivers, walls, and canals as the era shifts, and clicking an ancient city reveals its evolution across 18 periods. A person search traces individual journeys, and multi-person searches mark where paths intersected, like the meeting of Li Bai, Du Fu, and Gao Shi. The repo has roughly 7,300 stars and is still actively updated as of November 2026.

Beyond the human-facing interactions, the project ships three ways for AI agents to query it: a zero-dependency local MCP server with inspect_place, inspect_person, and search_atlas tools; an Agent Skill with a CLI script that generates maps for a given year and place; and an llms.txt file plus a URL protocol that embeds map views. The browser exposes window.atlasAPI and WebMCP as well. The README explicitly says the map boundaries are illustrative approximations, not authoritative survey results.

Licensing is split: code and self-drawn data are GPL-3.0, but prefecture boundaries from CHGIS V6 and Hartwell GIS are academic non-commercial only, no redistribution, and are not included in default GeoJSON exports. GeoJSON export only covers 403 BC to 1948 and omits modern province boundaries. Deployment is a static server or Docker with nginx:alpine, and embedding works through URL parameters, though WeChat, Zhihu, and Xiaohongshu block iframes.

Takeaways
— Covers 18 historical periods and roughly 2,400 years, from 403 BC (Partition of Jin) to the present.
— Interactive timeline supports drag, zoom, keyboard shortcuts, spacebar auto-play, and voice narration.
— Clicking a place shows its evolution across 18 periods; searching a person shows their journey with synchronized year, emperor, and territory.
— Supports multi-person searches, marking shared path intersections (e.g., Li Bai, Du Fu, Gao Shi).
— Event tracing provides 10 nodes per event across three acts for Chu-Han Contention, An Lushan Rebellion, and Jingkang Incident.
— AI access via MCP server with three tools (inspect_place, inspect_person, search_atlas), an Agent Skill with CLI script, llms.txt, and URL protocol.
— License: GPL-3.0 applies only to code and self-drawn data; prefecture boundaries from CHGIS are academic non-commercial only, no redistribution.
— GeoJSON export excludes prefecture boundaries by default, requires --with-prefectures, and covers 403 BC to 1948, without modern province boundaries.
— README disclaims boundary accuracy as illustrative approximations, not authoritative.
— Runs as a static site with any static server (e.g., python3 -m http.server) or Docker (nginx:alpine, image not published).
— Embedding via &embed=1 with from, to, lock, autoplay parameters; not supported on WeChat, Zhihu, or Xiaohongshu.
— Project created July 2026, last push November 2026, with roughly 7,301 stars and 875 forks.
Conclusions

The project's three AI entry points (MCP, Agent Skill, llms.txt) are a concrete example of how a static site can serve AI agents without a backend, a pattern worth copying for other content-heavy projects.

The license split between GPL code and academically restricted prefecture data is a reminder that open-source repositories can mix permissive and restricted assets; the default-on exclusion of prefecture boundaries in GeoJSON exports is a sensible safeguard.

The explicit disclaimer that boundaries are illustrative avoids the trap of presenting historical maps as authoritative, which is important given how easily such visualizations get cited as fact.

Concepts & terms
MCP (Model Context Protocol)
An open protocol that lets AI models call external tools and services through a standardized server interface. In this project, a local MCP server exposes functions like inspect_place and inspect_person so an AI agent can query the map data.
Agent Skill
A packaged capability that an AI agent can load and use, typically defined in a SKILL.md file with instructions and optional command-line scripts. Here, the skill includes a Python script that generates maps for specified years and places.
llms.txt
A machine-readable text file that describes a website's content and URLs for AI systems to discover and reference. It follows a proposed convention for making sites more accessible to large language models.
From the discussion
Featured comments
season_zhu

Suggestion: add the Xia, Shang, and Western Zhou periods, and including the Three Sovereigns and Five Emperors era would make it even more perfect.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗