Developer Guide

Developer Guide：開發者指南

本頁是給想從 source build、維護功能或建立自訂 HUD 的開發者。v1.6.1（tag commit 2426238830a776717ca23173677adc26f4bae074）已發布 Rust backend / MCP Beta；本 Wiki 對照的 main 為後續 commit ec7d769。PR #443 目前 OPEN、尚未合併或發布，範圍是補強 Rust 原生媒體與功能契約、加入 Rust Agent CLI，並移除剩餘 Python backend runtime。

Repository 導覽

backend-rust/            已於 v1.6.1 發布 Beta；sidecar、telemetry、session、tuning、MCP、設定與匯出
backend/                 既有 Python backend runtime；PR #443 移除 runtime，保留必要資料與選用工具
frontend/                React/Tauri UI、Dashboard、Tuning、HUD、Settings
hud_overlay/             內建 HUD package 與共用 telemetry/media 元件
docs/                    校準、MCP、portable HUD、release 與開發交接文件
frontend/src-tauri/       Tauri shell、sidecar、更新與 Windows release 整合
.github/workflows/        CI、測試、installer/portable 與 updater artifacts
ref/FH6-HorizonTuner.wiki/  GitHub Wiki 的獨立 Git repository

主要 UI 入口分成 Full 與 Lite 兩條產品路徑：Full 提供 Telemetry、Tuning、Car Parameters、HUD Overlay、Settings；Telemetry 內含 Live/Dashboard、Post-Race Analysis 與 Drag Test。Lite 保留 Dashboard、HUD Overlay 與 Settings 的輕量路徑。

資料與功能邊界

• UDP Data Out 是 telemetry 的輸入邊界；backend 解析後供 Dashboard、HUD、recording、analysis 與診斷使用。
• WebSocket 是即時 UI/HUD 更新通道；歷史 session、capture 與 drag data 則走有界 HTTP 查詢。
• SQLite/使用者資料目錄保存設定、race sessions、tuning captures、car parameters 與 drag records。
• Tuning solver 產生建議，不代表已向遊戲寫入設定；實際套用與路測仍在遊戲內完成。
• MCP 是 localhost read-only 對外查詢邊界，不應新增遊戲控制、任意 SQL 或第二個 UDP receiver。
• HUD package 以 /hud/ 內建與 /hud_user/ 使用者覆蓋分層；package 不能依賴 launcher 的固定 style 清單。

本機開發

請先閱讀 Repository 根目錄的 README、.agents/AGENTS.md 與 .agents/rules/workspace.md，再依目前 package manager 與 workflow 使用安裝/測試指令。常用的低風險檢查包括：

# Frontend syntax/type/test checks（依 package scripts 為準）
pnpm --dir frontend install --frozen-lockfile
pnpm --dir frontend run build

# Rust backend contracts
cargo test --locked --manifest-path backend-rust/Cargo.toml
cargo test --locked --manifest-path backend-rust/Cargo.toml --no-default-features

# Markdown whitespace check
git diff --check

Rust backend 與 MCP Beta 已在 v1.6.1 發布。PR #443 補強 Rust 原生媒體與 API/MCP/CLI 功能契約、增加 Rust Agent CLI，並退役 Python backend runtime；Python 留作選用維護與發行工具。該 PR 的 CI 涵蓋前端、Tauri 與打包契約；單一本機命令不代表 release readiness。Windows WASAPI/GSMTC 是 Windows 原生能力。後續主線 PR #426 的 Linux x64 Full no-HUD build 保留調校、遙測與 MCP，不提供 HUD/原生音訊媒體，並停止支援 macOS；這是主線開發狀態，v1.6.1 Release 僅提供 Windows 產物。平台與產物詳情以 repository release 文件為準。

自訂 HUD 開發提示

最小 package 至少需要：

hud_overlay/my-hud/
  index.html
  assets/

建議提供 author.json，並使用既有 shared telemetry contract。不要把 shared、assets、telemetry、common、fonts、css 或 js 當作 style ID。HUD 的細節請依序閱讀 HUD 開發指引、HUD Shared Core、HUD Telemetry Cards 與 HUD 樣式參考；需要逐行對照時再看 source 中的 hud_overlay/HUD_DEVELOPMENT_GUIDE.md。

文件維護原則

• GitHub Wiki 適合 onboarding、操作流程、故障排除與使用者導向的長文；精確的 API/程式契約仍應保留在 source/docs。
• 版本敏感資訊（port、artifact 名稱、工具數量、內建 style）要在更新 main 功能時一起檢查。
• calibration priors、community evidence 與 in-game capture 必須標示信心層級；未驗證資料不可寫成確定的遊戲常數。
• Wiki 頁面使用 GitHub Wiki 原生頁面連結；新增/改名頁面後要同步檢查 _Sidebar.md 與所有反向連結。
• 中文是主要說明語言；English 與日本語摘要至少應保留安裝、核心功能與限制，避免不同語系形成互相矛盾的承諾。
• HUD 文件採「總覽 → 開發指引 → Shared Core / Telemetry Cards → Style Reference」分層；共用契約變更時要同步檢查下游樣式與這四頁。

Wiki 的 Git 工作流

Wiki 是獨立 repository，位於：

ref/FH6-HorizonTuner.wiki

在該資料夾內直接使用既有 Git 方法：

git status
git pull --ff-only origin master
git diff --check
git add Home.md _Sidebar.md _Footer.md *.md
git commit -m "docs: update wiki"
git push origin master

Wiki live site 只呈現其預設分支；本專案目前使用 master。若要批次更新，先確認 dirty worktree 與其他協作者的 ownership，避免覆蓋未提交內容。主 Repo 的 branch、PR 與 Wiki repo 的 commit 是兩套 Git 狀態，請分開回報。

English

Published v1.6.1 (tag commit 2426238830a776717ca23173677adc26f4bae074) includes the Rust backend and MCP Beta; the Wiki's main reference is the later commit ec7d769. PR #443 remains open and unreleased: it hardens Rust native media and feature contracts, adds the Rust Agent CLI, and retires the remaining Python backend runtime. Python remains for optional maintenance and release tools. Later main PR #426 adds Linux x64 Full no-HUD builds with tuning, telemetry, and MCP, and drops macOS support; v1.6.1 release artifacts are Windows-only. The Wiki is a separate Git repository on master.

日本語

公開済み v1.6.1（tag commit 2426238830a776717ca23173677adc26f4bae074）には Rust backend / MCP Beta が含まれます。Wiki が参照する後続の main は ec7d769 です。PR #443 は未マージ・未リリースで、Rust の補強、Rust Agent CLI の追加、残る Python backend runtime の廃止を行います。Python は選択式の保守・リリースツールに残ります。後続 main の PR #426 では Linux x64 Full no-HUD build が tuning、telemetry、MCP を提供し、macOS は非対応となります。v1.6.1 の公開成果物は Windows のみです。Wiki は独立した Git repository の master で管理します。