# encoding-guard

**Repository Path**: nn200433/utf8-cli

## Basic Information

- **Project Name**: encoding-guard
- **Description**: cli 读写文件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# encoding-guard

`encoding-guard` 是一个面向仓库文本文件的 UTF-8 守卫工具。
它基于 Go 实现，兼容 `encoding_guard_sample.py` 的核心扫描行为，并补充了帮助、环境诊断和 JSON 报告能力。

## 功能

- 检测 invalid UTF-8
- 检测 UTF-8 BOM
- 检测 Unicode replacement character `U+FFFD`
- 检测常见 mojibake 标记序列
- 检测可疑的连续问号占位符
- 检测混合换行符 `CRLF` / `LF`
- 检测 UTF-16 / UTF-32 或 UTF-16 风格 NUL 字节风险
- 检测异常控制字符
- 支持显式路径、递归目录、Git staged 文件扫描
- 支持 `--rewrite-utf8` 去除 UTF-8 BOM
- 支持 `doctor` 环境诊断
- 支持 `--report json` 输出结构化结果

## 快速开始

```powershell
.\scripts\build.ps1 -RunTests -Clean
.\dist\encoding-guard.exe help
.\dist\encoding-guard.exe README.md
.\dist\encoding-guard.exe --recursive docs
.\dist\encoding-guard.exe --preset active-source
.\dist\encoding-guard.exe --staged --report json
.\dist\encoding-guard.exe doctor
```

## 常用命令

```powershell
.\dist\encoding-guard.exe help
.\dist\encoding-guard.exe help scan
.\dist\encoding-guard.exe presets
.\dist\encoding-guard.exe doctor
.\dist\encoding-guard.exe README.md
.\dist\encoding-guard.exe --recursive docs --exclude "**/session/**"
.\dist\encoding-guard.exe --rewrite-utf8 .\docs
.\dist\encoding-guard.exe --report json README.md
```

默认输出保持纯文本格式：

```text
[encoding_guard][ok] README.md
[encoding_guard][warn] docs/example.md: has UTF-8 BOM
[encoding_guard][summary] inspected=2 missing=0 recursive=true preset=custom
```

## 退出码

- `0`: 没有发现问题
- `1`: 存在 warning / invalid / missing / 运行时错误
- `2`: 参数或用法错误

## Build

```powershell
.\scripts\build.ps1 -RunTests -Clean
```

默认产物路径是 `dist\encoding-guard.exe`。

可选参数：

- `-OutputDir <path>`: 自定义输出目录
- `-RunTests`: 构建前执行 `go test ./...`
- `-Clean`: 构建前清理输出目录

## 防乱码原则

- 不要让中文正文通过 PowerShell pipeline 或 stdin 在多个工具之间中转。
- 优先让程序直接读写目标文件，而不是把中文内容先输出到终端再写回文件。
- 在 Windows PowerShell 中，处理中文前显式设置 UTF-8 编码。
- 修改完成后，再用 `encoding-guard` 扫描受影响文件。
- 如需先做环境确认，运行 `encoding-guard doctor`。

推荐 PowerShell 初始化：

```powershell
$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
[Console]::InputEncoding = $utf8NoBom
[Console]::OutputEncoding = $utf8NoBom
$OutputEncoding = $utf8NoBom
```

## 文档

- [docs/usage.md](docs/usage.md): 完整 CLI 用法、扫描规则、JSON 报告、CI 示例
- [docs/agent-utf8-guide.md](docs/agent-utf8-guide.md): 在 Codex 等 CLI agent 中避免中文乱码的实践

## 预设行为

`--preset active-source` 的范围是：

- `scripts`
- `pom.xml`
- 根目录下的 `.md` 文件
- 根目录下名称以 `xxx` 开头的目录

会跳过常见生成目录或工具目录，例如 `.git`、`.idea`、`.vscode`、`build`、`dist`、`node_modules`、`target`。