qka 1.6.4.dev3__tar.gz → 1.6.5.dev5__tar.gz

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.6.4.dev3
-Summary: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
+Version: 1.6.5.dev5
+Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Documentation, https://zsrl.github.io/qka
 Project-URL: Repository, https://github.com/zsrl/qka
@@ -63,6 +63,7 @@ Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # QKA — 快量化
+## Quant Kit for A-shares
 
 <p align="center">
   <a href="https://qka.quantai.chat" target="_blank">
@@ -79,119 +80,109 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-**快捷量化助手（Quick Quantitative Assistant）** — 简洁易用的 A 股量化交易框架。三行代码完成回测，从研究到实盘一路畅通。
-
----
-
-## 三行代码跑回测
+**QKA（快量化 / Quant Kit for A-shares）** — 简洁易用的 A 股量化回测框架。
 
 ```python
-import qka
-
-bt = qka.Backtest(qka.Strategy()).run(benchmark='000300.SH')
-bt.report('我的策略')   # 生成交互式 HTML 报告，浏览器自动打开
+from qka import Data, Strategy, Backtest
+
+class MyStrategy(Strategy):
+    def on_bar(self, date):
+        close = self.get('close')
+        for sym in close.index:
+            if sym not in self.broker.positions:
+                price = float(close[sym])
+                if price > 0:
+                    size = self.sizing.percent(0.1, price)
+                    if size >= 100:
+                        self.broker.buy(sym, price, size)
+
+bt = Backtest(Data(['000001.SZ']), MyStrategy(cash=100_000))
+bt.run(benchmark='000300.SH')
+bt.report()
 ```
 
-这就是全部。数据获取、回测执行、绩效计算、基准对比、图表可视化，一行搞定。
+---
 
 ## 安装
 
 ```bash
-# 推荐 — 用 uv
-uv add qka
-
-# 或
 pip install qka
 ```
 
+需要 Python 3.10+。
+
 ## 快速上手
 
-### 1. 拿数据
+### 数据
 
 ```python
-import qka
+from qka import Data
 
-data = qka.Data(
+data = Data(
     symbols=['000001.SZ', '600000.SH'],
-    period='1d',
-    adjust='qfq'
+    indicators={'sma_5': ('sma', 5), 'rsi_14': ('rsi', 14)},
 )
-df = data.get()
+df = data.get()  # 触发下载，返回宽表 DataFrame
 ```
 
-### 2. 写策略
+### 策略
 
 ```python
-class MyStrategy(qka.Strategy):
-    def on_bar(self, date, get):
-        close = get('close')
-        # 价格低于10元买入1000股（注意前复权可能导致早期价格为负）
-        if '000001.SZ' in close and 0 < close['000001.SZ'] < 10:
-            self.broker.buy('000001.SZ', close['000001.SZ'], 1000)
-```
+from qka import Strategy
 
-### 3. 跑回测 + 看报告
+class MyStrategy(Strategy):
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
+        # 自定义状态放这里
 
-```python
-bt = qka.Backtest(data, MyStrategy())
-bt.run(benchmark='000300.SH')          # 自动获取沪深300做基准对比
-bt.report(title='我的策略')            # 一键生成HTML报告
+    def on_bar(self, date):
+        close = self.get('close')
+        hist = self.history('close', 20)
+        # 写你的交易逻辑
 ```
 
-生成的 HTML 报告包含：
-- 📊 净值曲线 + 基准对比（交互式 Plotly 图表）
-- 📉 回撤曲线
-- 📅 月度收益率热力图
-- 📋 交易明细（含手续费）
-- 🏆 绩效指标：年化收益、夏普比率、最大回撤、胜率、盈亏比……
-
-### 4. 调整成本参数
+### 回测
 
 ```python
-bt = qka.Backtest(
-    data, strategy,
-    commission_rate=0.0003,      # 佣金万分之三
-    stamp_duty_rate=0.001,       # 印花税千分之一
-    slippage=0.001               # 滑点 0.1%
-)
+from qka import Backtest
+
+bt = Backtest(data, MyStrategy(cash=100_000))
 bt.run(benchmark='000300.SH')
+print(bt.summary())    # 输出绩效指标
+bt.report()            # 生成 HTML 报告
 ```
 
