Zotero 数据导入
红豆可以直接从本机 Zotero 数据目录或 Zotero 云端文库迁移数据，无需安装迁移插件，也不需要先导出 RIS、BibTeX 等中间文件。
入口：文件 → 导入 → Zotero 文献库。
可以导入哪些内容
当前导入功能支持：
- 个人文库、“我的出版物”和有权限访问的群组文库；
- 分类及其层级结构、文献条目和分类归属；
- 题名、作者、日期、出版信息、标识符、摘要、标签等元数据；
- 条目笔记、独立笔记、笔记中的嵌入图片和内部链接；
- 本地可用附件、链接网址、PDF 批注以及图片或手写批注；
- 仅存在于来源云端的附件，可从 Zotero 官方空间或来源 Zotero WebDAV 下载；
- 条目之间的关联关系。
当前不会迁移回收站内容、保存搜索、插件、界面设置、引用样式和账号密码。找不到原文件的链接附件会被标记为缺失并跳过。
一次导入一个来源文库。如果账号中有个人文库和多个群组文库，请分别执行导入。
导入前准备
- 备份红豆数据目录，并保留原 Zotero 数据目录或云端文库。
- 在红豆左侧先选中接收数据的可编辑文库。若当前文库不可编辑，内容会导入个人文库。
- 检查红豆目标文库的附件同步方式和剩余空间。导入后的附件会使用目标文库当前配置的红豆云空间或 WebDAV。
- 使用本机导入时，确认 Zotero 数据目录和链接文件的原始目录仍可访问。
- 大型文库建议先导入一个较小的群组文库或测试文库，检查分类、附件、笔记和批注后再继续。
选择导入来源
打开“文件 → 导入 → Zotero 文献库”后，可以选择：
- 本机 Zotero 数据：读取当前电脑上的 Zotero 数据库和本地可用附件；
- Zotero 云端数据：在 Zotero 官方授权页面登录，从在线个人文库、出版物文库或群组文库导入。
两种方式最终创建的数据结构一致。优先选择本机导入，可以直接利用已经下载到电脑上的附件；没有本机数据目录时，再使用云端导入。
从本机 Zotero 导入
第一步：选择数据目录
红豆会自动查找这台电脑上的 Zotero 数据目录，并优先分析最近使用的目录。
如果没有自动找到：
- 点击“选择文件夹”；
- 选择包含 zotero.sqlite 的数据目录，不要只选择数据库文件；
- 红豆会创建数据库临时快照进行分析，不会修改来源数据库。
如果提示“Zotero 正在使用这个数据库”，请完全退出 Zotero，再点击“重试”。红豆会保留已经选择的目录。
第二步：选择来源文库并查看预览
分析完成后，在“来源文库”中选择要迁移的个人文库、出版物文库或群组文库。
预览会显示：
- 文献、分类、笔记和批注数量；
- 附件总数；
- 本地可用、仅云端和缺失附件的数量；
- 本地附件占用空间。
如果账号中有多个文库，请确认名称无误后再开始。
第三步：设置分类和链接文件
导入选项包括：
- 为导入内容创建一个父集合：默认开启。内容会集中放在“从 Zotero 导入 - 文库名称”下，便于检查和回退；
- 将链接文件复制到红豆存储：默认开启。红豆会把仍可访问的链接文件复制到目标文库的附件存储中。
关闭父集合选项后，来源分类会直接建立在目标文库根目录；没有所属分类的条目会保留在文库根部。
关闭“将链接文件复制到红豆存储”后，链接文件仍指向原路径。移动文件、修改盘符或换电脑后可能无法打开，也通常不会通过附件同步上传。
第四步：处理仅云端附件
只有本地未下载的附件时，导入窗口会显示“来源云端附件”区域。可以选择：
- 暂不下载云端附件：先迁移题录、分类、笔记和本地附件，稍后重新导入未完成项；
- Zotero 官方空间：登录来源 Zotero 账号，从官方附件空间下载；
- 来源 Zotero WebDAV：填写来源账号使用的 WebDAV 基础地址、用户名和密码。
使用来源 WebDAV 时：
- 填写 HTTP 或 HTTPS 基础地址，不要在地址中包含用户名、密码、查询参数或片段；
- 红豆会只读检查服务器中的 zotero/ 目录；
- 点击“验证来源连接”，显示验证成功后再导入；
- 验证和下载不会修改来源 WebDAV，也不会覆盖红豆自己的 WebDAV 设置。
来源附件配置只负责“从哪里下载”。文件导入后，仍按照红豆目标文库的附件同步配置处理。
第五步：开始导入
确认预览和选项后点击“开始导入”。建议先保持窗口打开，观察进度和当前处理的条目。
从 Zotero 云端导入
第一步：登录 Zotero
- 选择“Zotero 云端数据”；
- 点击“登录 Zotero”；
- 红豆会打开系统默认浏览器，并在 Zotero 官方页面完成登录和授权；
- 授权期间红豆会暂时最小化，完成后自动恢复。
Zotero 密码只输入在官方页面。红豆不会读取或保存密码，只接收授权 Key，并将其安全保存到系统密码管理器。以后可以直接读取上次授权，也可以切换账号。
第二步：选择在线文库
登录成功后，红豆会读取当前账号有权限访问的文库。可以选择：
- 我的文库；
- 我的出版物；
- 个人账号可访问的群组文库。
选择后检查文献、分类、笔记、批注和附件数量。云端方式会按页读取完整文库，大型文库的分析时间会更长。
第三步：选择附件来源
云端元数据通过 Zotero API 读取。若文库包含附件，还需要选择附件实际保存的位置：
- 使用 Zotero 官方空间时，沿用刚才授权的账号；
- 来源账号使用 WebDAV 时，改选“来源 Zotero WebDAV”并完成只读验证。
云端文库中的链接文件通常只存在于原电脑，无法从 Zotero API 下载，会作为缺失附件跳过。
第四步：开始导入
确认父集合、附件来源和目标文库后点击“开始导入”。红豆会先读取云端数据，再下载附件并写入目标文库。
导入期间的操作
导入过程中可以：
- 点击“暂停”，红豆会在安全边界停下；点击“继续”恢复；
- 点击“取消导入”，红豆会完成当前操作后安全停止；
- 已经完成的分类、条目和附件会立即保存，不会因为暂停或取消而回滚；
- 不要在导入过程中移动来源数据目录、断开附件磁盘或修改来源 WebDAV。
如果网络中断或附件下载失败，可以在结果页返回并重试未完成项。
查看结果和继续未完成项
完成后，结果页会列出：
- 新建的条目和分类数量；
- 成功导入及从来源云端下载的附件数量；
- 已复用的既有条目数量；
- 来源版本较新但没有覆盖的条目数量；
- 仍为仅云端或缺失的附件；
- 错误数量和总用时。
存在错误、缺失附件、未下载附件或安全停止时，会显示“返回并重试未完成项”。再次开始后，红豆会自动跳过已经完成的内容，只处理未完成部分。
需要排查具体条目时，点击“导出详细报告”，保存 hongdou-zotero-import-report.json。报告包含来源文库、目标文库、迁移统计和错误列表，不包含账号密码。
重复导入和数据更新
红豆会记录来源文库、来源条目和目标条目之间的映射。
- 对同一来源文库再次导入到同一目标文库时，已完成内容会被复用，不会重复创建；
- 中断后重新导入会从未完成内容继续；
- 如果来源条目的版本比上次导入更新，结果页会计入“来源版本较新”；
- 当前不会自动用来源内容覆盖红豆中已经存在的条目。请根据结果报告，在红豆中人工核对需要更新的元数据、附件或笔记。
不要通过删除父集合来判断是否可以重新完整导入。删除集合不一定会删除其中的文献条目，重新导入仍会识别之前的迁移记录。
常见问题
没有检测到 Zotero 数据目录
点击“选择文件夹”，选择包含 zotero.sqlite 的目录。默认目录、旧版 profile 目录和自定义数据目录都有可能被检测到。
提示来源数据库正在使用
完全退出 Zotero，包括仍在后台运行的进程，然后点击“重试”。红豆需要先创建一致的只读快照。
附件显示为缺失
检查原文件是否被移动、删除或设为仅在线。链接文件必须能从当前电脑访问；云端附件需要配置正确的官方空间账号或来源 WebDAV。
Zotero 官方空间无法连接
重新登录并确认授权允许读取文库和附件文件。个人文库必须使用与来源文库一致的 Zotero 账号。
来源 WebDAV 验证失败
检查基础地址、用户名和密码，并确认服务器中存在可读取的 zotero/ 目录。来源 WebDAV 配置与红豆目标文库的 WebDAV 配置相互独立。
云端分析时间较长
大型个人文库或多个群组文库需要分批读取。保持网络稳定，等待预览完成后再选择文库和附件来源。
建议迁移完成后抽查分类层级、作者顺序、标签、PDF、笔记、批注和关联条目，并在确认完整后再清理旧环境。
