bopomofo-rescue

Detect and recover text that was accidentally typed with the Taiwanese Bopomofo / Zhuyin (注音) keyboard while the input method (IME) was stuck in English/ASCII mode — what Taiwanese users call 注音亂碼 or

SKILL.md

GitHub

注音鍵盤誤打還原 (Bopomofo Input Recovery)

安裝前提 (Prerequisite)

這個 skill 需要上游 repo 內附的解碼腳本與注音詞典(約 5 MB)才能運作;本目錄 只收錄 SKILL.md 與參考資料。請直接從來源安裝:

git clone https://github.com/Oliviaiii/bopomofo-rescue.git ~/.claude/skills/bopomofo-rescue

安裝後會一併掛上 UserPromptSubmit hook,訊息送出當下就自動解碼,不需任何前綴指令。 需要 Python 3,且 python 在 PATH 上。

This skill requires the decoder script and Bopomofo dictionary (~5 MB) bundled in the upstream repository — only SKILL.md and references/ are vendored here. Install from source with the command above. Requires Python 3 on PATH.

這個 skill 在解決什麼

台灣工程師常用注音輸入法。忘記把輸入法從英文切回中文時,本來想打的中文會 變成一串按鍵序列 —— 例如想打「你好嗎」卻打出 su3cl3a8。這串不是英文、也 不是亂碼,而是注音鍵盤的實體按鍵。這個 skill 把它還原回中文,讓你不必 重打就能繼續原本的請求。

核心原則

還原這一步一定要用 scripts/decode_bopomofo.py,不要自己心算。 LLM 自己硬猜按鍵映射經常出錯(例如會把 dj94 說成「是的」,實際是「快」)。 這支程式是純查表 + 音節切分 + 詞典斷詞(IME 式最大機率),會直接給你注音與 中文猜測。你的工作是用上下文確認或修正它的猜測 —— 這是你的強項,因為 同音字要靠前後文消歧(ㄕˋ = 是/事/世/市…),而標準 IME 沒有上下文、你有。

工作流程

當使用者訊息可能含注音誤打時:

  1. 執行腳本(把整段原始訊息交給它,它會自己挑出候選、跳過技術字串):

    python "${CLAUDE_SKILL_DIR}/scripts/decode_bopomofo.py" --brief "使用者的原始訊息"
    

    預設用 --brief:只回傳判讀所需欄位,約為完整 JSON 的 10%,省下大量 context。需要同音字候選或除錯時再拿掉 --brief(完整輸出含 chinese_alternatives、confidence 等;--full 另外附上所有 token 的 segments)。

    輸出 JSON 的重點欄位:

    • has_candidates:是否偵測到疑似誤打中文。
    • candidates[]:每個候選的 bopomofo(注音)、chinese(詞典最佳中文猜測)、 tier(信心分級)、以及可能出現的 repair(打字手誤補救建議,見下)。
    • reconstructed:把候選換成中文(詞典可用時)或 [注音] 的整句版本,直接可讀。
  2. 依 tier 決定行為(見下)。

  3. 用上下文確認 chinese 猜測,代回原句,然後照還原後的意思繼續做事。

依信心分級的行為

腳本已經把 confidence 轉成三級。請照這個原則反應,重點是不要打斷開發節奏:

tier 信心 建議行為
high ≥ 0.90 靜默還原,直接照還原後的意思繼續。不用大張旗鼓宣告。
medium 0.65–0.89 用一句話標註你的推測(例:「su3cl3a8 我理解為『你好嗎』」)再繼續。
low < 0.65 預設不動。只有在上下文讓意思非常明顯時才採用,否則照原文理解。

low 多半是純字母、能硬切成音節但其實可能是英文的 token(如 npm、git、 html)。這類寧可放過,除非整句語境明顯是中文而這個 token 格格不入。

確認中文猜測(你的工作)

腳本已用詞頻詞典給出 chinese 最佳猜測(常見句多半直接正確)。你負責用上下文 把關:

  • 預設採用 chinese。像 su3cl3a8 → 你好嗎、g42k7 → 是的,通常直接對。
  • 語境不合時,改看 chinese_alternatives。詞典只看頻率、不看上下文;若最佳 猜測在句中不通,從同音候選裡挑合理的(ㄕˋ 的候選:是/試/時/十/事…)。
  • 若怎麼拼都不成合理中文,就退回原文照字面理解,別硬湊。這個 fallback 很重要 —— 誤把 npm run dev 當中文會造成實際傷害。
  • 詞典缺席時(未安裝資料檔)chinese 會是空的、只有 bopomofo,這時就由你依 注音在上下文中判讀。

repair:打字手誤的補救建議

有時 tier 是 high、注音也切得出來,但 chinese 是空的 —— 這通常代表相鄰兩鍵 打反了。例如「說」= ㄕㄨㄛ 應打 gji,快打成 jgi,切出來變 ㄨ + ㄕㄛ:音節合法, 但國語沒有這個詞,詞典自然查無。

這時腳本會附上 repair 陣列(最多 3 個建議):

"repair": [{"kind": "transpose", "from": "jgi", "to": "gji",
            "chinese": "說", "note": "相鄰兩鍵對調後詞典可完整還原"}]

怎麼用:

  • 看到 repair 就優先採用它的 chinese,因為原本的解讀根本還不出中文, 而這個建議能被詞典完整還原 —— 它幾乎一定比原解讀接近使用者的本意。
  • 但仍要用上下文確認。轉置只是最常見的手誤之一,不保證就是使用者的原意。
  • 若 repair 建議在語境中不通,就退回原解讀(原本的 bopomofo 一直都保留著), 依注音自行判讀,或直接照原文處理。
  • 有多個建議時,挑語境最合理的,不必然是第一個。
  • repair 只是建議:腳本不會因此改寫 bopomofo,也不會提高 confidence。 最終判斷是你的工作。

安全界線(重要)

  • 腳本已排除程式碼區塊、行內 code、URL、路徑、git hash、CLI flag、版本號、 含大寫的識別字。你仍應再判斷一次:如果某個「候選」其實在語境中是檔名、 變數、指令,就不要還原它。
  • 這個 skill 只解讀輸入、不改變請求的意圖。還原後請照使用者本來的意思做事。

範例

範例 1(high,靜默) 輸入:su3cl3a8 幫我看一下這個 function 腳本:chinese=你好嗎 tier=high,reconstructed=你好嗎 幫我看一下這個 function 你的理解:直接照「你好嗎,幫我看一下這個 function」回應請求,不用特別解釋還原過程。

範例 2(用 alternatives 修正) 輸入:ej94k6 這個字怎麼念(假設 chinese 猜測在語境中不通) 腳本:給 chinese 與各音節的 chinese_alternatives 你的行為:從候選裡挑語境合理的字;若仍拼不出合理中文,就退回原文。

範例 3(技術字串,不觸發) 輸入:run npm install then git commit -m fix in ./src/app.py 腳本:has_candidates=false 你的行為:完全照原文處理,不做任何還原。

參考資料

需要人工核對、或腳本不可用時,可查:

  • references/keyboard-layout.md —— 大千式注音鍵盤完整對照表與合法韻母清單。
  • references/exclusion-rules.md —— 哪些字串該跳過、為什麼。

但正常情況下一律以腳本輸出為準,不要用參考表自己重算按鍵映射。