# Wiki 页面格式

> **所有 frontmatter 结构由 `schema.py` 中的 Pydantic 模型定义和校验。**
> 本文档是人类可读的规范说明，`schema.py` 是机器可执行的校验工具。两者必须一致。
> 校验命令：`python references/schema.py .wiki/{主题}/`

## 目录结构

每个研究主题一个目录：

```
{主题名}/
├── meta.yaml         # Wiki 元数据（见 storage-spec.md）
├── index.md          # 页面目录（Agent 维护，按类型分组）
├── log.md            # 操作日志（append-only，人类可读）
├── sources/          # 源文件摘要
├── entities/         # 实体页（机构、人物、产品）
├── concepts/         # 概念页（制度、方法、指标）
└── analyses/         # 分析归档（query 产出的有价值分析）
```

cognitive 类型 wiki 的目录变体：
```
{人物名}/
├── mental-models/    # 替代 entities/——每个心智模型一个页面
├── concepts/         # 启发式、价值观、表达风格、矛盾
├── sources/          # 采集来源
└── analyses/         # 分析归档
```

## 页面格式

每个页面分为两部分：**YAML frontmatter（结构化数据）** + **Markdown 正文（叙事分析）**。

**核心原则：数据放 YAML，分析放正文。** 正文不写数据表格。

---

## Frontmatter Schema

### 基础字段（所有页面必填）

```yaml
---
title: 页面标题
type: entity                    # entity | concept | source | analysis | mental-model
created: 2026-04-06
updated: 2026-04-06
sources: [source-slug-1, source-slug-2]
confidence: high                # high | medium | low | contested
tags: [entity]                  # 必填：页面类型 + 可选状态标签
aliases: []                     # 可选：页面别名
---
```

| 字段 | 必填 | 说明 |
|------|------|------|
| title | 是 | 页面标题 |
| type | 是 | 页面类型 |
| created | 是 | 创建日期 YYYY-MM-DD |
| updated | 是 | 最后更新日期（每次修改必须更新） |
| sources | 是 | 引用的 source 页面 slug 列表（source 类型页面填 `[]`） |
| confidence | 是 | 置信度：`high` / `medium` / `low` / `contested` |
| tags | 是 | Obsidian 标签列表，用于搜索过滤和分类浏览 |
| aliases | 否 | 页面别名列表，用于 Obsidian 搜索和链接补全 |

### tags 规则（Obsidian 搜索过滤必需）

`tags` 必须包含页面类型（`source` / `entity` / `concept` / `analysis` / `mental-model`），可追加状态标签：

```yaml
tags:
  - concept                    # 必填：页面类型
  - contested                  # 可选：confidence=contested 时加
  - low-confidence             # 可选：confidence=low 时加
```

source 类型页面额外加来源等级标签：

```yaml
tags:
  - source
  - primary-source             # 一手来源
  # 或 authoritative-secondary / secondary / hearsay / inference
```

这些标签用于 Obsidian 搜索过滤（如在搜索栏输入 `tag:#contested` 快速定位有争议的页面）。图谱着色不依赖 tags——靠 `path:` 规则区分页面类型，靠 `[confidence:contested]` Properties 查询高亮风险节点。

### aliases 规则

标题含括号说明时，拆出短名和括号内容作为别名：

```yaml
title: EET 税收模式（个人养老金税优机制）
aliases:
  - EET 税收模式
  - 个人养老金税优机制
```

### 结构化数据 → data.db

**所有可量化、可查证、可对比的数据写入 `data.db`（SQLite），不放在 frontmatter 中。**

Agent 在 ingest 时调用 `store.py` 的 `WikiStore` 接口：

```python
store.upsert_data("alpha-corp", "管理规模", 1350, "亿元", "2025-Q1", "2026-04-policy-doc", scope="含职业年金")
store.upsert_data("alpha-corp", "市场份额", 12, "%", "2025-Q1", "2026-04-policy-doc", confidence="contested")
```

如果同字段同时段已有旧值，`upsert_data` 自动将旧值写入 `history` 表并返回旧记录。

**数据字段规范**（由 `store.py: data_points` 表约束）：

| 字段 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `page_slug` | **是** | TEXT | 所属页面的 slug |
| `field` | **是** | TEXT | 数据维度名（如"管理规模"） |
| `value` | **是** | REAL | 数值 |
| `unit` | **是** | TEXT | 单位（亿元、%、万人、家...） |
| `period` | **是** | TEXT | 数据时点（如 "2023-12"、"2025-Q1"） |
| `source_slug` | **是** | TEXT | source 页面 slug |
| `scope` | 否 | TEXT | 统计口径说明 |
| `verified` | 否 | INTEGER | NULL=未知, 0=未验证, 1=已验证 |
| `confidence` | 否 | TEXT | 该数据点的置信度 |

**每个数字都必须有出处。** `source_slug` 指向哪个 source 页面。

**查询示例**：

```python
# 某机构的所有数据
store.query_data(page_slug="alpha-corp")

# 某字段的时间线（含历史值）
store.query_timeline(field="管理规模")

# 所有 contested 数据
store.conn.execute("SELECT * FROM data_points WHERE confidence='contested'").fetchall()
```

### relations 字段（结构化关系）

页面间的语义关系，补充正文中的 `[[wikilink]]`：

```yaml
relations:
  - target: beta-corp
    type: competes_with
  - target: 受托人市场格局
    type: part_of
  - target: national-council-ssf
    type: regulated_by
```

**常用关系类型**：

