# claude_code_kb_search

**Repository Path**: open_source_base/claude_code_kb_searchclaude_code_kb_search

## Basic Information

- **Project Name**: claude_code_kb_search
- **Description**: 这是一个为 Claude Code 设计的完整知识库管理解决方案，包含 MCP 服务器、可视化 WebUI 管理界面和一键启动功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-05
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库管理系统 - 统一架构版本
https://gitee.com/open_source_base/claude_code_kb_searchclaude_code_kb_search.git

这是一个为 Claude Code 设计的完整知识库管理解决方案，采用统一数据库架构，支持多知识库管理、智能搜索和可视化管理界面。

🎉 **最新版本特性**：
- ✅ **统一数据库架构** - 版本化管理，自动升级
- ✅ **多知识库支持** - 真正的多知识库管理，而非多数据库
- ✅ **智能搜索系统** - 支持关键词、语义和混合搜索
- ✅ **工作目录关联** - Claude Code 工作目录与知识库智能绑定
- ✅ **简化的管理** - 统一的API接口和管理工具

## ✨ 核心功能特性

### 🗄️ 统一数据库管理
- **版本化架构** - 数据库schema版本控制，支持平滑升级
- **自动迁移** - 启动时自动检测版本并升级到最新架构
- **数据安全** - 升级前自动备份，支持回滚
- **单一数据源** - 解决了多个数据库文件混乱的问题

### 🧠 多知识库系统
- **知识库管理** - 创建、管理多个独立的知识库
- **工作目录绑定** - 将知识库与Claude Code工作目录关联
- **优先级控制** - 设置知识库搜索优先级
- **动态切换** - 根据工作目录自动切换相关知识库

### 🔍 智能搜索引擎
- **多种搜索模式**：
  - 关键词搜索 - 基础文本匹配
  - 语义搜索 - AI驱动的语义理解（可配置）
  - 混合搜索 - 结合关键词和语义的最佳结果
- **搜索配置** - 支持OpenAI、本地模型等多种AI搜索后端
- **结果缓存** - 提高重复查询性能
- **可配置限制** - 自定义返回结果数量

### 🎛️ WebUI 管理界面
- **现代化界面** - 响应式设计，支持手机、平板访问
- **实时监控** - 系统控制、MCP服务器状态实时显示
- **知识库管理** - 创建、删除、配置知识库
- **工作目录管理** - 管理工作目录与知识库的关联关系
- **搜索配置** - 可视化配置智能搜索参数

### 🚀 一键启动系统
- **智能启动** - 自动检查环境、初始化数据库
- **多种模式** - 完整启动、仅WebUI、仅MCP服务器
- **自动配置** - 智能生成Claude Code配置
- **依赖检查** - 自动检测和提示缺失的依赖

## 🏗️ 系统架构

### 数据库架构 (v3.0)
```
主数据库 (knowledge.db) - 管理数据库
├── knowledge_bases - 知识库元信息
├── claude_workdirs - Claude工作目录
├── workdir_knowledge_relations - 工作目录-知识库关联
├── db_version - 数据库版本管理
└── database_info - 系统元信息

知识库文件 (kb_*.db) - 独立知识库
├── knowledge - 知识条目
├── db_version - 版本信息
└── 相关索引和触发器
```

### 组件架构
```
统一数据库管理层
├── DatabaseManager - 核心数据库管理器
├── 版本迁移系统 - 自动升级机制
└── 数据验证工具 - 完整性检查

多知识库业务层  
├── MultiKnowledgeBaseManager - 业务逻辑管理
├── 工作目录管理 - 智能关联
└── 知识搜索引擎 - 统一搜索接口

MCP服务层
├── UnifiedKnowledgeBase - 简化的MCP接口
├── 工具集成 - 完整的Claude Code工具
└── 错误处理 - 统一的错误处理机制

WebUI表现层
├── 统一API接口 - RESTful设计
├── 现代化前端 - Bootstrap + JavaScript
└── 实时状态监控 - 服务器状态跟踪
```

## 🚀 快速开始

### 环境要求
- **Python** 3.10 或更高版本
- **操作系统** Windows/macOS/Linux
- **内存** 至少 512MB 可用内存
- **磁盘空间** 至少 100MB 可用空间

### 安装依赖

```bash
# 完整安装（推荐）- 包含所有功能
pip install -r requirements.txt

# 最小化安装 - 基础功能
pip install -r requirements-minimal.txt

# 开发环境安装 - 包含测试工具
pip install -r requirements-dev.txt

# upgrade 升级到最新版本
pip install -r requirements.txt --upgrade
```

