qka 1.8.1.dev2__tar.gz → 1.9.1.dev4__tar.gz

{qka-1.8.1.dev2 → qka-1.9.1.dev4}/PKG-INFO

@@ -1,9 +1,8 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.8.1.dev2
+Version: 1.9.1.dev4
 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
 Project-URL: Issues, https://github.com/zsrl/qka/issues
 Author-email: myc <mayuanchi1029@gmail.com>
@@ -35,28 +34,14 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: akshare>=1.16.93
-Requires-Dist: baostock>=0.8.9
+Requires-Dist: baostock>=0.9.1
 Requires-Dist: dask[dataframe]>=2025.7.0
-Requires-Dist: fastapi>=0.115.13
-Requires-Dist: flask>=3.1.1
-Requires-Dist: ipykernel>=6.29.5
-Requires-Dist: litellm>=1.81.14
-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
-Requires-Dist: xtquant>=241014.1.2
 Provides-Extra: dev
 Requires-Dist: hatch-vcs>=0.3.0; extra == 'dev'
-Requires-Dist: mkdocs-material>=9.6.14; extra == 'dev'
-Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
-Requires-Dist: mkdocstrings-python>=1.16.12; extra == 'dev'
-Requires-Dist: mkdocstrings>=0.29.1; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
@@ -66,9 +51,6 @@ Description-Content-Type: text/markdown
 ## 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>
@@ -85,20 +67,40 @@ Description-Content-Type: text/markdown
 ```python
 from qka import Data, Strategy, Backtest
 
-class MyStrategy(Strategy):
+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:
-            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()
+            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'])
 ```
 
 ---
