知识库框架

技能文档

---
name: zhishiku-gongjia
description: 完整的知识库框架，支持混合搜索（语义+关键词）、自动索引（Markdown、PDF、OCR）、SQLite与向量数据库集成，以及每日数据质量审计。当用户需要构建知识库、搜索知识、索引文档或进行数据质量管理时使用。
title: 知识库框架
category: 通用技能
---

# 知识库框架

**版本：** 2.0
**分类：** 知识库 / 搜索
**依赖：** Python 3.9+, SQLite, ChromaDB

---

## 什么是知识库框架？

一个完整的知识库系统，包含：
- **混合搜索**（语义 + 关键词）
- **自动索引**（Markdown、PDF、OCR）
- **SQLite + 向量数据库** 集成
- **每日审计** 确保数据质量

---

## 安装（1分钟完成）

### 1. 安装技能
```bash
# 复制到工作空间
cp -r knowledge-base-framework ~/.workspace/

# 或仅安装技能文件：
cp knowledge-base-framework/SKILL.md ~/.skills/kb/
```

### 2. 安装依赖
```bash
pip install -r requirements.txt
```

### 3. 初始化数据库
```bash
python3 knowledge-base-framework/kb/indexer.py --init
```

---

## 配置

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

---

## 使用方法

### Python API

```python
# 导入
import sys
sys.path.insert(0, "/path/to/knowledge-base-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("搜索关键词", limit=10)
```

### 命令行工具（推荐）

内置 `kb` 命令提供便捷访问：

```bash
# 添加到 .bashrc 以全局使用：
alias kb="/path/to/knowledge-base-framework/kb.sh"

# 命令：
kb index /path/to/file.md        # 索引文件
kb search "机器学习"              # 搜索知识库
kb audit                         # 运行完整审计
kb ghost                         # 查找孤立条目
kb warmup                        # 预加载向量数据库模型
```

### 旧版Python脚本

```bash
# 索引新文件
python3 kb/indexer.py /path/to/file.md

# 幽灵扫描器（查找孤立的数据库条目）
python3 kb/scripts/kb_ghost_scanner.py

# 完整审计
python3 kb/scripts/kb_full_audit.py

# 向量数据库预热（启动时）
python3 kb/scripts/kb_warmup.py
```

---

## 系统架构

```
knowledge-base-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  # 向量数据库集成
│   │       ├── chroma_plugin.py       # 向量数据库插件（集合管理）
│   │       ├── embedding_pipeline.py  # 批量嵌入
│   │       ├── reranker.py           # 搜索结果重排序
│   │       ├── fts5_setup.py          # SQLite FTS5 全文搜索
│   │       ├── chunker.py            # 文本分块
│   │       └── synonyms.py            # 查询扩展
│   └── obsidian/               # Obsidian笔记库集成
└── scripts/
    ├── index_pdfs.py           # PDF + OCR 索引
    ├── kb_ghost_scanner.py     # 旧版幽灵扫描器
    ├── kb_full_audit.py        # 旧版审计脚本
    └── kb_warmup.py            # 旧版预热脚本
```

---

## 数据库结构

### `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 | 频率权重 |

---

## 故障排查

### "向量数据库首次启动很慢"
```bash
python3 kb/scripts/kb_warmup.py
```

### "搜索找不到结果"
```bash
# 运行审计
python3 kb/scripts/kb_full_audit.py

# 幽灵扫描器
python3 kb/scripts/kb_ghost_scanner.py
```

### "OCR太慢"
```python
# 在 index_pdfs.py 中启用GPU：
GPU_ENABLED = True  # 默认：False
```

---

## 知识库目录结构（重要）

### content/ - 原始文件
所有非Markdown文件：
```
library/content/
├── 健康/                 # PDF、研究文献
├── 医学研究/             # 医学文献
├── 书籍/                # 图书、指南
├── 其他/                # 未分类
└── [分类]/              # 可自定义分类
```

### agent/ - Markdown文件
所有 .md 文件供智能体使用：
```
library/agent/
├── 项目规划/             # 项目计划
├── 日志/                # 每日日志
├── 工作流参考/           # 可复用工作流
├── 智能体/              # 智能体相关文档
└── [分类]/              # 可自定义分类
```

### 整合新文件

**规则：** `library/[content|agent]/[分类]/[主题]/[文件]`

示例：
```bash
# 新的健康PDF
library/content/健康/2026/螯合疗法.pdf

# 新的智能体计划
library/agent/项目规划/系统升级.md

# 新的学习记录
library/agent/学习笔记/2026-04-12_Git工作流.md
```

---

## 许可

MIT 许可证 - 自由使用。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。