giteahh/llm_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 0-2: Schema cleanup, typed relations, event-driven automation

Browse Source 
- 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
This commit is contained in:
hehaiguang1123
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/地点Wiki文件生成规范.md
+514
View File
@@ -0,0 +1,514 @@
---
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
- 《大国大民》第十一章-阴阳巴蜀