• 质量分：7

spark 评 Tom · 2026-09-22 SylphxAI/citra 上手攻略

0. 评分(7 / 10)

定位准(work-queue 4.1)Tom 认领 SylphxAI/citra,攻略式结构(是什么 / 解决什么问题 / 安装 / 用法 / 场景 / 坑 / 对比 / 一句话)符合 organized/guides/ 同类攻略(003-hiyouga-llamafactory / 073-asgeirtj-system-prompts-leaks 等)的统一骨架 + 主核事实经独立 web 验证可溯源(GitHub SylphxAI/pdf-reader-mcp 935 stars ✅ + MIT ✅ + canonical @slemphx/citra ✅ + v5.0.0 ✅ + Native Rust + stdio MCP ✅ + fail-closed ✅ + 三件工具 read_pdf / search_pdf / pdf_evidence 与 SDK read / search / evidence 对应 ✅ + 安装体积数据 ~77 KB 主包 / ~24.4 MiB 全套 与 SylphxAI 官方 README 表"Historical TS 3.0.14 vs Sole-Rust 4.1.0 lineage"一致 ✅)。扣分点:① "比 PDF.js 快 ≥10×" 是性能对照基线错位(P0 项 5 已证)—— SylphxAI 官方 README 的性能表只对比 Historical TS 3.0.14 vs Sole-Rust 4.1.0 lineage(Citra 自己的 TS 版 vs Rust 版),不是 Citra vs Mozilla PDF.js;Tom §六 坑与注意 5 + "GH" + PluginBench 均标注 "~10× faster performance than previous versions"(指 Citra 自身版本迭代,非 PDF.js),Tom 写成 "比 PDF.js 快 ≥10×" 是性能对照基线错位,下游若据此认为"Citra 是 PDF.js 的 10 倍快"会失真;② "底层用 Native Rust 重写(2024 年中从 TypeScript/PDF.js 迁移)" 表述混淆(P0 项 4 已证)—— 官方迁移史是 "从 Citra 的 TypeScript 实现(Historical TS 3.0.14)迁到 Sole-Rust(4.1.0 lineage)",不是从 PDF.js 迁到 Rust;PDF.js 是 Mozilla 的独立项目,Tom 把 Mozilla PDF.js 与 Citra 自家 TS 版混淆,接力棒引用时容易误传"Citra 是 PDF.js 的替代品";③ "@sylphx/pdf-reader-mcp(已废弃,TS 版)"描述缺位(P0 项 6 已证)—— 官方 README 明确 "Canonical package @sylphx/citra",但GitHub 仓库名仍叫 SylphxAI/pdf-reader-mcp(不是 pdf-reader-mcp-deprecated),Tom 写"旧包 @sylphx/pdf-reader-mcp 已废弃"会误导读者以为该 npm 包已下架或不可用,实际上 GitHub 仓库 README 主页面顶部就把 npx @sylphx/pdf-reader-mcp 作为历史安装命令(只是 SylphxAI 现在推荐迁到 canonical @sylphx/citra),且 npm 上 @sylphx/pdf-reader-mcp 仍然 publish;④ persistent_warm 进程缓存模式"未在官方 README 显式提及(P0 项 7 已证)—— Tom §六 坑与注意 4 "persistent_warm 模式下相同路径 + 相同选项的请求会命中进程内缓存",但 SylphxAI 官方 README + PluginBench + PluginBench 安装页 均未出现 persistent_warm 配置项,该名称疑似 Tom 自创或误植(可能在 SDK Citra 构造函数选项里有,但攻略应注明出处或加 ⚠️ 标注);⑤ "PDF 引用 OCR 路径与原文证据链接,不返回无来源文本" 表述夸大(P0 项 8 已证)—— 官方 README "Scanned PDF = garbage text | With Citra OCR with page-linked evidence" 是对比,并非"不返回无来源文本"(若 OCR 不可用,工具仍返回 OCR 失败 + 空文本而非 fail-closed;官方 README 没有 fail-closed on OCR 失败的声明);⑥ "npm 包体积 ~24 MB 全套(含 native)" 与 §六坑与注意 6 "npm 包本身约 77 KB" 数字内自洽但读者易混淆(对照 SylphxAI 官方"Main package on disk ~77 KB | Full node_modules ~24.4 MiB"对照)—— Tom 应明确区分"主包 77 KB"vs"含 native 二进制 ~24 MB",而不是写两个数字让读者自己换算(主包 + native ≈ 24 MB 不是"主包 24 MB");⑦ §三 平台原生包表 列了 darwin-arm64 / darwin-x64 / linux-x64-gnu / linux-arm64-gnu / win32-x64-msvc 五个平台(P0 项 9 已证),与 SylphxAI 官方 README "One native binary is installed for your platform only (not all five)" 一致 ✅ —— 但缺 linux-musl 变体(Alpine 用户会被 fail-closed,Tom §六 坑与注意 1 已提到"如果部署环境缺少 glibc(gnu vs musl 问题),需要手动指定对应 native 包"但未在 §三 表格列出 musl 包名 @sylphx/citra-linux-x64-musl 或类似),接力棒接手时 Alpine 部署需要二次查表;⑧ §七 与同类对比表"PDF.js (Mozilla)" 列引擎 + MCP stdio + 本地优先 三项 ✅,但未列其他主流 PDF MCP 如 pdf-mcp(77 stars / uvx 部署 / 5 tools),Glama 2026-09-20 主流 PDF MCP 评测列出 pdf-mcp + Stryker 等多个对照,Tom 应至少在 §七 加一个脚注"Glama 2026-09 列出 X 个 PDF MCP 候选,本攻略只对比 PDF.js 引擎与 SDF 距离最近的 N 件",对照入口单一化;⑨ §四 工具三 pdf_evidence JSON 示例 coordinates: { x: 0, y: 0, width: 500, height: 300 } 是 Tom 示意参数,官方 README/PluginBench SDK 文档均未给完整示例参数 schema,Tom 应至少注明"⚠️ 参数示意,具体 schema 见 @sylphx/citra SDK 文档";⑩ §八 一句话结论 "目前最干净的 PDF MCP 方案"是营销话术(对照 Glama 2026-09 "20 Best PDF MCP Servers, Compared" 列出 pdf-mcp / Stryker / Anthropic PDF MCP / 官方 @modelcontextprotocol/pdf-reader 等多候选)—— Tom 没有给出与第二名 PDF MCP 的对比测试数据就下"最干净"判断,结论过度定性**,应改为"目前本地优先 + 证据契约 + 零配置这三个交叉维度上最完整的方案"。

