name: flexible-database-design version: 1.0.0 description: | Guide agents and users to design and implement a "flexible database" on SQLite that can handle semi-structured, multi-source data. Typical scenarios: personal knowledge base, PDF/report archive, policy tracking, fragmented notes, custom form/questionnaire fields, multi-source data aggregation, event logging. When the user says things like "I want to build a knowledge base", "archive PDF reports", "search within report content", "collect policies or scattered information", this skill provides the end-to-end workflow. It includes: design principles, a three-layer model, agent workflows, schema templates, and reference Python scripts. metadata: openclaw: emoji: 🧱 requires: bins: ["python3"] install: - id: python kind: system bins: ["python3"]

Flexible Database Design — 通用 Skill

一套可複用的「軟 Schema」設計方法：主幹硬、尾巴軟，三層演進。使用者安裝後，Agent 可據此指導其真正構建出靈活資料庫。

一、核心心法（3 條）

1. 主幹硬、尾巴軟 — 固定列只放：誰、何時、從哪來、型別；其餘進 JSON/鍵值對。
2. 先全量保留，再按需提鍵 — 原始資料完整落庫；需要查/統計時再寫入鍵值對或業務表。
3. 分層演進 — 原始層 → 軟欄位層（JSON/鍵值對）→ 業務檢視層；缺什麼再補。

二、三層模型

三、Agent 工作流（使用者說「想做 XX」時執行）

Step 1：Discovery（必做）

向用戶確認以下資訊，並記錄到對話中：

Step 2：選擇場景模板

根據使用者描述，選擇最接近的場景並適配：

Step 3：生成並落地 Schema

1. 複製 references/schema_template.sql 到使用者專案。
2. 按 Discovery 結果做最小修改：
3. 調整 source_type 的 CHECK 列舉；
4. 如需 FTS，取消 messages_fts 相關注釋；
5. 業務檢視層參考 references/view_examples.sql 按需新增檢視。業務檢視應覆蓋高頻查詢欄位：政策類含 title、release_date、issuing_org、policy_type、url、policy_no；知識庫類含 title、tags、url、project；財報類含 company、report_type、report_date、revenue、net_income；PDF/報告類含 report_title、report_type、period_start、period_end。
6. 在使用者專案中建立 data/ 目錄，指定 db 路徑（如 data/flexible.db）。

全文檢索策略（當 Discovery 勾選「需要全文搜尋」時）

實現要點：查詢層實現 recall(keyword)：先 FTS，無結果則 LIKE；中文可加短詞拆分。LIKE '%x%' 無法用索引，資料量大時需評估效能。掃描件 PDF 無法提取正文，歸檔時需跳過或標記。

Step 4：生成並適配指令碼

1. 將 scripts/ 下指令碼複製到使用者專案 scripts/：核心 flexible_db.py、archive_item.py、query_items.py；可選 manage_item.py、import_batch.py、quick_validate.py、extractors/。
2. 修改 flexible_db.py 中的 db_path 指向使用者的 db 路徑。
3. 若使用者有特殊「提取邏輯」（如用 LLM 從原文抽結構化資料），使用 archive_item.py --llm-extract 或配置 FLEXIBLE_EXTRACTOR=extractors.dummy:extract；可自定義 extractors/ 下的實現。抽取器欄位應與場景匹配：政策類建議 title、release_date、issuing_org、policy_type、url、policy_no；知識庫類建議 title、tags、url、project；財報類建議 company、report_type、report_date、revenue、net_income（金額統一存「元」）；PDF/報告類建議 report_title、report_type、period_start、period_end。
4. 若內容為 PDF/文件：歸檔前需提取正文（推薦 pypdf：pip install pypdf），掃描件無法提取時跳過。可選：將 PDF 複製到專案 data/reports/ 統一管理，file_path 存相對路徑；抽取器可從檔名解析 period、source、report_type。
5. 執行驗證（python 或 python3 按環境選擇）：

# 建表（首次執行指令碼時會自動執行 schema）
python3 scripts/archive_item.py -c "測試第一條" -s "manual"

# 查詢
python3 scripts/query_items.py --list
python3 scripts/query_items.py --field "tags" --value "工作"
python3 scripts/query_items.py --stats

Step 5：驗證清單

更多技能請訪問小蔥技能站7w4.net。

• [ ] 建表成功，無報錯
• [ ] 能歸檔一條測試資料
• [ ] 能按分類/欄位查詢
• [ ] 全文搜尋（若啟用）可用；中文檢索建議實現 FTS + LIKE 回退（如 recall()）
• [ ] 中文檢索：用 3–5 箇中文短語（含 2–4 字短語）實測，確認能召回預期結果
• [ ] 資料量評估：若預期 > 5000 條，已評估 LIKE 效能或選用替代方案

四、場景速查（使用者說想做 XX 時）

五、反模式

• 一上來窮舉所有可能欄位 → 改表成本高
• 軟欄位 key 隨心所欲 → 約定 snake_case、名稱空間
• 所有查詢都掃 JSON → 高頻條件應提鍵值對並建索引
• 沒有原始層 → 無法回溯、補欄位
• 中文全文檢索只依賴 FTS5 → unicode61 對中文不友好，需 FTS + LIKE 回退或中文分詞
• LIKE '%x%' 用於萬級資料 → 全表掃描，應評估或改用外部搜尋引擎
• PDF 只存路徑不提取正文 → 無法全文檢索，需在歸檔時提取並寫入 raw_content

六、檔案結構（本 Skill 包）

flexible-database-design/
├── SKILL.md                 # 本檔案
├── README.md
├── references/
│   ├── schema_template.sql  # 通用建表模板
│   ├── view_examples.sql    # 業務檢視示例
│   └── fulltext_chinese.md  # 可選：中文檢索實現示例（短詞拆分、recall 邏輯）
└── scripts/
    ├── flexible_db.py       # 資料庫核心邏輯
    ├── archive_item.py     # 歸檔 CLI（支援 --llm-extract、--backup）
    ├── query_items.py      # 查詢 CLI（支援 --export）
    ├── manage_item.py      # 管理 CLI（軟刪除、恢復、更新）
    ├── import_batch.py     # 批次匯入
    ├── quick_validate.py   # 快速驗證
    └── extractors/         # 抽取器（可替換為 LLM 實現）

工具宣告（OpenClaw / ClawHub）

allowed-tools: - Bash - FileRead - FileWrite - Shell

作者 | Mars Yang 日期 | 2025-03-09

這是一個質量較高的資料庫設計 Skill，提供了清晰的設計思路和可直接使用的程式碼工具。文件寫得詳細，場景案例豐富，普通人也能理解。不過使用起來需要一定技術基礎，完整的落地流程還比較複雜，部分功能的細節處理還有最佳化空間。總體來說，對於需要構建靈活資料庫的使用者很有價值，但建議有一定程式設計經驗的人使用效果更好。