一个中文乱码检测修复工具 AI Text Encoding Guard

最近整理了一个开源项目，叫 AI Text Encoding Guard。
事情的起因很具体：用 Claude Code 改含中文的文件，改完一看，中文全变乱码了。

修复前（乱码）                  修复后（正常）
─────────────────────           ─────────────────────
// 鐢ㄦ埛鐧诲綍鎴愬姛             // 用户登录成功
// 鏁版嵁搴撹繛鎺ュけ璐�           // 数据库连接失败
// 璁㈠崟鍒涘缓鎴愬姛              // 订单创建成功

这不是个例。Claude、Cursor、Copilot、Codex 都会中招。根源是 UTF-8 字节被误读为 GBK，等你发现的时候用户已经看到乱码了。

它做的事

扫描文件 → 七种乱码模式打分 → 可疑文件标记 → 一键修复（带备份）

核心流程：

扫描项目目录，默认覆盖 20 种常见文件扩展名
七种检测维度逐行分析，每种有独立权重
文件总分 > 0 标记为可疑，分数越高越严重
--fix-gbk 自动修复，三重安全门防止误修复
修复前自动创建 .bak.mojibake 备份

七种检测维度

乱码类型	产生原因	检测信号	权重
口字码	UTF-8 读 GBK	Unicode 替换字符 `�`	+12
破标签	AI 编辑吞尖括号	损坏的 HTML 闭合标签	+10
古文码	GBK 读 UTF-8	18 个已知乱码码点	+2
锟拷码	UTF-8→GBK→UTF-8 双重转换	`锟斤拷` 模式匹配	+8
烫屯码	VC 调试未初始化内存	`烫烫烫` / `屯屯屯` 重复	+6
问句码	双重转换	中文后连续 `??`	+8
符号码	ISO8859-1 读 UTF-8	拉丁扩展字符密集出现	+2

修复的三重安全门

修复不是盲目替换，而是：

① 尝试 GB18030 编码 → UTF-8 解码（逆向还原）
   也尝试反方向：UTF-8 编码 → GB18030 解码
        ↓
② 修复后分数必须 ≤ 原分数的 1/3
        ↓
③ 绝对改善值必须 ≥ 8 分
        ↓
  ┌─ 全部通过 → 写入修复 + 创建 .bak.mojibake 备份
  └─ 任一失败 → 跳过，标记为需人工检查

三道门全过才写入，任何一道不满足就跳过。宁可漏修，不可误修。

集成方式

GitHub Actions — 一行卡住 PR

- uses: haodehaode378/text-encoding-guard@v1

PR 有乱码自动拦截。

Claude Code — 每次编辑自动触发

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "python scripts/check_mojibake.py --root .",
        "description": "Check for Chinese mojibake after file edits"
      }
    ]
  }
}

加到 .claude/settings.json 里，AI 每次改文件都会自动跑一遍检测。乱码当场发现，当场修。

直接用

check-mojibake --root ./src
check-mojibake --root ./src --fix-gbk
check-mojibake --root . --fail-on-find

技术细节

零依赖，纯 Python 标准库，不需要装任何第三方包
双向修复，UTF-8↔GBK 两个方向都试
20 种默认扩展名，覆盖 .py .md .js .ts .vue .html .json 等
自动跳过 .git node_modules dist build 等目录
JSON 输出，方便管道和 CI 集成
Python 3.10+

谁会中招

场景	中招概率	后果
Claude Code 编辑含中文的 Vue/React 组件	极高	UI 文案全变乱码
Cursor 批量重构中文注释	高	代码可读性归零
Copilot 生成中文文档	中	README 变天书
CI/CD 自动化脚本处理中文文件	中	静默损坏，上线后才发现

为什么做这个

现有工具要么只检测编码（file/uchardet），不检测乱码内容；要么需要人工肉眼看。没有一个工具能同时做到：精确检测乱码 + 自动保守修复 + CI 集成 + AI 助手触发。

这个工具就是填这个坑的。

如果你也在用 AI 编码助手写中文项目，建议把它挂到 CI 或 Claude Code hooks 上。早发现早修复，比上线后被用户看到乱码强。

仓库地址：https://github.com/haodehaode378/text-encoding-guard

欢迎拿你的项目来试，跑一遍 check-mojibake --root . 看看有没有惊喜。
提 bug 或建议我会优先排进下一版。