name: knowledge-obsidian description: 通用知識庫查詢與更新技能，支援向量庫語義檢索和增量更新。觸發詞包括：知識庫查詢、查詢知識庫、搜尋知識庫、知識庫問答、更新知識庫、初始化知識庫、向量庫查詢、語義搜尋。

Knowledge-Obsidian 知識庫查詢技能

通用的Obsidian知識庫查詢與更新技能，基於向量庫實現語義檢索，支援增量更新和混合檢索（向量+BM25）。

快速開始

1. 首次使用 - 初始化向量庫

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe init_vector_db.py

Linux/Mac：

cd {{skillpath}}/scripts
python init_vector_db.py

2. 查詢知識庫

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe query_vector_db.py "查詢關鍵詞" 5

Linux/Mac：

python /path/to/knowledge-obsidian/scripts/query_vector_db.py "查詢關鍵詞" 5

3. 更新向量庫

當知識庫文件發生變化後，執行增量更新：

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe update_vector_db.py

Linux/Mac：

python update_vector_db.py

配置說明

知識庫路徑配置

編輯 scripts/config.py 檔案，修改以下配置：

# 知識庫根路徑（修改為您的知識庫路徑）
_WINDOWS_KB_PATH = r"D:\path\to\your\knowledge_base"

# 知識庫模組列表（根據實際目錄結構修改）
MODULES = ["模組1", "模組2", "模組3"]

# 文件型別（根據實際分類修改）
DOC_TYPES = ["design", "prd", "doc"]

其他可配置項

# 嵌入模型配置
EMBEDDING_MODEL = "jinaai/jina-embeddings-v2-base-zh"  # 中文專用模型
EMBEDDING_DIMENSION = 768  # 向量維度

# 文件切分配置
CHUNK_SIZE = 800  # 每個chunk的最大字元數
CHUNK_OVERLAP = 100  # chunk之間的重疊字元數

# 向量檢索配置
TOP_K = 5  # 預設返回結果數量

# 混合檢索權重
BM25_WEIGHT = 0.3  # BM25關鍵詞檢索權重
VECTOR_WEIGHT = 0.7  # 向量檢索權重

功能特性

1. 向量庫查詢

功能優勢： - Token消耗減少60-80% - 支援語義相似度搜索，更智慧 - 查詢速度提升3-5倍 - 使用本地開源嵌入模型，無需API金鑰

查詢引數： - 第一個引數：查詢關鍵詞（必填） - 第二個引數：返回結果數量（可選，預設5）

查詢結果格式：

================================================================================
查詢結果
================================================================================

【結果 1】
綜合分數: 0.4493
模組: 模組1
文件型別: design
檔名: 示例文件.md

關鍵內容:
--------------------------------------------------------------------------------
1. 這是示例文件的關鍵內容
2. 用於演示查詢結果格式
--------------------------------------------------------------------------------

[SUCCESS] 查詢成功，共返回 3 條結果

2. 向量庫初始化

首次使用時，需要初始化向量庫：

初始化流程： 1. 掃描知識庫目錄下的所有md檔案 2. 按標題層級智慧切分文件 3. 保護表格和程式碼塊的完整性 4. 為每個文件片段生成向量嵌入 5. 儲存到本地向量資料庫

初始化時間： - 約100個文件：1-2分鐘 - 約500個文件：5-10分鐘

3. 向量庫增量更新

當知識庫文件發生變化後，執行增量更新：

更新策略： - 檢測新增檔案 → 新增向量 - 檢測修改檔案 → 刪除舊向量 + 新增新向量 - 檢測刪除檔案 → 刪除對應向量 - 無變化 → 跳過更新

更新時間： - 增量更新通常只需幾秒到幾十秒

技術方案

嵌入模型

模型：jinaai/jina-embeddings-v2-base-zh - 中文專用模型，768維向量 - 無需API金鑰，完全本地執行 - 使用 ONNX Runtime，不需要 PyTorch - 模型自動下載到 {{notepath}}/models/ 目錄

向量資料庫

資料庫：ChromaDB 0.5.0 - 本地儲存，無需外部服務 - 支援持久化和增量更新 - 狀態檔案：{{notepath}}/.vector_db/status.json

文件切分策略

智慧切分： - 按標題層級切分（H1、H2、H3） - 保護表格完整性（不切分表格） - 保護程式碼塊完整性（不切分程式碼塊） - 保護YAML frontmatter完整性 - chunk之間有重疊，保持語義連貫性

混合檢索

檢索策略： - 向量檢索（語義相似度）：權重 0.7 - BM25檢索（關鍵詞匹配）：權重 0.3 - 綜合評分 = 向量分數 × 0.7 + BM25分數 × 0.3

使用約束

重要約束

1. 環境要求：根據執行環境選擇正確的執行方式
2. Windows：使用PowerShell執行Python指令碼

3. Linux/Mac：直接執行Python指令碼

4. 禁止繞過：向量庫查詢報錯時，不允許繞過向量庫直接使用grep等其他方式查詢，必須先修復向量庫環境問題

