Encoding Guard

Encoding Guard

防止 AI 编码工具 (Claude Code / Codex / Cursor 等) 在修改非 UTF-8 源文件时,因默认按 UTF-8 读写而永久损坏文件(乱码)。

何时使用本技能

必须触发(强制):

• 即将 Edit/Write 任何 .cpp / .h / .c / .hpp / .cc / .cxx / .hxx 源文件之前
• 用户提到 乱码 / 编码 / GBK / UTF-8 / 字符编码 / charset / mojibake 等关键词
• 在遗留项目、Windows 中文项目、中日韩项目中修改源码

可跳过(项目已确认为纯 UTF-8):

• 项目根目录存在 .encoding-utf8-only 标记文件
• 或上一轮扫描确认所有目标文件均为 UTF-8

核心问题

原文件(GBK) → AI按UTF-8读取(乱码) → AI基于乱码修改 → 按UTF-8写回 → 文件永久损坏

AI 工具的 Edit/Write 是纯文本替换,不感知编码。一旦源文件是 GBK 等非 UTF-8 编码,直接编辑必然乱码。

关键原则

根因只有一个:AI 的 Edit/Write 是纯文本替换,不感知编码。下面的原则都由此而来。

1. 编辑前先检测 — 不知道编码就无法安全编辑,先 detect 一次再决定走哪条路径。
2. 非 UTF-8 走转码流程 — 对 GBK 等原文件直接 Edit,等于亲手触发上面的乱码管道;经"转码 → 修改 → 转回"才安全。
3. 改后回校验 — 确认编码未被改变,拦截静默损坏。
4. 发现损坏立即恢复 — 编码被意外改成 UTF-8 时,git checkout -- 找回原文件再走一遍流程。
5. 批量改动先全扫 — 多文件场景先掌握各自原始编码,逐个决定是否需要走流程。

> 本技能的脚本位于本 skill 目录下的 scripts/。下文命令假设在 skill 根目录(即本 SKILL.md 所在目录)执行,或用绝对路径调用。

标准工作流

步骤 0:批量改动前先全量扫描(强烈建议)

python scripts/check_encoding.py

输出每个源文件的编码,标记非 UTF-8 的文件。

步骤 1:检测目标文件编码

python scripts/encoding_helper.py detect src/main.cpp

输出示例:

src/main.cpp → GBK (confidence: 0.99)  ⚠️ 需走安全流程

• UTF-8 / UTF-8-SIG / ASCII → 可直接编辑,跳到步骤 4 校验。
• GBK / GB2312 / Shift-JIS / Big5 / Latin1 等 → 必须走安全流程。

步骤 2:转码到 UTF-8(仅非 UTF-8 文件)

python scripts/encoding_helper.py to-utf8 src/main.cpp

生成:

• src/main.cpp.utf8 — UTF-8 工作副本(供 AI 编辑)
• src/main.cpp.bak — 原始备份

> 转码只改字符编码,保留原始行尾(CRLF/LF/CR 原样透传)。若项目是 Windows CRLF,往返后行尾不会变。

步骤 3:在 UTF-8 副本上修改

对 src/main.cpp.utf8 执行 Edit。不要直接改原 src/main.cpp — 那会触发乱码管道(见核心问题)。

步骤 4:转回原编码并校验

# 将修改后的 UTF-8 副本转回原编码,覆盖原文件
python scripts/encoding_helper.py from-utf8 src/main.cpp.utf8 --encoding GBK
# 校验编码正确(有 git 时会与 HEAD 版本对比)
python scripts/check_encoding.py src/main.cpp
# 确认无误后清理临时文件
rm src/main.cpp.utf8   # .bak 可保留到测试通过后再删

校验通过前不要删除 .bak。

快捷命令对照

| 需求 | 命令 | |---|---| | 全量扫描项目编码 | python scripts/check_encoding.py | | 检测单文件编码 | python scripts/encoding_helper.py detect | | 扫描目录编码 | python scripts/encoding_helper.py scan [dir] | | 校验单文件编码是否被改变 | python scripts/check_encoding.py | | 不对比 git 仅报告当前编码 | python scripts/check_encoding.py --no-git |

依赖

pip install chardet

已统一 UTF-8 的项目(跳过检测)

在项目根目录创建标记文件:

touch .encoding-utf8-only

存在此文件时,本技能直接放行编辑,跳过检测流程。

局限性

本技能依赖 AI 自觉遵守流程,属于软约束,可靠性有限。如需硬约束,建议升级为:

1. Hooks 守卫: .claude/settings.json 配置 PreToolUse/PostToolUse hook,自动检测+转换。
2. Git 防护: .gitattributes + pre-commit hook,拒绝编码被改变的提交。
3. 终极方案: 全项目统一 UTF-8,配合 MSVC /utf-8 编译选项。

详见 skill 目录下的 README.md。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Autsunset
• Source: Autsunset/encoding-guard
• License: MIT

Install and usage instructions live in the source repository linked above.