Haypile

Haypile

为你和你的 Agent 提供私有文档搜索。 一个二进制文件即可监视你的文件夹、为每份文档建立索引，并通过 MCP 将相关段落交给你的 Agent，每段都附有文件和页码引用。任何内容都不会离开你的设备。

大家都说，在文件中查找信息就像大海捞针。Haypile 就是能自己找出针的干草堆。

brew install BenyD/tap/hay
hay add ~/Documents
claude mcp add --transport http haypile http://localhost:11500/mcp

整个设置过程就是这么简单。Claude Code（或 Cursor，或任何支持 MCP 的工具）现在都可以搜索你建立索引的所有内容：search_documents 会返回按相关性排序并带有引用的段落，Agent 会据此作答，而不是猜测。

它也是一款功能完整的独立命令行工具：

hay search "termination clause"
hay ask "what did the Meridian contract say about termination?"

搜索能理解含义，而不只是匹配词语：“协议取消”可以找到终止条款。精确标识符仍会精确匹配。每条结果都会标注源文件和页码。

安装

brew install BenyD/tap/hay

也可以从 releases 获取二进制文件，或运行安装脚本：

curl -fsSL haypile.sh | sh

在 Windows 上，请在 PowerShell 中运行：

irm https://haypile.sh/install.ps1 | iex

一个约 56MB 的二进制文件，内含嵌入模型。无需 Python、Docker、向量数据库、下载模型，也无需网络。文本类文档可完全离线建立索引；扫描版 PDF 需要本地视觉模型进行 OCR（hay llm setup）。

为什么选择 Haypile

Agent 可以打开你指定的任何文件。问题在于找到正确的文件：grep 匹配的是词语，而不是含义；询问终止条款的问题，并不会包含合同中使用的词语。为了找到一个段落而通读整份文档，会占用任务所需的上下文窗口。云端文档工具通过将所有内容上传到别人的电脑来解决这个问题，而可自托管的 RAG 技术栈则需要 Python 环境、Docker 和一个需要照看的向量数据库。

Haypile 提供了缺失的选择：一个二进制文件，指定文件夹，即可完成。

• 为 Agent 做好准备。 在 localhost:11500 提供 MCP 和 REST。search_documents 会向 Claude Code、Cursor 或你自己的脚本提供带引用的文档段落。
• 混合搜索。 合并语义搜索和关键词搜索。释义会按含义匹配；案件编号会精确匹配。
• 始终提供引用。 每条结果和每个答案都会指向源文件和页码。
• 始终保持最新。 文件夹会受到监视。保存文件后，几秒内即可搜索。
• 隐私可验证。 见下文。

信任承诺

这些承诺与代码一同进行版本管理，不会悄然更改：

1. 开源与付费功能的界限会提前说明。 永久开源（AGPL-3.0）：索引、搜索、提问、REST API、MCP、CLI，以及即将推出的单用户 Web UI。完整的单用户产品，不设功能限制。付费功能（稍后推出）：身份验证、角色、审计日志、共享索引和托管版本等团队功能。
2. “零外部连接”是可验证的功能，而非口头承诺。 hay status 会报告出站连接；目标是 0。没有遥测。如果将来有所变化，一定会由用户选择启用、充分说明，并且默认关闭。
3. 不进行隐式网络通信。 本地优先的工具绝不能为了正常运行而暗中连接外部服务器。
4. 所有开发都在这个公开仓库中进行。 不会有私有仓库带来的意外。

工作原理

folders -> watcher -> extract (pdf/docx/pptx/md/txt/html/mbox) -> chunk -> embed
                                                            |
        you <- citations <- RRF merge <- FTS5 + vector search <- SQLite (one file)

所有内容都保存在你磁盘上的一个 SQLite 数据库中，搜索也完全自包含：嵌入模型随二进制文件一起提供。答案（hay ask）由你已在运行的任意兼容 OpenAI 的本地服务生成（Ollama、LM Studio、llama.cpp、Jan）。Haypile 本身不提供 LLM，也不会发起网络请求。

正确初始化文件夹：hay init

对于你工作的文件夹（案例文件夹、项目、论文档案），hay init 会写入文件夹专属配置，并一次性完成所有设置：

cd ~/cases/acme-litigation
hay init          # three short questions, all with sensible defaults

它会创建 .haypile.yml（标签和排除模式），为文件夹建立索引，可选择写入 .mcp.json，让 Claude Code 和 Cursor 能搜索这些文档；如果你还没有本地大模型，还会提供 hay llm setup。hay init --yes 会以无人值守模式运行。

