Zotero插件开发实战：如何用ChatGPT API打造智能文献助手

1次阅读

没有评论

共计 3400 个字符，预计需要花费 9 分钟才能阅读完成。

科研人员在文献管理中最常遇到的困扰就是信息过载。以 Zotero 为例，当用户每周新增 50 篇文献时：

平均每篇文献需要 5 分钟阅读摘要
手动标注关键信息耗时约 2 分钟 / 篇
分类整理时间约 3 分钟 / 篇

这意味着每周要额外花费 8 小时处理文献，相当于一个完整的工作日。更严峻的是，85% 的标注信息最终并未被实际引用，造成巨大的时间浪费。

无法直接访问 Zotero 本地数据库
受浏览器沙箱限制，不能调用系统级 API
需要额外处理跨域请求问题

完整访问 Zotero.Item 等核心数据结构
支持系统原生模块调用（如文件 IO）
内置 Promise-based 异步 API
可直接修改 UI 界面元素

使用官方模板创建项目骨架：

npx zotero-plugin-template init zotero-gpt-assistant

关键目录结构说明：

chrome/content/: 前端 UI 资源
chrome/locale/: 多语言支持
resource/: 后台逻辑代码

实现带自动重试的流式请求：

/**
 * 带指数退避的 API 请求封装
 * @param {string} prompt - 输入的提示文本
 * @param {number} maxRetries - 最大重试次数
 */
async function queryWithRetry(prompt, maxRetries = 3) {
  let retryDelay = 1000;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.openai.com/v1/chat/completions', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${API_KEY}`
        },
        body: JSON.stringify({
          model: "gpt-3.5-turbo",
          messages: [{role: "user", content: prompt}],
          stream: true
        })
      });

      const reader = response.body.getReader();
      let result = '';

      while (true) {const { done, value} = await reader.read();
        if (done) break;
        result += new TextDecoder().decode(value);
      }

      return result;
    } catch (error) {if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, retryDelay));
      retryDelay *= 2;
    }
  }
}

定义 TypeScript 接口增强类型安全：

interface EnhancedItem extends Zotero.Item {getAbstract: () => Promise<string>;
  setTags: (tags: string[]) => void;
}

const processItem = async (item: EnhancedItem) => {const abstract = await item.getAbstract();
  const summary = await queryWithRetry(` 请用中文总结以下文献核心观点:\n${abstract}`);

  item.setTags(['AI 生成摘要', ...item.getTags()]);
  item.setField('extra', summary);
  await item.saveTx();};

采用队列机制控制请求频率：

class RequestQueue {constructor(maxRequests = 5) {this.queue = [];
    this.activeCount = 0;
    this.maxRequests = maxRequests;
  }

  add(promiseFunc) {return new Promise((resolve, reject) => {this.queue.push({ promiseFunc, resolve, reject});
      this.processNext();});
  }

  processNext() {if (this.activeCount < this.maxRequests && this.queue.length) {
      this.activeCount++;
      const {promiseFunc, resolve, reject} = this.queue.shift();

      promiseFunc()
        .then(resolve)
        .catch(reject)
        .finally(() => {
          this.activeCount--;
          this.processNext();});
    }
  }
}

使用 IndexedDB 存储 API 响应：

const dbPromise = new Promise((resolve) => {const request = indexedDB.open('ZoteroGPTCache', 1);

  request.onupgradeneeded = (event) => {
    const db = event.target.result;
    db.createObjectStore('responses', { keyPath: 'hash'});
  };

  request.onsuccess = () => resolve(request.result);
});

async function getCachedResponse(hash) {
  const db = await dbPromise;
  return new Promise((resolve) => {const tx = db.transaction('responses');
    const store = tx.objectStore('responses');
    const request = store.get(hash);

    request.onsuccess = () => resolve(request.result?.data);
  });
}

Zotero 7+ 必须包含这些关键配置：

{
  "manifest_version": 2,
  "applications": {
    "zotero": {
      "strict_min_version": "7.0",
      "id": "gpt-assistant@example.com"
    }
  },
  "background": {"scripts": ["resource/background.js"]
  }
}

处理主线程阻塞问题：

// 错误做法：直接在主线程执行耗时操作
ZoteroPane.addMenuItem({callback: () => processLargeCollection() // 会导致 UI 冻结});

// 正确做法：使用 setTimeout 分片
async function processLargeCollection() {const ids = await Zotero.Items.getAllIDs();
  let index = 0;

  function processBatch() {const batch = ids.slice(index, index + 10);
    if (!batch.length) return;

    await Promise.all(batch.map(processItem));
    index += 10;
    setTimeout(processBatch, 0);
  }

  processBatch();}

进阶开发建议尝试：