Doc2X Zotero 插件使用指南
本文档介绍如何安装和使用 Doc2X 的 Zotero 插件，实现 PDF 文档的智能解析和翻译。
前置准备
1. 安装 Doc2X 客户端和插件
需要下载以下两个组件：
注意: 部分浏览器不认可 xpi 文件，会提示 xpi 文件损坏，建议使用 Edge 或 Chrome 浏览器解决此问题。
2. 注册 Doc2X 账户
注册地址: doc2x.noedgeai.com
视频教程
详细操作视频: https://www.bilibili.com/video/BV19Yf5YXEDF
提示: 视频教程录制时插件版本较早，安装步骤中包含"安装 Better Notes 插件"的说明。最新版插件（v1.0.31 及以上）已不再依赖 Better Notes for Zotero，安装时无需额外安装该插件，请以本文档为准。
使用流程
第一步：安装所需组件
确保安装以下所有组件：
- ✅ Zotero 7 / 8
- ✅ Doc2X 客户端
- ✅ Doc2X 插件
说明: 最新版插件已移除对 Better Notes for Zotero 的依赖，无需安装 Better Notes 即可正常使用全部功能。
第二步：配置插件设置
安装完成后，打开插件和桌面版客户端（确保已登录 Doc2X 账户）。
Windows 系统设置
- 支持版本: 仅支持 Win10 和 Win11
- 不支持: Zotero 6
- 操作路径: Zotero → 编辑 → 设置
Mac 系统设置
- 支持版本: 暂时只支持 M 系列芯片
- 操作路径: Zotero → 设置
Zotero 版本支持
- 插件支持 Zotero 7 / 8
重要提醒: 如果需要更新 Zotero 插件，必须先卸载旧版本插件 → 关闭 Zotero → 重新打开 Zotero → 安装新版本插件，否则可能因为 Zotero 的 bug 出现各类问题。
第三步：获取 Token
- 打开 Doc2X 客户端
- 在 Zotero 插件设置中点击"获取 Token"
- Mac: 左上角状态栏 Zotero → 设置 → Doc2X → 点击 获取 Token
- Windows: Zotero → 编辑 → 设置 → Doc2X → 点击 获取 Token
- 插件会自动从本地运行的 Doc2X 客户端获取授权信息
- 查看 Token 状态和解析次数显示
费用说明
- 付费模型: 消耗积分和解析页数
- 免费模型: 只消耗解析页数
第四步：配置解析与翻译选项
在插件设置页面，可以配置以下选项：
解析模型
- doc2x-v2-2410 — 旧版模型
- doc2x-v3-2509-beta — 最新版模型（推荐）
翻译模型
插件支持多种翻译模型，包含免费和付费选项：
- 免费模型: Doubao-1.5-lite、gpt-4.1-nano、qwen-turbo-latest 等
- 付费模型（消耗高级积分）: Doubao-1.5-pro、DeepSeek-V3、gpt-4.1-mini、qwen-max-latest、Kimi-K2 等
可用模型列表会从服务端动态加载，以插件设置中显示的为准。
目标语言
支持 10 种翻译目标语言：中文、英文、日语、法语、俄语、葡萄牙语、西班牙语、德语、韩语、阿拉伯语。
翻译忽略选项
可选择翻译时忽略以下内容：
- 表格
- 代码
- 图片
- 文献
输出格式
支持多种输出组合：
- 文本输出: 原文 MD、译文 MD、双语 MD、原文 HTML、译文 HTML、双语 HTML、译文 PDF、双语 PDF
- 排版保留输出: 原文 MD、保留排版译文 PDF、保留排版双语 PDF（原左译右）、保留排版双语 PDF（译左原右）
术语表
支持自定义术语表，用于控制专业术语的翻译一致性。可在设置页面选择和更新术语表。
配置完成后，勾选"我已完成解析和翻译配置"即可开始使用。
第五步：开始使用
在有父条目的 PDF 上右键，即可看到 Doc2X 菜单，包含以下功能：
- 翻译 PDF 为 Md 到笔记 — 将 PDF 翻译为目标语言并以 Markdown 笔记形式导入
- 解析 PDF 为 Md 到笔记 — 将 PDF 解析为 Markdown 笔记导入 Zotero（不翻译）
- 保留排版翻译 — 翻译 PDF 并保留原文排版布局
- 打开报错日志目录 — 查看插件错误日志
对于已解析完成的笔记，右键还可以选择：
- Doc2X: 预览 Markdown — 预览笔记的 Markdown 原文
- Doc2X: 在网页中查看 — 在浏览器中查看解析/翻译结果
使用注意事项
大文件处理建议
- 不建议在 Zotero 中对页数特别多的 PDF（>100 页）进行翻译
- 长 PDF 翻译时状态更新可能不明显
- 进度没有更新不代表翻译卡住，请耐心等待
- 可在客户端查看实时翻译进度
DeepSeek 模型特别提醒
DeepSeek 模型在翻译时耗时较长，请耐心等待。
翻译错误处理
如果遇到翻译阶段出错的情况（完成解析扣除解析页数，但翻译过程失败）：
正确做法:
- 在客户端的左侧任务栏选中相关结果
- 点击"继续翻译"
- 此操作只扣除积分，不会再次扣除解析页数
- 客户端内右上角导出选择导出到 Zotero
错误做法:
- ❌ 不要在 Zotero 中重新发起翻译
插件与客户端通信
插件通过 SSE（Server-Sent Events）与本地运行的 Doc2X 客户端通信。使用时请确保：
- Doc2X 客户端保持运行状态
- 若连接中断，插件会自动尝试重连
系统兼容性
| 操作系统 | 支持版本 | Zotero 版本 | 状态 |
|---|---|---|---|
| Windows | Win10/Win11 | Zotero 7/8 | ✅ 支持 |
| Windows | Win10/Win11 | Zotero 6 | ❌ 不支持 |
| Mac | M 系列芯片 | Zotero 7/8 | ✅ 支持 |
| Mac | Intel 芯片 | - | ❌ 暂不支持 |
问题反馈
如遇到任何 bug 或问题，请通过下面的方式联系我们：
常见问题
Q: xpi 文件提示损坏怎么办？
A: 换用 Edge 或 Chrome 浏览器进行下载和安装。
Q: 翻译进度长时间没有变化是否正常？
A: 正常现象，特别是使用 DeepSeek 模型时，请耐心等待并在客户端查看实时进度。
Q: 如何避免重复扣费？
A: 翻译失败后，请在客户端继续翻译，不要在 Zotero 重新发起。
Q: 支持哪些 Zotero 版本？
A: 支持 Zotero 7 / 8，不支持 Zotero 6。
Q: 还需要安装 Better Notes 插件吗？
A: 不需要。最新版插件已完全移除对 Better Notes for Zotero 的依赖，无需额外安装。
Q: 如何清除插件缓存？
A: 在插件设置页面点击"清除缓存"按钮，可重置所有设置（授权信息会保留）。
Q: 插件无法连接到 Doc2X 客户端怎么办？
A: 请确保 Doc2X 客户端正在运行。插件会自动检测本地客户端端口，若连接失败会自动重试。如仍无法连接，尝试重启客户端和 Zotero。