qka 1.3.1.dev5__tar.gz → 1.4.1.dev3__tar.gz

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.3.1.dev5
+Version: 1.4.1.dev3
 Summary: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Documentation, https://zsrl.github.io/qka
@@ -46,6 +46,7 @@ Requires-Dist: mcp[cli]>=1.9.0
 Requires-Dist: nbformat>=5.10.4
 Requires-Dist: plotly>=6.1.1
 Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: ta>=0.11.0
 Requires-Dist: tqdm>=4.67.1
 Requires-Dist: uvicorn>=0.34.3
 Requires-Dist: websockets>=16.0

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/docs/getting-started/concepts.md

@@ -44,11 +44,11 @@ Data ──> Backtest.run() ──> dask 分区迭代 ──> Strategy.on_bar(da
 
 ---
 
-## 关键抽象
+## 核心抽象
 
 ### `DataAccessor` — 滚动窗口数据访问器
 
-DataAccessor 是策略访问数据的中枢。它在回测过程中维护一个滚动窗口缓存：
+DataAccessor 是策略访问数据的中枢。它在回测过程中维护一个滚动窗口缓存，支持三种查询方式：
 
 ```
                         push(date, 'close', {symbol: value})
@@ -58,20 +58,24 @@ DataAccessor 是策略访问数据的中枢。它在回测过程中维护一个
            │      DataAccessor 内部缓存            │
            │                                      │
            │   close: {                            │
-           │     '000001.SZ': deque(maxlen=250),   │
-           │     '600000.SH': deque(maxlen=250),   │
+           │     '000001.SZ': deque(maxlen=750),   │
+           │     '600000.SH': deque(maxlen=750),   │
            │     ...                               │
            │   }                                   │
            │   volume: { ... }                     │
+           │   sma_20: { ... }      ← 预计算指标   │
+           │   rsi_14: { ... }                     │
            └─────────────────────────────────────┘
-                    │               │
-                    ▼               ▼
-            self.get()        self.history()
-            (横截面)          (时间序列)
+              │        │              
+              ▼        ▼              
+        self.get()  self.history()
+        (横截面)    (时间序列)
 ```
 
 #### `self.get(factor)` — 横截面数据
 
+#### `self.get(factor)` — 横截面数据
+
 返回**当前 bar** 所有股票的某个因子值：
 
 ```python
@@ -95,6 +99,66 @@ hist = self.history('close', 20)
 # ...              ...        ...        ...
 ```
 
+### 预计算技术指标（Data 层面）
+
+技术指标在数据层预计算，作为额外的列存在于合并 DataFrame 中，策略中直接通过 `self.get()` 和 `self.history()` 查询。
+
+#### 在 Data 中声明
+
+```python
+data = Data(
+    symbols=['000001.SZ', '600000.SH'],
+    indicators={
+        'sma_20': ('sma', 20),         # 20 日均线
+        'ema_14': ('ema', 14),         # 14 日指数均线
+        'rsi_14': ('rsi', 14),         # 14 日 RSI
+        'macd': ('macd', 12, 26, 9),   # MACD（生成 3 列）
+        'bbands': ('bbands', 20, 2),   # 布林带（生成 3 列）
+    }
+)
+```
+
+指标在数据加载时一次性预计算，每只股票会增加对应的列：
+
+```
+合并后列名格式：{symbol}_{指标名}
+例如：000001.SZ_sma_20, 000001.SZ_macd, 000001.SZ_macd_signal
+```
+
+#### 在策略中使用
+
+```python
+def on_bar(self, date):
+    # 直接取横截面（不用每 bar 现算）
+    sma_20 = self.get('sma_20')
+    price = self.get('close')
+    
+    # 历史数据同样支持
+    macd_hist = self.history('macd', 10)
+    bb_upper_hist = self.history('bbands_upper', 5)
+```
+
+#### 支持的指标
+
+| 指标名 | 参数 | 生成列 | 备注 |
+|--------|------|--------|------|
+| `sma` | `(length)` | `sma_20` | 简单移动平均 |
+| `ema` | `(length)` | `ema_14` | 指数移动平均 |
+| `wma` | `(length)` | `wma_30` | 加权移动平均 |
+| `rsi` | `(length)` | `rsi_14` | 相对强弱指数 |
+| `macd` | `(fast, slow, signal)` | `macd`, `macd_signal`, `macd_histogram` | 指数平滑异同 |
+| `bbands` | `(length, std)` | `bbands_upper`, `bbands_middle`, `bbands_lower` | 布林带 |
+| `atr` | `(length)` | `atr_14` | 平均真实波幅 |
+
+可指定自定义因子列：`('sma', 'high', 20)` 表示对 `high` 列计算 SMA。
+
+#### 对比：预计算 vs 动态计算
+
+| 方式 | 性能 | 策略代码简洁度 | 历史数据支持 |
+|------|------|---------------|-------------|
+| **预计算（推荐）** | 一次算好，各 bar 复用 | `self.get('sma_20')` | ✅ `self.history('sma_20', 20)` |
+| 动态计算（旧方式） | 每 bar 重复算 | `self.ta.sma('close', length=20)` | ❌ 需额外逻辑 |
+
 ---
 
 ### `Broker` — 虚拟经纪商

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/docs/getting-started/first-strategy.md

@@ -55,10 +55,17 @@ class BuyAndHold(Strategy):
 |------|------|------|
 | `self.get('close')` | 当前 bar 所有股票收盘价 | `pd.Series`（index=股票代码） |
 | `self.history('close', 20)` | 过去 N 日收盘价历史 | `pd.DataFrame`（行=日期，列=股票代码） |
+| `self.get('sma_20')` | 预计算的 20 日均线 | `pd.Series` |
+| `self.history('sma_20', 10)` | 过去 10 日 SMA 历史 | `pd.DataFrame` |
 
 !!! tip "不再是闭包"
     与旧版本不同，`on_bar` 不再接收 `get` 参数。所有数据通过 `self.get()` 和 `self.history()` 访问，代码更简洁一致。
 
+!!! tip "技术指标预计算"
+    技术指标在 `Data` 层通过 `indicators=...` 预计算，作为额外的列加载。
+    策略中直接用 `self.get('sma_20')` 获取，无需每 bar 动态计算。
+    详见 [核心概念 - 预计算技术指标](concepts.md)。
+
 ---
 
 ## 步骤 3：运行回测
@@ -192,6 +199,67 @@ class MaCross(Strategy):
                 self.bought = False
 ```
 
+## 进阶 2：用预计算指标实现 RSI 策略
+
+在 `Data` 中声明需要预计算的指标，策略中直接使用：
+
+```python
+from qka import Data, Strategy, Broker, Backtest
+
+class RsiStrategy(Strategy):
+    """RSI 超卖买入，超买卖出"""
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        rsi = self.get('rsi_14')
+        if close is None or close.empty or rsi is None or rsi.empty:
+            return
+
+        for sym in close.index:
+            if sym not in rsi.index:
+                continue
+            price = float(close[sym])
+            if price <= 0:
+                continue
+
+            if rsi[sym] < 30 and sym not in self.broker.positions:
+                # RSI 低于 30，超卖，买入
+                self.broker.buy(sym, price, 100)
+            elif rsi[sym] > 70 and sym in self.broker.positions:
+                # RSI 高于 70，超买，卖出
+                pos = self.broker.positions[sym]
+                self.broker.sell(sym, price, pos['size'])
+
+# 在 Data 中声明指标
+data = Data(
+    symbols=['000001.SZ', '600000.SH'],
+    indicators={
+        'rsi_14': ('rsi', 14),        # 预计算 14 日 RSI
+        'sma_20': ('sma', 20),         # 同时预计算 20 日均线
+    },
+)
+bt = Backtest(data, RsiStrategy())
+bt.run()
+bt.summary()
+```
+
+支持的所有预计算指标：
+
+| 指标名 | 声明方式 | 策略中获取 | 多输出列 |
+|--------|---------|-----------|---------|
+| SMA | `('sma', 20)` | `self.get('sma_20')` | — |
+| EMA | `('ema', 14)` | `self.get('ema_14')` | — |
+| RSI | `('rsi', 14)` | `self.get('rsi_14')` | — |
+| ATR | `('atr', 14)` | `self.get('atr_14')` | — |
+| MACD | `('macd', 12, 26, 9)` | `self.get('macd')` | 额外生成 `macd_signal`, `macd_histogram` |
+| BBANDS | `('bbands', 20, 2)` | `self.get('bbands_upper')` | 额外生成 `bbands_middle`, `bbands_lower` |
+
+> **预计算 vs 动态计算**：预计算在数据加载阶段一次性算好所有指标的完整序列。策略中每根 bar 拿到的既是当前值，也能查历史（`self.history('rsi_14', 10)`）。动态计算每 bar 重新算一遍，性能差且历史不可查。**始终使用预计算。**
+```
+
 ---
 
 ## 下一步

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/docs/user-guide/data.md

@@ -87,6 +87,66 @@ data = Data(
 
 ---
 
+## 预计算技术指标
+
+通过 `indicators` 参数一键声明技术指标，数据加载时自动预计算：
+
+```python
+from qka import Data
+
+data = Data(
+    symbols=['000001.SZ', '600000.SH'],
+    indicators={
+        'sma_20': ('sma', 20),           # 20 日均线
+        'sma_60': ('sma', 60),           # 60 日均线
+        'ema_14': ('ema', 14),           # 14 日指数均线
+        'rsi_14': ('rsi', 14),           # 14 日 RSI
+        'macd': ('macd', 12, 26, 9),     # MACD
+        'bbands': ('bbands', 20, 2),     # 布林带
+        'atr_14': ('atr', 14),           # 平均真实波幅
+    }
+)
+lazy = data.get(lazy=True)
+# 合并后的列：... 000001.SZ_sma_20, 000001.SZ_rsi_14, 000001.SZ_macd, ...
+```
+
+指标列跟 `close`、`volume` 一样，在策略中通过 `self.get()` 和 `self.history()` 访问：
+
+```python
+# 策略中
+sma_20 = self.get('sma_20')                    # 横截面
+macd_hist = self.history('macd', 10)           # 历史序列
+bb_upper = self.get('bbands_upper')            # 布林带上轨
+rsi_14 = self.get('rsi_14')                    # 当前 RSI
+```
+
+### 与 `factor` 的区别
+
+| | `factor` | `indicators` |
+|--|----------|-------------|
+| 适用场景 | 任意自定义计算 | 标准技术指标（SMA、MACD 等） |
+| 写法 | Python 函数 | 声明式字典 |
+| 多输出 | 手动添加多列 | 自动展开（MACD 生成 3 列） |
+| 底层 | 任意 pandas 逻辑 | 基于 `ta` 库 |
+
+二者可以同时使用，`indicators` 在 `factor` 之后执行。
+
+### 支持的指标
+
+| 指标名 | 参数 | 说明 | 生成列 |
+|--------|------|------|--------|
+| `sma` | `(length)` | 简单移动平均 | `sma_20` |
+| `ema` | `(length)` | 指数移动平均 | `ema_14` |
+| `wma` | `(length)` | 加权移动平均 | `wma_30` |
+| `rsi` | `(length)` | 相对强弱指数 | `rsi_14` |
+| `macd` | `(fast, slow, signal)` | 指数平滑异同 | `macd`, `macd_signal`, `macd_histogram` |
+| `bbands` | `(length, std)` | 布林带 | `bbands_upper`, `bbands_middle`, `bbands_lower` |
+| `atr` | `(length)` | 平均真实波幅 | `atr_14` |
+
+可指定自定义因子列：`('sma', 'high', 20)` 表示对 `high` 列计算 20 日均线。
+
+---
+
 ## 数据格式
 
 `Data.get()` 返回的 DataFrame 列名格式为 `{symbol}_{factor}`：

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
     "baostock>=0.8.9",
     "litellm>=1.81.14",
     "websockets>=16.0",
+    "ta>=0.11.0",
 ]
 
 [project.optional-dependencies]

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/qka/core/data.py

@@ -20,13 +20,15 @@ class Data():
     """
     数据管理类
     
-    负责股票数据的获取、缓存和管理，支持多数据源、并发下载和自定义因子计算。
+    负责股票数据的获取、缓存和管理，支持多数据源、并发下载、自定义因子计算
+    以及预计算技术指标。
     
     Attributes:
         symbols (List[str]): 股票代码列表
         period (str): 数据周期，如 '1d'、'1m' 等
         adjust (str): 复权方式，如 'qfq'、'hfq'、'bfq'
         factor (Callable): 因子计算函数
+        indicators (dict): 预计算技术指标，col_name → (ind_type, *args)
         source (str): 数据源，如 'baostock'（默认）、'akshare'、'qmt'
         pool_size (int): 并发下载线程数
         datadir (Path): 数据缓存目录
@@ -41,7 +43,8 @@ class Data():
         factor: Callable[[pd.DataFrame], pd.DataFrame] = lambda df: df,
         source: str = 'baostock',
         pool_size: int = 10,
-        datadir: Optional[Path] = None
+        datadir: Optional[Path] = None,
+        indicators: Optional[dict] = None,
     ):
         """
         初始化数据对象
@@ -53,12 +56,19 @@ class Data():
             factor: 因子计算函数，接收 DataFrame 返回 DataFrame，用于扩展自定义因子
             source: 数据来源，'baostock'（默认）、'akshare'、'qmt'
             pool_size: 并发下载线程数
-            datadir: 缓存根目录，默认为当前工作目录下的 datadir/
+            datadir: 缓存目录路径
+            indicators: 预计算技术指标，格式为 {列名: (指标名, *参数)}
+                        示例：{'sma_20': ('sma', 20), 'rsi_14': ('rsi', 14),
+                              'macd': ('macd', 12, 26, 9)}
+                        指标名支持：sma、ema、wma、rsi、macd、bbands、atr
+                        factor 默认为 'close'，多因子指标（如 bbands、atr）
+                        使用标准列名 high/low/close
         """
         self.symbols = symbols or []
         self.period = period
         self.adjust = adjust
         self.factor = factor
+        self.indicators = indicators or {}
         self.source = source
         self.pool_size = pool_size
 
@@ -181,6 +191,7 @@ class Data():
                     continue
                 ddf = dd.read_parquet(str(parquet_path))
                 ddf = self.factor(ddf)
+                ddf = self._apply_indicators(ddf)
                 column_mapping = {col: f'{symbol}_{col}' for col in ddf.columns}
                 dfs.append(ddf.rename(columns=column_mapping))
 
@@ -204,6 +215,7 @@ class Data():
                     continue
                 df = dd.read_parquet(str(parquet_path))
                 df = self.factor(df)
+                df = self._apply_indicators(df)
                 column_mapping = {col: f'{symbol}_{col}' for col in df.columns}
                 dfs.append(df.rename(columns=column_mapping))
 
@@ -217,6 +229,92 @@ class Data():
             self._cached = ddf.compute()
             return self._cached
 
+    def _apply_indicators(self, df: 'pd.DataFrame'):
+        """
+        对单只股票的数据计算预定义的技术指标。
+
+        Args:
+            df: 单只股票的 DataFrame
+
+        Returns:
+            DataFrame: 包含原始列和指标列
+        """
+        if not self.indicators:
+            return df
+
+        if isinstance(df, dd.DataFrame):
+            return df.map_partitions(
+                lambda partition: self._compute_indicator_cols(partition.copy())
+            )
+        return self._compute_indicator_cols(df.copy())
+
+    def _compute_indicator_cols(self, df):
+        """在 pandas DataFrame 上计算技术指标列（单只股票）。"""
+        import ta as _ta_lib
+
+        for col_name, spec in self.indicators.items():
+            # 统一解析：spec = (indicator_name, *args)
+            if isinstance(spec, (list, tuple)):
+                ind_type = spec[0]
+                args = list(spec[1:])
+            else:
+                raise TypeError(f"指标规格必须为元组，got {type(spec)}")
+
+            # 如果第一个参数是字符串，视为列名；否则默认为 'close'
+            factor = 'close'
+            rest = args
+            if args and isinstance(args[0], str):
+                factor = args[0]
+                rest = args[1:]
+
+            if ind_type == 'sma':
+                window = int(rest[0]) if rest else 20
+                df[col_name] = _ta_lib.trend.sma_indicator(df[factor], window=window)
+
+            elif ind_type == 'ema':
+                window = int(rest[0]) if rest else 30
+                df[col_name] = _ta_lib.trend.ema_indicator(df[factor], window=window)
+
+            elif ind_type == 'wma':
+                window = int(rest[0]) if rest else 30
+                df[col_name] = _ta_lib.trend.wma_indicator(df[factor], window=window)
+
+            elif ind_type == 'rsi':
+                window = int(rest[0]) if rest else 14
+                df[col_name] = _ta_lib.momentum.rsi(df[factor], window=window)
+
+            elif ind_type == 'macd':
+                fast = int(rest[0]) if len(rest) >= 1 else 12
+                slow = int(rest[1]) if len(rest) >= 2 else 26
+                signal = int(rest[2]) if len(rest) >= 3 else 9
+                _macd = _ta_lib.trend.MACD(
+                    df[factor], window_slow=slow, window_fast=fast, window_sign=signal,
+                )
+                df[col_name] = _macd.macd()
+                df[f'{col_name}_signal'] = _macd.macd_signal()
+                df[f'{col_name}_histogram'] = _macd.macd_diff()
+
+            elif ind_type == 'bbands':
+                window = int(rest[0]) if rest else 20
+                std = int(rest[1]) if len(rest) >= 2 else 2
+                _bb = _ta_lib.volatility.BollingerBands(
+                    df[factor], window=window, window_dev=std,
+                )
+                df[f'{col_name}_upper'] = _bb.bollinger_hband()
+                df[f'{col_name}_middle'] = _bb.bollinger_mavg()
+                df[f'{col_name}_lower'] = _bb.bollinger_lband()
+
+            elif ind_type == 'atr':
+                window = int(rest[0]) if rest else 14
+                df[col_name] = _ta_lib.volatility.average_true_range(
+                    df['high'], df['low'], df['close'], window=window,
+                )
+
+            else:
+                logger.warning(f"未知指标类型: {ind_type}，跳过 {col_name}")
+
+        return df
+
     def _get_from_akshare(self, symbol: str) -> pd.DataFrame:
         """
         从 akshare 获取单个股票的数据。

{qka-1.3.1.dev5 → qka-1.4.1.dev3}/qka/core/strategy.py

@@ -28,7 +28,7 @@ class Strategy(ABC):
             cash: 初始资金，默认 10 万元
         """
         self.broker = Broker(initial_cash=cash)
-        self._data = DataAccessor(max_window=250)
+        self._data = DataAccessor(max_window=750)
 
     def get(self, factor: str):
         """
@@ -75,6 +75,11 @@ class Strategy(ABC):
                 # 历史序列（过去 N 天）
                 hist = self.history('close', 20)
 
+                # 技术指标（基于 ta 库）
+                sma20 = self.ta.sma('close', length=20)
+                rsi14 = self.ta.rsi('close', length=14)
+                macd = self.ta.macd('close', fast=12, slow=26, signal=9)
+
                 # 交易操作
                 if not close.empty and '000001.SZ' in close.index:
                     self.broker.buy('000001.SZ', float(close['000001.SZ']), 100)