-> 💡 详细教程 👉 [qka.quantai.chat](https://qka.quantai.chat)
+### 更多示例
 
-## 特性一览
-
-| 特性 | 说明 |
+| 策略 | 说明 |
 |------|------|
-| 🚀 **极简 API** | 统一的 `Data`/`Strategy`/`Backtest` 三件套，上手零门槛 |
-| 📊 **A 股数据** | 基于 Akshare，覆盖全市场 A 股数据 |
-| ⚡ **并发下载** | 多线程批量拉数据，几百只股票秒级完成 |
-| 🔄 **高效回测** | 时间序列引擎，天然支持多股票横截面处理 |
-| 📈 **HTML 报告** | 一键生成自包含的交互式回测报告，浏览器直接打开 |
-| 📉 **基准对比** | 自动获取沪深300做基准，曲线叠加展示 |
-| 💰 **成本模型** | 佣金/印花税/滑点全支持，贴近实盘 |
-| 🔧 **模块化** | 核心、经纪商、MCP、Server 各模块可独立使用 |
-| 📝 **文档完善** | [qka.quantai.chat](https://qka.quantai.chat) |
-
-## 核心模块
+| [买入持有与定投](https://qka.quantai.chat/examples/buy_and_hold/) | 买入不动 + 每月定投 |
+| [均线交叉](https://qka.quantai.chat/examples/ma_cross/) | 5日线上穿/下穿20日线 |
+| [RSI + ATR 风控](https://qka.quantai.chat/examples/rsi_atr/) | RSI 超卖买入，ATR 止损 |
+| [动量排序选股](https://qka.quantai.chat/examples/momentum/) | 月度动量排序，Top 5 等权 |
+| [多因子打分](https://qka.quantai.chat/examples/multi_factor/) | PE/ROE/动量/波动率打分选股 |
 
-### Data — 数据获取
-多数据源、自动缓存、并发下载、统一格式。支持日线/分钟线，前复权/后复权。
+## 核心能力
 
-### Strategy — 策略编写
-事件驱动框架，在 `on_bar` 里写你的交易逻辑，`get()` 拿到当前截面数据做决策。
+- **多数据源** — baostock（默认）、akshare、QMT，自动缓存
+- **预计算指标** — sma/ema/macd/rsi/bbands/atr + 自定义因子
+- **事件驱动回测** — 按日推进，`self.get()` 横截面 + `self.history()` 窗口序列
+- **仓位管理** — `self.sizing.percent()` / `self.sizing.fixed_amount()` / `self.sizing.fixed_shares()` / `self.sizing.atr_risk()`
+- **交易模拟** — 佣金万2.5、印花税万5、滑点0.1%，最低佣金5元
+- **HTML 报告** — Plotly 交互图表，累计收益、回撤、月度热力图、交易明细
+- **基准对比** — 自动下载沪深300（或指定指数）做对比
 
-### Backtest — 回测引擎
-时间序列驱动，支持多资产、成本模型、基准对比。`run()` 执行，`report()` 出报告，`summary()` 打印绩效指标。
+## 文档
 
-### Brokers — 实盘交易（建设中）
-集成 QMT 接口，客户端/服务器架构，支持远程交易。
+完整教程、API 参考、示例代码：
 
-## 文档站
+👉 **[qka.quantai.chat](https://qka.quantai.chat)**
 
-完整文档、API 参考、最佳实践：
+## 下一步规划
 
-👉 **[qka.quantai.chat](https://qka.quantai.chat)**
+- [ ] 分钟级数据支持
+- [ ] 自适应参数优化
+- [ ] 实盘交易（QMT 接口）
 
 ## 许可证
 
@@ -199,11 +190,11 @@ bt.run(benchmark='000300.SH')
 
 ## 致谢
 
-- [Akshare](https://github.com/akfamily/akshare) — 免费 A 股数据源
+- [baostock](http://baostock.com) — 免费 A 股数据
+- [Akshare](https://github.com/akfamily/akshare) — 补充数据源
 - [Plotly](https://plotly.com/python/) — 交互式图表
-- [FastAPI](https://fastapi.tiangolo.com/) — API 框架
-- [xtquant](https://github.com/ShiMiaoYS/xtquant) — QMT Python 接口
+- [xtquant](https://github.com/ShiMiaoYS/xtquant) — QMT 接口
 
 ---
 
-> ⚠️ 量化交易存在风险，请充分了解风险后再使用本框架。作者不对任何投资损失负责。
+> ⚠️ 量化交易存在风险，请充分了解后再使用本框架。

qka-1.6.5.dev5/README.md

@@ -0,0 +1,136 @@
+# QKA — 快量化
+## Quant Kit for A-shares
+
+<p align="center">
+  <a href="https://qka.quantai.chat" target="_blank">
+    <img src="https://img.shields.io/badge/文档站-qka.quantai.chat-blue?style=flat" alt="文档站">
+  </a>
+  <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
+
+class MyStrategy(Strategy):
+    def on_bar(self, date):
+        close = self.get('close')
+        for sym in close.index:
+            if sym not in self.broker.positions:
+                price = float(close[sym])
+                if price > 0:
+                    size = self.sizing.percent(0.1, price)
+                    if size >= 100:
+                        self.broker.buy(sym, price, size)
+
+bt = Backtest(Data(['000001.SZ']), MyStrategy(cash=100_000))
+bt.run(benchmark='000300.SH')
+bt.report()
+```
+
+---
+
+## 安装
+
+```bash
+pip install qka
+```
+
+需要 Python 3.10+。
+
+## 快速上手
+
+### 数据
+
+```python
+from qka import Data
+
+data = Data(
+    symbols=['000001.SZ', '600000.SH'],
+    indicators={'sma_5': ('sma', 5), 'rsi_14': ('rsi', 14)},
+)
+df = data.get()  # 触发下载，返回宽表 DataFrame
+```
+
+### 策略
+
+```python
+from qka import Strategy
+
+class MyStrategy(Strategy):
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
+        # 自定义状态放这里
+
+    def on_bar(self, date):
+        close = self.get('close')
+        hist = self.history('close', 20)
+        # 写你的交易逻辑
+```
+
+### 回测
+
+```python
+from qka import Backtest
+
+bt = Backtest(data, MyStrategy(cash=100_000))
+bt.run(benchmark='000300.SH')
+print(bt.summary())    # 输出绩效指标
+bt.report()            # 生成 HTML 报告
+```
+
+### 更多示例
+
+| 策略 | 说明 |
+|------|------|
+| [买入持有与定投](https://qka.quantai.chat/examples/buy_and_hold/) | 买入不动 + 每月定投 |
+| [均线交叉](https://qka.quantai.chat/examples/ma_cross/) | 5日线上穿/下穿20日线 |
+| [RSI + ATR 风控](https://qka.quantai.chat/examples/rsi_atr/) | RSI 超卖买入，ATR 止损 |
+| [动量排序选股](https://qka.quantai.chat/examples/momentum/) | 月度动量排序，Top 5 等权 |
+| [多因子打分](https://qka.quantai.chat/examples/multi_factor/) | PE/ROE/动量/波动率打分选股 |
+
+## 核心能力
+
+- **多数据源** — baostock（默认）、akshare、QMT，自动缓存
+- **预计算指标** — sma/ema/macd/rsi/bbands/atr + 自定义因子
+- **事件驱动回测** — 按日推进，`self.get()` 横截面 + `self.history()` 窗口序列
+- **仓位管理** — `self.sizing.percent()` / `self.sizing.fixed_amount()` / `self.sizing.fixed_shares()` / `self.sizing.atr_risk()`
+- **交易模拟** — 佣金万2.5、印花税万5、滑点0.1%，最低佣金5元
+- **HTML 报告** — Plotly 交互图表，累计收益、回撤、月度热力图、交易明细
+- **基准对比** — 自动下载沪深300（或指定指数）做对比
+
+## 文档
+
+完整教程、API 参考、示例代码：
+
+👉 **[qka.quantai.chat](https://qka.quantai.chat)**
+
+## 下一步规划
+
+- [ ] 分钟级数据支持
+- [ ] 自适应参数优化
+- [ ] 实盘交易（QMT 接口）
+
+## 许可证
+
+[MIT](LICENSE)
+
+## 致谢
+
+- [baostock](http://baostock.com) — 免费 A 股数据
+- [Akshare](https://github.com/akfamily/akshare) — 补充数据源
+- [Plotly](https://plotly.com/python/) — 交互式图表
+- [xtquant](https://github.com/ShiMiaoYS/xtquant) — QMT 接口
+
+---
+
+> ⚠️ 量化交易存在风险，请充分了解后再使用本框架。

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/examples/buy_and_hold.md

@@ -12,9 +12,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class BuyAndHold(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
         self.bought = False
 
     def on_bar(self, date):
@@ -50,9 +49,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class MonthlyDCA(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
 
     def on_bar(self, date):
         # 每月 1 号买入

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/examples/ma_cross.md

@@ -12,9 +12,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class MaCross(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
 
     def on_bar(self, date):
         close = self.get('close')
@@ -78,9 +77,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class MultiMaCross(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=1_000_000)
+    def __init__(self, cash=1_000_000):
+        super().__init__(cash=cash)
 
     def on_bar(self, date):
         close = self.get('close')

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/examples/momentum.md

@@ -10,9 +10,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class Momentum(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=1_000_000)
+    def __init__(self, cash=1_000_000):
+        super().__init__(cash=cash)
         self.last_month = None
 
     def on_bar(self, date):

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/examples/multi_factor.md

@@ -10,9 +10,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class MultiFactor(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=1_000_000)
+    def __init__(self, cash=1_000_000):
+        super().__init__(cash=cash)
         self.last_month = None
 
     def on_bar(self, date):

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/examples/rsi_atr.md

@@ -10,9 +10,8 @@ from qka import Data, Strategy, Broker, Backtest
 
 
 class RsiAtrStrategy(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=1_000_000)
+    def __init__(self, cash=1_000_000):
+        super().__init__(cash=cash)
 
     def on_bar(self, date):
         close = self.get('close')

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/guides/strategy.md

@@ -7,12 +7,11 @@
 ## 基本结构
 
 ```python
-from qka import Strategy, Broker
+from qka import Strategy
 
 class MyStrategy(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
 
     def on_bar(self, date):
         close = self.get('close')
@@ -80,9 +79,8 @@ size = self.sizing.atr_risk(0.02, price, atr)    # ATR 风控仓位
 
 ```python
 class MyStrategy(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
         self.bought = False          # 自定义状态
         self.entry_prices = {}        # 入场价格记录
 ```

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/guides/trading.md

@@ -41,12 +41,12 @@ self.broker.sell('000001.SZ', price, size)
 
 ```python
 self.broker.cash           # 当前可用资金（¥85,000）
-self.broker.positions      # {'000001.SZ': {'size': 1000, 'cost_basis': 10.2}}
+self.broker.positions      # {'000001.SZ': {'size': 1000, 'avg_price': 10.2}}
 ```
 
 `positions` 中每只股票包含：
 - `size` — 持仓股数
-- `cost_basis` — 平均买入成本
+- `avg_price` — 平均买入成本
 
 ## 完整的买卖流程
 
@@ -70,7 +70,7 @@ def on_bar(self, date):
         # 涨幅超过 20% 则卖出
         else:
             pos = self.broker.positions[sym]
-            cost = pos['cost_basis']
+            cost = pos['avg_price']
             if price / cost - 1 > 0.2:
                 self.broker.sell(sym, price, pos['size'])
 ```

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/docs/index.md

@@ -5,8 +5,7 @@ from qka import Data, Strategy, Broker, Backtest
 
 class MyStrategy(Strategy):
     def __init__(self):
-        super().__init__()
-        self.broker = Broker(100_000)
+        super().__init__(cash=100_000)
     def on_bar(self, date):
         close = self.get('close')
         if close is not None and '000001.SZ' in close.index:
@@ -39,9 +38,8 @@ from qka import Data, Strategy, Broker, Backtest
 class BuyAndHold(Strategy):
     """买入平安银行，一直持有"""
 
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
         self.bought = False
 
     def on_bar(self, date):
@@ -119,9 +117,8 @@ bt.report(title='买入持有策略')
 from qka import Data, Strategy, Broker, Backtest
 
 class BuyAndHold(Strategy):
-    def __init__(self):
-        super().__init__()
-        self.broker = Broker(initial_cash=100_000)
+    def __init__(self, cash=100_000):
+        super().__init__(cash=cash)
         self.bought = False
 
     def on_bar(self, date):

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: QKA - 快量化文档
-site_description: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
+site_description: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 site_author: QKA Team
 site_url: https://qka.quantai.chat
 use_directory_urls: true

{qka-1.6.4.dev3 → qka-1.6.5.dev5}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "qka"
 dynamic = ["version"]
-description = "快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架"
+description = "QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架"
 authors = [{name = "myc", email = "mayuanchi1029@gmail.com"}]
 readme = "README.md"
 license = {file = "LICENSE"}

qka-1.6.5.dev5/skills/qka/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: qka
+description: >
+  QKA 框架使用技能。当用户需要基于 QKA 框架编写 A 股量化策略、运行回测、
+  处理股票数据、生成报告时使用。涵盖 QKA 全部核心 API 的使用方法。
+---
+
+# QKA 框架技能
+
+## 概述
+
+QKA 是一个 A 股量化交易回测框架。核心流程：
+
+```
+Data(symbols) → Strategy(策略类) → Backtest(回测) → Report(报告)
+                  ↑
+          indicators(预计算指标)
+```
+
+**类名约束：** 自定义策略类必须命名为 `MyStrategy`，继承 `Strategy`
+
+## 能力边界
+
+**能做的策略类型：**
+- 趋势跟踪（双均线、海龟突破、MACD）
+- 均值回归（RSI、Bollinger Bands）
+- 多因子选股（PE/ROE/动量/波动率打分选股，周期 rebalance）
+- 等权/市值加权组合
+- 定投（固定间隔买入固定金额）
+- 大盘 MA 择时、股债轮动
+
+**做不了的：**
+- 分钟级/高频（无分钟数据）
+- 期权、期货
+- 机器学习选股（无特征工程管道）
+- 实盘交易
+- 事件驱动（无财报/公告订阅）
+- 多周期策略（仅单周期）
+
+## A 股交易规则
+
+1. 买入股数必须是 100 的整数倍（一手）
+2. 价格必须 > 0 且不是 NaN
+3. 资金不足时不买入
+4. `sizing.percent()` 和 `sizing.fixed()` 已自动按手取整
+
+## 模块索引
+
+| 模块 | 文件 | 用途 |
+|---|---|---|
+| **Data** | references/data.md | 数据获取、缓存、预计算指标 |
+| **Strategy** | references/strategy.md | 策略编写、on_bar、get/history |
+| **Broker** | references/broker.md | 交易模拟、费用计算 |
+| **Sizing** | references/sizing.md | 仓位计算 |
+| **Backtest** | references/backtest.md | 回测引擎、benchmark |
+| **Report** | references/report.md | 回测报告生成 |
+
+按需查阅对应文件，每个文件包含精确的 API 签名、用法示例和常见错误。