Zotero GPT环境配置指南：从Node.js到OpenAI API密钥设置全流程

1. 环境准备与依赖要求

Zotero GPT插件需要Node.js运行环境及特定版本依赖支持。以下是详细的环境配置步骤：

1.1 系统环境要求

环境项	版本要求	验证命令
Node.js	≥16.0.0	node -v
npm	≥7.0.0	npm -v
Git	任意版本	git --version

1.2 项目克隆与依赖安装

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/zo/zotero-gpt
cd zotero-gpt

# 安装项目依赖
npm install

1.3 开发/生产构建命令

根据使用场景选择构建命令：

# 开发环境构建（保留调试信息）
npm run build-dev

# 生产环境构建（代码压缩优化）
npm run build-prod

# 完整构建（含类型检查）
npm run build

2. 核心配置文件解析

2.1 package.json关键配置

项目依赖配置文件位于根目录，定义了开发和运行时依赖：

{
  "dependencies": {
    "@dqbd/tiktoken": "^1.0.6",          // OpenAI Token计算库
    "langchain": "^0.0.66",             // LLM应用开发框架
    "node-fetch": "^3.3.1",             // HTTP请求库
    "zotero-plugin-toolkit": "^2.0.1"   // Zotero插件开发工具集
  },
  "devDependencies": {
    "typescript": "^5.0.4",             // TypeScript编译器
    "esbuild": "^0.17.4"                // 快速构建工具
  },
  "scripts": {
    "start-z6": "node scripts/start.js --z 6",  // 启动Zotero 6
    "start-z7": "node scripts/start.js --z 7"   // 启动Zotero 7
  }
}

2.2 启动配置文件（scripts/start.js）

该文件负责启动Zotero并加载开发插件：

// 默认启动命令解析逻辑
const startZotero = `${zoteroPath} --debugger --purgecaches ${
  profile ? `-p ${profile}` : ""
}`;

关键参数说明：

• --debugger: 启用调试模式
• --purgecaches: 清除缓存确保加载最新代码
• -p <profile>: 指定Zotero配置文件（可选）

3. OpenAI API密钥配置

3.1 获取OpenAI API密钥

1. 访问OpenAI平台（https://platform.openai.com）
2. 登录账户并导航至API Keys页面
3. 创建新密钥（Create new secret key）
4. 保存密钥备用（离开页面后无法再次查看完整密钥）

3.2 密钥配置方式

Zotero GPT提供两种密钥配置方式：

方式一：通过Zotero偏好设置界面

1. 启动Zotero
2. 打开编辑 > 首选项 > Zotero GPT
3. 在API设置区域输入：
   • API密钥（Secret Key）
   • API基础URL（默认：https://api.openai.com）
   • 模型选择（默认：gpt-3.5-turbo）

方式二：直接修改配置文件

手动编辑插件配置文件（需重启Zotero生效）：

// 配置文件路径：[Zotero配置目录]/prefs.js
user_pref("zoterogpt.secretKey", "sk-xxxxxxxxxxxxxxxxxxxxxxxx");
user_pref("zoterogpt.api", "https://api.openai.com");
user_pref("zoterogpt.model", "gpt-3.5-turbo");

3.3 密钥安全注意事项

• 切勿将API密钥提交至代码仓库
• 避免在公共设备上保存密钥
• 定期轮换密钥以增强安全性
• 配置使用量告警，监控异常访问

4. 启动与验证

4.1 启动Zotero与插件

根据Zotero版本选择启动命令：

# 启动Zotero 6（默认配置）
npm run start-z6

# 启动Zotero 7（实验性支持）
npm run start-z7

# 指定自定义配置文件启动
npm run start-z6 -- -p my-dev-profile

4.2 功能验证流程

1. 插件加载验证：

   • 打开Zotero
   • 检查工具菜单是否存在Zotero GPT选项

2. API连接测试：

   • 选择任意文献条目
   • 右键菜单选择Zotero GPT > 生成摘要
   • 如配置正确，将显示AI生成的文献摘要

3. 常见启动问题排查：

错误现象	可能原因	解决方法
插件未显示	构建失败	重新执行npm run build
API连接超时	网络问题	检查代理设置或API URL
密钥无效	密钥错误或过期	重新生成并配置API密钥
功能异常	依赖版本冲突	删除node_modules后重新安装

5. 高级配置选项

5.1 模型参数配置

通过Zotero偏好设置调整AI模型行为：

• temperature（温度）：控制输出随机性（0.0-1.0）
  • 较低值（0.2）：结果更确定、聚焦
  • 较高值（0.8）：结果更多样化、创造性
• max_tokens（最大令牌数）：控制输出长度
• relatedNumber：相关文献检索数量（默认5）

5.2 本地向量存储配置

插件使用本地存储缓存文献向量以提高性能：

// 向量存储路径（默认位于Zotero配置目录）
const storage = new LocalStorage(config.addonRef);
// 向量计算与缓存逻辑
const id = MD5(docs.map((i: any) => i.pageContent).join("\n\n")).toString();
const _vv = storage.get(obj, id);

缓存文件会自动管理，无需手动干预。

6. 开发环境设置（进阶用户）

6.1 开发工具配置

推荐开发工具组合：

• VS Code + TypeScript插件
• Zotero Debugger扩展
• ESLint（代码检查）

6.2 调试工作流

# 启动监视模式（代码变更自动重建）
npm run build-dev -- --watch

# 新终端窗口启动Zotero调试模式
npm run start-z6

6.3 目录结构说明

zotero-gpt/
├── addon/           # 插件资源目录（图标、本地化文件）
├── src/             # 源代码目录
│   ├── modules/Meet/OpenAI.ts  # OpenAI API交互模块
│   └── index.ts     # 插件入口点
├── scripts/         # 构建与启动脚本
└── tags/            # 提示词模板目录

7. 总结与最佳实践

7.1 配置检查清单

• [ ] Node.js环境已安装
• [ ] 项目依赖已正确安装
• [ ] API密钥已配置并验证
• [ ] 插件构建成功并加载
• [ ] 基础功能测试通过

7.2 性能优化建议

• 定期执行npm run build-prod获取优化构建
• 对于大型文献库，适当增加relatedNumber值
• 如频繁使用特定功能，考虑调整缓存策略

7.3 后续学习路径

1. 探索tags/目录下的提示词模板自定义
2. 学习langchain库扩展AI功能
3. 通过zotero-plugin-toolkit开发自定义功能

通过以上步骤，您已完成Zotero GPT的完整环境配置。该插件将显著提升文献管理效率，特别是在文献筛选、摘要生成和内容分析方面提供AI辅助支持。