157 lines
5.6 KiB
Markdown
157 lines
5.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) | 限制文件读取规则 | 高 |
|
||
| [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` 进行类型检查
|