SylphxAI/citra · 上手攻略
- 仓库：SylphxAI/citra
- 链接：https://github.com/SylphxAI/citra
- 分类：AI工具 / PDF处理 / MCP
- 作者：Tom
- 更新：2026-09-22
一、是什么
Citra 是一个面向 AI Agent 的本地优先 PDF 处理 MCP（Model Context Protocol）服务器。它的核心理念是给 AI 的 PDF 阅读能力配上可核验的证据——不是让 agent 自行推断，而是让它能引用「第 X 页、第 Y 段、具体坐标」这样的结构化信息。
底层用 Native Rust 重写（2024 年中从 TypeScript/PDF.js 迁移），通过一个轻薄的 Node.js 启动器加载平台专属原生二进制，提供三种 MCP 工具：read_pdf（结构化阅读）、search_pdf（定位搜索）、pdf_evidence（视觉裁切与取证）。最新版本 5.0.0（2026 年 9 月前后）。
官方 npm 包为 @sylphx/citra，另有旧包 @sylphx/pdf-reader-mcp（已废弃，TS 版）。
二、解决什么问题
普通 PDF 工具让 AI 产生「幻觉式引用」：agent 声称「第 14 页表格第 3 行」，但实际无法校验这个坐标是否真实存在。Citra 通过证据契约（Evidence Contract）彻底解决这个问题：
| 痛点 | Citra 的答案 |
|---|---|
| Agent 捏造页码/行号 | 返回 Page + geometry + provenance，坐标可逐字核验 |
| 表格被展平成乱码 | 保留 Rows·Columns·Cells·Bounding Boxes 结构 |
| 扫描件（图像 PDF）变成噪声 | OCR 路径与原文证据链接，不返回无来源文本 |
| 无本地 API key 时无法工作 | 完全本地运行，不需要任何云端视觉 API |
典型场景：让 AI 阅读财报/论文/合同时，给它「能拿给人类看的证据」，而不是让它自己拼凑答案。
三、快速安装
MCP 方式（推荐，零配置）
任意 MCP 客户端均可通过 stdio 启动，不需要 Docker，不需要 API key：
# 默认启动（自动选择平台 native 包）
npx -y @sylphx/citra
Claude Desktop / Cursor / VS Code / Codex 配置示例（~/.config/claude/ 或对应配置文件）：
{
"mcpServers": {
"citra": {
"command": "npx",
"args": ["-y", "@sylphx/citra"]
}
}
}
Claude Code 专用：
claude mcp add citra -- npx -y @sylphx/citra
全局 CLI
npm i -g @sylphx/citra
citra --help
平台原生包（自动按平台选择）
如果 npx 启动时找不到平台包，会自动提示安装对应 native 包：
| 平台 | 包名 |
|---|---|
| macOS arm64 | @sylphx/citra-darwin-arm64 |
| macOS x64 | @sylphx/citra-darwin-x64 |
| Linux x64 (gnu) | @sylphx/citra-linux-x64-gnu |
| Linux arm64 (gnu) | @sylphx/citra-linux-arm64-gnu |
| Windows x64 (msvc) | @sylphx/citra-win32-x64-msvc |
⚠️ 若平台 native 包缺失，Citra 会直接报错（fail-closed），不会静默回退到低质量 JS 引擎。这是有意设计，避免 agent 拿到无来源的结果不自知。
四、核心用法
工具一：read_pdf（主力工具）
结构化提取 PDF 全文，包含文字、表格、OCR 路径、页级引用。
{
"sources": [{ "path": "/absolute/path/to/report.pdf" }]
}
返回内容： - Markdown 格式正文：标题层级、段落顺序忠实于 PDF 阅读顺序 - 表格结构：Rows · Columns · Cells · Bounding Boxes，不是被展平的字符串 - OCR 证据链：扫描件的 OCR 文字与页码/坐标绑定，可引注 - 元数据：页数、标题、作者等文档属性
工具二：search_pdf
在 PDF 中定位包含关键词的段落，返回页码 + 文字片段，用于决定是否需要深度调用 read_pdf。
{
"query": "revenue",
"path": "/absolute/path/to/report.pdf"
}
工具三：pdf_evidence
裁切、渲染、检查 PDF 的特定区域，输出可视化证据（用于截图/日志/报告）。
{
"page": 14,
"coordinates": { "x": 0, "y": 0, "width": 500, "height": 300 },
"path": "/absolute/path/to/report.pdf"
}
SDK 方式（Node.js / TypeScript）
import { Citra } from '@sylphx/citra/sdk';
const citra = new Citra();
const result = await citra.read('/path/to/document.pdf');
支持的平台包同上；不装 native 包时同样 fail-closed。
五、典型适用场景
- 金融/财报分析：提取「第 14 页表 3 第 4 行第 2 列 = $12.4M」这类单元格级证据，AI 给出的数字可以被溯源
- 科研论文阅读：保留标题层级、页级引用，AI 引用的结论能对应原文段落
- 合同审查：扫描件 PDF 的 OCR 路径清晰，表格结构完整，不会漏读条款
- 多文档 RAG：Agent 先
search_pdf定位，再read_pdf精确提取，避免把整本文档 token 化 - 证据驱动的工作流：输出报告时附上「Page X, Box Y」式引用，可供人类复核
六、坑与注意
fail-closed设计：平台 native 包缺失时 MCP 调用会直接报错，不是警告。如果部署环境缺少 glibc（gnu vs musl 问题），需要手动指定对应 native 包。- macOS/Linux 首次下载：native 二进制文件体积较大（多 MB），
npx首次启动会下载约 20 MB，自动化 CI 环境需要考虑网络超时。 - 旧包
@sylphx/pdf-reader-mcp：已废弃，功能等同于 Citra 的 TS 实现，不应再安装。如看到旧文档用此包名，指向新包即可。 - 进程缓存：
persistent_warm模式下相同路径 + 相同选项的请求会命中进程内缓存，首次请求仍需完整解析。不是多主机共享缓存。 - 性能声明：官方声称同主机 warm 场景比 PDF.js 快 ≥10×（中位数），冷启动和跨主机场景无此保证。性能数据在
docs/specs/performance/目录有详细测量报告，有异议可自行复现。 - 二进制依赖：npm 包本身约 77 KB，但需要额外下载平台 native 包才能工作。离线环境需提前打包好对应平台的 native。
七、与同类对比
| 特性 | SylphxAI/citra | PDF.js (Mozilla) | Other PDF MCP Servers |
|---|---|---|---|
| 引擎 | Native Rust | JS (PDF.js) | 多为 JS/Python |
| 表格结构保留 | ✅ Rows/Cells/BBox | ❌ 展平 | 部分支持 |
| OCR 证据链 | ✅ 页+坐标绑定 | ❌ 无 | 部分支持 |
| MCP stdio | ✅ 原生 | ❌ 需自行包装 | ✅ |
| 本地优先 | ✅ 无云依赖 | ✅ | 视实现而定 |
| npm 包体积 | ~24 MB 全套（含 native） | 较大（PDF.js + tree） | 不等 |
| TS 版遗留 | ❌ 纯 Rust | N/A | N/A |
| 版本 | 5.0.0（2026） | N/A | 各不同 |
关键差异：Citra 的核心差异化不是「PDF 解析」，而是证据契约——它的每个返回结果都绑定坐标和来源。普通 PDF 解析返回纯文本；Citra 返回「带地理位置的文本」，这是给 AI 用的设计，不是给人用的。
八、一句话结论
需要让 AI Agent 读 PDF 并能给出可核验引用——而不是幻觉页码——选 Citra；它以 MIT 协议本地运行，零配置，是目前最干净的 PDF MCP 方案。