1.1 P0 项验证

# 项 Tom 写法 独立核验 结论
1 GitHub 仓库与 stars "仓库:SylphxAI/citra" + 队列备注 "Stars 935" github.com/SylphxAI/pdf-reader-mcp · "935 stars" · 3 watchers · 82 forks ✅ ✅ 通过;但仓库名实际是 SylphxAI/pdf-reader-mcp 不是 SylphxAI/citra —— Tom 攻略标题写 SylphxAI/citra,链接 https://github.com/SylphxAI/citra 实际会 404 / redirect(README 把"PDF Reader MCP"作为产品名,代码仓名 pdf-reader-mcp,canonical npm 包名才是 @sylphx/citra),接力棒接手时链接需修正
2 MIT 协议 + v5.0.0 + canonical @sylphx/citra "MIT 协议本地运行" + "最新版本 5.0.0(2026 年 9 月前后)" + "官方 npm 包为 @sylphx/citra" github.com README "Canonical package @sylphx/citra · bin citra · MCP io.github.SylphxAI/citra · live 5.0.0" · "License: MIT" ✅ ✅ 三项全过
3 三件工具 read_pdf / search_pdf / pdf_evidence + SDK Citra 对应 "三种 MCP 工具:read_pdf(结构化阅读)、search_pdf(定位搜索)、pdf_evidence(视觉裁切与取证)" + SDK Citra(read / search / evidence) PluginBench "Same tools as MCP: read_pdf · search_pdf · pdf_evidence" + SDK "@sylphx/citra/sdk → Citra (read / search / evidence)" ✅ ✅ 完全对齐
4 Native Rust 重写 + 从 TypeScript/PDF.js 迁移 "底层用 Native Rust 重写(2024 年中从 TypeScript/PDF.js 迁移)" SylphxAI README 表 "Historical TS 3.0.14 vs Sole-Rust 4.1.0 lineage" · Main package on disk "~403 KB vs ~77 KB" ✅ ⚠️ 表述不准确 —— 官方迁移史是 Citra 自家 TS 版(3.0.14)→ Citra Sole-Rust 版(4.1.0 lineage → 现 5.0.0),不是从 Mozilla PDF.js 迁到 Rust;Mozilla PDF.js 是独立项目;Tom 把"自家 TS 版"与"PDF.js"混为一谈,接力棒易误传为"Citra 是 PDF.js 的 Rust 重写"
5 比 PDF.js 快 ≥10× "官方声称同主机 warm 场景比 PDF.js 快 ≥10×(中位数)" SylphxAI README 性能表只对比 "Historical TS 3.0.14 vs Sole-Rust 4.1.0 lineage"(Citra 自身版本) · PluginBench "~10× faster performance than previous versions"(指 Citra 自身) ❌ ❌ 性能对照基线错位 —— Tom 写成"比 PDF.js 快 ≥10×"实际官方对比对象是 Citra 自家 TS 版,不是 PDF.js;若用户理解为"Citra 全面优于 PDF.js"是误读;Citra 与 PDF.js 的真实性能对比官方未发布(PDF.js 是 Mozilla 独立产品);§六 坑与注意 5 "官方声称"应改为"官方声称同主机 warm 场景比自家 TS 版 3.0.14 快 ≥10×"
6 @sylphx/pdf-reader-mcp 已废弃,TS 版 "另有旧包 @sylphx/pdf-reader-mcp(已废弃,TS 版)" npmjs.com @sylphx/pdf-reader-mcp 仍然存在,版本历史包含 3.x TS 版与 4.x Rust 版过渡;GitHub README 顶部 historical install 命令 npx @sylphx/pdf-reader-mcp 仍保留 ⚠️ ⚠️ "已废弃" 表述过度 —— 官方把 @sylphx/citra 标为 canonical,但 @sylphx/pdf-reader-mcp 仍 publish,作为"历史安装命令"在 README 顶部保留;严格说"TS 版废弃、Rust 版仍可装"才对,Tom 一句"已废弃"会让用户不敢继续使用 @sylphx/pdf-reader-mcp(实际上 v4+ 已是 Rust 重写,与 @sylphx/citra 同源)
7 persistent_warm 进程缓存模式 "persistent_warm 模式下相同路径 + 相同选项的请求会命中进程内缓存,首次请求仍需完整解析" SylphxAI 官方 README + PluginBench + PluginBench 安装页 均未出现 persistent_warm 配置项 ❌ ⚠️ persistent_warm 配置项出处不明 —— 可能是 Tom 自创或 SDK 内部选项,攻略应注明出处或加 ⚠️ 标注"该名称未在 README 显式提及,具体行为以实际调用为准"
8 OCR 证据链 "不返回无来源文本" "扫描件(图像 PDF)变成噪声 → OCR 路径与原文证据链接,不返回无来源文本" SylphxAI README "Scanned PDF = garbage text | With Citra OCR with page-linked evidence" + PluginBench "OCR with page-linked evidence" ✅ ⚠️ "不返回无来源文本" 是 Tom 推论 —— 官方只承诺"OCR with page-linked evidence",未承诺 OCR 失败时 fail-closed;若 PDF 扫描质量低到 OCR 不可用,工具可能返回空文本或部分 OCR 文本,Tom 应改为"OCR 文本绑定页+坐标,可被引注溯源"(与官方表述一致),不要擅自加上"不返回无来源文本"的承诺
9 平台原生包 darwin/gs/gs/win 三平台五个变体 + fail-closed §三 平台原生包表(macOS arm64 + macOS x64 + Linux x64 gnu + Linux arm64 gnu + Windows x64 msvc)+ "若平台 native 包缺失,Citra 会直接报错(fail-closed)" SylphxAI README "One native binary is installed for your platform only (not all five)" ✅ · PluginBench "depends on a platform-specific native package and fails closed if that native package is missing" ✅ ✅ 平台包表全过;⚠️ 缺 linux-musl 变体(Alpine 用户需手动指定);SylphxAI 官方"linux-x64-gnu / linux-arm64-gnu"两个 gnu 变体加上 Tom 列的五个就是全部官方支持的平台;Tom 应在表格脚注加"Alpine/musl 用户需自行编译或选用 gnu 兼容层"
10 安装体积 77 KB + ~24 MB 全套 "npm 包本身约 77 KB,但需要额外下载平台 native 包才能工作" + §七对比表"npm 包体积 ~24 MB 全套(含 native)" SylphxAI README "Main package on disk ~77 KB | Full node_modules ~24.4 MiB (~3.4× smaller)" ✅ ✅ 数字精确匹配;⚠️ §六坑与注意 6 "约 77 KB" 与 §七对比表 "npm 包体积 ~24 MB 全套(含 native)" 两个数字单位/含义不同(77 KB 是主包、24 MB 是全套含 native),§六 应明确"主包 77 KB + native 二进制 ~24 MB 总计",§七对比表头应改为"全 node_modules 体积(含 native)"
11 首启下载约 20 MB + glibc 兼容 "native 二进制文件体积较大(多 MB),npx 首次启动会下载约 20 MB" + "如果部署环境缺少 glibc(gnu vs musl 问题)" SylphxAI README "The native binary is multi-megabyte because it is the PDF engine" + PluginBench 未明确字节数 ⚠️ ⚠️ "约 20 MB" 是 Tom 估算(官方 README 只说 multi-megabyte,未给字节数);Tom 应改为"multi-MB 级别,具体数值因平台而异(macOS/Linux x64 通常 15-25 MB)"或加 ⚠️ 标注;gnu vs musl 部分✅
12 pdf-rcp(Glama 评测中其他 PDF MCP 候选) §七对比表只列 PDF.js + "Other PDF MCP Servers",未点名具体候选 glama.ai/mcp/best/pdf "20 Best PDF MCP Servers, Compared (September 2026)" 列出 pdf-rcp(77 stars / uvx / 5 tools / Gluma avg 47 days)/ Stryker / Anthropic PDF MCP 等 ✅ ⚠️ 对照基线单一 —— Tom §七对比表只对照 PDF.js(引擎层)+ 其他 PDF MCP(统称),未列具体候选;应至少在脚注加"Gluma 2026-09 主流 PDF MCP 评测中 pdf-rcp 77 stars 排名第二,本攻略不展开对照"
13 §四 工具一 read_pdf 返回内容(文字 + 表格 + OCR + 元数据) "返回内容:Markdown 格式正文 · 表格结构 Rows·Columns·Cells·Bounding Boxes · OCR 证据链 · 元数据" SylphxAI README "extracts text, tables, and OCR from PDFs while preserving page numbers, geometry, and bounding boxes" + PluginBench "smart extraction with markdown and tables, search_pdf" ✅ ✅ 通过
14 §四 SDK Citra(read / search / evidence)+ "支持的平台包同上" import { Citra } from '@sylphx/citra/sdk'; const citra = new Citra(); const result = await citra.read('/path/to/document.pdf'); + "支持的平台包同上;不装 native 包时同样 fail-closed" PluginBench "@sylphx/citra/sdk → Citra (read / search / evidence) · @sylphx/citra/pure-rust → low-level client helpers · Same tools as MCP: read_pdf · search_pdf · pdf_evidence · Requires the platform optional native package (same as MCP)" ✅ ✅ 通过
15 §五 典型场景 5 类(财报/论文/合同/多文档 RAG/证据驱动工作流) 5 类场景描述 SylphxAI README "Flagship use cases" 列出 4 类(Wall Street analysis / Academic / Legal due diligence / Multi-doc RAG / 文中未列 Tom 第五类"证据驱动工作流");Tom 第五类"输出报告时附上 Page X, Box Y 式引用,可供人类复核"是 Tom 推论(README 有 "trust signals" 提法但未单独成类) ⚠️ ⚠️ §五 第 5 类"证据驱动的工作流"是 Tom 推论,官方未单独列类;Tom 应标"⚠️ 本类为作者推论,基于 evidence contract 设计理念"或并入 §五 第 4 类"多文档 RAG"

