visionA/local-tool/.autoflow/05-implementation/review/m9-1-bridge-firmware-upgrade-review-round2.md

M9-1 Reviewer Round 2 — bridge.py firmware_upgrade（第 2 輪修改驗證）

審查日期：2026-05-25 範圍：backend 第 2 輪修改驗證、不重審第 1 輪細節 第 1 輪報告：m9-1-bridge-firmware-upgrade-review.md

TL;DR

通過（with 1 Minor + 1 Suggestion）。建議解除 M9-2 阻擋、可啟動。

backend 第 2 輪修改紀律高、所有 Major / Minor 全部正確落地、4 個情境 stage 序列邏輯清晰可讀、ctypes 簽名測試補上、firmware 字串覆蓋從 substring → 顯式 enumeration + forward-compat。第 2 輪僅發現 1 個 Minor regression（test 檔留下 _firmware_upgrade_start_ts 死碼、不影響 prod 但 cleanup 不徹底）+ 1 個 Suggestion。第 1 輪 8 項 issue 修了 8 項、新發現 0 Critical / 0 Major / 1 Minor / 1 Suggestion。s1 / s2 follow-up 評估合理、不影響 M9-2 啟動。

---

1. 第 1 輪 issue 修改驗證（逐項）

#	第 1 輪 Issue	第 2 輪修改位置	驗證結果
M1	_FwError / _FwTimeoutError / _fw_handle_failure 宣告位於 handler 之後、readability + 防禦問題	kneron_bridge.py:1535 / 1545 / 1553 全部移到 handler（1587）之前	✅ 完全到位
M2	needs_loader 控制流隱式	1717-1722：三個顯式 bool（needs_loader / should_run_loader_stage / loader_required_but_missing）+ 註解四情境	✅ 完全到位、M9-2 Go driver 可對照註解
M3	substring match 對 KDP3 forward-compat 脆弱	_fw_classify_legacy 重寫（1463-1508）：legacy_exact set + startswith("KDP1.") + KDP2-9 prefix forward-compat	✅ 完全到位
m1	_FW_ALLOWED_CHIPS 雙重防護	1180 constant + 1201 內部過 + 1204 字元防護	✅ 真的雙重防護、非冗餘
m2	libkplus fallback non-deterministic	1324 sorted() + 1330 WARNING log	✅ 完全到位
m3	double-disconnect risk	_fw_handle_failure 不再 disconnect、success 路徑兩處設 dg=None、finally 用 if dg is not None	✅ Single owner 原則完整
m4	_firmware_upgrade_start_ts 全域變數	prod code 全砍、SIGTERM closure capture	⚠️ prod 完全到位、但 test 檔殘留死碼（標 m5）
s4 (1-4)	4 個 test case	4 個新 test 全補（line 405-487 + 500-568）	✅ 完全到位

第 1 輪 8 項 issue 修了 8 項、其中 7 項完全到位、1 項（m4）prod 完全到位但 test 殘留（標 Minor m5）。

---

2. 第 2 輪新發現（regression risk）

Critical / Major

無。

🟡 Minor

#	軸	檔案:行	問題	建議修法
m5	Correctness / Test hygiene	test_kneron_bridge_firmware.py:616, 632	m4 在 bridge.py 已砍 _firmware_upgrade_start_ts、但 test 仍 bridge._firmware_upgrade_start_ts = 0.0、bridge._firmware_upgrade_start_ts = start_ts。Python 動態 setattr 不會拋錯、但留下死碼掩蓋 m4 修改徹底性	刪除 line 616 + 632 兩行賦值、保留 615 _firmware_upgrade_in_progress = False

💡 Suggestion

#	軸	檔案:行	建議
s5	Test	test_kneron_bridge_firmware.py:680	test_sigterm_handler_unregistered_after_upgrade 第二次呼叫 register 會覆蓋第一次的 _fw_original_sigterm_handler、測試邏輯能過但意圖不清。建議補註解「測試 register 的 idempotence」或拆兩個 test

---

3. 4 個情境 stage 序列驗證（M2 重構後）

