Obsidian Wiki × Team Knowledge Base 使用指南
Obsidian Wiki × Team Knowledge Base 使用指南
這份指南整理如何把 obsidian-wiki 擴展成團隊知識庫，並用 Azure DevOps (Github/ GitLab) 作為版本控管、審核與協作平台。
官方 Repo：https://github.com/ar9av/obsidian-wiki
中文好讀版：https://github.com/Ar9av/obsidian-wiki/blob/main/README_TW.md
1. 核心概念
obsidian-wiki 負責把專案、Agent 對話、技術決策與文件整理成 Markdown 知識頁。
Azure DevOps 負責：
- 儲存團隊共用 Vault。
- 用 branch 隔離每個人的修改。
- 用 Pull Request 審核 AI 產生的知識。
- 用 Azure DevOps Wiki 或 Repo 瀏覽已整理內容。
- 用 Pipeline 做 lint、連結檢查與備份。
整體架構：
Team members / Projects / Agent sessions
↓
obsidian-wiki
↓
local Obsidian Vault clone
↓
feature branch
↓
Azure DevOps Pull Request
↓
review and merge
↓
team knowledge base
重點：
- 團隊共用同一個 Vault repo。
- 每個人本機各自 clone 一份。
- AI 產生內容先進
_staging/或個人 branch。 - 重要知識透過 PR review 後才進主分支。
- 不需要每個人各自維護一套分散 wiki。
2. 建議 Azure DevOps 結構
建立一個 Azure DevOps Repo，例如：
team-knowledge-vault
Repo 內容：
team-knowledge-vault/
├── concepts/
├── entities/
├── projects/
├── decisions/
├── runbooks/
├── references/
├── synthesis/
├── journal/
├── _raw/
├── _staging/
├── _archives/
├── AGENTS.md
├── index.md
├── log.md
└── hot.md
建議用途：
concepts/：跨專案概念，例如 Clickhouse、MariaDB、CDC。projects/：各專案背景、架構、決策與踩坑。decisions/：ADR (Architecture Decision Record) 或重要技術決策。runbooks/：維運、部署、事故處理流程。_raw/：尚未整理的原始材料。_staging/：AI 產生、尚未 review 的筆記。AGENTS.md：團隊寫作規則與安全邊界。
3. 每個人的本機設定
每位成員先 clone Azure DevOps Repo：
git clone https://dev.azure.com/ORG/PROJECT/_git/team-knowledge-vault
cd team-knowledge-vault
每個人的 .env 指到自己的本機路徑：
OBSIDIAN_VAULT_PATH=/path/to/team-wiki
OBSIDIAN_SOURCES_DIR=
WIKI_STAGED_WRITES=true
團隊使用時，建議把三個參數分成兩類：
OBSIDIAN_VAULT_PATH：每位成員本機的共享 Wiki Git repo 路徑OBSIDIAN_SOURCES_DIR：每位成員自己的來源資料路徑 (可以留空, wiki-ingest 時每次帶入路徑)WIKI_STAGED_WRITES：團隊建議開啟，避免 Agent 直接修改正式知識庫
雖然實際路徑不同，但 OBSIDIAN_VAULT_PATH 都指向同一個 Git repository 的各自本機 clone。
GitHub / GitLab
team-wiki repo
│
├── Mike local clone
├── Dennis local clone
└── Alex local clone
不建議多人直接同時操作同一個網路共享資料夾，因為可能產生：
- 同時修改相同 Markdown
.manifest.json衝突index.md衝突_staging/互相覆蓋- Obsidian 同步衝突
使用每人一份 local clone，再透過 Git branch 和 Pull Request 合併，會比較穩定。
4. 團隊工作流程
4.1 建立分支
每次整理知識前先開分支：
git checkout -b knowledge/project-auth-architecture
4.2 從專案寫入知識
在任一專案中執行：
/wiki-update
整理這個專案的認證架構、資料流、重要決策、踩坑紀錄與可重用模式。
產生內容先放在 _staging/，不要直接覆蓋既有正式頁。
4.3 Review staged notes
檢查 _staging/：
git diff
確認內容後，把成熟內容移到正式分類：
_staging/projects/auth-notes.md
↓
projects/auth-service.md
4.4 建立 Pull Request
git add .
git commit -m "docs: add auth architecture knowledge notes"
git push -u origin knowledge/project-auth-architecture
在 Azure DevOps 建立 PR，由 team review：
- 內容是否正確？
- 是否洩漏密碼、token、客戶資料？
- 是否重複既有頁面？
- 是否有連到相關概念、專案與 runbook？
- 是否應該放在
projects/、concepts/、decisions/或runbooks/？
5. Azure DevOps Pipeline 建議
最小可行 Pipeline 只需要做三件事：
PR opened
↓
markdown lint
↓
wikilink / broken link check
↓
secret scan
可以先從人工 review 開始，等 PR 數量變多再加 Pipeline。不要一開始就把 CI 做太複雜。
6. 權限與治理
建議分三層：
- Readers：可以讀取知識庫。
- Contributors：可以開 branch 與 PR。
- Maintainers：可以 approve、merge、調整結構。
規則：
- 禁止直接 push
main。 - 所有 AI 生成內容都要 PR review。
- 私密資料不進 repo。
- 事故紀錄與 runbook 優先整理，因為重複使用價值最高。
7. 團隊 AGENTS.md 範例
在 repo root 建立 AGENTS.md：
# Team Knowledge Base Rules
- This is a shared team knowledge base stored in Azure DevOps.
- Do not write secrets, credentials, customer PII, or production tokens.
- Put AI-generated notes in `_staging/` unless explicitly asked to update a final page.
- Prefer updating existing pages over creating duplicates.
- Link related projects, concepts, decisions, and runbooks.
- Use Pull Requests for all changes to shared knowledge.
這個檔案會讓不同 Agent 進入 vault 時讀到同一套團隊規則。
8. 日常使用節奏
完成一個 feature 後
/wiki-update
整理這次 feature 的架構、關鍵決策、trade-off、測試策略與後續注意事項。
修完一個 incident 後
/wiki-update
整理這次 incident 的症狀、排查流程、根因、修復方式與預防措施。
適合的內容請整理成 runbook。
開始做類似任務前
/wiki-query 以前 team 怎麼處理 OAuth token refresh race condition？
9. 什麼時候需要 Azure DevOps Wiki？
最簡單的做法是把 Obsidian Vault 當 repo 管理，團隊用 Obsidian 或 VS Code 閱讀。
需要更多網頁化瀏覽時，再把 Azure DevOps Wiki 接上：
- 適合非工程成員閱讀。
- 適合公開 runbook 或 onboarding docs。
- 適合把 main branch 的 Markdown 當正式知識庫呈現。
如果 team 都習慣 Obsidian，Azure DevOps Repo + PR 已經夠用。
10. 最簡化理解
obsidian-wiki
負責把知識整理成 Markdown。
Obsidian Vault
負責本機閱讀、編輯與連結。
Azure DevOps Repo
負責團隊同步與版本控管。
Pull Request
負責審核 AI 產生內容。
_staging/
負責隔離尚未確認的知識。