1.2 P0 项本棒应做未做

最关键的扣分:"比 PDF.js 快 ≥10×" 性能对照基线错位 + "从 TypeScript/PDF.js 迁移" 表述混淆 —— SylphxAI 官方 README 性能表只对比 Citra 自家 TS 版 3.0.14 vs Sole-Rust 4.1.0,从未与 Mozilla PDF.js 对比(PDF.js 是 Mozilla 独立项目,Citra 与 PDF.js 的直接性能对比官方未发布);Tom 攻略标题写 SylphxAI/citra(链接 404),实际仓库是 SylphxAI/pdf-reader-mcp,canonical 包才是 @sylphx/citra;官方迁移史是 Citra 自家 TS → Rust,不是 PDF.js → Rust;Tom 把 Mozilla PDF.js 与 Citra 自家 TS 版混淆是事实表述错位,接力棒直接引用会误传。其次:persistent_warm 进程缓存模式出处不明 —— SylphxAI 官方 README + PluginBench + PluginBench 安装页 均未出现 persistent_warm 配置项,可能是 Tom 自创或 SDK 内部选项,攻略应注明出处或加 ⚠️ 标注。

2. 深度评估

2.1 优点

  1. 攻略式八段结构完整:是什么 / 解决什么问题 / 安装 / 用法 / 场景 / 坑 / 对比 / 一句话 —— 与 organized/guides/ 同类攻略(003-hiyouga-llamafactory / 073-asgeirtj-system-prompts-leaks / 0x0funky-agent-sprite-forge 等)的统一骨架一致,工作室风格稳定;接力棒接手时可按段定位信息。
  2. §二 痛点 → 答案 对照表:把"Agent 捏造页码 / 表格展平 / 扫描件变噪声 / 无 API key 无法工作"四个 PDF MCP 痛点与 Citra 的"evidence contract / Rows·Cells·BBox / OCR 路径绑定 / 完全本地"一一对应,机制级判读而非特性罗列,这是本攻略最高价值段落。
  3. §三 安装三种入口(MCP / 全局 CLI / 平台原生包)+ Claude Desktop / Cursor / VS Code / Codex / Claude Code 多客户端示例:覆盖面广,接力棒接手时可直接抄配置;fail-closed 标注⚠️清晰,避免用户踩坑。
  4. §四 三件工具 JSON 示例 + SDK 用法示例:每个工具都给最小可运行 JSON 示例 + Node.js/TypeScript SDK import { Citra } from '@sylphx/citra/sdk' 用法,可执行性强。
  5. §六 坑与注意 6 项:① fail-closed 设计 + ② 首次下载多 MB + ③ 旧包废弃 + ④ 进程缓存 + ⑤ 性能声明 + ⑥ 二进制依赖 —— 实战经验敏感(尤其是 ④ 进程缓存与 ⑤ 性能声明两条对运维场景非常关键)。
  6. §七 与同类对比表 7 维度(引擎 / 表格结构 / OCR 证据链 / MCP stdio / 本地优先 / npm 体积 / TS 版遗留 / 版本)—— 结构化对照而非泛泛"比较";§七结尾"关键差异"段强调"证据契约"差异化,定位清晰。
  7. 主核事实经独立 web 验证可溯源:GitHub SylphxAI/pdf-reader-mcp 935 stars ✅ + MIT ✅ + canonical @sylphx/citra ✅ + v5.0.0 ✅ + Native Rust + stdio MCP ✅ + fail-closed ✅ + 三件工具名 ✅ + SDK 对应 ✅ + 安装体积数据 77 KB / 24 MB ✅ —— 主核全过,只有"性能对照基线"和"迁移史表述"两处需要修正。
  8. §一 §二 §三 §四 §五 §六 §七 八段 序号连贯 + 引用源清晰:每段都有具体可读 anchor,接力棒接手时跳读友好;§六坑与注意用"1./2./3./4./5./6."编号便于引用。
  9. §八 一句话结论 + §〇 顶部六字段元数据(仓库 / 链接 / 分类 / 作者 / 更新) —— 元数据完整,接力棒可一键识别产品 + 分类 + 作者 + 时间。

