qka 1.6.2.dev2__tar.gz → 1.6.3.dev8__tar.gz

{qka-1.6.2.dev2 → qka-1.6.3.dev8}/.gitignore

@@ -182,4 +182,7 @@ _momentum_output.txt
 /tests/
 
 # 回测报告
-reports/
+reports/
+
+# 临时脚本
+_commit.ps1

{qka-1.6.2.dev2 → qka-1.6.3.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.6.2.dev2
+Version: 1.6.3.dev8
 Summary: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Documentation, https://zsrl.github.io/qka

{qka-1.6.2.dev2 → qka-1.6.3.dev8}/docs/examples/momentum.md

@@ -7,32 +7,27 @@
 ```python
 """每月末按动量排序，选前 20% 的股票买入"""
 from qka import Data, Strategy, Broker, Backtest
-import numpy as np
 
 
 class Momentum(Strategy):
     def __init__(self):
         super().__init__()
         self.broker = Broker(initial_cash=1_000_000)
-        self.monthly_rebalance = False
-        self.holdings = []
+        self.last_month = None
 
     def on_bar(self, date):
-        # 月末调仓
+        # 月末附近调仓
         if date.day < 28:
             return
 
-        # 每月只调一次（本周最后一个交易日）
-        if self.monthly_rebalance:
+        # 本月已调仓，跳过
+        month_key = (date.year, date.month)
+        if self.last_month == month_key:
             return
-        self.monthly_rebalance = True
-
-        # 下个月的第一天重置标记
-        if date.day >= 28:
-            pass  # 保持标记，等跨月再重置
+        self.last_month = month_key
 
         close = self.get('close')
-        if close is None or close.empty or len(close) < 5:
+        if close is None or close.empty:
             return
 
         # 过去 60 个交易日的动量
@@ -40,7 +35,7 @@ class Momentum(Strategy):
         if hist is None or hist.empty:
             return
 
-        # 算每只股票的收益率
+        # 计算每只股票的阶段收益率
         ret = {}
         for sym in hist.columns:
             prices = hist[sym].dropna()
@@ -55,7 +50,7 @@ class Momentum(Strategy):
         top_n = max(1, len(sorted_syms) // 5)
         buy_list = sorted_syms[:top_n]
 
-        # 卖出不在列表里的
+        # 卖出不在列表里的持仓
         for sym in list(self.broker.positions.keys()):
             if sym not in buy_list:
                 pos = self.broker.positions[sym]
@@ -63,7 +58,7 @@ class Momentum(Strategy):
                 if price > 0:
                     self.broker.sell(sym, price, pos['size'])
 
-        # 买入列表里的新标的
+        # 买入列表中的新标的
         cash_per_sym = self.broker.cash / len(buy_list)
         for sym in buy_list:
             if sym in self.broker.positions:

{qka-1.6.2.dev2 → qka-1.6.3.dev8}/docs/examples/multi_factor.md

@@ -13,6 +13,7 @@ class MultiFactor(Strategy):
     def __init__(self):
         super().__init__()
         self.broker = Broker(initial_cash=1_000_000)
+        self.last_month = None
 
     def on_bar(self, date):
         close = self.get('close')
@@ -23,6 +24,11 @@ class MultiFactor(Strategy):
         if date.day < 28:
             return
 
+        month_key = (date.year, date.month)
+        if self.last_month == month_key:
+            return
+        self.last_month = month_key
+
         rsi = self.get('rsi_14')
         hist = self.history('rsi_14', 20)
         if hist is None or hist.empty:

qka-1.6.3.dev8/docs/guides/backtest.md

@@ -0,0 +1,48 @@
+# 回测
+
+使用 `Backtest` 运行策略并获取回测结果。
+
+---
+
+## 基本用法
+
+```python
+from qka import Backtest
+
+bt = Backtest(data, MyStrategy())
+bt.run(benchmark='000300.SH')
+```
+
+`Backtest` 的参数：
+
+| 参数 | 说明 |
+|------|------|
+| `data` | Data 实例 |
+| `strategy` | 策略实例（可在构造函数中传入 cash 等参数） |
+
+## run 方法
+
+```python
+bt.run(benchmark='000300.SH')   # 带沪深 300 基准对比
+```
+
+执行流程：按时间排序数据 → 逐日调用 `on_bar(date)` → 记录每日资产变化 → 下载基准数据。
+
+大规模回测（数百只股票、数年数据）时，QKA 采用分批计算策略，避免一次性加载全部数据到内存。
+
+## 查看结果
+
+- `summary()` — 终端输出绩效指标
+- `report()` — 生成 HTML 报告
+
+详见[报告](report.md)。
+
+## 基准对比
+
+A 股最常使用沪深 300 指数：
+
+```python
+bt.run(benchmark='000300.SH')
+```
+
+启用基准后，summary 和 report 中会增加超额收益、超额夏普等指标。

qka-1.6.3.dev8/docs/guides/data.md

@@ -0,0 +1,82 @@
+# 数据
+
+回测的第一步是获取数据。QKA 负责下载、缓存和合并，用户只需指定股票代码。
+
+---
+
+## 基本用法
+
+```python
+data = Data(symbols=['000001.SZ', '600000.SH'])
+```
+
+以上代码会：
+
+1. 从 baostock 下载日线数据
+2. 每只股票保存为独立的 parquet 文件到本地缓存
+3. 下次运行时直接读取缓存，无需重复下载
+
+## 参数
+
+| 参数 | 作用 | 默认值 |
+|------|------|--------|
+| `symbols` | 股票代码列表 | 必填 |
+| `period` | 数据周期 | `'1d'` |
+| `adjust` | 复权方式：`'qfq'`（前复权）、`'hfq'`（后复权）、`'bfq'`（不复权） | `'qfq'` |
+| `source` | 数据源：`'baostock'` 或 `'akshare'` | `'baostock'` |
+
+```python
+data = Data(symbols=['000001.SZ'], adjust='hfq')
+```
+
+## 缓存位置
+
+```
+datadir/
+└── baostock/
+    └── 1d/
+        └── qfq/
+            ├── 000001.SZ.parquet
+            ├── 600000.SH.parquet
+            └── ...
+```
+
+每只股票独立文件。清除缓存直接删除该目录即可。
+
+## 合并后的数据
+
+多股票回测时，QKA 将各股票合并为一张宽表，列名格式为 `{股票代码}_{字段名}`：
+
+| 日期 | 000001.SZ_close | 600000.SH_close |
+|------|----------------|----------------|
+| 2024-01-02 | 10.2 | 8.1 |
+| 2024-01-03 | 10.5 | 8.3 |
+
+策略中无需关心此格式——`self.get('close')` 自动解析为横截面 Series。
+
+## 两种加载模式
+
+**普通模式** — 适用于少量股票（几十只以内）：
+
+```python
+data = Data(symbols=['000001.SZ'])
+```
+
+**懒加载（lazy）** — 适用于大规模数据（数百只股票），分批计算，降低内存占用：
+
+```python
+bt.run(lazy=True)
+```
+
+两种模式下策略代码完全一致，`self.get()` 和 `self.history()` 用法不变。
+
+## 数据源选择
+
+| 数据源 | 优点 | 缺点 |
+|--------|------|------|
+| **baostock**（默认） | 稳定，开箱即用 | 单线程下载 |
+| **akshare** | 支持并发 | 个股接口偶发屏蔽 |
+
+```python
+data = Data(symbols=['000001.SZ'], source='akshare')
+```

qka-1.6.3.dev8/docs/guides/indicators.md

@@ -0,0 +1,78 @@
+# 指标
+
+策略中经常需要均线、RSI、MACD 等技术指标。QKA 在数据加载时一次性预计算完毕，策略中直接读取。
+
+---
+
+## 基本用法
+
+```python
+data = Data(
+    symbols=['000001.SZ'],
+    indicators={
+        'sma_20': ('sma', 20),
+        'rsi_14': ('rsi', 14),
+    }
+)
+```
+
+策略中直接调用：
+
+```python
+def on_bar(self, date):
+    sma = self.get('sma_20')
+    rsi = self.get('rsi_14')
+```
+
+## 支持的指标
+
+| 指标 | 写法 | 生成列 |
+|------|------|--------|
+| 简单均线 | `('sma', 20)` | `sma_20` |
+| 指数均线 | `('ema', 14)` | `ema_14` |
+| 加权均线 | `('wma', 30)` | `wma_30` |
+| RSI | `('rsi', 14)` | `rsi_14` |
+| ATR | `('atr', 14)` | `atr_14` |
+| MACD | `('macd', 12, 26, 9)` | `macd`、`macd_signal`、`macd_histogram` |
+| 布林带 | `('bbands', 20, 2)` | `bbands_upper`、`bbands_middle`、`bbands_lower` |
+
+## 指定计算字段
+
+默认以收盘价（close）计算。如需对其他字段计算：
+
+```python
+indicators={
+    'sma_high_10': ('sma', 'high', 10),    # 对最高价计算均线
+}
+```
+
+## 自定义指标
+
+通过函数实现任意自定义计算逻辑：
+
+```python
+def add_ma5(df):
+    """每只股票单独计算 5 日均线"""
+    df['ma5'] = df['close'].rolling(5).mean()
+    return df
+
+data = Data(symbols=['000001.SZ'], indicators=add_ma5)
+```
+
+函数接收每只股票的 DataFrame，返回添加新列后的 DataFrame。可与内置指标混用：
+
+```python
+indicators={
+    'sma_20': ('sma', 20),
+    'ma5': add_ma5,
+}
+```
+
+## 预计算与动态计算对比
+
+| 方式 | 计算次数 | 策略中的用法 |
+|------|---------|-------------|
+| 预计算 | 加载时计算 1 次 | `self.get('sma_20')` |
+| 动态计算 | 每根 bar 计算 1 次 | 每 bar 手动调用 rolling |
+
+股票数量越多、回测周期越长，预计算的性能优势越明显。

qka-1.6.3.dev8/docs/guides/report.md

@@ -0,0 +1,74 @@
+# 报告
+
+回测完成后，QKA 提供终端概览和 HTML 报告两种方式查看结果。
+
+---
+
+## summary — 终端概览
+
+```python
+bt.summary()
+```
+
+输出示例：
+
+```
+QKA 回测报告 — MyStrategy
+────────────────────────────────────────
+初始资金:        ¥100,000.00
+最终资产:        ¥178,233.45
+总收益率:        +78.23%
+年化收益率:      +11.34%
+最大回撤:        -32.15%
+夏普比率:        0.68
+交易次数:        47
+胜率:            61.70%
+────────────────────────────────────────
+```
+
+### 指标说明
+
+| 指标 | 说明 |
+|------|------|
+| 总收益率 | 回测期间总资产涨幅 |
+| 年化收益率 | 折算为年化后的收益率，便于不同时长策略间的比较 |
+| 最大回撤 | 历史最高点到最低点的最大跌幅 |
+| 夏普比率 | 单位风险对应的超额收益。> 1 为良好，> 2 为优秀 |
+| 胜率 | 盈利交易占总交易笔数的比例 |
+| 交易次数 | 总交易笔数。次数过少时，胜率和收益率的统计意义有限 |
+
+启用 benchmark 后会多出：
+
+| 指标 | 说明 |
+|------|------|
+| 超额收益 | 策略相对基准的超额回报 |
+| 超额夏普 | 超额收益的夏普比率 |
+
+---
+
+## report — HTML 报告
+
+```python
+bt.report(title='我的策略', output_path='./my_report.html')
+```
+
+浏览器自动打开。不传 `output_path` 时，默认保存到 `./reports/` 目录。
+
+### 报告内容
+
+- **绩效指标卡片** — summary 中的关键数字，卡片式展示
+- **净值曲线** — 资产变化曲线，支持基准对比
+- **月度收益热力图** — 各月收益百分比，绿色表示盈利，红色表示亏损
+- **交易明细列表** — 每笔交易的买卖时间、价格、股数、盈亏
+
+### 手机查看
+
+报告是自包含的 HTML 文件，使用 Plotly 纯前端渲染，无需启动服务器。双击即可打开，通过微信或邮件分享后，在手机上同样可正常查看。
+
+---
+
+## 备注
+
+- `bt.report()` 返回 `Path` 对象，可使用 `str(report_path)` 获取文件路径
+- 多次调用 `bt.run()` 会覆盖前次回测的报告
+- 交易次数过少时，胜率 100% 也可能不具备统计意义，需结合交易次数综合判断

qka-1.6.3.dev8/docs/guides/sizing.md

@@ -0,0 +1,83 @@
+# 仓位
+
+固定股数（如 100 股）无法适配不同资金规模。`self.sizing` 根据可用资金自动计算合理买入股数。
+
+---
+
+## 方法一览
+
+| 方法 | 适用场景 |
+|------|---------|
+| `percent(ratio, price)` | 按可用资金比例买入 |
+| `fixed_amount(amount, price)` | 每月固定金额定投 |
+| `fixed_shares(n)` | 固定股数，自动按手取整 |
+| `atr_risk(risk_ratio, price, atr)` | 波动率自适应仓位 |
+| `kelly(win_rate, wl_ratio, price)` | 已知胜率赔率时的最优下注 |
+
+---
+
+## percent — 比例仓位
+
+最常用的方式。用可用资金的一定比例买入：
+
+```python
+size = self.sizing.percent(0.1, price)
+# 可用资金 10 万，price=10 → 1000 股
+# 可用资金 1 万，price=10 → 100 股
+```
+
+## fixed_amount — 固定金额
+
+适合定投场景，每次投入固定金额：
+
+```python
+size = self.sizing.fixed_amount(5000, price)
+# price=10 → 500 股
+```
+
+## fixed_shares — 固定股数
+
+```python
+size = self.sizing.fixed_shares(100)
+# 返回 100（现金充足时），不足时返回 0
+```
+
+## atr_risk — ATR 风控
+
+根据波动率动态调整仓位。ATR 较大时减少买入股数，ATR 较小时增加：
+
+```python
+atr = float(self.get('atr_14')[sym])
+size = self.sizing.atr_risk(0.02, price, atr)
+```
+
+ATR=0.5：`10万 × 2% / (0.5 × 2) = 2000 股`
+ATR=1.0：`10万 × 2% / (1.0 × 2) = 1000 股`
+
+波动率翻倍时仓位自动减半。
+
+## kelly — 凯利公式
+
+适合有历史统计数据的场景：
+
+```python
+size = self.sizing.kelly(0.6, 2.0, price)
+# 胜率 60%，赔率 2，f* = (0.6×2 - 0.4)/2 = 0.4 → 40% 仓位
+```
+
+计算结果 ≤ 0 时返回 0（不下注）。
+
+---
+
+## 注意事项
+
+**基于可用现金计算**，不含持仓市值。如需基于总资产：
+
+```python
+total = self.broker.cash
+for sym, pos in self.broker.positions.items():
+    total += pos['size'] * pos['cost_basis']
+```
+
+- ATR 为 0 时返回 0（新股或一字板）
+- 价格必须大于 0，前复权可能出现负价格，此时不交易

qka-1.6.3.dev8/docs/guides/strategy.md

@@ -0,0 +1,114 @@
+# 策略
+
+策略是一个继承 `Strategy` 基类的 Python 类，核心是实现 `on_bar` 方法。
+
+---
+
+## 基本结构
+
+```python
+from qka import Strategy, Broker
+
+class MyStrategy(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        # 交易逻辑写在这里
+```
+
+## 生命周期
+
+回测按时间顺序逐日推进。每个交易日调用一次 `on_bar(date)`，策略根据当日数据决定是否交易。
+
+## 数据获取
+
+**`self.get(factor)`** — 当日所有股票的横截面数据：
+
+```python
+close = self.get('close')
+# 返回 pd.Series:
+# 000001.SZ    10.50
+# 600000.SH     8.32
+
+price = float(close['000001.SZ'])
+
+for sym in close.index:
+    price = float(close[sym])
+```
+
+**`self.history(factor, window)`** — 过去 N 个交易日的历史数据：
+
+```python
+hist = self.history('close', 20)
+# 返回 pd.DataFrame:
+#              000001.SZ  600000.SH
+# 2024-01-02      10.2       8.12
+# 2024-01-03      10.5       8.32
+
+avg = hist['000001.SZ'].mean()
+```
+
+可访问的字段由 `Data` 配置决定。基础字段（`open`/`high`/`low`/`close`/`volume`）自动可用，指标字段需在 `indicators` 中声明。
+
+## 交易
+
+```python
+self.broker.buy('000001.SZ', price, size)    # 买入
+self.broker.sell('000001.SZ', price, size)   # 卖出
+```
+
+`size` 为股数。使用 `self.sizing` 计算合理仓位。
+
+## 仓位计算
+
+```python
+size = self.sizing.percent(0.1, price)           # 可用资金的 10%
+size = self.sizing.fixed_amount(10000, price)    # 固定金额 1 万元
+size = self.sizing.atr_risk(0.02, price, atr)    # ATR 风控仓位
+```
+
+详见[仓位](sizing.md)。
+
+## 状态管理
+
+在 `__init__` 中定义的自定义属性在整个回测过程中持续有效：
+
+```python
+class MyStrategy(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+        self.bought = False          # 自定义状态
+        self.entry_prices = {}        # 入场价格记录
+```
+
+## 多股票处理
+
+`self.get('close')` 返回所有股票的横截面，遍历处理即可：
+
+```python
+def on_bar(self, date):
+    close = self.get('close')
+    if close is None or close.empty:
+        return
+    for sym in close.index:
+        price = float(close[sym])
+        if price <= 0 or sym in self.broker.positions:
+            continue
+        size = self.sizing.percent(0.1, price)
+        if size > 0:
+            self.broker.buy(sym, price, size)
+```
+
+## 注意事项
+
+| 行为 | 原因 |
+|------|------|
+| 不要在 `on_bar` 中下载数据 | 每根 bar 都下载会导致性能严重下降 |
+| 不要在 `on_bar` 中使用 print | 数千根 bar 的输出量过大，应使用 `logger.debug` |
+| 不要访问回测引擎内部 | 策略只需与 broker 和 sizing 交互 |

qka-1.6.3.dev8/docs/guides/trading.md

@@ -0,0 +1,86 @@
+# 交易
+
+`Broker` 是虚拟券商，负责资金管理、持仓记录和交易费用计算。策略中通过 `self.broker` 访问。
+
+---
+
+## 初始化
+
+```python
+self.broker = Broker(initial_cash=100_000)
+```
+
+默认费率（贴近 A 股实盘）：
+
+| 费用 | 收取方向 | 默认费率 | 最低收费 |
+|------|---------|----------|---------|
+| 佣金 | 买卖双向 | 万 2.5 | 5 元 |
+| 印花税 | 卖出 | 万 5 | 无 |
+| 滑点 | 买卖双向 | 0.1% | 无 |
+
+自定义费率：
+
+```python
+self.broker = Broker(
+    initial_cash=1_000_000,
+    commission_rate=0.0001,      # 万 1
+    slippage=0.0005,             # 0.05%
+)
+```
+
+## 买卖操作
+
+```python
+self.broker.buy('000001.SZ', price, size)
+self.broker.sell('000001.SZ', price, size)
+```
+
+买入时扣除资金并增加持仓，卖出时释放资金并减少持仓。交易费用自动计算。
+
+## 持仓与资金
+
+```python
+self.broker.cash           # 当前可用资金（¥85,000）
+self.broker.positions      # {'000001.SZ': {'size': 1000, 'cost_basis': 10.2}}
+```
+
+`positions` 中每只股票包含：
+- `size` — 持仓股数
+- `cost_basis` — 平均买入成本
+
+## 完整的买卖流程
+
+```python
+def on_bar(self, date):
+    close = self.get('close')
+    if close is None or close.empty:
+        return
+
+    for sym in close.index:
+        price = float(close[sym])
+        if price <= 0:
+            continue
+
+        # 无持仓则买入
+        if sym not in self.broker.positions:
+            size = self.sizing.percent(0.1, price)
+            if size > 0:
+                self.broker.buy(sym, price, size)
+
+        # 涨幅超过 20% 则卖出
+        else:
+            pos = self.broker.positions[sym]
+            cost = pos['cost_basis']
+            if price / cost - 1 > 0.2:
+                self.broker.sell(sym, price, pos['size'])
+```
+
+## 特殊情况处理
+
+| 情况 | Broker 行为 |
+|------|------------|
+| 现金不足 | 不执行买入，记录日志 |
+| 持仓不足 | 不执行卖出，记录日志 |
+| 价格 ≤ 0 | 不交易，记录日志 |
+| 部分卖出 | 减少对应持仓数量 |
+| 全部卖出 | 从 positions 中移除该股票 |