開始用 Gongyeh

安裝與首次使用

請只從 Gongyeh 正式下載入口取得已簽名及經 Apple 公證的版本。下載後打開 DMG，將 Gongyeh 拖到 Applications，再從 Applications 開啟。

macOS 首次打開可能顯示互聯網下載確認，選擇「打開」即可繼續。若系統表示無法驗證開發者或檔案損毀，請停止使用該安裝檔並聯絡支援；不要關閉 Gatekeeper 或輸入繞過安全檢查的指令。

完成引導

Gongyeh 使用 Qwen3-ASR 1.7B / 4-bit，模型約 1.31 GB。已安裝的模型會直接重用；新安裝時，在「準備你的粵語模型」頁按「下載模型」。模型從 Hugging Face 的固定版本下載，可暫停及續傳。App 會檢查檔案大小與 SHA-256，完整通過後才啟用；請預留約 1.6 GB 空間，另加 App 所佔空間。

完成後依指示開啟麥克風及輔助功能權限。返回 App 時會重新檢查權限，也可按「已開啟？重新檢查」。輔助功能尚未生效時，可按「繼續試講」，用畫面按鈕錄音；跨 App 自動輸入仍需開啟輔助功能。引導試講不受試用或付費狀態限制。引導試講不計入試用；完成整個新手引導後，首次日常轉寫成功才開始 7 日免費試用；你也可按「稍後試講」直接完成設定。已經開始的試用不會因重跑引導而重置。之後辨識可離線進行；授權驗證的網絡要求另見「授權」設定。

在「設定 → 私隱與權限」中，麥克風顯示「尚未要求」時，按「允許麥克風」再在 macOS 提示中允許；顯示「未允許」時，按「系統設定」調整。權限狀態會獨立於模型載入更新，毋須等待模型準備完成。

如果系統設定已顯示開啟，但 App 仍未獲授權，先將 Gongyeh 的輔助功能開關關閉再開啟，返回 App 重查。仍未生效時，從清單移除舊的 Gongyeh 項目，再用「＋」加入「應用程式」內的 Gongyeh；若 macOS 提示重新開啟，按提示操作。早期測試版與正式版使用不同的簽名身分，從測試版升級可能需要重新確認。正式版沿用同一 Developer ID 身分。毋須關閉系統保安。

從測試版升級時的鑰匙串提示

試用開始時間、授權金鑰及離線驗證記錄保存在這部 Mac 的鑰匙串。簽名身分改變後，macOS 可能要求你允許新版讀取舊記錄，項目名稱可能顯示為 tech.noumenon.gong2。確認正在開啟正式的 Gongyeh 後，可輸入 login 鑰匙串密碼（通常與 Mac 登入密碼相同），並選「Always Allow／始終允許」。密碼由 macOS 驗證；Gongyeh 取得的是自己儲存的試用或授權資料。

鑰匙串、麥克風及輔助功能是獨立的授權。更新 App 或重新允許存取不會重置已開始的試用，也不需要刪除整個鑰匙串。

再次開啟與最近結果

關閉視窗後，Gongyeh 仍在選單列運行。從「應用程式」再次開啟會顯示首頁，可查看引擎狀態、最近一次結果及複製按鈕。輸入失敗會顯示短暫提示，文字仍可在首頁複製。語音引擎中斷時會嘗試恢復；若未能恢復，可在首頁按「重新載入語音引擎」。

錄音中的回饋與預覽

錄音時會顯示音量柱、時間與辨識預覽，浮窗會優先放在輸入框所在的螢幕。音量柱反映實際收音；未收到麥克風訊號時會顯示提示。Qwen3-ASR 每約 2 秒處理一塊音訊，說話期間持續更新預覽；末尾文字可能隨上下文修訂。放開快捷鍵後完成最後一段並一次輸入全文；只有引擎中途失敗時才會以完整錄音重試。

放開快捷鍵（Caps Lock 則再按一次）後，App 會完成餘下音訊的轉寫，再一次輸入最終文字。預覽不會提前寫入其他 App，也不會開始試用計時。按 Esc 或取消後，預覽和錄音會清除。預覽暫停時，仍可完成錄音後轉寫全文。

每日使用

