# 故障排除

本指南帮助您诊断和解决使用 AI 管家时遇到的问题。

## 错误代码速查表

| 错误代码/关键词        | 含义                    | 解决方案                                                          |
| ---------------------- | ----------------------- | ----------------------------------------------------------------- |
| `429`                  | API 速率限制 / 配额超限 | [更换免费层级支持的模型](faq.md#-gemini-429-报错--速率限制)       |
| `20015`                | 参数无效                | [切换为文本提取模式](faq.md#-错误-20015-the-parameter-is-invalid) |
| `20041`                | 模型不支持多模态        | [切换为文本提取模式](faq.md#-错误-20041-the-model-is-not-a-vlm)   |
| `401` / `Unauthorized` | API 密钥无效            | 检查密钥是否正确，重新生成密钥                                    |
| `403` / `Forbidden`    | 无权访问                | 检查 API 权限设置，确认账号状态                                   |
| `404`                  | API 路径错误            | 检查 API 路径是否正确，以及模型名是否正确（以官方 API 文档为准）  |
| `500` / `502` / `503`  | 服务端错误              | 等待一段时间后重试，检查平台状态                                  |
| `timeout`              | 请求超时                | 检查网络连接，尝试切换网络环境                                    |

---

## 自查清单

遇到问题时，请按以下步骤逐一排查：

### ✅ 1. 模型平台检查

- [ ] API 密钥是否正确填写（无多余空格）
- [ ] 已在对应模型详情中点击 **"测试连接"** 并显示成功
- [ ] 模型名称拼写正确（区分大小写）
- [ ] 如使用 OpenAI 兼容接口，Base URL 是否正确

### ✅ 2. 模型兼容性检查

- [ ] 使用的模型是否支持多模态（如果使用 Base64 模式）
- [ ] 如模型不支持多模态，是否已切换为 **文本提取** 模式

### ✅ 3. 文献条目检查

- [ ] 选中的是条目（非 PDF 附件本身）
- [ ] 条目下方有 PDF 附件
- [ ] PDF 文件没有损坏，能正常打开

### ✅ 4. 网络环境检查

- [ ] 网络连接正常
- [ ] 如使用代理，确认代理工作正常
- [ ] 某些平台可能需要特定网络环境

### ✅ 5. 第三方平台验证

- [ ] Cherry Studio 进行相同配置，是否能够正常使用

---

## 提交有效的 Bug 报告

如果问题无法自行解决，请提交 Issue。为帮助快速定位问题，请提供：

### 必要信息

1. **Zotero 版本**：例如 `7.0.30`
2. **AI 管家版本**：例如 `1.3.0`
3. **操作系统**：Windows / macOS / Linux
4. **使用的 AI 平台和模型**：例如 `Gemini gemini-2.0-flash`

### 问题描述

1. **完整的错误信息**：包括错误代码和提示文字
2. **重现步骤**：如何操作会触发这个问题
3. **截图/录屏**：如果方便，提供问题界面的截图

### 查看 Zotero Error Console

1. 打开 Zotero → **"工具"** → **"开发者"** → **"Error Console"**
2. 重现问题操作
3. 复制相关错误信息

### 提交入口

[👉 提交 Issue](https://github.com/steven-jianhao-li/zotero-AI-Butler/issues/new/choose)

---

## 常见操作提示

### 如何更新插件

1. 下载最新版 `.xpi` 文件
2. 打开 Zotero → **"工具"** → **"插件"**
3. 点击齿轮图标 → **"从文件安装插件"**
4. 选择新下载的 `.xpi` 文件
5. 重启 Zotero

### 如何卸载插件

1. 打开 Zotero → **"工具"** → **"插件"**
2. 找到 **AI 管家**，点击右侧三个点
3. 选择 **"移除"**
4. 重启 Zotero