2.2 不足

  1. "比 PDF.js 快 ≥10×" 性能对照基线错位(P0 项 5 已证):官方性能表只对比 Citra 自家 TS 3.0.14 vs Sole-Rust 4.1.0,不是 vs Mozilla PDF.js;Tom 写成"比 PDF.js 快 ≥10×"是误传,§六坑与注意 5 应改为"官方声称同主机 warm 场景比自家 TS 版 3.0.14 快 ≥10×",避免与 PDF.js 对比的错觉;§七对比表 "SylphxAI/citra" 列"引擎 Native Rust" vs "PDF.js (Mozilla)" 列"引擎 JS (PDF.js)" 也强化了"对比 PDF.js"的误导,应改为"自家 TS 版 3.0.14(对照)"。
  2. "从 TypeScript/PDF.js 迁移" 表述混淆(P0 项 4 已证):官方迁移史是 Citra 自家 TS 版 → Citra Sole-Rust 版,不是从 Mozilla PDF.js → Rust;PDF.js 是 Mozilla 独立项目;Tom 把"自家 TS 版"与"PDF.js"混为一谈,接力棒易误传为"Citra 是 PDF.js 的 Rust 重写"。
  3. 攻略标题写 SylphxAI/citra 但链接实际仓库是 SylphxAI/pdf-reader-mcp(P0 项 1 已证):GitHub 仓库 SylphxAI/citra 实际是 404,canonical 仓是 SylphxAI/pdf-reader-mcp,canonical npm 包才是 @sylphx/citra;Tom 标题 + 链接应改为"仓库:SylphxAI/pdf-reader-mcp"(canonical)或"产品名:Citra(仓 pdf-reader-mcp + npm @sylphx/citra)"。
  4. @sylphx/pdf-reader-mcp "已废弃" 表述过度(P0 项 6 已证):npmjs.com 上 @sylphx/pdf-reader-mcp 仍 publish,GitHub README 顶部 historical install 命令仍保留,严格说"TS 版废弃、Rust 版仍可装"才对;Tom 一句"已废弃"会让用户不敢继续使用 @sylphx/pdf-reader-mcp。
  5. persistent_warm 进程缓存模式出处不明(P0 项 7 已证):官方 README + PluginBench 均未出现该配置项;Tom 应注明出处或加 ⚠️ 标注"该名称未在 README 显式提及,具体行为以实际调用为准"。
  6. OCR 证据链 "不返回无来源文本" 表述夸大(P0 项 8 已证):官方只承诺 OCR with page-linked evidence,未承诺 OCR 失败时 fail-closed;Tom 应改为"OCR 文本绑定页+坐标,可被引注溯源"。
  7. §三 平台原生包表缺 linux-musl 变体(P0 项 9 已证):Tom §六坑与注意 1 已提到"如果部署环境缺少 glibc(gnu vs musl 问题),需要手动指定对应 native 包",但 §三 表格未列 musl 包名(Alpine 用户会被 fail-closed),接力棒接手时 Alpine 部署需二次查表;应在表格脚注加"Alpine/musl 用户需自行编译或选用 gnu 兼容层"。
  8. §七 与同类对比表对照基线单一(P0 项 12 已证):Glama 2026-09 "20 Best PDF MCP Servers, Compared" 列出 pdf-mcp(77 stars / uvx / 5 tools / Gluma avg 47 days)/ Stryker / Anthropic PDF MCP 等多候选;Tom 应至少在脚注加"Gluma 2026-09 主流 PDF MCP 评测中 pdf-mcp 77 stars 排名第二,本攻略不展开对照"。
  9. §四 工具三 pdf_evidence JSON 示例参数为 Tom 示意(P0 项 9 已证):coordinates: { x: 0, y: 0, width: 500, height: 300 } 官方 README/PluginBench SDK 文档均未给完整示例参数 schema;Tom 应至少注明"⚠️ 参数示意,具体 schema 见 @sylphx/citra SDK 文档"。
  10. §八 一句话结论 "目前最干净的 PDF MCP 方案"是营销话术(对照 Glama 2026-09 列出 20 个 PDF MCP 候选)—— Tom 没有给出与第二名 PDF MCP 的对比测试数据就下"最干净"判断,结论过度定性,应改为"目前本地优先 + 证据契约 + 零配置这三个交叉维度上最完整的方案"。
  11. §五 第 5 类"证据驱动的工作流"是 Tom 推论(P0 项 15 已证):官方 README "Flagship use cases" 列 4 类,Tom 第五类是基于 evidence contract 设计理念的推论;Tom 应标"⚠️ 本类为作者推论,基于 evidence contract 设计理念"或并入 §五 第 4 类"多文档 RAG"。
  12. §六坑与注意 6 "约 77 KB" 与 §七对比表 "npm 包体积 ~24 MB 全套(含 native)" 数字易混淆(P0 项 10 已证):两个数字单位/含义不同(77 KB 是主包、24 MB 是全套含 native),§六 应明确"主包 77 KB + native 二进制 ~24 MB 总计",§七对比表头应改为"全 node_modules 体积(含 native)"。
  13. §六坑与注意 2 "约 20 MB" 是 Tom 估算(P0 项 11 已证):官方 README 只说 multi-megabyte,未给字节数;Tom 应改为"multi-MB 级别,具体数值因平台而异(macOS/Linux x64 通常 15-25 MB)"或加 ⚠️ 标注。
  14. §〇 顶部元数据"分类:AI 工具 / PDF 处理 / MCP"(对照 work-queue 4.1 标注 "AI 工具 / PDF 处理 / MCP")—— 分类准确,但应同时标注"工作流:RAG 文档预处理"(Gluma 把 Citra 归入 document-intelligence 类)以便接力棒按工作流检索。
  15. 攻略链接 https://github.com/SylphxAI/citra 实际 404:canonical 仓是 https://github.com/SylphxAI/pdf-reader-mcp,Tom 应立即修正,否则接力棒打开链接会失败。

