liaozhaorun/NewStock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 完善 QMT 交易模块文档和配置展示功能

Browse Source 
- 优化前端仪表盘界面
- 添加配置文件可视化展示
- 编写 QMT 模块配置文档
- 完善项目规则体系（KiloCode）
This commit is contained in:
liaozhaorun
2026-01-27 00:52:35 +08:00
parent 50ee1a5a0a
commit 4607555eaf
31 changed files with 5248 additions and 8621 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
.kilocode/rules/formatting.md Normal file
View File

@@ -0,0 +1,166 @@
# 代码格式化规则
本项目使用 Python 语言开发，以下是代码格式化规范。
## 缩进
- 使用 **4个空格** 进行缩进
- 不使用 Tab 字符
## 行长度
- 每行最大长度：**100 字符**
- 长的表达式可以换行，保持缩进一致
## 空行
- 类定义之间：**2个空行**
- 函数定义之间：**1个空行**
- 函数内部逻辑分段：**使用空行分隔逻辑块**
- 导入语句之后：**1个空行**
## 空格使用
```python
# 正确的写法
df = df.sort_values(by=["ts_code", "trade_date"])
result = (df["close"] - df["open"]) / (df["high"] - df["low"] + epsilon)
# 错误的写法
df=df.sort_values(by=["ts_code","trade_date"])
result=(df["close"]-df["open"])/(df["high"]-df["low"]+epsilon)
```
### 运算符周围
- 运算符两侧各加一个空格
- 括号内侧不加空格
```python
# 推荐
total_buy_vol = df["buy_sm_vol"] + df["buy_lg_vol"] + df["buy_elg_vol"]
# 不推荐
total_buy_vol=df["buy_sm_vol"]+df["buy_lg_vol"]+df["buy_elg_vol"]
```
### 函数调用
```python
# 推荐
df["atr_14"] = grouped.apply(
lambda x: pd.Series(
talib.ATR(x["high"].values, x["low"].values, x["close"].values, timeperiod=14),
index=x.index,
)
)
# 不推荐
df["atr_14"] = grouped.apply(lambda x: pd.Series(talib.ATR(x["high"].values, x["low"].values, x["close"].values, timeperiod=14), index=x.index))
```
## 括号
```python
# 推荐
conditions_winner = [
(df["close"] > df["cost_85pct"]) & (df["winner_rate"] > 0.8),
(df["close"] < df["cost_15pct"]) & (df["winner_rate"] < 0.2),
]
# 不推荐
conditions_winner = [(df["close"] > df["cost_85pct"]) & (df["winner_rate"] > 0.8), (df["close"] < df["cost_15pct"]) & (df["winner_rate"] < 0.2)]
```
## 字符串引号
- 使用 **双引号** `"` 作为字符串默认引号
- 字符串内部包含双引号时，使用单引号 `'`
- 多行字符串使用三引号 `"""` 或 `'''`
## 导入顺序
```python
# 1. 标准库
import numpy as np
import pandas as pd
# 2. 第三方库
import talib
# 3. 本地模块
from .utils import some_function
```
## 注释
### 行内注释
- 行内注释与代码之间间隔 **2个空格**
- 注释以大写字母开头
```python
epsilon = 1e-8 # 防止除零
```
### 块注释
- 用于复杂逻辑的说明
- 使用 `#` 而非 `"""`（后者用于 docstring）
```python
# 计算每只股票的滚动协方差
# 使用高成交量窗口和收盘价窗口
def calculate_rolling_cov(group):
return group["high"].rolling(window_high_volume).cov(group["vol"])
```
### TODO 注释
```python
# TODO: 这个因子需要优化，可能导致过拟合
# FIXME: 修复浮点数精度问题
```
## Docstring
为所有公共函数、类和模块编写 docstring：
```python
def calculate_risk_adjusted_return(df, days=1, method="ratio", lambda_=0.5, eps=1e-8):
"""
计算单只股票的风险调整收益。
参数：
- df: DataFrame，包含 'ts_code' 和 'close' 列
- days: 预测未来多少天的收益
- method: 'ratio' 或 'difference'
- lambda_: 风险惩罚系数
- eps: 防止除零的小常数
返回：
- 添加 'risk_adj_return' 列的 DataFrame
"""
pass
```
## 数据管道格式化
对于复杂的数据处理链，使用链式调用并适当换行：
```python
df = (
df.sort_values(by=["ts_code", "trade_date"])
.groupby("ts_code", group_keys=False)
.apply(lambda x: x["close"].pct_change().rolling(window=5).std())
)
```
## 异常处理
```python
try:
result = df["close"] / (df["high"] - df["low"])
except ZeroDivisionError:
result = 0
```

292
.kilocode/rules/naming_conventions.md Normal file
View File

