人生经纬 · LifeTrace

Use when creating a sourced lifetime footprint map for a historical figure, public figure, family member, or private person from public research, JSON, or CSV data, especially when the result should be an interactive HTML timeline using AMap geocoding or map links.

把人物经历整理为“时间—地点—事件—来源—可信度”数据，并生成可播放、可点击的动态 HTML 人生足迹图。

运行要求

• Node.js 18 或更高版本。
• 真实地图预览需要联网，并在环境变量中提供高德 Web JS API Key：AMAP_KEY；新版 Key 可同时提供 AMAP_SECURITY_KEY。
• 需要读取人物数据、图片素材并写入 HTML/JSON；serve 仅监听本机 127.0.0.1。
• 可选安装 amap-cli-skill，用于高德地图状态与交互校验。

使用场景

• 为历史人物或公众人物整理公开、可引用的人生轨迹。
• 用用户提供的 JSON/CSV 制作本人、家人或纪念人物地图。
• 为教学、展览、传记和数字人文内容制作可交互时间地图。

工作流

1. 判断模式：公开人物走资料研究；普通人只处理用户主动提供的数据。
2. 建立事件表：记录时间、地点、事件、来源和可信度。
3. 核对地点：优先使用用户坐标；否则经用户允许后调用高德地理编码。不得用模型记忆伪造坐标。
4. 区分路线：历史人物使用地点关系线；现代导航路线只表示今天的道路，不得称为历史人物真实行程。
5. 按需生成人物像：读取 portrait-prompt.md，填充已核对的人物变量并生成 1:1 透明 PNG；逐字核对中文并确认透明通道，以 <person-slug>-portrait.png 保存。用户已提供授权图片时优先使用该图片，不重复生成。
6. 按需生成核心故事图：读取 story-prompt.md，只为最具代表性的事件制作 4:3 横向插图，并放入同一人物与故事画廊；不强制逐事件配图。
7. 运行校验并生成 HTML；使用 serve 从环境变量加载真实高德地图，检查动态播放、重置、标记、人物画廊、故事图和侧栏联动。

公开人物

• 搜索公开资料并打开原始页面，不把搜索摘要当作来源。
• 每个事件至少保留一个来源；重要转折点尽量交叉核对。
• 使用 confirmed、inferred、disputed 表示可信度。
• 古地名映射到现代位置时保留原名，并说明推定范围。

普通人

• 默认不联网搜索，不从零散信息推断住址或实时位置。
• 只读取用户上传内容；发布前检查精确住址、手机号、未成年人信息和照片授权。
• CSV 缺少坐标时，列出待补地点；未经允许不得联网，也不得伪造坐标。

使用教程

验证数据：

powershell

node life-trace.mjs validate liu-bei.json

生成公开人物地图：

powershell

node life-trace.mjs build liu-bei.json demo.html

生成普通人地图：

powershell

node life-trace.mjs build personal-template.csv my-life.html --person "我的人生地图"

经用户允许后用高德查询坐标：

powershell

$env:AMAP_KEY="你的高德 Web 服务 Key"
node life-trace.mjs geocode "四川省成都市"

Key 只从环境变量读取，不写入 Skill、数据或 HTML。

启动真实高德地图 Demo：

powershell

$env:AMAP_KEY="你的高德 Web JS API Key"
$env:AMAP_SECURITY_KEY="对应的安全密钥（旧版 Key 可留空）"
node life-trace.mjs serve demo.html

固定预览地址为 http://127.0.0.1:8777/demo.html。不要直接双击 demo.html：页面需要由 serve 在内存中注入高德配置。凭据错误时必须显示错误，不得用案例轮廓图冒充高德在线地图。

Demo 演示

先运行 node life-trace.mjs build liu-bei.json demo.html，再运行 node life-trace.mjs serve demo.html 并打开输出地址：

1. 点击“播放足迹”，路线按年代逐段点亮。
2. 播放到任意节点后点击“重置”，路线立即回到第一站。
3. 点击地图节点，右侧跳转到对应地点故事。
4. 左右滑动同一人物与故事画廊；人物像之后依次查看核心故事图，点击带图事件会自动跳转。
5. 点击时间轴卡片，地图聚焦并高亮该节点。
6. 点击“在高德地图查看”，用高德 URI 打开现代位置。

输出要求

• 保留人物标题、事件时间轴、来源、可信度和数据质量提示。
• 若包含人物像或故事图，构建时将图片嵌入 HTML，确保 ClawHub 分发后的 Demo 仍完整可用。
• 人物像与核心故事图使用统一的 4:3 画廊尺寸，并在右侧时间线顶部循环切换。
• 对无法定位的事件报错或排除出路线，不静默补造坐标。
• 最终 HTML 不包含 AMAP_KEY 或 AMAP_SECURITY_KEY，由本机 serve 运行时注入。