企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 科研

zotero-AI-Butler（Zotero AI 管家）是一款调用大模型自动精读论文库、并把论文揉碎总结为 Zotero 笔记的 Zotero 插件，支持 OpenAI、Gemini、Anthropic、OpenAI 兼容、火山方舟、Ollama 等主流大模型平台。如果你想为它新增一个大模型 Provider（接入新的大模型平台），本文是一份面向开发者的完整清单：只需 9 步，按序修改对应文件，即可让新平台完整跑通"配置密钥 → 测试连接 → 生成笔记"的全链路。

🏗️ 动手前：30 秒看懂 Provider 架构

AI 管家采用"统一中间件 + Provider 自注册"模式，新增 Provider 前请先弄清三件事：

1. 入口统一：所有上层功能（总结、思维导图、追问）只调用 LLMService，它负责读取偏好、准备 PDF/文本输入、组装LLMOptions，再路由到具体 Provider；
2. 注册机制：Provider 类在文件末尾通过ProviderRegistry.register(new XxxProvider())自注册，由 ProviderRegistry 按id查找；
3. 契约接口：每个 Provider 必须实现 ILlmProvider 接口——核心方法是generateSummary（生成摘要）、chat（多轮对话）、testConnection（测试连接），可选generateMultiFileSummary（多 PDF 摘要）和listModels（模型列表）。

💡 参考 doc/DevelopmentGuide.md 中的"新增 Provider 完整检查清单"章节，以及现有实现（如 OllamaProvider.ts）是最好的模板。

✅ 9 步完整清单

下面以新增一个名为mynewprovider的平台为例，逐步说明。

第 1 步：创建 Provider 类文件 🧩

推荐用脚手架脚本一键生成模板（同时会生成测试文件和.env占位符）：

node scripts/create-provider.mjs MyNewProvider mynewprovider

脚本见 scripts/create-provider.mjs。生成后你还需要手动补充：

• 在capabilities中声明能力：supportsText、supportsStreaming、supportsPdfBase64、maxPdfFiles、supportsSystemPrompt、supportedParams
• 按厂商官方 API 结构实现generateSummary/chat/testConnection（如支持多文件则实现generateMultiFileSummary）
• 文件末尾添加自注册：ProviderRegistry.register(new MyNewProvider())

⚠️ 若厂商不支持 PDF Base64 输入（如 Ollama），请在 Provider 内返回清晰的本地化错误提示，不要在中间件层按名称提前拦截。

第 2 步：导出 Provider

在 src/modules/llmproviders/index.ts 中添加导出，确保加载时触发自注册：

export { default as MyNewProvider } from "./MyNewProvider";

第 3 步：配置 API Key 管理 🔑

修改 src/modules/apiKeyManager.ts，让新平台支持多密钥轮换：

• 在ProviderId类型联合中追加"mynewprovider"
• 在PROVIDER_KEY_MAPPINGS中登记偏好键映射：

mynewprovider: { primaryPrefKey: "myNewProviderApiKey", extraKeysPrefKey: "myNewProviderApiKeysFallback", },

第 4 步：添加默认偏好设置

在 addon/prefs.js 中登记三项默认值（URL、API Key、模型名）：

pref("__prefsPrefix__.myNewProviderApiUrl", "https://api.example.com"); pref("__prefsPrefix__.myNewProviderApiKey", ""); pref("__prefsPrefix__.myNewProviderModel", "default-model");

第 5 步：补充 TypeScript 类型定义

在 typings/prefs.d.ts 中为新偏好项补上类型声明，避免getPref/setPref出现类型报错：

"myNewProviderApiUrl": string; "myNewProviderApiKey": string; "myNewProviderModel": string;

第 6 步：更新 LLMService 配置映射 ⚙️

修改 src/modules/llmService.ts，把新平台接入选项构建与密钥路由：

• 在buildOptions中添加else if (id === "mynewprovider")分支：读取 URL/模型偏好、通过ApiKeyManager.getCurrentKey()取当前可用密钥，填入LLMOptions
• 在mapToKeyManagerId中添加映射：if (id === "mynewprovider") return "mynewprovider";

LLMOptions的完整字段说明见 doc/LLMRefactorDesign.md 与 types.ts（apiUrl、apiKey、model、stream、temperature、maxTokens等，Provider 不支持的字段应忽略而非报错）。

第 7 步：添加 UI 设置界面 ⚠️ 最易遗漏

修改 src/modules/views/settings/ApiSettingsPage.ts，共5 个位置都要改：

1. Provider 下拉选项：追加{ value: "mynewprovider", label: "My New Provider" }
2. 设置区域：创建sectionMyNewProvider，包含 API URL、API Key、Model 三个输入框，并appendChild到表单
3. renderProviderSections：根据当前选中平台切换显示/隐藏该区域
4. saveSettings：通过querySelector获取三个 DOM 元素，写入values对象，添加验证分支和setPref保存调用
5. resetSettings：为新平台添加重置默认值

完成后，用户在设置页即可看到新的平台选项：

第 8 步：更新 API Key 校验逻辑 ⚠️ 容易遗漏

在 src/hooks.ts 的handleGenerateSummary函数中，为新 Provider 添加 API Key 检查分支：

} else if (pLower === "mynewprovider") { selectedApiKey = Zotero.Prefs.get( `${config.prefsPrefix}.myNewProviderApiKey`, true, ) as string; providerName = "My New Provider"; }

⚠️ 若遗漏此步，用户未配置密钥时会看到"请先配置 OpenAI API Key"之类的错误提示，排查成本极高。

第 9 步：更新文档 📄

• README.md 的"支持平台"表格
• doc/DevelopmentGuide.md 的环境变量示例
• docs/api-configuration.md 的配置指南

🧪 测试与质量门控

新增 Provider 后按项目分层测试策略验证（详见 doc/DevelopmentGuide.md）：

在.env中将ACTIVE_LLM_PROVIDER=mynewprovider并填入密钥，测试前置脚本 scripts/gen-env-setup.mjs 会将其写入 Zotero 偏好，只对活动 Provider 执行耗时测试，其余标记pending，避免 CI 噪音。

质量门控：npm run build无类型错误 → 测试全部通过 →npm run lint:check通过，即可提交。

📌 常见坑速查

写在最后

照着这份清单，9 个文件、按序打勾，你的新大模型平台就能完整融入 AI 管家的精读工作流：用户把文献丢进 Zotero，管家自动精读并生成笔记，让你"十分钟完全了解"一篇论文。完整设计细节可继续阅读 doc/DevelopmentGuide.md 与 MultiModelSummaryHandoff.md，祝开发顺利 🚀

• 人工智能
• 大模型
• AI 应用
• 科研