司天地图数据规范
本页面说明司天（SiTian）编辑器如何从 Obsidian 库读取地理数据，以及 层级、上层区域、地点类型 等 frontmatter 字段的填写规则，确保笔记能正确映射为地图节点。
数据流
Markdown（本库，唯一事实源）
→ node scripts/extract-data.js（提取脚本）
→ .sitian/geodata.json（坐标缓存，可删除后重建）
→ 司天编辑器渲染
- Markdown 是唯一事实源：节点名称、层级、从属关系全部来自 frontmatter / 文件名 / 索引。
- 坐标不属于世界观：节点坐标仅存于
.sitian/geodata.json，永远不要手动写入 frontmatter。
- 手动拖拽过的节点带
userMoved 标记，重新提取后坐标会保留（不被布局算法重置）。
数据来源目录
| 目录 | 提取内容 |
|---|
03 设定/11 地理系统/星域/ | 星域（star_domain） |
03 设定/11 地理系统/星系/ | 恒星系（galaxy） |
03 设定/11 地理系统/行星/ | 行星（planet） |
03 设定/02 场景地点/ | 场景地点（城市/城镇/村庄/设施/区域/地点等） |
01 索引/地理系统索引.md | 世界与星域层级补全（按缩进级别区分星域/星系） |
frontmatter 字段总览
| 字段 | 用途 | 必填 | 取值 |
|---|
层级 | 节点在地图树中的层级 | 地理系统必填；场景地点建议填 | 见「层级字段」 |
上层区域 | 直接父级节点（wikilink） | 建议填 | '[[父节点名]]' 或裸名 |
地点类型 | 地点的细分类型（第二维度） | 场景地点建议填 | 见「地点类型字段」 |
publish / tags / 创建日期 / 最后更新 / 模板版本 | 常规字段 | 按既有规范 | — |
层级字段
层级 决定节点在地图中的类型与渲染样式。直接写中文值，不要写英文代码（facility 等由脚本自动转换）。
| frontmatter 值 | 地图类型（layer） | 说明 |
|---|
世界 | world | 顶层世界 |
星域 | star_domain | 世界下的宏观区域 |
星系 | galaxy | 星域下的恒星系 |
行星 | planet | 恒星系中的天体 |
恒星 | star | 恒星 |
卫星 | moon | 卫星 |
区域 | region | 地理区域（岛、流域等） |
城市 | city | 城市聚落 |
城镇 | town | 城镇聚落 |
村庄 | village | 村庄聚落 |
设施 | facility | 建筑/设施（宫殿、商店、工厂、学校等） |
地点 | location | 自然地貌或难以归类的特殊地点 |
填写规则
- 直接写上表中文值；禁止写英文代码（如
facility）——旧版本已写入的英文值会被脚本自动修正，但新笔记请直接写中文。
- 场景地点未写
层级 时，脚本按「文件名后缀 → 标签 → 正文类别」推断，但推断不如显式标注可靠，建议显式填写。
- 聚落（城市/城镇/村庄）有独立渲染样式，不填
地点类型。
文件名后缀推断（未写层级时的兜底规则）
X城 → 城市；X镇 → 城镇；X村 → 村庄X岛 / X半岛 / X流域 → 区域X府 / 宫 / 殿 / 馆 / 院 / 楼 / 塔 / 寺 / 庙 / 坛 / 阁 / 堂 / 厅 / 站 / 厂 / 店 / 所 / 中心 / 基地 / 据点 / 墓 / 桥 / 设施 → 设施X山 / 江 / 河 / 湖 / 谷 / 林 / 原 / 海 / 滩 / 崖 → 地点
上层区域字段
- 格式：
'[[父节点名]]'（带引号）或裸名 父节点名。
- 必须指向直接上级，不能跨级。例如月兔之城的上级是
[[月球]]（行星），而不是 [[乐园星系]]（恒星系）。
- 填
无 或不填表示顶层节点。
地点类型字段
地点类型 是地点的第二维度，用于行星地图上区分设施种类（8 种颜色 + 图标）。仅在 层级 为 设施 / 地点 / 区域 时填写；城市/城镇/村庄不填。
| frontmatter 值 | 含义 | 地图图标 | 示例 |
|---|
宗教 | 神殿、祭坛、神社、大社、供奉处 | 🛕 紫 | 泽代神殿、万宁祭坛、风神大社 |
皇室 | 宫殿、府邸、城堡 | 🏯 金 | 绒花宫、星绮君宫、镇江堡 |
商业 | 商店、超市、餐厅、咖啡厅、食堂、烘焙 | 🏪 橙 | 柴旺超市、柳月道具店、狐狐食堂 |
工业 | 工厂、军械库 | 🏭 灰 | 阿希德米亚、蓝箭台 |
居住 | 住所、庇护所、小屋 | 🏠 青 | 哈伦的住所、米尔庇护所、露汐的家 |
公共 | 学校、医院、图书馆、广场、监狱、广播站、空间站、防空洞 | 🏛 蓝 | 智能体学校、绒花图书馆、算经堂 |
特殊 | 封印地、遗迹、飞船、传送门、中立区 | ✦ 粉 | 双剑封印处、纷花号、边境传送门 |
自然 | 山、湖、江、谷、林、原 | ⛰ 绿 | 意识之湖、望凤山、静默山谷 |
判定优先级（显式填写可覆盖一切推断）
名称关键词 > 标签（tags） > 兜底「公共」。脚本内另有 15 条人工修正（如 雨神宫→宗教、智能体学校→公共），但显式填写永远优先。
容易填错的边界案例
- 名字或标签带「地下室 / 庇护所」的学校、图书馆、防空洞 → 应填
公共（不要被标签误导填居住/特殊）。
- 带「宫殿」标签但实为神祇居所的 雨神宫 → 应填
宗教。
- 岛屿（庆云岛）→ 应填
自然。
- 封印地（双剑封印处 / 眠洁剑封印地）→ 应填
特殊。
常见错误与修正
| 错误 | 后果 | 修正 |
|---|
层级写英文（facility） | 旧版本不识别 | 改为中文 设施 |
层级写错（如宫殿写成 城市） | 地图显示为城市聚落样式 | 按上表修正 |
| 上层区域指向跨级父节点 | 节点挂在错误层级 | 改为直接上级 |
| 地点类型填未知值 | 回落为图层默认样式 | 只用上表 8 个值 |
| 忘记填层级/地点类型 | 脚本按文件名/标签推断，可能不准确 | 显式填写 |
与司天的关系
- 修改 frontmatter 后，需重新提取（司天「重新提取数据」或
node scripts/extract-data.js），地图才会更新。
- 司天中创建的节点（如「新恒星」「新行星」）不会写回 Markdown，仅存在于缓存层；重新提取后这类节点会消失（属预期行为）。
- 手动拖拽的坐标、绘制的地形/区域/路线等编辑器数据都存于
.sitian/ 缓存，不要手动编辑这些 JSON。
- 笔记文件名中的括号（如
时间钟楼（建筑））是文件系统层面的消歧义寻址信息，见 同名与歧义处理规则。司天后续版本支持「显示名」后，可在司天内为这类节点设置不含括号的显示名称。