内容
# 文档完整性
**AI 让文档腐烂成为一种流行病。**
代码每小时都在变化，AI 助手只会让这种变化更快。而文档却跟不上。文档完整性读取您的文档，提取其中关于代码库的具体声明，并逐一检查与源代码的匹配情况。漂移成为 CI 中的一个失败检查，就像一个破碎的测试一样。
像 `doctest` 和 `mdbook test` 这样的工具运行文档中嵌入的代码块。文档完整性验证它们周围的正文：文档中描述的标志、选项、环境变量、路径和行为都会与代码实际执行的情况进行检查。
## 三项检查
文档完整性运行三项互补的检查：
- **引用检查器** — 确定性，无需 API 密钥，立即生效。捕获文档中提到的文件、CLI 标志、环境变量或符号，这些在源代码中不再存在。
- **声明验证器** — LLM 支持，捕获语义漂移：“默认超时为 30 秒”，“返回一个列表”，“设置 `FOO=bar` 以启用 X”。在设置 `ANTHROPIC_API_KEY` （或 `ANTHROPIC_AUTH_TOKEN`）时运行。
- **覆盖率** — 反向检查：代码使用的标志和环境变量，而文档中未提及。默认开启，以警告形式报告。
无需额外配置即可使用。获取密钥后功能更强大。
每个发现都有一个 **严重程度**：`error` （读者会因此受到影响）或 `warning` （真实但非关键）。默认情况下，只有错误才会导致构建失败，因此轻微问题会被报告但不会中断 CI。可通过 `--fail-on` 调整。
## 安装
```bash
npm install -g docverity
```
或无需安装直接运行：
```bash
npx docverity
```
## 使用
从您的仓库根目录：
```bash
docverity
```
默认情况下，它会检查 `README.md` 和 `docs/` 下的所有 `.md` 文件。您可以显式指定文件以缩小范围，并使用 `-C` 指定另一个根目录：
```bash
docverity -C path/to/repo
```
跳过模型以进行快速的确定性检查：
```bash
docverity --no-llm
```
当有模型可用时，文档完整性会运行一个 **仲裁阶段**，该阶段会驳回标记为错误的正面结果（示例、已记录为已删除的标志、其他工具的命令）。它按以下顺序查找模型，如果您已经使用 Claude Code，则无需设置：
1. `ANTHROPIC_API_KEY` （或 `ANTHROPIC_AUTH_TOKEN`），
2. `claude` CLI（Claude Code），如果它在您的 PATH 中 - 使用您的订阅，
3. 在作为 MCP 服务器运行时，通过 MCP 采样获取主机的模型。
### 选项
| 标志 | 描述 |
| --- | --- |
| `-C, --root <dir>` | 要检查的仓库根目录（默认为当前目录）。 |
| `--no-llm` | 仅进行确定性检查；无需 API 调用。 |
| `--model <id>` | LLM 引擎的模型（默认为 `claude-opus-4-8`）。 |
| `--no-coverage` | 跳过代码到文档的检查，以查找未记录的标志/环境变量。 |
| `--fail-confidence <n>` | 报告发现的最低置信度（0..1）。默认为 `0.7`。 |
| `--fail-on <level>` | 导致构建失败的最低严重程度：`error` （默认）、`warning`、`info` 或 `none`。 |
| `--strict` | 对无法验证的声明也失败。 |
| `--format <fmt>` | `pretty` （默认）、`json` 或 `github`。 |
文档完整性像 linter 一样导致 CI 失败。退出代码：`0` clean（或仅警告），`1` 发现的严重程度达到或超过 `--fail-on`，`2` 配置错误（例如无效的 `--fail-confidence`/`--fail-on` 或缺少文档文件），因此永远不会用绿色构建掩盖实际的漂移。
## 在 CI 中（GitHub Actions）
```yaml
name: docs
on: [pull_request]
jobs:
docverity:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx docverity --format github
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
使用 `--format github`，漂移的声明会作为内联注释出现在拉取请求中更改的行上。
## 从代理（MCP）使用
文档完整性附带一个 MCP 服务器，因此编码代理可以检查文档并在更改代码的同一回合中修复漂移。将它添加到您的 MCP 客户端：
```json
{
"mcpServers": {
"docverity": {
"command": "npx",
"args": ["docverity", "mcp"]
}
}
}
```
这公开了一个名为 `check_docs` 的工具，它返回每个漂移声明及其文件、行、过时文本、代码证据、置信度分数和建议的修复，代理可以直接应用。默认情况下，它运行确定性引擎（快速、免费、无密钥）；传递 `llm: true` 以验证正文声明。
包含一个 [`SKILL.md`](SKILL.md)，以便代理知道何时调用它（在编辑代码后，在发布前，或在询问文档是否正确时）。
## 工作原理
1. **提取** — 将每个文档解析为原子声明（标志、路径、环境变量、符号或正文断言）。
2. **定位** — 在源代码树中搜索每个声明的证据（通过 ripgrep 时可用）。文档文件排除在证据之外：声明必须由代码支持，而不是由文档重述。
3. **验证** — 引用引擎检查硬证据；LLM 引擎根据定位的证据判断正文声明，并返回 ok/drifted/unverifiable 以及具体原因。
4. **报告** — 漂亮的输出、可读的 JSON 或 GitHub 注释。
## 许可证
MIT
