Zotero CAJ Converter (for Zotero 7)

这是一个专为 Zotero 7 开发的插件，能够自动将中国知网 (CNKI) 的 CAJ 格式文件转换为 PDF 文件，并自动更新 Zotero 条目。

✨ 功能特性

• 右键转换：在 Zotero 中右键点击 CAJ 附件，一键转换为 PDF。
• 自动替换：转换成功后，自动将附件条目更新为 PDF 格式（图标变为红色 PDF 图标），无需手动重新挂载。
• 无缝集成：支持 Zotero 7 的全新界面，适配深色模式。
• 智能容错：即使下载的文件没有 .caj 后缀，也能识别并转换。

---

⚙️ 安装与配置指南 (macOS)

由于 CAJ 格式的特殊性，本插件依赖于外部开源工具 caj2pdf。请务必严格按照以下步骤配置环境。

第一步：安装系统依赖

插件依赖 python3 和 mutool (用于处理 PDF)。

1. 检查 Python 3: macOS 通常自带 Python 3。打开终端 (Terminal) 输入：

   python3 --version

   如果有输出版本号即可。

2. 安装 mutool: 这是 caj2pdf 转换过程中必须的工具。推荐使用 Homebrew 安装：

   brew install mupdf-tools

   (如果您没有安装 Homebrew，请先安装 Homebrew，或者手动下载 mupdf 工具包并配置 PATH)

第二步：配置 caj2pdf 转换工具

插件默认在您的用户主目录下寻找 caj2pdf。

1. 克隆 caj2pdf 仓库到主目录: 在终端中运行：

   cd ~
   git clone https://github.com/caj2pdf/caj2pdf.git

   注意：目录必须是 ~/caj2pdf (即 /Users/您的用户名/caj2pdf)。

2. 安装 Python 依赖库: 进入目录并安装依赖：

   cd ~/caj2pdf
   pip3 install -r requirements.txt

   如果您的网络无法连接 GitHub，请确保安装了以下库：PyPDF2, mutagen 等。

3. 验证环境: 在终端尝试运行一次（检查是否报错）：

   python3 ~/caj2pdf/caj2pdf

   如果输出 usage: caj2pdf ... 说明配置成功。如果报错缺少模块，请重新执行第2步。

第三步：安装插件

1. 下载最新版本的 .xpi 文件（例如 zotero-caj-converter-v0.2.0.xpi）。
2. 打开 Zotero 7。
3. 点击菜单栏 工具 (Tools) -> 附加组件 (Plugins)。
4. 点击右上角的齿轮图标 ⚙️ -> Install Add-on From File...。
5. 选择下载的 .xpi 文件进行安装。
6. 重启 Zotero。

---

📖 使用方法

1. 导入文献: 使用 Zotero Connector 从知网抓取文献，或者直接拖拽 CAJ 文件到 Zotero。
2. 执行转换:
   • 选中包含 CAJ 附件的条目（或直接选中 CAJ 附件）。
   • 右键点击，在菜单中选择 CAJ -> PDF。
3. 等待完成:
   • 右下角会弹出转换进度条。
   • 转换完成后，附件图标会自动变为 PDF 图标，您现在可以双击直接打开阅读了。

---

❓ 常见问题与故障排除

Q: 右键菜单里没有 "CAJ -> PDF" 选项？ A:

1. 请确保您安装的是 Zotero 7。
2. 确保您选中的是附件条目，或者包含附件的文献条目。
3. 插件可能还在加载，尝试重启 Zotero。

Q: 进度条显示 "Error: /usr/bin/python3 failed"？ A: 这通常意味着 Python 环境配置有问题。

1. 请检查 /tmp/zotero_caj_debug.log 文件，里面有详细的报错信息。 在终端运行：cat /tmp/zotero_caj_debug.log
2. 常见原因：
   • 没有安装 mupdf-tools (brew install mupdf-tools)。
   • Python 缺少依赖 (pip3 install PyPDF2)。
   • ~/caj2pdf 目录不存在。

Q: 转换后的 PDF 打不开或为空？ A: 这是一个已知问题，部分加密的 CAJ 文件或特殊格式（如某些学位论文）caj2pdf 可能无法完美支持。这是 caj2pdf 工具本身的限制。

---

📝 开发构建

如果您想自行修改代码：

# 安装依赖
npm install

# 编译 TypeScript 并打包
npm run package

📄 许可证

MIT License