資料模型

TypeMD 採用雙儲存設計：Markdown 檔案是 source of truth，SQLite 資料庫提供快速索引和搜尋。本頁說明索引層的技術細節。

使用者導向的檔案結構說明，請參閱檔案結構。

檔案即 Source of Truth

最根本的設計原則是檔案永遠是 source of truth。SQLite 索引是加速層，隨時可以從檔案重建。如果索引被刪除或損壞，不會有任何資料遺失——開啟 vault 就會重建。

這個設計帶來以下好處：

• 使用 Git 進行版本控制（只有 Markdown 和 YAML 檔案重要）
• 用任何文字編輯器手動編輯
• 透過檔案同步工具（Dropbox、iCloud、Syncthing）同步
• 不需要資料庫遷移就能在不同機器間搬移

系統屬性

所有 Object 都有由 TypeMD 管理的系統屬性，分為三類：

儲存屬性（Stored）

寫入 frontmatter，依以下順序排列：

屬性	說明	類型
name	建立時保留原始輸入；若有 name template 則自動填入	使用者可編輯
description	選填的描述文字	使用者可編輯
created_at	建立時間，建立後不可變更	自動管理
updated_at	最後更新時間，儲存時自動更新	自動管理
tags	與內建 tag type 的 Relation（多值）	使用者可編輯
locked	布林值，啟用後禁止編輯	使用者可編輯
archived	布林值，啟用後在預設查詢中隱藏	使用者可編輯

衍生屬性（Derived）

從結構或中繼資料推導的穩定值，不寫入 frontmatter，唯讀：

屬性	說明
object_type	Object 所屬的 Type 名稱
created_by	建立此 Object 的來源

計算屬性（Computed）

需要解析內文或查詢索引的動態值，不寫入 frontmatter，唯讀：

屬性	說明
links	此 Object 內文中的 wiki-link 目標列表
backlinks	連結到此 Object 的其他 Object 列表
updated_by	最後更新此 Object 的來源

SQLite 索引

索引儲存在 .typemd/index.db，包含：

• Object 中繼資料 — type、檔名和所有 frontmatter 屬性
• Wiki-link 記錄 — 從 Object 內文提取，用於反向連結追蹤
• 全文搜尋索引 — 由 FTS5 驅動，涵蓋檔名、屬性和內文

索引檔案不應直接編輯。它完全由 TypeMD 管理。

自動同步行為

索引在以下情況會自動同步：

• 開啟 Vault 時 — 每次開啟 vault 時，TypeMD 都會走訪所有 Object 檔案並同步索引（例如 git clone 後首次開啟也適用）
• CLI/TUI 操作時 — 建立、儲存或刪除 Object 時會立即更新索引

同步流程由 Projector 元件處理，它透過 Repository 走訪所有 Object 檔案並 upsert 到索引中。Projector 在系統中的角色請參閱系統架構。

查詢架構

TypeMD 提供兩種查詢路徑：

結構化查詢

查詢管線使用結構化 FilterRule 條件來篩選 Object。每條規則指定一個屬性、一個運算子和一個值。查詢針對 SQLite 索引執行以提升效能，回傳輕量的 ObjectResult 投影而非完整的 Object 實體。

篩選規則透過 Vault.QueryObjects() 以程式化方式使用，也可在 view 設定（types/<name>/views/<view>.yaml）中定義。

全文搜尋

使用 tmd search 搜尋檔名、屬性和內文。由 SQLite FTS5 驅動：

tmd search "concurrency"
tmd search "golang" --json

TUI 搜尋

在 TUI 中，按 / 進入搜尋模式。結果會即時篩選。按 Esc 清除結果並回到完整列表。

唯一性約束機制

Type schema 可透過設定 unique: true 來啟用 name 唯一性檢查。啟用後，TypeMD 會阻止建立同一 type 下擁有相同 name 值的多個 Object。

types/person/schema.yaml

name: person
unique: true  # 同一個人名稱只能有一個
properties:
  - name: role
    type: string

唯一性在建立時透過檢查索引中是否已存在相同 type 和 name 的 Object 來強制執行。也可透過 tmd type validate 驗證。內建的 tag type 預設啟用 unique: true。

Vault 設定

.typemd/config.yaml 是選填的 vault 層級設定檔，使用介面層命名空間：

.typemd/config.yaml

date_format: "DD/MM/YYYY"
datetime_format: "DD/MM/YYYY HH:mm:ss"
cli:
  default_type: page

目前支援的設定：

Key	說明
date_format	date 屬性的顯示格式，使用 YYYY、MM、DD 等 token（預設：YYYY-MM-DD）。儲存格式不變。
datetime_format	datetime 屬性及系統時間戳的顯示格式，使用 YYYY、MM、DD、HH、mm、ss 等 token（預設：YYYY-MM-DD HH:mm:ss）。儲存格式不變。
cli.default_type	tmd object create 省略 type 參數時使用的預設 object type

Config 檔在 vault 開啟時載入。若檔案不存在或為空，所有設定使用零值（不會出錯）。無效的 YAML 會產生錯誤。