内容
# mdya
*中文 / [日语](README.ja.md)*
[](#license)
[](https://github.com/yoshihirosuzuki/mdya/releases/latest)
[](https://github.com/yoshihirosuzuki/mdya/actions/workflows/ci.yml)
一个用于本地 Markdown 集合的小型、快速的搜索原语。支持 BM25 全文搜索、设备端向量搜索和融合两者的混合搜索，并通过两个入口点公开：**命令行接口（CLI）** 和 **MCP 服务器**。
## 概述
mdya 是一个**搜索原语**。它索引本地 Markdown，并通过 CLI 和 MCP 服务器返回搜索结果。它就是这样。
mdya 不是搜索代理，也不是 LLM 查询重写前端。它没有查询扩展、没有重新排序器，也没有多阶段代理管道。需要这些功能的流程应该通过 CLI 或 MCP 接口在 mdya 之上分层一个单独的工具。
它从一开始就设计为本地优先。没有任何路径可以访问云端 LLM API；推理完全在设备上运行；分发是一个单独的二进制文件。
它可以做的事情：
- **BM25 全文搜索** — 支持日语形态分析（lindera/ipadic）的全文搜索。
- **向量搜索** — 设备端嵌入（默认 `cl-nagoya/ruri-v3-30m`，256 维）上的余弦相似度。
- **混合搜索** — 通过互惠秩融合（RRF）融合 BM25 和向量结果。
- **Markdown 分块** — 沿标题和代码围栏边界分割。
- **MCP 服务器** — `mdya mcp`（标准输入/输出 / HTTP）向 MCP 客户端公开搜索工具。
`.pdf` 文件通过与 `.md` 相同的摄取路径。它们在摄取时转换为纯文本，然后使用与 Markdown 相同的管道进行分块和嵌入。
## 支持的平台
- macOS（arm64 / x86_64）
- Linux（amd64 / arm64）
- Windows（x86_64）
## 安装
```sh
# Linux / macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yoshihirosuzuki/mdya/releases/latest/download/mdya-installer.sh | sh
```
```powershell
# Windows
powershell -ExecutionPolicy Bypass -c "irm https://github.com/yoshihirosuzuki/mdya/releases/latest/download/mdya-installer.ps1 | iex"
```
或者，从[发布页面](https://github.com/yoshihirosuzuki/mdya/releases)获取存档，并将 `mdya` 二进制文件放在您的 `PATH` 中。
Rust 用户可以从 [crates.io](https://crates.io/crates/mdya) 安装。这会从源代码构建，因此需要以下[从源代码构建的先决条件](#build-from-source)（特别是 `protoc`）：
```sh
cargo install mdya
```
### 从源代码构建
先决条件：
- Rust 1.95+（在存储库根目录的 `rust-toolchain.toml` 中自动固定）
- `just`（`cargo install just`）
- `protoc`（Protocol Buffers 编译器，`lance` 存储库的构建依赖项）。在 macOS 上，使用 `brew install protobuf`；在 Linux 上，使用 `apt install -y protobuf-compiler`；在 Windows 上，使用 `choco install protoc`。
```sh
git clone https://github.com/yoshihirosuzuki/mdya.git
cd mdya
cargo build --release # 生成 ./target/release/mdya
# 或安装到您的 PATH：
cargo install --path . # 将 mdya 安装到 ~/.cargo/bin
```
## 入门指南
最短的路径是 `init` → `collection add` → `update-all` → `search`。
```sh
mdya init # 创建 ~/.mdya/（config.yml + 索引数据目录）
mdya collection add ~/notes # 注册一个目录作为集合（名称 = basename，这里是 notes）
mdya update-all # 遍历每个已注册的集合，摄取 .md / .markdown / .pdf，构建索引
mdya search fts "release plan" # BM25 全文搜索
mdya search vector "release plan" # 向量搜索
mdya search hybrid "release plan" # 混合搜索（RRF）
```
> 第一次 `mdya update-all`（和向量/混合搜索）会自动将嵌入模型（`cl-nagoya/ruri-v3-30m`，约 140 MB）下载到 `~/.mdya-models/`，并在之后重用该缓存。
搜索结果以人类可读的格式打印到标准输出。
```
notes/release.md score=0.812
> 发布程序如下
> 1. 更新版本号
---
notes/checklist.md score=0.751
> 发布前检查清单
---
2 文档命中（显示最多 20 个）
```
常见标志：
- `-c, --collections <NAMES...>` — 限制特定集合（默认：全部）
- `-n, --limit <N>` — 顶部 N 个命中（默认 20）
- `--format <FORMAT>` — 输出格式（默认 `human`）。`json`（机器友好信封）、`md`（Markdown，适合粘贴或 LLM 输入）和 `xml`（在结构上等同于 JSON，也适合 LLM 输入）也可用。
## MCP 服务器
mdya 可以作为 MCP（模型上下文协议）服务器运行，以便 Claude Code 或 Claude Desktop 等客户端可以调用其搜索工具。
```sh
mdya mcp # 在标准输入/输出上启动 MCP 服务器
```
在 Claude Code 中注册：
```sh
claude mcp add mdya -- mdya mcp
```
## 进一步阅读
有关配置、各个子命令和 MCP 详细信息，请参阅[用户手册](docs/manual/en/README.md)。
## 配置
配置存放在 `~/.mdya/config.yml` 中的单个文件中（`mdya init` 会生成一个模板）。最小示例：
```yaml
collections:
notes:
path: ~/notes
embedding:
model: cl-nagoya/ruri-v3-30m
runtime:
memory_limit_mb: 8192 # 此进程的 RSS 上限，单位为 MB。0 表示禁用。
embed_parallelism: 8 # 在 update-all 期间并行嵌入的文件数。0 表示顺序执行。
```
`mdya collection add <path>` 会重写 `collections` 部分，因此您通常不需要手动编辑它。可以通过 `--config-dir <path>` 移动配置目录，通过 `--model-cache-dir <path>` 移动嵌入模型缓存（默认 `$HOME/.mdya-models/`）。
## 开发
```sh
just check # fmt-check + clippy (-D 警告) + cargo test（整个工作区）
just smoke # 仅限烟雾测试
just # 列出可用的配方
```
## 贡献
在尽力而为的基础上欢迎贡献（一个人维护；没有正式的 SLA）。在打开问题或 PR 之前，请阅读以下内容：
- [CONTRIBUTING.md](CONTRIBUTING.md) — 问题/PR 工作流程、构建和测试设置。
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — Contributor Covenant。
- [SECURITY.md](SECURITY.md) — 安全漏洞的私人渠道。
- [SUPPORT.md](SUPPORT.md) — 哪里可以提问。
## 许可证
双重许可下 MIT OR Apache-2.0。参见 [`LICENSE-MIT`](LICENSE-MIT) 和 [`LICENSE-APACHE`](LICENSE-APACHE)。
