故障排查
使用准确的 provider、model 和任务配置，在可丢弃笔记上复现。检查进度日志和输出路径，区分认证、生成、解析和写入失败；连接测试成功不能验证整个工作流。
概览
记录 Notemd／Obsidian 版本、操作系统、动作名、provider 协议、模型和最小复现。取消尚未收敛时不要启动新任务。在确定归属前保留既有输出和恢复文件。
诊断机制
连接测试
在 provider 设置运行 测试连接。部分预设仅测试模型列表即可成功，另一些执行短聊天。随后用小型实际任务验证模型与输出契约。
进度与开发者诊断
进度界面报告状态、错误和目标路径，API 活动帮助区分等待、完成与失败。按需开启 API 错误调试。开发者 provider 诊断会执行较长请求并可能消耗配额，适合短测试成功而实际任务失败时有意使用。
诊断响应可能包含笔记、部分模型输出、端点或凭据，分享前在本地审核并脱敏。脱敏 provider profile 仍需检查元数据。
常见错误
API Key 无效或缺失
HTTP 401 时检查密钥是否属于所选 provider／端点及是否含多余空白；403 时检查账户权限、项目限制、模型授权和计费状态。重复重试不能修复凭据。
网络／连接错误
检查 Obsidian 设备到端点的主机、端口、协议和路由。Ollama／LM Studio 需已运行且模型可用。localhost 是运行 Obsidian 的设备，不是另一台电脑。选择正确预设；运行时回退自动选择，不是 UI 传输开关。
限流（429）
降低并发，核对请求／token 配额和共享密钥的其他客户端。重试可恢复部分临时失败，但不保证配额错误最终成功。
找不到模型
支持时获取模型列表，或填写账户已知可用 model／deployment，检查 API version 与区域。预设可能是历史值，不证明上游仍提供模型。Azure OpenAI 需 deployment 名，Ark 可能要求 endpoint ID。
没有链接或概念
检查实际处理后文件、源材料、模型输出格式，以及概念目录是否非空且启用。独立提取默认仅标题、反向链接关闭。若自定义提示词删去标记，恢复内置提示词作对照。
输出缺失或位置异常
读取任务报告的路径。添加链接默认 _processed.md，翻译默认 _<language>.md，批量标题生成报告 complete 目录。自定义翻译目录创建失败可回退源目录。重跑前检查路径碰撞与权限。
取消后仍有文件
取消在支持路径停止后续工作，保留已完成写入，不会自动撤销。已接受的远端请求或写入仍可能完成。删除或重跑整个目录前，检查逐文件结果和恢复／冲突路径。
图表或原生导出失败
各类型顺序生成，一种失败不阻断其余类型；取消会停止后续类型并保留完成文件。导出失败可从预览或历史重试，无须再次请求模型；生成阶段失败仍需重新生成该类型。旧版 v1/v2 恢复记录继续可读。
图形 HTML 包含可缩放的图形；结构化摘要 HTML 展示文字、结构与引文。可编辑 HTML/SVG 是渲染器名称，不代表网页内编辑器；编辑请使用原生源文件。PPTX、MP4 等演示导出保留独立设置与依赖。 图表使用手册.
报告问题
- 用小型合成笔记和专用目录复现。
- 记录准确版本、动作、模型、必要设置、预期与实际结果。
- 附脱敏进度／错误和最小问题产物，移除密钥、私密内容和非必要端点元数据。
- 说明单文件与默认提示词下是否复现。
- 提交 GitHub Issues。
截图通常不足以证明文件格式或取消问题；尽可能提供源文件／输出对或最小操作序列。
后续阅读
- Provider 设置：协议与连接测试。
- 批量处理：范围与部分完成。
- 自定义提示词：输入／输出契约。
- 配置：真实默认值和路径。