{"id":35189594,"url":"https://github.com/dtsola/xiaoyaosearch","last_synced_at":"2026-04-01T16:50:11.240Z","repository":{"id":330918919,"uuid":"1094171135","full_name":"dtsola/xiaoyaosearch","owner":"dtsola","description":"小遥搜索，听懂你的话、看懂你的图，用AI找到本地任何文件。让搜索像聊天一样简单。XiaoyaoSearch: Understands your words, reads your images, finds any local file with AI. Making search as easy as chatting.","archived":false,"fork":false,"pushed_at":"2026-03-24T02:00:42.000Z","size":88856,"stargazers_count":1178,"open_issues_count":0,"forks_count":105,"subscribers_count":59,"default_branch":"main","last_synced_at":"2026-03-24T13:49:27.168Z","etag":null,"topics":["agent-skills","ai-search","document-search","file-search","local-search","mcp","multimodal-ai","natural-language","productivity","semantic-search"],"latest_commit_sha":null,"homepage":"https://project.xiaoyaosai.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dtsola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T10:58:03.000Z","updated_at":"2026-03-24T12:16:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dtsola/xiaoyaosearch","commit_stats":null,"previous_names":["dtsola/xiaoyaosearch"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/dtsola/xiaoyaosearch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtsola%2Fxiaoyaosearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtsola%2Fxiaoyaosearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtsola%2Fxiaoyaosearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtsola%2Fxiaoyaosearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dtsola","download_url":"https://codeload.github.com/dtsola/xiaoyaosearch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtsola%2Fxiaoyaosearch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-search","document-search","file-search","local-search","mcp","multimodal-ai","natural-language","productivity","semantic-search"],"created_at":"2025-12-29T05:31:54.838Z","updated_at":"2026-04-01T16:50:11.233Z","avatar_url":"https://github.com/dtsola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 小遥搜索 XiaoyaoSearch\n\n[English Version](README_EN.md) | 简体中文\n\n![小遥搜索](docs/产品文档/产品截图/小遥搜索.png)\n\n## 📖 项目简介\n\n![小遥搜索](docs/产品文档/logo/logo_256x256.png)\n\n小遥搜索是一款专为知识工作者、内容创作者和技术开发者设计的跨平台本地桌面应用（Windows/MacOS/Linux）。通过集成的AI模型，支持语音输入（30秒内）、文本输入、图片输入等多种方式，将用户的查询转换为语义进行智能搜索，实现对本地文件的深度检索。\n\n## ⭐️ 重要说明\n- 本项目非商业使用完全免费，允许修改和分发（需保留版权声明和协议）；商业目的需授权，详细见[小遥搜索软件授权协议](LICENSE)\n- 本项目完全通过Vibe Coding实现，提供所有源码及开发文档（上下文）供大家交流学习\n  ![开发文档](docs/产品文档/产品截图/开发文档.png)\n\n## 作者介绍\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/产品文档/产品截图/author-avatar.jpg\" alt=\"dtsola\" width=\"120\" height=\"120\" style=\"border-radius: 50%;\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003edtsola\u003c/b\u003e — IT架构师 | 一人公司实践者\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  🌐 \u003ca href=\"https://www.dtsola.com\"\u003e个人站点\u003c/a\u003e \u0026nbsp;|\u0026nbsp;\n  📺 \u003ca href=\"https://space.bilibili.com/736015\"\u003eB站\u003c/a\u003e \u0026nbsp;|\u0026nbsp;\n  💬 微信：dtsola（技术交流 | 商务合作）\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/产品文档/产品截图/个人二维码.png\" alt=\"微信二维码\" width=\"120\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"docs/产品文档/产品截图/开发者交流群图.png\" alt=\"开发者交流群\" width=\"120\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"docs/产品文档/产品截图/用户交流群图.png\" alt=\"用户交流群\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csmall\u003e微信联系 \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; 开发者交流群 \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; 用户交流群\u003c/small\u003e\n\u003c/p\u003e\n\n### ✨ 核心特性\n\n- **🎤 多模态输入**：支持语音录音、文本输入、图片上传\n- **🔍 深度检索**：支持视频（mp4、avi）、音频（mp3、wav）、文档（txt、markdown、office、pdf）的内容和文件名搜索\n- **🧠 AI增强**：集成BGE-M3、FasterWhisper、CN-CLIP、OLLAMA等先进AI模型\n  - **☁️ 云端大模型**：支持OpenAI/DeepSeek/阿里云等兼容API，与本地模型自由切换（v1.3.0）\n  - **☁️ 云端嵌入模型**：支持OpenAI/DeepSeek/阿里云等嵌入API，提升搜索质量（v1.6.0）\n- **⚡ 高性能**：基于Faiss向量搜索和Whoosh全文搜索的混合检索架构\n- **🔒 隐私可控**：本地运行默认数据不上传，支持云端API选项，性能与隐私权衡由您选择\n- **🎨 现代界面**：基于Electron + Vue 3 + TypeScript的现代化桌面应用\n- **🤖 AI生态集成**：\n  - **MCP 服务器支持**：支持 Model Context Protocol，可被 Claude Desktop 连接进行本地文件智能搜索（v1.4.0）\n  - **Agent Skills 支持**：为 Claude Code、VS Code、Cursor 等 AI 助手提供标准化工具调用能力（v1.5.0）\n\n## 📖 核心界面\n\n### 搜索界面\n\n#### 主界面\n![搜索界面](docs/产品文档/产品截图/搜索界面-主界面.png)\n\n#### 通过文本搜索\n![通过文本搜索](docs/产品文档/产品截图/搜索界面-文本搜索.png)\n\n#### 通过语音搜索\n![通过语音搜索](docs/产品文档/产品截图/搜索界面-语音搜索.png)\n\n#### 通过图片搜索\n![通过图片搜索](docs/产品文档/产品截图/搜索界面-图片搜索.png)\n\n### 索引管理界面\n![索引管理界面](docs/产品文档/产品截图/索引管理界面.png)\n\n### 设置界面\n![设置界面](docs/产品文档/产品截图/设置界面.png)\n\n## 🏗️ 技术架构\n\n### 系统架构图\n\n![系统架构](docs/产品文档/产品截图/系统架构.png)\n\n### 技术栈\n\n**前端技术**\n- **框架**: Electron + Vue 3 + TypeScript\n- **UI库**: Ant Design Vue\n- **状态管理**: Pinia\n- **构建工具**: Vite\n\n**后端技术**\n- **框架**: Python 3.10 + FastAPI + Uvicorn\n- **AI模型**: BGE-M3 + FasterWhisper + CN-CLIP + Ollama\n- **搜索引擎**: Faiss (向量搜索) + Whoosh (全文搜索)\n- **数据库**: SQLite + 索引文件\n\n### 项目结构\n\n```\nxiaoyaosearch/\n├── backend/                        # 后端服务 (Python FastAPI)\n│   ├── app/                       # 应用核心代码\n│   │   ├── api/                   # API路由层\n│   │   ├── core/                  # 核心配置\n│   │   ├── models/                # 数据模型\n│   │   ├── services/              # 业务服务\n│   │   ├── schemas/               # 数据模式\n│   │   └── utils/                 # 工具函数\n│   ├── requirements.txt           # Python依赖\n│   ├── main.py                   # 应用入口\n│   └── .env                      # 环境变量\n├── frontend/                      # 前端应用 (Electron + Vue3)\n│   ├── src/                      # 源代码\n│   │   ├── main/                 # Electron主进程\n│   │   ├── preload/              # 预加载脚本\n│   │   └── renderer/             # Vue渲染进程\n│   ├── out/                      # 构建输出\n│   ├── dist-electron/            # 打包输出\n│   ├── resources/                # 应用资源\n│   ├── package.json              # Node.js依赖\n│   └── electron-builder.yml      # 打包配置\n├── docs/                          # 项目文档\n│   ├── 00-mrd.md                  # 市场调研\n│   ├── 01-prd.md                  # 产品需求\n│   ├── 02-原型.md                 # 产品原型\n│   ├── 03-技术方案.md             # 技术方案\n│   ├── 04-开发任务清单.md         # 开发任务\n│   ├── 05-开发排期表.md           # 开发排期\n│   ├── 开发进度.md                # 进度跟踪\n│   ├── 接口文档.md                # API文档\n│   ├── 数据库设计文档.md          # 数据库设计\n│   └── 高保真原型/                # UI原型\n├── data/                          # 数据目录\n│   ├── database/                  # SQLite数据库\n│   ├── indexes/                   # 搜索索引\n│   │   ├── faiss/                 # 向量索引\n│   │   └── whoosh/                # 全文索引\n│   ├── models/                   # 模型文件\n│   └── logs/                   # 日志文件\n├── .claude/                       # Claude助手配置\n├── LICENSE                        # 软件授权协议（中文版）\n├── LICENSE_EN                     # 软件授权协议（英文版）\n├── README.md                      # 项目说明（中文版）\n└── README_EN.md                   # 项目说明（英文版）\n```\n\n## 🚀 快速开始\n\n### 方式一：整合包部署（推荐普通用户）\n\n\u003e **适用人群**：非开发者、希望快速体验小遥搜索的用户\n\u003e **支持平台**：仅支持 Windows\n\u003e **部署难度**：⭐ 简单（一键安装）\n\n#### 下载整合包\n\n从百度网盘下载最新的 Windows 整合包：\n- 链接：https://pan.baidu.com/s/1lDaWjMCRXIT-Sqx9UFjerg?pwd=37ed\n- 提取码：37ed\n\n请选择最新版本下载（如 `XiaoyaoSearch-Windows-v1.1.1.zip`）\n\n#### 安装步骤\n\n**1. 解压整合包**\n\n将下载的压缩包解压到任意目录（建议不要包含中文路径）\n\n**2. 运行环境准备脚本**\n\n双击运行 `scripts/setup.bat`，脚本会自动完成以下操作：\n- 解压 Python 嵌入式运行时\n- 安装后端 Python 依赖\n- 安装前端 Node 依赖\n- 生成配置文件\n- 创建数据目录\n\n\u003e **RTX 50 系显卡用户**：如果您使用 RTX 50 系显卡，请运行 `scripts/setup_rtx50显卡.bat`，该脚本会安装支持 CUDA 12.8 的 PyTorch 版本以获得最佳性能。\n\n**3. 安装 Ollama**\n\n双击运行 `runtime\\ollama\\OllamaSetup.exe`，按提示完成安装。\n\n安装完成后，打开命令行运行：\n```bash\nollama serve\nollama pull qwen2.5:1.5b\n```\n\n**4. 下载 AI 模型**\n\n从百度网盘下载默认模型：\n- 链接：https://pan.baidu.com/s/1jRcTztvjf8aiExUh6oayVg\n- 提取码：ycr5\n\n将模型解压到对应目录：\n- `data\\models\\embedding\\BAAI\\bge-m3\\` - 嵌入模型\n- `data\\models\\cn-clip\\` - 视觉模型\n- `data\\models\\faster-whisper\\` - 语音识别模型\n\n**5. 启动应用**\n\n双击运行 `scripts/startup.bat`，脚本会：\n- 启动后端服务\n- 启动前端服务\n\n**详细文档**：[整合包部署指南](docs/部署文档/整合包部署指南.md)\n\n---\n\n### 方式二：开发者部署\n\n\u003e **适用人群**：开发者、希望参与项目贡献的用户\n\u003e **支持平台**：Windows / macOS / Linux\n\u003e **部署难度**：⭐⭐⭐ 需要开发环境\n\n#### 环境要求\n\n- **操作系统**: Windows / macOS / Linux\n- **Python**: 3.10.11+（https://www.python.org/downloads/）\n- **Node.js**: 21.x+（https://nodejs.org/en/download）\n- **内存**: 建议16GB 以上\n- **显卡**: 建议RTX3060 6GB以上\n\n#### 安装步骤\n\n**1. 克隆项目**\n```bash\ngit clone https://github.com/dtsola/xiaoyaosearch.git\ncd xiaoyaosearch\n```\n\n**2. 后端部署**\n\n```shell\n# 进入后端目录\ncd backend\n\n# 安装依赖包（默认CPU版本的推理引擎）\npip install -r requirements.txt\n\n# 安装faster-whisper\npip install faster-whisper\n\n# 启用CUDA（可选，注意：cuda版本需根据环境确定）\npip uninstall torch torchaudio torchvision\n\n# RTX 40 系及更早显卡（CUDA 12.1）\npip install torch==2.1.0+cu121 torchaudio==2.1.0+cu121 torchvision==0.16.0+cu121 --index-url https://download.pytorch.org/whl/cu121\n\n# RTX 50 系显卡（CUDA 12.8）\npip install torch==2.10.0+cu128 torchaudio==2.10.0+cu128 torchvision==0.25.0+cu128 --index-url https://download.pytorch.org/whl/cu128\n\n```\n\n**安装ffmpeg**:\nhttps://ffmpeg.org/download.html\n\n**安装ollama**:\nhttps://ollama.com/\n\n**配置 `.env` 文件**:\n```env\n\n# 数据配置\nFAISS_INDEX_PATH=../data/indexes/faiss\nWHOOSH_INDEX_PATH=../data/indexes/whoosh\nDATABASE_PATH=../data/database/xiaoyao_search.db\n\n# API配置\nAPI_HOST=127.0.0.1\nAPI_PORT=8000\nAPI_RELOAD=true\n\n# 日志配置\nLOG_LEVEL=info\nLOG_FILE=../data/logs/app.log\n```\n\n**准备模型**:\n系统默认模型说明：\n- ollama：qwen2.5:1.5b\n- 嵌入模型：BAAI/bge-m3\n- 语音识别模型：Systran/faster-whisper-base\n- 视觉模型：OFA-Sys/chinese-clip-vit-base-patch16\n\n注意：建议先准备默认模型，先成功启动应用后，再更换模型。\n\nollama模型：\nollama pull qwen2.5:1.5b （根据情况自行选择）\n\n所有模型下载地址：（百度盘）\n链接: https://pan.baidu.com/s/1jRcTztvjf8aiExUh6oayVg?pwd=ycr5 提取码: ycr5 \n\n嵌入模型：\n- 模型根目录：data/models/embedding\n- 将下载的模型直接解压放入到根目录即可，以下是对应关系\n  - data/models/embedding/BAAI/bge-m3\n  - data/models/embedding/BAAI/bge-small-zh\n  - data/models/embedding/BAAI/bge-large-zh\n\n语音识别模型：\n- 模型根目录：data/models/faster-whisper\n- 将下载的模型直接解压放入到根目录即可，以下是对应关系\n  - data/models/faster-whisper/Systran/faster-whisper-base\n  - data/models/faster-whisper/Systran/faster-whisper-small\n  - data/models/faster-whisper/Systran/faster-whisper-medium\n  - data/models/faster-whisper/Systran/faster-whisper-large-v3\n\n视觉模型：\n- 模型根目录：data/models/cn-clip\n- 将下载的模型直接解压放入到根目录即可，以下是对应关系\n  - data/models/cn-clip/OFA-Sys/chinese-clip-vit-base-patch16\n  - data/models/cn-clip/OFA-Sys/chinese-clip-vit-large-patch14\n\n\n\n**启动后端服务**:\n```shell\n# 使用内置配置启动\npython main.py\n\n# 或使用uvicorn启动\nuvicorn main:app --host 127.0.0.1 --port 8000 --reload\n```\n\n#### 3. 前端部署\n\n```shell\n# 进入前端目录\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n---\n\n## 🔄 版本升级指南\n\n当需要升级到新版本时，请参考 [版本升级指南](docs/技术文档/版本升级指南.md)，轻松保留您的索引数据和配置。\n\n---\n\n## 🤝 如何共享代码\n\n感谢你对小遥搜索的关注！我们欢迎任何形式的贡献，无论是代码、文档、Bug 修复还是新功能建议。\n\n### 贡献方式\n\n#### 方式一：提交 Pull Request（推荐）\n\n**步骤 1：Fork 项目**\n1. 访问 [xiaoyaosearch](https://github.com/dtsola/xiaoyaosearch) 仓库\n2. 点击右上角的 \"Fork\" 按钮，将项目 Fork 到你的 GitHub 账户\n\n**步骤 2：克隆到本地**\n```bash\ngit clone https://github.com/\u003c你的用户名\u003e/xiaoyaosearch.git\ncd xiaoyaosearch\n```\n\n**步骤 3：创建功能分支**\n```bash\ngit checkout -b feature/你的功能名称\n# 或\ngit checkout -b fix/问题描述\n```\n\n**步骤 4：进行开发**\n- 按照项目代码规范进行开发\n- 确保代码有适当的注释\n- 运行测试确保功能正常\n\n**步骤 5：提交代码**\n```bash\ngit add .\ngit commit -m \"feat(scope): 简洁描述你的改动\"\n```\n提交格式规范：\n- `feat`: 新功能\n- `fix`: Bug 修复\n- `docs`: 文档更新\n- `style`: 代码格式调整\n- `refactor`: 代码重构\n- `perf`: 性能优化\n- `test`: 测试相关\n- `chore`: 构建/工具链相关\n\n**步骤 6：推送到 GitHub**\n```bash\ngit push origin feature/你的功能名称\n```\n\n**步骤 7：创建 Pull Request**\n1. 访问你 Fork 的仓库页面\n2. 点击 \"Compare \u0026 pull request\" 按钮\n3. 填写 PR 描述：\n   - 标题：简洁说明改动内容\n   - 描述：详细说明改动原因、实现方式、测试结果\n4. 等待维护者审核\n\n#### 方式二：提交 Issue\n\n如果你发现了 Bug 或有功能建议：\n1. 访问 [Issues](https://github.com/dtsola/xiaoyaosearch/issues) 页面\n2. 点击 \"New Issue\"\n3. 选择合适的 Issue 模板\n4. 详细描述问题或建议\n\n### 代码规范\n\n#### 前端规范\n- 组件命名：PascalCase（如 `SearchPanel.vue`）\n- 变量/函数：camelCase（如 `searchResults`）\n- 常量：UPPER_SNAKE_CASE（如 `MAX_FILE_SIZE`）\n- 代码注释：使用中文\n\n#### 后端规范\n- 文件命名：snake_case（如 `search_service.py`）\n- 类名：PascalCase（如 `SearchService`）\n- 函数/变量：snake_case（如 `search_files`）\n- 常量：UPPER_SNAKE_CASE（如 `MAX_RESULTS`）\n- 代码注释：使用中文\n\n### 贡献指南\n\n- ✅ 遵循项目的代码规范\n- ✅ 保持代码简洁，避免过度设计\n- ✅ 添加适当的错误处理\n- ✅ 确保代码有适当的测试\n- ✅ 更新相关文档\n\n### 获取帮助\n\n- 💬 微信：dtsola（请备注 \"小遥搜索贡献\"）\n- 📧 邮件：通过官网 https://www.dtsola.com 联系\n- 📺 B站：https://space.bilibili.com/736015\n\n### 贡献者权益\n\n- 📝 你的名字将出现在项目贡献者列表中\n- 🌟 你的改动将帮助成千上万的用户\n- 🤝 加入独立开发者社区，交流学习\n- 🎁 优秀贡献者可获得项目周边礼品\n\n---\n\n**让我们一起打造更好的本地搜索体验！** 🚀\n\n## 产品路线图\n[产品路线图](ROADMAP.md)\n\n## 数据源插件列表\n\n小遥搜索支持**插件化架构**，可通过插件扩展多种数据源：\n\n### 支持的数据源类型\n\n| 类型 | 说明 | 状态 |\n|------|------|------|\n| 📁 本地文件 | 系统内置，无需配置 | ✅ 已实现 |\n| ☁️ 语雀 | 阿里语雀知识库 | ✅ 已实现 |\n| ☁️ 飞书 | 飞书文档 | ✅ 已实现 |\n| ☁️ Notion | Notion 笔记 | 📋 计划中 |\n| 🔗 GitHub | 代码仓库和 Wiki | 📋 计划中 |\n| 🔗 GitLab | GitLab 代码仓库 | 📋 计划中 |\n\n### 完整列表\n\n查看完整的数据源插件列表（13种类型）：\n\n**📖 [数据源插件列表](docs/技术文档/数据源插件列表.md)** | [English Version](docs/技术文档/数据源插件列表_EN.md)\n\n### 开发插件\n\n想要开发新的数据源插件？\n\n**📖 [插件开发文档](docs/技术文档/插件开发文档.md)**\n\n---\n\n## 🔥 MCP 服务器支持\n\n小遥搜索现已支持 **Model Context Protocol (MCP)**，可被 Claude Desktop 等 AI 应用连接，进行本地文件智能搜索。\n\n### 什么是 MCP？\n\nMCP (Model Context Protocol) 是 Anthropic 推出的开源协议，允许 AI 应用（如 Claude Desktop）连接到本地数据源。通过 MCP，Claude 可以直接搜索和访问您的本地文件，提供更智能的问答和帮助。\n\n### Agent Skills 支持\n\n小遥搜索现已支持 **Agent Skills**，为 Claude Code、VS Code、Cursor 等 AI 助手提供标准化的 MCP 工具调用能力。\n\n**安装 Skill**：\n\n```bash\n# 项目级别\ncp -r skills/ .claude/skills/\n\n# 或全局级别\ncp -r skills/ ~/.claude/skills/\n```\n\n安装后，AI 助手可自动发现小遥搜索的 MCP 工具，并提供正确使用指导。\n\n### MCP 客户端配置\n\n小遥搜索 MCP 服务器使用 **HTTP 传输协议**，任何支持 HTTP MCP 的客户端都可以连接。\n\n#### Claude Code CLI 配置\n\n官方命令行工具，快速配置：\n\n```bash\n# 添加 HTTP MCP 服务器\nclaude mcp add --transport http xiaoyao-search http://127.0.0.1:8000/mcp\n\n# 检查 MCP 是否添加成功（确保 MCP 已经启动的前提下，运行下面命令）\nclaude mcp list\n```\n\n#### 其他支持 MCP 的客户端\n\n任何支持 MCP 协议的客户端都可以连接到：`http://127.0.0.1:8000/mcp`\n\n**基本配置模板**：\n\n```json\n{\n  \"name\": \"xiaoyao-search\",\n  \"url\": \"http://127.0.0.1:8000/mcp\",\n  \"type\": \"sse\"\n}\n```\n\n**常用客户端配置示例**：\n\n- **Cline (VSCode 插件)**: 在 VSCode 设置中搜索 `cline.mcpServers`，添加上述配置\n- **Cursor**: 在 Cursor 设置的 MCP 服务器配置中添加上述配置\n- **其他 MCP 客户端**: 参考客户端文档，使用 SSE 传输方式连接\n\n### 支持的搜索工具\n\n| 工具名称 | 说明 | AI 模型 |\n|---------|------|---------|\n| semantic_search | 语义搜索，支持自然语言查询理解 | BGE-M3 |\n| fulltext_search | 全文搜索，支持精确关键词匹配和中文分词 | Whoosh |\n| voice_search | 语音搜索，支持语音输入转文本后搜索 | FasterWhisper |\n| image_search | 图像搜索，支持图片上传查找相似内容 | CN-CLIP |\n| hybrid_search | 混合搜索，结合语义和全文搜索的优势 | BGE-M3 + Whoosh |\n\n### 使用示例\n\n配置完成后，您可以在 Claude Desktop 中进行以下操作：\n\n**语义搜索**：\n```\n用户：帮我找一下关于异步编程的文档\nClaude：[调用 semantic_search 工具] 找到 5 个相关文档...\n```\n\n**全文搜索**：\n```\n用户：搜索包含 \"async def\" 的代码文件\nClaude：[调用 fulltext_search 工具] 找到 3 个代码文件...\n```\n\n**图像搜索**：\n```\n用户：[上传图片] 找找类似的图表\nClaude：[调用 image_search 工具] 找到 2 个相似的图表...\n```\n\n### 验证 MCP 连接\n\n访问健康检查端点验证 MCP 服务状态：\n```bash\ncurl http://127.0.0.1:8000/mcp/health\n```\n\n返回示例：\n```json\n{\n  \"status\": \"enabled\",\n  \"server\": \"fastmcp\",\n  \"tools_count\": 5,\n  \"tools\": [\"semantic_search\", \"fulltext_search\", \"voice_search\", \"image_search\", \"hybrid_search\"]\n}\n```\n\n### 配置选项\n\n在 `backend/.env` 中配置 MCP 服务：\n\n```bash\n# MCP 服务器配置\nMCP_SSE_ENABLED=true              # 是否启用 MCP SSE 服务\nMCP_SERVER_NAME=xiaoyao-search    # 服务器名称\nMCP_DEFAULT_LIMIT=20              # 默认结果数量\nMCP_DEFAULT_THRESHOLD=0.5         # 默认相似度阈值\nMCP_VOICE_ENABLED=true            # 是否启用语音搜索\n```\n\n### 技术实现\n\n- **协议实现**：使用 [fastmcp](https://github.com/PrefectHQ/fastmcp) 框架\n- **传输方式**：HTTP SSE (Server-Sent Events)\n- **架构模式**：FastAPI 集成，共享 AI 模型和搜索服务\n- **内存优化**：单一进程，模型只加载一次，节省 4-6GB 内存\n\n### 详细文档\n\n- [MCP PRD](docs/特性开发/mcp/mcp-01-prd.md) - 产品需求文档\n- [MCP 技术方案](docs/特性开发/mcp/mcp-03-技术方案.md) - 技术实现方案\n- [MCP 官方文档](https://modelcontextprotocol.io/) - MCP 协议规范\n\n---\n\n## 项目贡献者\n感谢以下人员为本项目做出的贡献：\n- [@jidingliu](https://github.com/jidingliu) - 提交代码及项目宣传","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtsola%2Fxiaoyaosearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdtsola%2Fxiaoyaosearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtsola%2Fxiaoyaosearch/lists"}