Mktero：基于 MinerU API 的 Zotero Markdown 论文阅读插件

[tenglvjun]

大家好，我开发了一个开源 Zotero 插件 Mktero，它使用 MinerU API 将 Zotero 中的 PDF 附件转换为 Markdown，并直接在 Zotero 标签页中提供重排阅读体验。

项目地址：

https://github.com/tenglvjun/mktero

最新版本：

https://github.com/tenglvjun/mktero/releases/latest

为什么做这个插件？

使用 Zotero 阅读论文时，我经常遇到双栏排版、公式、表格和图片不便连续阅读的问题。

PDF 很适合保留论文的原始版式，但在较小窗口中阅读时，经常需要上下滚动和缩放。因此，我希望在保留原始 PDF 的同时，增加一个更适合连续阅读的 Markdown 视图。

Mktero 的处理流程如下：

Zotero 本地 PDF
    -> 获取 MinerU 上传地址
    -> 上传 PDF
    -> 查询 MinerU 解析任务
    -> 下载结果压缩包
    -> 规范化并安全渲染 full.md 和图片
    -> 在 Zotero 标签页中展示

目前支持的功能

• 支持 Zotero 7、8 和 9
• 从 PDF 阅读器工具栏或文库右键菜单打开
• 使用 MinerU VLM 模型解析 PDF
• 启用公式和表格识别
• 渲染 Markdown、KaTeX 公式、表格、图片和代码块
• 自动生成可跳转的文章目录
• 识别正文中的参考文献、图片和表格引用
• 悬停预览参考文献、图片和表格
• 点击引用跳转至对应内容
• 全屏预览、缩放和拖动论文图片
• 显示 Zotero 中已有的 PDF 高亮和下划线
• 在 Markdown 正文中划词创建高亮或笔记
• 将能够可靠定位的标注同步回 Zotero PDF
• 在本地缓存 Markdown 和图片
• 恢复已经上传但尚未完成的 MinerU 任务
• 避免重复上传内容相同的 PDF
• 支持英文和简体中文界面

MinerU API 集成方式

Mktero 使用 PDF 内容的 SHA-256 和 MinerU 解析配置标识转换结果。

如果 PDF 已经上传，但 MinerU 尚未返回最终结果，Mktero 会在本地保存 MinerU batchID、插件生成的 dataID 和上传时间。

用户关闭 Mktero 标签页或重启 Zotero 后，再次打开相同 PDF 时，插件会继续查询原来的任务，而不是重新上传文件。

转换完成后，Mktero 会下载结果压缩包并读取其中的 full.md。目前支持加载压缩包中的 GIF、JPEG、PNG 和 WebP 图片。

在 Zotero 中展示前，插件还会处理以下安全边界：

• 规范化压缩包路径，阻止目录逃逸
• 限制压缩包、Markdown、图片和公式的资源大小
• 转义不受支持的原始 HTML
• 清理 MinerU 表格中的标签和属性
• 禁止加载 Markdown 中的远程图片
• 限制可以打开的链接协议

本地缓存和任务恢复

转换成功后，Mktero 会将 Markdown 和图片缓存在当前 Zotero 配置目录中。

再次打开内容和解析配置相同的 PDF 时，可以直接读取本地缓存，不再上传 PDF 或等待 MinerU 解析。

任务恢复与已完成结果缓存是相互独立的。即使用户关闭结果缓存，也不会重复提交仍然可以恢复的 MinerU 任务。

用户也可以主动点击 Markdown 阅读页中的刷新按钮，忽略缓存并重新解析当前 PDF。

隐私说明

缓存未命中时，Mktero 会将完整 PDF 上传到 MinerU。

以下内容保存在当前 Zotero 配置目录中，目前没有加密：

• MinerU API Token
• 转换后的 Markdown 和图片
• 用于恢复任务的 MinerU batchID、dataID 和上传时间
• 尚未同步到 Zotero 的临时 Markdown 标注

Zotero PDF 标注不会发送给 MinerU，也不会写入 Mktero 的 Markdown 缓存。

如果 PDF 包含敏感、保密或不适合上传第三方服务的内容，不建议使用 Mktero 处理。

当前限制

• 只支持已经下载到本机的 Zotero PDF 附件
• Markdown 文档本身是只读视图
• OCR、公式和版面解析质量取决于 MinerU
• PDF 文本层与 MinerU 结果差异较大时，部分标注可能无法匹配
• 暂时不显示图片、区域、手写和独立便签类 PDF 标注
• 文件大小、页数、账户额度和服务可用性由 MinerU API 决定

希望获得的反馈

Mktero 当前版本是 v0.2.3。我希望向 MinerU 的开发者和用户了解：

• 当前 API 调用流程是否符合推荐实践？
• 任务恢复方式是否合理？
• 是否有更合适的任务唯一标识方案？
• 哪类 PDF 或版面容易暴露解析问题？
• 公式、表格、图片和参考文献结果是否存在需要特殊处理的格式？
• API 响应结构或结果压缩包格式未来是否可能调整？
• MinerU Token 的首次配置流程是否足够清楚？
• MinerU 还有哪些能力适合用于 Zotero 论文阅读场景？

如果测试过程中遇到问题，欢迎提供 Zotero 版本、Mktero 版本和出现问题时的转换阶段。

请不要在 Discussion 或 Issue 中公开 API Token、预签名上传地址、认证后的原始 API 响应或包含隐私的 PDF 内容。

Mktero 使用 MIT License 开源。

项目与完整文档：

https://github.com/tenglvjun/mktero

问题反馈：

https://github.com/tenglvjun/mktero/issues

感谢 MinerU 团队提供 PDF 解析能力，也欢迎大家对当前集成方式提出建议。