# UTF-8 编码规范

## 项目编码标准

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

## 文件编码要求

### 1. Python 文件
- **必须** 在文件开头添加编码声明：
  ```python
  # -*- coding: utf-8 -*-
  ```
  或
  ```python
  # coding: utf-8
  ```

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

### 3. 文件读取/写入
- 所有文件操作必须明确指定 `encoding='utf-8'`：
  ```python
  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 脚本中，需要设置标准输出编码：
```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` 脚本检查所有文件的编码格式：
```bash
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 编码
- [ ] 测试输出中文显示正常