内容
# 收件箱转换工具
将PDF文件放入文件夹中，几秒钟后即可获得干净的Markdown文件。完全离线操作，无需API密钥，无速率限制，无云依赖，无费用。
## 为什么需要这个工具
如果你使用LLM助手（如Claude、ChatGPT等）并将其与文件系统访问结合到Obsidian“第二大脑”工作流中，你可能会遇到这个问题：PDF文件对于这些工具来说直接读取并不可靠——工具调用失败、提取内容不完整，或者助手直接要求你手动粘贴文本。基于云的转换（如Gemini、GPT-4V等）可以解决质量问题，但需要API密钥、速率限制和计费设置，对于一个简单、枯燥、重复的任务来说，这太过复杂。
这个工具绕过了所有这些问题：一个文件夹监视器，它使用[`pymupdf4llm`](https://github.com/pymupdf/RAG)在本地将PDF转换为Markdown。无需网络调用，无需密钥，无需配额，无需计费。
## 功能描述
**可以做：** 监视一个文件夹，将出现在该文件夹中的任何`.pdf`文件转换为具有相同名称的`.md`文件，并将其放在同一文件夹中。能够较好地保留文本类PDF的标题和表格。
**不能做：** 将笔记归档到任何地方，对笔记进行分类，或对你的知识库结构做出任何决定——这是一个独立的步骤，实际上，这一步更适合你的LLM助手来完成，而不是脚本。这个工具解决了*读取*问题，而不是*组织*问题。
**不适用于：** 扫描的或纯图像的PDF（没有嵌入的文本层）——这些需要OCR，而本工具不提供。文本类PDF（大多数论文、应用程序、报告）效果良好。
## 安装和使用
在macOS、Windows和Linux上均可使用——监视器本身是用纯Python编写的。
```bash
pip install --upgrade pymupdf4llm watchdog
```
然后运行它，指向你想要监视的文件夹：
```bash
python3 pdf_inbox_watcher.py "/path/to/your/inbox"
```
保持终端窗口打开，它将持续监视。把PDF放到文件夹里，几秒钟后，旁边就会出现一个`.md`文件。
### 永久在后台运行
如果你想让它在重启后仍然运行并自动启动，请根据你的操作系统选择下面的步骤。
<details>
<summary><b>macOS (launchd)</b></summary>
1. 编辑`com.inboxingestor.watcher.plist`，将两个`REPLACE_WITH_FULL_PATH_TO`占位符替换为脚本和你的收件箱文件夹的实际路径。
2. 将其移动到位并加载它：
```bash
mkdir -p ~/Library/LaunchAgents
mv com.inboxingestor.watcher.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.inboxingestor.watcher.plist
```
(`launchctl load`在某些系统上仍然有效，但已弃用——如果它失败并出现`Input/output error`错误，请使用上面的`bootstrap`命令。)
3. 验证它是否正在运行：
```bash
launchctl list | grep inboxingestor
```
你应该在输出中看到一个实际的进程ID（而不是`-`）。
**常见问题 #1 — TCC / 完全磁盘访问权限：** 如果你的收件箱文件夹位于`Desktop`、`Documents`或`Downloads`中，macOS的隐私保护（TCC）将阻止后台进程读取它，即使你手动在终端中运行脚本时它工作正常。如果你看到`Operation not permitted`错误日志中的错误，请前往**系统设置 → 隐私和安全 → 完全磁盘访问权限**，并添加你的`python3`二进制文件。
**重要：** 找到*实际的*二进制文件，而不是符号链接——授予FDA到符号链接将静默失败。运行`which python3`，然后完全解析它：
```bash
ls -l "$(which python3)"
```
如果它显示它是一个符号链接（通常与Xcode命令行工具安装一起出现，例如`/usr/bin/python3` → `/Library/Developer/CommandLineTools/usr/bin/python3`，它通常是另一个符号链接到`.../Python3.framework/Versions/X.Y/bin/python3`），请继续跟踪链接，直到找到实际文件，并授予完全磁盘访问权限到*该*路径。最好将plist的`ProgramArguments`直接指向此完全解析的路径，以免在启动d执行的二进制文件上出现歧义。
**常见问题 #2 — 旧的/隔离的plist文件：** 如果你使用除纯文本编辑器或`cat`/shell重定向之外的工具编辑`.plist`文件（例如某些GUI工具或脚本编写器），它可能会获取`com.apple.provenance`扩展属性，导致`bootstrap`失败并出现`Input/output error`错误。请检查`xattr -l ~/Library/LaunchAgents/com.inboxingestor.watcher.plist`——如果有任何内容显示，请使用`xattr -d com.apple.provenance ~/Library/LaunchAgents/com.inboxingestor.watcher.plist`删除它，或使用`cat original.plist > ~/Library/LaunchAgents/com.inboxingestor.watcher.plist`重写文件以去除它。
要停止它：`launchctl bootout gui/$(id -u)/com.inboxingestor.watcher`
</details>
<details>
<summary><b>Windows (任务调度器)</b></summary>
1. 打开**任务调度器**（在开始菜单中搜索）。
2. **创建任务**（不是“基本任务”—你需要完整的对话框以获得更多控制）。
3. **常规选项卡：** 将其命名为类似`PDF 收件箱监视器`。如果您希望它完全在后台运行，请选中“无论用户是否登录都运行”，否则请保留默认值以便仅在您的会话中运行。
4. **触发器选项卡 → 新建：** 设置为“登录时”，以便它自动启动。
5. **操作选项卡 → 新建：**
- 程序/脚本：`python`（或来自命令提示符的`where python`的完整路径）
- 添加参数：`pdf_inbox_watcher.py "C:\path\to\your\inbox"`
- 启动于：您保存`pdf_inbox_watcher.py`的目录
6. 保存。右键单击任务并选择**运行**以立即测试它。
在任务调度器的历史记录/日志中检查任务以确认它已无错误启动。
</details>
<details>
<summary><b>Linux (systemd 用户服务)</b></summary>
1. 编辑`inbox-ingestor.service`，将占位符路径替换为脚本和收件箱文件夹的实际路径。
2. 安装为用户服务：
```bash
mkdir -p ~/.config/systemd/user
cp inbox-ingestor.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now inbox-ingestor.service
```
3. 检查它是否正在运行：
```bash
systemctl --user status inbox-ingestor.service
```
应该显示`active (running)`。
查看日志：`journalctl --user -u inbox-ingestor.service -f`
</details>
## 与LLM助手配对（这才是真正的目的）
监视器解决了转换问题。将生成的笔记归档/整理是一个单独的、需要判断的步骤——这就是您的LLM助手的作用，如果它有对您的知识库的文件系统访问权限（例如，通过MCP文件系统服务器访问Claude，或为其他工具提供类似的插件）。
一个简单的有效模式：
1. 在一周内将PDF放入您的收件箱文件夹。
2. 监视器在PDF文件到达时将其静默转换为markdown。
3. 定期打开与您的助手的会话，并说类似的话 *“处理收件箱”* - 让它读取每个转换后的文件，决定它应该成为什么样的笔记，并将其归档到您的知识库中的正确位置。
该工具的范围故意限定为可靠地完成前两个步骤，而不执行其他操作——归档逻辑位于您与助手一起使用的提示/过程文档中，因为那里需要判断，而不是在脚本中。
## 许可证
MIT — 您想怎么使用就怎么使用，只需承认我们。
ChronoDyne Systems, Inc.
比人类更人性化。
MCP 市场