# MineNASAI 项目规则

## 编码规范

- **文件编码**: UTF-8
- **文件名编码**: UTF-8
- **控制台输出**: UTF-8
- 所有文件和目录必须使用 UTF-8 编码

### PowerShell 终端编码设置

在使用前请先设置编码：

```powershell
# 方法1: 切换代码页
chcp 65001

# 方法2: PowerShell 编码设置
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
$PSDefaultParameterValues['*:Encoding'] = 'utf8'
```

或在 PowerShell 配置文件中永久设置（`$PROFILE`）：

```powershell
# 编辑配置文件
notepad $PROFILE

# 添加以下内容
$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
```

## 代码规范

- 使用中文交流
- 函数添加必要注释
- 如有进度文档注意维护进度

## 文档生成规则

### ⚠️ 重要：仅在明确需要时生成文档

**禁止**：
- 一次性生成大量文档
- 过度规划和文档化
- 在没有明确需求时创建文档

**允许**：
- 用户明确要求时生成文档
- 关键设计决策需要记录时
- 进度跟踪需要时

### 文档命名规范

**必须使用中文命名**：
- ✅ `项目分析.md`
- ✅ `开发步骤.md`
- ✅ `进度跟踪.md`
- ❌ `PROJECT-ANALYSIS.md`
- ❌ `DEVELOPMENT-STEPS.md`
- ❌ `PROGRESS.md`

**文档类型**：
- 设计文档：`设计-[主题].md`
- 技术方案：`方案-[主题].md`
- 问题记录：`问题-[描述].md`
- 进度跟踪：`进度.md`

## 工作方式

### 优先级

1. **解决实际问题** - 专注于编码和实现
2. **简洁沟通** - 直接回答问题，不要长篇大论
3. **按需文档** - 只在需要时才写文档

### 代码优先

- 先写代码，后写文档
- 用代码示例代替长篇解释
- 实践验证优于理论规划

### 避免过度设计

- 不要一次性规划太多
- 先实现 MVP，再迭代优化
- 遇到问题再解决，不要提前过度设计

## Python 代码规范

- Python 3.11+
- 类型注解（使用 type hints）
- Docstring（简洁的中文说明）
- 测试覆盖关键功能

## Git 提交规范

使用中文提交信息：
- `feat: 添加xxx功能`
- `fix: 修复xxx问题`
- `docs: 更新文档`
- `refactor: 重构xxx`
- `test: 添加测试`

## 注意事项

- 维护 `进度.md` 文件记录关键进展
- 重大技术决策需要记录理由
- 遇到问题优先查看现有代码和文档
- 不确定时先问，再动手