Oliviaiii 注音鍵盤誤打還原 (Bopomofo Input Recovery)
這個 skill 在解決什麼
台灣工程師常用注音輸入法。忘記把輸入法從英文切回中文時，本來想打的中文會
變成一串按鍵序列 —— 例如想打「你好嗎」卻打出 su3cl3a8。這串不是英文、也
不是亂碼，而是注音鍵盤的實體按鍵。這個 skill 把它還原回中文，讓你不必
重打就能繼續原本的請求。
核心原則
還原這一步一定要用 scripts/decode_bopomofo.py，不要自己心算。
LLM 自己硬猜按鍵映射經常出錯（例如會把 dj94 說成「是的」，實際是「快」）。
這支程式是純查表 + 音節切分 + 詞典斷詞（IME 式最大機率），會直接給你注音與
中文猜測。你的工作是用上下文確認或修正它的猜測 —— 這是你的強項，因為
同音字要靠前後文消歧（ㄕˋ = 是/事/世/市…），而標準 IME 沒有上下文、你有。
工作流程
當使用者訊息可能含注音誤打時：
執行腳本（把整段原始訊息交給它，它會自己挑出候選、跳過技術字串）：
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：把候選換成中文（詞典可用時）或[注音]的整句版本，直接可讀。
依
tier決定行為（見下）。用上下文確認
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—— 哪些字串該跳過、為什麼。
但正常情況下一律以腳本輸出為準，不要用參考表自己重算按鍵映射。