136 lines
4.6 KiB
Markdown
136 lines
4.6 KiB
Markdown
# 项目规则索引
|
|
|
|
本项目使用 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) | 限制文件读取规则 | 高 |
|
|
| [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 结构
|
|
- **标题层级**：使用 `#`, `##` 等定义分类
|
|
- **列表枚举**：使用 `-`, `*` 枚举具体规则
|
|
- **代码示例**：使用 ``` 包含代码示例
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
NewStock/
|
|
├── .kilocode/
|
|
│ └── rules/
|
|
│ ├── formatting.md # 代码格式化规则
|
|
│ ├── naming_conventions.md # 命名约定规则
|
|
│ ├── restricted_files.md # 限制文件修改规则
|
|
│ ├── restricted_reads.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` 进行类型检查
|