内容
Seek 引擎
[](https://github.com/MunasheChitima/findandseek-engine/actions/workflows/test.yml)
[](LICENSE.md)
[](pyproject.toml)
一个本地优先的文件智能引擎。它索引您机器上的文档、代码和电子邮件 — 在摄入时使用设备上的模型理解它们 — 并通过 [MCP](https://modelcontextprotocol.io) 将该内存暴露给任何 AI 助手。没有任何内容离开您的机器：模型在本地运行（在 Apple 硅芯片上为进程内 MLX，在其他地方为本地 [O](https://ollama.com) 守护进程），索引是本地 SQLite 数据库，并且没有云组件。
将它指向您的文件夹，连接 Claude Desktop（或任何 MCP 客户端），并询问有关您创建的任何问题。
## 它是什么样子
> **您：** 水管工在三月份向我收取了多少费用？
>
> **助手：** *(调用 `search_files`，获取一个结果卡)*
> 485 美元 — `invoice_plumber_march.pdf`，3 月 15 日，Joe's Plumbing Services，用于紧急管道维修。
助手没有读取您的文件夹。它获取了一个紧凑的卡片 — 文件名、文档类型、一行锚点、主要事实、置信区间 — 这就足够了。当一张卡片 *不够* 时，它会为相关段落调用 `get_file_context`，而不是整个文件。
这是一句话的设计：**在摄入时理解每个文件，以便以后检索永远是廉价的。** 传统的代理程序会对每个问题进行 grep 和读取整个文件，其上下文和账单会随着工作大小的增加而增长。在 2,500 个文件的语料库中（三个完整的重复，每个臂运行到完成），与基线相比，该引擎读取的 **输入令牌减少了 56%** ，并以 **大约一半的成本** 完成了相同的任务（减少 49%；范围 61%）。节省随着的增加而增加：在查找上几乎为零，在六部门综合症上约为 49%。有关原始每轮成绩单、每任务分布和注意事项，请参见 [docs/benchmarks/](docs/benchmarks/)。
## 它可以读取
| | |
|---|---|
| 文档 | `.pdf` `.docxdoc` `.odtrtf` `.txt` `.md` |
| 电子 `.xlsx` `.xls` `.csv` `.tsv` |
| 演示文稿 | `.pptx` `.ppt` `.odp` |
| 电子邮件 | `.eml` `.msg` |
| 图片（OCR） | `.png` `.jpg` `.jpeg` `.tiff` `.heic` |
扫描的 PDF 和照片会（macOS 上的 Apple Vision，Linux 上的 tesseract）。旧版 `.doc`/`.odt`/`.ppt` 需要在 Linux 上安装 LibreOffice。
macOS OCR小型预编译的 Swift程序运行。如果您不想运行您没有编译的二进制文件，请从它旁边的源代码编译 — 请参见 [`tools/README.md`](tools/ocr/README.md)。
## 要求
- Apple 硅芯片上的 macOS（推理在进程内 MLX 中），**或** 安装并运行 [Ollama](https://ollama.com Linux（`ollama serve`）以及用于图像/扫描 OCR 的 `tesseract-ocr` 和可选的用于旧版 `.doc`/`.odt` 格式的 LibreOffice Python 3.11 [uv](https://astral.sh/- 约 4 GB 的磁盘用于模型权重
Windows 不是推理支持的目标，但监视器和管理员是跨平台的 — 如果您有 Ollama使用 `findandseek-up` 驱动它（请开机运行](#开机运行)）。
## 快速入门
```bash
git clonegithub.com/MunasheChitima/findandseek-engine
cd findandseek-engine
uv sync
uv run findandseek-setup # 下载模型权重（Qwen3，嵌入）
uv run findandseek-api # 在 127.0.1:8775 上启动本地引擎
```
在 macOS 上，`findandseek-setup` 获取 MLX 权重；在 Linux 上，它拉取等效的 Ollama 模型（`qwen3:4b` 用于摘要，`embeddinggemma` 用于嵌入 — 相同的模型系列，因此在一个平台上构建的索引与另一个平台兼容）。
告诉引擎索引哪些内容（每个文件夹重复）：
```bash
curl -X POST http://127.0.0.1:8775/folders \
-H 'Content-Type: application/json' \
-d '{"path":HOME"'/Documents"}'
```
索引在后台运行；随时检查进度：
```bash
curl http://127.0.0.1:8775/health
```
### 后台摄入（保持索引实时）
摄入分为三个长期运行的进程：**工作线程** 执行索引，**监视器** 检测文件更改并将其加入队列，**API** 提供控制/查询。仅 `findandseek-api` 将文件夹加入队列但不索引它们 — 您还需要工作线程运行。
最简单的方法是一个命令，运行并监督所有三个（重新启动崩溃的进程，在 Ctrl-C 时干净地停止它们）：
```bash
uvseek-up # 工作线程 + 监视器 + API
uv run findandseek-up --no-api # 仅后台摄入（工作线程 + 监视器）
```
监视器是跨平台的（它使用 `watchdog`：Linux 上的 inotify，macOS 上的 FSEvents，Windows 上的 ReadDirectoryChangesW），因此您监中的新文件和会自动重新索引。
#### 开机运行
在 macOS 上使用 `findandseek-service`（launchd）。在 Linux 上，提供了一个 systemd 用户单元，位于 [`deploy/findandseek.service`](deploy/findandseek.service) — 编辑两个标记的路径，然后 `systemctl --user enable --now findandseek` （以及 `login-linger "$USER"` 以在注销时保持运行）。在 Windows 上，指向任务调度器到 `uv run findandseek-up`。
## 连接您的 AI 助手
将 MCP 服务器添加到 Claude Desktop（`claude_desktop_config.json`）或任何其他 MCP 客户端：
```json
{
"mcpServers "findandseek": {
"command": "uv",
"args": ["run", "--directory", "/path/to/findandseek-enginefindandseek-engine-mcp"]
}
}
}
```
您的助手现在对您的本地索引具有以下工具：工具 | 功能 |
| --- | --- |
| `search_files` | 索引的所有内容的混合语义 + 关键字搜索 |
| `get_summary` | 文件的设备端摘要 |
| `get_file_context` | 文件的摘要及其最相关的块 |
| `get_chunk` | 文件的一个块，可选邻块 |
| `find_entity` | 查找人员、组织、电子邮件和其他提取的实体 |
| `query_typed_facts` / `aggregate_typed_facts` | 查询摄入时提取的结构化事实（数量、日期……） |
| `list_recent` | 最近修改的文件 |
| `index_status` | 已索引的内容，已挂起的内容 |
| `propose_organize | 为文件夹草拟清理/重新组织计划 |
**此处没有任何内容会移动您的文件。** `propose_organize_plan` 将提案写入索引并返回计划 ID；应用它是由用户在 FindandSeek 应用程序中控制的，有日志记录，并且是可逆的。故意没有可以触摸文件系统的 MCP 工具。
**在此基础上构建代理？** [docs/FOR_AGENTS.md](docs/FOR.md) 是它为何适合代理的原因；[docs/AGENT_GUIDE.md](docs/AGENTE.md) 是操作 工具、升级路径和代理系统中的反模式。
## REST API
MCP 工具可以做的一切也可以通过 `127.0.0.1:8775` 上的纯 HTTP 使用，如果您不想使用 MCP：
| 端点 | 用途 |
| --- | --- |
| `GET /health` | 索引和摄入 从这里开始 |
|search?q=…&scope=…` | 混合搜索；与 `search_files` 相同的排名 `GET /browse?type=…&scope=…` | 按文档类型列出索引文件 |
| `GET?days=7` | 最近修改的文件 |
GET /entity?type=value=…`实体查找 |
| `facts` | 带类型化事实（数量、日期） |
| `folders` | 将索引 |
| `folders` | 停止监视文件夹并清除它读取端点都采用 `scope` 参数 — 一个文件夹路径，限制结果仅限于该文件夹及其下。完整的路由列表在 [`find_and_seek/api/server.py`](find_and_se/server.py) 中。
身份验证。** API 绑定到 `127.0.0.1` 并信任每个调用者，这对于本地单用户工具来说是合适的，但是一旦更改就变得不安全 — `FINDANDSEEK_API_HOST=0.0.0.0` 将使搜索您索引的所有内容对可以访问该端口的任何人开放。请参见 [SECURITY.md](SECURITY.md)。
## 运行测试
测试套件是密封的 — 不需要模型权重或网络，运行时间约为 15 秒：
```bash
export FINDANDSEEK_TEST=1
export FINDANDSEEK_PERFORMANCE_MODE=full # 在电池上需要 — 平滑模式暂停摄入
uv run pytest tests -q
```
有一件事需要注意：在测试模式下，嵌入式后端返回确定性的伪向量，因此排名测试会锻炼关键字和融合路径，而不是实际的语义召回。如果您正在更改检索质量，请使用 [`find_and/eval/`](find_and_seek/eval/) 验证实际索引。
## 配置
行为可通过 `FINDANDSEEK_*` 环境变量（端口、OCR、搜索权重、文件大小上限、电池暂停）进行调整。请参见 [`find_and_seek/config/settings.py`](find_and_seek/config/settings.py) — 每个旋钮都在其读取位置有文档。
## 与 FindandSeek 产品的关联
该存储库是为 [FindandSeek](findandseek.app) 提供支持的开放引擎。商业了本地 macOS 应用程序、媒体理解视频、语音）、组织智能引擎层（HCP 分诊卡、受控执行、舰队部署基于权限的代理部署层** — 基于角色的访问控制，限制每个部署的代理仅限于执行的用户已经可以看到的文件，因此代理继承用户权限而不是索引。引擎本身是完整且有用的，但产品是企业机制的所在地。
## 贡献
请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。简：每个 PR 都运行测试，新行为需要测试，者被要求签署 CLA（项目保留单个版权，以便提供商业许可证和未来的 Apache-2.0 版本）。
## 许可证
[商业源许可证 1](LICENSE.md)（BUSL-1）。这是一个源代码可用许可证，而不是开源许可证：您可以免费读取、运行和修改引擎，包括在公司内部用于您自己的使用，但您不能将其出售给他人或为他们运行为服务。每个版本在发布两周年后转换为 Apache 2.0，届时这些限制将消失。
"FindandSeek" 是许可者的商标。代码，不涵盖名称。
**实际含义语言摘要，非法律建议，许可证文本为准）： **在您自己的团队或公司内免费运行 在您自己的机器上，将引擎用于您自己的运营的，并且无论您的商业化，它都。个人使用、学习和研究也是免费的。
- **您不能将其出售给他人或为他们运行。** 您不得将其作为服务托管给第三方，也不得被付费部署、操作或提供给其他人的业务。将引擎转变为产品或为他人管理的服务需要商业许可证。在 [findandseek.app](https://seek.app)，并附具有内置代理构建的层：基于角色的访问控制，限制每个限于执行该已经可以看到的文件。
它最终会开放 每个版本在发布两年后成为 Apache 2届时这些限制将消失。
