Zotero 插件 API 与调试：从只读到可控修改

遇到一个 API 名称时，先问它属于文库数据还是某个窗口。核心数据对象和窗口界面不是同一作用域，后台生命周期里也不能假定始终存在当前窗口。官方 JavaScript API 文档可作为入口；遇到文档没有覆盖的能力，应继续查目标 Zotero 版本的源码和模板示例，不把类型提示当作完整兼容保证。

第一个实验只读标题

在独立测试文库选中普通文献条目，再打开“工具→开发者→运行 JavaScript”。下面示例按官方 API 组织，用于了解输入与返回值；核对日期为2026年11月10日，尚未在目标 Zotero 版本逐一真机执行，结果待核实。

// 文档示例：先确认实验配置中已选中测试条目
const pane = Zotero.getActiveZoteroPane();
const selected = pane ? pane.getSelectedItems() : [];
return selected.map(item => ({
  id: item.id,
  title: item.getField('title')
}));

没有选中条目时返回空数组是合理结果。先用这种无写入例子确认自己理解所选对象；附件、笔记和普通文献有不同字段，不能假定每一种对象都能执行相同操作。异步模式需要等待后再返回，控制台里看到一个 Promise 并不等于操作已经完成。

写入从一条测试数据开始

修改条目的通常顺序是检查对象类型与权限、读取旧值、设定字段，再等待保存完成。新建对象也要明确所属文库。事务、集合、附件和笔记各有约束，复制一段字段修改示例不能推出其他操作也相同。本篇不提供面向日常文库的批量改写脚本；请先在自己新建的测试条目验证，并保留修改前后的可比较结果。

保存成功后重新读取数据，确认实际值和界面都符合预期。失败时保留错误，不把提示框“已完成”当作保存证据。若准备触及附件文件或大量记录，先独立设计失败恢复办法，再把操作接入按钮。

事件、界面与设置要能退出

事件通知可以让插件响应条目或窗口变化。读模板的 registerNotifier 示例时，留意登记返回的标识，以及退出时对应的 unregisterObserver。回调里只处理自己关心的事件和对象；写入触发新通知时，还要避免同一任务反复执行。

界面优先参考目标版本提供的注册能力和模板示例，不要为插入一个菜单而到处搜索并修改任意节点。窗口打开时登记，关闭或插件禁用时移除；连续启用两次仍只有一份界面，才是值得保留的基本检查。偏好设置使用项目独有前缀，区分默认值、已保存值和当前界面状态，避免和其他插件同名。

一次只定位一个问题

先记录最短复现步骤，再观察输出。轻量信息可用 Zotero.debug；错误控制台帮助找异常，开发工具用于查看界面与断点。不要把完整文库内容或凭证写入调试日志。模板的 npm start 支持修改后的重建与重载，但热重载能工作也不说明退出清理完整，正式验收还要测试禁用、重启和新窗口。

排查时可依次确认：功能入口是否执行、选择对象是否正确、异步操作是否结束、结果是否真正保存。每次只改变一个条件，用相同测试数据比较前后；这样比同时改多个地方后碰巧恢复更容易查清原因。