常见问题与排错

模型无法连接

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 和受支持的文本/图片文件；不支持的文件会显示为不可编辑。
• 切换工作区不会移动旧文件，可从历史工作区切回或在系统文件管理器中迁移。

仍未解决

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