assist/UTF8_ENCODING_STANDARD.md

UTF-8 编码规范

项目编码标准

本项目所有文件必须使用 UTF-8 编码格式，以确保中文和特殊字符的正确显示和处理。

文件编码要求

1. Python 文件

• 必须 在文件开头添加编码声明：

  # -*- coding: utf-8 -*-
  

  或

  # coding: utf-8
  

2. 文件保存

• 所有文件保存时使用 UTF-8 编码（无BOM）
• 禁止使用 GBK、GB2312 等其他编码格式

3. 文件读取/写入

• 所有文件操作必须明确指定 encoding='utf-8'：

  with open('file.txt', 'r', encoding='utf-8') as f:
      content = f.read()
  
  with open('file.txt', 'w', encoding='utf-8') as f:
      f.write(content)
  

Cursor/VS Code 配置

项目已配置 .vscode/settings.json，确保：

• 默认文件编码：UTF-8
• 自动检测编码：禁用（避免误判）
• 文件行尾：LF（Unix风格）

控制台输出

Windows 系统

在 Python 脚本中，需要设置标准输出编码：

import sys
import io

if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')

检查脚本

使用 check_encoding.py 脚本检查所有文件的编码格式：

python check_encoding.py

常见问题

1. 控制台输出乱码

• 确保文件以 UTF-8 保存
• 在脚本开头设置标准输出编码
• Windows 系统运行 chcp 65001 设置控制台代码页

2. 文件读取乱码

• 检查文件实际编码（可用 check_encoding.py）
• 确保使用 encoding='utf-8' 参数

3. 文件保存乱码

• 检查编辑器编码设置
• 确保 Cursor/VS Code 设置为 UTF-8

验证清单

创建新文件时，请确认：

• 文件以 UTF-8 编码保存
• Python 文件包含编码声明
• 文件读写操作指定 encoding='utf-8'
• 控制台输出脚本设置了 UTF-8 编码
• 测试输出中文显示正常