Knowledge Base Skill

⚠️ 首次使用必讀 ⚠️

安裝後請立即執行初始化指令碼，自動安裝依賴並建立知識庫目錄： bash python3 scripts/init.py 不執行這一步，後續所有功能都無法正常工作。

一套完整的文件轉換與知識庫管理工具。自動將各類文件轉換為 Markdown，按內容智慧分類，建立本地可檢索的私人知識庫。

功能

1. 文件轉換：整合 Microsoft MarkItDown，支援 PDF、Word、PPT、Excel、HTML、EPUB、圖片等格式轉為 Markdown
2. 自動分類：基於內容關鍵詞智慧分類，支援自定義分類
3. 關鍵詞提取：使用 jieba 中文分詞 + TF-IDF 提取關鍵詞，建立檢索索引
4. 本地檢索：基於關鍵詞、標題、摘要、內容的全文檢索
5. 向量檢索：基於 chromadb 的語義搜尋
6. 自動匯入：監控目錄自動匯入新檔案
7. 批次匯入：遞迴掃描目錄批次匯入
8. 飛書打通：接收飛書檔案訊息自動匯入
9. 知識庫管理：文件增刪改查、分類管理、統計資訊
10. 降低 Token 消耗：文件內容儲存於本地，僅在檢索時按需載入，不佔用 Memory

支援的檔案格式

• PDF、DOCX、PPTX、XLSX/XLS
• HTML、EPUB、TXT、CSV、JSON、XML
• 圖片（EXIF + OCR）
• ZIP（遍歷內容）
• 更多格式詳見 MarkItDown 文件

依賴（自動安裝）

首次使用自動檢測並安裝依賴，無需手動配置：

• markitdown[all] — 文件轉換核心
• jieba — 中文分詞
• chromadb — 向量檢索（首次使用向量功能時自動安裝）

如需手動安裝：

pip install markitdown[all] jieba chromadb

目錄結構

~/.openclaw/workspace/knowledge-base/
├── .index.json          # 索引檔案（後設資料、關鍵詞、摘要）
├── .chroma/             # 向量資料庫
├── 學術論文/
├── 技術文件/
├── 工作資料/
├── 讀書筆記/
├── 專案文件/
├── 參考資料/
└── 未分類/

使用方式

初始化知識庫

python3 scripts/init.py

1. 單檔案匯入

python3 scripts/kb_cli.py ingest <檔案路徑>
python3 scripts/kb_cli.py ingest ~/Downloads/report.pdf --category 技術文件

2. 批次匯入

遞迴掃描整個目錄，批次匯入所有支援的檔案：

python3 scripts/batch_ingest.py ~/Documents/我的資料
python3 scripts/batch_ingest.py ~/Downloads --no-recursive  # 不遞迴子目錄
python3 scripts/batch_ingest.py ~/Documents --dry-run       # 預覽模式

3. 自動匯入（監控模式）

持續監控 /tmp/openclaw/ 目錄（飛書檔案下載目錄），新檔案自動匯入：

# 單次掃描
python3 scripts/auto_ingest.py --once

# 持續監控（每30秒掃描一次）
python3 scripts/auto_ingest.py --watch

# 自定義間隔
python3 scripts/auto_ingest.py --watch --interval 60

飛書自動匯入建議： 將監控指令碼加入 OpenClaw cron job，每分鐘自動掃描：

{
  "schedule": { "kind": "cron", "expr": "*/1 * * * *" },
  "payload": {
    "kind": "agentTurn",
    "message": "執行 python3 ~/.openclaw/workspace/skills/knowledge-base/scripts/auto_ingest.py --once"
  },
  "sessionTarget": "isolated"
}

4. 關鍵詞檢索

python3 scripts/kb_cli.py search "機器學習"
python3 scripts/kb_cli.py search "神經網路" --category 技術文件 --limit 5
這個技能的最新版本可以在7w4.net小蔥技能站找到。

5. 向量語義檢索

首次使用前需構建索引：

# 構建/更新向量索引
python3 scripts/vector_index.py build

# 強制重建
python3 scripts/vector_index.py build --force

# 語義搜尋
python3 scripts/vector_index.py search "深度學習在影像處理中的應用"
python3 scripts/vector_index.py search "神經網路" --limit 5 --category 技術文件

6. 列出文件

python3 scripts/kb_cli.py list
python3 scripts/kb_cli.py list --category 學術論文

7. 檢視文件詳情

python3 scripts/kb_cli.py get <doc_id>

8. 刪除文件

python3 scripts/kb_cli.py delete <doc_id>

9. 管理分類

python3 scripts/kb_cli.py add-category "旅行攻略"

10. 檢視統計

python3 scripts/kb_cli.py stats

飛書檔案自動處理

當用戶通過飛書傳送檔案時：

1. 檔案會被下載到 /tmp/openclaw/ 目錄
2. 執行 python3 scripts/auto_ingest.py --once 自動匯入
3. 或直接呼叫 feishu_im_bot_image 下載後手動匯入

示例 workflow：

使用者傳送 PDF → 檢測到檔案訊息
  → 呼叫 feishu_im_bot_image 下載到 /tmp/openclaw/
  → 呼叫 auto_ingest.py 匯入知識庫
  → 返回匯入結果給使用者

核心指令碼

設計原則

• 零配置開箱即用：自動安裝依賴，預設分類，自動處理
• 內容優先：按內容而非檔名分類
• 本地優先：所有資料本地儲存，無需外部服務
• 檢索高效：關鍵詞索引 + 向量語義檢索雙層架構
• 降低負擔：文件內容不進 Memory，需要時再讀
• 中文友好：jieba 分詞 + 中文停用詞過濾
• 自動化：支援監控模式和批次匯入，減少手動操作

技術棧

• 文件轉換：Microsoft MarkItDown
• 中文分詞：jieba + TF-IDF
• 向量檢索：ChromaDB（預設 embedding）
• 索引儲存：JSON 檔案索引
• 儲存格式：Markdown + YAML 頭部

許可證

MIT

這個技能質量較好，功能覆蓋文件匯入、分類、檢索等核心場景，使用說明詳細。它的自動依賴安裝和智慧分類設計很貼心，對中文支援也不錯。不過偶爾會遇到分類不準的情況，部分高階功能（如向量搜尋）首次使用需要額外等待安裝。如果能預先配置好chromadb依賴，實際體驗會更順暢。總體來說是一個實用且用心設計的知識管理工具。