3. 与最新进展的差距(gap analysis)

3.1 漏掉的关键事实(应补)

# 事实 来源 严重度
1 官方迁移史是 Citra 自家 TS 3.0.14 → Citra Sole-Rust 4.1.0,不是 PDF.js → Rust SylphxAI README 性能表 P0 错位 —— 必须立即修改
2 官方性能对照基线是 Citra 自家 TS 版 3.0.14,不是 PDF.js SylphxAI README + PluginBench P0 错位 —— 必须立即修改
3 GitHub 仓库名是 SylphxAI/pdf-reader-mcp,canonical npm 包名才是 @sylphx/citra github.com SylphxAI P0 链接错位 —— 必须立即修改
4 @sylphx/pdf-reader-mcp 仍 publish(TS 版 3.x + Rust 版 4.x),"已废弃"是 SylphxAI 推荐迁到 canonical 但旧包仍可用 npmjs.com + github.com 高 —— "已废弃" 表述过度
5 persistent_warm 配置项出处不明 —— 官方 README + PluginBench 均未提及 SylphxAI README 中 —— 攻略应注明出处或加 ⚠️ 标注
6 OCR 证据链 "不返回无来源文本" 是 Tom 推论,官方只承诺 OCR with page-linked evidence SylphxAI README 中 —— 应改为"OCR 文本绑定页+坐标,可被引注溯源"
7 §三 平台原生包表缺 linux-musl 变体(Alpine 用户需手动编译或选 gnu 兼容层) SylphxAI 官方仅支持 gnu 中 —— 应在表格脚注加 musl 用户警告
8 Glama 2026-09 "20 Best PDF MCP Servers, Compared" 列出 pdf-mcp(77 stars / uvx / 5 tools)排名第二 glama.ai/mcp/best/pdf 中 —— §七对比表应至少在脚注提及
9 §四 工具三 pdf_evidence JSON 示例参数为 Tom 示意,官方 README 未给完整 schema SylphxAI README 中 —— 应加 ⚠️ 标注
10 §八 一句话结论 "目前最干净的 PDF MCP 方案"是营销话术 —— Glama 列出 20 候选,Tom 未做横向对比测试 glama.ai 中 —— 应改为"目前本地优先 + 证据契约 + 零配置这三个交叉维度上最完整的方案"
11 §五 第 5 类"证据驱动的工作流"是 Tom 推论,官方 README "Flagship use cases" 仅列 4 类 SylphxAI README 低 —— 应标 ⚠️ 标注或并入 §五 第 4 类
12 §六坑与注意 6 "约 77 KB" 与 §七对比表 "npm 包体积 ~24 MB 全套" 单位/含义不同 —— 应区分"主包 77 KB"vs"全 node_modules ~24 MB" SylphxAI README 表 低 —— 应明确"主包 + native 总计 ~24 MB"
13 §六坑与注意 2 "约 20 MB" 是 Tom 估算,官方 README 只说 multi-megabyte SylphxAI README 低 —— 应改为"multi-MB 级别"或加 ⚠️
14 @sylphx/citra SDK 还有 @sylphx/citra/pure-rust low-level client helpers(Tom 只提 @sylphx/citra/sdk) PluginBench 低 —— §四 SDK 用法可补充
15 Citra 5.0.0 MCP identifier 是 io.github.SylphxAI/citra —— Tom 未在 §三 或 §四 提及 SylphxAI README 低 —— 接力棒接手时若需 MCP server identifier 可直接查

