Jasminum插件API文档：开发者参考手册与接口说明

Jasminum是一个功能强大的Zotero插件，专门用于识别和抓取中文元数据，特别是中国知网的学术文献信息。这个开发者参考手册将为你详细介绍Jasminum插件的API接口、核心模块和扩展开发方法。🎯

📚 核心架构与模块概览

Jasminum插件的架构设计采用了模块化的思想，主要包含以下几个核心模块：

元数据抓取模块

• CNKI服务模块：src/modules/services/cnki.ts - 负责与中国知网API交互
• 本地附件匹配：src/modules/attachments/localMatch.ts - 智能匹配下载的PDF文件与元数据

UI交互模块

• 菜单系统：src/modules/menu.ts - 管理右键菜单和工具栏
• 首选项面板：src/modules/preferences/ - 包含主设置和转换器配置

工具功能模块

• PDF大纲系统：src/modules/outline/ - 提供PDF书签和导航功能
• 进度管理：src/modules/progress.ts - 显示操作进度

🔧 主要API接口说明

元数据抓取API

Jasminum的核心功能是通过CNKI服务获取中文期刊的完整元数据。开发者可以通过以下方式调用：

// 示例：调用CNKI元数据抓取
const cnkiService = new CNKI();
const results = await cnkiService.searchByTitle("论文标题");

附件匹配API

本地附件匹配功能能够智能识别下载文件夹中的PDF文件，并将其与Zotero中的条目自动关联：

// 示例：本地附件匹配
const localService = new LocalAttachmentService();
const matchedFiles = await localService.matchAttachments(item);

🚀 开发环境配置指南

快速开始步骤

1. 克隆仓库

   git clone https://gitcode.com/gh_mirrors/ja/jasminum
   

2. 安装依赖

   npm install
   

3. 启动开发服务器

   npm start
   

核心配置文件

• 插件清单：addon/manifest.json - 定义插件基本信息
• 首选项配置：addon/prefs.js - 存储用户设置
• 构建配置：zotero-plugin.config.ts - 编译和打包设置

📁 重要源码文件路径

主入口文件

• src/index.ts - 插件的主入口点
• src/addon.ts - 插件基础类定义
• src/hooks.ts - 生命周期钩子函数

工具类文件

• src/utils/ - 包含各种工具函数
  • src/utils/http.ts - HTTP请求处理
  • src/utils/prefs.ts - 首选项管理

💡 扩展开发最佳实践

添加新的数据源

开发者可以扩展src/modules/services/目录，实现新的元数据抓取服务。

自定义匹配规则

通过修改src/modules/attachments/中的算法，可以优化附件匹配的准确性。

🔍 调试与问题排查

开发者工具使用

• 在Zotero中启用开发者工具
• 使用Zotero.debug()输出调试信息
• 查看Help->Debug Output Logging获取详细日志

📈 性能优化建议

1. 缓存机制 - 对频繁访问的数据实现本地缓存
2. 异步处理 - 使用Promise和async/await优化性能
3. 批量操作 - 支持多文件同时处理

Jasminum插件的API设计遵循了Zotero插件开发的最佳实践，为开发者提供了丰富而灵活的接口选择。无论是进行功能扩展还是二次开发，都能找到合适的切入点。🌟