🎙️ Lecture 18: 【大師專案】商用級隱私防護網：語音過濾器與 GUI 設定面板 (Speech Filter & Settings)

🎧 錄音室開場：邁向商業級外掛的最後一哩路！

• Ray：「各位大導演，恭喜你們來到實戰工坊的最終關！今天，我們要挑戰做一個可以正式發布、甚至有自己專屬『設定介面（GUI）』的商業級外掛。」
• 小咪：「太酷了！這樣使用者就可以自己在設定選單裡勾選，來開關外掛功能了！但同時要處理底層語音過濾，又要畫視窗畫面，這需求一定超級複雜，我們要怎麼寫 Prompt 呢？」
• Ray：「這就是我們今天要解鎖的終極大絕招：『CO-STAR 提示詞框架』！只要套用這個在科技界最頂級的派工單範本，哪怕是十幾個檔案的複雜大專案，AI 也能一秒聽懂、一次寫對！」

🎯 大師專案目標：密碼防窺靜音網 (Password Mute Guard)

1. 隱私防護：當游標移動到任何網頁或軟體的「密碼輸入框」時，自動封殺所有語音朗讀，徹底防止密碼被旁人聽見。
2. 設定面板：在 NVDA 官方設定選單中，加入一個打勾控制框，讓使用者可以決定「開啟/關閉」這個防窺功能。

🧠 大導演的思維課：複雜專案的 CO-STAR 提示詞架構

當一個專案同時包含「系統級底層攔截」與「GUI 視覺畫面設計」時，你不能再用口語聊天的方式對 AI 許願。你必須使用 CO-STAR 框架，將需求結構化地封裝起來：

• C (Context) 背景脈絡：告訴 AI 開發環境是最新版 NVDA 2026.1。
• O (Objective) 任務目標：說明要做出「密碼靜音過濾」與「原生設定 UI」兩大功能。
• S (Style) 寫作風格：要求代碼風格（例如使用標準類別繼承，而不是手動魔改）。
• T (Tone) 語氣與態度：要求 AI 扮演嚴謹的無障礙大師，不准有任何 API 幻想。
• A (Audience) 目標受眾：這個外掛是給視障者用的，GUI 必須完全支援無障礙讀取。
• R (Response) 輸出格式要求：要求直接給出完整可執行的 Python 程式碼。

📝 實戰演練：大導演的 CO-STAR 提示詞派工單

請將以下這張黃金派工單，整段複製並貼給你的 AI：

「[Context 背景脈絡] 你現在是一位頂尖且極度嚴謹的 NVDA 視障輔助軟體外掛工程師。我們正在為最新的 NVDA 2026.1 進行開發。

[Objective 任務目標] 請幫我編寫一個名為 passwordMute.py 的全域外掛（GlobalPlugin），放在 globalPlugins 下。 功能 1：請使用底層語音過濾技術，只要焦點是密碼框，就封殺語音朗讀，保護隱私。 功能 2：請提供一個原生 GUI 設定面板，讓使用者可以打勾開啟或關閉防窺功能。

[Style & Tone 開發規範與態度（請嚴格遵守 NVDA 官方指南）] 1. 【語音過濾】：請在 __init__ 中使用 speech.filter_speechSequence.moveToEnd(self.filter_password, last=False) 註冊過濾器，確保排序在最優先。 2. 【焦點判斷】：在過濾函數 filter_password 中，使用 api.getFocusObject() 判斷，若 obj.role == controlTypes.Role.PASSWORD 且設定為開啟，則直接 return [] 清空語音，否則正常放行。 3. 【GUI 面板】：請繼承 gui.settingsDialogs.SettingsPanel 建立設定視窗，使用 gui.guiHelper.BoxSizerHelper 來生成 wx.CheckBox 打勾框。 4. 【設定儲存】：請將打勾狀態保存到 NVDA 原生的 config.conf["passwordMute"]["enabled"] 中。 5. 【註釋要求】：代碼中必須包含清晰的中文註釋，解釋每一行程式碼的運作原理，讓不懂寫程式代碼的一般人也能了解。

[Audience 目標受眾] 你的程式碼將被視障者與 Vibe Coding 導演直接使用，請確保介面與代碼邏輯簡單清晰、完全支援螢幕閱讀器朗讀。

[Response 輸出格式] 請直接給我這支 passwordMute.py 的完整 Python 原始碼，不需多餘的解釋，只要可以直接執行的程式碼。」

