内容
# nowdocs
> 一个本地的、单二进制文件的MCP服务器，为编码代理提供当前的第三方文档。
编码代理可以自信地建议自其训练数据被收集以来已经更改的API。nowdocs索引您机器上的文档，并通过MCP公开它们，因此Codex CLI、Claude Code、Cursor和其他MCP客户端可以搜索当前文档，而不仅仅依赖于模型内存。
**版本 0.2.0：** 本文档描述了v0.2.0版本。预构建的资产出现在[v0.2.0发布页面](https://github.com/nowdocs/nowdocs/releases/tag/v0.2.0)，直到发布工作流完成；在此之前，[v0.1.2](https://github.com/nowdocs/nowdocs/releases/tag/v0.1.2)仍然是最新发布的二进制文件。nowdocs免费运行，无遥测数据，默认情况下将查询、嵌入和索引文档保留在您的设备上。
## 为什么选择nowdocs
- **默认本地优先：** 查询文本、嵌入和文档内容保留在您的机器上，除非您选择启用原生Cohere重新排序。
- **混合检索：** 语义搜索、BM25全文搜索和互惠排名融合（RRF）。
- **通过stdio的MCP：** 无需配置监听端口、主机或公共服务。
- **精选注册表：** 从当前的Next.js、React和Vue文档集开始，或摄取本地Markdown文档。
- **单个Rust二进制文件：** 为macOS、Linux musl和Windows提供预构建的发布版本。
## 安装
### 预构建二进制文件
```bash
# 推荐：Cargo binstall验证GitHub Release校验和。
cargo binstall nowdocs
# 通过Homebrew tap在macOS或Linux上安装。
brew tap nowdocs-registry/nowdocs
brew install nowdocs
```
### 从源代码构建
```bash
cargo install nowdocs
# 或使用当前的存储库checkout
cargo build --release
```
源代码构建需要兼容的Rust工具链、`protoc`和`curl`在`PATH`上。
- macOS：`brew install protobuf`
- Debian/Ubuntu：`sudo apt-get install protobuf-compiler`
第一个启用下载的模型命令，例如`nowdocs doctor --model`或`nowdocs smoke`，会从Hugging Face下载Apache-2.0 `jina-embeddings-v2-small-en`模型（约66 MB），然后在本地缓存。运行`nowdocs doctor --model`以使该下载显式化。`nowdocs verify`永远不会下载它。
## 五分钟快速入门手册
此路径安装精选的Next.js文档集，验证检索并启动MCP服务器。
```bash
# 1. 检查本地环境并在缺少时下载模型。
nowdocs doctor --model
# 2. 安装精选的文档集。
nowdocs install nextjs
# 3. 确认检索返回有用的文档。
nowdocs smoke nextjs "middleware matcher configuration"
# 4. 启动本地MCP服务器。
nowdocs serve
```
`serve`使用stdio上的换行符分隔的JSON。它永远不会绑定主机或端口。
使用以下通用配置将服务器注册到MCP客户端：
```json
{
"mcpServers": {
"nowdocs": {
"command": "nowdocs",
"args": ["serve"]
}
}
}
```
Codex CLI、Claude Code、Cursor、Claude Desktop和通用MCP客户端的客户端特定行为在[MCP客户端](docs/MCP_CLIENTS.md)中。
## 代理优先设置
v0.2.0公开了一个确定性的JSON合约，以便代理可以先检查，然后提出一个计划，等待明确的批准，应用它并验证结果：
```bash
# 只读且离线安全。
nowdocs capabilities --json
nowdocs status --json
# 规划可能会获取注册表元数据，但它不会安装文档集或更改客户端配置。
# 它存储一个私有的、过期的本地计划。
nowdocs setup plan --client codex --docset react --online --json
# 仅在用户批准上述确切的计划哈希后运行。
nowdocs setup apply --plan-hash <plan-hash> --json
# 只读、离线验证。此命令从不下载模型。
nowdocs verify --docset react --client codex --json
```
代理必须检查JSON `status`、`code`、`next_actions`和可选的`rollback`对象，而不是将退出代码0视为无条件成功。有关完整的批准和回滚协议，请参见[代理设置](docs/AGENT_SETUP.md)。
发现和规划与突变是分开的。`setup apply`需要确切的存储计划哈希和明确的用户批准。自动回滚仅接受设置拥有的操作ID，成功的回滚会消耗该授权，因此它不能针对用户重新创建的注册表重放。
返回的`setup-apply`操作公开了最高的计划风险以及应用是否可以使用网络。它不被标记为完全可逆：返回的回滚操作可以恢复操作拥有的客户端配置更改，但它不卸载或降级文档集。
## 可选的原生Cohere重新排序
默认情况下，重新排序是禁用的。启用时，它会将搜索输入发送到
Cohere使用您的帐户。在启用之前，请阅读[原生Cohere重新排序指南](docs/RERANKING.md)，
它涵盖了配置、数据传输、故障回退、模型选择、MCP客户端环境和当前的OpenRouter边界。
## 常见工作流程
| 目标 | 命令 |
|---|---|
| 发现机器合约 | `nowdocs capabilities --json` |
| 检查本地状态而不更改它 | `nowdocs status --json` |
| 计划一个客户端和一个文档集 | `nowdocs setup plan --client <client> --docset <docset> [--online] --json` |
| 应用已批准的设置计划 | `nowdocs setup apply --plan-hash <hash> --json` |
| 验证本地检索和客户端配置 | `nowdocs verify --docset <docset> [--client <client>] --json` |
| 列出注册表文档集 | `nowdocs registry list` |
| 安装精选的文档集 | `nowdocs install <docset>` |
| 导入本地Markdown | `nowdocs ingest <dir> <name> --license MIT --source-url <url>` |
| 验证检索 | `nowdocs smoke <docset> [query]` |
| 启动MCP服务器 | `nowdocs serve` |
| 列出已安装的文档集 | `nowdocs list-installed` |
| 更新文档集 | `nowdocs update <docset>` |
| 重建本地缓存 | `nowdocs rebuild <docset>` |
| 诊断或安全修复设置 | `nowdocs doctor [--model] [--repair]` |
| 检查缓存 | `nowdocs cache status` |
当您拥有或被允许使用源材料时，请使用`nowdocs ingest`。对于CC-BY-4.0文档，请提供所需的`--attribution`值。使用`nowdocs share <docset>`创建文本和清单贡献包；它故意排除向量。
## 文档
- [入门](docs/GETTING_STARTED.md) - 安装、摄取、烟雾测试和恢复。
- [代理设置](docs/AGENT_SETUP.md) - 机器合约、批准边界、设置、验证和回滚。
- [MCP客户端](docs/MCP_CLIENTS.md) - 客户端特定配置和验证。
- [故障排除](docs/TROUBLESHOOTING.md) - 模型、缓存、注册表、MCP和源构建失败。
- [架构](docs/ARCHITECTURE.md) - 数据流和安全边界。
- [贡献](CONTRIBUTING.md) - 代码和文档集贡献工作流。
## 安全和隐私
MCP仅公开只读的`nowdocs_search`和`nowdocs_list`工具。修改本地状态的命令（例如`install`、`ingest`、`uninstall`和`setup apply`）仅限于CLI。代理设置将规划与突变分开，并将状态更改的下一个操作标记为需要确认。
在文档到达LLM之前，nowdocs净化返回的文本和元数据以减少提示注入内容。注册表下载仅限于受信任的注册表版本并使用SHA-256验证。共享的文档集仅包含文本和清单；注册表CI使用固定的模型重建向量。
请参阅[隐私政策](docs/PRIVACY.md)、[威胁模型](docs/THREAT_MODEL.md)和[安全政策](.github/SECURITY.md)以获取详细信息。
成功执行`install`、`update`、`ensure`、`registry`、`smoke`或`doctor`命令后，nowdocs可能会执行两个尽力检查：GitHub最新发布元数据以获取更新的二进制文件，以及受信任的注册表元数据以获取已安装注册表文档集的更新。每个通道都有时间限制，并且最多每24小时检查一次；失败是沉默的，永远不会更改主要命令结果。提醒信息打印到stderr，nowdocs从不自动下载或安装更新。设置`NOWDOCS_UPDATE_CHECK=0`以禁用这两个检查及其缓存提醒。`nowdocs serve`仍然是仅限缓存的，并且从不启动任一检查。
## 当前范围和限制
- 精选注册表当前提供Next.js、React和Vue文档集。
- 检索优先使用英语，并使用固定的Candle/Jina嵌入后端。
- Codex CLI、Claude Code和Cursor支持有条件的托管设置。Claude Desktop当前需要单独分发的`.mcpb`扩展；nowdocs尚不提供此扩展。其他MCP客户端使用生成的配置和手动安装。
- Next.js真实语料库评估门户当前报告recall@5为0.900，MRR为0.720。它并不代表每个文档集或查询的准确性。
- 发布版本未进行代码签名。请验证发布校验和；`cargo-binstall`会自动执行此操作。
- 五个平台发布资产已构建并经过校验和验证。Homebrew CLI安装仍应在具有Homebrew的机器上重新检查。
## 贡献和政策
nowdocs在`MIT OR Apache-2.0`下获得许可。贡献使用开发人员证书来源（DCO），而非CLA。请参阅[CONTRIBUTING.md](CONTRIBUTING.md)和[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
公共注册表经过策划，仅接受许可允许重新分发的文档。请审查[可接受使用政策](docs/AUP.md)、[DMCA政策](docs/DMCA.md)、[商标政策](docs/TRADEMARK.md)和[NOTICE](NOTICE)。
请勿在公共问题中报告安全漏洞。请使用GitHub的私有漏洞报告流程或发送电子邮件至`legal@gwmmai.com`，主题行中包含`[nowdocs security]`。
