疑難排解
以精確 provider/model 和任務設定，在可捨棄筆記重現。核對進度與輸出路徑，分開認證、生成、解析和檔案寫入錯誤；連線成功不驗證整條流程。
概覽
記錄 Notemd、Obsidian、作業系統、動作、協定、模型與最小重現。取消未收斂前勿啟動下一任務；確認歸屬前保留輸出和復原檔。
診斷機制
連線測試
在 provider 設定執行 測試連線。部分預設先測模型清單且可不聊天即成功，其他執行短聊天。再以小型實際任務核驗模型與輸出契約。
進度與開發者診斷
進度介面報告狀態、錯誤和位置，API 活動區分等待、完成或失敗。只在需要時啟用 API 錯誤調試。開發者 provider 診斷使用較長請求且可能消耗配額，適合短測成功而正式任務失敗時有意使用。
診斷可能包含筆記、部分模型回應、端點或憑證。分享前在本地審核並去識別化；已遮蔽金鑰的 profile 仍需檢查元資料。
常見錯誤
API Key 無效或缺失
401 時確認金鑰屬於所選 provider／端點且無多餘空白；403 時檢查帳號／專案限制、模型授權和計費。重試無法修復無效憑證。
網路／連線問題
核對 Obsidian 裝置到端點的主機、連接埠、協定和路由。本地服務需正在執行且模型可用，localhost 不代表另一台電腦。選匹配預設；執行時自動選擇回退，不存在使用者傳輸模式開關。
限流（429）
降低批次並行，核對請求／token 配額及其他共用金鑰客戶端。重試能處理部分暫時錯誤，不保證配額失敗皆可恢復。
找不到模型
支援時取得清單，否則填已知可用 model／deployment，檢查 API version 和區域。預設值可能已過時，不證明上游仍可用。Azure 需 deployment 名，Ark 可能要求 endpoint ID。
沒有連結／概念
檢查實際處理後檔、源文是否有用、模型格式是否正確，以及非空概念目錄是否啟用。獨立擷取預設僅標題、無來源連結。自訂提示詞移除標記時，以內置提示詞作對照。
輸出缺失或位置不符
按報告路徑查找：連結預設 _processed.md，翻譯 _<language>.md，批次標題生成報告 complete 目錄。自訂翻譯目錄建立失敗可回退源目錄，重跑前檢查碰撞與權限。
取消後留下檔案
取消在支援處停止後續工作，已完成寫入不自動回復，接受中的遠端請求／寫入可能完成。刪除或整批重跑前核對逐檔結果及復原衝突。
圖表或原生匯出失敗
各類型依序產生，一種失敗不阻斷其他類型；取消會停止後續類型並保留已完成檔案。匯出失敗可從預覽或歷史重試，無須再次請求模型；產生階段失敗仍須重新產生該類型。舊版 v1/v2 復原記錄繼續可讀。
圖形 HTML 包含可縮放的圖形；結構化摘要 HTML 顯示文字、結構與引文。可編輯 HTML/SVG 是渲染器名稱，不代表網頁內編輯器；編輯請使用原生原始檔。PPTX、MP4 等簡報匯出保留獨立設定與相依元件。 圖表使用手冊.
回報問題
- 用短合成筆記和專用目錄重現。
- 記錄版本、動作、模型、必要設定、預期與實際結果。
- 附去識別化進度、錯誤及最小產物，移除機密內容和不必要端點細節。
- 說明單檔及預設提示詞下是否重現。
- 提交 GitHub Issues。
單張截圖通常不能證明格式或取消問題，盡可能提供源檔／輸出對或最小步驟。
延伸閱讀
- Provider 設定：協定與測試。
- 批次處理：範圍與部分完成。
- 自訂提示詞：契約。
- 設定：預設及目標。