Cowork Semantic Search

协同语义搜索

](https://github.com/ZhuBit/cowork-semantic-search/stargazers)   

如果你觉得这很有用，可以考虑给它一个⭐ — 它帮助其他人发现这个项目。

文档的本地语义搜索。没有API密钥。没有云。适用于任何MCP客户端。

demo

______________________________________________________________________

为什么

AI编码工具功能强大，但在处理本地文件时存在盲点：

• 冻结的知识 --训练数据有一个截止点。您最新的报告、笔记和合同在模型的世界中不存在。
• 上下文窗口限制 --您无法将500个文档粘贴到提示中。
• 无跨文件搜索 --你的AI工具可以一次读取一个文件，但无法在整个文档库中搜索相关部分。

这个插件弥合了这一差距。它将您的本地文档索引到一个小型、快速的矢量数据库中。当你问一个问题时，它只检索相关的部分——这样你的人工智能工具就可以用你的实际数据来回答。

Your documents --> chunked --> embedded --> local vector DB
                                                 |
         Your question --> embedded --> similarity search --> relevant chunks --> AI answers

特性

• 完全离线 --一次性模型下载（约120MB），然后无需网络调用。没有数据离开你的机器。
• 增量索引 --SHA-256内容哈希。只有更改的文件才会被重新处理。重新索引1000个文件，其中3个文件发生了更改，需要几秒钟的时间。
• 多语言 --原生处理50多种语言。用一种语言搜索，用另一种语言查找结果。
• 混合搜索 --通过互易秩融合将语义相似性与全文关键字搜索相结合。捕捉纯向量搜索遗漏的内容。
• 多种格式 --txt、md、pdf、docx、pptx、csv开箱即用。
• 任何MCP客户端 --适用于Claude Code、Cursor、Windsurf、Cline和任何其他MCP兼容工具。
• 零基础设施 --LanceDB将所有内容都存储为本地文件。没有服务器，没有Docker，没有数据库需要管理。

支持格式

快速开始

1.安装

git clone https://github.com/ZhuBit/cowork-semantic-search.git
cd cowork-semantic-search
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

2.配置您的MCP客户端

将服务器添加到MCP客户端的配置中。用你自己的路径替换。

Claude Code -- .mcp.json in your project root

{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/cowork-semantic-search",
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}

Cursor -- .cursor/mcp.json in your project root or ~/.cursor/mcp.json globally

{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}

Windsurf -- ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}

Cline -- MCP Servers settings in the Cline VS Code extension

打开临床>MCP服务器图标>配置>高级MCP设置，然后添加：

{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}

3.重新启动MCP客户端并继续

“为~/documents/projects中的所有文档建立索引”

“搜索‘季度收入报告’”

首先运行下载嵌入模型（约120MB），然后一切都离线运行。

示例：搜索黑曜石金库

如果你在黑曜石（或任何标记文件文件夹）中做笔记，这个插件会把你的人工智能工具变成你知识库的搜索引擎。

You: "Index my vault at ~/Documents/ObsidianVault"
AI:  Indexed 847 files -> 3,291 chunks in 42s

You: "What did I write about API rate limiting?"
AI:  Found 6 relevant chunks across 3 files:
       - notes/backend/rate-limiting-strategies.md
       - projects/acme-api/design-decisions.md
       - daily/2025-11-03.md
       ...

You: "Find anything about the client meeting last November, use hybrid search"
AI:  Found 4 results using hybrid search (vector + keyword):
       - meetings/2025-11-12-acme-kickoff.md
       - daily/2025-11-12.md
       ...

适用于PDF、Word文档、PowerPoint和CSV，只需将其指向文件夹即可。

工具

运作原理

1. 解析 --从每个文档中提取文本，保留结构（页面、幻灯片）
2. 块 --拆分为~400个字符的重叠部分以进行精确检索
3. 嵌入 --使用以下公式将每个块转换为384维向量 paraphrase-multilingual-MiniLM-L12-v2
4. 商店 --将块+向量保存在LanceDB数据库中（本地文件，无需服务器）
5. 搜索 --嵌入您的查询，通过余弦相似度查找最近的块，可选择通过RRF与全文关键字搜索相结合

高级用法

Use as a Python library

from server.indexer import index_folder
from server.search import semantic_search

# Index a folder
result = index_folder("/path/to/docs")
print(f"{result['files_indexed']} files -> {result['total_chunks']} chunks")

# Search
results = semantic_search("project deadline", mode="hybrid")
for r in results["results"]:
    print(f"  {r['file_name']}: {r['text'][:100]}...")

建筑

server/
  main.py       # MCP server + tool definitions
  parsers.py    # Per-format text extraction
  chunker.py    # Text splitting with metadata
  indexer.py    # Discovery, hashing, embedding pipeline
  store.py      # LanceDB vector store + FTS + hybrid search
  search.py     # Query embedding + search orchestration

发展

source .venv/bin/activate
pytest tests/ -v

56个测试，涵盖解析器、分块、索引、搜索和MCP工具集成。

欢迎投稿——打开问题或提交PR。

路线图

• ONNX运行时实现更快的嵌入（删除PyTorch依赖关系）
• 通过工具参数可配置块大小和重叠
• 多文件夹命名索引
• 元数据过滤（日期范围、标签、自定义字段）
• 监视模式（文件更改时自动重新索引）

支持

如果这对你有用，考虑给它一个⭐ — 它帮助其他人找到项目。

许可证

AGPL-3.0——免费使用、修改和自托管。如果您将其作为网络服务提供，则必须共享源代码。看 许可证 了解详情。