# Personal Knowledge Base

> 管理个人知识库，基于RAG和文本向量化技术，支持文件的保存、向量化、检索、问答、删除等功能

- Skill: `dvcrn/personal-knowledge-base-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add dvcrn/personal-knowledge-base-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/personal-knowledge-base-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/dvcrn/personal-knowledge-base-2

---


# 个人知识库技能

本技能提供基于RAG（检索增强生成）和文本向量化技术的个人知识库管理能力。

## 何时使用

当用户表达以下意图时，使用此技能：
1. 创建新知识库：「创建知识库abc」或「创建知识库abc，文本块长度为200」
2. 保存文件到知识库：「把文件xxx保存到我的知识库aabb」
3. 更新知识库文件：「在知识库abc中更新xxx文件」
4. 在知识库中查询知识或信息：「查知识库aabb：xxx」
5. 列举知识库：「当前我有哪些知识库」
6. 列举知识库文件：「知识库aabb下有哪些文件」
7. 删除知识库文件：「删除知识库aabb下的xx文件」
8. 查询文本块：「查看知识库aabb中xx文件的第n个文本块内容」

## 配置文件

技能目录下的 `config.txt` 文件包含大部分配置参数。

### ZHIPUAI_API_KEY 配置方式

**推荐方式**：通过环境变量配置（优先级更高）

```bash
# Windows PowerShell
$env:ZHIPUAI_API_KEY="your-api-key-here"

# Windows CMD
set ZHIPUAI_API_KEY=your-api-key-here

# Linux/Mac
export ZHIPUAI_API_KEY="your-api-key-here"
```

**备选方式**：在 `config.txt` 中配置（向后兼容）

```
ZHIPUAI_API_KEY=your-api-key-here
```

**优先级**：环境变量 > config.txt

> **注意**：出于安全考虑，推荐使用环境变量方式配置 API Key，避免敏感信息明文保存在配置文件中。

### 其他配置项说明

| 参数 | 说明 |
|------|------|
| workspace_root | 知识库根目录 |
| embedding_model | 嵌入模型名称 |
| ZHIPUAI_LLM_MODEL | 智谱LLM模型名称 |
| DEFAULT_CHUNK_SIZE | 知识库缺省文本块大小 |
| DEFAULT_TOP_K | 默认检索的文本块最大数量 |
| DEFAULT_SIMILARITY_THRESHOLD | 相似度阈值 |

## 支持的文件格式

- **文本文件** (.txt)
- **PDF文件** (.pdf)
- **Word文档** (.doc, .docx)
- **Markdown文件** (.md, .markdown)
- **PowerPoint演示文稿** (.ppt, .pptx)

## 目录结构要求

知识库目录应按以下结构组织：
```
知识库根目录/
└── {知识库名称}/
    ├── sourcefiles/    # 原始文件存储目录
    └── vectordb/       # 向量数据库存储目录
        ├── faiss_index.bin
        ├── faiss_metadata.pkl
        └── kb_metadata.pkl    # 知识库元数据（包含文本块大小）
```

## 使用方法

### 1. 创建新知识库

当用户表示「创建知识库abc」时：

1. 解析知识库名称（如abc）
2. 在知识库根目录下创建 `abc` 目录
3. 在 `abc` 目录下创建 `sourcefiles` 和 `vectordb` 子目录
4. 在 `vectordb` 目录下生成空的向量库和索引文件
5. 保存文本块大小元数据（若用户指定了文本块长度则使用该值，否则使用config.txt中的DEFAULT_CHUNK_SIZE）
6. 重叠大小自动计算为：文本块大小 × 10%

使用示例：
```python
from scripts.knowledge_base_manager import KnowledgeBaseManager

# 创建知识库，指定文本块大小为500
result = KnowledgeBaseManager.create_knowledge_base(
    knowledge_base_name="abc",
    workspace_root="d:/Nancy/MyWork/WorkBuddyWorkSpace/MyKnowledgeBase",
    chunk_size=500  # 可选，不指定则使用config.txt中的DEFAULT_CHUNK_SIZE
)
print(result)
# 输出: {'success': True, 'message': "成功创建知识库 'abc'，文本块大小: 500", ...}
```

### 2. 保存文件到知识库

当用户表示「把文件（上传的文件或指定路径的文件）保存到我的知识库aabb」时：

1. 检查知识库是否存在，若不存在返回「知识库不存在，请先创建」
2. 找到工作区知识库根目录的`/aabb` 子目录
3. 确保 `sourcefiles` 目录存在（如不存在则创建）
4. 检查文件是否已存在于sourcefiles目录中：
   - 如果文件已存在，返回「文件已经存在」，不执行后续向量化操作
5. 复制原始文件到sourcefiles目录
6. 从知识库的元数据中读取文本块大小
7. 使用文本块大小进行文本分割（重叠大小 = 文本块大小 × 10%）
8. 将文本内容分割切块、向量化，存储到vectordb目录

使用示例：
```python
from scripts.knowledge_base_manager import create_knowledge_base_manager

# 创建知识库管理器
manager = create_knowledge_base_manager(
    knowledge_base_name="aabb",
    workspace_root="d:/Nancy/MyWork/WorkBuddyWorkSpace/MyKnowledgeBase"
)

