EastDong314/agent-skills

Obsidian 筆記

操作環境

使用本地知識庫 ${OBSIDIAN_VAULT:-$HOME/workspace/notes}。將其視為使用者擁有的知識庫和 Markdown 程式碼庫：保留無關的編輯，除非被要求，否則避免大量重寫，並保持筆記檔名和連結符合 Obsidian 的規範。

此知識庫通常是代理的工作區根目錄，因此一般的筆記工作可以使用內建的檔案工具（Codex：read/apply_patch；DSH 和 pi：read/edit/write）。對於知識庫之外的任何路徑，寫入前須先詢問。

此技能是 Codex、pi 和 DSH 共用的套件。選擇符合當前代理的基底目錄，然後在以下每個命令中使用 $HELPER：

# DSH（規範來源副本）
export SKILL_DIR="$HOME/.dsh/skills/obsidian-notes"
# Codex
# export SKILL_DIR="$HOME/.codex/skills/obsidian-notes"
# pi
# export SKILL_DIR="$HOME/.pi/agent/skills/obsidian-notes"

export HELPER="$SKILL_DIR/scripts/obsidian_notes.py"
python3 "$HELPER" --help

如果 SKILL_DIR 尚未在當前 shell 中導出，請在每個命令中重新導出它，或者根據此技能所報告的技能基底目錄來解析 scripts/obsidian_notes.py 的路徑。請使用 python3（此助手僅使用標準函式庫；僅當 python3 不存在時才回退到 python）。

對於確定性的 CRUD、索引、日誌、Lint、Bases 和 Canvas 操作，優先使用此捆綁的助手。它預設使用知識庫，並拒絕知識庫外部的路徑。

在需要時，使用本機 Obsidian 應用程式或 obsidian:// URI 方案來開啟筆記。在 Linux Flatpak 上，應用程式 ID 為 md.obsidian.Obsidian；通常 PATH 中沒有 obsidian 執行檔。

此技能是 kepano/obsidian-skills 中模式的本地、知識庫專用超集：Obsidian Flavored Markdown、Bases、JSON Canvas、CLI 用法和乾淨的網頁提取。將這些領域保持在一個工作流程中，以便知識庫操作始終限制在 ${OBSIDIAN_VAULT:-$HOME/workspace/notes} 範圍內。

知識庫模型

對於較大的知識工作，使用三層模型：

• 原始來源：使用者提供的文章、PDF、剪報、會議記錄、螢幕截圖或文字稿。將這些視為真實來源的輸入；除非明確要求，否則不要改寫或刪除它們。
• Wiki 筆記：結構化的 Markdown 頁面，代理可以透過總結、綜合、交叉連結和更新來建立和維護。
• Schema：此技能加上知識庫本地約定筆記（位於 技術/00-System/ 和 Obsidian 指南資料夾）。在進行非簡單變更之前，搜尋有關知識庫使用、分類法和 Obsidian 約定的筆記。

值得優先閱讀的知識庫本地 Schema 筆記：AGENTS.md（知識庫根目錄，全域規則）、技術/AGENTS.md（技術/ 本地規則）、技術/00-System/目錄結構說明.md、技術/00-System/全局維護規則.md、技術/00-System/分類與標籤規範.md、技術/00-System/知識庫使用說明.md、技術/00-System/文檔模板說明.md 和 技術/10-個人效率與環境/Obsidian/Obsidian知識管理使用規範.md。

需要遵守的已知知識庫約定：

• 內容以中文撰寫；筆記是帶有 YAML frontmatter 的 Markdown，至少包含 tags 和 related，通常還有 title/aliases/created/updated/type/status/source。
• 根資料夾是 AI/（主要知識庫，編號的章節），以及 開發/、日記/、零星想法/、項目/。
• 不確定的分類屬於 98-待整理；棄用的內容屬於 99-歸檔。僅當確實需要時才建立這些資料夾。
• 優先更新現有的高價值筆記，而不是覆蓋它；如果無法安全合併，則建立一個帶有「待合併」後綴的新檔案。

對於非簡單的工作，請先閱讀相關的 Schema 筆記。目標是複合知識：更新現有的頁面、連結、索引條目和日誌，以便未來的對話無需從頭開始重新發現相同的上下文。

工作流程

1. 從使用者的請求中釐清操作：建立、讀取、更新、刪除、搜尋、匯入、查詢、Lint、整理、開啟、建立 Base、建立 Canvas、剪藏網頁來源或除錯 Obsidian 行為。
2. 在更改任何內容之前檢查現有筆記：
   • 在 Bash 中使用 rg，或使用代理自己的內容/路徑搜尋工具進行內容和路徑搜尋。
   • 對於知識庫範圍內的路徑，使用助手的 search、read 或 list 命令。
   • 當結構、分類法或長期維護很重要時，請閱讀知識庫 Schema 筆記。
   • 僅在應用程式配置重要時才檢查 .obsidian/。
