📦 kb-framework — 本地知识库

版本： 2.0 分类： Knowledge Base / Search 依赖： Python 3.9+, SQLite, ChromaDB

---

什么是 KB 框架？

一个完整的知识库，具备：

• 混合搜索（语义 + 关键词）
• 自动索引（Markdown、PDF、OCR）
• SQLite + ChromaDB 集成
• 每日审计 保障数据质量

---

安装（1 分钟）

1. 安装 Skill

# 克隆或解压到 OpenClaw 工作区
cp -r kb-framework ~/.openclaw/workspace/
# 或仅复制 skill：
cp kb-framework/SKILL.md ~/.npm-global/lib/node_modules/openclaw/skills/kb/

2. 安装依赖

pip install -r requirements.txt

3. 初始化数据库

python3 ~/.openclaw/workspace/kb-framework/kb/indexer.py --init

---

配置

设置环境变量 KB_DB_PATH 或编辑 kb/config.py

---

用法

Python API

# 导入
import sys
sys.path.insert(0, "/path/to/kb-framework")
from kb.indexer import BiblioIndexer
# 索引文件
with BiblioIndexer("/path/to/knowledge.db") as idx:
    idx.index_file("/path/to/file.md")
# 搜索
from kb.library.knowledge_base.hybrid_search import HybridSearch
hs = HybridSearch()
results = hs.search("Your search term", limit=10)

CLI（推荐）

内置 kb 命令，一键使用：

# 添加到 .bashrc 实现全局调用：
alias kb="/path/to/kb-framework/kb.sh"
# 命令：
kb index /path/to/file.md          # 索引文件
kb search "machine learning"       # 搜索知识库
kb audit                           # 运行完整审计
kb ghost                           # 查找孤立条目
kb warmup                          # 预加载 ChromaDB 模型

遗留 Python 脚本

# 索引新文件
python3 kb/indexer.py /path/to/file.md
# Ghost 扫描器（查找孤立 DB 条目）
python3 kb/scripts/kb_ghost_scanner.py
# 完整审计
python3 kb/scripts/kb_full_audit.py
# ChromaDB 预热（开机时）
python3 kb/scripts/kb_warmup.py

---

架构

kb-framework/
├── SKILL.md                    # 本文件
├── README.md                   # 详细文档
├── kb/
│   ├── indexer.py              # 核心索引器（BiblioIndexer）
│   ├── commands/               # CLI 命令：index、sync、audit、ghost、warmup、search
│   ├── base/                   # 核心：config.py、db.py、logger.py、command.py
│   ├── library/
│   │   └── knowledge_base/
│   │       ├── hybrid_search.py       # 混合搜索（语义 + 关键词）
│   │       ├── chroma_integration.py  # ChromaDB 包装器
│   │       ├── chroma_plugin.py     # ChromaDB 插件（集合管理）
│   │       ├── embedding_pipeline.py # 批量嵌入
│   │       ├── reranker.py           # 搜索结果重排序
│   │       ├── fts5_setup.py         # SQLite FTS5 全文搜索
│   │       ├── chunker.py            # 文本分块
│   │       └── synonyms.py           # 查询扩展
│   └── obsidian/               # Obsidian Vault 集成
└── scripts/
    ├── index_pdfs.py            # PDF + OCR 索引
    ├── kb_ghost_scanner.py      # 遗留 ghost 扫描器
    ├── kb_full_audit.py         # 遗留审计脚本
    └── kb_warmup.py             # 遗留预热脚本

---

数据库 Schema

files 表

字段	类型	说明
id	TEXT	UUID
file_path	TEXT	绝对路径
file_name	TEXT	文件名
file_category	TEXT	分类
file_type	TEXT	pdf/md/txt
file_size	INTEGER	字节数
line_count	INTEGER	行数
file_hash	TEXT	SHA256
last_indexed	TIMESTAMP	最后索引时间
index_status	TEXT	indexed/pending/failed
source_path	TEXT	原始路径
indexed_path	TEXT	MD 提取路径
is_indexed	INTEGER	0/1

file_sections 表

字段	类型	说明
id	TEXT	UUID
file_id	TEXT	外键 → files
section_header	TEXT	标题
section_level	INTEGER	1-6
content_preview	TEXT	前 500 字符
content_full	TEXT	完整内容
keywords	TEXT	JSON 数组
importance_score	REAL	0.0-1.0

keywords 表

字段	类型	说明
id	INTEGER	自增
keyword	TEXT	词汇
weight	REAL	词频

---

故障排查

“ChromaDB 首次启动慢”

python3 kb/scripts/kb_warmup.py

“搜索不到结果”

# 运行审计
python3 kb/scripts/kb_full_audit.py
# Ghost 扫描
python3 kb/scripts/kb_ghost_scanner.py

“OCR 太慢”

# 在 index_pdfs.py 中启用 GPU：
GPU_ENABLED = True  # 默认：False

---

库结构（重要）

content/ - 原始文件

所有非 Markdown 文件：

library/content/
├── Gesundheit/          # PDF、研究
├── Medizin_Studien/     # 医学文献
├── Bücher/              # 书籍、指南
├── Sonstiges/           # 未分类
└── [category]/          # 可自定义分类

agent/ - Markdown 文件

所有 .md 文件，供 agent 使用：

library/agent/
├── projektplanung/      # 代理计划
├── memory/              # 每日日志
├── Workflow_Referenzen/ # 可复用工作流
├── agents/              # 代理专属文档
└── [category]/          # 可自定义分类

集成新文件

规则： library/[content|agent]/[category]/[topic]/[file] 示例：

# 新的健康 PDF
library/content/Gesundheit/2026/Chelat-Therapie.pdf
# 新的代理计划
library/agent/projektplanung/Treechat_Upgrade.md
# 新的学习笔记
library/agent/learnings/2026-04-12_Git_Workflow.md

---

许可证

MIT License - 免费使用。