内容
<div align="center">
# pluckr
**本地优先、代理原生文档缓存。**
拉取文档站点、GitHub 仓库、`llms.txt` 端点或本地文件夹到 markdown 缓存中。通过 SQLite FTS5 进行搜索。提供给 Claude Code、Cursor 和任何 MCP 主机。
[](https://github.com/SarthakShrivastav-a/pluckr/actions/workflows/ci.yml)
[](https://github.com/SarthakShrivastav-a/pluckr/releases)
[](https://pkg.go.dev/github.com/SarthakShrivastav-a/pluckr)
[](https://goreportcard.com/report/github.com/SarthakShrivastav-a/pluckr)
[](LICENSE)
</div>
---
## 为什么
目前，大型语言模型代理只有三个文档选项：
- **将整个站点塞入上下文** — 浪费资源、昂贵且脆弱
- **实时浏览** — 速度慢、不稳定、被单页应用和速率限制阻塞
- **希望训练数据是最新的** — 通常不是这样
`pluckr` 是第四个选项。一个静态二进制文件维护一个干净的 markdown 文件夹和一个小型 SQLite 全文索引。一个 MCP 服务器将该缓存暴露给任何兼容的主机（Claude Code、Cursor、Claude Desktop、Cline、Zed 等）。您的代理搜索一次，获取所需的部分，并引用原始 URL。
## 看看它的实际效果
```text
$ pluckr add https://react.dev/reference --pull
added react.dev (website) → https://react.dev/reference
pulling react.dev (website)...
react.dev: 412 pages, 3,180 chunks, 6 skipped, 0 errors in 18.2s
$ pluckr search "useEffect cleanup"
1. react.dev › Reference › useEffect › Cleaning up an effect
https://react.dev/reference/react/useEffect#cleaning-up-an-effect
... return a [cleanup] function from the Effect ...
$ pluckr mcp # 通过 MCP/stdio 提供缓存服务
```
## 安装
`pluckr` 以单个静态 Go 二进制文件的形式提供。今天有三种安装方式：
```bash
# 1. 最新版本（推荐）
go install github.com/SarthakShrivastav-a/pluckr/cmd/pluckr@latest
# 2. 特定版本
go install github.com/SarthakShrivastav-a/pluckr/cmd/pluckr@v0.2.2
# 3. 从源代码构建
git clone https://github.com/SarthakShrivastav-a/pluckr.git
cd pluckr && go build -o pluckr ./cmd/pluckr
```
需要 Go 1.25+。预构建的 Linux / macOS / Windows 二进制文件（amd64 和 arm64）附在每个 [GitHub 版本](https://github.com/SarthakShrivastav-a/pluckr/releases) 中 — 下载，解压，添加到 `PATH` 中。
## 快速入门
```bash
# 订阅几个来源（从规范中检测类型）
pluckr add https://react.dev/reference
pluckr add https://docs.python.org/3 --max 200
pluckr add facebook/react/docs # github
pluckr add https://example.com/llms.txt # llms.txt 惯例
pluckr add ~/internal-docs # 本地 markdown 文件夹
# 获取并索引所有内容
pluckr pull --all
# 从 CLI 搜索
pluckr search "useState"
# 为您的代理提供服务
pluckr mcp
```
## 源类型
| 类型 | 规范 | 功能 |
|---|---|---|
| `website` | `https://react.dev/reference` | 站点地图 → 导航 → 广度优先搜索爬取，获取每个 URL，渲染为干净的 markdown |
| `llms_txt` | `https://example.com/llms.txt` | 优先使用 `/llms-full.txt`（如果存在）；否则，从 `/llms.txt` 解析链接 |
| `github` | `facebook/react/docs` | 列出仓库树，拉取可选子目录下的每个 `.md` / `.markdown` / `.mdx` 文件 |
| `local` | `~/internal-docs` | 遍历文件夹，拾取 `.md` / `.markdown` / `.mdx` / `.txt` 文件。无网络 |
类型从规范中检测；传递 `--kind` 以覆盖。
## 连接到代理
### Claude Code（推荐）
安装捆绑插件 — MCP 服务器 + 技能 + 斜杠命令 + `SessionStart` 钩子：
```bash
/plugin marketplace add SarthakShrivastav-a/pluckr
/plugin install pluckr@pluckr
/reload-plugins
```
您将获得：
- **MCP 服务器**，具有七种工具（搜索/获取/列表/大纲 + 刷新/添加/删除）
- **技能**，告诉 Claude 在访问网络之前何时使用缓存
- **斜杠命令** — `/pluckr-add`，`/pluckr-list`，`/pluckr-search`，`/pluckr-refresh`
- **`SessionStart` 钩子** — 运行 `pluckr list`，以便 Claude 从消息零知道存在哪些源
或手动连接仅 MCP 服务器：
```bash
claude mcp add pluckr -- pluckr mcp
```
### Cursor
添加到 `~/.cursor/mcp.json`：
```json
{ "mcpServers": { "pluckr": { "command": "pluckr", "args": ["mcp"] } } }
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{ "mcpServers": { "pluckr": { "command": "pluckr", "args": ["mcp"] } } }
```
## MCP 工具界面
| 工具 | 用途 |
|---|---|
| `search_docs(query, sources?, limit?)` | 跨订阅源的 BM25 搜索。返回具有标题路径、摘要和新鲜度的块 |
| `get_page(source, path)` | 一个缓存页面的完整 markdown |
| `list_sources()` | 具有类型、根目录、页面数量、最后同步和过时标志的订阅源 |
| `get_outline(source)` | 整个源的标题树 |
| `refresh_source(name)` | 重新运行一个源的管道。*可变* |
| `add_source(spec, …)` | 订阅一个新源。*可变* |
| `remove_source(name, …)` | 从注册表中删除一个源。*可变* |
MCP 主机的每次调用的同意 UI 是可变工具的用户可见安全门。设置 `PLUCKR_MCP_NO_MUTATIONS=true` 以在服务器端禁用它们。
## CLI 参考
```text
pluckr add <spec> [--name --kind --refresh --max --pull]
pluckr list
pluckr remove <name> [--keep-files]
pluckr pull [name...] [--all]
pluckr search <query> [--source --limit]
pluckr reindex <name>
pluckr mcp
pluckr root
```
## 磁盘布局
```text
~/.pluckr/
registry.json # 订阅源 + 新鲜度 + 授权引用
sources/
react.dev/
pages/ # markdown 是事实来源
reference/hooks/useState.md
manifest.json # 每页哈希、fetched_at、token_count
index.db # SQLite FTS5 — 可从 pages/ 重建
```
markdown 文件是事实来源。手动编辑它们，运行 `pluckr reindex <source>`，FTS5 索引就会跟上。
## 私有文档的身份验证
标头和 cookie 在获取时扩展 `${ENV}` 引用，因此密钥不会出现在注册文件中：
```json
{
"name": "internal-confluence",
"kind": "website",
"root": "https://wiki.corp.example/spaces/DOCS",
"headers": { "Cookie": "JSESSIONID=${WIKI_SESSION}" }
}
```
`refresh` 字段接受 `7d`、`30d`、`manual` 或 `never`。MCP 服务器在会话启动时启动过期源的后台刷新。
## 架构
小型 Go 接口，每个实现都隔离在其自己的包中：
```
fetch → render → chunk → store + retriever → mcp / cli
HTTP HTML→md heading- FTS5 (modernc.org/ stdio
with bounded, sqlite, no CGo)
empty- 800-token
content cap
detection
```
参见 [docs/design.md](docs/design.md) 以获取完整的 v0.1 设计 — 锁定决策、包边界、MCP 工具语义、同步模型和明确的超范围项目。
## 状态
积极开发中。源类型、FTS5 搜索、MCP 读取工具和 CLI 都已实现。单页应用文档站点的无头渲染和可插入的向量检索器已设计但尚未构建。每次推送到 `main` 分支都会自动发布下一个 semver 补丁和二进制文件。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。欢迎提交错误报告、源类型 PR、渲染器改进和 CLI / MCP 改进。
## 许可证
[MIT](LICENSE)。