你可以随时手动编辑 .haypile.yml。守护进程会检测到变更，并在几秒内重新同步索引：

tag: acme-litigation
exclude:
  - drafts/**
  - "*.bak"

提问（自带大模型）

hay ask 会检索最相关的段落，并让本地大模型根据这些段落生成回答，同时附上引用：

hay ask "what did the Meridian contract say about termination?"

生成回答时会使用你已运行的任何 OpenAI 兼容服务（Ollama、LM Studio、llama.cpp、Jan），并自动检测它们常用的端口；也可以通过 --endpoint 和 --model 显式指定。如果没有可用服务，hay ask 会说明情况并展示最相关的段落。搜索始终不需要大模型。

想用云端模型生成回答？自带密钥即可：

hay ask --endpoint https://api.example.com/v1 --key sk-... "what changed in the lease?"

边界始终清晰：你的文档始终在本地建立索引。选择启用后，仅会将该问题检索出的段落发送到你选择的端点，并使用你的密钥（HAYPILE_LLM_API_KEY 也可）。对于非 localhost 的纯 http 端点，系统会拒绝使用密钥。

还没有本地大模型？运行一条引导式命令即可完成设置：

hay llm setup    # installs and starts Ollama, pulls a model, asks before every download

在 Claude Code、Cursor 或你自己的工具中使用

守护进程会在 localhost:11500 上提供 MCP（Streamable HTTP）和 REST 服务：

# Claude Code
claude mcp add --transport http haypile http://localhost:11500/mcp

# Anything that prefers launching a process (stdio transport)
#   command: hay   args: ["mcp-stdio"]

# Plain REST
curl -X POST localhost:11500/api/query -d '{"query": "termination clause"}'

提供的工具：search_documents（带引用的混合搜索）和 list_sources。守护进程会在运行 hay add 时自动启动，并且只会监听 localhost。

命令

hay init [folder]        per-folder setup: config, index, editor wiring
hay add <path>           index a folder or file and watch it for changes
hay search "<query>"     hybrid retrieval, results with citations
hay ask "<question>"     answer from your documents, with cited sources
hay list                 indexed folders and document counts
hay remove <path>        un-index a folder
hay status               daemon state, model info, outbound connections (target: 0)
hay web                  open the local web UI in your browser
hay serve                run the daemon (REST API + MCP on localhost:11500)
hay llm setup            guided local LLM setup for hay ask

路线图

版本	范围
v0.x（当前）	CLI、REST API、MCP 服务、hay web 本地 UI。支持 Markdown、文本、PDF、docx、pptx、HTML、mbox 邮件。通过本地视觉大模型对扫描版 PDF 进行 OCR。
v1.x	内置 OCR（无需大模型）、完善 Windows 安装程序
v2	可选的更大嵌入模型，适用于超大型语料库的 ANN 索引
Pro	面向办公室的团队层：身份验证、角色、审计日志、共享索引（付费）

详细了解路线图、决策和信任承诺：docs/ROADMAP.md。

开发

go build ./cmd/hay     # build the binary
go test ./... -race    # run tests (green before any merge)

语义搜索使用的嵌入模型包含在发布版二进制文件中。开发版则从磁盘加载模型，以免将权重提交到 git：

./hack/fetch-model.sh                    # one-time download (also quantizes)
go build -tags bundled ./cmd/hay         # release-style: model in the binary
HAYPILE_MODEL_PATH=internal/embed/bundled/model.safetensors ./hay   # dev

没有模型时，所有功能仍可在纯关键词模式下运行。

Web UI（hay web）位于 webui/ 中，是一个精简的 Vite + Preact 应用；其构建产物提交在 internal/webui/dist 下，并嵌入二进制文件，因此仅运行 go build 也始终会打包最新 UI。修改 UI 时运行：

cd webui && npm install
npm run dev      # live dev server, proxies /api to a running daemon
npm run build    # writes internal/webui/dist (commit the result)

检索质量靠测量，不凭感觉：eval/ 中包含一组查询及其预期结果，每次影响检索的变更都会运行这组测试。

贡献

欢迎贡献。请先阅读 CONTRIBUTING.md。其中介绍了开发工作流、必须保持不变的隐私承诺（零外发、内置模型、仅限 localhost）、贡献内容的许可方式，以及 CI 强制要求的 DCO 签署（git commit -s）。

安全

发现漏洞？请私下报告，不要提交公开议题。披露流程及适用范围请参阅 SECURITY.md。

许可

AGPL-3.0。个人用户永久免费。AGPL 确保所有实际用户都能永久免费使用，同时要求任何将 Haypile 作为服务提供的人开源其修改。