🛠️ 看懂 AI 寫的代碼：逐行白話拆解

這份大師級外掛代碼非常精美。我們跟著 Ray，一行行看懂它是如何掌控語音與介面的：

# 引入全域外掛基礎模組
import globalPluginHandler
# 引入核心 API
import api
# 引入控制項角色定義
import controlTypes
# 引入語音模組
import speech
# 引入設定管理模組，用來讀寫 config.conf
import config
# 引入 wxPython 視窗控制庫
import wx
# 引入 NVDA 原生設定面板與版面配置輔助工具
import gui
from gui.settingsDialogs import SettingsPanel

# 1. 向 NVDA 的設定系統註冊我們外掛的專屬欄位與預設值
# 預設為啟用防窺 (enabled=True)
config.conf.spec["passwordMute"] = {
    "enabled": "boolean(default=True)"
}

class GlobalPlugin(globalPluginHandler.GlobalPlugin):

    def __init__(self):
        super().__init__()
        # 2. 註冊我們的語音過濾器函數
        speech.filter_speechSequence.register(self.filter_password)
        # 3. 將我們的過濾器移到整個過濾鏈的最前面，保證第一個攔截
        speech.filter_speechSequence.moveToEnd(self.filter_password, last=False)

    # 這是語音過濾器的核心。每次 NVDA 要說話前，都會把要說的文字（speechSequence）丟進來
    def filter_password(self, speechSequence):
        # 取得目前使用者的焦點物件
        obj = api.getFocusObject()

        # 檢查設定檔中防窺功能是否為啟用狀態
        isEnabled = config.conf["passwordMute"]["enabled"]

        # 4. 如果焦點物件的角色是「密碼框」，且防窺功能是有開啟的
        if obj and obj.role == controlTypes.Role.PASSWORD and isEnabled:
            # 直接回傳一個空的列表！這會把所有原本要唸出來的字母直接消音！
            return []

        # 如果不是密碼框，或者防窺功能關閉了，就原封不動放行，正常朗讀
        return speechSequence

# 5. 建立我們的設定面板類別，繼承自官方的原生面板
class PasswordMuteSettingsPanel(SettingsPanel):
    # 設定面板的標題
    title = "密碼防窺外掛設定"

    # 用來繪製畫面的函數
    def makeSettings(self, settingsSizer):
        # 建立一個自動對齊與排版的助手
        helper = gui.guiHelper.BoxSizerHelper(self, sizer=settingsSizer)

        # 建立一個打勾框，文字為「啟用密碼框自動靜音功能」
        self.chkEnabled = helper.addItem(wx.CheckBox(self, label="啟用密碼框自動靜音功能"))

        # 將目前設定檔裡的數值，自動填入這個打勾框中（如果是 True 就打勾，False 就不打勾）
        self.chkEnabled.SetValue(config.conf["passwordMute"]["enabled"])

    # 當使用者在設定面板按下「確定」或「套用」時執行
    def onSave(self):
        # 將打勾框目前的狀態，儲存回 NVDA 原生的設定檔中，完成永久保存！
        config.conf["passwordMute"]["enabled"] = self.chkEnabled.GetValue()

💡 核心代碼導讀：

• config.conf.spec：這告訴 NVDA 在 config.conf 設定檔裡開闢一小塊專屬空間。這樣一來，外掛重啟或電腦關機後，使用者的打勾設定依然會被永久記住！
• return []：這是過濾器的絕招。speechSequence 是一個要被送去語音引擎的「火車清單」，回傳 [] 就等於把整台火車的貨物丟掉，語音引擎收不到貨，自然保持絕對安靜！

🧪 測試與驗收

1. 將檔案命名為 passwordMute.py 放進 globalPlugins。
2. 重啟 NVDA。按下 NVDA+N 開啟選單 -> 偏好設定 -> 設定。
3. 檢查左邊的清單，你會驚喜地發現「密碼防窺外掛設定」已經完美出現在官方列表裡了！
4. 點選它，並測試在瀏覽器登入密碼時，NVDA 是不是已經完全安靜不唸出你的密碼。恭喜！你的第一個商用級外掛完美成功！

👉 下一堂課：Lecture 19 【實戰演練六】Browse Mode 網頁快鍵導航 (clickable_nav)
👉 回課程大綱：學習地圖