🎙️ Lecture 21: 【終極大師專案】Windows 底層鍵盤攔截與執行緒安全 (zhuyin_say)

🎧 錄音室開場：駭入 Windows 的最深處！

• Ray：「各位大導演，我們終於來到實戰工坊的最後一關！今天我們要介紹的專案 『注音說明模式 (zhuyin_say)』，是難度封頂的究極魔王！」
• 小咪：「它聽起來不就是按一個按鍵，然後唸出那個按鍵的注音嗎？這很難嗎？」
• Ray：「唸出注音不難。難的是，這個外掛要求：『當模式開啟時，不管你現在是不是在中文輸入法 (IME) 狀態，不管你按了什麼，這些字都絕對不可以被打到螢幕上』！NVDA 一般的快捷鍵攔截，根本擋不住微軟的新注音輸入法，字照樣會被打出去！」
• Ray：「為了解決這個問題，這個專案直接駭進了 Windows 最底層的作業系統心臟！但也因此引發了可怕的『多執行緒撞車當機』。讓我們一起來看看，大師級的 Prompt 是如何解題的！」

---

🎯 專案解密：zhuyin_say 的底層生死鬥

根據 nv-addon-zhuyin_say_development.md 的開發紀錄，這個專案經歷了四個版本的慘烈演進：

1. 突破防線：接管系統底層鉤子 (winInputHook)

一般的 @scriptHandler.script 攔截，面對微軟輸入法會直接失效。 因此，開發者大膽放棄了常規做法，直接呼叫了 NVDA 內部用來與 Windows 作業系統溝通的 API：winInputHook.setCallbacks。 在自訂的按鍵攔截函式 (patched_keyDown) 裡，只要外掛決定攔截這個按鍵，就直接向作業系統回傳 False。這招「釜底抽薪」，讓 Windows 直接把按鍵丟進垃圾桶，微軟注音輸入法連鍵盤按下的訊號都收不到，達成了 100% 的輸入阻斷！

2. 致命崩潰：C++ 執行緒斷言錯誤

當成功阻斷輸入後，開發者想要讓 NVDA 唸出注音，於是寫了 ui.message("ㄅ")。 結果，NVDA 瞬間當機閃退！ * 崩潰原因：因為 winInputHook 是在 Windows 背景的「底層 C++ 執行緒」裡運作的。而在這個背景執行緒裡，我們居然試圖叫負責畫面的「主 GUI 執行緒」講話。這違反了作業系統的「執行緒安全 (Thread-Safety)」鐵律，導致 C++ 直接報錯崩潰！ * 終極解法：祭出了我們在 L16 學過的安全金律：wx.CallAfter(ui.message, text)。透過 wx.CallAfter，背景執行緒會「寄一封信」給主執行緒，請主執行緒有空的時候唸出注音，完美避開了撞車危機！

3. 點字閱讀優化：Tab 鍵縮排

開發紀錄中還特別提到，為了讓使用「點字顯示器 (Braille Display)」的視障者能更順暢地閱讀 Python 原始碼，專案特地把所有 4 空格的縮排，全部取代成了 Tab 鍵 (\t)。這能節省點字顯示器寶貴的儲存格空間。

---

📝 大導演的 Vibe Coding 派工單 (Prompt)

要請 AI 寫出這麼硬核的外掛，我們不需要會寫 C++，但我們必須在 Prompt 中把「架構層級」拉到最高，並強制下達安全命令！

「你現在是深諳 Windows 底層 API 與 NVDA 核心架構的 C++ / Python 雙棲工程師。 請幫我開發『鍵盤注音學習模式』全域外掛 (zhuyin_say)。

