Unicode 安全编码规范（项目执行版）

August 28, 2026 · View on GitHub

本文件是「Unicode 安全编码规范」在本仓库的执行细则。 生成或修改任何代码、配置、文档时，必须遵守本规范。 配套工具见 scripts/ 目录；仓库历史问题与根因见 SKILL.md 的「F. Windows/PowerShell 环境适配 → 已知陷阱与解决方案」。

总目标

内部统一使用 Unicode，外部文本数据统一优先使用 UTF-8， 所有编码边界显式声明编码，不依赖默认字符集，不进行无意义的重复转码。

硬性规定（15 条）

  1. 所有源码、配置文件、模板文件、JSON、CSV、日志和文本文件统一使用 UTF-8 编码。
  2. 不要依赖操作系统、IDE、运行环境或系统区域设置的默认字符集。
  3. 任何涉及字符串、文件、网络请求、HTTP、数据库、JSON 序列化/反序列化的地方，都必须明确使用 UTF-8。
  4. 禁止在没有明确需求的情况下使用 GBK、GB2312、ANSI、Latin-1、Windows-1252 等编码。
  5. 禁止出现 UTF-8 编码后再按 GBK、ANSI 或其他编码解码的情况。
  6. 文件读取和写入时，应显式指定 UTF-8，而不是使用默认编码。
  7. Web 页面统一声明 UTF-8，例如：<meta charset="UTF-8">
  8. HTTP 接口涉及文本内容时，应正确声明 UTF-8，例如：Content-Type: application/json; charset=utf-8
  9. 数据库应优先使用支持完整 Unicode 的字符集，例如 MySQL 使用 utf8mb4，同时确保数据库、表、字段和连接字符集保持一致。
  10. JSON 中的中文应正常作为 Unicode 字符处理，不要为了「防止乱码」而进行不必要的重复转码。
  11. 不要对已经是 Unicode 字符串的数据重复执行 encode/decode。
  12. 如果代码中存在 Base64、URL Encoding、HTML Entity、Unicode Escape 等编码操作，要明确区分「字符编码」和「数据转义」，不要混用。
  13. 修改已有项目时，先检查原有编码方式，避免因为强制转换造成已有数据损坏。
  14. 如果无法确定外部输入的字符编码，不要猜测，应在代码中增加明确的编码检测、参数配置或异常处理。
  15. 中文字符串、中文注释、中文文件名和中文接口数据都必须能够正确读取、存储、传输和显示。

Shell 选择规则（先探测系统参数）

  • 任何涉及命令行执行的任务，第一步先运行 python scripts/detect_env.py 获取当前系统参数并保存到 .zerotoken/environment.json（7 天有效期）。
  • Windows 系统一律使用 PowerShell 语法（; 链式 / if ($?) {} 条件链式）， 禁用 bash；PowerShell 版本以保存的探测结果为准 （5.1 Desktop 与 7+ Core 的编码默认行为不同）。
  • Linux/macOS 使用 sh/bash/zsh 等 POSIX shell，不套用 PowerShell 规避规则。
  • 中文支持能力以探测结果 console.cjk_capable 为准：不支持时内容验证走文件而非终端显示。

编码链路检查

生成代码前，检查整个字符处理链路，确保每一个环节的编码一致：

输入数据 → 字符串处理 → 文件/数据库 → 网络传输 → API → 前端/终端显示

项目执行细则

Python 文件读写

  • 所有 open() 必须显式指定编码：读取用 open(path, 'rb') 二进制读后显式 decode， 或 open(path, 'r', encoding='utf-8')；写入一律 open(path, 'w', encoding='utf-8')。
  • 禁止 errors='replace' 静默替换损坏字符（会把中文无声变成 U+FFFD 替换字符）。 编码无法确定时必须显式抛错提示先检查原编码： 统一实现见 scripts/safe_io.py 的 sniff_encoding / decode_bytes （BOM → UTF-8 → GB18030，全部失败抛 UnknownEncodingError）。
  • 读取历史遗留文件（可能为 UTF-16 或 GB18030）用 scripts/safe_io.py 的 safe_read， 它会自动检测 BOM 并做安全解码；写入统一 UTF-8 无 BOM（safe_write / safe_append）。

