第二十七節 故障排查與常見問題
27.1 啟動相關
- 應用無法啟動：先看記錄檔（設定 → 資料 → 開啟記錄檔目錄；或在解除安裝並重裝後再次嘗試）。
- 應用啟動後白屏：通常是系統自帶網頁視圖元件版本過舊，參考第二節系統要求升級。
- Linux 安裝套件黑屏：Linux 的 DEB 安裝套件現在會自動適配系統 WebKit —— 系統已裝有 WebKit 4.1（如 Kali / Debian / Ubuntu）時優先用系統自帶的元件與硬體加速，不再強制軟體渲染（此前在 Kali 等系統上會黑屏）；沒裝時（如銀河麒麟 V11、離線環境）自動改用包內自帶的元件並啟用相容渲染，開箱即用。
- Windows 開啟專案提示 BitLocker 已鎖定 / 磁碟機尚未就緒：專案所在盤被 BitLocker 鎖定時，點一下「BitLocker 已鎖定」即可調起系統解除鎖定對話框，解除鎖定後自動開啟；「磁碟機尚未就緒」請先檢查該盤（如外接盤是否已連線）再重試。
27.2 登入相關
- SSO 瀏覽器回跳後桌面端沒有反應：通常是瀏覽器代理 / VPN 攔截了本機回呼連接埠，關閉代理後重試。
- 登入後沒有可用模型：設定 → 模型 → 參數設定 中點「重新整理」；或重新登入。
27.3 會話相關
- 會話突然沒有回應：點擊 停止 按鈕，再發新訊息即可復原。
- 會話歷史似乎被截斷：可能觸發了歷史折疊；點擊折疊摘要展開即可看到原文。
- 錯誤："服務未就緒"：等待 30 秒；持續未復原請開啟 設定 → Hooks → 錯誤抽屜 檢視具體原因。
27.4 工具相關
- 工具呼叫一直在轉圈：通常是背景執行任務被模型調度但未拉取輸出；點開任務卡片檢視實時記錄檔。
- 某工具被拒絕：檢查智慧體管理器 →「配置工具」中該工具在當前模式下的權限設定。
- 外部服務連不上：檢查接入地址與憑證；檢視錯誤抽屜裡伺服器端原始傳回。
27.5 安全分析相關
- 樣本掃描傳回空結果：預設安裝可能未包含完整規則集，請聯絡內部分發渠道獲取完整版本。
- 反編譯耗時長：反編譯涉及模型呼叫，復雜樣本可能耗時數十秒甚至更久；可以讓助手把任務轉背景。
27.6 隨行通訊相關
- 微信掃碼後桌面端沒反應：通訊通道初始化最長 30 秒，再次重新整理QR Code重試。
- 綁定碼失敗：10 分鐘過期；重新生成。
- 簽核卡片在微信裡沒出現：檢查通道是否還線上（設定中可看連線狀態）。
27.7 性能相關
- CPU 佔用高：若你啟用了多個背景任務，注意並行上限；可在 設定 → Hooks 中檢視在跑任務清單。
- 磁碟佔用大：通常是會話歷史或樣本目錄大；設定 → 資料 → 資料目錄 中可看到具體大小，按需歸檔舊會話。
27.7.1 模型呼叫錯誤的精準提示
伺服器端傳回的各類錯誤現在能精準歸類，提示直接告訴你該怎麼辦，不再一律給籠統或誤導性的訊息：
| HTTP | 含義 | 提示 |
|---|---|---|
| 402 | 點數不足 | 「點數不足，前往購券」（購券口徑；與帳號用量展示、伺服器端計費一致，不再用「儲值 / 重設 / 餘額」等不一致表述；不再當成可重試錯誤反復重試） |
| 429 | 方案請求速率達到上限 / 週期額度用盡 | 嚴格依服務端告知時間重試，不提前，每輪累計等待有上限；提示區分每分鐘請求上限與週期額度，並顯示服務端回傳的週期、用量資訊 |
| 401 / 403 | 驗證失敗 / 需要登入 | 「重新登入或重發 key」（不再讓你去查配置） |
| — | 輸入超出 token 上限 | 歸類為「上下文過長」並如實提示 |
| 503 | 當前模型暫無可用通道 | 「稍後重試或切換模型」 |
| 502 / 529 / overloaded | 上游服務例外 / 繁忙 | 繁忙時顯示等待原因與倒數，可換模型或停止等待；驗證或帳戶餘額、額度不足單獨說明，不作為暫時繁忙反覆重試 |
| 404 | 端點不存在 | 單獨分類為 endpoint_not_found_error；提示「檢查 Provider Base URL」（與"API JSON 傳回的 404 模型不存在"分流） |
未設定模型發送不再卡住：刪除了正在使用的服務提供方後直接發送，過去會卡住；現改為在訊息流內行內確認，引導你切換到可用模型再發。啟動失敗時也會復位執行狀態，不再一直停在「執行中」。
27.7.2 macOS App Translocation 升級失敗
如果你沒把應用拖進 應用程式，直接從「下載」或「桌面」雙擊執行，點檢查更新會被 macOS 的 App Translocation 機制鎖住（應用被放進只讀臨時鏡像執行）。本版已識別這種「只讀位置」並快速失敗給出明確引導：
「請結束應用 → 把它拖進『應用程式』資料夾 → 重新開啟 → 再檢查更新」
其它只讀卷 / 受管目錄等寫盤失敗也統一兜底成同樣的友好提示。
27.7.2.5 Windows 背景程序穩定性
Windows 上的背景服務（zWorkspace / zMCP）做了系統性根治：
- 程序存活探測改用系統級句柄等待，不再把活着的子程序誤判為已結束（mac / Linux 行為不變）。修了"每次重開工作區都啟動一個、舊的變成孤兒程序"。
- GUI 程式下子程序 stderr 採集修正，啟動失敗診斷報告裡的「原始錯誤」復原有內容，根因判斷更準。
- MCP 配置讀寫不再丟欄位：之前在「配置工具」面板裡增刪 / 啟停某個 MCP 後端時，儲存可能意外把其它 stdio 後端的啟動命令抹掉，導致下次 zMCP 因「缺命令」整個掛掉。
- 單後端故障不再拖垮整體：某個後端結構錯誤 / 連不上 / 被停用時，zMCP 仍能起，壞的那個跳過並警示，其餘照常可用。
- 後端連線非同步化 + 有界重試：電腦重新啟動 / 網路未就緒時，慢 / 不可達後端不再阻塞整個閘道啟動；後端在背景並行探活、有界次數重試，網路好了自動補連上。修了「重新啟動後某個遠端或區域網路後端連不上就把整個工具閘道拖垮、工具全用不了」。
- 應用結束兜底：用 OS 級程序組綁定，App 當機 / 強殺 / 升級時連帶清理整棵程序樹；子程序側改用更可靠的父程序結束監聽，不再殘留孤兒程序。
- zAgent 當機記錄檔完整保留：背景對話程序（zAgent）意外當機時捕獲原生例外並把當機前的 stderr 完整保留，不再悄無聲息結束（如「結束碼 2」這類難查的情況）。記錄檔齊了，疑難問題更快定位。寫入人設或向子代理餵送資料遇到管道中斷（broken pipe）時，也會上報 zAgent 的真實結束原因，而不是籠統的症狀文案。
27.7.2.6 試用 / 授權過期鎖介面可直接結束
內測（Alpha）版本有效期 45 天（自該版本發佈起算，啟動時與此後每小時檢查），過期後彈出全螢幕鎖定介面，需要升級到新版才能繼續使用：已登入且有用量時自動檢查更新、下載並倒數計時重新啟動；未登入時給出「前往登入」；沒有可用用量時給出「購買點券」「升級 · 訂閱套餐」。
試用過期 / 授權失效的全螢幕鎖定介面底部常駐「結束應用」按鈕 — 此前點關閉只是隱藏到系統匣（等於沒結束），現在任何狀態都能幹淨結束程序。介面裡的官網 / 主頁鏈接為 avlcode.cn。
27.7.3 背景工作區服務啟動失敗自動診斷
背景工作區服務（zMCP）啟動失敗時，AVL Code 會在本機自動採集診斷訊息（自連連接埠對比、程序存活探測等），直接在錯誤抽屜裡給出根因結論 + 建議動作，無需任何手動操作。
- 同時落一份診斷報告文件（最多保留最近 20 份）。
- 「未找到 zWorkspace / zAgent 二進位」根因上浮：若啟動時定位不到內置的 zWorkspace / zAgent 元件，不再只提示「未找到二進位」，而是把嵌入元件釋放失敗的真實根因一並上報，並附按平台區分的排查建議。（相關的：內置元件解壓縮上限由 64 MiB 提升到 256 MiB，修正部分 Intel 機型因元件體積增長被安全護欄誤攔、釋放失敗導致啟動失敗的問題。）
- 全程零操作、不外發資料。
- 這份診斷報告可一鍵作為「意見回饋」的附件帶給我們，加速排查。
27.7.4 線上文件入口
隨時需要查文件：
- 側邊欄「幫助」按鈕：一鍵用系統預設瀏覽器開啟 avlcode.cn/docs.html。
- macOS 幫助選單 → 線上文件：同一目標地址，緊跟在「命令清單」後面。
27.8 記錄檔
應用記錄檔位置可在 設定 → 資料 → 開啟記錄檔目錄 一鍵存取，崩潰堆疊也會同步出現在錯誤抽屜裡，無需開啟終端機。