@@ -0,0 +1,292 @@
# 命名约定规则
本项目定义了统一的命名规范，确保代码可读性和一致性。
## 文件命名
### Python 源文件
- 使用 **小写字母** 和 **下划线** (`snake_case`)
- 模块名应简洁明了
- 避免使用缩写
```python
# 推荐
factor_processor.py
data_process.py
utils.py
# 不推荐
factorproc.py
dataProcess.py
Util.py
```
### 目录命名
- 使用 **小写字母** 和 **下划线**
- 含义明确的目录名
```
# 推荐
main/factor/
main/utils/
main/data/update/
# 不推荐
main/Factor/
main/Utils/
main/data/Update/
```
### 配置文件
- 使用小写下划线命名
- 后缀明确（如 `.env`, `.yml`, `.yaml`）
```
.env
.gitignore
requirements.txt
```
## 变量命名
### 普通变量
- 使用 **小写下划线** (`snake_case`)
- 名称应表达变量的含义
- 避免无意义的单字母（循环变量除外）
```python
# 推荐
stock_code = "600519"
close_prices = df["close"]
rolling_mean = grouped["close"].rolling(window=5).mean()
# 不推荐
s = "600519"
c = df["close"]
rm = grouped["close"].rolling(window=5).mean()
```
### 常量
- 使用 **全大写** 和 **下划线** (`UPPER_SNAKE_CASE`)
- 定义在模块顶部或单独的常量文件
```python
# 推荐
WINDOW_SIZE = 20
EPSILON = 1e-8
DEFAULT_JOIN = "left"
# 不推荐
windowSize = 20
epsilon = 1e-8
default_join = "left"
```
### 临时变量
- 使用 **单下划线前缀** 表示临时变量
- 或使用有意义的临时变量名
```python
# 推荐
df["_temp_calc"] = df["close"] * 1.1
result = [x for x in _ if x > 0]
# 不推荐
df["temp"] = df["close"] * 1.1
result = [x for x in a if x > 0]
```
### 私有变量
- 使用 **双下划线前缀**（Python 名称修饰）
- 或单下划线前缀（约定私有）
```python
class FactorCalculator:
def __init__(self):
self._default_window = 20 # 约定私有
self.__internal_cache = {} # 名称修饰（更严格）
```
## 函数命名
### 公共函数
- 使用 **小写下划线** (`snake_case`)
- 动词开头，表达函数行为
```python
# 推荐
def get_rolling_factor(df):
pass
def calculate_moving_average(prices, window):
pass
def merge_with_industry_data(df, industry_df):
pass
# 不推荐
def rollingFactor(df): # 违反 snake_case
pass
def Factor(df): # 不清晰
pass
```
### 私有函数
- 使用 **单下划线前缀**
```python
def _internal_calculation(df):
"""内部计算函数，不对外暴露"""
pass
```
### 数据处理函数
```python
# 推荐：明确表达输入输出
def read_and_merge_h5_data(h5_filename, key, columns, df=None, join="left"):
pass
def load_factor_data(factor_type):
pass
def save_predictions(predictions, output_path):
pass
```
## 类命名
- 使用 **大驼峰命名** (`PascalCase`)
- 名词或名词短语
```python
# 推荐
class FactorCalculator:
pass
class DataProcessor:
pass
class StockAnalyzer:
pass
# 不推荐
class factorCalculator: # 违反 PascalCase
pass
class data_processor: # 违反 PascalCase
pass
```
## DataFrame 列命名
### 因子列
- 使用 **小写下划线**
- 清晰表达因子含义
- 分类变量使用 `cat_` 前缀
```python
# 推荐：因子
df["volume_change_rate"] # 成交量变化率
df["flow_lg_elg_intensity"] # 主力资金流强度
df["chip_concentration_range"] # 筹码集中度范围
# 推荐：分类变量
df["cat_is_positive"] # 是否正收益（0/1）
df["cat_volume_breakout"] # 成交量突破信号
df["cat_winner_price_zone"] # 获利盘价格区域
```
### 中间计算列
- 使用 **单下划线前缀** 表示临时列
```python
# 推荐
df["_is_positive"] = (df["pct_chg"] > 0).astype(int)
df["_pos_returns"] = df["pct_chg"].where(df["pct_chg"] > 0, 0)
# 不推荐
df["temp_positive"] = (df["pct_chg"] > 0).astype(int)
df["posRet"] = df["pct_chg"].where(df["pct_chg"] > 0, 0)
```
### 排名列
- 使用 `rank_` 前缀
```python
df["rank_act_factor1"] = df.groupby("trade_date")["act_factor1"].rank(ascending=False, pct=True)
```
### 通用后缀
| 后缀 | 含义 | 示例 |
|------|------|------|
| `_change` | 变化量 | `cost_support_15pct_change` |
| `_ratio` | 比值 | `flow_divergence_ratio` |
| `_accel` | 加速度 | `flow_lg_elg_accel` |
| `_spike` | 异常值 | `vol_spike` |
| `_std` | 标准差 | `vol_std_5` |
| `_ma` | 移动平均 | `maobv_6` |
| `_return` | 收益率 | `future_return` |
| `_volatility` | 波动率 | `volatility` |
## 股票相关术语缩写
| 缩写 | 全称 | 示例列名 |
|------|------|----------|
| `ts_code` | 股票代码 | - |
| `trade_date` | 交易日期 | - |
| `vol` | 成交量 | `vol` |
| `amount` | 成交额 | `amount` |
| `open` | 开盘价 | `open` |
| 最高价 | `high` | `high` |
| `low` | 最低价 | `low` |
| `close` | 收盘价 | `close` |
| `pct_chg` | 涨跌幅 | `pct_chg` |
| `turnover_rate` | 换手率 | `turnover_rate` |
| `circ_mv` | 流通市值 | `circ_mv` |
## 命名一致性检查
### 因子命名模式
```python
# 资金流因子
df["lg_elg_net_buy_vol"] # 大单+超大单净买入量
df["sm_net_buy_vol"] # 小单净买入量
df["flow_divergence_ratio"] # 资金流分歧比
# 筹码因子
df["chip_concentration_range"] # 筹码集中度
df["chip_skewness"] # 筹码偏度
df["floating_chip_proxy"] # 浮筹比例代理
# 收益因子
df["return_5"] # 5日收益率
df["return_20"] # 20日收益率
```
### 模型命名
```python
# 推荐
my_catboost_model.cbm
best_model.pth
# 不推荐
model1.cbm
final.pth
```

