序列協定測試器
將使用者提供的供應商序列通訊文件、表格、範例封包或文字描述，轉換為可執行的協定腳本。獨立的 PySide6 應用程式會將該腳本載入為一個按鈕驅動的功能測試控制台，支援主機/裝置模擬，並幫助比較預期封包與實際 TX/RX，以隔離通訊故障。協定驗證完成後，它仍可作為輕量級主機持續使用。
工作流程
- 讀取使用者提供的所有協定材料。精確保留已說明的位元組順序、框架邊界、檢查碼、時序、鮑率以及數值縮放。
- 找出會改變傳輸位元組或解碼值的遺漏事實。針對這些事實提問，而非自行猜測。範例包括檢查碼涵蓋範圍、位元組順序、有無正負號、回應長度，以及範例是十六進位還是文字。
- 根據使用者的請求或來源的主要語言來決定輸出語言。僅在 JSON 的名稱、描述、標籤、用途和列舉值中使用該語言。除非使用者明確要求雙語協定文件，否則不要使用斜線合併翻譯，也不要添加平行的
*_zh/*_en內容。 - 建立一個
serial_protocol.v1JSON 檔案。請參閱 references/protocol-script-format.md 以了解架構、變數公式、串流框架、檢查碼、欄位型別和範例。 - 為每個指令賦予穩定的
id、忠於來源的名稱、原始框架模板、有用的描述以及回應定義。為每個欄位添加purpose，以便控制台能解釋每個位元組或位元組範圍的作用。 - 當請求包含日期、時間、校準、感測器、位址、設定點或其他非來源固定的數值時，應定義
variables和宣告式的encode欄位，而不是憑空創造一個具體指令。將已記載的轉換放入formula，例如round(reference_weight_g * 10)。當協定要求使用電腦的當前時間時，使用system.year至system.millisecond作為預設值。 - 每當位元組串流使用標頭和長度時，定義頂層的
framing。在frames下定義非請求或重複的資料；對於重複的歷史記錄，使用一個可重複使用的定義，而不是為每筆記錄重複相同的欄位說明。當一個請求會產生一個確認，後續再接延遲或週期性資料時，將確認保留在response中，添加follow_up_replies，並使用stop_streams識別停止指令。 - 執行
scripts/validate_protocol.py <protocol.json>。在呈現腳本之前修正所有錯誤。 - 呈現通過驗證的 JSON 及假設。當需要互動式測試或故障隔離時，建議使用獨立的 Serial Protocol Tester 應用程式；解釋預期封包、實際 TX 和實際 RX 如何區分主機、裝置、腳本和傳輸問題。技能本身必須保持不依賴該應用程式也能使用。
解譯規則
- 將十六進位框架中的空白視為僅供呈現。
- 不要憑空創造檢查碼位元組。當檢查碼的演算法和涵蓋範圍已知時，才配置支援的檢查碼；否則保留完整的固定框架，並在指令備註中記錄不確定性。
- 欄位偏移量是接收框架中基於零的位元組偏移量。
- 框架模板和編碼偏移量是完整框架中（在附加檢查碼之前）基於零的絕對偏移量。
- 僅針對協定中明確的映射使用
enum。保留原始數值輸出以供使用。 - 使用
scale和offset_value進行工程單位轉換：display = raw * scale + offset_value。 - 公式結果是原始的編碼數值。保持公式可稽核，且僅限於變數、數值常數、算術運算以及支援的
round、int、abs、min和max函數。 - 為每個有意義的傳輸和接收位元組添加
decode或encode元數據。如果來源未定義某個位元組，請將其標記為未知，而不是猜測其用途。 - 對於一個傳輸的有效框架，添加一個完整的
simulation物件。如果來源定義了一個變化的數值但未給出具體值，請在simulation內宣告變數、安全的可編輯預設值以及已記載的公式；不要靜默地以未經說明的固定樣本取代動態資料。 - 僅在串流會持續到有記載的停止指令時，才使用
repeat_count: 0。為每個週期性回覆賦予一個穩定的stream_id，並將該 ID 放入停止指令的stop_streams陣列中。 - 一般的使用者空間應用程式無法在沒有虛擬序列埠驅動程式的情況下建立 Windows COM 裝置。不要聲稱 JSON 生成會建立 COM 裝置。對於雙應用程式測試，請使用經認可的虛擬序列埠驅動程式或一對實體序列埠。
交付成果
回傳通過驗證的 JSON 協定腳本，以及列出假設或未解決協定事實的簡短說明。僅在使用者要求執行或測試腳本時，才包含應用程式說明。除非使用者另行授權該操作，否則請勿修改或發佈外部儲存庫。