Chinese Mojibake Scan 是一個保守型中文亂碼與編碼風險掃描器，適合用在含有繁體中文、簡體中文、CSV、Markdown、log、設定檔、原始碼或中英混合內容的專案。
它預設只回報證據，不會自動改檔。
可偵測內容
- Unicode replacement character，通常代表文字曾經被錯誤或有損解碼。
- 可逆的 UTF-8 被 Latin-1/CP1252 錯解造成的中文 mojibake。mojibake-scan: ignore
- UTF-8 解碼失敗，但 Big5、CP950、GBK、GB18030 可解出合理中文的檔案。
- 可疑 mojibake token 與 C1 control character。
- 終端機或 PowerShell 顯示錯亂，但檔案本身可能仍是正確 UTF-8 的情況。
快速開始
在你要檢查的專案根目錄執行：
python "$env:USERPROFILE\.codex\skills\chinese-mojibake-scan\scripts\scan_mojibake.py" .
如果你是 clone 這個 repository，也可以直接執行本地版本：
python scripts\scan_mojibake.py .
常見用途：
| 用途 | 指令 |
|---|---|
| 掃描目前專案並輸出可讀報告 | python scripts\scan_mojibake.py . |
| 輸出 JSON 給自動化流程使用 | python scripts\scan_mojibake.py . --json |
| 只掃描單一檔案 | python scripts\scan_mojibake.py path\to\file.txt |
| 包含 generated、dependency 等預設略過的路徑 | python scripts\scan_mojibake.py . --include-all |
| 排除容易吵的路徑 | python scripts\scan_mojibake.py . --exclude "logs/*" --exclude "*.min.js" |
| 跑內建樣本 corpus 成功率評估 | python scripts\evaluate_corpus.py |
輸出範例：
[high] reversible-utf8-as-latin1-or-cp1252 docs\release-notes.md:12 reason: Line can be reinterpreted into Chinese by reversing Latin-1/CP1252 mojibake. snippet: broken: ... suggested: fixed: ...
忽略刻意範例
如果文件中刻意展示亂碼範例，可以在同一行加入：
mojibake-scan: ignore
也可以建立 .mojibakeignore，用 glob pattern 排除檔案：
references/*.md fixtures/intentional/*
輸出格式
文字輸出會依嚴重度排序：
high：replacement character、可逆中文 mojibake、或可能是 legacy 中文編碼。medium：可疑 mojibake token 或 control character。low：非 UTF-8 文字或讀取錯誤，需要人工確認。
JSON 輸出會包含 path、line、kind、severity、reason、snippet，部分可逆案例會包含 suggested 修復建議。
成功率評估
執行內建 synthetic corpus 評估：
python scripts\evaluate_corpus.py
它會輸出 precision、recall、accuracy 與逐案例結果。內建 corpus 很小，建議持續加入真實案例來追蹤實際成功率。
Codex Skill 用法
用一行 PowerShell 指令安裝：
$dest="$env:USERPROFILE\.codex\skills\chinese-mojibake-scan"; if (Test-Path $dest) { Remove-Item $dest -Recurse -Force }; git clone https://github.com/Kelu0427/chinese-mojibake-scan.git $dest
之後可以照需求對 Codex 下提示詞：
| 目標 | 提示詞 |
|---|---|
| 只掃描不改檔 | 使用 chinese-mojibake-scan 掃描目前專案有沒有中文亂碼，只報告不要修檔 |
| 輸出詳細報告 | 使用 chinese-mojibake-scan 掃描目前專案，整理 path、line、severity、reason 和 suggested repair |
| 判斷是否只是終端機顯示亂碼 | 使用 chinese-mojibake-scan 判斷這是真實檔案壞掉，還是只有終端機顯示 mojibake |
| 修復可逆亂碼 | 使用 chinese-mojibake-scan 掃描並只修復明確可逆的中文 mojibake |
| 檢查 legacy 中文編碼 | 使用 chinese-mojibake-scan 找出可能是 Big5、CP950、GBK、GB18030 而不是 UTF-8 的檔案 |
| 忽略已知範例 | 使用 chinese-mojibake-scan 掃描此專案，但把標記 mojibake-scan: ignore 的行視為刻意範例 |
安全原則
- 把 mojibake 視為 byte-level evidence，不只靠肉眼看終端機輸出。
- 除非明確要求修復，否則不改檔。
- 可疑輸出要用 byte-level read 或明確 encoding 再確認。
- legacy Big5/GBK 檔案要先確認目標編碼，通常才轉 UTF-8。
授權
MIT License。詳見 LICENSE。
