编码自动切换器 (encoding-guard)
打开文件时自动检测编码格式并以正确编码显示；内核猜不对的文件自动打开正确编码视图；检测到 AI 写坏编码时自动修复还原（可逆损坏，内容与行数不变）。编码列表可配置，不写死 GBK——任何 iconv-lite 支持的编码都可适配。
一作者：上了个大笔当
二作者：咕咚咕咚
功能
- 自动检测并正确打开（主要功能）：打开文件时自动检测编码，猜错时按检测到的编码重新打开纠正，无需任何操作
- 正确编码编辑器：内核编码重开能力缺失时（如 Trae SOLO），自动打开按正确编码解码的可编辑视图（等效于按编码重开），自动关闭乱码标签，正常编辑、Ctrl+S 按原编码保存回文件；文件被外部修改时视图自动刷新
- AI 改写自动纠正：AI 工具改写已打开的文件后，自动比对磁盘内容与编辑器显示，不一致则重开纠正。仅当整个文件字节编码一致（仅内核标签猜错）时有效；若新增/修改部分的编码与既有内容不一致（混合编码）或内容已损坏，重开无法恢复，此类情况由「外部写入监督」告警提示
- 外部写入监督与自动修复：AI 不经编辑器直接改写磁盘文件时，后台监听变化并做编码体检。可逆损坏自动修复还原（双重转码还原 / 混合编码分段转码 / 编码迁移回滚），纯字节转码保证内容与行数不变、修复前留
.bak 临时备份（成功后自动删除）；不可逆损坏（字节已丢失）无法恢复，仍告警提示回退
- 选择编码保存：编辑器标题栏按钮，下拉选择目标编码后转换保存；按源编码解码磁盘字节再写回，中文内容不损坏；有未保存修改时拒绝转换
- 以正确编码查看：命令面板手动对当前文件打开正确编码视图
命令
| 命令 |
说明 |
编码切换: 选择编码保存 |
下拉选择目标编码（UTF-8 及设置中的检测编码），转换并保存 |
编码切换: 以正确编码查看 |
对当前文件打开正确编码可编辑视图 |
配置
| 设置项 |
默认值 |
说明 |
encoding-guard.detectionEncodings |
["gbk", "gb18030"] |
UTF-8 之外要自动识别/纠正/转换的编码列表（iconv-lite 支持的编码名，如 big5、shift_jis、cp1252 等），按优先级排序 |
encoding-guard.kernelGuessEncodings |
["utf8", "gbk", "gb18030"] |
写入内核 files.candidateGuessEncodings 的候选编码 |
encoding-guard.applyKernelGuess |
false |
是否把上面列表写入内核猜码设置。默认关闭：部分内核对候选列表支持不佳，强制写入会导致猜测失效、只回落默认编码 |
encoding-guard.autoRepairBytes |
true |
检测到可逆编码损坏（双重转码/混合编码/编码迁移）时自动修复文件字节；关闭后只告警不修改 |
encoding-guard.repairBackup |
true |
自动修复前写 .bak 临时备份（成功后自动删除） |
encoding-guard.maxRepairBytes |
5242880 |
自动修复的文件大小上限（字节），超过只告警 |
默认配置对中国 GBK 环境开箱即用；其他环境（Big5、Shift-JIS 等）修改 detectionEncodings 即可。
工作机制
打开文件的纠正决策链：
打开 GBK 等非 UTF-8 文件
├─ 内核猜对 → 正常显示（结束）
├─ 猜错 → 命令式重开（自动侦查内核的 reopenWithEncoding 类命令）
│ └─ 失败 → 关闭重开 1 次（内核猜测是确定性的，多试无益）
└─ 全部失败 → 自动打开正确编码可编辑视图（单视图，替换乱码标签，Ctrl+S 按原编码写回）
其他机制：
- 通用检测：BOM-UTF8 → UTF-8 字节校验 → 按配置编码列表依次试解码（无替换字符即命中）
- 每次重新打开都重新检测：用户重新打开文件时自动清除该文件的历史结论（指纹/冷却/视图记录），重新走完整纠正链；插件内部重开重建文档模型的事件会被标记拦截，不与用户打开混淆，也不产生循环
- 防打扰：串行队列 + 失败 10 分钟冷却（仅约束外部改写触发的重试，用户打开不受限）+ 编码编辑器开着时不重复打开
- 外部写入监督：FileSystemWatcher → 只读头部 64KB 探测 → 截断容错（末尾 1~3 字节修正）→ 二进制/文本扩展名双层过滤 → 500ms 防抖 → 全文一致性校验 → 日志文件只记日志不弹窗
- 字节级自动修复（可逆损坏）：只做纯字节转码，绝不重组文本——
- 双重转码还原：GBK 字节经 latin1/cp1252 路径被写成 UTF-8 时，逆向转码 100% 还原
- 混合编码分段转码：原 GBK 文件被 AI 用 UTF-8 写入部分行（或对称场景）时，逐行判定编码归属，少数派行无损转成多数派编码；行内混合无法可靠切分，保守放弃并告警
- 编码迁移回滚：内容完好但编码被整体改写（GBK 文件被 AI 整体按 UTF-8 重写，或对称地 UTF-8 文件被按 GBK 重写）时，自动转回监听记录的原编码（依赖
lastEnc 历史记录，会话内首次写入无从判定时不触发）
- 三道硬校验（无损解码 / 行数不变 / 行级 round-trip），任一失败放弃修复退回告警
- 并发安全：静默窗口（指纹 2 秒不变才动手）+ 动手前重读比对 + 临时文件 rename 原子替换 + 回写对抗（AI 用旧快照覆盖时自动再修，上限 3 次后告警提示让 AI 重新读取）
- 行数不变有数学保证：UTF-8 与 GBK/GB18030 的多字节序列都不含 0x0A，纯转码不会吞掉换行符
- 不污染配置：默认不改写内核编码设置；历史版本写入过的全局候选列表会自动检测并恢复
- 保存防覆盖：编码编辑器 Ctrl+S 时重新检测文件当前实际编码并按它写回；若编码已被外部改写（与打开时不一致），阻止保存并弹警告，防止覆盖外部内容
安装
- 扩展面板右上角
··· → 从 VSIX 安装...，选择 encoding-guard-x.y.z.vsix
- 本地开发调试：F5 启动扩展开发宿主窗口
构建
build.bat
自动完成：安装依赖 → 类型检查 → esbuild 构建 → 生成 .vsix 安装包。
诊断
输出面板（Ctrl+Shift+U）选择「编码切换器」查看检测、命令侦查、重开、视图、转换的详细日志。
已知限制
- 编码编辑器中编辑后 Ctrl+S 按原编码（如 GBK）写回，超出该编码字符集的内容（如 emoji）会丢失，属编码本身限制
- 持续追加的日志文件不做外部改写校验与自动重开（追加与全文比对天然竞态），仅保留损坏告警
- 同一行内混合两种编码的内容（AI 在已有中文的行内改写）无法仅凭字节可靠切分归属，自动修复会保守放弃并告警，不做猜测性修复
- AI 写盘时已丢失字节（解码出 U+FFFD）的损坏在数学上不可恢复，任何工具都无法还原，只能告警回退
- 未保存的新文件（Untitled）无法转换编码，需先保存
| |
