FactVerse AI Agent 故障排查

當 AI 客戶端已經接入 FactVerse AI Agent，但工作流程無法按預期完成時，使用本指南。先檢查 endpoint、API key、scope 和來源資料邊界，再分析工作流程邏輯。

快速排查順序

1. 確認客戶端使用了預期 host 和 endpoint。
2. 確認請求發送了 X-API-Key。
3. 在執行時列出工具，並把可見工具與預期工作流程對比。
4. 確認 API key 的 scope 與工具 scope 匹配。
5. 檢查來源資料新鮮度、資產映射、文件可用性和場景版本。
6. 排查寫入動作被阻止前，先檢查審批策略。

連接與認證

現象	可能原因	檢查	修復
閘道返回 403	缺少 API key header	檢查請求 headers	使用 X-API-Key 發送 key
閘道返回 401	key 無效、已撤銷、過期或屬於其他環境	請管理員確認 key 狀態	輪換或重新簽發 key
客戶端連到錯誤路由	endpoint 路徑或 host 錯誤	與 /mcp/base/、/mcp/pdm/ 或已啟用模組 endpoint 對比	更新客戶端 server URL
TLS 或網路失敗	客戶端無法存取客戶 host	從同一網路測試 host	修復網路、代理、DNS 或憑證信任

工具可見性與 scope

現象	可能原因	檢查	修復
預期工具缺失	endpoint 錯誤、模組未啟用或 key 缺少 scope	運行工具發現	使用正確 endpoint 或申請所需 scope
scope 被拒絕	key 沒有所需 scope	對比工具 scope 與 scope 參考	透過管理員更新 key 策略
工具列表為空	endpoint 可達，但模組設定不可用	檢查部署模組啟用狀態	啟用模組或使用受支援 endpoint
寫入工具不可見	key 唯讀或審批策略阻止寫入工具	檢查 base.action.write 和工作流程策略	寫入獲批前把輸出保留為草稿

資料與資產問題

現象	可能原因	檢查	修復
無法解析資產	Platform、Inspector、DFS 和文件中的名稱或 ID 不一致	按站點、區域、設備 ID 和別名檢索	確認後更新資產映射
回答過於空泛	來源資料缺失、過期或範圍過寬	檢查資料時間戳和查詢邊界	收窄邊界或修復資料管線
缺少近期工作記錄	Inspector 或外部工單記錄尚未同步	檢查最近同步時間和來源系統狀態	重新整理連接器後重跑
文件不可用	文件超出租戶、權限或知識 scope	檢查文件權限和租戶歸屬	更新文件存取權限或掛接正確來源

預測性維護問題

現象	可能原因	檢查	修復
健康摘要較弱	訊號歷史過短、稀疏或未映射	複核訊號時長、採樣間隔、單位和缺口	返回資料就緒度報告並修復輸入資料
異常缺少解釋	缺少維護上下文或運行模式	對比異常視窗、工作歷史和模式變化	掛接工單、巡檢備註和運行狀態
告警過多	資產組或閾值設定過寬	複核資產邊界和閾值策略	與維護工程師一起調校
後續動作被阻止	缺少工程師審核或寫入 scope	檢查審批狀態和 base.action.write	將動作保留為草稿

Physical AI 與模擬問題

現象	可能原因	檢查	修復
場景無法用於模擬	缺少場景版本或必要資產元資料	檢查場景版本、資產版本、比例和座標系	先準備場景包再計算
模擬表現較差	碰撞、質量、關節、摩擦或約束元資料不完整	運行 SimReady 就緒度複核	修復元資料並重新檢查
結果無法複用	缺少假設、後端參數或驗證備註	檢查場景包和結果記錄	補充假設、限制和驗證備註
計算請求被阻止	缺少計算 scope 或負責人審批	檢查 base.compute.run 和專案審批	流轉給工程負責人

升級記錄

問題需要產品或實施支援時，保留這份記錄：

欄位	說明
環境	Host、endpoint、租戶或專案標識、部署類型。
請求	使用者任務、時間範圍、資產或場景邊界、客戶端類型。
工具發現	可見工具、缺失的預期工具、key 持有的 scope。
來源狀態	資產映射、資料新鮮度、文件可用性、場景版本、連接器狀態。
錯誤	HTTP 狀態、工具錯誤、驗證訊息或被阻止的審批狀態。
審核負責人	對下一步負責的操作員、維護工程師、工程負責人或管理員。