Zotero 与原生云文献库

在 UniDoc 中打开 引用 → 文献库。把文献、研究笔记、附件和脑图放在同一份原生文献库里，再把需要的引文插入文档。

1. 接入 Zotero

选择 连接 Zotero，填写个人文献库的用户数字 ID，或群组文献库的群组数字 ID。公开文献库通常不需要密钥；私有库需要有读取权限的 API Key，可在 Zotero Keys 设置创建。

API Key 仅在本次读取期间保留在页面内存中，直接发送到 Zotero API；不写入文献库、UDOC、云存储或 UniDoc 服务器。关闭窗口会取消正在进行的读取。UniDoc 登录与 Zotero 授权分别用于各自服务。

此版本提供 Zotero → UniDoc 的读取与合并。重新读取可获取新增和更新条目；本机修改与导入版本冲突时，由用户选择保留哪一版。读取失败或库版本在分页期间变化时，不提交不完整结果。不会向 Zotero 写回、删除远端条目，也不会把远端删除自动应用到本机库。

也可以选择 导入，一次选择多个导出文件。

导出文件内的本地路径不是附件正文。若需要云端 PDF 或其他附件，在对应条目点击 上传附件，选择真实文件；文件通过现有 OmniDoc 账户存储上传到 R2。不会悄悄扫描本机路径或上传未选中的文件。

2. 原生文献库与云端

新建多个文献库，编辑条目、作者、摘要和笔记，使用标签、分类与全文检索整理研究。误删条目可以在回收站恢复。本机变更保存在 IndexedDB，按登录账户隔离；未登录时保存在该浏览器的本机库中。登录后可显式选择 导入未登录文献库，复制到自己的账户空间。

点击 存到云端，将当前库打包为真实 .library.udoc，使用既有 OmniDoc 上传授权和 R2 存储。其他设备登录同一账户，点击 云端文献库，选择快照恢复。每次打开云端快照会建立本机副本，保留原快照；这是手动保存／恢复，不是多人实时共同编辑或后台双向同步。

附件正文独立存储在账户云端，库内保留受账户权限约束的文件标识。下载到别的账户不会自动转移附件访问权限；把库文件交给别人也不等于公开其附件。文献库保存到云端时不会生成公开分享链接。

本机库可直接导出为原生 UDOC、完整 JSON、BibTeX 或 RIS。后两种仅导出书目信息，不能代替完整库备份。本机浏览器数据可能被用户清理，重要研究请保留原生备份或云端快照。

3. 关系图与脑图链接

关系图展示实际存在的连接：Zotero 关联条目、条目与笔记／附件的从属关系、笔记中的入链与出链，以及手动建立的支持、反驳、扩展或一般关联。选择节点即可查看对应条目。不会把关键词相似误当作真实引用关系。

支持识别：

• zotero://select/library/items/ABCDEFGH，以及群组条目链接。
• zotero://note/u/ABCDEFGH/?line=...&section=...，以及 Better Notes 群组笔记链接。
• zotero://open-pdf/library/items/ABCDEFGH?page=7&annotation=...，以及群组 PDF 链接。

目标已导入且身份可唯一匹配时，先定位到原生文献库条目；笔记尽可能定位到对应章节或行。PDF 页码和批注参数保留在 在 Zotero 打开 的链接中，由已安装的 Zotero 定位。未导入的目标仍可通过原始链接打开 Zotero；不会猜测一个同名条目替代它。

脑图可以导入 .mm，也可以新建节点、添加分支、关联本库条目或外部链接，再导出 .mm。UniDoc 自身的条目关联使用 UDOC_ITEM 扩展字段保留。Better Notes 的独有同步配置、插件缓存和其他图谱插件的私有格式不在本次兼容范围内。

4. 在文档中引用

先把光标放到正文，再打开文献库，选中文献后点击 插入引文。支持 APA、Vancouver 和 Harvard 排版；点击 插入参考文献 生成书目。正文引文增删或顺序调整后，点击 更新引文，按正文中的实际顺序重新排版；Vancouver 编号不会为每篇都固定成 1。

文档保存时只携带已用到的书目字段与条目 ID，因此断网后仍能查看引文信息和已生成书目。完整私人文献库、研究笔记、API Key 不会随普通引用进入文档或文档分享。显式导出的文献库文件则包含完整库数据，请按自己的分享意图使用。

数据与实现边界

当前单次文献数据导入上限为 32 MiB，单库最多 50,000 条目；关系图最多展示当前条目两层邻域内的 160 个节点。附件容量遵守账户上传额度。导入的 HTML 笔记作为内容安全显示，脚本、事件处理器和危险 URL 不会执行；原始笔记数据仍保留在原生库中。