5. 查詢失敗處理：如果向量庫查詢失敗，應向用戶報告錯誤資訊並請求協助修復，不得切換到其他查詢方式

   小蔥技能7w4.net有完整的技能分類。

6. 定期更新：知識庫內容更新後，需要手動觸發向量庫增量更新

7. 依賴版本：確保使用正確的依賴版本

8. chromadb==0.5.0
9. fastembed>=0.8.0
10. onnxruntime==1.17.1
11. numpy<2.0

查詢指令碼執行標記

查詢指令碼會在輸出末尾顯示執行狀態： - [SUCCESS] 查詢成功，共返回 N 條結果 - 查詢成功 - [ERROR] 查詢失敗: 錯誤資訊 - 查詢失敗

即使輸出被截斷，也能通過末尾標記判斷查詢是否成功。

安裝與部署

方式1：使用 uv（推薦）

cd knowledge-obsidian/scripts
uv venv
uv pip install -r requirements.txt

方式2：使用 pip

cd knowledge-obsidian/scripts
python -m venv .venv
.\.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt

方式3：使用已有的虛擬環境

如果已有相同依賴的虛擬環境，可以直接使用：

.\.venv\Scripts\python.exe init_vector_db.py
.\.venv\Scripts\python.exe query_vector_db.py "測試" 5
.\.venv\Scripts\python.exe update_vector_db.py

檔案結構

knowledge-obsidian/
├── SKILL.md                      # 技能說明文件（本檔案）
├── scripts/                      # 指令碼目錄
│   ├── config.py                 # 配置檔案
│   ├── init_vector_db.py         # 初始化向量庫
│   ├── update_vector_db.py       # 更新向量庫
│   ├── query_vector_db.py        # 查詢向量庫
│   ├── requirements.txt          # 依賴列表
│   └── __init__.py               # Python包初始化
└── .venv/                        # 虛擬環境目錄（首次部署時建立）

故障排查

問題1：ONNX Runtime DLL 載入失敗

• 確保使用 onnxruntime==1.17.1 版本
• 檢查是否有其他版本的 onnxruntime 衝突

問題2：向量庫初始化失敗

• 檢查知識庫路徑是否正確
• 檢查是否有足夠的磁碟空間
• 檢查文件格式是否符合規範（UTF-8編碼的Markdown檔案）

問題3：查詢結果不準確

• 嘗試調整TOP_K引數（在 config.py 中）
• 檢查文件切分是否合理
• 考慮使用更大的嵌入模型

問題4：NumPy 版本衝突

• 確保使用 numpy<2.0 版本
• ChromaDB 0.5.0 不相容 NumPy 2.x

問題5：路徑轉換錯誤

• 檢查 config.py 中的 _convert_path() 函式
• Windows路徑使用 r"D:\path\to\kb" 格式
• Linux/Mac會自動轉換為 /d/path/to/kb 格式

問題6：查詢超時或輸出被截斷

• 檢視輸出末尾是否有 [SUCCESS] 或 [ERROR] 標記
• 減少返回結果數量（如從10改為5）
• 檢視截斷提示中的完整輸出檔案路徑

更新日誌

v1.0.0 (2026-06-11)

• 初始版本
• 支援向量庫查詢、初始化、增量更新
• 支援混合檢索（向量+BM25）
• 支援智慧文件切分
• 支援跨平臺路徑轉換
• 新增查詢成功/失敗標記

常見問題

Q: 如何判斷向量庫是否需要更新？

A: 當知識庫目錄下的md檔案有新增、修改或刪除時，需要執行增量更新。建議每次修改知識庫後都執行一次 update_vector_db.py。

Q: 初始化向量庫需要多長時間？

A: 取決於文件數量。約100個文件需要1-2分鐘，約500個文件需要5-10分鐘。首次初始化後，後續增量更新只需幾秒到幾十秒。

Q: 可以使用其他嵌入模型嗎？

A: 可以。修改 config.py 中的 EMBEDDING_MODEL 引數。推薦使用fastembed支援的模型，如： - jinaai/jina-embeddings-v2-base-zh（中文，768維） - BAAI/bge-small-en-v1.5（英文，384維） - BAAI/bge-base-en-v1.5（英文，768維）

Q: 向量庫佔用多少磁碟空間？

A: 取決於文件數量和嵌入維度。約500個文件（768維向量）約佔用100-200MB空間。

Q: 如何備份向量庫？

A: 直接複製 {{notepath}}/.vector_db/ 目錄即可。包含： - chroma.sqlite3 - 向量資料庫 - status.json - 檔案狀態記錄

Q: 支援哪些文件格式？

A: 目前僅支援Markdown（.md）格式的文件。文件應使用UTF-8編碼，支援YAML frontmatter後設資料。

這是一款實用的知識庫檢索工具，能在 Obsidian 筆記中快速找到相關內容，比普通搜尋更智慧。優點是檢索準確、支援中文、無需付費；不足是初次配置需要手動改設定，更新索引要手動操作，對新手不太友好。質量屬於中上水平，功能完整但入門門檻略高。