前言¶

Obsidian 裏混着業務附件、項目 README、手寫 Markdown 和各類生成物時，單靠人工維護「每個源文件旁有沒有 .core.md、文件夾有沒有 資料索引.md、圖譜鏈接是否跟得上改名/移動」很容易漏項。常見做法是偶爾全庫整理，或在插件裏做局部自動化，但和「在 Cursor 裏一邊改文件一邊讓模型補索引」往往脫節。

下面介紹 SkillHub 社區 Skill Obsidian資料整理（座標 @user_55161a2d/obsidian-core-notes，當前版本 1.0.2）。它把 vault 內的核心側記、專題綜合筆記、文件夾索引和 Obsidian 關係鏈接寫成一套可複用的 Agent 工作流，並附帶 Python 腳本做掃描、刷新與校驗。

這是什麼¶

Obsidian資料整理 面向 Obsidian vault，也可用於與文檔/代碼混放的 workspace。發佈者爲 SkillHub 用戶 user_55161a2d，來源爲 community，分類爲 knowledge-management，不需要 API Key（requires_api_key=false）。

Skill 的定位是：讓源文件、生成的 .core.md、專題級 專題綜合.core.md 以及關係索引保持同步；在創建、編輯、移動、刪除、掃描、彙總或整理可能涉及 .core.md、專題綜合.core.md、資料索引.md、核心文件索引.md 的文件時啓用。

核心功能¶

筆記類型與命名¶

Skill 區分四類產出，並在規則裏固定用途：

1. 文件側記：對非 Markdown 的業務源附件，生成與源文件同名的 <源文件名>.core.md。
2. 文件夾索引：目錄內用 資料索引.md 做導航與直接源文件列表。
3. 工作區入口：在 vault 根或約定位置維護 核心文件索引.md。
4. 專題綜合：僅對經篩選的高價值目錄寫 專題綜合.core.md；多數目錄應保持輕量源圖，而非處處「深度綜述」。

已有意義的 Markdown 核心文檔應直接引用，不重複生成側記。代碼、配置、腳本、測試、模型輸出、解析結果目錄等不生成 .core.md（詳見 Skill 內 references/core-file-rules.md）。

文檔治理字段¶

生成物需帶 YAML 治理字段，例如：

• 生成的 .core.md 側記：doc_role: source、doc_authority: supporting、doc_rule: wiki-doc-governance-v1。
• 資料索引.md 與 核心文件索引.md：doc_role: common、doc_authority: preferred、doc_rule: wiki-doc-governance-v1。
• 承載長期判斷的深度 專題綜合.core.md 可用 doc_role: result。

修訂源 Markdown、索引或專題筆記前，Skill 要求對照 vault 內文檔分類分級準則（路徑在 SKILL 中爲 個人/公司相關個人資料/個人知識庫實現路徑/文檔分類分級與技能取信準則.md）；若你的庫沒有該文件，需自行對齊同類治理約定。

附帶腳本命令¶

安裝後 Skill 目錄下的 scripts/obsidian_core_notes.py 提供：

refresh 是圖譜維護 pass，不能替代人工或 LLM 對 專題綜合.core.md 的策展式撰寫。用戶要求「像 V3 一樣的專題綜合」時，需在 refresh 之後對選定目錄做專題綜合 pass（見 references/topic-synthesis-core-notes.md）。

安全刪除與標記¶

僅當文件含有生成標記時才允許批量覆蓋或刪除，例如 <!-- CORE_FILE_NOTE_V1 -->、<!-- CORE_FOLDER_INDEX_V1 -->、<!-- CORE_WORKSPACE_INDEX_V1 -->。手寫 Markdown 除非用戶明確要求，不得刪除。激進清理前，Skill 要求先把將被覆蓋/刪除的生成筆記備份到 vault 外。

安裝與啓用¶

通過 SkillHub CLI¶

若尚未安裝 CLI，可先按 SkillHub 安裝說明 執行檢測與安裝。安裝 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能無法被識別。

command -v skillhub && skillhub --version

skillhub install @user_55161a2d/obsidian-core-notes --dir ~/.cursor/skills/

Cursor 的 skills 目錄一般爲 ~/.cursor/skills/；Claude Code 爲 ~/.claude/skills/；Codex 爲 ~/.codex/skills/ 或項目下的 .agents/skills/。其他客戶端路徑以 SkillHub 安裝文檔第四節爲準。

通過對話讓 Agent 安裝¶

SkillHub 頁面提供的提示詞爲：請根據 https://skillhub.cn/install/skillhub.md，安裝 @user_55161a2d/obsidian-core-notes。

安裝完成後重啓或刷新 Agent，使 Skill 被加載。本 Skill 版本 1.0.2，SkillHub 頁面統計（以抓取資料爲準）：評分 100000，下載 2237 次。

典型用法¶

下面步驟對應 SKILL.md 中的 Workflow，<skill-dir> 替換爲安裝後的 Skill 目錄，<vault-root> 替換爲你的 Obsidian 庫根路徑。

1. 確認根目錄：默認以當前工作目錄爲 vault/workspace root，用戶指定時用其路徑。

2. 大範圍改動前先掃描：

python <skill-dir>/scripts/obsidian_core_notes.py scan --root <vault-root> --json

3. 選定筆記類型（側記 / 資料索引.md / 專題綜合.core.md），在同一輪對話裏完成源文件的增刪改移時，同步更新對應 .core.md 與最近的 資料索引.md。

4. 批量刷新輕量索引與側記：

python <skill-dir>/scripts/obsidian_core_notes.py refresh --root <vault-root>

5. 要做專題綜合前先篩目錄：

python <skill-dir>/scripts/obsidian_core_notes.py topic-candidates --root <vault-root> --json

6. 批量操作後校驗：

python <skill-dir>/scripts/obsidian_core_notes.py validate --root <vault-root>

7. 僅在用戶明確要求時清理生成物：

python <skill-dir>/scripts/obsidian_core_notes.py clean-generated --root <vault-root>

發現默認業務根/項目根不準時，可在 scan 與 refresh 上使用 --business-root 或 --project-root 覆蓋發現邏輯（見 references/core-file-rules.md 的 Discovery defaults）。

適用場景與注意¶

適合誰：已經在 Obsidian（或與代碼倉共存的文檔庫）裏用 .core.md + 中文索引文件組織知識、並希望 Agent 在改文件時自動維護圖譜與索引的維護者；也適合需要腳本批量 refresh / validate 的定期整理。

限制與坑：

• 不要把 refresh 當成專題綜述生成器；V3 式 專題綜合.core.md 需要單獨的策展步驟與 topic-candidates 篩選。
• 修改原始 Markdown 時，不要用過程/證據內容覆蓋結果類文件；優先用 related_process、related_result、validation 等溯源鏈接。
• 依賴 vault 內可選的「文檔分類分級」準則文件時，若路徑不存在，需自行約定等效的 doc_role / doc_authority 規則。
• 腳本會排除 node_modules、.git、構建產物、模型目錄等；業務邊界錯判時用 CLI 參數糾正。

結尾¶

Obsidian資料整理 把核心側記、專題綜合、文件夾索引與 Obsidian 鏈接維護收斂成一套 Agent 規則加可執行腳本，適合在編輯 vault 時減少索引漂移，並用 validate 兜底批量操作。

• SkillHub 頁面：https://www.skillhub.cn/skills/user_55161a2d/obsidian-core-notes
• 安裝座標：@user_55161a2d/obsidian-core-notes
• API 資源地址：https://api.skillhub.cn/user_55161a2d/obsidian-core-notes