引文排版使用 Citation.js 和 Frank Bennett 的 citeproc-js。许可证、可重建依赖和原始引擎源码随发布提供：许可证、citeproc-js 源码。

官方协议参考：Zotero API v3、Zotero 同步版本规则、Zotero 关联条目、Better Notes。

这份说明由原生 UDOC 无损导出，可下载其 原生源文件 后在 UniDoc 中继续使用。

5. 公网入口与第一次打开

生产站点入口是 UniDoc 编辑器。文献库使用说明的公网页面是 完整使用手册，原生可恢复源文件是 REFERENCE_LIBRARY.udoc。说明页和源文件都由同一份 UniDoc 文档导出，下载 .udoc 后仍可在 UniDoc 中继续编辑。

请使用支持 IndexedDB 和原生对话框的现代浏览器，本次界面验收使用 Microsoft Edge。文献库在页面内打开，不需要允许浏览器弹窗；窄屏会切换为上下布局。打开外部 Zotero 链接时，浏览器可能询问是否允许启动 Zotero 应用。

首次访问时，顶部功能区的 引用 组会出现 文献库 按钮。文献库为空时会显示引导卡片，可直接点 导入文献 或 连接 Zotero。不登录也能创建本机库和导入文件；读取 Zotero 私有库需要 Zotero API Key；云端保存、附件上传和跨设备云端恢复才需要登录 OmniDoc。两种授权互不替代。

6. 界面速览：每个区域负责什么

文献库采用三栏工作区，减少在研究、整理和引用之间来回跳转：

底栏会显示读取、打包、上传等操作阶段，例如 正在读取 Zotero 文献 和已读取条目数。网络操作期间工作区暂时变灰并锁定，避免同时修改同一库。关闭窗口会取消正在进行的 Zotero 请求；已启动的云端上传可能仍会完成，但其迟到结果不会再写入已关闭或已切换账户的文献库。

7. 三条推荐工作流

工作流 A：从 Zotero 到可引用文档

1. 先把光标放到需要引用的正文位置，再打开 引用 → 文献库 → 连接 Zotero。读取 Zotero 不要求先登录 OmniDoc。
2. 选择 个人文献库 或 群组文献库，填写 Zotero 数字 ID。私有库再填写只读 API Key；公开库可以留空。
3. 等待读取完成。页面会合并文献、作者、标签、分类、笔记、附件元数据和关联条目，并显示新增、更新和冲突数量。
4. 在搜索框输入标题、作者、DOI 或标签，选中目标条目；需要时先点击 编辑 补充摘要、标签或笔记。
5. 在底栏选择排版风格，点击 插入引文。文献库关闭，引文插入打开文献库前的光标位置。插入下一处时，先在正文中重新定位光标，再打开文献库。
6. 所有引文插入后点击 插入参考文献。正文顺序变化或删除引文后点击 更新引文。

工作流 B：整理笔记、附件和研究关系

1. 用 新建笔记 创建研究笔记，或导入 Better Notes 的 Markdown／HTML。
2. 在条目详情点击 关联，选择关系类型：关联、支持、反驳、扩展或笔记链接。
3. 在 关系图 中点击节点查看对应条目和连接；连线来自库内真实关系，不会根据关键词自动推断。
4. 在 脑图 中新建脑图、添加分支、关联本库条目或填写网页／Zotero 深链接。导入的 FreeMind／Freeplane .mm 会保留层级、箭头和节点链接。
5. 对有权限的账户，在条目详情点击 上传附件；只会上传当前选择的文件，完成后附件记录指向该账户的 R2 对象。

工作流 C：跨设备备份与恢复

1. 在窗口右上方点击 存到云端。UniDoc 会把完整库打包为 .library.udoc，通过账户上传授权保存到 OmniDoc R2。
2. 另一台设备登录同一账户，打开 引用 → 文献库 → 云端文献库，选择带时间戳的快照。
3. 打开快照后会创建一个名为“原名 · 云端副本”的本机库，再按需切换使用；原云端快照不会被覆盖。
4. 需要离线备份时，在左栏展开 导出／备份，优先选择 原生文献库 .udoc。JSON 适合程序处理，BibTeX／RIS 适合交给其他文献工具，但它们不包含完整笔记、分类和脑图。

8. Zotero 与 Better Notes 的链接规则

UniDoc 将深链接当作数据的一部分保存，不会把它们改写成易失的本地路径。下列链接在目标已导入且身份唯一时会先定位到 UniDoc 条目；否则保留 在 Zotero 打开 的原始链接：

zotero://select/library/items/ABCDEFGH
zotero://select/groups/123456/items/ABCDEFGH
zotero://note/u/ABCDEFGH/?line=18&section=方法
zotero://open-pdf/library/items/ABCDEFGH?page=7&annotation=AB12CD34