情境	預期 stage 序列	實作確認	結果
1. KL520 KDP1 legacy + loader.bin	preparing → loading → flashing → verifying → done	1739-1783 loader stage + 1799-1812 kp_load_firmware_from_file；test test_kl520_kdp1_legacy_full_5_stages（line 214-247）	✅
2. KL520 KDP1 legacy 缺 loader.bin	preparing → error(loader_write_failed)	1730-1736 raise _FwError("loading", "loader_write_failed", ...)；test test_loader_write_failed（line 346-358）	✅
3. KL720 KDP1 legacy 無 loader.bin（warrenchen 模式）	preparing → flashing → verifying → done	1784-1788 elif needs_loader skip loading + 1813-1828 kp_update_kdp_firmware_from_files(scpu, ncpu, True)；test test_kl720_kdp_legacy（line 271-288）	✅
4. 已 KDP2（KL520 / KL720）	preparing → flashing → verifying → done	_fw_classify_legacy KDP2 prefix 命中 return False、走 warrenchen 模式；test test_kl520_already_kdp2_short_circuit（line 249-269）	✅

四情境 stage 序列邏輯與 test 驗證皆完全對齊、M2 重構成功。

---

4. s1 / s2 follow-up 評估

follow-up	留 follow-up 理由	對 M9-2 影響
s1（handler ~300 行抽 helper）	抽 helper 需傳大量 shared state、closure 設計細節多、M2 已讓 main flow 可讀性大幅提升、ROI 不高	❌ 無影響、M9-2 看 bridge 介面而非內部結構
s2（poll loop 用 exponential backoff）	實測 5s 已穩、上界 8s、最多 6 次 poll、CPU 開銷可忽略、純 micro-optimization	❌ 無影響、Go driver 不參與 polling

兩個 follow-up 都不阻擋 M9-2。

---

5. TDD §6.1 對齊度

項目	round 1	round 2
Handler input/output schema	100%	100%
stage enum	100%	100%
reason enum 8 種	7/8	7/8（validate_failed downgrade-only、A 階段不需）
progress event schema	100%	100%
Stage 觸發點	✅	✅ M2 重構後流程更清晰
Timeout 60s/200s	✅	✅
USB stable 5-8s	✅	✅
Graceful shutdown 拒絕	✅ bridge 端	✅ bridge 端
ctypes 走法	✅	✅ + binding 簽名 test
MAGIC 值	✅	✅
防 firmware 字串脆弱	⚠️ substring	✅ 顯式 enumeration + forward-compat

對齊度 98% → 98%（preparing stage 細分 scan/connect sub-message 留 M9-5）；但 M2 + M3 對「未來 KDP3+ device 不會誤觸 loader」這個未來相容性問題顯著改善。

---

6. 既有 6 個 handler 零改動驗證

Handler	round 1 行為	round 2 行為	結果
handle_scan / handle_connect / handle_disconnect / handle_reset / handle_load_model / handle_inference	693-1202	693-1202	✅ 6/6 零改動、無 spillover

第 2 輪修改完全限制在 firmware_upgrade 區段（1205-1983）+ _resolve_firmware_paths_full（1183-1240）+ 1180 _FW_ALLOWED_CHIPS constant。

---

7. 9 個新增 tests 品質評估

Test	對應	品質
test_kl520_legacy_empty_firmware_string	M3/s3	✅ 邊界完整
test_kl520_legacy_usb_boot_strings	M3/s3	✅ subTest 7 變體
test_kl520_legacy_kdp1_variants	M3/s3	✅ KDP1.x / 大小寫
test_kdp3_kdp4_not_legacy	s3	✅ 最關鍵、KDP3-9 forward-compat
test_unknown_firmware_default_not_legacy	M3	✅ 保守 default
test_loading_stage_disconnect_during_op	s4(1)	✅ 覆蓋 1764-1775
test_loading_stage_reconnect_failed	s4(2)	✅ call_count 攔截
test_failure_event_full_extra_fields	s4(3)	✅ 4 必填欄位
test_libkplus_binding_signatures	s4(4)	✅ MockCDLL 設計巧妙

9 個新 test 都覆蓋盲點、命名清楚、docstring 帶 line ref、品質高。

---

8. 是否阻擋 M9-2

否、解除阻擋、可啟動 M9-2。

理由：

1. 第 1 輪 3 Major 全部完全到位、其中 M2 控制流重構對 M9-2 Go driver 開發直接有幫助
2. M3 firmware 字串覆蓋解決未來 KDP3+ device brick 風險、長期穩定性關鍵改善
3. m5 是 test hygiene 問題、不阻擋功能
4. s1 / s2 follow-up 對 M9-2 介面層完全無影響

---

9. 是否需 backend 第 3 輪修改

否。僅 1 Minor + 1 Suggestion、可在 M9-2 期間順手清掉或併入 M9-1 PR 收尾 cleanup commit。

---

10. 結論

• 通過 with Minor：m5 + s5 不阻擋 M9-2
• M9-2 啟動建議：立即派 backend
• m5 + s5 處理：M9-2 期間順手清、不必為此單獨派 backend round 3