---
id: SCHEMA-001
type: schema
title: 文獻 Wiki 維護規則
updated: 2026-10-03
status: template
---

# 文獻 Wiki 維護規則

這份檔案寫給 AI 代理（Claude Code、Codex 或其他能讀寫檔案的 AI）與人類維護者看。AI 每次處理這個 Wiki 前都要先讀這份檔案。

## 三層結構

| 層 | 位置 | 誰能改 | 用途 |
|---|---|---|---|
| 原始層 | `raw/`：清理後的全文（例如 KMDB 的 `cleaned_*.md`）與知識萃取檔 | 任何人都不改 | 逐頁保留「### PDF 第 N 頁」；正式引用仍回原始 PDF |
| Wiki 層 | `sources/`、`concepts/`、`maps/`、`queries/`、`index.md`、`log.md` | AI 起草、人工確認 | 書目頁、概念頁、主題地圖、問答歸檔 |
| 規則層 | 本檔 `AGENTS.md` | 只由研究者本人修改，AI 不改 | 規定頁面格式、連線類型與維護流程 |

## 頁面類型

| 類型 | 資料夾 | ID 前綴 | 一頁放什麼 |
|---|---|---|---|
| 書目頁 | `sources/` | `SRC-` | 一本書或一篇文獻的書目、定位摘要、可引用頁碼與原始檔位置 |
| 概念頁 | `concepts/` | `CON-` | 一個概念。定義、各來源怎麼說、彼此的關係、適用邊界 |
| 主題地圖 | `maps/` | `MAP-` | 一個主題下的概念頁與書目頁連結，按研究流程排列 |
| 問答歸檔 | `queries/` | `QA-` | 一次有價值的提問與附來源的回答，之後可被其他頁引用 |

檔名一律使用英文小寫與連字號（例如 `abductive-analysis.md`），中文名稱放在 `title` 與 `aliases`。

## 一個頁面的四個名字

| 名字 | 例子 | 用途 |
|---|---|---|
| ID | `CON-001` | Wiki 內部的固定編號，引用時用，例如（SRC-TT-ABD p.4） |
| 檔名 | `abductive-analysis.md` | 電腦裡真正的檔案名稱；`[[連結]]` 與 `relations` 的 `target` 都填檔名（不含 .md） |
| title | `溯因分析` | 人看到的正式名稱 |
| aliases | `溯因推理`、`abduction` | 其他叫法；新建頁面前先用別名查，避免同一概念建成兩頁 |

`[[abductive-analysis|溯因分析]]` 的前半段是要連到的檔名，後半段是畫面上顯示的文字。寫在 Markdown 表格裡時，中間的 `|` 要寫成 `\|`。

## 原始層的放法

每本書在 `raw/` 底下一個資料夾，資料夾名稱就是 KMDB 的書名代號，裡面放兩個檔案：

```
raw/
└── data-analysis-to-theory-breakthrough/
    ├── cleaned_data-analysis-to-theory-breakthrough.md
    └── knowledge_extraction_data-analysis-to-theory-breakthrough.md
```

`_handoff.md` 是處理紀錄，不必放。

## 每頁的 frontmatter

```yaml
id: CON-007
type: concept            # source | concept | map | query
title: 溯因分析
summary: 一句話摘要，會被自動收進 index.md
aliases: [溯因推理, abductive analysis, abduction]
sources: [SRC-TT-ABD]    # 本頁引用到的書目 ID
relations:               # 有型別的連線；target 填檔名（不含 .md）
  - type: 引用
    target: timmermans-tavory-abductive-analysis
    basis: 引用
  - type: 概念相近
    target: anomaly-crisis-incommensurability
    basis: 研究者推論
status: draft            # 所有頁面一律先填 draft；回原文核對過才改成 reviewed
updated: 2026-10-03      # 最後修改日期
```

