Obsidian Wiki × Digital Garden 使用指南

這份指南整理如何把 ar9av/obsidian-wiki 接到既有的 Obsidian Vault，並讓它與 Digital Garden 共用同一份 Markdown source。

Obsidian Repo：https://github.com/ar9av/obsidian-wiki
Obsidian Digital Garden: https://github.com/oleeskild/obsidian-digital-garden

相關入口

• 回到 Mike's Digital Garden 首頁
• 知識管理架構：寫作與發佈分離模式
• Hermes Agent 完整使用指南
• Hermes Agent 常用玩法指南
• Obsidian Wiki 基礎日常使用指南

1. 核心概念

obsidian-wiki 的用途是把不同專案、Agent 對話與技術文件整理進同一個 Obsidian Vault。

整體架構如下：

不同程式專案
├── hr-system
├── clickhouse-etl
├── event-hub
└── obsidian-garden
        │
        ▼
同一個 Obsidian Vault
        │
        ├── 私有知識
        ├── 專案筆記
        ├── 技術概念
        └── Digital Garden 公開文章

重點：

• 只需要一個 Vault。
• setup 通常只做一次。
• 不同專案都可以寫入同一個 Vault。
• wiki-query 可以跨專案搜尋整個 Vault。
• Digital Garden 原本的發布流程可以保留。

2. 可以使用既有 Vault 嗎？

可以。

既有的 Obsidian Vault 可以直接指定給 obsidian-wiki，不需要建立新的空 Vault。

你的情況是：

obsidian-vault/
├── AI/
├── Dev/
├── Projects/
├── Tool/
└── Home.md

這個 Vault 同時也是 Digital Garden 的 source，因此建議遵守以下原則：

1. 保留現有資料夾與 Markdown。
2. 不要讓 AI 自動產生的筆記直接公開。
3. 只有確認過的文章才加入 dg-publish: true。
4. 第一次 setup 前先建立 Git 備份。

3. 一次性安裝與初始化

3.1 進入現有 Vault

在 Terminal 輸入：

cd 

在 cd 後保留一個空格，再把 Finder 中的 obsidian-vault 資料夾拖入 Terminal。

完成後會變成類似：

cd "/Users/mike/Documents/obsidian-vault"

確認目前路徑：

pwd

3.2 備份現有 Vault

如果 Vault 已經是 Git repository：

git status
git add .
git commit -m "backup before obsidian-wiki setup"

如果尚未使用 Git，可以先跳過，但仍建議至少複製一份備份。

3.3 安裝 obsidian-wiki

建議使用 pipx：

brew install pipx
pipx ensurepath

重新開啟 Terminal 後：

pipx install obsidian-wiki

確認：

obsidian-wiki --help

3.4 指定目前 Vault

當 Terminal 已經位於 obsidian-vault 內，執行：

obsidian-wiki setup --vault "$(pwd)"

這會把目前資料夾設定為共用 Wiki Vault。

3.5 驗證安裝

obsidian-wiki info
obsidian-wiki doctor
obsidian-wiki list

用途：

obsidian-wiki info

查看版本、Vault 路徑與設定資訊。

obsidian-wiki doctor

檢查 Vault、設定檔與 Skills 是否正常。

obsidian-wiki list

查看目前安裝的 Wiki Skills。

遇到 pip3/python3 版本不一致、PATH 抓不到指令等問題時，可參考 obsidian-wiki 安裝與設定筆記 的除錯步驟。

4. 第一次 Agent 初始化

CLI setup 完成後，開啟你常用的 Agent，例如 OpenCode：

cd "/你的完整路徑/obsidian-vault"
opencode

接著輸入：

/wiki-setup

或：

set up my wiki

因為你使用的是既有 Digital Garden Vault，建議使用以下提示：

使用目前這個既有 Obsidian Vault 初始化 Wiki。

不要重新整理或覆蓋現有 Digital Garden 文章。
保留 Hermes Agent、NextJS、Projects、Tool 等現有資料夾。
Wiki 所需的 metadata 或內部資料夾請另外建立。
不要改動既有 frontmatter。
自動產生的筆記不要加入 dg-publish: true。

這個 Agent 初始化通常只需要做一次。

5. 日常使用流程

之後不需要一直待在 Vault 目錄中。

5.1 從不同專案寫入知識

例如 Next.js 專案：

cd ~/Projects/my-nextjs-project
opencode

執行：

/wiki-update

也可以指定整理內容：

/wiki-update

整理這個專案的認證架構、資料庫設計、
重要技術決策、踩坑紀錄與可重用模式。

再換到另一個專案：

cd ~/Projects/clickhouse-etl
opencode

執行：

/wiki-update

兩個專案的知識都會寫入同一個 Vault。