### 一键启动（推荐）

1. **双击运行启动器**
   ```bash
   /bin/launcher.bat  # Windows
   # 或
   ./bin//launcher.sh  # Linux/macOS
   ```

2. **选择启动模式**
   - 选项 1：**完整启动** - WebUI + MCP服务器 + 自动配置
   - 选项 2：**仅启动 WebUI** - 管理界面（开发模式）
   - 选项 3：**仅启动 MCP服务器** - 后台服务模式

3. **访问管理界面**
   - 地址：http://127.0.0.1:5500
   - 自动打开浏览器显示现代化管理界面

### 手动启动

```bash
# 1. 初始化数据库（首次运行）
python scripts/setup/init_knowledge.py

# 2. 启动 WebUI 管理界面
cd webui
python app.py

# 3. 启动 MCP 服务器（另开终端）
python scripts/legacy/knowledge_server_old.py
```

## 🎯 使用 Claude Code

### 自动配置（推荐）

1. **完整启动系统**
   ```bash
   /bin/launcher.bat  # 选择选项 1
   ```

2. **自动生成配置** - 系统会自动：
   - 检测Claude Code配置文件位置
   - 生成正确的MCP服务器配置
   - 提示如何添加到Claude Code

3. **确认配置** - 访问 WebUI 的"系统信息"页面确认配置正确

### 手动配置

如果需要手动配置，将以下内容添加到Claude Code配置文件：

```json
{
  "mcpServers": {
    "knowledge-search": {
      "command": "python",
      "args": [
        "你的项目路径/knowledge_server.py"
      ],
      "env": {}
    }
  }
}
```

