qka 2.1.1.dev2__tar.gz → 2.1.2.dev6__tar.gz

{qka-2.1.1.dev2 → qka-2.1.2.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.1.1.dev2
+Version: 2.1.2.dev6
 Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Repository, https://github.com/zsrl/qka
@@ -63,56 +63,29 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-**QKA（快量化 / Quant Kit for A-shares）** — 简洁易用的 A 股量化回测框架。
+简洁易用的 A 股量化回测框架。
 
-```python
-from qka import Data, Strategy, Backtest
+---
 
-data = Data(
-    symbols=['sz.000001'],
-    indicators={
-        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
-        'sma_20': ('ta.trend.sma_indicator', 'close', 20),
-    },
-)
+## 安装
 
-class MaCross(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.pct = 0.2
+### 包安装
 
-    def on_bar(self, date):
-        close = self.get('close')
-        fast = self.get('sma_5')
-        slow = self.get('sma_20')
-        for sym in close.index:
-            price = float(close[sym])
-            if price <= 0:
-                continue
-            if fast[sym] > slow[sym]:
-                size = self.sizing.percent(self.pct, price)
-                if size > 0:
-                    self.broker.buy(sym, price, size)
-            else:
-                pos = self.broker.positions.get(sym, {}).get('size', 0)
-                if pos > 0:
-                    self.broker.sell(sym, price, pos)
-
-strategy = MaCross()
-bt = Backtest(data, strategy)
-bt.run(cash=200000, start_date='2024-01-01')
-print(bt.metrics['total_return_pct'])
+```bash
+pip install qka
 ```
 
----
+需要 Python 3.10+。
 
-## 安装
+### AI 技能安装
+
+为 Claude Code、Cursor 等 AI 编程工具安装 QKA 技能：
 
 ```bash
-pip install qka
+npx skills add zsrl/qka
 ```
 
-需要 Python 3.10+。
+安装后，AI 助手即可自动加载 QKA 框架的 API 文档，生成符合规范的量化策略代码。
 
 ## 快速上手
 
@@ -174,11 +147,46 @@ print(bt.metrics['sharpe_ratio'])        # 夏普比率
 
 框架 API 完整文档见 [skills/qka/SKILL.md](skills/qka/SKILL.md)——所有类的方法签名、参数、返回值和约束都在里面。
 
-## 下一步规划
+## 完整示例
+
+```python
+from qka import Data, Strategy, Backtest
 
-- [ ] 分钟级数据支持
-- [ ] 自适应参数优化
-- [ ] 实盘交易（QMT 接口）
+data = Data(
+    symbols=['sz.000001'],
+    indicators={
+        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
+        'sma_20': ('ta.trend.sma_indicator', 'close', 20),
+    },
+)
+
+class MaCross(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.pct = 0.2
+
+    def on_bar(self, date):
+        close = self.get('close')
+        fast = self.get('sma_5')
+        slow = self.get('sma_20')
+        for sym in close.index:
+            price = float(close[sym])
+            if price <= 0:
+                continue
+            if fast[sym] > slow[sym]:
+                size = self.sizing.percent(self.pct, price)
+                if size > 0:
+                    self.broker.buy(sym, price, size)
+            else:
+                pos = self.broker.positions.get(sym, {}).get('size', 0)
+                if pos > 0:
+                    self.broker.sell(sym, price, pos)
+
+strategy = MaCross()
+bt = Backtest(data, strategy)
+bt.run(cash=200000, start_date='2024-01-01')
+print(bt.metrics['total_return_pct'])
+```
 
 ## 许可证
 
@@ -192,4 +200,3 @@ print(bt.metrics['sharpe_ratio'])        # 夏普比率
 ---
 
 > ⚠️ 量化交易存在风险，请充分了解后再使用本框架。
-充分了解后再使用本框架。

{qka-2.1.1.dev2 → qka-2.1.2.dev6}/README.md

@@ -1,145 +1,152 @@
-# QKA — 快量化
-## Quant Kit for A-shares
-
-<p align="center">
-  <a href="https://pypi.org/project/qka/">
-    <img src="https://img.shields.io/pypi/v/qka?color=blue" alt="PyPI">
-  </a>
-  <a href="https://github.com/zsrl/qka">
-    <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
-  </a>
-  <a href="LICENSE">
-    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-  </a>
-</p>
-
-**QKA（快量化 / Quant Kit for A-shares）** — 简洁易用的 A 股量化回测框架。
-
-```python
-from qka import Data, Strategy, Backtest
-
-data = Data(
-    symbols=['sz.000001'],
-    indicators={
-        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
-        'sma_20': ('ta.trend.sma_indicator', 'close', 20),
-    },
-)
-
-class MaCross(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.pct = 0.2
-
-    def on_bar(self, date):
-        close = self.get('close')
-        fast = self.get('sma_5')
-        slow = self.get('sma_20')
-        for sym in close.index:
-            price = float(close[sym])
-            if price <= 0:
-                continue
-            if fast[sym] > slow[sym]:
-                size = self.sizing.percent(self.pct, price)
-                if size > 0:
-                    self.broker.buy(sym, price, size)
-            else:
-                pos = self.broker.positions.get(sym, {}).get('size', 0)
-                if pos > 0:
-                    self.broker.sell(sym, price, pos)
-
-strategy = MaCross()
-bt = Backtest(data, strategy)
-bt.run(cash=200000, start_date='2024-01-01')
-print(bt.metrics['total_return_pct'])
-```
-
----
-
-## 安装
-
-```bash
-pip install qka
-```
-
-需要 Python 3.10+。
-
-## 快速上手
-
-### 数据
-
-```python
-from qka import Data
-
-data = Data(
-    symbols=['sz.000001', 'sh.600000'],
-    indicators={
-        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
-        'rsi_14': ('ta.momentum.rsi', 'close', 14),
-    },
-)
-df = data.get()  # 返回宽表 DataFrame，列名 {symbol}|{factor}
-```
-
-### 策略
-
-```python
-from qka import Strategy
-
-class MyStrategy(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.lookback = 20  # 自定义参数
-
-    def on_bar(self, date):
-        close = self.get('close')            # 当前横截面
-        hist = self.history('close', 20)     # 历史窗口
-        # 交易逻辑：self.broker.buy / self.broker.sell
-        # 仓位计算：self.sizing.percent / self.sizing.fixed_shares
-```
-
-### 回测
-
-```python
-from qka import Backtest
-
-strategy = MyStrategy()
-bt = Backtest(data, strategy)
-bt.run(cash=200000, start_date='2024-01-01', benchmark='sh.000300')
-print(bt.metrics['total_return_pct'])   # 总收益率
-print(bt.metrics['sharpe_ratio'])        # 夏普比率
-```
-
-## 核心能力
-
-- **多数据源** — baostock（默认）、akshare、QMT
-- **预计算指标** — ta 库全部 60+ 指标，`('ta.trend.sma_indicator', 'close', 5)` 格式直接透传
-- **事件驱动回测** — 按日推进，`self.get()` 横截面 + `self.history()` 窗口序列
-- **仓位管理** — `sizing.percent()` / `sizing.fixed_amount()` / `sizing.fixed_shares()` / `sizing.atr_risk()`
-- **交易模拟** — 佣金万 2.5、印花税万 5（仅卖出）、滑点 0.1%，最低佣金 5 元
-- **绩效指标** — 总收益率、年化、夏普比率、最大回撤、Calmar、胜率、盈亏比等 13 项
-- **基准对比** — 支持沪深 300（或指定指数）对比
-
-## 文档
-
-框架 API 完整文档见 [skills/qka/SKILL.md](skills/qka/SKILL.md)——所有类的方法签名、参数、返回值和约束都在里面。
-
-## 下一步规划
-
-- [ ] 分钟级数据支持
-- [ ] 自适应参数优化
-- [ ] 实盘交易（QMT 接口）
-
-## 许可证
-
-[MIT](LICENSE)
-
-## 致谢
-
-- [baostock](http://baostock.com) — 免费 A 股数据
-- [ta](https://github.com/bukosabino/ta) — 技术指标库
-
----
-
-> ⚠️ 量化交易存在风险，请充分了解后再使用本框架。
-充分了解后再使用本框架。
+# QKA — 快量化
+## Quant Kit for A-shares
+
+<p align="center">
+  <a href="https://pypi.org/project/qka/">
+    <img src="https://img.shields.io/pypi/v/qka?color=blue" alt="PyPI">
+  </a>
+  <a href="https://github.com/zsrl/qka">
+    <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  </a>
+</p>
+
+简洁易用的 A 股量化回测框架。
+
+---
+
+## 安装
+
+### 包安装
+
+```bash
+pip install qka
+```
+
+需要 Python 3.10+。
+
+### AI 技能安装
+
+为 Claude Code、Cursor 等 AI 编程工具安装 QKA 技能：
+
+```bash
+npx skills add zsrl/qka
+```
+
+安装后，AI 助手即可自动加载 QKA 框架的 API 文档，生成符合规范的量化策略代码。
+
+## 快速上手
+
+### 数据
+
+```python
+from qka import Data
+
+data = Data(
+    symbols=['sz.000001', 'sh.600000'],
+    indicators={
+        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
+        'rsi_14': ('ta.momentum.rsi', 'close', 14),
+    },
+)
+df = data.get()  # 返回宽表 DataFrame，列名 {symbol}|{factor}
+```
+
+### 策略
+
+```python
+from qka import Strategy
+
+class MyStrategy(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.lookback = 20  # 自定义参数
+
+    def on_bar(self, date):
+        close = self.get('close')            # 当前横截面
+        hist = self.history('close', 20)     # 历史窗口
+        # 交易逻辑：self.broker.buy / self.broker.sell
+        # 仓位计算：self.sizing.percent / self.sizing.fixed_shares
+```
+
+### 回测
+
+```python
+from qka import Backtest
+
+strategy = MyStrategy()
+bt = Backtest(data, strategy)
+bt.run(cash=200000, start_date='2024-01-01', benchmark='sh.000300')
+print(bt.metrics['total_return_pct'])   # 总收益率
+print(bt.metrics['sharpe_ratio'])        # 夏普比率
+```
+
+## 核心能力
+
+- **多数据源** — baostock（默认）、akshare、QMT
+- **预计算指标** — ta 库全部 60+ 指标，`('ta.trend.sma_indicator', 'close', 5)` 格式直接透传
+- **事件驱动回测** — 按日推进，`self.get()` 横截面 + `self.history()` 窗口序列
+- **仓位管理** — `sizing.percent()` / `sizing.fixed_amount()` / `sizing.fixed_shares()` / `sizing.atr_risk()`
+- **交易模拟** — 佣金万 2.5、印花税万 5（仅卖出）、滑点 0.1%，最低佣金 5 元
+- **绩效指标** — 总收益率、年化、夏普比率、最大回撤、Calmar、胜率、盈亏比等 13 项
+- **基准对比** — 支持沪深 300（或指定指数）对比
+
+## 文档
+
+框架 API 完整文档见 [skills/qka/SKILL.md](skills/qka/SKILL.md)——所有类的方法签名、参数、返回值和约束都在里面。
+
+## 完整示例
+
+```python
+from qka import Data, Strategy, Backtest
+
+data = Data(
+    symbols=['sz.000001'],
+    indicators={
+        'sma_5':  ('ta.trend.sma_indicator', 'close', 5),
+        'sma_20': ('ta.trend.sma_indicator', 'close', 20),
+    },
+)
+
+class MaCross(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.pct = 0.2
+
+    def on_bar(self, date):
+        close = self.get('close')
+        fast = self.get('sma_5')
+        slow = self.get('sma_20')
+        for sym in close.index:
+            price = float(close[sym])
+            if price <= 0:
+                continue
+            if fast[sym] > slow[sym]:
+                size = self.sizing.percent(self.pct, price)
+                if size > 0:
+                    self.broker.buy(sym, price, size)
+            else:
+                pos = self.broker.positions.get(sym, {}).get('size', 0)
+                if pos > 0:
+                    self.broker.sell(sym, price, pos)
+
+strategy = MaCross()
+bt = Backtest(data, strategy)
+bt.run(cash=200000, start_date='2024-01-01')
+print(bt.metrics['total_return_pct'])
+```
+
+## 许可证
+
+[MIT](LICENSE)
+
+## 致谢
+
+- [baostock](http://baostock.com) — 免费 A 股数据
+- [ta](https://github.com/bukosabino/ta) — 技术指标库
+
+---
+
+> ⚠️ 量化交易存在风险，请充分了解后再使用本框架。

{qka-2.1.1.dev2 → qka-2.1.2.dev6}/qka/core/backtest.py

@@ -132,6 +132,7 @@ class Backtest:
                         for factor, data in by_factor.items():
                             self.strategy._data.push(dt, factor, data)
                         # dask 路径：策略使用 self.get() / self.history()
+                        self.strategy.broker.timestamp = dt
                         self.strategy.on_bar(dt)
                         self.strategy.broker.on_bar(
                             dt, self.strategy._data.get
@@ -143,6 +144,7 @@ class Backtest:
                     by_factor = self._parse_row(row)
                     for factor, data in by_factor.items():
                         self.strategy._data.push(date, factor, data)
+                    self.strategy.broker.timestamp = date
                     self.strategy.on_bar(date)
                     self.strategy.broker.on_bar(
                         date, self.strategy._data.get
@@ -154,6 +156,7 @@ class Backtest:
                 by_factor = self._parse_row(row)
                 for factor, data in by_factor.items():
                     self.strategy._data.push(date, factor, data)
+                self.strategy.broker.timestamp = date
                 self.strategy.on_bar(date)
                 self.strategy.broker.on_bar(
                     date, self.strategy._data.get

{qka-2.1.1.dev2 → qka-2.1.2.dev6}/qka/core/data.py

@@ -45,8 +45,24 @@ class Data():
         pool_size (int): 并发下载线程数
         datadir (Path): 数据缓存目录
         target_dir (Path): 目标存储目录
+        extra_fields (List[str]): baostock 扩展字段（选股/估值用），如 ['peTTM', 'pbMRQ', 'turn']
     """
     
+    # baostock query_history_k_data_plus 完整支持的基础字段（除 date 索引外）
+    BAOSTOCK_BASE_FIELDS = ["open", "high", "low", "close", "volume", "amount"]
+    # 可通过 extra_fields 追加的扩展字段白名单（行情/估值/选股类）
+    BAOSTOCK_EXTRA_FIELDS = [
+        "preclose",    # 前收盘价
+        "turn",        # 换手率(%)
+        "tradestatus", # 交易状态(1=正常, 0=停牌)
+        "pctChg",      # 涨跌幅(%)
+        "isST",        # 是否 ST(1=是, 0=否)
+        "peTTM",       # 市盈率(TTM)
+        "pbMRQ",       # 市净率(MRQ)
+        "psTTM",       # 市销率(TTM)
+        "pcfNcfTTM",   # 市现率(TTM)
+    ]
+
     def __init__(
         self, 
         symbols: Optional[List[str]] = None,
@@ -57,6 +73,7 @@ class Data():
         pool_size: int = 10,
         datadir: Optional[Path] = None,
         indicators: Optional[dict] = None,
+        extra_fields: Optional[List[str]] = None,
     ):
         """
         初始化数据对象
@@ -71,6 +88,10 @@ class Data():
             pool_size: 并发下载线程数
             datadir: 缓存目录路径
             indicators: 预计算指标/因子，支持三种格式：
+            extra_fields: baostock 扩展字段列表（选股/估值用，如 ['peTTM', 'pbMRQ', 'turn']），
+                可选值见 BAOSTOCK_EXTRA_FIELDS。追加的列同样遵循 {symbol}|{field} 命名，
+                如 'sh.600000|peTTM'。注意：首次下载后缓存字段固定，变更 extra_fields
+                会自动检测列缺失并重新下载对应股票。
                 
                 **1. 字典（混搭 ta 函数和自定义因子）：**
                 ```python
@@ -99,6 +120,17 @@ class Data():
         self.source = source
         self.pool_size = pool_size
 
+        # extra_fields 白名单校验 + 去重
+        self.extra_fields = []
+        for f in (extra_fields or []):
+            if f not in self.BAOSTOCK_EXTRA_FIELDS:
+                raise ValueError(
+                    f"extra_fields 含不支持的字段: {f}。"
+                    f"可选: {self.BAOSTOCK_EXTRA_FIELDS}"
+                )
+            if f not in self.extra_fields:
+                self.extra_fields.append(f)
+
         # 统一处理 indicators 参数
         if callable(indicators):
             # 函数形式 → 保存为 callable
@@ -125,6 +157,35 @@ class Data():
         self.target_dir = self.datadir / self.source / self.period / (self.adjust or "bfq")
         self.target_dir.mkdir(parents=True, exist_ok=True)
 
+    def _cache_missing_extra_fields(self, path: Path) -> bool:
+        """检查已有 parquet 缓存是否缺少 extra_fields 指定的列。"""
+        if not self.extra_fields or not path.exists():
+            return False
+        try:
+            cols = set(pq.read_schema(path).names)
+        except Exception:
+            return True
+        return any(f not in cols for f in self.extra_fields)
+
+    def _merged_extra_fields(self, path: Path) -> List[str]:
+        """
+        计算本次下载实际请求的扩展字段：当前 extra_fields 与缓存已有扩展列的并集。
+
+        保证同一 datadir 下不同 extra_fields 配置共享缓存时，列只增不减、
+        不互相覆盖（第一次只有 peTTM，第二次再加 pbMRQ 时 peTTM 仍保留）。
+        """
+        merged = list(self.extra_fields)
+        if not path.exists():
+            return merged
+        try:
+            existing = set(pq.read_schema(path).names)
+        except Exception:
+            return merged
+        for f in self.BAOSTOCK_EXTRA_FIELDS:
+            if f in existing and f not in merged:
+                merged.append(f)
+        return merged
+
     def _download(
         self, symbol: str,
         download_start: str = None,
@@ -135,6 +196,7 @@ class Data():
 
         首次下载只拉请求范围（非全量）。已存在时检查缓存覆盖范围，
         只补下载缺失的部分（前面缺失补前面，后面缺失补后面），合并去重写回。
+        若缓存缺少 extra_fields 指定的列（如从无扩展字段升级到有），则全量重新下载。
 
         Args:
             symbol: 股票代码
@@ -151,12 +213,16 @@ class Data():
         default_start = '1990-01-01'
         default_end = pd.Timestamp.now().strftime("%Y-%m-%d")
 
-        # ── 首次下载：只拉请求范围 ──
-        if not path.exists():
+        # 实际请求的扩展字段 = 当前配置 ∪ 缓存已有扩展列（列只增不减，不互相覆盖）
+        merged_extra = self._merged_extra_fields(path)
+
+        # ── 首次下载：只拉请求范围（缓存缺失 extra_fields 列时也全量重下）──
+        if not path.exists() or self._cache_missing_extra_fields(path):
             df = self._get_from_baostock(
                 symbol,
                 start_date=download_start or default_start,
                 end_date=download_end or default_end,
+                extra_fields=merged_extra,
             )
             if len(df) == 0:
                 raise RuntimeError(f"{symbol}: baostock 返回空数据")
@@ -183,6 +249,7 @@ class Data():
             end_before = (cache_min - pd.Timedelta(days=1)).strftime("%Y-%m-%d")
             df_before = self._get_from_baostock(
                 symbol, start_date=download_start, end_date=end_before,
+                extra_fields=merged_extra,
             )
             if len(df_before) > 0:
                 pieces.insert(0, df_before)
@@ -196,6 +263,7 @@ class Data():
                 symbol,
                 start_date=start_after,
                 end_date=download_end or default_end,
+                extra_fields=merged_extra,
             )
             if len(df_after) > 0:
                 pieces.append(df_after)
@@ -220,7 +288,7 @@ class Data():
         缓存不存在、不覆盖请求范围、或需要拉最新数据时返回 True。
         """
         path = self.target_dir / f"{symbol}.parquet"
-        if not path.exists():
+        if not path.exists() or self._cache_missing_extra_fields(path):
             return True
         if self.source != 'baostock':
             return False
@@ -624,6 +692,7 @@ class Data():
         self, symbol: str,
         start_date: str = '1990-01-01',
         end_date: str = '2050-12-31',
+        extra_fields: Optional[List[str]] = None,
     ) -> pd.DataFrame:
         """
         从 baostock 获取单个股票的数据。
@@ -632,17 +701,24 @@ class Data():
             symbol: baostock 格式股票代码，如 sz.000001、sh.600000
             start_date: 起始日期，格式 YYYY-MM-DD，默认 1990-01-01
             end_date: 截止日期，格式 YYYY-MM-DD，默认 2050-12-31
+            extra_fields: 本次请求的扩展字段列表。None 时使用 self.extra_fields；
+                调用方（_download）可传入"当前配置 ∪ 缓存已有列"的并集，保证列只增不减
 
         Returns:
-            pd.DataFrame: 股票数据，以 date 为索引，包含 open, high, low, close, volume, amount 列
+            pd.DataFrame: 股票数据，以 date 为索引，包含 open, high, low, close, volume, amount
+            及 extra_fields 指定的扩展列（如有）
         """
         # adjustflag: 1=不复权, 2=前复权, 3=后复权
         adjust_map = {'bfq': '1', 'qfq': '2', 'hfq': '3'}
         adjustflag = adjust_map.get(self.adjust, '2')
 
+        # 基础字段 + extra_fields 扩展字段（缺省用 self.extra_fields）
+        extra = list(extra_fields) if extra_fields is not None else self.extra_fields
+        fields = ",".join(["date"] + self.BAOSTOCK_BASE_FIELDS + extra)
+
         rs = bs.query_history_k_data_plus(
             symbol,
-            "date,open,high,low,close,volume,amount",
+            fields,
             start_date=start_date,
             end_date=end_date,
             frequency='d',
@@ -659,8 +735,8 @@ class Data():
         if len(df) == 0:
             return df
 
-        # baostock 返回的数值列是字符串，转数值类型
-        numeric_cols = ["open", "high", "low", "close", "volume", "amount"]
+        # baostock 返回的数值列是字符串，转数值类型（基础列 + 本次请求的扩展字段）
+        numeric_cols = self.BAOSTOCK_BASE_FIELDS + extra
         for col in numeric_cols:
             if col in df.columns:
                 df[col] = pd.to_numeric(df[col], errors="coerce")