# 项目规则索引

本项目使用 KiloCode 的自定义规则系统来维护代码质量和一致性。所有规则文件存储在 `.kilocode/rules/` 目录下。

## 规则概览

| 规则文件 | 描述 | 优先级 |
|----------|------|--------|
| [formatting.md](formatting.md) | 代码格式化规范 | 高 |
| [naming_conventions.md](naming_conventions.md) | 命名约定规范 | 高 |
| [restricted_files.md](restricted_files.md) | 限制文件修改规则 | 高 |
| [restricted_reads.md](restricted_reads.md) | 限制文件读取规则 | 高 |
| [interaction_rules.md](interaction_rules.md) | 交互限制规则 | 高 |
| [requirement_review.md](requirement_review.md) | 代码修改需求审查规则 | 高 |
| [rule_formatting_guide.md](rule_formatting_guide.md) | 规则编写指南 | 中 |

## 规则说明

### 1. 代码格式化规则 [formatting.md](formatting.md)

定义项目代码的格式化标准，包括：

- **缩进**：使用 4 个空格
- **行长度**：每行最大 100 字符
- **空行**：类间 2 空行，函数间 1 空行
- **空格**：运算符两侧各一个空格
- **导入顺序**：标准库 → 第三方库 → 本地模块
- **注释**：行内注释距代码 2 空格
- **Docstring**：为所有公共函数、类编写

### 2. 命名约定规则 [naming_conventions.md](naming_conventions.md)

定义项目命名规范：

- **文件命名**：小写下划线 (`snake_case`)
- **变量命名**：小写下划线
- **常量命名**：全大写下划线 (`UPPER_SNAKE_CASE`)
- **函数命名**：小写下划线，动词开头
- **类命名**：大驼峰 (`PascalCase`)
- **DataFrame 列命名**：因子列、分类变量、中间计算列的规范
- **股票术语缩写**：统一使用的缩写标准

### 3. 限制文件规则 [restricted_files.md](restricted_files.md)

定义需要保护的文件和目录：

- **禁止修改**：模型文件 (`.cbm`, `.pth`)、预测结果 (`.tsv`)、配置文件 (`.env`)
- **只读数据**：数据文件目录
- **Jupyter Notebook 规则**：编辑流程规范
- **保护机制**：临时文件清理规则

### 4. 读取限制规则 [restricted_reads.md](restricted_reads.md)

定义禁止读取的文件类型：

- **配置文件**：包含 `config` 字符串的文件（不区分大小写）
- **JSON 文件**：所有以 `.json` 结尾的文件
- **强制执行**：无例外原则，禁止任何方式的读取

### 5. 规则编写指南 [rule_formatting_guide.md](rule_formatting_guide.md)

指导如何编写新的规则文件：

- **Markdown 格式**：推荐使用 Markdown 结构
- **标题层级**：使用 `#`, `##` 等定义分类
- **列表枚举**：使用 `-`, `*` 枚举具体规则
- **代码示例**：使用 ``` 包含代码示例

### 6. 交互限制规则 [interaction_rules.md](interaction_rules.md)

定义与用户交互时的行为限制：

- **代码编写**：必须先询问用户，获得许可后才能编写代码
- **命令执行**：必须先询问用户，获得许可后才能执行命令
- **询问内容**：明确说明将要执行的操作、目的和影响

### 7. 代码修改需求审查规则 [requirement_review.md](requirement_review.md)

规范代码修改前的需求审查流程：

- **修改前检查**：检查模块目录下是否存在需求md文件
- **修改范围控制**：只修改任务要求的功能相关代码
- **变更影响评估**：发现可能影响其他功能的改动时先与用户确认
- **例外情况**：语法错误、代码格式化、性能优化可小幅调整

## 项目结构

```
NewStock/
├── .kilocode/
│   └── rules/
│       ├── formatting.md             # 代码格式化规则
│       ├── naming_conventions.md     # 命名约定规范
│       ├── restricted_files.md       # 限制文件修改规则
│       ├── restricted_reads.md       # 限制文件读取规则
│       ├── interaction_rules.md      # 交互限制规则
│       ├── requirement_review.md       # 代码修改需求审查规则
│       └── rule_formatting_guide.md  # 规则编写指南
├── main/
│   ├── factor/                       # 因子计算模块
│   ├── train/                        # 训练模块
│   ├── utils/                        # 工具模块
│   └── data/                         # 数据文件
├── qmt/                              # QMT 交易模块
├── my_catboost_model.cbm             # 训练好的模型
└── .env                              # 环境配置
```

## 快速参考

### Python 代码示例

```python
import numpy as np
import pandas as pd

WINDOW_SIZE = 20
EPSILON = 1e-8

class FactorCalculator:
    """因子计算器"""
    
    def get_rolling_factor(self, df):
        """计算滚动因子"""
        # 代码始终遵循格式化规则
        result = (
            df.sort_values(by=["ts_code", "trade_date"])
            .groupby("ts_code", group_keys=False)
        )
        return result
```

### 变量命名检查

| 类型 | 正确示例 | 错误示例 |
|------|----------|----------|
| 变量 | `close_prices` | `closePrices` |
| 常量 | `MAX_WINDOW` | `MaxWindow` |
| 函数 | `get_factor()` | `GetFactor()` |
| 类 | `StockAnalyzer` | `stock_analyzer` |
| 列 | `flow_lg_elg_intensity` | `flowLgElgIntensity` |

## 规则更新

当项目需要调整规则时：

1. 修改 `.kilocode/rules/` 下的对应 `.md` 文件
2. 更新本索引文件的规则说明
3. 通知团队成员规则变更
4. 运行代码检查工具验证规则一致性

## 相关工具

- **代码格式化**：使用 `black` 格式化工具
- **代码检查**：使用 `flake8` 进行静态分析
- **类型检查**：使用 `mypy` 进行类型检查