**配置文件路径**：
- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.claude/claude_desktop_config.json`

## 🛠️ MCP 工具集

### 基础知识管理工具

#### `search_knowledge` - 知识搜索
**功能**: 在关联的知识库中搜索相关内容

**参数**:
- `query` (必需): 搜索关键词
- `limit` (可选): 返回结果数量，默认10

**示例**: "搜索 Python 装饰器相关知识"

#### `intelligent_search` - 智能搜索
**功能**: 使用AI驱动的语义搜索

**参数**:
- `query` (必需): 搜索查询
- `search_mode` (可选): 搜索模式 - `keyword`/`semantic`/`hybrid`
- `limit` (可选): 返回结果数量，默认5

**示例**: "用语义搜索找到关于异步编程的最佳实践"

#### `add_knowledge` - 添加知识
**功能**: 向指定知识库添加新知识

**参数**:
- `kb_id` (必需): 目标知识库ID
- `title` (必需): 知识标题
- `content` (必需): 知识内容
- `category` (可选): 分类
- `tags` (可选): 标签列表

**示例**: "添加关于Docker容器优化的运维知识"

### 知识库管理工具

#### `list_knowledge_bases` - 列出知识库
**功能**: 显示所有可用知识库及其状态

#### `get_workdir_knowledge_bases` - 获取工作目录知识库
**功能**: 显示当前工作目录关联的知识库

#### `create_knowledge_base` - 创建知识库
**功能**: 创建新的知识库

**参数**:
- `name` (必需): 知识库名称
- `description` (可选): 知识库描述

### 系统管理工具

#### `get_system_info` - 系统信息
**功能**: 获取系统状态和统计信息

## 🎛️ WebUI 管理界面

### 主要功能模块

#### 📊 智能仪表板
- **系统统计** - 知识库数量、知识条目总数、工作目录关联状态
- **MCP状态监控** - 实时显示MCP服务器运行状态
- **快速搜索** - 首页直接搜索知识库内容（可以选择工作目录和知识库）
- **快速操作** - 一键创建知识库、管理工作目录关联、MCP服务器控制

#### 🗄️ 知识库管理
- **知识库列表** - 显示所有知识库及其状态
- **创建知识库** - 可视化创建新知识库
- **知识库配置** - 修改名称、描述、优先级
- **知识统计** - 每个知识库的详细统计信息

#### 📁 工作目录管理
- claude code 正在工作的文件夹，也就是在哪里运行了claude命令。目的是不同的项目使用不同的知识库
- **默认目录关联* 用于通用查询,所有没有创建的工作目录用这个关联的知识库进行查询
- **关联管理** - 绑定/解绑知识库与工作目录，创建修改删除工作目录，mcp 根据工作目录查询对应的知识库。
             -  分页显示知识库，可以通过搜索查出来，点击关联/解绑
- **优先级设置** - 设置知识库在选中的目录的搜索优先级
- **批量操作** - 快速配置多个关联关系

#### 🔍 搜索配置
- **搜索模式** - 配置默认搜索模式（关键词/语义/混合）
- **AI后端配置** - 配置OpenAI API或本地模型和自定义api.  参数增加url, api_key, model 等配置参数
- **结果限制** - 设置默认搜索结果数量
- **缓存设置** - 配置搜索结果缓存策略

#### 🔧 系统控制
- **MCP服务器** - 启动/停止MCP服务器
- **MCP使用教程** - 配置和测试方案
- **数据库状态** - 显示数据库版本和健康状态
- **系统验证** - 一键验证系统完整性
- **日志查看** - 实时查看系统运行日志(webui 和 mcp_server)

## 📂 项目结构（更新后）

```
claude_code_kb_search/
├── 📁 database/                    # 统一数据库管理
│   ├── 📄 database_manager.py      # 核心数据库管理器
│   ├── 📄 init_database.py         # 数据库初始化脚本
│   ├── 📄 upgrade_database.py      # 数据库升级脚本
│   ├── 📁 schemas/                 # 数据库架构文件
│   │   └── 📄 current.sql          # 当前版本完整架构
│   ├── 📁 migrations/              # 版本迁移脚本
│   │   ├── 📄 migrate_to_1.0.sql   # 升级到v1.0
│   │   ├── 📄 migrate_to_2.0.sql   # 升级到v2.0
│   │   └── 📄 migrate_to_3.0.sql   # 升级到v3.0
│   └── 📁 data/                    # 初始数据
│       └── 📄 initial_data.sql     # 示例知识数据
├── 📄 knowledge_server.py          # 统一MCP服务器
├── 📄 multi_knowledge_base_manager.py # 多知识库管理器
├── 📄 search_config.py             # 搜索配置管理
├── 📄 ai_search.py                 # AI搜索引擎
├── 📁 webui/                       # WebUI管理界面
│   ├── 📄 app.py                   # 统一架构Flask应用
│   ├── 📁 templates/               # 更新的模板文件
│   │   ├── 📄 index.html           # 现代化仪表板
│   │   ├── 📄 knowledge_bases.html # 知识库管理
│   │   ├── 📄 workdir_relations.html # 工作目录管理
│   │   └── 📄 search_config.html   # 搜索配置
│   └── 📁 static/                  # 静态资源
├── 📄 /bin/launcher.bat                 # 智能启动器（推荐）
├── 📄 knowledge.db                 # 主管理数据库
├── 📄 DATABASE_ARCHITECTURE.md     # 新架构详细文档
├── 📄 test_unified_system.py       # 统一系统测试
└── 📄 requirements.txt             # 完整依赖列表
```

## 🔄 数据库更新机制

### 自动更新（推荐）
系统启动时会自动：
1. **检测当前版本** - 读取数据库版本信息
2. **比较目标版本** - 确定是否需要升级
3. **创建备份** - 升级前自动备份原数据
4. **执行迁移** - 按版本顺序执行迁移脚本
5. **验证结果** - 升级后验证数据完整性

### 手动升级
```bash
# 升级现有数据库到最新版本
python database/upgrade_database.py

# 全新初始化（首次安装）
python database/init_database.py

# 验证系统完整性
python test_unified_system.py
```

### 数据安全
- ✅ **自动备份** - 每次升级前自动创建时间戳备份
- ✅ **增量迁移** - 只执行必要的升级步骤
- ✅ **数据验证** - 升级后完整性检查
- ✅ **回滚能力** - 可从备份文件恢复

## 🛠️ 开发和扩展

### 添加新知识库
```python
from multi_knowledge_base_manager import get_multi_knowledge_base_manager

manager = get_multi_knowledge_base_manager()
kb_id = manager.create_knowledge_base("我的知识库", "专业领域知识")
```

### 批量导入知识
```python
# 向指定知识库添加知识
success = manager.add_knowledge(
    kb_id="your_kb_id",
    title="知识标题",
    content="详细内容",
    category="分类",
    tags=["标签1", "标签2"]
)
```

### 配置智能搜索
```python
from search_config import get_search_config