Better Notes 的 data-citation、data-annotation 元数据也会被提取为可跳转链接。点击笔记链接后，UniDoc 会在笔记中滚动到章节或行并高亮目标；PDF 链接会保留页码和批注 key，并提供 在 Zotero 打开 PDF 第 N 页。链接中的脚本、事件处理器和危险 URL 会被过滤，安全显示不会执行外部代码。

9. 文档引用的数据边界

文档保存时，正文引文仅携带已实际使用的书目字段、条目 ID 和来源链接。完整文献库、私人笔记、附件记录以及 Zotero API Key 仍留在文献库作用域，不会因为插入一条引文而进入普通 .udoc 或共享副本。点击文档里的引文可以重新打开文献库并查看离线引文快照。

如果需要把完整库交给同事，请在文献库中明确导出 .library.udoc，再将该文件交给对方导入。云端快照供同一账户恢复，不会生成对外共享链接；不要把包含私人笔记和附件元数据的完整 JSON 当作普通引文附件公开。共享文档本身不会自动公开 R2 附件权限。

10. 访客、登录与账户隔离

访客导入的数据只存于当前浏览器的 local 作用域。登录成功后，打开文献库并点击 导入未登录文献库，可把访客库复制到当前账户；复制完成后仍保留原本机库，便于核对。不同账户使用不同作用域，互相看不到对方的本机库。

登录状态刷新不会清空当前文献库或要求重复登录。若在 Zotero 读取、云端恢复或附件上传过程中切换账户，UniDoc 会关闭文献库并停止接收这次操作的结果，避免写入错误账户。已发送的上传请求可能继续在原账户完成。

11. 常见问题排查

连接 Zotero 一直没有结果：先确认填的是数字 ID，而不是用户名；群组库要选择“群组文献库”。私有库需要具有读取权限的 API Key。Zotero 返回 401／403 时不会提交部分结果，修正权限后重新读取即可。

提示请求过于频繁：Zotero API 返回 429 或 Backoff 时，等待提示的秒数再重试。UniDoc 分页读取每页最多 100 条，并在版本变化或中途失败时丢弃未完成合并，原有本机库不受影响。

插入引文按钮不可用：当前文档可能是只读共享、光标已离开正文，或文档在另一个窗口被替换。回到可编辑文档，把光标放在目标段落，再重新打开文献库。

云端列表为空：确认已登录同一 OmniDoc 账户，并先用 存到云端 创建 .library.udoc 快照。云端文件列表只显示以 .library.udoc 结尾的文献库快照，不会把普通附件误列为文献库。

附件上传失败或很慢：状态会依次显示检查权限、申请授权、上传和确认云端文件。文件很小也可能等待授权接口；请记录停留阶段、耗时及错误信息，区分授权延迟与文件传输耗时。关闭窗口会忽略迟到结果，但不能保证中止已发送的上传请求；先在云端文件中检查是否已完成，再决定是否重试。

脑图导入后样式不同：UniDoc 保留节点文字、层级、LINK、备注链接和箭头数据，第三方软件的主题、颜色和插件私有缓存不在兼容范围内。可在脑图页继续编辑，再导出标准 .mm。

12. 安全、隐私和容量

• Zotero API Key 只在本次读取的页面内存中使用，关闭窗口即清除；它不会写入 .udoc、云端文献库或 UniDoc 服务器。
• 文献库按账户作用域隔离；云端保存沿用 OmniDoc 账户鉴权和 R2 对象权限。
• 导入的 HTML 笔记按安全内容显示，脚本和危险 URL 不执行；原生库仍保留原始笔记数据，安全过滤作用于显示。
• 单个文献数据导入文件不超过 32 MiB，单库最多 50,000 条目；关系图最多显示当前条目两层邻域内 160 个节点。附件上限遵守 OmniDoc 账户上传额度。
• 云端快照是手动保存／恢复副本，不是多人实时协作库；请在重要变更后再次点击 存到云端。

13. 可复现与兼容声明

引文排版使用发布包中随附的 Citation.js 0.8.2 和 citeproc-js；许可证、构建脚本和源码均随项目发布，便于审计和重建。UniDoc 当前支持 Zotero → UniDoc 的读取、导入和合并，不向 Zotero 回写、删除或自动同步远端条目。Better Notes 兼容重点是条目／笔记／PDF 深链接和笔记元数据；插件的私有缓存、实时同步服务及其他图谱插件格式不在本版本承诺内。

如需报告问题，请附上：浏览器及版本、文献库来源（Zotero JSON／API／RDF 等）、条目数量、文献库窗口底部最后一条状态文字，以及是否能在不登录的本机库中复现。不要在工单或聊天中粘贴 API Key、附件私密 URL 或完整私人笔记。