# 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` 体验全新的统一知识库管理系统! 🚀 ### 捐赠方式 项目已集成捐赠功能,您可以通过以下方式支持我们: - **微信支付**: - 微信捐赠二维码 ## 📄 许可证 MIT License - 详见LICENSE文件