# 添加文件到知识库
result = manager.add_file_to_knowledge_base("path/to/file.pdf")
print(result)
```

### 3. 更新知识库中的文件

当用户表示「在知识库abc中更新xxx文件」时：

1. 检查知识库是否存在，若不存在返回「知识库不存在，请先创建」
2. 检查知识库中是否存在该文件，若不存在返回「知识库中不存在该文件」
3. 删除该文件的源文件（sourcefiles目录下）
4. 删除该文件在向量库中的所有文本块
5. 将新文件添加到知识库

使用示例：
```python
from scripts.knowledge_base_manager import create_knowledge_base_manager

manager = create_knowledge_base_manager(
    knowledge_base_name="abc",
    workspace_root="d:/Nancy/MyWork/WorkBuddyWorkSpace/MyKnowledgeBase"
)

# 更新文件
result = manager.update_file_in_knowledge_base("path/to/new_file.pdf")
print(result)
```

### 4. 检索并回答问题

当用户表示「查知识库aabb：xxx」时：

1. 创建指定知识库（aabb）的向量数据库管理器
2. 将问题xxx向量化
3. 在向量库中检索与问题最相似的文本片段
4. 用检索到的内容,结合用户的问题，进行理解和思考，然后合理组织语言，回答用户的问题

使用示例：
```python
# 查询知识库
result = manager.answer_question("xxx")
print(result["answer"])
print(result["source_files"])
```

### 5. 列举知识库

当用户表示「当前我有哪些知识库」时：

1. 检查知识库根目录
2. 返回所有知识库列表（每个知识库包含：名称、文件数量、文本块大小、简单描述）

使用示例：
```python
from scripts.knowledge_base_manager import KnowledgeBaseCatalog

catalog = KnowledgeBaseCatalog()
# 获取简要列表
kb_list = catalog.list_knowledge_bases()
print(kb_list)

# 获取详细信息
kb_list_detailed = catalog.list_knowledge_bases_detailed()
for kb in kb_list_detailed:
    print(f"知识库: {kb['name']}, 文件数: {kb['file_count']}, 文本块大小: {kb['chunk_size']}, 描述: {kb['description']}")
```

### 6. 列举知识库下的文件

当用户表示「知识库aabb下有哪些文件」时：

1. 创建指定知识库的向量数据库管理器
2. 从向量库的元数据中获取所有文件的名称和相关信息
3. 返回文件列表（每个文件包含：文件名、文本块数量、导入日期时间）

使用示例：
```python
manager = create_knowledge_base_manager("aabb")
files = manager.list_files_in_knowledge_base()
for f in files:
    print(f"文件: {f['filename']}, 文本块数: {f['chunk_count']}, 导入时间: {f['import_time']}")
```

### 7. 删除知识库下的某个文件

当用户表示「删除知识库aabb下的xx文件」时：

1. 创建指定知识库的向量数据库管理器
2. 检查vectordb目录下的向量库中是否存在该文件的文本块
3. 如果存在，删除向量库中该文件相关的所有文本块
4. 删除sourcefiles目录下的原始文件
5. 如果向量库中没有这个文件，返回「aabb知识库中不存在这个文件」

使用示例：
```python
result = manager.remove_file_from_knowledge_base("xx.pdf")
print(result)
```

### 8. 查询指定文本块内容

当用户表示「查看知识库aabb中xx文件的第n个文本块内容」时：

1. 创建指定知识库（aabb）的向量数据库管理器
2. 检查vectordb目录下的向量库元数据中是否存在该文件
3. 如果文件存在，获取该文件的第n个文本块内容
4. 返回文本块内容，如果索引超出范围则返回错误提示

使用示例：
```python
# 查询指定文件的第3个文本块
result = manager.get_chunk_by_index("xx.pdf", 3)
print(result["content"])  # 文本块内容
print(result["total_chunks"])  # 文件总文本块数
```

## 配置参数

以下参数可在创建KnowledgeBaseManager时配置：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| knowledge_base_name | 必填 | 知识库名称 |
| workspace_root | config.txt配置 | 知识库根目录 |
| embedding_model | "embedding-3" | 嵌入模型 |
| chunk_size | 从知识库元数据加载 | 文本块大小 |
| vector_size | 2048 | 嵌入向量维度（固定值） |
| similarity_threshold | 0.5 | 相似度阈值 |
| top_k | 3 | 默认检索的文本块数量 |

**注意**：
- 文本块重叠大小会在运行时自动计算：`chunk_overlap = int(chunk_size * 0.1)`
- 每个知识库可以有不同的文本块大小设置，存储在知识库的元数据文件中

## 依赖要求

- Python 3.8+
- faiss-cpu
- langchain
- langchain-community
- langchain-text-splitters
- pypdf
- python-docx
- python-pptx (支持PPT文件)
- docx2txt (用于Word文档解析)
- zhipuai (智谱AI SDK，可选)

安装依赖：
```bash
pip install faiss-cpu langchain langchain-community langchain-text-splitters pypdf python-docx python-pptx markdown zhipuai docx2txt
```

## 注意事项

1. **文件去重**：通过文件哈希值判断文件是否已存在于向量库中，避免重复向量化
2. **文本分割**：使用RecursiveCharacterTextSplitter进行智能文本分块，支持中英文混合场景
3. **相似度过滤**：检索结果会根据相似度阈值进行过滤，确保返回内容相关性
4. **向量库重建**：删除文件时会重建FAISS索引，确保数据一致性
5. **知识库元数据**：每个知识库独立保存文本块大小设置，确保文件分割一致性
6. **知识库存在性检查**：创建管理器时会自动检查知识库是否存在，不存在则抛出异常