5.2 查詢既有知識

在任何專案中：

/wiki-query 我以前如何處理 MariaDB RSS 高於 buffer pool？

或者：

/wiki-query ClickHouse ReplacingMergeTree 的版本欄位如何設計？

也可以直接從 Terminal 查詢：

obsidian-wiki query "MariaDB memory RSS"

5.3 匯入現有 Markdown 或文件

你的 Vault 已經有：

AI/
Dev/
Projects/
Tool/
Home.md

可以用：

/wiki-ingest

建議第一次不要整個 Vault 一次匯入，而是分資料夾測試：

/wiki-ingest Tool

/wiki-ingest NextJS

/wiki-ingest Hermes Agent

推薦提示：

使用 wiki-ingest 分析 Tool 資料夾。

保留原始 Markdown 與 frontmatter。
不要修改 dg-publish 欄位。
只建立必要的摘要、索引與 Wikilink。

6. Digital Garden 發布流程

原本流程不需要改。這篇文章整理的是同一個原則：寫作與發布分離，公開與否仍由 dg-publish 手動控制。

Obsidian Vault
    ↓
帶有 dg-publish: true 的文章
    ↓
Digital Garden Plugin
    ↓
GitHub
    ↓
Vercel

obsidian-wiki 只是新增一層知識整理：

程式專案 / Agent 對話
        ↓
obsidian-wiki
        ↓
同一個 Obsidian Vault
        ↓
人工確認
        ↓
dg-publish: true
        ↓
Digital Garden

建議發布規則

AI 自動產生的筆記：

---
dg-publish: false
---

或乾脆不加入 dg-publish。

確認內容可公開後，再手動改成：

---
dg-publish: true
---

7. 建議 Vault 結構

可以保留現有結構，再增加一個 AI Wiki 區：

obsidian-vault/
├── AI/
├── Dev/
├── Projects/
├── Tool/
├── AI-Wiki/
│   ├── Projects/
│   ├── Concepts/
│   ├── Debugging/
│   └── Patterns/
├── _raw/
└── Home.md

建議：

• AI-Wiki/：自動整理的知識。
• Projects/：專案級筆記。
• Concepts/：技術概念。
• Debugging/：排查紀錄。
• Patterns/：可跨專案重用的方法。
• _raw/：尚未整理的原始內容。

8. 日常建議節奏

完成一次開發或 Debug 後

/wiki-update

範例：

/wiki-update

整理這次 MariaDB RSS 記憶體問題的排查流程、
判斷依據、排除項目與最終結論。

開始處理類似問題前

/wiki-query 過去處理 MariaDB RSS 過高時有哪些可能原因？

匯入臨時筆記

/wiki-ingest

查看 Wiki 狀態

/wiki-status

檢查壞連結

obsidian-wiki lint

檢查安裝狀態

obsidian-wiki doctor

9. 哪些情況需要重新 setup？

通常只有以下情況：

• 更換 Vault。
• 換新電腦。
• 設定檔損壞。
• Agent Skills 路徑改變。
• 更新套件後需要重新掛載 Skills。
• 想完全重建 Wiki 結構。

新增新專案時，不需要重新 setup。

10. 最完整指令流程

# 1. 進入既有 Vault
cd "/你的完整路徑/obsidian-vault"

# 2. 備份
git add .
git commit -m "backup before obsidian-wiki setup"

# 3. 安裝
brew install pipx
pipx ensurepath
pipx install obsidian-wiki

# 4. 指定現有 Vault
obsidian-wiki setup --vault "$(pwd)"

# 5. 驗證
obsidian-wiki info
obsidian-wiki doctor
obsidian-wiki list

# 6. 啟動 Agent
opencode

在 OpenCode 中：

使用目前既有的 Digital Garden Vault 初始化 Wiki。

保留現有資料夾與文章。
不要覆蓋既有 frontmatter。
不要自動加入 dg-publish: true。

之後日常使用：

cd ~/Projects/某個專案
opencode

/wiki-update

查詢知識：

/wiki-query 問題內容

11. 最簡化理解

/wiki-setup

全域初始化，一次即可。

/wiki-update

在不同專案內反覆執行，把知識寫入共用 Vault。

/wiki-query

查詢整個 Vault 中的知識。

/wiki-ingest

匯入既有 Markdown、文件或歷史資料。

Digital Garden

仍然只發布你明確標記為 dg-publish: true 的文章。

延伸閱讀

• Mike's Digital Garden
• 知識管理架構：寫作與發佈分離模式
• Hermes Agent 完整使用指南
• Hermes Agent 常用玩法指南
• Obsidian Wiki 基礎日常使用指南
• obsidian-wiki 安裝與設定筆記