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 结果做最小修改：
   • 调整 source_type 的 CHECK 枚举；
   • 如需 FTS，取消 messages_fts 相关注释；
   • 业务视图层参考 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。
3. 在用户项目中创建 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：验证清单

• 建表成功，无报错
• 能归档一条测试数据
• 能按分类/字段查询
• 全文搜索（若启用）可用；中文检索建议实现 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