Zotero文献查重API使用：构建自定义相似度分析工具

2026-02-05 05:27:29作者：裘晴惠Vivianne

你是否在管理大量文献时遇到重复引用的问题？手动比对文献标题、作者和年份不仅耗时，还容易遗漏相似条目。本文将带你利用Zotero内置的文献查重API，构建一个自定义相似度分析工具，自动识别重复文献并生成可视化报告，让文献管理效率提升300%。读完本文，你将掌握：

Zotero查重核心算法原理
如何调用Duplicates API获取相似文献集
构建自定义查重规则的实现方法
生成交互式相似度分析报告的技巧

Zotero查重机制解析

Zotero的文献查重功能由chrome/content/zotero/xpcom/duplicates.js模块实现，采用多维度特征匹配算法，通过以下步骤识别重复文献：

数据预处理：对标题、作者等文本进行标准化处理，包括去除标点、大小写转换和特殊字符清理

function normalizeString(str) {
  str = Zotero.Utilities.removeDiacritics(str)
    .replace(/[ !-/:-@[-`{-~]+/g, ' ') // 标点转空格
    .trim()
    .toLowerCase();
  return str;
}

特征提取：从文献元数据中提取关键特征值，建立查重索引：
- 标准标识符：ISBN（书籍）、DOI（期刊文章）
- 内容特征：标准化标题、作者组合、出版年份
- 时间特征：出版日期的年份信息

相似度计算：采用并查集(Disjoint Set Forest) 数据结构进行聚类分析，将相似文献归入同一集合：

// 并查集实现核心代码
Zotero.DisjointSetForest.prototype.union = function (x, y) {
  var xRoot = this.find(x);
  var yRoot = this.find(y);
  if (xRoot.rank < yRoot.rank) {
    xRoot.parent = yRoot;
  } else if (xRoot.rank > yRoot.rank) {
    yRoot.parent = xRoot;
  } else {
    yRoot.parent = xRoot;
    xRoot.rank++;
  }
}

Duplicates API核心功能

Zotero提供了完整的查重API接口，主要包含在Zotero.Duplicates类中，关键方法如下：

1. 获取查重搜索对象

// 创建查重实例
const duplicates = new Zotero.Duplicates(libraryID);
// 获取查重结果搜索对象
const search = await duplicates.getSearchObject();
// 执行搜索获取重复文献ID
const itemIDs = await search.search();

该方法内部会创建临时表存储查重结果，通过tmpDuplicates_前缀的临时表实现高效查询，如duplicates.js#L49所示：

var table = 'tmpDuplicates_' + Zotero.Utilities.randomString();
var sql = `CREATE TEMPORARY TABLE ${table} (id INTEGER PRIMARY KEY)`;

2. 获取文献相似集

通过getSetItemsByItemID方法可获取指定文献的所有相似文献ID：

// 获取与目标文献相似的所有文献ID
const similarItems = duplicates.getSetItemsByItemID(targetItemID);

该功能由Zotero.DisjointSetForest实现集合管理，通过findAllInSet方法提取同一集合中的所有文献ID。

构建自定义查重工具

基于Zotero的Duplicates API，我们可以构建满足特定需求的自定义查重工具。以下是一个完整的实现示例，增加了自定义相似度阈值和多字段权重配置功能。

1. 扩展查重类

class CustomDuplicates extends Zotero.Duplicates {
  constructor(libraryID, options = {}) {
    super(libraryID);
    this.options = {
      titleWeight: 0.7,       // 标题权重
      authorWeight: 0.2,      // 作者权重
      yearTolerance: 2,       // 年份容忍度
      minSimilarity: 0.6,     // 最小相似度阈值
      ...options
    };
  }
  
  // 重写相似度计算方法
  _calculateSimilarity(itemA, itemB) {
    let score = 0;
    
    // 标题相似度
    const titleSim = this._titleSimilarity(itemA.title, itemB.title);
    score += titleSim * this.options.titleWeight;
    
    // 作者相似度
    const authorSim = this._authorSimilarity(itemA.creators, itemB.creators);
    score += authorSim * this.options.authorWeight;
    
    // 年份差异检查
    if (Math.abs(itemA.year - itemB.year) > this.options.yearTolerance) {
      return 0; // 超出年份容忍度
    }
    
    return score >= this.options.minSimilarity ? score : 0;
  }
  
  // 自定义标题相似度计算
  _titleSimilarity(titleA, titleB) {
    // 实现改进的编辑距离算法
    const normalizedA = this.normalizeString(titleA);
    const normalizedB = this.normalizeString(titleB);
    return this._levenshteinDistance(normalizedA, normalizedB);
  }
}

2. 实现查重工作流

async function runCustomDuplicateCheck(libraryID, options) {
  const customDup = new CustomDuplicates(libraryID, options);
  
  // 获取查重结果
  await customDup._findDuplicates();
  
  // 获取所有重复文献集
  const duplicateSets = customDup._sets;
  
  // 生成分析报告
  const report = await generateReport(duplicateSets);
  
  return report;
}

可视化相似度报告

结合Zotero的UI组件，我们可以创建交互式查重报告。以下是使用itemPane.js中的组件展示重复文献对比的示例：

<duplicates-merge-pane id="custom-duplicates-pane">
  <div class="similarity-score">
    <span>相似度: <strong>87%</strong></span>
    <div class="progress-bar">
      <div class="progress" style="width: 87%"></div>
    </div>
  </div>
  
  <div class="item-comparison">
    <div class="item-card left">
      <h3>文献A</h3>
      <p class="title">${itemA.title}</p>
      <p class="authors">${formatAuthors(itemA.creators)}</p>
      <p class="year">${itemA.year}</p>
    </div>
    
    <div class="item-card right">
      <h3>文献B</h3>
      <p class="title">${itemB.title}</p>
      <p class="authors">${formatAuthors(itemB.creators)}</p>
      <p class="year">${itemB.year}</p>
    </div>
  </div>
  
  <div class="match-details">
    <h4>匹配详情</h4>
    <ul>
      <li>标题匹配: 92% (${matches.title})</li>
      <li>作者匹配: 75% (${matches.authors})</li>
      <li>出版年份: 一致 (${itemA.year})</li>
    </ul>
  </div>
</duplicates-merge-pane>

实际效果可参考Zotero内置的重复文献合并界面，该界面由duplicatesMergePane.js实现，包含文献对比、字段选择和合并操作功能。

高级应用场景

1. 跨库查重

结合Zotero的多库管理功能，可以实现团队共享库与个人库之间的查重：

async function crossLibraryCheck(mainLibID, compareLibID) {
  // 获取主库文献
  const mainItems = await Zotero.Items.getByLibrary(mainLibID);
  
  // 构建对比库索引
  const compareIndex = await buildLibraryIndex(compareLibID);
  
  // 逐篇比对
  const crossDuplicates = [];
  for (const item of mainItems) {
    const matches = await findSimilarInIndex(item, compareIndex, 0.7);
    if (matches.length) {
      crossDuplicates.push({
        source: item.id,
        matches: matches
      });
    }
  }
  
  return crossDuplicates;
}

2. 批量去重工具

利用zoteroPane.js中的选择功能，实现批量处理重复文献：

// 参考zoteroPane.js中的批量操作实现
Zotero.CustomDuplicates.batchProcess = async function(operation, itemIDs) {
  const progressWindow = new Zotero.ProgressWindow();
  progressWindow.changeHeadline("处理重复文献");
  
  const step = new progressWindow.Step();
  step.setText(`正在${operation === 'merge' ? '合并' : '删除'} ${itemIDs.length}篇文献`);
  step.setProgressBar();
  progressWindow.addStep(step);
  progressWindow.show();
  
  try {
    for (let i = 0; i < itemIDs.length; i++) {
      const itemID = itemIDs[i];
      if (operation === 'merge') {
        await Zotero.Items.merge(itemID, itemIDs[i+1]);
        i++; // 跳过已合并项
      } else {
        await Zotero.Items.trash(itemID);
      }
      step.setProgress(i / itemIDs.length);
    }
    progressWindow.startCloseTimer(2000);
    return true;
  } catch (e) {
    Zotero.logError(e);
    progressWindow.addError("处理失败: " + e.message);
    return false;
  }
};