130
.kilocode/rules/restricted_files.md Normal file
View File

@@ -0,0 +1,130 @@
# 限制文件规则
本规则定义了项目中需要保护的文件和目录，这些文件不应被直接修改或删除。
## 禁止修改的文件
### 模型文件
- `**/*.cbm` - CatBoost 模型文件
- `**/*.pth` - PyTorch 模型检查点
- `**/best_model.pth` - 最佳模型文件
- `main/train/best_model.pth`
### 预测结果文件
- `**/predictions_*.tsv` - 预测结果文件
- `main/train/predictions_test.tsv`
- `main/train/predictions_train.tsv`
- `main/train/predictions.tsv`
- `main/train/test1.tsv`
- `main/train/test2.tsv`
- `predictions_test.tsv`
### 配置文件
- `.env` - 环境变量配置
- `.gitignore` - Git 忽略规则
## 禁止直接编辑的目录
### 模型训练输出目录
- `main/train/` - 模型训练输出目录
- 所有 `.pth` 文件
- 所有 `.tsv` 预测结果
- 所有 `.ipynb` 分析报告（需要时可通过 Jupyter 编辑）
### 数据文件目录
- `main/data/` - 数据文件目录
- 所有 `.ipynb` 数据处理笔记本（需通过 Jupyter 编辑）
- `update/` 子目录下的文件
### 模型文件
- `my_catboost_model.cbm` - CatBoost 训练好的模型
## 只读数据目录
以下目录包含只读数据，处理时需要特别注意：
```python
# 正确的读取方式
def load_data(filename):
data = pd.read_hdf(filename, key="data") # 使用 pandas 读取 HDF5
return data
# 错误的写入方式 - 不要修改源数据
def process_data(filename):
data = pd.read_hdf(filename, key="data")
data.to_hdf(filename, key="data") # 禁止！会覆盖源数据
```
## Jupyter Notebook 规则
### 允许的操作
- 在 `main/data/` 和 `main/train/` 目录下编辑 `.ipynb` 文件
- 运行 Notebook 进行数据分析
- 添加新的分析单元
### 禁止的操作
- 直接修改生成的模型文件
- 手动修改预测结果文件
## 保护机制
### 临时文件
临时计算产生的中间文件（如带前缀 `_` 的列）应在函数结束时清理：
```python
def get_factor(df):
old_columns = df.columns.tolist()[:]
# 临时计算
df["_temp_calc"] = df["close"] / df["open"]
# 清理临时列
cols_to_drop = ["_temp_calc"]
df.drop(columns=cols_to_drop, inplace=True, errors="ignore")
new_columns = [col for col in df.columns.tolist()[:] if col not in old_columns]
return df, new_columns
```
### 模型文件保护
模型文件只能通过训练脚本生成，禁止手动修改：
```python
# 正确：使用训练脚本
# python main/train/train_model.py
# 禁止：直接编辑模型文件
# 任何对 .pth, .cbm 文件的手动编辑都是不允许的
```
## 环境变量
以下环境变量在 `.env` 中定义，禁止硬编码：
- 数据库连接信息
- API 密钥
- 路径配置
如需使用这些变量，应通过 `os.getenv()` 或 `python-dotenv` 读取：
```python
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("API_KEY")
```
## 相关规则文件
读取限制规则已移至独立文件 [`restricted_reads.md`](restricted_reads.md)，包含禁止读取 config 文件和 JSON 文件的详细规则。

