legacy-bridge

把舊工具包成 AI agent 可操作的介面，包含四層 backend（L0–L3）、capability 查詢、MCP 2026-07-28 server，以及 JSON CLI。

Agent ──MCP (2026-07-28) / JSON CLI──▶ Capability API + Action API
                                          │
                                        Router  (依 probe 與執行統計選層、驗證、fallback、降級)
                                          │
              ┌──────────────┬────────────┼─────────────┬──────────────┐
              L0 native      L1 script    L2 UIA        L3 vision
              INI/檔案/DB/DLL CLI/COM      pywinauto     截圖+SoM+OCR+輸入

目錄

Related MCP server: WinScript

安裝與啟動

pip install -e ".[dev]"            # 核心 + 測試
pip install -e ".[windows]"        # Windows 實機：pywinauto / pywin32 / mss / pyautogui / opencv / rapidocr

# MCP（stdio，本機 agent）
lb-mcp --manifest manifests/legacy_flasher.yaml
# MCP（Streamable HTTP，遠端 agent）
lb-mcp --manifest manifests/legacy_flasher.yaml --transport streamable-http --port 8765

# CLI
lb --manifest manifests/legacy_flasher.yaml caps
lb --manifest manifests/legacy_flasher.yaml run set_baudrate value=115200
lb --manifest manifests/legacy_flasher.yaml run flash_firmware path=C:/fw.bin --confirm
lb --manifest manifests/legacy_flasher.yaml ui shot --out s.png   # 附 SoM 標號

Claude Code / Claude Desktop 的 MCP 設定範例放在 examples/mcp.json。

Windows 注意事項（工程判斷）： server 必須跑在使用者已登入的互動桌面，不能包成 Windows Service，因為 session 0 碰不到 GUI，L2 和 L3 都會失效。

Capability 查詢介面

支援狀態分成這幾種：ok、degraded（連續失敗 ≥2 次或 confidence 低）、needs_restart（例如 GUI 開著時寫 INI）、needs_state、unsupported、probe_failed。

畫面狀態的限制規則：

• 狀態符合 manifest 宣告：四層都可以用。

• GUI 沒開（NotRunning）：只用 L0/L1。

• GUI 開著但在其他狀態（例如燒錄中）：一律不執行，避免干擾進行中的操作。

MCP 2026-07-28 對應（已對照官方 changelog 與 SDK 原始碼）

Manifest 支援的 impl

• L0：ini_read ini_write file_tail sqlite_query ctypes_call

• L1：cli（支援 progress_re、ok_re、timeout、取消）com_call

• L2：uia_value uia_select uia_text uia_click uia_set_text uia_sequence

• L3：ocr_region vision_select vision_sequence（找目標的順序：template → OCR → VLM；都找不到時請 agent 自己用 screenshot 加 click）

要接你自己的工具，複製一份 manifest 改寫即可，不需要改程式。

Windows 實機驗證：Audacity 3.7.9（examples/audacity/）

完整的驗證矩陣與數據見 docs/VERIFICATION.md。

測試環境為 Windows 11、繁中系統、Python 3.12、mcp 2.2.0、pywinauto 0.6.9、rapidocr 1.4.4。MCP 走 stdio，協定版本 2026-07-28。

實機上發現、並已修正到程式裡的問題：

1. Python 3.12 的 os.path.exists(r"\\.\pipe\X") 會真的打開 pipe，讓 Audacity 的 pipe 卡在半連線狀態。現在 L1 的 probe 只列出 \\.\pipe\ 目錄確認 pipe 存在，不會打開它；連線改為每個行程只建立一條並持續使用。

2. GUI 開著時寫 cfg 會被覆蓋：wx 程式關閉時會把設定寫回檔案。所以 needs_restart 的正確做法是先關閉程式、再寫入、再重新啟動。

3. tasklist 在中文系統輸出 cp950，改成用 oem 解碼。

4. Win32 選單不在 UIA 樹裡，而且系統選單列的名稱會依系統語言變成「系統」「應用程式」。L2 改用 win32 backend 送 WM_COMMAND 執行 menu_select，找不到才退回用點擊。

5. wx 的 Edit 不接受 UIA 的 ValuePattern，set_field 失敗時改用鍵盤輸入。

6. 對話框在 UIA 裡是巢狀或看不到的，改用 win32 列舉該行程的所有頂層視窗。

7. 各層語意必須一致：原本 L2/L3 的 Tone 是寫進目前選取範圍，L1 則是新增音軌。以 increases_by 驗證就抓出這個差異，後來 L2/L3 都補上新增音軌的步驟。

8. **匯出只有 44 bytes 的 WAV（只有檔頭）**被 postcondition 攔下來，沒有被當成成功。

9. L3 的限制：視窗被遮住時截到的是別的程式；OCR 會把整條選單列合併成一個文字框，對 L3 選單列的 OCR 也不穩定。已改為操作前先把視窗帶到前景、在合併的文字框內依字元位置推算座標，並優先使用錄好的 template（templates/），OCR 退為備援。

10. UI 操作失敗時會跑 cleanup（例如按 Cancel、按 Esc），避免殘留的 modal 對話框卡住後面所有動作。router 也會在狀態是 Dialog 時拒絕執行需要 MainWindow 的動作。

驗證狀態

• Windows 實機（Audacity，見上一節）： L0、L1、L2、L3、MCP stdio、MRTR、首次啟動對話框自動處理都實際跑過。

• 已測試（Linux 與 Windows，19 個 pytest 全過）： L0/L1 對 demo 工具實際執行；L2/L3 用 sim；MCP 走 stdio JSON-RPC 用 mcp 2.2.0 的 client 端對端測試，涵蓋協定版本 2026-07-28、server/discover 宣告 Tasks extension、MRTR 確認的接受與拒絕、Tasks 的 input_required 往返、沒有 Tasks 時的同步執行加 progress。Streamable HTTP 手動 smoke test 通過。

• 未測試： COM（com_call）、ctypes_call，以及在實機上走 Tasks extension（Audacity 的 manifest 沒有長時間動作；Tasks 在 Linux 上已做過端對端測試）。

已知限制

• MCPServer 只能為每個 method 設一種 cache hint，所以 resources/read 一律 ttl 0，manifest resource 沒辦法單獨設長 TTL。

• Tasks 的 notifications/tasks 推播沒有實作，目前只支援輪詢（規格的預設方式）。

• 沒有 Tasks 的同步路徑無法在執行中途提問，遇到會安全地拒絕並回報。

• SoM 候選框目前是 UIA、OCR、輪廓的簡單合併；不同工具可能需要調參數，或錄 template。

授權

MIT License，Copyright (c) 2026 Ming-Chih Lung (Taiwan, Tainan)。全文見 LICENSE。