NewStock/.kilocode/rules/formatting.md

代码格式化规则

本项目使用 Python 语言开发，以下是代码格式化规范。

缩进

• 使用 4个空格 进行缩进
• 不使用 Tab 字符

行长度

• 每行最大长度：100 字符
• 长的表达式可以换行，保持缩进一致

空行

• 类定义之间：2个空行
• 函数定义之间：1个空行
• 函数内部逻辑分段：使用空行分隔逻辑块
• 导入语句之后：1个空行

空格使用

# 正确的写法
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)

运算符周围

• 运算符两侧各加一个空格
• 括号内侧不加空格

# 推荐
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"]

函数调用

# 推荐
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))

括号

# 推荐
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)]

字符串引号

• 使用 双引号 " 作为字符串默认引号
• 字符串内部包含双引号时，使用单引号 '
• 多行字符串使用三引号 """ 或 '''

导入顺序

# 1. 标准库
import numpy as np
import pandas as pd

# 2. 第三方库
import talib

# 3. 本地模块
from .utils import some_function

注释

行内注释

• 行内注释与代码之间间隔 2个空格
• 注释以大写字母开头

epsilon = 1e-8  # 防止除零

块注释

• 用于复杂逻辑的说明
• 使用 # 而非 """（后者用于 docstring）

# 计算每只股票的滚动协方差
# 使用高成交量窗口和收盘价窗口
def calculate_rolling_cov(group):
    return group["high"].rolling(window_high_volume).cov(group["vol"])

TODO 注释

# TODO: 这个因子需要优化，可能导致过拟合
# FIXME: 修复浮点数精度问题

Docstring

为所有公共函数、类和模块编写 docstring：

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

数据管道格式化

对于复杂的数据处理链，使用链式调用并适当换行：

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())
)

异常处理

try:
    result = df["close"] / (df["high"] - df["low"])
except ZeroDivisionError:
    result = 0