先點選文字欄位，按住所選快捷鍵（預設 Fn）講廣東話，放開後轉寫。錄音長度不設限制，長段說話會在停頓處分段辨識，放開時只需完成最後一段；按 Esc 可取消。轉寫期間不要切換輸入欄位。如果輸入位置已改變，可從選單列複製最近一次結果。

Fn 可能與 macOS 表情符號或系統聽寫快捷鍵衝突。可在 Gongyeh 設定選其他快捷鍵，或在 macOS 鍵盤設定調整 Fn 的用途。Caps Lock 使用按一下開始、再按一下完成的方式。

在尚未允許輔助功能時，首頁仍可錄音並複製文字。開啟權限後即可使用全局快捷鍵與自動輸入。錄音中撤回麥克風會取消錄音；撤回輔助功能則會完成目前轉寫，保留文字供你複製。

國語與繁簡文字

「設定 → 一般 → 語言模式」可選粵語、國語或實驗中的自動偵測。「輸出文字」可選香港繁體、台灣繁體、傳統繁體或簡體。變更語言或文字格式會重新載入語音引擎；進行中的錄音完成後才套用。

人聲檢測會在本機過濾純噪音，沒有辨識到語音時不會輸入文字，也不會開始試用。仍請核對轉寫結果；人聲檢測不能保證辨識所有環境聲音。

詞庫：人名、地方、品牌與常錯字

「設定 → 詞庫」可加入經常用到的詞語，例如人名、公司名、港鐵站、品牌或工作用語。

• 正確寫法：會作為提示交給本機語音引擎，令它更容易辨識這些詞。
• 常見錯誤寫法（可留空，多個用「、」分隔）：如果講嘢經常把「搜尋」寫成「手尋」，把「手尋」加為錯誤寫法，之後輸入前會自動改正。英文詞語不分大小寫，只會整個詞替換。

每個詞語都可以暫停或刪除，最多 200 個。修改詞庫後，語音引擎會在閒置時自動重新載入；進行中的錄音完成後才套用。詞庫只儲存在這部 Mac。

麥克風與錄音問題

選擇正確的麥克風，確認裝置已連接及已取得系統權限。Gongyeh 不會更改其他 App 使用的系統預設麥克風。若沒有轉寫結果，先試一句較清楚的短句，再檢查輸入裝置。

轉寫完成，但沒有輸入

先確認游標位於可編輯文字欄位，並在系統設定開啟 Gongyeh 的輔助功能權限。密碼欄位及部分受保護輸入框不接受自動輸入。選單列保留最近一次轉寫，可按「複製文字」後自行貼上。

模型載入或轉寫出錯

下載中斷或服務暫時限流時，稍後按「繼續下載／重試」。已下載的部分會保留；校驗不符的檔案不會啟用，重試時會重新下載有問題的檔案。若空間不足，騰出空間後重試。

已完成下載但載入失敗，可選「重新載入語音引擎」。若模型遺失或損壞，可從選單「準備語音模型」或「設定 → 私隱與權限 → 準備／修復模型」重新檢查及下載。App 已包含執行環境，不需要 Python 或 Homebrew。相同模型會跨 App 更新重用。

更新 App 與模型

此版本採用已測試的固定模型。模型更新隨 App 版本說明提供；相同模型會沿用本機檔案，不必重新下載。目前沒有背景下載或自動安裝模型更新。

清除資料與移除

選單列及「設定 → 私隱與權限」都可清除最近一次轉寫。結束 App 亦會釋放這段文字。移除 App 前，可先關閉登入時自動啟動，並在系統設定撤回權限。鑰匙圈中的試用日期不一定隨移除 App 一併刪除。

模型保存在 ~/Library/Application Support/Gongyeh/Models/，移除 App 不會自動刪除它們。「設定 → 私隱與權限 → 在 Finder 顯示」可打開該位置；結束 Gongyeh 後移除 Models 資料夾即可釋放空間。下次使用需重新下載。

登入時啟動

在「設定 → 一般」開啟登入時啟動。若顯示等待系統允許，按「開啟系統登入項目」完成批准；未批准前不會自動啟動。系統拒絕或變更會直接反映在設定頁，App 不會在背景替你重新開啟已關閉的登入項目。

支援

正式支援聯絡方式：gongyeh@noum.tech。回報時提供 macOS 版本、App 版本及重現步驟即可；請不要傳送密碼、付款資料、完整授權金鑰或未獲同意的錄音。