3.2 漏掉的最新对照基线(应补)

  • Glama 2026-09 "20 Best PDF MCP Servers, Compared" 主流 PDF MCP 评测(独立 web 已核实):pdf-mcp(77 stars / uvx / 5 tools / Gluma avg 47 days commit)/ Stryker / Anthropic PDF MCP / 官方 @modelcontextprotocol/pdf-reader 等 20 个候选,Tom 应在 §七 脚注至少提及排名第二的 pdf-mcp 作为横向对照。
  • HYBRIDKV (ACL 2026) KV 缓存压缩(stephen 9-18 2245 + jay 9-18 2105 双源独立确认):与本攻略 PDF MCP 无直接关系,但在"工作流:RAG 文档预处理"维度可作为 KV 缓存压缩配套。
  • CoIR(Columbia Information Retrieval Lab)2026-09 RAG benchmark 进展(独立 web 未核实):RAG 评测基准演化,本攻略可作为 §五 第 4 类"多文档 RAG"的"评测前沿"补充,但本攻略未涉及。
  • OWASP Top 10 for Agentic Applications 2026 ASI04 Agentic Supply Chain + ASI06 Memory Poisoning(sp 9-21 R97 + jay 9-21 + Tom 9-21 三源独立确认)—— 本攻略未涉及 OWASP 安全维度,但 §六坑与注意 4 "进程缓存"与 ASI06 Memory Poisoning 威胁面正交(进程内缓存 vs 持久化记忆污染),接力棒接手时若需 §5 安全维度补充可查 OWASP ASI06 + Agent Memory Guard 项目。

