简介scite-zotero-plugin 是一款面向科研工作者的 Zotero 扩展插件用于在文献管理器中直接查看每篇论文基于 Smart Citation 数据的分类统计Supporting、Mentioning、Contrasting并快速跳转到 scite 的站点报告页面解决科研人员快速评估文献引用质量与倾向性的问题。压缩包共 31 个文件以 TypeScript 源码、JSON 配置、XUL 界面定义与 PNG 图标为核心整体大小约 1.24MB其中 TS 文件实现插件逻辑JSON 负责元数据与依赖管理XUL 描述 Firefox/Zotero 界面PNG 提供示例截图和按钮图标。已有 1161 人学习下载。通过该资源可获得一套完整的 Zotero 插件工程包括 Webpack 构建配置、TSLint 与 CircleCI 集成、语言包及皮肤目录能够帮助有一定 TypeScript 基础的开发者理解插件打包、界面挂载和 scite API 数据展示的完整流程也可作为二次开发或学术文献工具定制的参考起点。1. scite 插件到底给 Zotero 补了什么不是显示引用数是显示引用语境用过 Zotero 的人都知道它帮你把文献存得整整齐齐但文献之间的引用关系它基本不管。scite 这个工具的定位恰好补上这块它不只是告诉你“这篇论文被引了多少次”而是把每一条引用语境拆出来标明这条引用是支持、反对还是仅提及。scite-zotero-plugin 就是把 scite 的引用语境数据塞进 Zotero 条目里的桥。装上之后你在 Zotero 里选中一篇文献就能直接看到 scite 的报告、引用分类统计不用再单独开网页去 scite.ai 查。适合每天跟文献打交道、又不想在 Zotero 和 scite 之间来回切的研究生、科研工作者。这篇文章我会从插件工程结构讲到本地构建再讲几个我实际踩过的坑最后给一个自定义右键菜单的进阶改法。2. 插件工作原理与工程骨架Zotero 插件为什么用 TypeScript 写2.1 scite 的核心能力Citation Statement 与 Classificationscite 的底层数据模型和普通引文索引最大的不同在于它把每条引文拆成了“Citation Statement”——也就是引用这句话出现的上下文片段同时给这条引用打一个分类标签。分类通常是三类supporting支持、contrasting对比/质疑、mentioning仅提及不带立场。这个分类是算法加人工审核混合产出的所以它比单纯数引用次数更能反映一篇文献在学术对话里的真实生态位。scite-zotero-plugin 做的事情本质上就是把 Zotero 条目映射到 scite 的 DOI 或 arXiv ID然后拉取这个映射对应的 Citation Statement 和分类统计。注意它和 Zotero 自带那种“抓取 PDF 元数据”的插件不同它不解析你本地 PDF 内容而是依赖 scite 的数据库。这意味着你的条目必须带 DOI 或者 arXiv 编号否则插件找不到对应记录。2.2 插件在 Zotero 里的加载模型bootstrap.js 与 manifest.jsonZotero 的插件机制和 Firefox 老式扩展类似但又有自己的一套。一个插件本质是一个 .xpi 文件里面至少要有一个 manifest.json声明插件 ID、版本、权限和入口脚本。入口脚本通常叫 bootstrap.js但它不是你自己手写的——在 scite-zotero-plugin 这类基于 zotero-plugin-template 的工程里bootstrap.js 是构建流程自动生成的加载器它负责在 Zotero 启动时把你的主逻辑注入进去。这里有个关键认知Zotero 插件的启动方式是“bootstrap 式”也就是插件安装后立刻生效不需要重启 Zotero。它通过生命周期钩子来管理install、startup、shutdown、uninstall。你在源码里写的 hooks.ts 或 lifecycle.ts会被构建工具编译并打包进 bootstrap.jsZotero 在相应时机调用这些钩子。2.3 工程目录与构建链路从 TS 源码到 xpiscite-zotero-plugin 用的是 TypeScript这不是为了花哨而是因为 Zotero 插件要操作的对象模型Services、ZoteroPane、Zotero.Item结构复杂类型标注能少翻很多文档。工程里典型的目录划分是src/ 放 TypeScript 源码比如 hooks.ts、addon.ts、prefs.tsaddon/ 放静态资源和 manifest.json 的模板build/ 或 dist/ 是构建输出目录最终生成 .xpipackage.json 统一管理依赖和构建脚本构建链路一般是这样的TypeScript 源码经 esbuild 打包成几个 chunk再和 addon/ 下的静态文件一起打进一个 .xpi。esbuild 选得比较多因为 Zotero 插件的总代码量不大esbuild 的冷启动速度和增量编译在这个场景里优势明显。# 安装依赖项目用 pnpm 的话 pnpm install # 开发模式监听文件变化并持续构建 pnpm run build --watch # 一次性构建出 xpi 包 pnpm run build逻辑说明--watch模式会在你改代码时自动重新构建生成新的 xpi适合配合 Zotero 的“重新加载插件”功能做调试循环。一次性构建则适合最终打包分发。构建产物路径一般在 build/release/ 下文件名带有版本号。参数说明如果你的网络环境拉不到依赖可以切到 npm 镜像源但需要确认 package.json 里锁定的 pnpm 版本和 Node 版本。zotero-plugin-template 对 Node 版本有下限要求太老的 Node 跑不了 esbuild。3. 本地构建与安装调试把插件跑进你的 Zotero3.1 环境准备与依赖安装先把工程克隆下来。这里我假定你已经装了 Node.js 和 pnpm。Node 版本建议 18 以上esbuild 对 Node 版本比较敏感太老会直接报错。安装依赖时注意zotero-plugin-toolkit 这个包的主体逻辑依赖 Zotero 的全局对象本地安装时它只做类型检查和工具函数打包真正跑起来是在 Zotero 里所以安装过程不会真的去下载 Zotero 本体。git clone https://github.com/scite/scite-zotero-plugin.git cd scite-zotero-plugin pnpm install逻辑说明git clone 拿到源码后pnpm install 会安装 package.json 里声明的依赖包括 zotero-plugin-toolkit、esbuild、typescript 等。这一步如果失败九成是网络问题按 pnpm 的报错去换镜像即可。参数说明安装完成后可以看一眼 node_modules/.bin/ 下有没有 esbuild 和 tsconfig 的软链有就说明核心工具链没问题。3.2 构建插件并安装 xpi构建命令会根据 ZOTERO_PLUGIN_ID、ZOTERO_PLUGIN_VERSION 这些环境变量来生成 manifest.json。如果你直接跑pnpm run build它会读取 .env 或默认配置。构建完会生成一个 .xpi在 Zotero 里通过“工具 → 插件 → 齿轮图标 → Install Plugin From File”装上。pnpm run build ls build/release/*.xpi逻辑说明这步把 TypeScript 源码编译成实际能在 Zotero 里执行的 JavaScript并连同 manifest.json、prefs.js 等打包成 xpi。拿到 xpi 的路径后在 Zotero 的插件管理界面选择那个文件即可。参数说明如果你改了版本号一定要同步改 package.json 和 addon/manifest.json 模板里的 version 字段否则 Zotero 会因为版本号不合规拒绝安装。3.3 调试与日志排查Zotero 插件调试有几个入口。最笨但有效的办法是看 Zotero 的调试输出窗口在 Zotero 里按 ShiftF2或者菜单栏“帮助 → 调试输出日志”。插件里用 console.log 打印的内容都会到这里。// src/hooks.ts 里加一段临时日志 console.log([scite-zotero-plugin] startup called, version:, addon.data.version);逻辑说明Zotero 的调试输出窗口会显示 console.log 和 console.error。插件启动时如果这段日志没打出来说明 bootstrap.js 根本没被执行问题多半出在 manifest.json 的入口配置或者插件 ID 冲突。参数说明Zotero 7 之后调试输出窗口的位置和样式有变化但不影响内容。另外Zotero 的 profile 目录下也有 logs/ 目录里面会有更底层的错误记录适合排查插件崩溃这类问题。MAC 和 Windows 路径不同以 Zotero 的帮助菜单里显示的 profile 路径为准。4. 核心代码路径与参数读透 scite 插件的关键文件4.1 manifest.json 的配置项manifest.json 是 Zotero 插件的门面。它决定了插件在插件列表里显示什么名字、能操作哪些 Zotero 对象、入口脚本是哪个。scite-zotero-plugin 里的 manifest.json 有几个关键字段值得注意。{ manifest_version: 2, name: scite-zotero-plugin, version: 1.0.0, applications: { zotero: { id: scite-pluginscite.ai, update_url: https://scite.ai/static/zotero/update.json, strict_min_version: 6.0, strict_max_version: 7.0.* } }, bootstrap: true, scripts: [bootstrap.js] }逻辑说明applications.zotero.id是插件的唯一标识Zotero 用它来区分插件改名字可以但尽量别改这个 ID否则 Zotero 会认为是两个插件。update_url指向一个 JSON 文件用来支持自动更新如果你是在本地调试这个 URL 可以是任意合法地址甚至不写。bootstrap: true表示这个插件走的是 bootstrap 加载模型。参数说明strict_min_version和strict_max_version很关键。scite 插件为什么经常出现“装了没反应”多半是版本约束太严比如 max 写的是 7.0.*而你的 Zotero 已经升到 7.1插件就被静默禁用了。自己改的时候要么放宽范围要么升插件版本。4.2 hooks 与生命周期bootstrap.js 被加载后Zotero 会调用它导出的生命周期函数。zotero-plugin-template 的设计里hooks 文件通常是 src/hooks.ts里面通过 toolkit 的 ZoteroPlugin 类来注册生命周期。// src/hooks.ts import { ZoteroPlugin } from zotero-plugin-toolkit; const plugin new ZoteroPlugin({ id: scite-pluginscite.ai, name: scite-zotero-plugin, version: 1.0.0, }); plugin.hooks.onStartup () { console.log([scite-zotero-plugin] onStartup fired); // 在这里注册菜单、快捷键、偏好面板等 }; plugin.hooks.onShutdown () { console.log([scite-zotero-plugin] onShutdown fired); }; export default plugin;逻辑说明onStartup是插件每次随 Zotero 启动时执行的入口。所有需要常驻的功能——比如给 ZoteroPane 的条目右键菜单加一项——都要在这里注册。onShutdown则是清理现场的地方比如移除菜单项、释放监听器。参数说明如果你改动了 hooks 里的代码需要重新构建并重装插件。Zotero 的“重新加载插件”功能在调试时会用到但要注意重新加载不等于重新安装生命周期函数会重新走一遍。4.3 从选中条目到 scite 数据关键函数与参数这个插件最有价值的逻辑是把 Zotero 条目变成 scite 能识别的 DOI再请求 scite API。核心流程分三段拿选中条目 → 提取 DOI → 请求 scite 接口。// 示例从 Zotero 选中条目中提取 DOI function getSelectedItemDOI(): string | null { const items ZoteroPane.getSelectedItems(); if (items.length 0) return null; const item items[0]; const doi item.getField(DOI) as string; return doi ? doi.trim() : null; }逻辑说明ZoteroPane.getSelectedItems()返回当前选中条目的数组通常只取第一个。item.getField(DOI)是 Zotero 的数据层接口能拿到条目注册表里的 DOI 字段。注意有些条目没有 DOI而是 arXiv ID这时需要额外判断item.libraryID或 extra 字段里是否有 arXiv 编号。参数说明Zotero 的字段名是固定的“DOI” 就是 DOI 字段的接口名。如果你要改成支持 arXiv需要自己解析 item 的 extra 字段那种情况要处理正则匹配。拿到 DOI 后插件会请求 scite 的 API。scite 官方提供了一个面向公众的 API 端点返回 JSON 格式的引用数据。// 示例请求 scite API 获取引用统计 async function fetchSciteData(doi: string): Promiseany { const url https://api.scite.ai/reports/${doi}; const resp await fetch(url, { headers: { Content-Type: application/json }, }); if (!resp.ok) throw new Error(scite API error: ${resp.status}); return resp.json(); }逻辑说明这个接口返回的 JSON 里通常包含total_citations、supporting_citations、contrasting_citations、mentioning_citations这几个字段。插件拿到后直接显示条数或者更进一步把支持/反对的引用列表展示出来。注意 fetch 在 Zotero 环境里是全局可用的不需要额外引入。参数说明这个 API 端点是 scite 公共接口一般不需要 key。但如果你用到了需要鉴权的接口比如批量搜索就要在请求头加Authorization字段格式是Bearer your-token。token 不要在源码里硬编码放到 Zotero 的 prefs 里更合适。5. 避坑笔记scite 插件最常见的五个坑5.1 装了插件没反应现象在 Zotero 插件管理界面装好 scite 插件重启后选中文献右键没有任何新菜单工具栏也没出现新图标。原因最常见的是 Zotero 版本不匹配。scite 插件 manifest.json 里strict_max_version如果写的是 7.0.*而你的 Zotero 是 7.1插件会被自动禁用但插件列表里不会立刻标红只是功能全部失效。还有一种是插件 ID 冲突比如你同时装了之前手动打包的另一个版本Zotero 认为重复。解决先在“工具 → 插件”里点开 scite 插件看右侧状态是启用还是禁用。禁用的话要么换旧版 Zotero要么自己改源码里的 manifest.json 放宽版本号上限然后重新构建。重复安装的全部卸载后只装一个。5.2 构建出来没有 bootstrap.js现象pnpm run build执行成功但打开生成的 xpi里面只有 manifest.json 和一堆静态资源没有 bootstrap.js装到 Zotero 里提示缺少入口脚本。原因esbuild 的入口配置指向了不存在的文件或者 hooks.ts 里没有默认导出 ZoteroPlugin 实例。后者是新手常踩的坑bootstrap.js 生成时依赖源码导出的 plugin 对象你没导出它就生成不出来。解决检查 package.json 里 build 脚本的 esbuild 入口参数确认指向 src/hooks.ts。再检查 hooks.ts 里有没有export default plugin。改成正确导出一行即可。5.3 Zotero 7 升级后 API 不兼容现象插件在 Zotero 6 里一切正常升级到 Zotero 7 后右键菜单没了控制台报错说ZoteroPane未定义或getSelectedItems不存在。原因Zotero 7 对内部对象做了一次大清理很多老式 API 被移到了 Services 命名空间下或者改了调用方式。ZoteroPane 的获取方式从全局变量改成了Zotero.getMainWindow().ZoteroPane这种形式。解决把ZoteroPane.getSelectedItems()改成const zp Zotero.getMainWindow().ZoteroPane; const items zp.getSelectedItems();逻辑说明在 Zotero 7 里ZoteroPane不再是全局变量而是挂在主窗口对象下的属性。Zotero.getMainWindow()能拿到当前的主窗口实例。这样改完之后兼容 Zotero 6 和 7 的写法是在代码里做一层判断判断ZoteroPane是否已是全局。参数说明getSelectedItems在 Zotero 7 里还有个可选的参数控制是否包含子条目默认是 false一般不用动。5.4 scite API 请求失败或超时现象插件能弹窗但里面的引用数据一直是加载中打开调试窗口看到 fetch 请求报 CORS 或超时。原因scite API 的 CORS 策略可能阻止了 Zotero 里的网页请求。Zotero 插件跑在特权环境里但 fetch 请求如果目标是跨域接口仍受同源策略限制。另外scite 的 API 有时会因为参数格式不对返回 403。解决在 manifest.json 的权限声明里加上permissions: [https://api.scite.ai/*]逻辑说明这个声明相当于告诉 Zotero 插件运行时允许向 scite 接口发起跨域请求。加了之后CORS 报错一般就消失了。如果还超时多半是网络问题或者 API 端点在当前地区不稳定这种就属于外部依赖故障插件本身没得修只能等网络恢复。参数说明permissions数组里可以写多个域名但不要写all_urls这种通配Zotero 对宽泛权限审核比较严通配容易导致安装警告。5.5 插件版本号格式不对装不上现象构建出的 xpi 拖进 Zotero 安装时提示“插件版本格式错误”或“invalid version”。原因Zotero 要求 version 字段遵循严格的数字点分格式比如1.0.0。如果你 package.json 里写的是1.0.0-beta.1这种语义化版本号Zotero 7 里会直接拒绝安装。esbuild 构建时不校验这个但 Zotero 装的时候会校验。解决把版本号改成1.0.0或1.0.1。如果你一定要用预发布标记可以写成1.0.0.1这种四段数字或者1.0.0b1Zotero 都能认。6. 进阶给 scite 插件加右键菜单与自定义偏好6.1 在 Item 菜单加一个“查看 scite 引用语境”入口到这个阶段你已经有了一份能编译、能安装、能拉数据的 scite 插件。接下来可以按自己的使用习惯改。我见过多数人会想加一个右键菜单入口因为 zotero-plugin-template 默认可能没有绑定到条目右键菜单。加法的核心是调用Zotero.IntegratedContextMenu或老式的ZoteroPane.ctxMenuPopulated事件。推荐后者Zotero 7 还在用。ZoteroPane.ctxMenuPopulated function (menu, item) { menu.append( new Zotero.MenuSeparator(), new Zotero.MenuItem({ label: View scite Citations, command: scite-view-citation, }) ); };逻辑说明这个钩子会在条目右键菜单弹出时被调用menu是待填充的菜单对象item是当前选中的条目。这里每弹一次菜单就插入一个分隔符和一项“View scite Citations”点击后通过 command 触发的回调里再去处理 scite 请求。6.2 把偏好存进 Zotero 的 prefsscite API 如果要用 token建议存到 prefs 而不是硬编码。Zotero 的 prefs 系统用起来很简单。function getSciteApiKey(): string { return Zotero.Prefs.get(scite.apiKey, true) as string; } function setSciteApiKey(key: string): void { Zotero.Prefs.set(scite.apiKey, key, true); }逻辑说明Zotero.Prefs.get第三个参数传 true 表示这是一个全局偏好不区分 profile。API key 这么存至少不散落在源码里。参数说明偏好字段名可以自定义但建议在 manifest.json 里用prefs段预声明比如prefs: { scite.apiKey: { type: string, value: } }预声明的好处是 Zotero 会帮你建好默认值就算用户没碰过设置项这个 key 也始终存在。6.3 验证插件更新链路是否健康改完这些不要急着就完事。我习惯在每次改动后过一遍这事插件更新时Zotero 会访问update_url指向的 JSON如果这个 JSON 里的addons数组格式不正确Zotero 会反复弹更新失败的提示。scite 官方如果更新了update_url指向的版本号而本地源码没跟着改就会出现“本地版本和在线版本不一致”的死循环。从那以后我每次构建 scite 插件都先把update_url暂时清掉或者指向本地的update.json确认安装、卸载、升级链路没问题再把线上地址补回去。这个习惯帮我省了不少排查时间。希望这篇拆解能让你少走几步弯路顺利跑起自己的 scite 插件。本文还有配套的精品资源点击获取