常见问题与排错

模型无法连接

1. Base URL 通常只填写到版本号，例如 https://api.openai.com/v1，不要附加 /chat/completions。
2. 检查 API Key、模型名称与模型类型。
3. 在模型配置中运行连接检测。
4. 本地 Ollama 或 LM Studio 必须正在运行，并允许 NoteGen 所在设备访问。
5. 如果使用代理，检查供应商级代理是“继承、直连”还是“自定义”，并确认全局代理地址有效。
6. 兼容旧接口时，可将 Token 限制参数从 max_completion_tokens 改为 max_tokens。

同步失败或发生冲突

• 先确认当前平台显示“已连接”，并检查 Token 权限、仓库/存储桶/路径前缀。
• GitHub 已有仓库通常只需 Contents 读写；由 NoteGen 创建仓库还需要 Administration 读写。
• GitLab 使用 REST API，需要 api 权限；Gitea 自建实例需填写正确地址。
• 冲突时可合并两边新增内容、用远程覆盖本机，或用本机覆盖远程。后两种操作可能丢失一侧未同步修改。
• 首次在新设备开启“记录与配置自动同步”时，先确认应上传本机还是拉取远程。
• 工作区路径等设备特定配置默认不会跨设备同步。

MCP 无法启动

• 移动端仅支持 HTTP MCP；stdio 本地命令仅支持桌面端。
• 在 MCP 设置中检查 Node.js、Python、uv、npx 等运行时。
• 命令与参数应分开填写；环境变量和请求头必须是有效 JSON。
• 先使用“测试连接”，再在对话工具栏选择服务器。
• 不要从不可信来源导入会执行本地命令的配置。

OCR 或图片识别失败

• OCR 需要对应语言包；首次使用可能需要下载。
• 检查语言代码，例如简体中文与英文可使用 chi_sim,eng。
• 移动端和 macOS 可能使用系统原生 OCR，其他环境可能使用 Tesseract。
• VLM 需要可用的视觉/对话模型和网络连接；复杂布局适合 VLM，纯文本适合 OCR。

录音或朗读没有声音

• 检查系统麦克风权限和输入设备。
• 录音转写需要 STT 模型；内置免费服务不可用时可配置自己的模型。
• 朗读优先选择“自动”；系统语音不可用时再配置 TTS 模型。
• 上传音频失败时，确认格式受支持且文件没有损坏。

工作区或文件未显示

• 更改工作区后重启应用，使所有组件重新加载路径。
• 确认应用拥有目录读写权限。
• NoteGen 主要管理 Markdown 和受支持的文本/图片文件；不支持的文件会显示为不可编辑。
• 切换工作区不会移动旧文件，可从历史工作区切回或在系统文件管理器中迁移。

网页剪藏无法连接

• 仅桌面端可以接收浏览器剪藏；确认 NoteGen 正在运行，并已在记录设置中启用网页剪藏。
• 扩展默认连接 127.0.0.1:37421。安全软件、浏览器策略或其他程序占用端口时可能失败。
• 修改开关后刷新目标网页并重启扩展；浏览器内部页面和扩展商店页面不允许注入选区助手。
• 队列达到 100 条或 50 MiB 时，先保持 NoteGen 运行并等待积压发送完成。

网络搜索没有结果

• 在网络搜索设置中测试第三方 Key，并检查账户额度、代理和地区限制。
• 确认当前模型启用了网络搜索或工具调用，且对话工具栏中的网络搜索开关已打开。
• 原生搜索不可用时检查第三方服务顺序；第三方不可用时确认基础搜索未关闭。
• 结果受网站登录、反爬和网络环境影响，关键结论应打开原始来源核对。

画布无法导入、生成或同步

• 无损导入请使用 NoteGen 画布 JSON；Mermaid 只支持 flowchart/graph 中可映射的节点和连线。
• AI 图表需要可用聊天模型和有效数据；中断后可编辑图表请求并重试。
• PNG/SVG 导出异常时先缩小画布范围、适应视图，并检查远程图片是否可访问。
• 同步失败时不要重复删除并重建画布，先保留本地数据并检查记录与设置同步队列。

导入文档失败

• 加密、损坏或超过资源限制的文档无法转换；尝试解除密码、重新导出或分成较小文件。
• 扫描 PDF 没有文本层，应先 OCR；复杂表格、公式和嵌入对象需要人工检查。
• Notion ZIP 应直接使用 Markdown/CSV 导出包，不要先改变包内目录。
• 导入前确认工作区可写，并处理目标目录中的同名文件。

自托管同步无法连接

• 检查服务端 /health/ready、HTTPS 证书和 WebSocket 反向代理配置。
• 确认客户端与服务端版本兼容，设备时间正确，并重新登录。
• 不要丢失恢复密钥；重置设备或账户前先确认其他设备和服务端备份可用。
• 出现资料库或工作区映射错误时关闭自动同步，不要继续覆盖，先导出本地 ZIP。

更新或启动失败

• 确认下载包与 CPU/平台匹配，并从官网或 GitHub Releases 重新下载。
• 更新前关闭仍在运行的 NoteGen 进程；安全软件可能锁定安装文件。
• 新版无法启动时保留应用数据目录和工作区，不要先执行清理，提交脱敏诊断信息后再决定降级。
• 降级不能保证兼容新版数据库，优先恢复由兼容版本创建的 ZIP。

仍未解决

提交 Issue 时，请提供 NoteGen 版本、系统版本、复现步骤、预期结果和实际结果。公开日志或截图前请移除 API Key、Token、私人路径和笔记内容。