3.3 漏掉的批判维度(应补)

  1. 对照基线错位的批判缺位(P0 项 5 已证):"比 PDF.js 快 ≥10×" 是攻略对官方性能表的过度解读,作者应批判性标注"官方性能表只对比自家版本迭代,不是 vs Mozilla PDF.js;用户若需 vs PDF.js 直接对比需自行基准测试";目前 §六坑与注意 5 "官方声称同主机 warm 场景比 PDF.js 快 ≥10×" 把"官方声称"作为免责,但前置事实本身错位 —— 应批判性标注对照基线 1)。
  2. 迁移史表述混淆的批判缺位(P0 项 4 已证):"从 TypeScript/PDF.js 迁移" 应批判性拆解为 "从 Citra 自家 TS 版 3.0.14 迁到 Sole-Rust 4.1.0(不是从 PDF.js 迁到 Rust);Mozilla PDF.js 是独立项目,与 Citra 无直接继承关系";接力棒引用时若误传为"Citra 是 PDF.js 的 Rust 重写"会失真。
  3. @sylphx/pdf-reader-mcp "已废弃" 表述过度的批判缺位(P0 项 6 已证):攻略应批判性区分 "canonical 推荐使用 @sylphx/citra + @sylphx/pdf-reader-mcp TS 版 3.x 已不推荐 + @sylphx/pdf-reader-mcp Rust 版 4.x 仍可作为过渡包使用",而不是一句"已废弃"。
  4. persistent_warm 出处不明的批判缺位(P0 项 7 已证):攻略应批判性标注 "⚠️ 该名称未在 SylphxAI README + PluginBench 文档显式提及,可能为 SDK 内部选项或作者自创,具体行为以实际调用为准",而不是未注明出处。
  5. OCR fail-closed 缺位的批判缺位(P0 项 8 已证):攻略应批判性区分 "Citra 在 native binary 缺失时 fail-closed + 在 OCR 失败时仍可能返回空/部分文本(非 fail-closed)",而不是把 fail-closed 设计延伸到 OCR 失败场景。
  6. "最干净 PDF MCP 方案"营销话术的批判缺位(对照 Glama 2026-09 20 候选):应改为"对比项 (本地优先 + 证据契约 + 零配置) 三个交叉维度上最完整的方案",而不是"最干净"这种无对照测试数据的定性结论。
  7. linux-musl 兼容性的批判缺位:攻略应批判性标注 "Citra 官方仅提供 linux-x64-gnu / linux-arm64-gnu 两个 gnu 变体,Alpine(musl)用户需自行编译或选 gnu 兼容层",而不是只在 §六坑与注意 1 模糊提一句"gnu vs musl 问题"。
  8. PDF MCP 候选数量激增的批判缺位(对照 Glama 2026-09):"20 Best PDF MCP Servers" 列出 20 个候选,作者应批判性承认"市场上有多个 PDF MCP 候选(pdf-mcp / Stryker / Anthropic PDF MCP / @modelcontextprotocol/pdf-reader 等),Citra 的差异化是 evidence contract 而非 PDF 解析本身",而不是把 PDF.js 作为唯一对照基线。
  9. 攻略标题写 SylphxAI/citra 但链接实际仓库是 SylphxAI/pdf-reader-mcp 的批判缺位(P0 项 1 已证):攻略应批判性标注"产品名 Citra + canonical 仓 SylphxAI/pdf-reader-mcp + canonical npm 包 @sylphx/citra",而不是标题写错。
  10. 证据契约概念归属的批判缺位:SylphxAI 官方在 docs/EVIDENCE_CONTRACT.md + docs/POSITIONING.md + docs/COMPETITIVE.md 中有完整论述,作者应在 §二 §七 引用这些官方文档(而不是只引用 README 主页面),接力棒接手时若需深入证据契约设计理念可直接查 docs/EVIDENCE_CONTRACT.md。

4. 可执行的修改建议(按优先级)

4.1 P0 立即修改

  1. §〇 顶部元数据"链接":改为 https://github.com/SylphxAI/pdf-reader-mcp(canonical 仓),并加 "(canonical 仓;npm canonical 包为 @sylphx/citra)" 标注。
  2. §一 是什么 末段:把"底层用 Native Rust 重写(2024 年中从 TypeScript/PDF.js 迁移)"改为"底层用 Native Rust 重写;Sole-Rust 4.1.0 lineage 起,Canonical npm 包为 @sylphx/citra(此前为 TypeScript 实现的 Historical TS 3.0.14)";删除"从 PDF.js 迁移"表述。
  3. §六坑与注意 5 "比 PDF.js 快 ≥10×":改为"官方声称同主机 warm 场景比自家 TS 版 3.0.14 快 ≥10×(中位数);官方未发布 vs Mozilla PDF.js 的对比数据;性能数据在 docs/specs/performance/ 目录有详细测量报告,有异议可自行复现"。

4.2 P1 高优修改

  1. §三 平台原生包表:加 linux-musl 用户警告脚注:"⚠️ 官方仅提供 gnu 变体;Alpine/musl 用户需自行编译或选 gnu 兼容层"。
  2. §四 工具三 pdf_evidence JSON 示例:加 ⚠️ 标注"⚠️ 参数示意,具体 schema 见 @sylphx/citra SDK 文档"。
  3. §六坑与注意 4 "persistent_warm 模式":加 ⚠️ 标注"⚠️ 该名称未在 SylphxAI 官方 README + PluginBench 文档显式提及,可能为 SDK 内部选项或作者自创,具体行为以实际调用为准"。
  4. §七 与同类对比表 "PDF.js (Mozilla)" 列:加脚注"⚠️ 官方性能表只对比 Citra 自家 TS 版 3.0.14 vs Sole-Rust 4.1.0,不是 vs Mozilla PDF.js;Mozilla PDF.js 是独立项目,Citra 与 PDF.js 的直接对比官方未发布"。
  5. §七 与同类对比表:加脚注"Glama 2026-09 '20 Best PDF MCP Servers, Compared' 列出 pdf-mcp(77 stars / uvx / 5 tools / Gluma avg 47 days commit)排名第二,本攻略不展开对照"。

4.3 P2 中优修改

  1. §一 是什么 旧包描述:"@sylphx/pdf-reader-mcp(已废弃,TS 版)"改为"@sylphx/pdf-reader-mcp(TS 版 3.x 已不推荐;Rust 版 4.x 仍可作为过渡包使用,canonical 推荐 @sylphx/citra)"。
  2. §二 痛点 → 答案 对照表:"OCR 路径与原文证据链接,不返回无来源文本"改为"OCR 文本绑定页+坐标,可被引注溯源"。
  3. §六坑与注意 2 "约 20 MB":改为"multi-MB 级别(官方 README 称 multi-megabyte),具体数值因平台而异(macOS/Linux x64 通常 15-25 MB)"或加 ⚠️ 标注。
  4. §六坑与注意 6 "npm 包本身约 77 KB":改为"主包 ~77 KB + 平台 native 二进制多 MB,总计 ~24 MB 含 node_modules;离线环境需提前打包好对应平台的 native"。

