第二十七節 故障排查與常見問題

27.1 啟動相關

• 應用無法啟動：先看記錄檔（設置 → 資料 → 開啟記錄檔目錄；或在解除安裝並重裝後再次嘗試）。
• 應用啟動後白屏：通常是系統自帶網頁視圖元件版本過舊，參考第二節系統要求升級。

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 模型呼叫錯誤的精準提示

伺服器端傳回的各類錯誤現在能精準歸類，提示直接告訴你該怎麼辦，不再一律給籠統或誤導性的訊息：

未設定模型發送不再卡住：刪除了正在使用的模型供應商後直接發送，過去會卡住；現改為在訊息流內行內確認，引導你切換到可用模型再發。啟動失敗時也會復位執行狀態，不再一直停在「執行中」。

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 試用 / 授權過期鎖介面可直接結束

試用過期 / 授權失效的全螢幕鎖定介面底部常駐「結束應用」按鈕 — 此前點關閉只是隱藏到托盤（等於沒結束），現在任何狀態都能幹淨結束程序。介面裡的官網 / 主頁鏈接為 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 記錄檔

應用記錄檔位置可在 設置 → 資料 → 開啟記錄檔目錄 一鍵存取，崩潰堆疊也會同步出現在錯誤抽屜裡，無需開啟終端機。