简介：面向科研人员与 Zotero 深度用户的 scite 插件源码包，用于在文献管理界面中直接查看论文的 Smart Citation 分类统计，包括支持性、提及性与对比性引用数量，并可快速跳转至站点报告页，适合文献综述、引文核查与学术写作场景。压缩包共 31 个文件，约 1.24MB，以 TypeScript 源码和 XUL 界面文件为核心，辅以 JSON 配置、PNG 截图及构建脚本，便于理解插件从数据请求、条目面板渲染到菜单交互的实现脉络。已有 1163 人学习下载。借助完整源码与工程配置，读者可研究 Zotero 插件开发流程、引文分类数据的展示方式，并据此进行二次开发或本地调试，亦可作为 TypeScript 桌面扩展项目的参考案例。
1. 引文语境盲区：scite Zotero 插件到底补了什么
读一篇综述最费劲的地方，往往不是看懂结论，而是判断某条引用到底在支持、在反驳，还是只是被顺手提了一句。scite Zotero 插件解决的正是这个问题：它是一个用 TypeScript 写的 Zotero 扩展，在条目面板和文献列表里直接给出每篇论文的引用语境统计——支持性引用、对比性引用、仅提及三类计数。它适合需要快速判断一篇文献在领域内是被印证还是被质疑的人，也适合在综述写作前做一轮粗筛。插件本身不生产数据，它做的事是把外部引文语境服务的结果，稳稳当当地嵌进你已经在用的文献管理器里。
2. 插件骨架与 TypeScript 编译：从 manifest 到 bootstrap 的加载链路
先把工程结构定下来，后面所有功能才有地方落。这个插件的技术栈是 TypeScript + Zotero 7 插件体系，编译产物是浏览器环境能直接跑的 IIFE。选 TypeScript 不是为了好看，是因为引文语境数据字段多、状态多、缓存键多，靠 JSDoc 兜不住，一个supporting写成support就够你查半小时。
2.1 为什么走 bootstrap 而不是注入 XUL
Zotero 7 移除了 overlay 式的界面扩展机制，插件必须以 bootstrap 方式加载：xpi 根目录放manifest.json和bootstrap.js，Zotero 在启动、关闭、安装、卸载时调用固定命名的钩子函数。这个变化带来的直接影响是，界面元素不能靠改 XUL 文件声明式注入，得在运行时用 DOM API 和 Zotero 提供的管理器去注册。很多人第一次写 Zotero 7 插件就是卡在这——照着 Zotero 6 的教程写了一遍 overlay，装上去毫无反应，也不报错，属于典型的黑匣子体验。
manifest 里最关键的两个字段是插件 ID 和版本区间。ID 一旦发布就不能改，改了等于换了个插件，用户那边的旧数据、旧配置全部对不上。版本区间写窄了，Zotero 小版本一升级插件就被静默禁用，用户只会觉得"装完没反应"。
{ "manifest_version": 2, "name": "scite-zotero-plugin", "version": "0.1.0", "description": "在 Zotero 条目面板中展示文献的引用语境统计", "applications": { "zotero": { "id": "scite-zotero-plugin@local.dev", "strict_min_version": "7.0", "strict_max_version": "7.*" } } }strict_max_version我给的是7.*，不是精确到7.0.11。插件用到的管理器接口在小版本内基本稳定，锁死小版本只会让升级变麻烦。如果你的插件依赖了某个特定版本才有的 API，再考虑收紧，否则别自找麻烦。
bootstrap.js 保持极薄，只做转发。真正的逻辑全在 TypeScript 编译出来的包里，这样调试时心智负担小：出问题要么在加载链路，要么在业务代码，不会两边都怀疑。
// bootstrap.js —— 只负责生命周期转发，不放业务逻辑 var ScitePlugin; function install() {} async function startup({ id, version, rootURI }) { // 把编译产物挂到全局，再交给 TypeScript 侧的入口 Services.scriptloader.loadSubScript(rootURI + "chrome/content/scripts/index.js"); await ScitePlugin.hooks.onStartup({ id, version, rootURI }); } async function shutdown() { // 必须在这里把注册过的 UI 元素全部注销，否则重装会残留 if (ScitePlugin) await ScitePlugin.hooks.onShutdown(); } function uninstall() {} // Zotero 通过这个固定签名取窗口引用 function onMainWindowLoad({ window }) { if (ScitePlugin) ScitePlugin.hooks.onMainWindowLoad(window); } function onMainWindowUnload({ window }) { if (ScitePlugin) ScitePlugin.hooks.onMainWindowUnload(window); }这里的逻辑说明：loadSubScript同步执行编译产物，所以紧接着就能拿到全局变量；钩子函数名是 Zotero 硬编码的，拼错一个字母不会报错，只会静默不执行。参数说明上，rootURI是插件安装目录的 file:// 形式地址，拼路径时结尾的斜杠一定要保留，漏掉就会拼出...addonchrome/...这种畸形路径。
2.2 目录骨架与编译配置
目录按"源码 / 静态资源 / 构建产物"三段切分，构建产物不进版本库。这样做的实际好处是，你随时可以删掉build/重新生成，不会误删了手写的 bootstrap.js。
scite-zotero-plugin/ ├─ src/ │ ├─ index.ts # 入口，导出 hooks │ ├─ api.ts # 请求与归一化 │ ├─ cache.ts # 本地缓存读写 │ ├─ pane.ts # 条目面板 │ ├─ column.ts # 列表列 │ └─ menu.ts # 右键菜单 ├─ addon/ # 原样拷贝进 xpi 的静态文件 │ ├─ manifest.json │ ├─ bootstrap.js │ ├─ prefs.js │ └─ chrome/content/icons/ ├─ esbuild.mjs ├─ tsconfig.json └─ package.jsonTypeScript 只做类型检查，不产出运行代码；打包交给 esbuild。这么做是因为 Zotero 内部脚本加载器不吃 ES Module，必须打成 IIFE。
{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "noEmit": true, "skipLibCheck": true, "types": ["zotero-types"] }, "include": ["src/**/*.ts"] }// esbuild.mjs import { build } from "esbuild"; import { cpSync, rmSync, mkdirSync } from "node:fs"; rmSync("build", { recursive: true, force: true }); mkdirSync("build", { recursive: true }); cpSync("addon", "build", { recursive: true }); await build({ entryPoints: ["src/index.ts"], bundle: true, format: "iife", // Zotero 的 loadSubScript 只认传统脚本 globalName: "ScitePlugin", // 必须和 bootstrap.js 里的变量名一致 target: ["firefox115"], // Zotero 7 基于 Firefox 115 ESR outfile: "build/chrome/content/scripts/index.js", sourcemap: false, // 发布版关掉，调试版可开 inline });globalName和 bootstrap.js 里的var ScitePlugin必须字面一致，这是最容易出低级错误的接缝。target设成 firefox115 是有依据的，Zotero 7 的渲染引擎就是这个版本，设太低会白白丢掉可选链之类的语法糖，设太高可能产出运行时不存在的新语法。
2.3 入口 hooks 与全局状态
TypeScript 侧的入口只做四件事：初始化、注册 UI、注销 UI、清理缓存。全局状态用一个模块级对象持有，不往Zotero全局对象上乱挂东西——挂了以后很难判断是谁污染了全局。
// src/index.ts const pluginID = "scite-zotero-plugin@local.dev"; const state = { registered: [] as Array<() => void>, // 每个注册动作配一个注销函数 rootURI: "", }; export const hooks = { async onStartup({ rootURI }: { rootURI: string }) { state.rootURI = rootURI; await initSchema(); // 建缓存表 registerItemPane(pluginID, state); registerColumns(pluginID, state); registerMenu(pluginID, state); Zotero.debug("[scite] 启动完成"); }, async onShutdown() { // 倒序执行，先注册的后注销 for (const off of state.registered.reverse()) { try { off(); } catch (e) { Zotero.debug(`[scite] 注销失败: ${e}`); } } state.registered.length = 0; }, onMainWindowLoad(win: Window) {}, onMainWindowUnload(win: Window) {}, };state.registered数组这个设计是血泪经验换来的。Zotero 的 UI 管理器大多返回一个注销句柄或者接受一个注销调用，但如果你的注册动作散落在好几个文件里，很容易漏掉一个。统一收集成() => void，关停时倒序跑一遍，就不会出现"禁用插件后列还在、点一下报错"的尴尬局面。倒序是为了处理依赖关系，后注册的东西一般依赖先注册的。
3. 引文语境数据层：DOI 归一、并发限流与三级缓存
数据层是这个插件真正的心脏。界面好看不好看是次要的，能不能在打开一个两百条文献的集合时不卡死、不把配额打光，全看这一层。
3.1 DOI 归一化：前置过滤比请求本身更容易翻车
Zotero 条目里的 DOI 字段脏得超乎想象：有带https://doi.org/前缀的，有带doi:前缀的，有末尾跟着句号和右括号的，有全大写和小写混着的。直接拿这个字符串去拼 URL，轻则 404，重则把带斜杠的路径拼成两级，请求打到别的端点上去。
// src/api.ts const PREFIX_RE = /^(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)/i; const DOI_RE = /^10\.\d{4,9}\/\S+$/; export function normalizeDoi(raw?: string | null): string | null { if (!raw) return null; let doi = raw.trim().replace(PREFIX_RE, ""); // 去掉从参考文献里复制时带出来的尾部标点 doi = doi.replace(/[.,;:)\]}]+$/, ""); if (!DOI_RE.test(doi)) return null; return doi.toLowerCase(); // DOI 大小写不敏感，统一小写做缓存键 }逻辑说明：先剥前缀，再剥尾部标点，最后用正则卡格式。\d{4,9}是 DOI 注册机构号的实际长度区间，这个约束能挡掉一批把 ISBN 或 PMID 错填进 DOI 字段的条目。参数上，函数返回null而不是抛异常，是刻意的——批量遍历时，一条脏数据不应该打断整批任务。
还有一个前置判断：只有条目类型属于期刊文章、会议论文、预印本这几类时才值得去查。书籍章节、数据集、软件的 DOI 在引文语境库里基本是空的，白跑一趟还占配额。常见做法是先按item.itemType过滤一道，再按有没有 DOI 过滤第二道，两道下来能砍掉三成无效请求。
3.2 请求封装：超时、去重与错误分级
请求层要解决三个问题：单次请求不能无限等、同一个 DOI 并发进来只发一次、失败要能区分"没有数据"和"请求出错"。第一种情况是正常的空结果，不该重试也不该报错；第二种才需要退避。
export interface Tallies { supporting: number; contrasting: number; mentioning: number; total: number; } const API_BASE = "https://api.scite.ai"; // 端点以官方文档为准，抽成常量便于替换 const inFlight = new Map<string, Promise<Tallies | null>>(); export function getTallies(doi: string, timeoutMs = 8000): Promise<Tallies | null> { const key = doi.toLowerCase(); // 同一个 DOI 的并发请求合并成一个，避免列表滚动时打出一串重复请求 const running = inFlight.get(key); if (running) return running; const task = (async () => { const ctrl = new AbortController(); const timer = setTimeout(() => ctrl.abort(), timeoutMs); try { const res = await fetch(`${API_BASE}/tallies/${encodeURIComponent(key)}`, { signal: ctrl.signal, headers: { Accept: "application/json" }, }); if (res.status === 404) return null; // 库里没有这篇，属于正常空结果 if (res.status === 429) throw new Error("RATE_LIMIT"); if (!res.ok) throw new Error(`HTTP_${res.status}`); return normalizeTallies(await res.json()); } catch (e) { Zotero.debug(`[scite] ${key} 拉取失败: ${e}`); return null; // 失败不缓存，下次还会重试 } finally { clearTimeout(timer); inFlight.delete(key); } })(); inFlight.set(key, task); return task; } function normalizeTallies(json: any): Tallies { const t = json?.tallies ?? json ?? {}; const pick = (v: unknown) => Math.max(0, Math.trunc(Number(v) || 0)); const supporting = pick(t.supporting); const contrasting = pick(t.contrasting); const mentioning = pick(t.mentioning); return { supporting, contrasting, mentioning, total: pick(t.total) || supporting + contrasting + mentioning, }; }参数说明：timeoutMs默认 8 秒，是因为 Zotero 在打开大集合时主线程压力已经不小，单条请求拖太久会让界面感觉发黏；inFlight这个 Map 用 DOI 小写做键，和归一化保持一致；normalizeTallies里的pick做了三重防御——非数字、负数、小数都归到合法的非负整数，因为外部接口的字段类型不保证和你预期的一样。
API_BASE单独抽出来是必须的。这类第三方服务端点调整不算罕见，散落在代码里十几处 URL 拼接，改一次要全局搜索半天还容易漏。
3.3 缓存设计：数据库表比 prefs 靠谱
把统计结果塞进Zotero.Prefs里是很多人的第一反应，简单是简单，但几百条 DOI 的 JSON 字符串塞进首选项，读写都会变慢，而且没有索引、没有条件查询。建一张小表成本很低，收益明显。
// src/cache.ts export async function initSchema() { await Zotero.DB.queryAsync( `CREATE TABLE IF NOT EXISTS sciteTallies ( doi TEXT PRIMARY KEY, supporting INTEGER NOT NULL DEFAULT 0, contrasting INTEGER NOT NULL DEFAULT 0, mentioning INTEGER NOT NULL DEFAULT 0, total INTEGER NOT NULL DEFAULT 0, fetchedAt INTEGER NOT NULL )` ); await Zotero.DB.queryAsync( `CREATE INDEX IF NOT EXISTS idx_scite_tallies_fetchedAt ON sciteTallies (fetchedAt)` ); } const MAX_AGE_MS = 14 * 24 * 3600 * 1000; // 引文统计变化慢，两周足够 export async function readCache(doi: string): Promise<Tallies | null> { const row = await Zotero.DB.rowQueryAsync( "SELECT supporting, contrasting, mentioning, total, fetchedAt FROM sciteTallies WHERE doi = ?", [doi] ); if (!row) return null; if (Date.now() - row.fetchedAt > MAX_AGE_MS) return null; // 过期当没有 return { supporting: row.supporting, contrasting: row.contrasting, mentioning: row.mentioning, total: row.total, }; } export async function writeCache(doi: string, t: Tallies) { await Zotero.DB.queryAsync( `INSERT INTO sciteTallies (doi, supporting, contrasting, mentioning, total, fetchedAt) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(doi) DO UPDATE SET supporting = excluded.supporting, contrasting = excluded.contrasting, mentioning = excluded.mentioning, total = excluded.total, fetchedAt = excluded.fetchedAt`, [doi, t.supporting, t.contrasting, t.mentioning, t.total, Date.now()] ); }fetchedAt上建索引是为了后面那句清理语句能走索引：定期把超过 90 天的行删掉，表不会无限膨胀。MAX_AGE_MS设两周而不是一天，是因为引用语境统计本身变化很慢，一篇论文的支持/对比比例不会隔夜翻盘，缓存太短等于白白消耗配额。
批量预取用一个固定大小的 worker 池，不要用Promise.all一把梭。两百条文献同时发请求，轻则触发限流，重则被对方直接掐断。
export async function prefetch(dois: string[], concurrency = 4) { const queue = [...new Set(dois)]; const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => { while (queue.length) { const doi = queue.shift()!; if (await readCache(doi)) continue; // 命中缓存直接跳过 const t = await getTallies(doi); if (t) await writeCache(doi, t); await Zotero.Promise.delay(120); // 主动让出，别把连接池占满 } }); await Promise.all(workers); }并发数 4 是个经验值，再高对端不一定给你这么快，本地 SQLite 写入也会开始排队。delay(120)这一行看着多余，实际能显著降低被限流的概率，属于典型的"看起来能删、删了就出事"。
4. 界面注入：条目面板、列表列与右键批量预取
数据有了，接下来是把它放到用户看得见的地方。Zotero 7 提供了三个管理器接口：条目面板、列表列、菜单。三者的用法风格一致，都是"注册 + 拿注销句柄"，但细节坑不少。
4.1 条目面板：同步渲染骨架，异步补数据
条目面板是主战场。用户点开一条文献，右侧面板里应该立刻出现一行统计，不能转圈转三秒。做法是onRender同步读缓存填数字，onAsyncRender再去发请求补差值。
// src/pane.ts export function registerItemPane(pluginID: string, state: any) { Zotero.ItemPaneManager.registerSection({ paneID: "scite-tallies", pluginID, header: { l10nID: "scite-section-head", icon: "chrome://scite-zotero-plugin/content/icons/scite-16.svg", }, onRender: ({ body, item }) => { // 同步阶段：只读缓存，绝不发网络请求 const doi = normalizeDoi(item?.getField?.("DOI")); body.replaceChildren(); if (!doi) { body.append(makeNote("该条目没有可用的 DOI")); return; } const cached = readCacheSync(doi); // 内存镜像，见 4.3 body.append(cached ? makeBadges(cached) : makeNote("正在获取…")); }, onAsyncRender: async ({ body, item }) => { const doi = normalizeDoi(item?.getField?.("DOI")); if (!doi) return; if (readCacheSync(doi)) return; // 已有缓存就不重复请求 const t = await getTallies(doi); if (!t) return; await writeCache(doi, t); body.replaceChildren(makeBadges(t)); }, }); state.registered.push(() => { Zotero.ItemPaneManager.unregisterSection(pluginID, "scite-tallies"); }); }关键的取舍在onRender里：它是同步的，一旦在这里 await 网络，整个条目面板的渲染都会被拖住。readCacheSync读的是一个内存镜像，不是数据库——数据库查询是异步的，同步接口拿不到。这个内存镜像在启动时全量加载一次，之后每次写库同步更新，几百到几千条记录的内存开销可以忽略。
注销用的是unregisterSection(pluginID, paneID)这种双参数形式，不同 Zotero 小版本的签名可能略有差异，接入时对着自己那版的类型定义确认一下，别照抄。
4.2 列表列：dataProvider 必须是纯函数
列表列的价值在于一眼扫过去就能看出哪几篇是争议文献。但列渲染的调用频率极高——滚动、排序、刷新都会触发，所以dataProvider里绝对不能有 IO。
// src/column.ts export function registerColumns(pluginID: string, state: any) { const cols = [ { key: "sciteSupporting", label: "支持" }, { key: "sciteContrasting", label: "对比" }, ]; for (const c of cols) { Zotero.ItemTreeManager.registerColumns({ pluginID, dataKey: c.key, label: c.label, dataProvider: (item: Zotero.Item) => { const doi = normalizeDoi(item.getField("DOI")); if (!doi) return ""; const cached = readCacheSync(doi); if (!cached) return "—"; return String(c.key === "sciteSupporting" ? cached.supporting : cached.contrasting); }, renderCell: (index, data, column, isFirstColumn, doc) => { const span = doc.createElement("span"); span.textContent = data; // 对比数不为 0 时标红，方便扫读 if (column.dataKey === "sciteContrasting" && data !== "—" && Number(data) > 0) { span.style.color = "#c0392b"; span.style.fontWeight = "600"; } return span; }, }); state.registered.push(() => { Zotero.ItemTreeManager.unregisterColumns(pluginID, c.key); }); } }dataProvider返回字符串，数字要显式String()转换，直接返回 number 在部分版本会渲染成空白。renderCell里创建元素必须用传入的doc参数，不能直接用全局document——Zotero 可能有多窗口，用全局 document 创建的元素插到另一个窗口会报错。
4.3 内存镜像与右键批量预取
内存镜像用一个 Map 维护，写库时同步更新，启动时一次性灌入。
// src/cache.ts（续） const memory = new Map<string, Tallies>(); export function readCacheSync(doi: string): Tallies | null { return memory.get(doi.toLowerCase()) ?? null; } export async function warmupMemory() { const rows = await Zotero.DB.queryAsync( "SELECT doi, supporting, contrasting, mentioning, total FROM sciteTallies WHERE fetchedAt > ?", [Date.now() - MAX_AGE_MS] ); memory.clear(); for (const r of rows ?? []) { memory.set(r.doi, { supporting: r.supporting, contrasting: r.contrasting, mentioning: r.mentioning, total: r.total, }); } }writeCache里补一行memory.set(doi, t)，镜像和数据库就不会脱节。启动顺序上，warmupMemory()要在注册界面之前 await 完，否则第一批onRender会全部读到空。
右键菜单挂批量预取，用户选中一批条目后一次性把数据灌满，之后滚动就都是缓存命中。
// src/menu.ts export function registerMenu(pluginID: string, state: any) { Zotero.MenuManager.registerMenu({ menuID: "scite-prefetch", pluginID, target: "main/library/item", menus: [{ menuType: "menuitem", l10nID: "scite-prefetch-label", onCommand: async (_event: Event, context: any) => { const items: Zotero.Item[] = context?.items ?? []; const dois = items .map((it) => normalizeDoi(it.getField("DOI"))) .filter((d): d is string => !!d); if (!dois.length) { Zotero.getActiveZoteroPane().displayErrorMessage("所选条目里没有可用的 DOI"); return; } await prefetch(dois, 4); Zotero.getActiveZoteroPane().displayErrorMessage(`已更新 ${dois.length} 条`); }, }], }); state.registered.push(() => { Zotero.MenuManager.unregisterMenu(pluginID, "scite-prefetch"); }); }context.items这个字段名和菜单注册的参数结构，不同 Zotero 7 小版本之间有微调，接的时候对着自己环境的类型定义核一遍，别硬抄。菜单 ID 和 panelID 一样，注册和注销必须成对出现且字面一致，写错一个字符就是残留。
5. 常见问题排查：五条真会遇到的坑和一套定位路径
插件类项目的问题有个共同点：出错时往往不报错，只是"没反应"。下面五条是我在这类插件上反复撞到的，每条都按现象、原因、解决写清楚，能省掉你不少盲猜时间。
5.1 五条踩坑记录
坑一：装完插件，菜单和面板全都不出现，也没有任何提示。现象是 Zotero 重启后一切照旧，扩展列表里能看到插件已启用。原因是bootstrap.js不在 xpi 的根目录，而是被压进了某个子目录，Zotero 找不到生命周期函数，就把插件当成纯声明式的挂了空挡。解决方式是重新打包，确认压缩包里第一层就能看到manifest.json和bootstrap.js，用解压工具打开 xpi 看一眼最直接。
坑二：条目明明有 DOI，面板却一直显示"正在获取…"。现象是面板永远停在加载态。原因通常是归一化之后仍然拼出了非法 URL——比如 DOI 里带了空格或中文全角括号，encodeURIComponent编完之后对端返回 400，而代码里把 400 也当成空结果return null，于是既不写缓存也不显示。解决是把非 2xx 的响应按状态码分级打日志，同时把归一化正则收紧，遇到非法字符直接判null走"无可用 DOI"分支。
坑三：打开大集合后 Zotero 明显卡顿，滚动条一顿一顿。现象是列表滚动不顺。原因是在dataProvider或renderCell里做了数据库查询甚至网络请求。这两个回调在一次滚动中会被调用成百上千次，任何 IO 都会被放大成肉眼可见的卡顿。解决是严格保证这两个函数只读内存 Map，所有落库动作放进onAsyncRender或批量预取里。这条踩一次就够记一辈子。
坑四：跑了一次批量预取，配额直接被限流，之后半小时都用不了。现象是预取到一半全部失败，日志里清一色 429。原因是并发开太大或者没有做请求去重，同一个 DOI 因为出现在多个条目里被重复请求。解决是把并发压到 4，用inFlightMap 做进行中合并，并在 worker 之间加一点延迟；同时对 429 做一次指数退避，第一次退 2 秒，第二次退 8 秒，别硬刚。
坑五：禁用再启用插件后，列表里出现两列一模一样的"支持"。现象是列重复。原因是onShutdown里没有注销，或者注销时用的dataKey和注册时不一致。Zotero 的注册管理器不会自动清理插件留下的东西，它只认注销调用。解决是把每个注册动作的注销函数统一收集到state.registered数组里，关停时倒序执行；并且把dataKey、paneID、menuID抽成常量，注册和注销引用同一个常量，从根上消除拼写差异。
5.2 一套可复用的定位路径
出问题先分层，别一上来就读业务代码。第一层看加载：打开"帮助 → 调试输出"窗口，重启 Zotero，看有没有插件加载相关的报错，这层能定位九成的"完全没反应"。第二层看注册：用"工具 → 开发者 → Run JavaScript"在 Zotero 窗口里执行几句检查，确认面板和列到底注册上没有。
// 在 Run JavaScript 窗口里执行，逐段排查注册状态 const pluginID = "scite-zotero-plugin@local.dev"; Zotero.debug("面板是否注册: " + !!Zotero.ItemPaneManager.getSection?.(pluginID, "scite-tallies")); Zotero.debug("缓存表行数: " + (await Zotero.DB.valueQueryAsync("SELECT COUNT(*) FROM sciteTallies"))); Zotero.debug("内存镜像大小: " + (typeof ScitePlugin !== "undefined" ? "已加载" : "未加载"));第三层看数据：直接在 Run JavaScript 里调一次getTallies，把返回值和缓存表里的行对比，能快速区分"请求没通"和"渲染没刷新"。这条路径固定下来之后，绝大多数问题十分钟内能定位到具体哪一层，比漫无目的地加console.log高效得多。
注意：调试期间频繁重装插件时，务必先确认
onShutdown干净退出。残留的 UI 元素会让下一次启动的表现变得完全不可预测，我曾经因为一个没注销的列排查了整整一个下午。
6. 打包、验证与一个能省事的自检习惯
出 xpi 之前有一道容易漏的检查：build/目录里除了代码，还得把prefs.js带上。Zotero 读取默认首选项靠的是这个文件，没有它，你在代码里Zotero.Prefs.get("extensions.scite.timeout")拿到的是undefined，然后超时逻辑静默走默认分支——不报错，但行为和你预期不一样。
# 打包脚本，注意 -x 排除构建残留 cd build zip -r -FS ../scite-zotero-plugin.xpi . \ -x "*.map" -x "*.ts" -x "__MACOSX/*" -x ".DS_Store"-FS让 zip 同步文件列表，重复打包不会累积旧条目，这个参数在小步迭代时特别有用。打完包别急着装，先解压看一眼层级：manifest.json、bootstrap.js、chrome/三者必须在同一层。
验证分三步走。第一步装到干净的 Zotero 配置里，别在开发机上装——开发机上往往已经有旧版本残留，装上去看着正常，发给别人就翻车。第二步用 Run JavaScript 手动跑一次完整链路，确认从归一化到写库每一步都有返回值。
const doi = ScitePlugin.normalizeDoi("https://doi.org/10.1000/ABC.123."); Zotero.debug("归一化结果: " + doi); const t = await ScitePlugin.getTallies(doi); Zotero.debug("拉取结果: " + JSON.stringify(t));第三步做一次"断网复现"：拔掉网络，打开十几条文献，确认界面不卡、不报错、显示降级文案，恢复网络后能自动补上。这一步能暴露掉大部分把网络请求塞进同步渲染路径的问题。
进阶一点的做法，是给自己加一条离线自检命令：遍历缓存表，把total和三个分项之和对不上的行挑出来。
SELECT doi, supporting, contrasting, mentioning, total FROM sciteTallies WHERE total <> supporting + contrasting + mentioning LIMIT 20;正常情况下这条查询应该返回空。返回了行，说明某次归一化逻辑有问题，或者对端字段语义变了。这个自检我固定在每次发版前跑一遍，比等用户反馈快得多。
从那以后我每次发版前，都强制走一遍"干净配置安装 → 断网复现 → 自检 SQL"这套流程，哪怕只改了一行样式。插件这类东西出问题的地方往往不在你改的那一行，而在你以为不会动的那一层。希望帮到你。
本文还有配套的精品资源，点击获取
