hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
515 lines
17 KiB
Markdown
515 lines
17 KiB
Markdown
---
|
||
categories:
|
||
- "[[LLM Wiki]]"
|
||
tags:
|
||
- wiki
|
||
- concept
|
||
- workflow
|
||
- location
|
||
created: 2026-04-11
|
||
source: "[[《大国大民》王志纲/《大国大民》第三章-发现山西.md]]"
|
||
type: concept
|
||
aliases:
|
||
- 地点笔记流程
|
||
- Location Wiki Workflow
|
||
---
|
||
|
||
# 地点 Wiki 文件生成规范
|
||
|
||
> 基于《大国大民》系列地点笔记的实践经验，定义地点类 Wiki 文件的生成规则、数据流关系和模板体系。
|
||
|
||
---
|
||
|
||
## 一、体系架构：Place 文件 × Base 视图
|
||
|
||
### 1.1 三层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Place Type 笔记 (References/) │
|
||
│ 定义 type 的 icon 和 color │
|
||
│ 如：Landmark.md → icon: 📍, color: "#3498db" │
|
||
│ 标签：tags: places/types │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
│ type 字段引用（wikilink）
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Place 笔记 (wiki/*.md) │
|
||
│ 双重身份：LLM Wiki 知识页 + Places 地图数据 │
|
||
│ categories: [[LLM Wiki]] + [[Places]] │
|
||
│ type: [[Landmark]] / [[Region]] / [[Historic site]] │
|
||
│ loc / coordinates / rating / address │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
│ embed 引用
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Base 视图 (Templates/Bases/) │
|
||
│ Places.base → 表格 + 地图（直接取 note.icon） │
|
||
│ Map.base → 全局地图（formula 从 Type 继承 icon） │
|
||
│ Trips.base → 旅行关联 │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 数据流详解
|
||
|
||
#### Place 文件 → Places.base
|
||
|
||
| 文件字段 | Base 引用方式 | 用途 |
|
||
|----------|--------------|------|
|
||
| `categories` 含 `[[Places]]` | `filters: categories.contains(link("Places"))` | 筛选入口 |
|
||
| `type` | `properties: note.type` | 表格列、Type 视图筛选 |
|
||
| `loc` | `properties: note.loc` | Location 视图：`list(loc).contains(this)` |
|
||
| `coordinates` | `coordinates: note.coordinates` | 地图定位 |
|
||
| `icon` | `markerIcon: note.icon` | 地图标记图标（**直接取值**） |
|
||
| `color` | `markerColor: note.color` | 地图标记颜色（**直接取值**） |
|
||
| `rating` | `properties: note.rating` | 排序 |
|
||
| `last` | `properties: note.last` | 排序（最近更新） |
|
||
|
||
#### Place 文件 → Map.base
|
||
|
||
| 文件字段 | Base 引用方式 | 用途 |
|
||
|----------|--------------|------|
|
||
| `categories` 含 `[[Places]]` | `filters` | 筛选入口 |
|
||
| `type`（wikilink） | `formula.Icon = list(type)[0].asFile().properties.icon` | **从 Place Type 继承 icon** |
|
||
| `type`（wikilink） | `formula.Color = list(type)[0].asFile().properties.color` | **从 Place Type 继承 color** |
|
||
| `coordinates` | `coordinates: note.coordinates` | 地图定位 |
|
||
| `loc` | Location 视图：`list(loc).contains(this)` | 按地区筛选 |
|
||
| `last` | `sort` | 排序 |
|
||
|
||
#### Place 文件 → Trips.base
|
||
|
||
| 文件字段 | Base 引用方式 | 用途 |
|
||
|----------|--------------|------|
|
||
| `loc` | `filters: list(loc).contains(this)` | 按地区筛选旅行 |
|
||
|
||
#### Trips 笔记 → Trips.base
|
||
|
||
| 文件字段 | Base 引用方式 | 用途 |
|
||
|----------|--------------|------|
|
||
| `categories` 含 `[[Trips]]` | `filters` | 筛选入口 |
|
||
| `start` / `end` | `properties` | 旅行时间 |
|
||
| `loc` | `properties` | 旅行关联地点 |
|
||
|
||
### 1.3 两套 icon/color 取值机制
|
||
|
||
| 视图 | 取值方式 | 对 Place 文件的要求 |
|
||
|------|----------|---------------------|
|
||
| **Places.base** | `note.icon` / `note.color` 直接取 | 每条笔记自身有 icon 和 color 字段 |
|
||
| **Map.base** | `formula.Icon` / `formula.Color` 从 Place Type 继承 | `type` 必须是 **wikilink**，指向 References/ 下的 Place Type 笔记 |
|
||
|
||
**⚠️ 兼容策略**：Place 文件应**同时**包含自身 icon/color 字段（供 Places.base）和使用 wikilink 的 type 字段（供 Map.base formula）。
|
||
|
||
### 1.4 Place Type 笔记
|
||
|
||
| 文件 | icon | color | 适用范围 |
|
||
|------|------|-------|----------|
|
||
| `References/Landmark.md` | 📍 | `#3498db` | 具体景点、地标 |
|
||
| `References/Region.md` | 🗺️ | `#2ecc71` | 城市、省份、行政区域 |
|
||
| `References/Historic site.md` | 🏛️ | `#e67e22` | 历史遗迹、古城 |
|
||
|
||
Place Type 笔记格式（参考 `References/Parks.md`）：
|
||
|
||
```yaml
|
||
---
|
||
tags:
|
||
- places/types
|
||
icon: {emoji}
|
||
color: "{hex}"
|
||
---
|
||
|
||
## Places
|
||
|
||
![[Map.base#Type]]
|
||
![[Places.base#Type]]
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Frontmatter 规范
|
||
|
||
### 2.1 完整字段模板
|
||
|
||
```yaml
|
||
---
|
||
categories:
|
||
- "[[LLM Wiki]]" # LLM Wiki 知识库身份
|
||
- "[[Places]]" # Places 地图体系身份
|
||
tags:
|
||
- wiki
|
||
- places
|
||
- {type-tag} # landmark | region | historic-site
|
||
- china
|
||
created: YYYY-MM-DD
|
||
last: YYYY-MM-DD # 最近更新日期，用于排序
|
||
source: "[[来源路径]]" # ⚠️ 单行字符串，不是列表
|
||
type: place
|
||
- "Landmark" # ⚠️ wikilink 指向 Place Type 笔记loc:
|
||
- "[[上级地区]]" # wikilink，如 "[[山西]]"
|
||
coordinates:
|
||
- "{纬度}" # 字符串格式
|
||
- "{经度}" # 字符串格式
|
||
rating: 5 # 1-7 整数
|
||
address: 完整中文地址
|
||
icon: 📍 # emoji，与 Place Type 的 icon 一致
|
||
color: "#3498db" # hex 颜色，与 Place Type 的 color 一致
|
||
---
|
||
```
|
||
|
||
### 2.2 type 字段映射
|
||
|
||
| type 值 | 对应 Place Type | tags 中的 type-tag | 说明 |
|
||
|---------|----------------|-------------------|------|
|
||
| `"Landmark"` | `References/Landmark.md` | `landmark` | 具体景点、地标 |
|
||
| `"Region"` | `References/Region.md` | `region` | 城市、省份 |
|
||
| `"Historic site"` | `References/Historic site.md` | `historic-site` | 历史遗迹 |
|
||
|
||
### 2.3 关键格式规则（2026-04-13 修正）
|
||
|
||
> ⚠️ 经过实际测试，以下是正确的格式：
|
||
|
||
| 规则 | ✅ 正确 | ❌ 错误 |
|
||
|------|---------|---------|
|
||
| **type 格式** | `type:\n - "Landmark"` | `type: - "[[Landmark]]"` |
|
||
| **type 值** | 用引号：`"Landmark"` | 不用引号：`Landmark` |
|
||
| **type 不能用 wikilink** | `"Landmark"` | `[[Landmark]]` |
|
||
| **loc 格式** | `loc:\n - "[[山西]]"` | `loc: 山西` |
|
||
| **loc 必须 wikilink** | `[[山西]]` | `山西` |
|
||
| **source 格式** | `source: "[[路径]]"` | `source:\n - "[[路径]]"` |
|
||
| **coordinates** | 字符串列表，每行一个 | 数字类型 |
|
||
| **color** | 引号包裹 `"#3498db"` | 裸值 `#3498db` |
|
||
| **布尔值** | `marp: "true"` | `marp: true` |
|
||
|
||
### 2.4 source 字段规范（重点）
|
||
|
||
source 必须**单行字符串**格式：
|
||
|
||
```yaml
|
||
# ✅ 正确
|
||
source: "[[《大国大民》王志纲/《大国大民》第十一章-阴阳巴蜀]]"
|
||
|
||
# ❌ 错误 - 不要用列表
|
||
source:
|
||
- "[[《大国大民》王志纲/《大国大民》第十一章-阴阳巴蜀]]"
|
||
```
|
||
|
||
---
|
||
|
||
## 三、内容结构规范
|
||
|
||
### 3.1 标准章节模板（景点型 — Landmark）
|
||
|
||
```markdown
|
||
# {地点名}
|
||
|
||
> **一句话定义**：{15字以内概括}
|
||
|
||
## 简介
|
||
{客观描述，50-100字}
|
||
|
||
## 历史背景
|
||
{从原始来源中提取的相关内容，引用原文关键段落}
|
||
|
||
## {特色章节}（可选，按需命名）
|
||
## 文化价值 / 建筑特色 / 文明意义 等
|
||
|
||
## 地理位置与交通
|
||
{简要交通信息}
|
||
|
||
## 游览建议
|
||
{编号列表，3-5条}
|
||
|
||
## 关联内容
|
||
- 相关地点
|
||
|
||
## 参考资料
|
||
- raw/来源路径
|
||
|
||
## Trips
|
||
![[Templates/Bases/Trips.base#Location]]
|
||
|
||
## Places
|
||
![[Templates/Bases/Map.base#Location]]
|
||
![[Templates/Bases/Places.base#Location]]
|
||
```
|
||
|
||
### 3.2 标准章节模板（区域型 — Region）
|
||
|
||
```markdown
|
||
# {区域名}
|
||
|
||
> **一句话定义**：{15字以内概括}
|
||
|
||
## 简介
|
||
{客观描述}
|
||
|
||
## 地理特征
|
||
{分区描述，如陕西三副面孔}
|
||
|
||
## 历史贡献
|
||
{表格 + 叙述}
|
||
|
||
## 核心概念
|
||
{该区域对文明的贡献}
|
||
|
||
## 关联内容
|
||
|
||
### 地点
|
||
- 下属地点1
|
||
- 下属地点2
|
||
|
||
### 人物
|
||
- 相关人物
|
||
|
||
### 概念
|
||
- 相关概念
|
||
|
||
## 参考资料
|
||
- raw/来源路径
|
||
|
||
## Trips
|
||
![[Templates/Bases/Trips.base#Location]]
|
||
|
||
## Places
|
||
![[Templates/Bases/Map.base#Location]]
|
||
![[Templates/Bases/Places.base#Location]]
|
||
```
|
||
|
||
### 3.3 引用规则
|
||
|
||
- **优先引用原文**：将原始来源中与该地点直接相关的段落以 `>` blockquote 形式引用
|
||
- **标注出处**：使用"王志纲在《发现山西》中指出"等前缀
|
||
- **适度改写**：非直接引用部分用自己语言概括，但保持核心观点不变
|
||
- **不做主观评价**：除原始来源中已有的评价外，不添加个人观点
|
||
|
||
### 3.4 底部 embed（所有地点文件必须有）
|
||
|
||
```markdown
|
||
## Trips
|
||
|
||
![[Templates/Bases/Trips.base#Location]]
|
||
|
||
## Places
|
||
|
||
![[Templates/Bases/Map.base#Location]]
|
||
|
||
![[Templates/Bases/Places.base#Location]]
|
||
```
|
||
|
||
这三个 embed 使地点文件自动出现在：
|
||
|
||
- **Trips.base 的 Location 视图**：当旅行笔记的 loc 包含本地点时显示
|
||
- **Map.base 的 Location 视图**：以本地点为中心的地图
|
||
- **Places.base 的 Location 视图**：同地区的地点列表
|
||
|
||
---
|
||
|
||
## 四、模板体系
|
||
|
||
### 4.1 可用模板
|
||
|
||
| 模板文件 | 适用场景 | type 默认值 |
|
||
|----------|----------|------------|
|
||
| `Templates/Place Template.md` | 景点、地标 | `[[Landmark]]` |
|
||
| `Templates/City Template.md` | 城市、省份 | `[[Region]]` |
|
||
|
||
### 4.2 Place Type 模板
|
||
|
||
`Templates/Place Type Template.md` — 创建新的地点类型时使用（如"寺庙""博物馆"等）。
|
||
|
||
### 4.3 使用流程
|
||
|
||
1. 在 Obsidian 中新建笔记
|
||
2. 选择模板：景点 → Place Template，城市 → City Template
|
||
3. 填写 frontmatter（source、type wikilink、loc、coordinates 等）
|
||
4. 编写内容
|
||
5. 确认底部 embed 存在
|
||
|
||
---
|
||
|
||
## 五、坐标获取规范
|
||
|
||
### 5.1 必须使用真实坐标
|
||
|
||
**禁止使用占位坐标**。每个地点必须通过腾讯位置服务 API 获取真实经纬度。
|
||
|
||
**API 凭证**：
|
||
- Key: `ZXMBZ-GTICB-2FUUC-JCOM6-NZ4YV-ZOFKP`
|
||
- SK: `Nu5fywkMyVQxLMgLWk6zUJSHie7FvfjJ`
|
||
|
||
### 5.2 签名算法
|
||
|
||
```
|
||
sig = MD5(request_path + "?" + sorted_raw_params + SK)
|
||
```
|
||
|
||
关键要点：
|
||
|
||
- `request_path` = 路径部分（如 `/ws/geocoder/v1`），**不是完整 URL**
|
||
- 参数按 key 字母排序
|
||
- 签名计算用**原始未编码**的参数值
|
||
- 实际 HTTP 请求中参数需要 URL 编码
|
||
- **使用 Python** 调用，PowerShell 在 Windows 上有 GBK 编码问题
|
||
|
||
### 5.3 Python 脚本位置
|
||
|
||
复用脚本：`.sisyphus/get-coordinates.py`（已验证可用）
|
||
|
||
### 5.4 离线参考
|
||
|
||
- Kiwix 离线 Wikipedia：`https://kiwix.haiguang.xyz:14004`
|
||
- 可用于核实地点的准确坐标和地址
|
||
|
||
---
|
||
|
||
## 六、文件命名规范
|
||
|
||
| 类型 | 格式 | 示例 |
|
||
|------|------|------|
|
||
| 具体景点 | `{景点全名}.md` | `云冈石窟.md`、`壶口瀑布.md` |
|
||
| 城市 | `{城市名}.md` 或 `{城市名}城.md` | `成都.md`、`太原城.md` |
|
||
| 省份/区域 | `{区域名}.md` | `山西省.md` |
|
||
| 特殊景点 | `{景点全名}.md` | `洪洞大槐树.md` |
|
||
|
||
---
|
||
|
||
## 七、工作流程
|
||
|
||
### 7.1 标准流程
|
||
|
||
```
|
||
1. 读取原始来源 → 提取地点列表
|
||
2. 为每个地点确定 type（Landmark / Region / Historic site）
|
||
3. 调用腾讯地图 API → 获取真实坐标
|
||
4. 选择对应模板（Place / City）创建地点文件
|
||
5. 确认 frontmatter 完整性（categories、type wikilink、loc、coordinates、icon、color）
|
||
6. 确认底部 embed 存在（Trips + Map + Places）
|
||
7. 创建关联实体文件（人物、书籍等）
|
||
8. 更新 wiki/index.md
|
||
9. 更新 wiki/log.md
|
||
10. 验证：文件存在 + frontmatter 格式 + 坐标正确 + Base 视图可查
|
||
```
|
||
|
||
### 7.2 验证清单
|
||
|
||
每个地点文件完成后必须检查：
|
||
|
||
- [ ] 文件实际存在于磁盘（`read` 目录列表确认）
|
||
- [ ] `categories` 同时包含 `[[LLM Wiki]]` 和 `[[Places]]`
|
||
- [ ] `type` 是 wikilink 格式，指向 `References/` 下的 Place Type
|
||
- [ ] `loc` 是 wikilink 格式，指向正确的上级地区
|
||
- [ ] `source` 是单行字符串格式
|
||
- [ ] `coordinates` 是两个字符串值（纬度在前、经度在后）
|
||
- [ ] `icon` 和 `color` 与对应的 Place Type 一致
|
||
- [ ] `color` 值用引号包裹
|
||
- [ ] 引用的原文段落准确无误
|
||
- [ ] 底部 embed 正确（Trips.base + Map.base + Places.base）
|
||
|
||
---
|
||
|
||
## 八、常见陷阱
|
||
|
||
### 8.1 type 格式（2026-04-13 修正）
|
||
|
||
> ⚠️ 经过实际测试验证，**type 值必须是带引号的纯文本，不能使用 wikilink**。
|
||
|
||
```yaml
|
||
# ✅ 正确格式（实测验证通过）
|
||
type: place
|
||
- "Landmark"
|
||
- "Region"
|
||
- "Historic site"
|
||
|
||
# ❌ 错误格式 - wikilink 会导致 Base 视图无法正确显示
|
||
type: place
|
||
- "[[Landmark]]"
|
||
|
||
# ❌ 错误格式 - 缺少引号
|
||
type: place
|
||
- Landmark
|
||
```
|
||
|
||
**原因**：Places.base 和 Map.base 直接读取 `note.type` 字符串值进行匹配，wikilink 格式会导致匹配失败。
|
||
|
||
### 8.2 Windows 中文文件名
|
||
|
||
在 Windows 系统上，`write` 工具报告成功但文件可能未实际持久化。**必须通过 `read` 目录列表确认文件存在**。
|
||
|
||
### 8.3 source 格式混淆
|
||
|
||
最常见错误。记住：`source` 是**单行字符串**，不是列表。参考已确认正确的文件（如 `王志纲.md`）。
|
||
|
||
### 8.4 坐标顺序
|
||
|
||
腾讯 API 返回 `lat`（纬度）和 `lng`（经度）。frontmatter 中 coordinates 的顺序是**纬度在前、经度在后**。
|
||
|
||
### 8.5 PowerShell 编码
|
||
|
||
Windows 上 PowerShell 处理中文有 GBK 编码问题。**坐标获取脚本必须用 Python**。
|
||
|
||
---
|
||
|
||
## 九、现有文件迁移计划
|
||
|
||
### 9.1 需要迁移的文件
|
||
|
||
#### 巴蜀系列（第十一章，2026-04-13 创建）
|
||
|
||
| 文件 | 当前状态 | 需要补充 |
|
||
|------|----------|----------|
|
||
| 成都.md | 缺 type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
| 重庆.md | 缺 categories:[[Places]]/type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
| 都江堰.md | 缺 categories:[[Places]]/type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
| 宽窄巷子.md | 缺 categories:[[Places]]/type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
| 钓鱼城.md | 缺 categories:[[Places]]/type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
| 鹤鸣山.md | 缺 categories:[[Places]]/type/loc/coordinates/icon/color/address/embed | 全量补充 |
|
||
|
||
#### 省份系列（需纳入 Places 体系）
|
||
|
||
| 文件 | 当前状态 | 需要补充 |
|
||
|------|----------|----------|
|
||
| 陕西省.md | 无 Places category，无坐标 | 全量补充 |
|
||
| 湖北省.md | 无 Places category，无坐标 | 全量补充 |
|
||
|
||
#### 已有 Places 格式（需更新 type 为 wikilink）
|
||
|
||
| 文件 | 当前状态 | 需要补充 |
|
||
|------|----------|----------|
|
||
| 大同古城.md | type: historic-site（纯文本） | 改为 `"[[Historic site]]"` |
|
||
| 云冈石窟.md | type: landmark（纯文本） | 改为 `"[[Landmark]]"` |
|
||
| 武汉.md | type: landmark（纯文本） | 改为 `"[[Landmark]]"` |
|
||
| 其他山西/湖北地点 | 同上 | 同上 |
|
||
|
||
### 9.2 迁移执行顺序
|
||
|
||
1. **第一批**：更新 Place Type（将现有纯文本 type 统一改为 wikilink）— 批量 ast-grep
|
||
2. **第二批**：补充巴蜀系列的完整 Places 数据 — 逐个获取坐标
|
||
3. **第三批**：省份纳入 Places 体系 — 用省会坐标
|
||
|
||
---
|
||
|
||
## 十、参考文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `wiki/大同古城.md` | **最佳参考**：Landmark 完整格式（待更新 type 为 wikilink） |
|
||
| `wiki/云冈石窟.md` | Landmark 格式参考（待更新 type） |
|
||
| `wiki/武汉.md` | 城市级 Landmark 格式参考（待更新 type） |
|
||
| `wiki/陕西省.md` | Region 格式参考（待纳入 Places 体系） |
|
||
| `References/Landmark.md` | Place Type：景点地标 |
|
||
| `References/Region.md` | Place Type：区域城市 |
|
||
| `References/Historic site.md` | Place Type：历史遗迹 |
|
||
| `Templates/Place Template.md` | 景点型模板 |
|
||
| `Templates/City Template.md` | 城市/区域型模板 |
|
||
| `Templates/Place Type Template.md` | 新建类型时使用 |
|
||
| `.sisyphus/get-coordinates.py` | 坐标获取脚本（已验证可用） |
|
||
|
||
## 来源
|
||
|
||
---
|
||
## 规范文档
|
||
|
||
详见 [[地点Wiki文件生成规范]]
|
||
|
||
- 《大国大民》王志纲/《大国大民》第三章-发现山西.md
|
||
- 《大国大民》第十一章-阴阳巴蜀
|