3. 保留 Obsidian 語義：
   • 對於內部參考，使用 Wiki 連結，如 [[Target Note]] 或 [[Target Note|Alias]]。
   • 當使用者需要精確參考時，使用標題連結 [[Target Note#Heading]] 和區塊連結 [[Target Note#^block-id]]。
   • 對於穩定的分類，在 frontmatter 中使用標籤；僅在標籤是散文的一部分時才使用內聯 #tags。
   • 維護 YAML frontmatter 以記錄元資料、日期、別名、狀態、來源、專案、領域、模型、主機和下一步行動。
   • 對於結構化欄位，優先使用 Obsidian Properties 和 Bases 相容的 frontmatter。僅當使用者明確要求 Dataview 查詢、內聯欄位或 Dataview 儀表板時，才使用 Dataview 內聯欄位，例如 status:: active。
   • 在嵌入知識庫內容時，優先使用相對嵌入 ![[file.png]] 或 ![[Note#Heading]]。
   • 僅對受益於視覺強調的內容使用 Callout：摘要、警告、範例、決策、待辦事項和問題。
4. 使用代理的修補/編輯工具（Codex：apply_patch；DSH 和 pi：edit）進行範圍編輯，或使用 write/助手來建立或取代整個筆記。在編輯或取代檔案之前，請先讀取它。
5. 對於持久性變更，更新或重新產生索引並附加日誌條目。
6. 編輯後進行驗證：讀取已更改的檔案、檢查連結/搜尋結果、驗證 .base 或 .canvas 檔案（如果存在），並可選擇在 Obsidian 中開啟筆記。

筆記品質規則

對於新筆記，請建立在 Obsidian 中有用的筆記，而不是純 Markdown 傾印：

• 從 YAML frontmatter 開始，除非目標資料夾有明確的相反約定。
• 當概念有別名時，請包含 aliases。
• 盡可能包含符合現有知識庫分類法的 tags。
• 新增一個簡潔的第一段，說明筆記的內容。
• 新增帶有標題的章節，以便進行反向連結。
• 使用 Wiki 連結新增 ## 相關連結 或 ## Links 到相關的現有筆記。匹配目標資料夾已使用的本地化標題：編號的 AI/ 資料夾使用 ## 相關連結，專案筆記可能使用任一格式。
• 預設將結構化欄位放在 YAML frontmatter 中，以便 Obsidian Properties 和 Bases 可以編輯、排序和篩選它們。除非使用者要求 Dataview 內聯欄位，否則不要將同一個欄位同時作為 frontmatter 和正文中的 key:: value 重複。
• 對於專案或任務筆記，包含可操作的狀態和下一步欄位。
• 對於長青知識筆記，將聲明連結到來源筆記和相關概念。

在建立新的筆記範本、修復筆記結構或決定如何使用 frontmatter、標籤、反向連結、Dataview、索引檔案、日誌和來源匯入時，請閱讀 references/obsidian-patterns.md（位於 $SKILL_DIR 下）。

Obsidian Markdown 功能

當這些語法功能能讓筆記在 Obsidian 中更有用時，請使用它們：

• Wiki 連結：[[Note]]、[[Note|Alias]]、[[Note#Heading]]、[[Note#^block-id]]、[[#Same-note heading]]。
• 嵌入：![[Note]]、![[Note#Heading]]、![[image.png|300]]、![[document.pdf#page=3]]、![[Canvas.canvas]]、![[View.base#View Name]]。
• Callout：> [!note]、> [!warning] Title、> [!todo]- Collapsed，內容使用巢狀引用行。
• 註解：%%hidden text%% 或用於代理專用註解的區塊註解（不應渲染）。
• 強調/數學/圖表：==高亮==、內聯 $math$、區塊 $$math$$ 和圍欄 mermaid。
• 腳註：[^1] 參考、定義和內聯腳註。

不要過度格式化筆記。優先使用一般的 Markdown，直到 Obsidian 擴充功能能改善導航、檢索或渲染效果。

Bases

當使用者想要筆記的資料庫檢視、任務清單、閱讀清單、專案儀表板、篩選索引或屬性驅動的表格/卡片/清單/地圖時，請使用 .base 檔案。

Base 檔案是 YAML。圍繞以下內容建構它們：

• filters：全域和檢視特定的表達式，例如 file.hasTag("project")、file.inFolder("Daily Notes")、status == "active"。
• formulas：計算欄位，例如到期前的天數、狀態標籤、字數估計或衍生連結。
• properties：筆記、檔案和公式欄位的顯示名稱和配置。
• summaries：聚合公式，例如平均值、總和、最小值、最大值、最新值、已勾選、空值、已填寫、唯一值。
• views：具有明確 order 的表格、卡片、清單或地圖檢視。

規則：

• 引用篩選器和公式表達式，特別是當它們包含 :、#、括號、比較運算子或巢狀引號時。
• 將包含雙引號的公式用單引號包起來：'if(done, "Yes", "No")'。
• 日期減法會傳回持續時間。在數值函數之前存取 .days、.hours 等。
• 使用 if(property, expression, fallback) 保護可選屬性。
• 編輯後進行驗證：python3 "$HELPER" validate-base "Dashboards/Projects.base"。

JSON Canvas

當使用者要求視覺地圖、研究板、流程圖、依賴關係圖、專案概覽或畫布時，請使用 .canvas 檔案。

Canvas 檔案是 JSON，具有頂層 nodes 和 edges 陣列：

• 節點需要 id、type、x、y、width 和 height。
• 節點類型為 text、file、link 和 group。
• 邊需要 id、fromNode 和 toNode；可選的側邊為 top、right、bottom、left。
• 產生唯一的 16 字元小寫十六進位 ID。
• 在 JSON 字串值中使用真正的換行符，除非文字應顯示 \n 字元。
• 在節點之間保留 50-100px 的間距，對齊到網格，並保持群組節點足夠大以包含其子節點。
• 編輯後進行驗證：python3 "$HELPER" validate-canvas "Maps/Topic.canvas"。

網頁剪藏與來源提取

當使用者提供要匯入知識庫的 URL 時：

• 如果存在本地 defuddle 命令，優先使用 defuddle parse <url> --md；它會提取可讀的 Markdown 並移除導航雜亂內容。
• 此處預設不安裝 defuddle；請先檢查，否則使用代理的網頁擷取/搜尋工具，然後僅將持久性的事實和連結儲存到知識庫中。
• 不要對已經指向原始 Markdown 的 URL 使用 Defuddle。
• 將來源 URL、作者/日期（如果可用）、檢索日期和處理狀態保留在 frontmatter 中。
• 對於較長的來源，請建立來源摘要筆記，並更新持久性的概念/專案/實體筆記，而不是將整篇文章傾印到 Wiki 層中。

Obsidian CLI 與應用程式

當 Obsidian 正在執行且 obsidian 命令可用時，使用它執行應用程式感知的操作：

obsidian help
obsidian read file="My Note"
obsidian search query="term" limit=10
obsidian property:set name="status" value="done" file="My Note"
obsidian backlinks file="My Note"
obsidian daily:append content="- [ ] Follow up"

對於外掛或主題除錯，在程式碼更改後優先使用應用程式感知的命令：

obsidian plugin:reload id=my-plugin
obsidian dev:errors
obsidian dev:console level=error
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

如果未安裝 CLI 或 Obsidian 未執行，請回退到知識庫檔案操作和 obsidian:// URI 方案。助手的 open 命令已經處理了 Flatpak 應用程式和 URI 回退：

python3 "$HELPER" open "技術/00-System/index.md"

匯入、查詢與 Lint

當使用者提供來源或要求從外部工件新增知識時，使用匯入行為：

• 讀取來源並識別持久性的事實、決策、概念、實體、未解決的問題和矛盾。
• 在建立新頁面之前，搜尋知識庫中的現有頁面。
• 僅在將來有用時才建立來源摘要筆記。
• 更新相關的現有概念/專案/實體筆記，而不僅僅是新的來源頁面。
• 新增反向連結和 related 條目，以便新知識可以從現有筆記中存取。
• 附加一個日誌條目，描述匯入了什麼以及哪些頁面發生了更改。

從知識庫回答時使用查詢行為：

• 首先閱讀索引/Schema 筆記（如果可用）。
• 在回答之前搜尋並閱讀相關筆記。
• 在答案中透過 Wiki 連結或路徑引用本地筆記。
• 如果答案產生了持久性的綜合，請提供將其寫回為筆記或更新現有筆記的選項。

使用 Lint 行為進行維護：

• 檢查缺少的 frontmatter、缺少的相關章節、孤立筆記、重複標題、過時的聲明、錯誤的連結以及缺乏頁面的重要概念。
• 在進行廣泛清理之前，優先報告有針對性的修復計劃。
• 對於要求的清理，以小批次修復連結和元資料，並記錄此次操作。

助手命令

助手預設使用 ${OBSIDIAN_VAULT:-$HOME/workspace/notes}（可用 --vault 覆蓋），並拒絕知識庫外部的路徑。執行 python3 "$HELPER" --help 以取得完整的命令清單。

# 搜尋標題和內容
python3 "$HELPER" search "query"

# 透過相對路徑讀取筆記
python3 "$HELPER" read "AI/example.md"

# 建立筆記，包括上層資料夾
python3 "$HELPER" create "AI/example.md" --title "範例" --tags project,active --body $'# 範例\n\n...'

# 在檢查後取代筆記
python3 "$HELPER" update "AI/example.md" --body "...完整的 markdown..."

# 僅在使用者明確要求時刪除
python3 "$HELPER" delete "AI/old-note.md" --yes

# 在 Obsidian 中開啟筆記
python3 "$HELPER" open "AI/example.md"

# 建立並驗證 Base
python3 "$HELPER" create-base "技術/00-System/active-projects.base" --name "活躍專案"
python3 "$HELPER" validate-base "技術/00-System/active-projects.base"

# 建立並驗證 Canvas
python3 "$HELPER" create-canvas "AI/Maps/project-overview.canvas"
python3 "$HELPER" validate-canvas "AI/Maps/project-overview.canvas"

# 在 技術/00-System/index.md 重新產生 Wiki 風格的索引
python3 "$HELPER" index