# Encoding Guard

> Prevents encoding corruption (乱码/mojibake) when modifying C/C++ and other source files that use non-UTF-8 encodings (GBK, GB2312, GB18030, Shift-JIS, Latin1, Big5). MUST be used BEFORE any Edit/Write operation on .cpp, .h, .c, .hpp, .cc, .cxx, .hxx source files in legacy or mixed-encoding projects. Also triggers on keywords: 编码, 乱码, GBK, UTF-8, UTF-8 with BOM, charset, codepage, iconv, mojibake,…

- **Type:** Skill
- **Install:** `agentstack add skill-autsunset-encoding-guard-encoding-guard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Autsunset](https://agentstack.voostack.com/s/autsunset)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Autsunset](https://github.com/Autsunset)
- **Source:** https://github.com/Autsunset/encoding-guard

## Install

```sh
agentstack add skill-autsunset-encoding-guard-encoding-guard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:批量改动前先全量扫描(强烈建议)

```bash
python scripts/check_encoding.py
```

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

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

```bash
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 文件)

```bash
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:转回原编码并校验

```bash
# 将修改后的 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` |

## 依赖

```bash
pip install chardet
```

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

在项目根目录创建标记文件:
```bash
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](https://github.com/Autsunset)
- **Source:** [Autsunset/encoding-guard](https://github.com/Autsunset/encoding-guard)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-autsunset-encoding-guard-encoding-guard
- Seller: https://agentstack.voostack.com/s/autsunset
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.