在 Obsidian 裡，這段 frontmatter 會顯示成「Properties」面板，兩者是同一批資料。`relations` 這種多層的欄位在 Properties 面板裡無法正常編輯，請切到原始碼模式（Source mode）修改。`relations` 寫的是「是什麼關係」，Obsidian 的關係圖看不到；所以每一條 `relations`，內文也要有一個對應的 `[[連結]]`。

## 連線類型（五種，不得自行新增）

| 類型 | 意思 | 例子 |
|---|---|---|
| 引用 | 本頁內容直接出自該來源的特定頁碼 | 溯因分析 → SRC-TT-ABD p.14–16 |
| 概念相近 | 兩個概念指向相近現象，但出自不同脈絡 | 溯因分析的「意外發現」與孔恩的「反常」 |
| 方法延伸 | 一個方法是另一個方法的下一步或操作化 | 開放編碼 → 聚焦編碼 → 軟體轉譯 |
| 立場衝突 | 兩個來源對同一問題的主張不同 | Gillham「證據優先」與 Yin「理論命題先行」 |
| 研究者推論 | 原書沒有這樣說，是我們把兩者連起來 | 必須在 `basis` 寫明「研究者推論」 |

## 每一句主張都要能回到原書

內文沿用 KMDB 既有的三層證據標記：

- `原文依據`：書中直接陳述，後面附 `（SRC-ID p.頁碼）`
- `根據原文推論`：由多段內容組合的判讀
- `延伸應用`：用到管理或研究情境的跨情境運用，不視為原書主張

頁碼一律使用 PDF 頁碼，與原始層的錨點一致。

## 三種操作

### 1. 匯入（ingest）

1. 讀 `raw/` 裡的清理檔與知識萃取檔（KMDB 的 `knowledge_extraction_*.md`）。
2. 建立或更新一張書目頁。
3. 對書中的每個核心概念：先在 `index.md` 和各頁 `aliases` 搜尋是否已有概念頁。有就補一節「〈這本書〉怎麼說」，沒有才新建。
4. 新增或修改連線時填寫 `type` 與 `basis`。
5. 更新 `index.md`，在 `log.md` 尾端追加一筆紀錄。

一本書通常會動到 5–15 頁。新建概念頁之前一定先查別名，避免「常規科學」與「常態科學」變成兩頁。

### 2. 查詢（query）

1. 先讀 `index.md`，挑出相關頁面。
2. 讀概念頁；需要引用時回到原始層對應頁碼核對原文。
3. 回答時每個論點附 `（SRC-ID p.N）`。
4. 值得保留的回答存成 `queries/` 新頁（`type: query`、ID 前綴 `QA-`），並在 `log.md` 記錄。
5. 存檔後重新執行 `python tools/build_index.py` 與 `python tools/wiki_lint.py`；索引不會自動更新。

### 3. 健康檢查（lint）

執行 `tools/wiki_lint.py`，至少檢查：

- frontmatter 必填欄位是否齊全
- 每個概念頁是否至少有一筆附頁碼的引用
- `[[連結]]` 是否指向存在的頁面
- 是否有沒有任何頁面連入的孤兒頁
- `index.md` 是否列出全部頁面
- 是否有別名重複，也就是同一概念被建成兩頁
- 頁面是否超過長度上限

## 長度上限

- 概念頁 120 行以內；超過就拆成兩個概念，或把細節移到書目頁。
- `index.md` 每頁一行；超過 200 行時改依類型拆成 `index-sources.md`、`index-concepts.md`。
- 一次查詢只讀 `index.md` 加 3–5 頁，讀不夠再擴大。

## 不可以做的事

- 不改原始層任何檔案。
- 不寫沒有頁碼的主張；查不到頁碼就標「待回查」。
- 所有頁面（人寫的和 AI 起草的）一律先填 `status: draft`，人工回原文核對後才改成 `reviewed`。
- 執行任何 Python 指令前，先確認這台電腦能執行 Python；不能執行就停下來回報，不要用其他方式繞過。
- 不把書籍全文或大段原文複製進 Wiki；引用原文以一兩句為限。