故障排查

遇到问题时，建议先使用 30 秒的短音频试录进行诊断，切勿在正式重要会议开始时临时排查。每次在 macOS 系统设置中修改权限或安装新的 CLI 工具后，请彻底重启 Kapinote 以使变更生效。

1. 麦克风无法收音（缺少我的声音）

1. 打开 系统设置 → 隐私与安全性 → 麦克风，确认 Kapinote 处于勾选开启状态。
2. 若提示权限变更，请根据引导退出并重新打开 Kapinote。
3. 检查系统状态栏或控制中心，确认默认输入麦克风没有被意外静音。
4. 关闭可能独占音频硬件的其他录音软件或 DAW 工具后重试。

2. 缺少远端参会人员声音（系统音频无反应）

录制 Zoom、Teams、腾讯会议、飞书等软件中的对方声音与共享音频，必须依赖系统音频内录权限：

1. 打开 系统设置 → 隐私与安全性 → 屏幕与系统音频录制，勾选并允许 Kapinote。
2. 彻底重启 Kapinote。
3. 在会议软件或浏览器中播放声音，观察 Kapinote 录音界面的系统音频电平波动。
4. 权限异常重置： 若已勾选但仍无声，先在系统设置中关闭该权限开关，再重新勾选并重启应用。

3. Apple Speech 无法使用或无转录文本

• 检查你的 macOS 系统版本与语言资源包是否支持当前选中的语言。
• 确认已在 系统设置 → 隐私与安全性 → 语音识别 中允许 Kapinote。
• 首次使用对应语言时，macOS 需要在后台下载 Apple 官方语言模型包，请确保设备连网并稍作等待。
• 如系统组件持续异常，建议切换至 Qwen3-ASR 本地模型 或云端语音服务。

4. Qwen3-ASR 下载失败或转录延迟过高

• 下载中断： 确保 Mac 处于稳定网络环境且有 2 GB 以上可用磁盘空间，下载完成校验前请勿退出应用。
• 运行卡顿与掉帧： 端侧实时转录需要调用 Apple 芯片算力；若转录落后于语速，建议关闭后台高负载应用（如大型游戏、视频渲染或密集编译任务）。

5. 云端转录 API 报错或失败

• 密钥格式： 重新复制粘贴 API Key，确保首尾无空格、换行或多余双引号。
• 账号配额： 登录服务商后台确认 API Key 具备转录权限且账号有可用额度。
• 网关地址： 除非使用企业私有网关，否则请保留 Kapinote 预置的默认 Base URL。详见 云端转录服务配置。
• 企业网络策略： 部分公司网络或 VPN 可能会拦截长连接 WebSocket（wss://），可尝试临时切换为个人热点验证。

6. AI 服务验证失败或无法生成总结

• 模型标识符： 核对输入的 Model 字符串是否与服务商官方文档完全一致（注意大小写与版本后缀）。
• Azure 部署名： Azure OpenAI 必须在 Model 字段填入你的自定义 Deployment Name。
• AWS Bedrock 区域： Base URL 需填入已开通模型权限的 AWS 区域（如 us-east-1）。
• 本地 Ollama： 确保 Ollama 应用已启动且菜单栏图标可见；终端执行 ollama run 模型名称 应能正常回答。运行 ollama list，将显示的完整模型名称原样复制到 Kapinote，并保持 Base URL 为 http://localhost:11434。详见 Ollama 完整配置与故障排查。
• 转录资产保障： 若语音转录已成功但 AI 总结报错，请放心保留该会议记录；修复 AI 服务配置后随时可以重新一键生成笔记。

7. 找不到 CLI 命令行工具

1. 先在 macOS 终端中直接运行该命令（如 gemini、claude、copilot、codex），并在终端中完成交互式登录。
2. 若终端可用但 Kapinote 报错提示找不到可执行文件，请彻底关闭并重启 Kapinote，使其重新加载系统的 $PATH 环境变量。
3. 初次配置时，建议将 Model 字段保持留空以使用该 CLI 工具的默认模型。

8. 搜索或对话未能匹配到会议细节

• 确认该场会议已彻底结束并完成转录索引构建。
• 在全局对话中，请务必使用 @ 显式关联对应的目标会议；未被纳入上下文勾选的会议不会被 AI 读取。

若以上方法仍未能解决问题，请生成一份保护隐私的 诊断报告，在求助时提供操作步骤、发生时间与可见错误信息。