| type | 含义 | 示例 |
|------|------|------|
| `part_of` | 属于 | 某机构 part_of 受托人市场 |
| `manages` | 管理 | 受托人 manages 年金基金 |
| `regulated_by` | 受监管 | 机构 regulated_by 人社部 |
| `competes_with` | 竞争 | 机构A competes_with 机构B |
| `implements` | 实施 | 机构 implements 受托责任 |
| `derived_from` | 来源于 | 概念 B derived_from 概念 A |
| `contradicts` | 矛盾 | 数据 A contradicts 数据 B |
| `influenced_by` | 受影响（cognitive 类型） | 心智模型 influenced_by 人物 |
| `applies_to` | 适用于 | 心智模型 applies_to 领域 |

**relations 规范**：
- `target` 填 slug（不加路径前缀）
- `type` 从上表选取，或自定义（但保持项目内一致）
- relations 是 frontmatter 中的结构化声明，正文中的 `[[wikilink]]` 是人类可读的引用——两者互补

### source 类型页面的额外字段

```yaml
---
title: 人社部2024年度企业年金基金统计报告
type: source
created: 2026-04-06
updated: 2026-04-06
sources: []
confidence: high
source_type: 一手               # 一手 | 二手·权威 | 二手 | 转述 | 推断 | 口述
source_origin: 人社部官网
source_date: 2024-12-31         # 原始材料的日期（不是 ingest 日期）
source_url: ""                  # 来源 URL（如有）
---
```

### cognitive 类型（心智模型页）的额外字段

```yaml
---
title: 能力圈
type: mental-model
created: 2026-04-06
updated: 2026-04-06
sources: [poor-charlies-almanack]
confidence: high
verification:
  cross_domain: true            # 跨域复现
  generative: true              # 有生成力
  exclusive: true               # 有排他性
  domains: [投资, 商业决策, 人生选择]  # 出现过的领域
---
```

---

## 正文约定

**正文只写叙事分析和上下文解读，不写数据表格。**

以下为示例（以金融领域为例）：

```markdown
# 某机构业务概况

该机构是行业规模最大的参与者之一。2025年Q1管理规模增至 XXX 亿元，
但市场份额数据因统计口径变更与上期报告不可直接比较。

[[competitor-a|竞争对手 A]]同期增速行业第一，正在缩小差距。
详见 [[市场格局]]。
```

**正文规则**：
- 用 `[[slug]]` 或 `[[slug|显示名]]` 做页面链接
- 提到数据时引述结论，不重复 frontmatter 中的具体数值（避免不一致）
- 可以用 `> ⚠️` blockquote 标注重要警告（如口径差异）
- 分析性内容是正文的核心价值——这是 YAML 无法承载的部分

---

## 文件命名

- slug 格式：小写字母 + 连字符，如 `alpha-corp.md`
- 中文概念用中文 slug：`受托人市场格局.md`（Obsidian 友好）或拼音 slug
- source 页面加日期前缀：`2026-04-06-hrss-report.md`（连字符分隔）

## index.md 格式

index 只做导航，不内联数据：

```markdown
# {主题名} Wiki Index

> {N} pages | Last updated: {日期} | Type: {ontology_type}

## Entities ({N})
- [[alpha-corp]] — 机构 A 养老金业务
- [[beta-corp]] — 机构 B 养老保险

## Concepts ({N})
- [[受托人市场格局]] — 受托人竞争格局与份额
- [[企业年金制度]] — 政策法规与制度框架

## Sources ({N})
- [[2026-04-06-hrss-report]] — 人社部2024年度报告
- [[2026-04-06-q1-briefing]] — 2025年一季度市场简报

## Analyses ({N})
- [[trustee-comparison]] — 受托人市场格局对比分析
```

**index 规则**：每个条目一行，`[[slug]] — 一句话描述`。不放表格、不放统计数据。

## log.md 格式

```markdown
# {主题名} Wiki Log

## 2026-04-06 14:30 — ingest
- Source: 2026-04-06-hrss-report
- Created: entities/alpha-corp, concepts/受托人市场格局
- Updated: (无)
- Conflicts: (无)

## 2026-04-06 15:00 — ingest
- Source: 2026-04-06-q1-briefing
- Updated: entities/alpha-corp (管理规模 1200→1350亿，份额 contested)
- Created: entities/beta-corp
- Conflicts: alpha-corp.市场份额 (15% vs 12%，口径不同)
```

## Validation Rules

| 规则 | 要求 |
|------|------|
| frontmatter 完整 | `title`, `type`, `created`, `updated`, `sources`, `confidence` 六字段必须存在 |
| type 值合法 | `source` / `entity` / `concept` / `analysis` / `mental-model` |
| data 字段规范 | 每个数据点必须有 `value`, `unit`, `period`, `source` |
| history 有 reason | 每条历史记录必须有 `reason` 字段 |
| relations 有 type | 每条关系必须有 `target` 和 `type` |
| sources 非空 | 除 source 类型外，`sources` 列表至少一个 slug |
| 日期格式 | `YYYY-MM-DD` |
| slug 与文件名一致 | 文件名（去 `.md`）= slug |

## 置信度更新规则

| 事件 | 置信度变化 |
|------|-----------|
| 新 source 印证已有数据（data 字段一致） | → `high` |
| 新 source 更新已有数据（有更新时点/更权威来源） | 更新 data，旧值进 history |
| 新 source 与已有数据矛盾且无法判断 | data 中该字段 confidence → `contested` |
| lint 发现 data 中有无 source 的字段 | → `low` |
| 页面 6 个月未被 ingest 触及 | lint 建议标注"待验证" |