@@ -119,10 +121,13 @@ pip install qka
 from qka import Data
 
 data = Data(
-    symbols=['000001.SZ', '600000.SH'],
-    indicators={'sma_5': ('sma', 5), 'rsi_14': ('rsi', 14)},
+    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
+df = data.get()  # 返回宽表 DataFrame，列名 {symbol}|{factor}
 ```
 
 ### 策略
@@ -131,14 +136,15 @@ df = data.get()  # 触发下载，返回宽表 DataFrame
 from qka import Strategy
 
 class MyStrategy(Strategy):
-    def __init__(self, cash=100_000):
-        super().__init__(cash=cash)
-        # 自定义状态放这里
+    def __init__(self):
+        super().__init__()
+        self.lookback = 20  # 自定义参数
 
     def on_bar(self, date):
-        close = self.get('close')
-        hist = self.history('close', 20)
-        # 写你的交易逻辑
+        close = self.get('close')            # 当前横截面
+        hist = self.history('close', 20)     # 历史窗口
+        # 交易逻辑：self.broker.buy / self.broker.sell
+        # 仓位计算：self.sizing.percent / self.sizing.fixed_shares
 ```
 
 ### 回测
@@ -146,37 +152,26 @@ class MyStrategy(Strategy):
 ```python
 from qka import Backtest
 
-bt = Backtest(data, MyStrategy(cash=100_000))
-bt.run(benchmark='000300.SH')
-print(bt.summary())    # 输出绩效指标
-bt.report()            # 生成 HTML 报告
+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'])        # 夏普比率
 ```
 
-### 更多示例
-
-| 策略 | 说明 |
-|------|------|
-| [买入持有与定投](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 + 自定义因子
+- **多数据源** — baostock（默认）、akshare、QMT
+- **预计算指标** — ta 库全部 60+ 指标，`('ta.trend.sma_indicator', 'close', 5)` 格式直接透传
 - **事件驱动回测** — 按日推进，`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（或指定指数）做对比
+- **仓位管理** — `sizing.percent()` / `sizing.fixed_amount()` / `sizing.fixed_shares()` / `sizing.atr_risk()`
+- **交易模拟** — 佣金万 2.5、印花税万 5（仅卖出）、滑点 0.1%，最低佣金 5 元
+- **绩效指标** — 总收益率、年化、夏普比率、最大回撤、Calmar、胜率、盈亏比等 13 项
+- **基准对比** — 支持沪深 300（或指定指数）对比
 
 ## 文档
 
-完整教程、API 参考、示例代码：
-
-👉 **[qka.quantai.chat](https://qka.quantai.chat)**
+框架 API 完整文档见 [skills/qka/SKILL.md](skills/qka/SKILL.md)——所有类的方法签名、参数、返回值和约束都在里面。
 
 ## 下一步规划
 
@@ -191,10 +186,9 @@ bt.report()            # 生成 HTML 报告
 ## 致谢
 
 - [baostock](http://baostock.com) — 免费 A 股数据
-- [Akshare](https://github.com/akfamily/akshare) — 补充数据源
-- [Plotly](https://plotly.com/python/) — 交互式图表
-- [xtquant](https://github.com/ShiMiaoYS/xtquant) — QMT 接口
+- [ta](https://github.com/bukosabino/ta) — 技术指标库
 
 ---
 
 > ⚠️ 量化交易存在风险，请充分了解后再使用本框架。
+充分了解后再使用本框架。

qka-1.9.1.dev4/README.md

@@ -0,0 +1,145 @@
+# 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-1.8.1.dev2 → qka-1.9.1.dev4}/pyproject.toml

@@ -18,30 +18,16 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "akshare>=1.16.93",
-    "fastapi>=0.115.13",
-    "flask>=3.1.1",
-    "mcp[cli]>=1.9.0",
-    "nbformat>=5.10.4",
     "plotly>=6.1.1",
-    "uvicorn>=0.34.3",
-    "xtquant>=241014.1.2",
-    "ipykernel>=6.29.5",
     "pyarrow>=21.0.0",
     "tqdm>=4.67.1",
     "dask[dataframe]>=2025.7.0",
-    "baostock>=0.8.9",
-    "litellm>=1.81.14",
-    "websockets>=16.0",
     "ta>=0.11.0",
+    "baostock>=0.9.1",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.14",
-    "mkdocstrings>=0.29.1",
-    "mkdocstrings-python>=1.16.12",
     "python-semantic-release>=9.0.0",
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
@@ -50,14 +36,11 @@ dev = [
 
 [project.urls]
 Home = "https://github.com/zsrl/qka"
-Documentation = "https://zsrl.github.io/qka"
 Repository = "https://github.com/zsrl/qka"
 Issues = "https://github.com/zsrl/qka/issues"
 
 [project.scripts]
-qka-zmq-server = "qka.server.zmq_server:main"
 qka = "qka.cli:main"
-qka-ws-client = "qka.server.ws_client:main"
 
 [tool.hatch.version]
 source = "vcs"

{qka-1.8.1.dev2 → qka-1.9.1.dev4}/qka/__init__.py

@@ -20,16 +20,11 @@ from qka.core.broker import Broker
 from qka.core.sizing import SizingAccessor
 
 # 子模块导入
-from qka import core, utils, mcp
-
-# 交易相关（有依赖的模块暂时不导入，避免导入错误）
-# from qka.brokers.trade import create_trader
-# from qka.brokers.client import QMTClient
-# from qka.brokers.server import QMTServer
+from qka import core, utils
 
 __all__ = [
     # 核心功能
     'Data', 'Backtest', 'Strategy', 'Broker', 'DataAccessor', 'SizingAccessor',
     # 子模块
-    'core', 'utils', 'mcp'
+    'core', 'utils'
 ]

qka-1.9.1.dev4/qka/cli.py

@@ -0,0 +1,21 @@
+"""
+QKA命令行接口
+"""
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description="QKA量化交易框架命令行工具")
+    parser.add_argument("--version", action="store_true", help="显示版本信息")
+
+    args = parser.parse_args()
+    if args.version:
+        from qka import __version__
+        print(f"qka {__version__}")
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

{qka-1.8.1.dev2 → qka-1.9.1.dev4}/qka/core/backtest.py

@@ -9,6 +9,9 @@ import numpy as np
 import dask.dataframe as dd
 from typing import Optional, Union
 from collections import defaultdict
+from qka.core.broker import Broker
+from qka.core.accessor import DataAccessor
+from qka.core.sizing import SizingAccessor
 
 
 class Backtest:
@@ -36,9 +39,20 @@ class Backtest:
         self.data = data
         self.strategy = strategy
         self.results = None
-        self.initial_cash = strategy.broker.cash
+        self.initial_cash = None  # 由 run() 设置
+        self.metrics = None
         self._benchmark_data = None
 
+    @property
+    def trade_history(self):
+        """逐笔交易明细（list[dict]）"""
+        return self.strategy.broker.trade_history if hasattr(self.strategy, 'broker') else []
+
+    @property
+    def trades(self):
+        """每日资金/市值/持仓快照（pd.DataFrame）"""
+        return self.strategy.broker.trades if hasattr(self.strategy, 'broker') else pd.DataFrame()
+
     @staticmethod
     def _parse_row(row):
         """
@@ -63,7 +77,9 @@ class Backtest:
             by_factor[factor][symbol] = val
         return dict(by_factor)
 
-    def run(self, benchmark: Optional[str] = None):
+    def run(self, cash: float = 100000.0,
+            start_date: str = None, end_date: str = None,
+            benchmark: Optional[str] = None):
         """
         执行回测
 
@@ -74,15 +90,23 @@ class Backtest:
         避免一次性加载全量数据。
 
         Args:
-            benchmark (str, optional): 基准代码，如 '000300.SH'（沪深300）。
-                                       如果提供，会下载基准数据用于对比。
+            cash: 初始资金，默认 10 万元
+            start_date: 回测起始日期 YYYY-MM-DD，None 表示数据最早日期
+            end_date: 回测截止日期 YYYY-MM-DD，None 表示数据最晚日期
+            benchmark: 基准代码，如 '000300.SH'（沪深300）。
+                       如果提供，会下载基准数据用于对比。
 
         Returns:
-            None。回测结果保存在 self.results 中，可通过
-            self.summary() 查看绩效指标，self.report() 生成报告。
+            None。回测结果保存在 self.results、self.metrics、self.trade_history 中。
         """
-        # 获取数据（优先用 lazy 模式，由 Backtest 决定是否分区）
-        raw = self.data.get(lazy=True)
+        # 注入基础设施
+        self.initial_cash = cash
+        self.strategy.broker = Broker(initial_cash=cash)
+        self.strategy.sizing = SizingAccessor(self.strategy.broker)
+        self.strategy._data = DataAccessor()
+
+        # 获取数据
+        raw = self.data.get(lazy=True, start_date=start_date, end_date=end_date)
 
         # 加载基准数据
         if benchmark:
@@ -137,6 +161,7 @@ class Backtest:
 
         # 保存回测结果
         self.results = self.strategy.broker.trades
+        self.metrics = self._compute_metrics()
 
     def _load_benchmark(self, benchmark_code: str):
         """
@@ -146,38 +171,27 @@ class Backtest:
             benchmark_code: 基准代码，如 '000300.SH'
         """
         try:
-            import akshare as ak
-            clean_code = benchmark_code.replace('.SH', '').replace('.SZ', '').replace('.BJ', '')
-            bm_df = ak.stock_zh_index_daily(symbol=f"sh{clean_code}")
+            from qka.core.data import Data
+            bm_data = Data(symbols=[benchmark_code], source='baostock')
+            bm_df = bm_data.get(lazy=False)
             if bm_df is not None and not bm_df.empty:
-                bm_df['date'] = pd.to_datetime(bm_df['date'])
-                bm_df = bm_df.set_index('date')
-                bm_df = bm_df.sort_index()
-                self._benchmark_data = bm_df['close']
+                # 提取 close 列（可能是多股票 MultiIndex，取第一只）
+                close_col = [c for c in bm_df.columns if 'close' in str(c).lower()]
+                if close_col:
+                    self._benchmark_data = bm_df[close_col[0]]
+                else:
+                    self._benchmark_data = bm_df.iloc[:, 0]
                 print(f"基准数据加载成功: {benchmark_code}，{len(bm_df)} 个交易日")
         except Exception as e:
             print(f"基准数据加载失败: {e}")
 
-    def summary(self) -> dict:
-        """
-        计算并打印回测绩效指标
-
-        返回包含以下指标的字典：
-        - 总收益率、年化收益率、年化波动率
-        - 夏普比率、最大回撤、Calmar比率
-        - 胜率、盈亏比、交易次数
-        - 最终资产、总手续费
-
-        Returns:
-            dict: 绩效指标字典
-        """
+    def _compute_metrics(self) -> dict:
+        """计算绩效指标。无数据时返回空 dict。"""
         if self.results is None or self.results.empty:
-            print("请先运行回测 (backtest.run())")
             return {}
 
         totals = self.results['total']
         if len(totals) < 2:
-            print("回测数据不足（至少需要2个交易周期）")
             return {}
 
         # 基本数据
@@ -192,7 +206,6 @@ class Backtest:
         # 日收益率序列
         daily_returns = totals.pct_change().dropna()
         if len(daily_returns) == 0:
-            print("没有足够的收益率数据")
             return {}
 
         # 年化收益率
@@ -257,30 +270,10 @@ class Backtest:
         else:
             win_rate = 0
             profit_loss_ratio = 0
-            trade_pnl = []
 
         # 总手续费
         total_commission = self.strategy.broker.total_commission
 
-        # 打印报告
-        print("=" * 55)
-        print("           回测绩效报告")
-        print("=" * 55)
-        print(f"  初始资金:        RMB {initial:>10,.2f}")
-        print(f"  最终资产:        RMB {final:>10,.2f}")
-        print(f"  总收益率:         {total_return:>+8.2f}%")
-        print(f"  年化收益率:       {annual_return * 100:>+8.2f}%")
-        print(f"  年化波动率:       {annual_vol * 100:>8.2f}%")
-        print(f"  夏普比率:         {sharpe:>8.2f}")
-        print(f"  最大回撤:         {max_drawdown:>8.2f}%")
-        print(f"  Calmar比率:       {calmar:>8.2f}")
-        print(f"  交易次数:         {n_trades:>8}")
-        print(f"  胜率:             {win_rate:>8.2f}%")
-        print(f"  盈亏比:           {profit_loss_ratio:>8.2f}")
-        print(f"  总手续费:         RMB {total_commission:>10,.2f}")
-        print(f"  回测天数:         {n_days:>8} 天")
-        print("=" * 55)
-
         return {
             'initial_cash': initial,
             'final_equity': final,