控制台输出（Windows 中文环境）

  • Python 3.7+：模块加载时显式 sys.stdout.reconfigure(encoding='utf-8') （sys.stderr 同理），不要依赖系统代码页（中文 Windows 默认 GBK/936）。
  • 兜底：无法重配置的流用 safe_print（scripts/safe_io.py），保证永不抛 UnicodeEncodeError。
  • 终端显示：PowerShell 中配合 chcp 65001 查看中文输出；若仍乱码，属于终端显示层 问题，文件本身编码正确，用 read_file 工具验证内容。
  • 读取附件/文件：Windows PowerShell 5.1 的 Get-Content 默认按 ANSI 代码页（GBK） 解码无 BOM 的 UTF-8 文件，含中文的附件会显示乱码（如 鐗堟湰鍙?1.9.1），但文件 未损坏。优先用 read_file 工具读取；必须在 PowerShell 中读时显式指定 Get-Content -Encoding UTF8；附件是 GBK/UTF-16 等非 UTF-8 编码时用 safe_io.safe_read() 自动检测转码。显示乱码≠文件损坏，禁止据此盲目转码。
  • 禁止用 PowerShell Add-Content 向 UTF-8 文件追加中文（默认 GBK 写入会污染）， 改用 Python open(path, 'a', encoding='utf-8') 或 safe_io.safe_append。

文件写入编码矩阵（PS 5.1 实测）

写入方式默认编码显式 -Encoding UTF8结论
Set-ContentGBK/ANSI；非 GBK 字符静默写成 ?（emoji 实测变 3F）UTF-8 带 BOM❌ 禁止用于任何非 ASCII 内容
Add-Content同上（追加即污染 UTF-8 文件）；且目标不以换行结尾时不补换行导致粘连带 BOM + 同样不补换行❌ 禁止追加中文，统一用 safe_io.safe_append()
Out-File / > 重定向UTF-16 LE（带 BOM）UTF-8 带 BOM⚠️ 非 ASCII 时禁用默认行为
[IO.File]::WriteAllText / AppendAllTextUTF-8 无 BOM（.NET Core 3.0+/PS7 默认；5.1 下建议显式传编码）—✅ PowerShell 内首选
  • PowerShell 中确需直接写 UTF-8 文本时统一用： [IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))。
  • 跨脚本、含中文/emoji 的写入一律走 Python：safe_io.safe_write()（UTF-8 无 BOM + LF）/ safe_append()（自动补换行）。

PowerShell 脚本（.ps1）

  • 唯一例外：.ps1 文件必须使用 UTF-8 with BOM。 原因：Windows PowerShell 5.1（系统自带）对无 BOM 文件按 ANSI 代码页（GBK）解码， 含中文的 UTF-8 无 BOM 脚本会乱码甚至解析异常。 PowerShell 7+ 无此问题，但为兼容 5.1 统一带 BOM。
  • 已由 scripts/init_env.ps1 示范（首字节 EF BB BF）。

Node.js / HTTP

  • 请求头/响应头显式声明编码，例如 'Content-Type': 'application/json; charset=utf-8'。
  • fetch / readFileSync / writeFileSync 显式传 'utf-8'；JSON.stringify 默认 保留 Unicode（不要 escape 转义中文）。
  • URL 编码、Base64、HTML Entity 属于数据转义，与字符编码无关，不得混用。

JSON

  • 中文作为普通 Unicode 字符处理：Python 用 json.dumps(data, ensure_ascii=False)， 写入文件时 encoding='utf-8'；不要为了「防乱码」做重复转码。

数据库

  • 如引入数据库，使用 utf8mb4，并确保数据库、表、字段、连接字符集一致。

仓库现有工具链

工具用途
scripts/safe_io.py编码检测核心（sniff_encoding/decode_bytes）+ 安全读写（read_text/safe_read/safe_write/safe_append/write_result），safe_print 控制台兜底；unknown 显式抛 UnknownEncodingError
scripts/fix_encoding.py扫描/转换文件编码为 UTF-8（scan / preview / convert / check-replacement）
scripts/detect_gbk_contamination.py检测并修复 UTF-8 文件中的 GBK 污染（scan / inspect / fix）
scripts/batch_edit.py一次多编辑（原子替换），复用 safe_io.read_text，不静默损坏
scripts/verify_output.py验证结果写入 UTF-8 文件（替代 print），grep_check 显式解码
scripts/audit_encoding.py全项目编码审计（UTF-8/BOM/替换字符/混合换行）
scripts/detect_env.py环境探测与持久化：OS / Shell / 控制台编码 / 中文支持 / PowerShell 版本 / Git quotepath，结果存 .zerotoken/environment.json（7 天有效期），决定 F/G 模式与 Shell 选择
scripts/init_env.ps1Windows 环境初始化（git quotepath、控制台 UTF-8、编码健康检查）

生成代码后的安全检查

每次生成/修改代码后，额外执行一次：

python scripts/audit_encoding.py --root . --out audit_result.txt

确认：

  1. 无 non-utf8 文件；
  2. 无 替换字符（U+FFFD）；
  3. 无混合换行（LF/CRLF 混用）；
  4. .ps1 文件带 BOM（审计单独列 utf-8-sig 属预期）。