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搜索后端
- 结果缓存 - 提高重复查询性能
- 可配置限制 - 自定义返回结果数量
- 现代化界面 - 响应式设计，支持手机、平板访问
- 实时监控 - 系统控制、MCP服务器状态实时显示
- 知识库管理 - 创建、删除、配置知识库
- 工作目录管理 - 管理工作目录与知识库的关联关系
- 搜索配置 - 可视化配置智能搜索参数
- 智能启动 - 自动检查环境、初始化数据库
- 多种模式 - 完整启动、仅WebUI、仅MCP服务器
- 自动配置 - 智能生成Claude Code配置
- 依赖检查 - 自动检测和提示缺失的依赖
主数据库 (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 可用空间
# 完整安装（推荐）- 包含所有功能
pip install -r requirements.txt
# 最小化安装 - 基础功能
pip install -r requirements-minimal.txt
# 开发环境安装 - 包含测试工具
pip install -r requirements-dev.txt
# upgrade 升级到最新版本
pip install -r requirements.txt --upgrade-
双击运行启动器
/bin/launcher.bat # Windows # 或 ./bin//launcher.sh # Linux/macOS
-
选择启动模式
- 选项 1：完整启动 - WebUI + MCP服务器 + 自动配置
- 选项 2：仅启动 WebUI - 管理界面（开发模式）
- 选项 3：仅启动 MCP服务器 - 后台服务模式
-
访问管理界面
- 地址：http://127.0.0.1:5500
- 自动打开浏览器显示现代化管理界面
# 1. 初始化数据库（首次运行）
python scripts/setup/init_knowledge.py
# 2. 启动 WebUI 管理界面
cd webui
python app.py
# 3. 启动 MCP 服务器（另开终端）
python scripts/legacy/knowledge_server_old.py-
完整启动系统
/bin/launcher.bat # 选择选项 1 -
自动生成配置 - 系统会自动：
- 检测Claude Code配置文件位置
- 生成正确的MCP服务器配置
- 提示如何添加到Claude Code
-
确认配置 - 访问 WebUI 的"系统信息"页面确认配置正确
如果需要手动配置，将以下内容添加到Claude Code配置文件：
{
"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
功能: 在关联的知识库中搜索相关内容
参数:
query(必需): 搜索关键词limit(可选): 返回结果数量，默认10
示例: "搜索 Python 装饰器相关知识"
功能: 使用AI驱动的语义搜索
参数:
query(必需): 搜索查询search_mode(可选): 搜索模式 -keyword/semantic/hybridlimit(可选): 返回结果数量，默认5
示例: "用语义搜索找到关于异步编程的最佳实践"
功能: 向指定知识库添加新知识
参数:
kb_id(必需): 目标知识库IDtitle(必需): 知识标题content(必需): 知识内容category(可选): 分类tags(可选): 标签列表
示例: "添加关于Docker容器优化的运维知识"
功能: 显示所有可用知识库及其状态
功能: 显示当前工作目录关联的知识库
功能: 创建新的知识库
参数:
name(必需): 知识库名称description(可选): 知识库描述
功能: 获取系统状态和统计信息
- 系统统计 - 知识库数量、知识条目总数、工作目录关联状态
- 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 # 完整依赖列表
系统启动时会自动：
- 检测当前版本 - 读取数据库版本信息
- 比较目标版本 - 确定是否需要升级
- 创建备份 - 升级前自动备份原数据
- 执行迁移 - 按版本顺序执行迁移脚本
- 验证结果 - 升级后验证数据完整性
# 升级现有数据库到最新版本
python database/upgrade_database.py
# 全新初始化（首次安装）
python database/init_database.py
# 验证系统完整性
python test_unified_system.py- ✅ 自动备份 - 每次升级前自动创建时间戳备份
- ✅ 增量迁移 - 只执行必要的升级步骤
- ✅ 数据验证 - 升级后完整性检查
- ✅ 回滚能力 - 可从备份文件恢复
from multi_knowledge_base_manager import get_multi_knowledge_base_manager
manager = get_multi_knowledge_base_manager()
kb_id = manager.create_knowledge_base("我的知识库", "专业领域知识")# 向指定知识库添加知识
success = manager.add_knowledge(
kb_id="your_kb_id",
title="知识标题",
content="详细内容",
category="分类",
tags=["标签1", "标签2"]
)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 文件
解决方案:
# 运行清理脚本（自动合并数据）
python scripts/utils/cleanup_databases_simple.py症状: 数据库版本过旧或升级失败
解决方案:
# 自动升级到最新版本
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错误或数据读取失败
解决方案:
# 验证所有知识库完整性
python test_unified_system.py
# 重新初始化（会创建备份）
python database/init_database.py --force症状: 浏览器显示模板错误或404
解决方案:
- 确认使用的是新版
webui/app.py - 检查所有HTML模板文件是否存在
- 重启WebUI服务
症状: 页面加载或搜索响应慢
解决方案:
- 检查知识库大小和数量
- 启用搜索结果缓存
- 优化搜索结果限制数量
症状: Claude显示"无法连接到MCP服务器"
解决方案:
- 确认MCP服务器正在运行
- 检查配置文件路径是否使用新的
knowledge_server.py - 验证项目路径在配置中是否正确
- 查看
mcp_server.log详细错误信息
症状: 搜索返回不相关或过少结果
解决方案:
- 检查工作目录是否正确关联知识库
- 尝试不同的搜索模式（关键词/语义/混合）
- 在WebUI中调整搜索配置
- 验证知识库数据是否正确导入
- 索引优化 - 系统自动创建必要索引
- 定期维护 - 定期运行
VACUUM清理数据库 - 批量操作 - 大量数据导入时使用事务
- 结果缓存 - 启用智能搜索结果缓存
- 并发限制 - 控制同时进行的搜索请求数
- 模式选择 - 根据需求选择最适合的搜索模式
- 内存管理 - 监控长时间运行的服务内存使用
- 日志轮转 - 定期清理过大的日志文件
- 资源监控 - 使用WebUI监控系统资源状态
即将推出的功能（开发中）：
- 🧠 向量搜索 - 基于embedding的高级语义搜索
- 📄 文档导入 - 直接导入PDF、Word等文档
- 🔄 实时同步 - 多客户端实时数据同步
- 🎨 主题定制 - WebUI外观主题自定义
- 📊 高级分析 - 知识库使用情况分析
- 🚀 性能模式 - 高性能搜索和缓存策略
如果您遇到问题：
- 查看日志 - WebUI中的实时日志查看
- 运行测试 -
python test_unified_system.py进行系统检查 - 查看文档 -
DATABASE_ARCHITECTURE.md详细技术文档 - 系统验证 - WebUI中的"系统验证"功能
升级提醒: 如果您从旧版本升级，系统会自动处理数据迁移，但建议先备份重要数据。
这个统一架构版本解决了原有系统的主要问题：
- ✅ 数据库混乱 → 统一管理，版本控制
- ✅ 多数据库问题 → 真正的多知识库架构
- ✅ 功能分散 → 统一API和管理界面
- ✅ 升级困难 → 自动检测和无缝升级
- ✅ 配置复杂 → 一键启动和智能配置
立即开始: 运行 /bin/launcher.bat 体验全新的统一知识库管理系统！ 🚀
项目已集成捐赠功能，您可以通过以下方式支持我们：
- 微信支付：
-
MIT License - 详见LICENSE文件