为什么做 MEFinder？
我是一名在读文科硕士生。以前写小论文，每到定稿前，都要把正文里的引文一条条重新核对：原文有没有抄错，出处有没有写对，页码准不准，我对上下文的理解有没有偏差。写作的时候，我也常常明明记得某个观点、某段大意，却一时想不起原句到底怎么写、藏在哪份文献里。
现在写大论文，文献更多了。我常常要在好几个 PDF 之间来回切换，反复打开、搜索、翻页、核对。被这些麻烦反复折腾之后，我开始想：如果有一个工具，能把自己的文献都放在一起，既能凭记得的片段找回原句，也能根据论文里的引文找到出处、上下文和页码，会不会省下很多时间？
我找了一圈，没发现真正贴合这种需求的软件，于是决定自己动手做一个。MEFinder 就这样开始了。
无论你交给它的是完整的原句、残缺的片段，还是带着错字漏字的只言片语，它都会在你的本地文献库里找回原文，带你回到上下文和原始页面，并把出处整理好，方便你继续核对、复制。
它不会替你“猜”引文来自哪里，也不会编一个像模像样的答案来糊弄你。搜索、索引、页码映射和大部分元数据处理，默认都在本机完成；只有扫描件、文本层乱码或版面复杂的 PDF 确实需要解析时，才由你决定是否交给 MinerU 或其他视觉服务。
这也是我第一次完整地做完一个软件项目，一路上磕磕绊绊，很多东西都是边做边学，MEFinder 也还在继续完善。如果它没找到你确定存在的句子，或者页码、题录处理得不对，欢迎附上具体样例来提交 Issue。感谢大家愿意试用，不足之处还请多多包涵。
如果 MEFinder 恰好能帮你少翻几次 PDF、少花点核对引文的时间，欢迎顺手点个 Star 🌟。对第一次做开源项目的我来说，你的支持会是很大的鼓励，也会让我更有动力继续把它做好。
✨ 主要功能
| 功能 | 能做什么 |
|---|
| 原句定位 | 输入完整原句、残句或带少量错字、漏字的文本，通过自动、精确、忽略空格、忽略标点和模糊模式定位原文。 |
| 上下文 / 页码定位 | 查看命中位置的前后文，区分 PDF 物理页与书内引用页码；支持自动映射和人工分段校准。 |
| PDF / Word / EPUB / 扫描件 | Word、EPUB 和文本型 PDF 在本机解析；EPUB 保留出版方 page-list/pagebreak 页码；扫描版、乱码文本层与复杂布局 PDF 可按需接入 MinerU、本机 OCR 或视觉模型。 |
| 本机 OCR（离线） | 「设置 → 本地 OCR」安装组件后，日文扫描件走 NDL 日文 OCR，日文古籍与繁体竖排古籍走 NDL 古籍 OCR；不提供现代中文 OCR，也不生成屏幕重排页码。 |
| 繁体竖排 / 外部解析结果 | 可继续检索已经由 OCR、MinerU 或其他工具解析的繁体竖排、影印本等材料，并结合页码信息定位。 |
| 繁简统一检索 | 「设置 → 阅读与检索 → 文献检索」开关，默认开启；简体关键词可命中繁体原文，结果、页码与导出保留原文。 |
| 结构化阅读 | 从搜索结果直接打开结构化文本，查看命中段落、相邻内容与原始 PDF 页面；工具栏目录读取已入库的一、二级标题，点击章节可同步定位对照版本。 |
| 译本 / 版本对照 | 把同一作品的原文、译本或不同版本归入作品组，选两个版本自动逐段对齐，双栏对照阅读并在版本间定位对应文字；对齐在本机完成，支持 PDF 和 EPUB 格式。每对版本可查看并人工修正正文范围，失效对齐可一次全部重新对齐。 |
| Zotero 来源同步（0.5.7） | 「设置 → 来源 → Zotero」勾选 Zotero 分类，MEFinder 读取 Zotero 7 自带的本机只读接口，把其中的 PDF / EPUB 走自己的解析管线入库；增删与题录以 Zotero 为准（含茉莉花插件抓取的知网题录），不读 Zotero 全文索引、不改 Zotero 库。 |
| 题录补全 / 五种出处格式 | 识别并补全图书、译著、期刊和学位论文题录；支持中文脚注、GB/T 7714、APA、MLA、Chicago。 |
| 文档包传输 | 把已入库 PDF 连同页级文本、书目和页码映射导出为 .mefinder，换设备后重新导入就能恢复，不用重新 OCR。 |
| 按页导出 Markdown | 文献库菜单可按原书页码或 PDF 物理页码导出指定页；PDF 已配对脚注随正文带出。EPUB 依赖出版方页码，页外脚注暂不保证。 |
| 独立阅读窗口 | 在「设置 → 阅读与检索 → 阅读窗口」开启“在独立窗口中阅读”（默认关闭）；结构化阅读和译本对照可在独立窗口中单独移动和缩放，关闭时仍在主窗口内阅读。 |
| 引文核对 / 主题检索 / 对齐修正（MCP） | 让支持 MCP 的 AI 助手访问文献库：批量核对引文是否逐字命中、逐字比对错引差异、按主题召回相关段落、读取版权页与题录缺口；还可辅助标注并修正自动译本对齐。 |
🎯 适合什么场景
- 写论文时只记得一句话，却忘了出自哪本书、哪一页；
- AI 给的引文、笔记或文档里摘的句子，想回到原文确认一下；
- 本地攒了一堆 PDF / Word / EPUB，不想一本本打开挨个
Ctrl + F；
- 扫描书、影印本、繁体竖排材料已经做过 OCR，希望统一检索；
- 搜到原句后还想接着看上下文、翻到原页、顺手复制规范出处；
- PDF 的“第 48 页”实际对应书内“第 1 页”，需要分别管理物理页与引用页码。
⚙️ 工作原理
flowchart LR
A[Word / PDF / EPUB] --> B{可直接读取文本?}
B -->|是| C[本地解析]
B -->|否| D[OCR / MinerU / Vision API]
C --> E[本地 SQLite 文献库]
D --> E
E --> F[FTS5 trigram 全文索引]
F --> G[原句检索]
G --> H[上下文 / 结构化阅读]
G --> I[物理页 / 引用页码]
G --> J[题录 / 出处格式化]
MEFinder 使用本地 SQLite 数据库和 FTS5 trigram 全文索引保存来源、文献、段落、原始文本与页码映射。搜索时不需要向量数据库、Embedding 或 LLM API。
原生文本 PDF 优先由 PyMuPDF 读取，Word 和 EPUB 文献走本地解析。EPUB 按 OPF spine 的阅读顺序提取正文，只采用出版方提供的 page-list/pagebreak 页码。只有扫描版、乱码文本层或复杂布局 PDF 需要 OCR / 视觉解析，可选在线 MinerU、本机 OCR 组件或视觉模型；只有你主动使用在线解析时，待处理的页面才会被上传。
页码系统同时保留 PDF 物理页与正式引用页码。自动映射无法可靠判断时，可以人工分段校准；没校准过的页码不会被当成正式引用页码。
⬇️ 下载
正式发布包都在 GitHub Releases，普通用户不需要安装 Python。
| 平台 | 版本 | 发布包 |
|---|
| Windows | 安装版（推荐） | MEFinder-v<版本>-windows-setup.exe |
| Windows | 绿色免安装版 | MEFinder-v<版本>-windows-portable.zip |
| macOS | Apple Silicon | MEFinder-v<版本>-macos-arm64.dmg |
| macOS | Apple Silicon（备用） | MEFinder-v<版本>-macos-arm64.zip |
| macOS | Intel | MEFinder-v<版本>-macos-x86_64.dmg |
| macOS | Intel（备用） | MEFinder-v<版本>-macos-x86_64.zip |
Windows
- 支持 Windows 10 21H2 及以上系统；
- 安装版支持应用内检查更新，用户数据默认保存在
%LOCALAPPDATA%\MEFinder；
- 绿色版完整解压后双击
文献原句定位器.exe，程序、文献、索引、设置和日志均保存在解压目录；
- 未签名的发布包可能触发 Windows SmartScreen 提示。
macOS
- Apple Silicon（
arm64）支持 macOS 14 或更高版本；
- Intel（
x86_64）支持 macOS 12 或更高版本；
- 根据 Mac 芯片选择 Apple Silicon（
arm64）或 Intel（x86_64）DMG；
- 打开 DMG 后将
MEFinder.app 拖入 Applications；
- 应用数据保存在
~/Library/Application Support/MEFinder/。
Homebrew（可选）：已安装 Homebrew 的用户可以用 Cask 安装并跟进更新：
brew trust sabercomo/mefinder # 新版 Homebrew 要求先信任第三方 tap
brew tap sabercomo/mefinder
brew install --cask mefinder
之后用 brew update && brew upgrade --cask mefinder 升级。Homebrew 渠道要求 macOS 14 及以上（两架构取较严门槛；Intel 机若是 macOS 12–13，请直接下载 DMG 安装）。应用未经 Apple 公证：首次启动若被拦截，在「系统设置 → 隐私与安全性 → 仍要打开」批准一次即可，之后的升级会延续已批准状态。brew uninstall --cask mefinder 不影响文献数据。
桌面应用可在「设置 → 数据位置」打开已有 MEFinder 资料库（例如从另一台电脑同步的文件夹），或迁移当前资料到新位置。两种操作均在重启后生效；打开已有库不复制或覆盖资料。跨设备使用云盘库时，先退出另一端并等待同步完成。
「设置 → 关于与更新」显示当前版本，提供官方网站、更新日志、最近更新与 GitHub Star 入口。Windows 安装版可检查、下载并确认安装更新；Mac 可手动检查并前往下载 DMG，通过 Homebrew 安装的用户也可在这里复制更新命令。
📖 快速开始
-
导入文献
打开左侧“文献导入”，选择或拖入 PDF / Word / EPUB。原生文本文件会直接进入本地索引；扫描、乱码或复杂布局 PDF 会提示选择解析方式。
-
搜索原句
输入完整句子或片段，选择综合、精确或模糊检索，也可以限定 Word、PDF 或指定文献范围。
-
查看原文
在结果中查看命中内容与上下文，打开结构化文本，或跳转到原始 PDF 的对应物理页。
-
校准引用页码
如果 PDF 封面、目录等导致物理页与书内页码不一致，可建立分段映射。例如：
PDF 起始页：48
引用起始页：1
-
复制出处
选择中文脚注、GB/T 7714、APA、MLA 或 Chicago，然后复制当前文献的规范出处。关键元数据或页码缺失时，程序会明确提示。
配置 MinerU API（可选）
扫描版、乱码文本层或复杂排版 PDF 会交给 MinerU 在线解析。先到 MinerU 申请 API Token（先登录，再申请）拿到 Token，再到软件里填：
- 打开 设置 → MinerU API，进去就是填写表单，其他保持默认就行；
- 把申请到的 API Token 粘贴进输入框；
- 到期日期选填，拿不准就留空。建议填上：免费 Key 一般只有三个月有效期，填了以后账号列表里会显示剩余天数，过期了也看得出来；
- 点 保存配置；
- 保存后账号出现在列表里，点 测试，显示连接成功就行。
导入扫描 PDF 时选 强制 MinerU，或者保留默认的 自动选择——文字层不可靠时程序会自动改用 MinerU。
不想用 MinerU 的话，也能在 设置 → 其他解析 API 里添加 OpenAI 兼容的视觉模型或中转接口，导入时选 其他视觉 API。
自己部署的 MinerU 也能用：在 设置 → MinerU API 把“服务地址”改成你的部署地址即可，MEFinder 会自动检测接口版本，也可以在设置中手动锁定协议。服务端启用了 API key 时在这里配置。
译本对照
同一部作品的原文、译本和不同版本可以自动对齐后对照阅读：
- 在文献库勾选同一部作品的原文、译本或不同版本，点击 加入作品…，新建作品或加入已有作品（第一本默认作为基准版本；一本书只属于一个作品）。
- 打开左侧栏的 译本对照，作品的版本清单里逐对直接标出对齐状态与匹配段落比例：尚未对齐时点 生成对齐，已有对齐时点 对照阅读。版本改名、增减、换基准和删除作品都在 管理版本 里；存在失效对齐时，作品列表顶部会给出「N 组对齐需重新生成 · 全部重新对齐」，按原对齐方向逐组重算，可随时停止。
- 自动识别的正文首尾可能有偏移：每对版本的 正文范围 入口把两书并排显示各自的开头与结尾，可按目录章节、PDF 页码或文本段序号定位；两侧独立调整，保存范围并重新对齐 一次写入两端并重算这一对。
- 阅读器里可以随时 添加对照版本 或关闭对照；滚动左栏时右栏跟随并高亮对应段落，点一段原文可查看它的对应段；算法置信度偏低的段落旁有 !，可以人工勾选对应的译文段（支持一对多）、标记译本无对应或暂不处理。检索结果和文献库也进入同一个阅读器。
生成对齐时显示当前阶段的百分比、进度条与预计剩余时间；时间根据实际处理速度估算，仅指当前阶段。加载模型、检查和保存结果时显示阶段说明，缓存命中时跳过文本计算。
对齐组件卸载后，已有对齐仍可只读阅读，生成新对齐需要重新安装。页面上的「已匹配段落」只表示算法找到对应的段落比例，不代表对应一定准确。
对齐会综合跨语言语义和章节结构，一句对应多句的情况也能处理，全部在本机计算，不上传文献内容；首次生成对齐前，需在 设置 → 译本对齐 安装独立计算运行时并下载跨语言语义模型（一次性联网，默认优先国内镜像，失败自动回退官方源），装好后计算全程离线、任务中途不联网。当前一次只对照两个版本，不提供三栏对照；自动对齐用于辅助定位，不能代替对原文和译文的人工核对。
文档包导出 / 导入（0.4.4）
解析结果可以随身带走，换台电脑也不用重新 OCR：
- 导出：选中一本或多本已入库 PDF，在设置 → 文档传输里选择“仅文档数据”（页级文本、书目、页码映射，文件小）或“文档包＋原 PDF”（跨设备推荐，导入后可直接打开原文），导出为
.mefinder。当前版本只导出 PDF 文献，批量操作会跳过 Word 与 EPUB。
- 导入：把
.mefinder 拖进导入页就行，旧 .mefinder.zip 也支持导入。程序会恢复书目、页码和索引；包内含原 PDF 时一并恢复，不需要重新解析。
- 完整性校验：包内原 PDF 会核对大小和 SHA-256；校验不一致时拒绝恢复该 PDF。文档包未做数字签名，不能据此判断来源真实性。
MCP 文献核对（0.5.1，可选集成）
提供十七个 MCP 工具，让支持 MCP 的 AI 助手直接访问你的文献库，覆盖定位、阅读结构、页码映射、跨译本对照、核对、检索、题录与书目补全，以及人工对齐修正：
- 定位与阅读：
list_documents 列出已导入文献并返回稳定 ID，同时标出所属作品及组内哪些版本已完成对齐；locate_quote 定位引文原文、上下文与页码状态；list_sections 列出与阅读器目录同源的章节及其位置范围；read_document_window 按物理页或段落读取有界文本窗口，也可按章节逐节读取。
- 页码映射：
describe_page_mapping 按连续区间说明一篇文献哪些位置有可引用页码、映射方法，扫描件缺了哪些印刷页，以及页内文字是否已核准为该页印的文字；引用页码就是书上印的页码，不需要与 PDF 页换算。只读已入库映射，不运行自动检测，未校准的区间如实标为 uncalibrated。
- 引文核对：
verify_quotes 一次批量核对多条引文是否逐字命中（verified / approximate / not_found），并给出每个命中所在的章节标题路径，便于核对语境，diff_quote 把疑似错引与最接近的原句逐字符对齐，标注增、漏、改的差异。
- 主题检索：
search_passages 按自然语言描述或关键词按相关性召回相关段落，适合只记得大意、无法逐字引用时找回原文（是相关性检索，命中不代表逐字一致）。
- 译本 / 原文对照：
find_parallel_passages 接收一句中文或任一版本的句子，以作品组已生成的对齐为中心返回英文、原文或其他译本的多个附近候选、定位及前后文；调用它的 Agent 再依据跨语言语义、专名、引文结构和上下文校准。只有唯一候选证据充分时才确认，仍有歧义或证据不足时必须明确说明；可按目标语言或具体版本收窄，不现场机器翻译，也不改写已有对齐。
- 题录：
read_bibliographic_pages 读取版权页 / CIP 页等候选文本供提取题录，read_bibliographic_metadata 列出现有题录字段并标注已填 / 存疑 / 缺失。AI 从原书版权页读出题录后，可用 propose_bibliographic_update 提议补全（附原书依据与页码，只填空字段，已有值不覆盖），经你明确确认后调用 confirm_bibliographic_update；确认后由桌面端按人工保存的同一流程写入（运行中几秒内，未运行则下次启动时）。
- 人工对齐修正：
list_alignment_corrections 列出已记录的人工修正供复核；当 find_parallel_passages 的自动对齐指向错误译文段时，AI 可用 propose_alignment_correction 提议修正，经你明确确认后调用 confirm_alignment_correction 生效；revoke_alignment_correction 可随时撤销已有修正并恢复自动对齐。提议不改变任何查询结果，必须由你确认后才会生效。
十七个工具中有十二个只读，五个为写操作：书目补全的 propose / confirm，与人工对齐修正的 propose / confirm / revoke，均须经用户确认。工具本身不提供问答、总结或翻译等生成功能。Windows 安装版、绿色版和 macOS 发布包都包含独立 MEFinderMCP sidecar，不用装 Python；源码模式也可单独接入。桌面窗口无需保持开启，MCP 进程本身不联网。
需要选择的是 MEFinderMCP.exe，不是桌面主程序。Windows 安装版通常位于：
C:\Users\<你的用户名>\AppData\Local\Programs\MEFinder\MEFinderMCP.exe
绿色版则用解压目录里的 MEFinderMCP.exe，例如 D:\MEFinder\MEFinderMCP.exe。它走本地 STDIO 协议，不用手动双击，客户端会自动启动它。
Codex（Windows）
打开 设置 → 插件 → MCP → 添加 → 添加 MCP 服务器，填写：
| 项目 | 内容 |
|---|
| 名称 | mefinder |
| 类型 | STDIO |
| 启动命令 | MEFinderMCP.exe 的完整路径 |
| 参数、环境变量 | 留空 |
| 工作目录 | MEFinderMCP.exe 所在文件夹 |
保存后重启或重新加载 MCP，然后让 Codex 试试，比如说：“请只使用 mefinder 搜索这句话来自哪篇文献、哪一页。”
Claude Code（Windows）
打开 PowerShell（按 Win + R 输入 powershell 回车），粘贴下面这条命令，把路径换成自己的：
claude mcp add --transport stdio --scope user mefinder -- "D:\MEFinder\MEFinderMCP.exe"
claude mcp list
WorkBuddy（Windows）
进入 WorkBuddy 后，依次点击：
连应用 → 更多连接器 → 自定义连接器 → 配置 MCP
WorkBuddy 的部分教程以 Streamable HTTP 为例；MEFinder 使用本地 STDIO MCP，不需要填写 URL 或 Headers。
在 MCP 配置中加入：
{
"mcpServers": {
"mefinder": {
"type": "stdio",
"command": "D:\\MEFinder\\MEFinderMCP.exe",
"args": []
}
}
}
把 command 里的路径换成你电脑上 MEFinderMCP.exe 的实际位置。Windows 安装版和绿色版的配置方式相同，区别只有 MEFinderMCP.exe 所在路径不同。
例如实际路径是：
D:\MEFinder\MEFinderMCP.exe
在 JSON 中需要写成：
D:\\MEFinder\\MEFinderMCP.exe
保存后返回 MCP 服务管理，在“我的 MCP”中找到 mefinder 并确认已经启用。连接成功后就能在 WorkBuddy 里直接调用 MEFinder。
Windows 的完整操作、macOS 三客户端配置和常见错误见 Windows/macOS MCP 配置教程；源码模式和 Codex 高级排错见 Codex MCP 配置、健康检查与隐私说明。返回给 AI 的命中原文和上下文会进入相应客户端的对话及模型上下文，涉及未公开文献时请留意。
⚠️ 已知限制
- 导入按固定大小分块进行，不限制单个文件总大小；超大型 PDF 会按解析服务能力切片处理；
- 纯扫描、乱码文本层和复杂排版 PDF 依赖 OCR / AI 解析（在线 MinerU、本机 OCR 组件或视觉模型），检索质量受上游结果影响；
- 原书没有印刷页码时，可以定位 PDF 物理页，但不会生成不存在的书内页码；
- DOCX 页码依赖文档分节和页面结构，导入后建议人工抽样核验；
- EPUB 只有在出版方提供 page-list 或 pagebreak 时才有可引用页码；阅读器随字号生成的动态页数不会写入索引；
- EPUB 暂不支持按页跳转，有出版方页码也只按目录与文本段序号定位；
- 0.5.5 起数据库升级到 v7，0.5.7 起升级到 v8（新增 Zotero 关联表），旧版本无法打开升级后的库。若需保留降级能力，请在升级前彻底退出应用并完整备份数据目录；设置中的「导出备份」仅含页码、书目和偏好，不含 PDF 与索引库，不能替代整目录备份；
- 旧版二进制 DOC 的页码精度有限，部分情况下只能显示目录页码范围；
- 未校准的 PDF 会显示“引用页码尚未校准”，不会用 PDF 页序冒充正式页码；
- 跨页搜索通过相邻页窗口实现，结果会返回起始页和结束页；
- MinerU 和其他在线视觉解析依赖网络与有效凭据，本地搜索和索引不依赖这些服务。
🗺️ Roadmap
- 提升超大型 PDF 导入、断点恢复与异常重试能力；
- 继续优化繁体竖排、双开页和复杂版面的页码定位；
- 扩展题录数据源与不同文献类型的自动补全能力；
- 继续完善引用核验、结构化阅读和批量资料管理；
- 持续改进 Windows / macOS 安装、签名和自动更新流程。
Roadmap 只是当前的改进方向，不代表固定发布日期；实际进度以 版本记录 和 Releases 为准。
🛠️ 开发与构建
源码模式需要 Python 3.12。requirements-core.txt 提供不含对齐计算栈的后端依赖；需要离线生成对照时再安装 requirements-alignment.txt，并在设置中下载模型。缺少计算组件仍可搜索、结构化阅读和查看已有对照。桌面发布包同样不携带对齐计算栈：首次生成对齐前，需在「设置 → 译本对齐 → 独立计算运行时」联网安装一次（约 94 MiB），装好后计算全程离线、任务中途不联网。
python3 -m pip install -r requirements-core.txt
python3 -m src.me_finder build-index --include-pdf
python3 -m src.me_finder serve --host 127.0.0.1 --port 8765
运行测试：
python3 -m unittest discover
构建与发布文档：
许可证
MEFinder 自有代码依据 GNU Affero General Public License Version 3 only
发布（SPDX-License-Identifier: AGPL-3.0-only）。完整条款见 LICENSE，
发行包内第三方组件的许可证见 THIRD_PARTY_NOTICES.txt。
隐私
- 本地搜索、索引和页码映射等功能默认只在用户本机进行。
- 只有用户主动配置并调用 MinerU、视觉 API 或其他联网功能时，相关数据才会发送到用户所选择的第三方服务。
- API 密钥保存在本地，不随安装包分发。
- 第三方服务受各自隐私政策约束。
MEFinder 的目标很简单：让“我记得这句话，但我忘了它在哪”不再变成翻几十本书的体力活。