49
.kilocode/rules/restricted_reads.md Normal file
View File

@@ -0,0 +1,49 @@
# 禁止读取的文件
以下文件包含敏感信息或属于配置文件，**绝对禁止**以任何方式读取。
## 配置文件
包含 `config` 字符串的文件（不区分大小写）：
- `**/*config*` - 所有包含 config 的文件名
- `config.py`
- `app_config.py`
- `database_config.py`
- `config.json`
- `config.yaml`
- `config.yml`
- `my_config.py`
- `CONFIG.py`
- `AppConfig.json`
## JSON 文件
所有以 `.json` 结尾的文件：
- `**/*.json`
- `settings.json`
- `data.json`
- `output.json`
- `package.json`
- `tsconfig.json`
## 强制执行规则
### 无例外原则
- ❌ 禁止任何理由读取上述文件
- ❌ 即使任务无法完成也禁止读取
- ❌ 禁止使用任何变通方法读取
### 唯一例外
用户主动将文件内容上传至对话上下文（非文件读取工具）
### 错误处理
如果尝试读取上述文件，必须返回：
```
FileRestrictionError: 禁止读取文件: {路径}
原因: 文件名包含 'config' 或文件扩展名为 '.json'

122
.kilocode/rules/rule_formatting_guide.md Normal file
View File

@@ -0,0 +1,122 @@
# 规则编写指南
本指南定义了如何编写和格式化项目规则文件。
## 规则文件格式原则
### Markdown 格式
Custom rules can be written in plain text, but **Markdown format is recommended** for better structure and comprehension by the AI models.
### 结构要求
1. **使用 Markdown 标题** (`#`, `##`, etc.) 定义规则分类
2. **使用列表** (`-`, `*`) 枚举具体项目或约束
3. **使用代码块** (```) 包含代码示例
### 示例格式
```markdown
# 规则标题
规则描述...
## 具体规则
- 规则项目 1
- 规则项目 2
## 代码示例
```python
# 正确示例
def example():
pass
# 错误示例
def wrong():
pass
```
```
## 规则文件命名规范
- 使用小写下划线：`rule_name.md`
- 避免使用大写字母和空格
- 文件名应清晰表达规则内容
## 规则文件组织
### 核心规则文件
| 文件名 | 描述 |
|--------|------|
| `formatting.md` | 代码格式化规则 |
| `naming_conventions.md` | 命名约定规则 |
| `restricted_files.md` | 限制文件规则（修改限制） |
| `restricted_reads.md` | 读取限制规则 |
| `rule_formatting_guide.md` | 规则编写指南 |
### 规则索引
`rules_index.md` 提供所有规则的快速参考和链接。
## 规则内容结构
### 必要元素
1. **标题**：清晰描述规则主题
2. **描述**：说明规则的目的和作用
3. **具体规则**：使用列表形式枚举
4. **示例**：代码示例说明正确和错误的做法
### 可选元素
- **模式匹配**：使用表格说明匹配规则
- **注意事项**：补充说明和警告
- **相关规则**：指向其他相关规则文件的链接
## 禁止读取规则格式
对于定义禁止读取文件的规则，使用以下格式：
```markdown
# 禁止读取的文件
以下文件包含敏感信息，**绝对禁止**以任何方式读取。
## 配置文件
- `**/*config*` - 包含 config 的文件名
- `config.py`
- `app_config.py`
## JSON 文件
- `**/*.json`
- `settings.json`
- `data.json`
## 强制执行规则
- ❌ 禁止任何理由读取
- ❌ 即使任务无法完成也禁止
- 唯一例外：用户主动上传至上下文
```
## 更新规则时的注意事项
1. **保持格式一致**：遵循 Markdown 格式原则
2. **更新索引**：如果添加新规则，更新 `rules_index.md`
3. **添加示例**：为新规则提供清晰的代码示例
4. **版本控制**：重大变更应记录变更日志
## 验证清单
添加新规则前，检查以下项目：
- [ ] 使用 Markdown 格式
- [ ] 包含清晰的标题和描述
- [ ] 使用列表枚举具体规则
- [ ] 提供代码示例
- [ ] 更新规则索引（如需要）

135
.kilocode/rules/rules_index.md Normal file
View File

@@ -0,0 +1,135 @@
# 项目规则索引
本项目使用 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` 进行类型检查