内容
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
<img src="docs/logo.svg" alt="" width="48" height="48">
</picture>
# 干草堆
**您文档的私有搜索和问答。** 一个二进制文件，监视您的文件夹，索引每个文档，并回答有关它们的问题，并提供引用。没有任何内容会离开您的机器。
> 每个人都说在文件中查找信息就像大海捞针一样。干草堆是能找到自己的针的干草堆。
```sh
hay add ~/Documents
hay search "termination clause"
hay ask "what did the Meridian contract say about termination?"
```
搜索理解含义，而不仅仅是词语：“agreement cancellation” 可以找到终止条款。精确标识符仍然完全匹配。每个结果都引用其源文件和页面。
## 安装
```sh
brew install BenyD/tap/hay
```
或者从 [releases](https://github.com/BenyD/haypile/releases) 获取二进制文件，或运行安装脚本：
```sh
curl -fsSL haypile.sh | sh
```
在 Windows 上，在 PowerShell 中运行：
```powershell
irm https://haypile.sh/install.ps1 | iex
```
一个二进制文件，大约 56MB，带有嵌入式模型。无需 Python，无需 Docker，无需矢量数据库，无需模型下载，无需网络。
## 为什么
您的文档（合同、论文、笔记、案件文件）实际上是无法搜索的，只能通过文件名和确切关键词来搜索。云 AI 工具通过将所有内容上传到别人的计算机来解决这个问题。自托管 RAG 堆栈通过 Python 环境、Docker 和矢量数据库来解决这个问题。
干草堆是缺失的选择：**一个二进制文件，指向文件夹，完成。**
- **混合搜索。** 语义和关键词，合并。释义按含义匹配；案例编号完全匹配。
- **始终有引用。** 每个结果和每个答案都指向源文件和页面。
- **始终保持新鲜。** 文件夹被监视。保存文件后，文件将在几秒钟内可搜索。
- **构建以便构建。** REST API 和 MCP 服务器在 `localhost:11500`，因此 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) -> chunk -> embed
|
you <- citations <- RRF merge <- FTS5 + vector search <- SQLite (one file)
```
所有内容都存储在一个 SQLite 数据库中，搜索完全是自包含的：嵌入式模型随二进制文件一起提供。答案 (`hay ask`) 由您已经运行的任何 OpenAI 兼容的本地服务器生成（Ollama、LM Studio、llama.cpp、Jan）。干草堆本身不提供 LLM，也不进行网络调用。
## 正确设置文件夹：`hay init`
对于您工作的文件夹（案例文件夹、项目、论文存档），`hay init` 会编写每个文件夹的配置文件，并一键完成所有设置：
```sh
cd ~/cases/acme-litigation
hay init # 三个简短的问题，都有合理的默认值
```
它创建 `.haypile.yml`（标签和排除模式），索引文件夹，可选地编写 `.mcp.json` 以便 Claude Code 和 Cursor 可以搜索这些文档，如果您还没有本地 LLM，则提供 `hay llm setup`。`hay init --yes` 运行无人值守。
随时手动编辑 `.haypile.yml`。守护进程会在几秒钟内注意到并重新同步索引：
```yaml
tag: acme-litigation
exclude:
- drafts/**
- "*.bak"
```
## 提出问题（自带 LLM）
`hay ask` 检索最相关的段落，并让本地 LLM 从中回答，并提供引用：
```sh
hay ask "what did the Meridian contract say about termination?"
```
生成使用您已经运行的任何 OpenAI 兼容的服务器（Ollama、LM Studio、llama.cpp、Jan），自动检测它们通常的端口，或使用 `--endpoint` 和 `--model` 显式设置。如果没有，`hay ask` 会解释并显示顶部的段落。搜索永远不需要 LLM。
还没有本地 LLM？一个有指导的命令可以让您做到这一点：
```sh
hay llm setup # installs and starts Ollama, pulls a model, asks before every download
```
## 从 Claude Code、Cursor 或您自己的工具使用
守护进程在 `localhost:11500` 上公开 MCP（Streamable HTTP）和 REST：
```sh
# 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 (now) | CLI, REST API, MCP server, `hay web` local UI. Markdown, text, PDF, docx, pptx, HTML. Scanned-PDF OCR via your local vision LLM. |
| v1.x | Bundled OCR (no LLM required), Windows installer polish |
| v2 | Optional larger embedding models, ANN index for very large corpora |
| Pro | Team layer for offices: auth, roles, audit logs, shared indexes (paid) |
路线图、决策和信任承诺的详细信息：[docs/ROADMAP.md](docs/ROADMAP.md)。
## 开发
```sh
go build ./cmd/hay # build the binary
go test ./... -race # run tests (green before any merge)
```
语义搜索使用一个嵌入式模型，发布构建在二进制文件中携带。开发构建从磁盘加载它，因此权重不会进入 git：
```sh
./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/](webui/) 作为一个小型 Vite + Preact 应用程序；其构建输出存储在 `internal/webui/dist` 下，并嵌入到二进制文件中，因此单独的 `go build` 始终会提供当前的 UI。使用以下命令进行交互：
```sh
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/](eval/) 包含一个查询集，带有预期结果，在每次影响检索的更改时运行。
## 贡献
欢迎贡献。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。它涵盖了开发工作流、隐私合同（零外出、捆绑模型、仅限 localhost）的完整性、贡献的许可方式以及 CI 强制执行的 DCO 签署（`git commit -s`）。
## 安全
发现了漏洞？请私下报告，而不是作为公开问题。有关披露过程和适用范围，请参见 [SECURITY.md](SECURITY.md)。
## 许可证
[AGPL-3.0](LICENSE)。个人永久免费。 AGPL 保持免费供每个实际用户使用，同时要求任何提供 Haypile 作为服务的用户开放其更改。