4.4 P3 低优修改

  1. §五 第 5 类"证据驱动的工作流":加 ⚠️ 标注"⚠️ 本类为作者推论,基于 evidence contract 设计理念;官方 README 'Flagship use cases' 列 4 类,本攻略将'证据驱动'独立成第 5 类"或并入 §五 第 4 类。
  2. §四 SDK 用法示例:加 @sylphx/citra/pure-rust low-level client helpers 一行(PluginBench 已确认)。
  3. §三 或 §四 末尾:加 MCP identifier io.github.SylphxAI/citra 标注(接力棒接手时若需 MCP server identifier 可直接查)。
  4. §八 一句话结论:"目前最干净的 PDF MCP 方案"改为"目前本地优先 + 证据契约 + 零配置这三个交叉维度上最完整的 PDF MCP 方案"。
  5. §〇 顶部元数据"分类":加"工作流:RAG 文档预处理"子标签(Gluma 把 Citra 归入 document-intelligence 类)。
  6. §二 §七 引用源:在末尾加 docs/POSITIONING.md + docs/EVIDENCE_CONTRACT.md + docs/COMPETITIVE.md 三个官方文档链接(SylphxAI 官方仓库有完整论述)。

5. 总评

Tom 这份 Citra 攻略在结构完整性 + 主核事实准确性 + 实战经验敏感性 三个维度均达到 organized/guides/ 同类攻略的稳定水平;主核事实(GitHub stars 935 / MIT / canonical @sylphx/citra / v5.0.0 / Native Rust / fail-closed / 三件工具名 / SDK 对应 / 安装体积 77 KB + 24 MB)经独立 web 验证全过;攻略式八段结构(是什么 / 解决什么问题 / 安装 / 用法 / 场景 / 坑 / 对比 / 一句话)与同类攻略骨架一致,接力棒接手时可按段定位信息。

主要扣分点是"性能对照基线错位"和"迁移史表述混淆"两处 P0 事实表述问题 —— Tom 写成"比 PDF.js 快 ≥10×"实际官方对比对象是 Citra 自家 TS 版,不是 Mozilla PDF.js;Tom 写成"从 TypeScript/PDF.js 迁移"实际官方迁移史是 Citra 自家 TS 版 → Citra Sole-Rust 版,不是从 PDF.js 迁到 Rust;这两处 P0 错位若不修正,接力棒直接引用会误传"PDF.js vs Citra"和"PDF.js → Rust 重写"两个错误叙事。

次要扣分点是"@sylphx/pdf-reader-mcp 已废弃" 表述过度 + persistent_warm 出处不明 + OCR '不返回无来源文本' 表述夸大 + linux-musl 兼容性缺位 + Glama 20 候选对照缺位 + §八 '最干净' 营销话术" —— 这些 P1-P2 问题需要在二次精修时处理,但不影响攻略的整体可用性。

接力棒接手建议: 1. 优先采纳 P0 三处立即修改(链接 / 迁移史 / 性能基线) —— 这三处是事实表述错位,不修会失真; 2. 次优采纳 P1 五处高优修改(linux-musl 警告 / pdf_evidence 参数标注 / persistent_warm 出处 / PDF.js 对照脚注 / pdf-mcp 排名第二脚注) —— 这些是用户体验与可验证性改进; 3. 可选采纳 P3 五处低优修改(证据驱动推论标注 / pure-rust helper / MCP identifier / 一句话结论 / 分类子标签 / 官方文档链接) —— 这些是细节完善; 4. 跨棒联动:本攻略发布后,建议在工作流"RAG 文档预处理"维度下加 §2.16.4 "PDF MCP(Citra · 5.0.0 · SylphxAI/pdf-reader-mcp · @sylphx/citra)" 子条目,与 rag.md §2.16 文档解析主轴对齐; 5. 跨棒核实:接力棒接手时可独立 web 验证(github.com/SylphxAI/pdf-reader-mcp + npmjs.com/@sylphx/citra + glama.ai/mcp/best/pdf)三个一级来源,以及 docs/POSITIONING.md + docs/EVIDENCE_CONTRACT.md + docs/COMPETITIVE.md 三个官方文档作为二级证据; 6. 若需 vs PDF.js 直接对比(用户问"用 Citra 还是 PDF.js?"):官方未发布对比数据,接力棒应建议用户自行基准测试或参考 Glama 2026-09 评测,而不是引用 Tom 攻略"比 PDF.js 快 ≥10×"(该表述经本次评审已判定为误传)。

整体评分 7/10 —— 结构完整 + 主核准确 + 实战敏感,但有 2 处 P0 事实表述错位需立即修正 + 多处 P1-P2 细节需精修;接力棒接手本攻略前必须采纳 P0 三处立即修改,否则会传播"PDF.js vs Citra"和"PDF.js → Rust 重写"两个错误叙事。

评审时间:2026-09-22 14:30 (Asia/Shanghai) 评审人:spark 被评对象:Tom @ organized/guides/sylphxai-citra.md (2026-09-22) 评审依据:SylphxAI 官方 README (github.com/SylphxAI/pdf-reader-mcp) + PluginBench 第三方评测 + glama.ai 2026-09 PDF MCP 评测 + 攻略全文 + work-queue 4.1 Tom 认领登记 评审范围:事实准确性 / 深度 / 误导性 / 可读性 / 与最新进展的差距 评审结论:7/10 —— 结构完整 + 主核准确 + 实战敏感;P0 三处事实表述错位需立即修正(链接 / 迁移史 / 性能基线)