核心架構與極嚴格規範： 1. 【100% 底層阻斷】：一般的 gesture hook 擋不住 IME 輸入法。請直接接管 winInputHook.setCallbacks(keyDown=self.patched_keyDown...)。在 patched_keyDown 中，若模式開啟，必須回傳 False 以在 Windows OS 底層徹底丟棄按鍵事件！ 2. 【跨執行緒防撞金律】：patched_keyDown 是由 C++ 背景執行緒呼叫的。當你需要朗讀注音時，嚴禁直接呼叫 ui.message 或 core.callLater（會引發 wxWidgets 斷言崩潰）。你必須且只能使用 wx.CallAfter(ui.message, 注音字串) 將發聲任務安全遞交給主執行緒！ 3. 【點字友善排版】：為了方便視障者閱讀你的原始碼，請捨棄 Python 常見的 4 空格縮排，全面改用 Tab 鍵 (\t) 進行縮排。

請直接給我完整且保證不當機的 zhuyinExplanation.py 原始碼。」

---

🎓 學習總結：造物主的境界

當你讀懂了 zhuyin_say 的開發邏輯，你會發現：程式碼只是語言，真正的價值在於「解決問題的戰略架構」！ 我們透過 Vibe Coding，指揮 AI 繞過表層的限制，直接駭入 Windows 最底層，並用 wx.CallAfter 化解了致命的系統崩潰。這，就是 Vibe Coding 大導演的最高境界！

---

🔍 零基礎讀碼指南：白話拆解 zhuyinExplanation.py 原始碼

如果你從未寫過代碼，看到 zhuyinExplanation.py 裡兩百多行的英文字母，可能會覺得像天書一樣。別慌！我們用「工廠流水線」和「信件收發室」的比喻，帶你一步步拆解它的物理構造。

📦 1. 備料與工具箱引進 (第 3 至 16 行：import)

在程式的最開頭，有一堆以 import 開頭的句子。這幕就像是在工廠開工前，從工具庫裡借出工具：

• import keyboardHandler：借出 NVDA 內部的鍵盤管理員。
• import winInputHook：借出作業系統底層的「鍵盤攔截鉤子」。
• import wx：借出介面庫的「信件收發室管理員」（處理執行緒安全）。

📖 2. 注音字典對照表 (第 36 至 67 行：ZHUYIN_MAP)

這是一個大括號包起來的區塊，稱為「字典 (Dictionary)」。

• 白話解釋：這就像是一本密碼本。左邊是鍵盤按鍵（如 "q"），右邊是它對應的朗讀音標（如 "ㄆ"）。
• 當外掛抓到按鍵時，就會來這本密碼本裡查表，找出該讀什麼音。

🛡️ 3. 貍貓換太子：極底層攔截 (第 122 至 181 行：patched_keyDown)

這是這個外掛的靈魂函數，像一個嚴格的「海關檢查哨」：

• patched_keyDown：這是當按鍵按下時，Windows 作業系統第一時間會通知的地方。
• 按鍵攔截與丟棄 (return False)：在一般的程式中，按鍵按完就放行；但在這裡，如果模式開啟，程式最後會回傳 return False。這代表告訴作業系統：「這個按鍵已經被我沒收了，不要傳給微軟輸入法，也不要打在螢幕上！」這就是為什麼英文字母絕對不會跑出來的祕密。
• 放行快捷鍵 (NVDA+I)：海關必須放行特殊的通行證。如果偵測到是關閉鍵 NVDA+I，它就會呼叫原本的處理器並回傳放行，否則外掛一開啟就再也關不掉了。

✉️ 4. 執行緒安全郵差 (第 168 至 177 行：wx.CallAfter)

這是最專業也最關鍵的一行：wx.CallAfter(ui.message, zhuyin_char)。

• 執行緒當機危機：Windows 的鍵盤攔截器是在「背景執行緒（地下工廠）」運作的，而發聲和畫面是由「主 GUI 執行緒（地上辦公室）」管理的。地下工廠的工人如果直接衝進地上辦公室大吼（直接呼叫 ui.message），就會引發系統衝突而導致 NVDA 崩潰閃退。
• 白話解決方案：wx.CallAfter 就像是「寫一封信放入辦公室信箱」。背景工人把注音符號寫在信上，請郵差送去給主執行緒，主執行緒收到信後在安全的時間代為朗讀。100% 執行緒安全，絕不當機！

---

👉 回課程大綱：學習地圖