MaimemoPDF

MaimemoPDF 是一个面向 Linux/Wayland 的桌面工具：它为扫描版 PDF 生成可搜索的 OCR 副本，并把 Zathura 中划选的单词或短语通过墨墨开放 API 加入学习计划。

功能

• GTK4/libadwaita 原生设置界面。
• 自动检查 PDF 是否存在文字层，以及是否限制复制。
• 使用 Poppler + Tesseract 逐页 OCR，原始 PDF 永不改写。
• OCR 结果按源文件哈希缓存，可直接用 Zathura 打开。
• 在 Zathura 中划词后按可自定义的单手快捷键，编辑确认后添加到墨墨。
• 在前端创建、查看、编辑和删除墨墨云词本。
• 管理自己创建的词汇释义、助记和例句。
• 划词时可选择云词本及章节，并独立决定是否加入学习计划。
• 可配置生产、测试或自定义墨墨 API 地址、Token 和超时。
• 本地保存不含 Token 的操作历史。

系统依赖

项目不依赖 Electron，也没有必须从 PyPI 下载的运行库。Arch Linux 可使用：

图形界面最低需要 GTK 4.8 和 libadwaita 1.4。

sudo pacman -S python python-gobject gtk4 libadwaita poppler \
  tesseract tesseract-data-eng tesseract-data-chi_sim ghostscript \
  zathura zathura-pdf-poppler wl-clipboard libnotify

其中 pdfinfo、pdftotext、pdftocairo 和 pdfunite 由 Poppler 提供。

安装

./scripts/install-user.sh

安装内容位于 ~/.local/bin 和 ~/.local/share。请确保 ~/.local/bin 已加入 PATH。

niri 用户可添加下面的初始全局快捷键。也可以在应用的“选词设置”页面输入新键位并保存，应用会自动备份、修改和验证 niri 配置：

Alt+Z repeat=false hotkey-overlay-title="添加划选词到墨墨 Add selection to Maimemo" {
    spawn "/home/<你的用户名>/.local/bin/maimemo-pdf" "capture";
}

请把 <你的用户名> 替换为实际用户名；niri 的 spawn 不会展开 ~。 应用自动修改前会把原配置备份为 binds.kdl.maimemo-pdf.bak；如果 niri validate 失败，会立即恢复原文件。

使用

1. 在墨墨背单词中进入“我的 → 更多设置 → 实验功能 → 开放 API”，获取 Token，并开启自动同步。
2. 运行 maimemo-pdf，在“API 设置”中填写 Token，点击“测试连接”并保存。
3. 在“PDF / OCR”中选择 PDF。扫描件完成 OCR 后会生成可搜索副本，可直接用 Zathura 打开。
4. 在“墨墨内容”中创建云词本，或管理个人释义、助记和例句。
5. 在 Zathura 中用鼠标划选单词或短语，按当前设置的快捷键（默认 Alt+Z），选择词本和章节后确认。

墨墨开放 API 只能读取和修改你自己创建的释义、助记与例句，不能读取墨墨内置词典释义。云词本和学习计划也是两个独立对象；应用会分别执行并显示结果。

也可以使用命令行：

maimemo-pdf inspect "/path/to/file.pdf" --json
maimemo-pdf ocr "/path/to/file.pdf" --open
maimemo-pdf capture

墨墨 API 没有撤销添加端点。误加词汇需要在墨墨 App 内处理。

数据与安全

• 配置：~/.config/maimemo-pdf/config.json
• OCR 副本：~/.local/share/maimemo-pdf/ocr/
• 历史记录：~/.local/share/maimemo-pdf/history.jsonl

配置文件和历史文件权限强制为 0600。Token 按当前设计以明文保存在配置文件中；应用界面会遮挡显示，但拥有该用户文件读取权限的程序仍可读取它。

OCR 会有少量识别误差，因此添加前的编辑确认默认不能关闭。复制受限的文档仅应在你拥有相应使用权限时处理。

开发与测试

无需安装项目即可从源码运行：

PYTHONPATH=src python3 -m maimemo_pdf
PYTHONPATH=src python3 -m unittest discover -s tests -v

上传至 GitHub：

git remote add origin git@github.com:<username>/MaimemoPDF.git
git push -u origin main

许可证

MIT