Zotero 版笔记同步助手安装与使用教程（实验室）
Zotero 版笔记同步助手安装与使用教程（实验室）
🧪 实验室功能：Zotero 版插件暂未上架 Zotero 官方插件目录，需要通过「从文件安装」使用。 功能与稳定性会持续打磨，欢迎试用反馈。
装上它之后，你可以把链接或文章发给《笔记同步助手》公众号；遇到链接时，助手会将链接交给 DeepSeek、豆包、千问 等 AI 处理，再把 AI 整理好的内容自动同步进 Zotero，落在你指定的分类里。
它和 Obsidian / 思源笔记 / Joplin / Logseq 版共用同一个云空间、同一把密钥，在哪一端保存，都可以同步到 Zotero。
一、开始之前
- Zotero 7 及以上。插件的开发与验证在 Zotero 10 上完成。
- 目前只写入 「我的文库」，暂不支持群组文库。
- 准备好你的密钥：关注《笔记同步助手》公众号即可获取，已有其他版本密钥的用户直接沿用。
二、安装插件（3 步）
安装入口和之后的同步入口都在 Zotero 的 工具 菜单里。第一次安装时，先点 工具 → 插件；装好后，这里还会多出「笔记同步助手：拉取文章」和「笔记同步助手：设置」。
-
下载插件文件：点此下载 note-sync-helper-zotero.xpi。 下载下来是一个
.xpi文件，不用解压。 -
打开插件管理页：点 工具 → 插件，再点这个页面右上角的 齿轮， 选择 Install Plugin From File…。这个页面由 Zotero 提供，所以这一项可能显示为英文。
-
选中刚下载的
.xpi。装好后「笔记同步助手」会出现在已启用列表里，不用重启 Zotero。
装好之后回到 工具 菜单，就能看到「笔记同步助手：拉取文章」和「笔记同步助手：设置」两项了。
三、填写密钥
打开 Zotero 的 编辑 → 设置（macOS 在 Zotero → 设置），左侧选择 「笔记同步助手」。 也可以直接走 工具 →「笔记同步助手：设置」。
在 账号 区域：
- 密钥 — 粘贴从《笔记同步助手》公众号获取的密钥。它只存在本机，不会写进笔记。
- 同步服务地址 — 一般不用修改。连接失败时会自动尝试备用地址；如果你填写了自己的地址， 则只使用该地址。
- 立即同步 — 填好密钥后可以直接同步一次；按钮旁边会显示上次同步结果。
🔒 密钥只保存在你自己的电脑上，不会写进笔记，也不会出现在日志里。
四、保存位置（重点）
- 文章分类路径 — 决定文章落到 Zotero 的哪个分类。用
/分隔多级分类，不存在时会自动创建。 ⚠️ 这里填的是 Zotero 里的分类，不是电脑上的文件夹。 - 文章分类日期格式 — 决定分类路径中日期变量的显示方式。
- 条目标题模板 — 决定同步后每个条目的标题。
- 条目标题日期格式 — 决定条目标题中日期变量的显示方式。
文章分类路径可以使用 {{{title}}}、{{{dateSaved}}}、{{{yearSaved}}}、
{{{monthSaved}}}。例如按月归档后，可以形成「笔记同步助手 / 2026-08」这样的分类层级。
条目标题模板可以使用 {{{title}}}、{{{author}}}、{{{dateSaved}}}。如果只想保留原题，
写 {{{title}}} 即可；想带上保存日期，可以写 {{{dateSaved}}}-{{{title}}}。
五、内容与模板
前置元数据模式决定作者、来源、标签和时间保存在哪里：
- 保存为 Zotero 自带信息（推荐） — 写进 Zotero 自带字段，笔记正文更干净。
- 写进笔记正文 — 这些信息显示在子笔记开头。
- 保存为 Zotero 自带信息并写进笔记正文 — 两处都保留。
已有条目处理策略决定再次同步同一篇文章时，如何对待已经存在的笔记正文：
- 保留你的修改（默认） — 发现正文被你改过时不覆盖，也是最稳妥的选择。
- 用最新内容替换正文 — 用云空间里的最新内容更新正文。
- 不处理已有条目 — 已存在的条目保持原样。
下面的 文章内容模板决定子笔记正文写什么，其中 {{{content}}} 代表 AI 整理后的文章内容；
前置元数据模板决定写进笔记开头的信息格式。修改 文章内容模板时请保留
{{{content}}}，否则正文不会出现在子笔记里。
六、图片与附件
在 图片与附件 区域：
- 图片处理 — 可选 下载并保存到本地、保留原始链接 或 不加载图片。
- 下载正文里的附件（文档、表格、压缩包、音视频等） — 打开后，正文中的这些文件会保存为 Zotero 条目的附件。
- 单个图片或附件大小上限（MB） — 限制单个文件的下载大小。
选择 下载并保存到本地 后，正文图片会存进 Zotero，断网也能查看。某张图片或某个附件 下载失败时，插件会保留原始链接并继续处理，不会影响这篇文章和后续文章同步。
自动同步
- 频率（本设备） — 单位是秒；
0表示只手动同步，非0时最低 60 秒。 - 启动 Zotero 时自动同步（本设备） — 每次打开 Zotero 后自动同步一次。
这两项只对当前设备生效，换一台电脑需要重新设置。
高级设置
- 每次拉取数量 — 一般保持默认即可。
- 连接等待时间（毫秒） — 网络较慢时可以适当调大。
- 调试日志（密钥和文章正文不会出现在日志里） — 排查问题时再打开。
七、开始同步
设置完成后，走 工具 →「笔记同步助手：拉取文章」，或者点击设置页里的 立即同步。
同步完成后，Zotero 右下角会弹出原生提示，写明本次共处理几篇，以及其中的新建、更新、未改动、 保留你的修改各有多少；如果有图片或附件没下载成功，也会一并显示数量。
八、效果示例
每篇文章会成为一个类型为 「网页」 的条目，标题按 条目标题模板生成；网址、网站标题、 日期、访问时间、摘要和标签会自动填好，条目也会落在按模板生成的分类里。
文章正文会成为这个条目的 子笔记，标题层级、列表、引用和代码段都会保留。
选择 下载并保存到本地 后，多张正文插图也会保存进 Zotero，之后断网仍能查看。
打开 下载正文里的附件（文档、表格、压缩包、音视频等） 后，下载好的文件会出现在条目的 附件区里。
条目的 「其他」 栏里会有两行同步标记，形如 笔记同步助手: … 和
笔记同步助手笔记: …。请不要删除——插件靠它认出「这条是我同步过来的」；删掉后，
同一篇内容可能会被当成新文章再同步一份。
数据安全：插件如何保护你的修改
- 默认选择 保留你的修改（默认）：你在 Zotero 里改过的笔记正文，重新同步时不会被覆盖， 同步结果会把它记成「保留你的修改」。
- 换一台电脑后，即使本机没有以前的同步记录，插件也不会覆盖已有笔记，更不会重复新建条目。
- 把条目放进 回收站 后再同步，它不会被恢复，也不会另外新建一份。
- 图片或附件下载失败时，只会保留原始链接并给出提示，不会卡住整篇或后面的文章。
常见问题
Q：找不到「Install Plugin From File…」？ A：先打开 工具 → 插件，再点插件管理页右上角的 齿轮。这一项是 Zotero 自带界面， 可能显示为英文。
Q：安装后没有看到设置和同步入口？ A：先在插件管理页确认「笔记同步助手」已经启用，再重新打开 工具 菜单。设置入口也可以从 编辑 → 设置 → 笔记同步助手进入。
Q：重复同步会不会出现两份条目？ A：正常不会。请保留条目「其他」栏里的两行同步标记，插件需要用它们识别已经同步的条目。
Q：会不会覆盖我自己改过的笔记？ A：默认不会。**保留你的修改（默认）**会保护你改过的正文；换电脑后没有本机同步记录时， 同样不会覆盖，也不会重复新建。
Q：可以同步到群组文库吗？ A：暂时不可以。目前只写入 「我的文库」。
Q：和其他版本是同一个云空间吗？ A：是。Zotero、Obsidian、思源笔记、Joplin、Logseq 版共用同一个云空间、同一把密钥。
Q：图片存在哪里？会不会占很多空间？ A：选「下载并保存到本地」时，图片会作为笔记里的图片存进 Zotero 自己的存储目录，断网也能看。 不想占空间就把 图片处理 改成「保留原始链接」，笔记里只留链接、打开时联网加载。
Q：能配合 Zotero 自带的同步用到第二台电脑吗？ A：插件写的条目、笔记和同步标记都放在 Zotero 自带的字段里，会跟着 Zotero 自己的同步一起走。 不过「两台电脑 + Zotero 账号同步」的完整链路我们还在验证，实验室阶段建议先在一台电脑上用； 真的换机时，装上插件填同一把密钥即可，已有条目不会被重复新建，你改过的正文也不会被覆盖。
实验室版本欢迎试用反馈，有问题可以在服务号里联系人工客服。