config = get_search_config()
config.ai_provider = "openai"  # 或 "local", "custom"
config.openai_api_key = "your-api-key"
config.default_search_mode = "hybrid"
config.save()
```

## 🚨 故障排除（更新版）

### 数据库相关问题

#### 🗄️ 重复数据库文件
**症状**: 发现多个 `knowledge.db` 文件

**解决方案**:
```bash
# 运行清理脚本（自动合并数据）
python scripts/utils/cleanup_databases_simple.py
```

#### 📊 版本不匹配
**症状**: 数据库版本过旧或升级失败

**解决方案**:
```bash
# 自动升级到最新版本
python database/verify_upgrade.py

# 查看当前版本
python -c "from database.database_manager import get_database_manager; print(get_database_manager().get_current_version('knowledge.db'))"
```

#### 🔧 数据库损坏
**症状**: SQLite错误或数据读取失败

**解决方案**:
```bash
# 验证所有知识库完整性
python test_unified_system.py

# 重新初始化（会创建备份）
python database/init_database.py --force
```

### WebUI 相关问题

#### 🌐 页面加载错误
**症状**: 浏览器显示模板错误或404

**解决方案**:
1. 确认使用的是新版 `webui/app.py`
2. 检查所有HTML模板文件是否存在
3. 重启WebUI服务

#### 📱 响应速度慢
**症状**: 页面加载或搜索响应慢

**解决方案**:
1. 检查知识库大小和数量
2. 启用搜索结果缓存
3. 优化搜索结果限制数量

### MCP服务器问题

#### 🔌 Claude Code连接失败
**症状**: Claude显示"无法连接到MCP服务器"

**解决方案**:
1. 确认MCP服务器正在运行
2. 检查配置文件路径是否使用新的 `knowledge_server.py`
3. 验证项目路径在配置中是否正确
4. 查看 `mcp_server.log` 详细错误信息

### 搜索功能问题

#### 🔍 搜索结果不准确
**症状**: 搜索返回不相关或过少结果

**解决方案**:
1. 检查工作目录是否正确关联知识库
2. 尝试不同的搜索模式（关键词/语义/混合）
3. 在WebUI中调整搜索配置
4. 验证知识库数据是否正确导入

## 💡 性能优化建议

### 数据库优化
- **索引优化** - 系统自动创建必要索引
- **定期维护** - 定期运行 `VACUUM` 清理数据库
- **批量操作** - 大量数据导入时使用事务

### 搜索优化
- **结果缓存** - 启用智能搜索结果缓存
- **并发限制** - 控制同时进行的搜索请求数
- **模式选择** - 根据需求选择最适合的搜索模式

### 系统优化
- **内存管理** - 监控长时间运行的服务内存使用
- **日志轮转** - 定期清理过大的日志文件
- **资源监控** - 使用WebUI监控系统资源状态

## 🔮 新功能预览

即将推出的功能（开发中）：
- 🧠 **向量搜索** - 基于embedding的高级语义搜索
- 📄 **文档导入** - 直接导入PDF、Word等文档
- 🔄 **实时同步** - 多客户端实时数据同步
- 🎨 **主题定制** - WebUI外观主题自定义
- 📊 **高级分析** - 知识库使用情况分析
- 🚀 **性能模式** - 高性能搜索和缓存策略

## 📞 技术支持

如果您遇到问题：

1. **查看日志** - WebUI中的实时日志查看
2. **运行测试** - `python test_unified_system.py` 进行系统检查
3. **查看文档** - `DATABASE_ARCHITECTURE.md` 详细技术文档
4. **系统验证** - WebUI中的"系统验证"功能

**升级提醒**: 如果您从旧版本升级，系统会自动处理数据迁移，但建议先备份重要数据。

---

## 🎯 总结

这个统一架构版本解决了原有系统的主要问题：
- ✅ **数据库混乱** → 统一管理，版本控制
- ✅ **多数据库问题** → 真正的多知识库架构
- ✅ **功能分散** → 统一API和管理界面
- ✅ **升级困难** → 自动检测和无缝升级
- ✅ **配置复杂** → 一键启动和智能配置

**立即开始**: 运行 `/bin/launcher.bat` 体验全新的统一知识库管理系统！ 🚀

### 捐赠方式
项目已集成捐赠功能，您可以通过以下方式支持我们：

- **微信支付**：
- <img src="donation/webchat_donation.jpg" alt="微信捐赠二维码" width="200">

## 📄 许可证
MIT License - 详见LICENSE文件