Troubleshooting

Troubleshooting：疑難排解

先判斷問題是在「程式啟動」、「UDP telemetry 收不到」、「資料有到但 UI/HUD 不更新」、「錄製/分析」、「MCP 連線」或「效能」哪一層。每次只改一個設定，並保留 log 與版本資訊，較容易定位原因。

程式無法啟動

• 確認使用的是與作業系統相符的 Full/Lite Installer 或 Portable 版本。
• Portable 版請保留 EXE、sidecar 與相關資料夾的相對位置；不要只複製主 EXE。
• 若 Windows SmartScreen 或防毒軟體攔截，先確認檔案來自官方 GitHub Release，再依組織政策處理解除封鎖。
• 若視窗出現後立即消失，保留 logs/、版本號與 Windows Event Viewer 記錄，不要先刪除資料目錄。
• 更新失敗時，先重新啟動程式並從 GitHub Releases 下載對應 Full/Lite 版本；不要混用兩種 manifest 或手動替換 updater public key。

沒有 telemetry

依序檢查：

1. 遊戲中的 Data Out 是否啟用。
2. IP 是否為 127.0.0.1。
3. 遊戲 Data Out port 是否與 Settings → Telemetry Port 相同，預設為 8000。
4. 遊戲是否已進入會產生有效行駛資料的狀態，而不是停在主選單。
5. Dashboard 是否顯示 backend ready，而不是只看 HUD 視窗是否開啟。
6. 是否有其他程式占用相同 UDP port。

修改 port 後，必須同時修改遊戲設定與 FH6-HorizonTuner 設定，然後重新啟動資料流。不要為了測試而啟動第二個 telemetry receiver；若需要外部儀表，使用 Settings 的 raw forwarding。

HUD 開啟但畫面沒有資料

• 先確認 Dashboard 能收到資料；Dashboard 也沒有資料時，回到上一節處理 UDP。
• 確認 HUD master switch 已開啟，且選擇的 style 仍存在於 /api/hud/styles。
• 確認 HUD 視窗沒有被放到另一個螢幕、桌面或遊戲的全螢幕模式遮住。
• 自訂 HUD 請確認 hud_overlay/<name>/index.html 位於 EXE 同級，並避開保留名稱。
• 若只有自訂 HUD 失效，先切換到 simple 或 advanced 判斷是否為 package 本身問題。

MCP 無法連線

• FH6-HorizonTuner、backend/sidecar 與 MCP Server 必須都已 ready/enabled。
• 開發模式通常使用 http://127.0.0.1:8001/mcp；Release 版可能因 port 占用而使用 dynamic port。
• 以 Settings MCP card 顯示的 URL 為準，或查看 logs/web_port.txt；不要猜測 Release port。
• Client 設定必須是 Streamable HTTP /mcp，不要另開第二個 MCP server。
• connection refused 通常表示程式未執行、backend 未 ready、MCP 未開啟或 port 已改變。

完整 tool/resource 與安全邊界見 MCP Integration。

Recording、分析與匯出

• Race Recording 必須在行駛前開啟，否則之後不會憑空產生完整的 session 或 lap。
• Dyno Recording 與 Race Recording 是不同資料用途；不要用 dyno 曲線取代賽道 session。
• 賽後分析沒有 lap 時，確認錄製期間有跨過有效的起終點/圈次判定，並檢查 session 是否已保存。
• MoTeC 匯出前先選定 primary lap；若要比較，另外選 compare lap。
• 匯入資料必須符合頁面要求的 CSV 欄位；保留原始檔，以便重做匯入或回報問題。
• 刪除 session 前先備份需要的資料；這是使用者資料操作，不是單純清除畫面。

Tuning 建議不合理或不能套用

• 確認 Step 1 的車輛、驅動形式、胎種、引擎與改裝輸入正確。
• 先完成 Step 2–4，再用 Step 5 的 telemetry diagnosis 驗證；不要把 solver 輸出視為遊戲內已套用的設定。
• Developer Tuning View 的 solver、slider mapping 與 priors 是校準中的輔助資料，不等於已驗證的 production constants。
• Step 5 建議可能因輪胎、路面、季節、輔助與駕駛方式不同而改變；一次只採用少量建議，再回到遊戲測試。
• 若事件 feed 顯示衝突，先查看 active/applied/all filter 與 confidence，再決定是否採用單一建議或 Adopt All Suggestions。

畫面卡頓或更新延遲

• 先分辨是整體 FPS 下降、HUD 繪製成本高，還是 telemetry timestamp 停止更新。
• 關閉不需要的 HUD cards、Live Map、音訊 visualizer 或高頻效果，再比較結果。
• 不要同時讓多個外部工具各自建立 telemetry listener；需要轉發時使用單一 raw forwarding 路徑。
• 避免在遊戲、Dashboard、HUD 與錄製都處於最高負載時做效能判斷。
• 若只有歷史分析很慢，先縮小時間窗口或降低採樣點數；這不代表 live telemetry 一定故障。

回報問題時附上的資料

請提供：

• App 版本、Full/Lite、Installer/Portable 與 Windows 版本。
• 發生問題的頁面、操作順序、車輛/賽事/路面與是否使用自訂 HUD。
• Dashboard 是否有即時資料、Settings 中實際 port、MCP 是否開啟。
• 相關時間範圍的 logs/ 檔案，以及可重現問題的最小步驟。
• 若涉及 capture 或 session，先移除不希望公開的個人資料；不要上傳 token、私密設定或整個資料目錄。

Diagnostic Console 與 Support Bundle

若 UI 提供 Diagnostic Console，可依 DEBUG、INFO、WARNING、ERROR 層級篩選即時 log，並展開相關 traceback。需要回報問題時，可使用 Download Support Bundle 產生本機 ZIP；它只收集有界的 aggregate diagnostics 與最近的已遮罩 log，預期不包含 raw UDP payload、絕對路徑、玩家識別資訊或 credentials，也不會自動上傳。

下載前仍應檢查壓縮檔內容，移除任何不希望分享的資料，並只透過可信任的支援管道提供。Support Bundle 不是完整的資料庫備份，也不包含所有 Session/capture。

English

Troubleshoot by layer: startup, UDP Data Out, Dashboard/HUD rendering, recording and analysis, MCP, or performance. Verify Data Out IP 127.0.0.1, matching telemetry port (default 8000), backend readiness, and the actual Release MCP URL from Settings or logs/web_port.txt. Do not run a second telemetry listener. For tuning issues, treat Developer View solver output as calibration assistance and validate changes in-game.

日本語

問題を「起動」「UDP Data Out」「Dashboard/HUD」「Recording/分析」「MCP」「性能」の層に分けて確認してください。Data Out の IP は 127.0.0.1、telemetry port（既定値 8000）はゲームと一致させます。Release 版の MCP URL は Settings または logs/web_port.txt から取得し、2 つ目の telemetry listener は起動しないでください。Tuning の Developer View 出力は補助的な校正データであり、ゲーム内で検証が必要です。