qka 2.3.2.dev2__tar.gz → 2.4.0__tar.gz

{qka-2.3.2.dev2 → qka-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.3.2.dev2
+Version: 2.4.0
 Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Repository, https://github.com/zsrl/qka
@@ -137,6 +137,7 @@ print(bt.metrics['sharpe_ratio'])        # 夏普比率
 ## 核心能力
 
 - **数据获取** — 写个股票代码就能取到本地，自动缓存、自动补齐最新数据，重复使用秒读
+- **多数据源** — 内置 `tickflow`、`baostock`、`tdx` 三个行情源，改一个 `source=` 即可切换，各源缓存分目录存放、互不干扰
 - **技术指标** — 均线、MACD、RSI、ATR 等 ta 库全部指标，外加 α/β、夏普、最大回撤等内置指标，声明一下即可，策略里不用自己 rolling
 - **估值字段** — 换手率、涨跌幅、停牌与 ST 标记、市盈率、市净率等，需要哪些就取哪些
 - **模拟行情** — 一条 `Simulate` 就能造出单边上涨、单边下跌、来回震荡的走势，不必等真实行情，用来验证策略是不是真在按逻辑交易
@@ -200,6 +201,7 @@ print(bt.metrics['total_return_pct'])
 
 - [tickflow](https://tickflow.org) — 免费 A 股 / ETF / 可转债行情（默认数据源）
 - [baostock](http://baostock.com) — 免费 A 股数据（估值等扩展字段）
+- [通达信](https://www.tdx.com.cn) — 本机「TQ 版」客户端的行情（`source='tdx'`，仅 Windows）
 - [ta](https://github.com/bukosabino/ta) — 技术指标库
 
 ---

{qka-2.3.2.dev2 → qka-2.4.0}/README.md

@@ -86,6 +86,7 @@ print(bt.metrics['sharpe_ratio'])        # 夏普比率
 ## 核心能力
 
 - **数据获取** — 写个股票代码就能取到本地，自动缓存、自动补齐最新数据，重复使用秒读
+- **多数据源** — 内置 `tickflow`、`baostock`、`tdx` 三个行情源，改一个 `source=` 即可切换，各源缓存分目录存放、互不干扰
 - **技术指标** — 均线、MACD、RSI、ATR 等 ta 库全部指标，外加 α/β、夏普、最大回撤等内置指标，声明一下即可，策略里不用自己 rolling
 - **估值字段** — 换手率、涨跌幅、停牌与 ST 标记、市盈率、市净率等，需要哪些就取哪些
 - **模拟行情** — 一条 `Simulate` 就能造出单边上涨、单边下跌、来回震荡的走势，不必等真实行情，用来验证策略是不是真在按逻辑交易
@@ -149,6 +150,7 @@ print(bt.metrics['total_return_pct'])
 
 - [tickflow](https://tickflow.org) — 免费 A 股 / ETF / 可转债行情（默认数据源）
 - [baostock](http://baostock.com) — 免费 A 股数据（估值等扩展字段）
+- [通达信](https://www.tdx.com.cn) — 本机「TQ 版」客户端的行情（`source='tdx'`，仅 Windows）
 - [ta](https://github.com/bukosabino/ta) — 技术指标库
 
 ---

{qka-2.3.2.dev2 → qka-2.4.0}/qka/__init__.py

@@ -20,6 +20,8 @@ from qka.core.strategy import Strategy
 from qka.core.broker import Broker
 from qka.core.sizing import SizingAccessor
 from qka.core.analysis import Analysis, Segment, AlphaBeta
+# 通达信数据源：安装目录的设置与查询（source='tdx' 时使用）
+from qka.core.tdx import set_tdx_root, get_tdx_root_info
 
 # 子模块导入
 from qka import core, utils
@@ -29,6 +31,8 @@ __all__ = [
     'Data', 'Simulate', 'Backtest', 'Strategy', 'Broker', 'DataAccessor', 'SizingAccessor',
     # 分析
     'Analysis', 'Segment', 'AlphaBeta',
+    # 通达信数据源
+    'set_tdx_root', 'get_tdx_root_info',
     # 子模块
     'core', 'utils'
 ]

{qka-2.3.2.dev2 → qka-2.4.0}/qka/core/data.py

@@ -21,6 +21,7 @@ from typing import List, Optional, Callable, Union
 from qka.utils.logger import logger
 from qka.core import indicator
 from qka.core.simulate import Simulate
+from qka.core import tdx
 
 # qka 内置指标裸名集合，用于 dispatch 识别（无需 qka. 前缀）
 _QKA_BUILTIN_NAMES = frozenset({
@@ -64,16 +65,17 @@ class Data():
         period (str): 数据周期，如 '1d'、'1m' 等
         adjust (str): 复权方式，如 'qfq'、'hfq'、'bfq'
         indicators (dict | Callable): 预计算指标/因子
-        source (str): 数据源，默认 'tickflow'（可选 'baostock'）
+        source (str): 数据源，默认 'tickflow'（可选 'baostock'、'tdx'）
         pool_size (int): 并发下载线程数
         datadir (Path): 数据缓存目录
         target_dir (Path): 目标存储目录
         extra_fields (List[str]): 扩展字段（选股/估值用），如 ['peTTM', 'pbMRQ', 'turn']。
-            仅 'baostock' 源提供（可选值见 BAOSTOCK_EXTRA_FIELDS）；'tickflow' 源无扩展列，会忽略
+            仅 'baostock' 源提供（可选值见 BAOSTOCK_EXTRA_FIELDS）；'tickflow' 与
+            'tdx' 源无扩展列，会忽略
     """
     
     # 支持的行情源
-    SOURCES = ('tickflow', 'baostock')
+    SOURCES = ('tickflow', 'baostock', 'tdx')
 
     # baostock query_history_k_data_plus 完整支持的基础字段（除 date 索引外）
     BAOSTOCK_BASE_FIELDS = ["open", "high", "low", "close", "volume", "amount"]
@@ -92,6 +94,8 @@ class Data():
     # TickFlow 可提供的扩展字段：其历史日线固定返回 OHLCV + amount，
     # 无估值/换手率等扩展列（季报级 financials 不是每日序列，不接入）。
     TICKFLOW_EXTRA_FIELDS = []
+    # 通达信源当前只接行情（OHLCV + amount），暂无扩展列
+    TDX_EXTRA_FIELDS = []
 
     # parquet 元数据键：这只标的「已确认起点」——数据源在该日期之前没有更早的数据。
     # 没有它，请求起点只要早于缓存首日（往往只是撞上长假）就得白跑一趟网络去确认。
@@ -152,14 +156,17 @@ class Data():
                        仅供辅助计算（β/α 等），不参与指标计算
             period: 数据周期，如 '1d'（日线）、'1m'（分钟）
             adjust: 复权方式，'qfq'（前复权）、'hfq'（后复权）、'bfq'（不复权）
-            source: 数据来源，默认 'tickflow'（可选 'baostock'）。两者返回结构一致，
-                切换源不影响上层调用；差异见各源的扩展字段能力
+            source: 数据来源，默认 'tickflow'（可选 'baostock'、'tdx'）。各源返回结构一致，
+                切换源不影响上层调用；差异见各源的扩展字段能力。'tdx' 走本机安装的
+                「支持 TQ 策略」通达信客户端（仅 Windows，需客户端在运行），安装目录的定位
+                方式见 `qka.set_tdx_root` / `qka.get_tdx_root_info`
             pool_size: 并发下载线程数
             datadir: 缓存目录路径
             indicators: 预计算指标/因子，支持三种格式：
             extra_fields: 扩展字段列表（选股/估值用，如 ['peTTM', 'pbMRQ', 'turn']），
                 可选值见 BAOSTOCK_EXTRA_FIELDS —— 仅 'baostock' 源提供；
-                'tickflow' 源无扩展列，传入的扩展字段会被静默忽略（不报错、不生成该列）。
+                'tickflow' 与 'tdx' 源无扩展列，传入的扩展字段会被静默忽略
+                （不报错、不生成该列）。
                 追加的列同样遵循 {symbol}|{field} 命名，如 '600519.SH|peTTM'。注意：
                 首次下载后缓存字段固定，变更 extra_fields 会自动检测列缺失并重新下载对应股票。
 
@@ -217,8 +224,7 @@ class Data():
         self.warmup = warmup
 
         # 当前数据源实际支持的扩展字段（源能力不同，按源过滤）
-        whitelist = (self.BAOSTOCK_EXTRA_FIELDS if source == 'baostock'
-                     else self.TICKFLOW_EXTRA_FIELDS)
+        whitelist = self._extra_fields_whitelist(source)
 
         # extra_fields 校验 + 去重
         # 未知字段（拼写错误）报错；当前源提供不了的字段静默忽略
@@ -448,6 +454,14 @@ class Data():
             return True
         return any(f not in cols for f in self.extra_fields)
 
+    def _extra_fields_whitelist(self, source: str) -> List[str]:
+        """该数据源实际支持的扩展字段（源能力不同，按源过滤）。"""
+        if source == 'baostock':
+            return self.BAOSTOCK_EXTRA_FIELDS
+        if source == 'tdx':
+            return self.TDX_EXTRA_FIELDS
+        return self.TICKFLOW_EXTRA_FIELDS
+
     def _merged_extra_fields(self, path: Path) -> List[str]:
         """
         计算本次下载实际请求的扩展字段：当前 extra_fields 与缓存已有扩展列的并集。
@@ -462,8 +476,7 @@ class Data():
             existing = set(pq.read_schema(path).names)
         except Exception:
             return merged
-        whitelist = (self.BAOSTOCK_EXTRA_FIELDS if self.source == 'baostock'
-                     else self.TICKFLOW_EXTRA_FIELDS)
+        whitelist = self._extra_fields_whitelist(self.source)
         for f in whitelist:
             if f in existing and f not in merged:
                 merged.append(f)
@@ -712,7 +725,10 @@ class Data():
             if need_calendar:
                 sim_index = self._trading_index(sim_start, sim_end)
             if need_download:
-                if self.source == 'baostock':
+                # baostock 与 tdx 都是「进程级单例连接」（tdx 的 tq 类方法
+                # 共用同一 run_id），并发调用会共用同一连接状态，故逐个下载；
+                # tickflow 的客户端无此约束，可并发。
+                if self.source in ('baostock', 'tdx'):
                     for symbol in tqdm(need_download, desc="下载数据"):
                         try:
                             self._download(symbol, download_start, download_end)
@@ -1106,6 +1122,8 @@ class Data():
         """按当前数据源分发到对应实现，返回结构一致（date 索引 + OHLCV/amount）。"""
         if self.source == 'baostock':
             return self._get_from_baostock(symbol, start_date, end_date, extra_fields)
+        if self.source == 'tdx':
+            return self._get_from_tdx(symbol, start_date, end_date, extra_fields)
         return self._get_from_tickflow(symbol, start_date, end_date, extra_fields)
 
     # ── TickFlow 数据源 ────────────────────────────────────────
@@ -1164,6 +1182,11 @@ class Data():
         market, code = cls._split_symbol(symbol)
         return f"{code}.{market.upper()}"
 
+    @classmethod
+    def to_tdx_symbol(cls, symbol: str) -> str:
+        """任意写法 → 通达信写法，如 600519.SH（与 tickflow 同形）"""
+        return cls.to_tickflow_symbol(symbol)
+
     def _get_from_tickflow(
         self, symbol: str,
         start_date: str = '1990-01-01',
@@ -1235,3 +1258,93 @@ class Data():
         for col in self.BAOSTOCK_BASE_FIELDS:
             df[col] = pd.to_numeric(df[col], errors='coerce')
         return df
+
+    # ── 通达信数据源（本机 TQ 版客户端，仅 Windows）────────────────
+
+    # 通达信 get_market_data 字段名 → qka 标准列名
+    TDX_FIELD_MAP = {
+        'Open': 'open', 'High': 'high', 'Low': 'low',
+        'Close': 'close', 'Volume': 'volume', 'Amount': 'amount',
+    }
+
+    def _get_from_tdx(
+        self, symbol: str,
+        start_date: str = '1990-01-01',
+        end_date: str = '2050-12-31',
+        extra_fields: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        从本机「支持 TQ 策略」的通达信客户端获取单只标的的日线数据。
+
+        返回结构与 _get_from_baostock 一致（date 索引 + open/high/low/close/
+        volume/amount），两处口径在本源内直接对齐：
+        - **volume**：通达信给的就是「股」，与 baostock 口径一致，原样使用
+        - **amount**：通达信单位是「万元」，×10000 换算成「元」
+
+        复权由通达信自己按 dividend_type 算好（front=前复权 / back=后复权 /
+        none=不复权），本处只做口径映射，不自行计算复权。
+
+        取数前必须先 ``refresh_kline``：通达信本地只存「下载过」的 K 线，直接查
+        没下载过的标的只会得到最新一根（历史静默缺失）。refresh_kline 让客户端
+        把该标的的 K 线补齐，本地已有时也会很快返回。
+
+        extra_fields 对通达信行情无意义（当前仅接行情，无扩展列），此处不处理。
+        """
+        # 周期映射（当前仅日线）
+        period_map = {'1d': '1d'}
+        if self.period not in period_map:
+            raise RuntimeError(
+                f"tdx 源暂不支持周期 {self.period!r}（可选: {list(period_map)}）"
+            )
+
+        # 复权映射：通达信 front=前复权 / back=后复权 / none=不复权
+        adjust_map = {'bfq': 'none', 'qfq': 'front', 'hfq': 'back'}
+        dividend_type = adjust_map.get(self.adjust, 'front')
+
+        tdx_symbol = self.to_tdx_symbol(symbol)
+        tq = tdx.get_tq()
+
+        # 通达信只认 YYYYMMDD
+        start = pd.Timestamp(start_date).strftime('%Y%m%d')
+        end = pd.Timestamp(end_date).strftime('%Y%m%d')
+
+        # 先让客户端补齐该标的的 K 线（失败返回 None），否则历史会静默缺失
+        if tq.refresh_kline(stock_list=[tdx_symbol],
+                            period=period_map[self.period]) is None:
+            raise RuntimeError(
+                f"通达信刷新 K 线缓存失败（{tdx_symbol}）："
+                "请确认「TQ 版通达信」客户端已启动并已登录。"
+            )
+
+        try:
+            raw = tq.get_market_data(
+                stock_list=[tdx_symbol],
+                start_time=start,
+                end_time=end,
+                dividend_type=dividend_type,
+                period=period_map[self.period],
+            )
+        except Exception as e:  # noqa: BLE001
+            raise RuntimeError(f"通达信查询 {symbol}({tdx_symbol}) 失败: {e}") from e
+
+        # 无任何数据时返回空 dict
+        if not raw:
+            return pd.DataFrame()
+
+        # 每张字段表都是「日期为索引、列为代码」的宽表，只取当前这一列
+        cols = {}
+        for src, dst in self.TDX_FIELD_MAP.items():
+            tbl = raw.get(src)
+            if tbl is None or tdx_symbol not in getattr(tbl, 'columns', []):
+                return pd.DataFrame()
+            cols[dst] = tbl[tdx_symbol]
+
+        df = pd.DataFrame(cols)
+        df.index = pd.DatetimeIndex(df.index)
+        df.index.name = 'date'
+        df['amount'] = df['amount'] * 10000            # 万元 → 元
+        df = df[df['close'].notna()]                   # 去掉多标的并集索引带出的空行
+        df = df[~df.index.duplicated(keep='last')].sort_index()
+        for col in self.BAOSTOCK_BASE_FIELDS:
+            df[col] = pd.to_numeric(df[col], errors='coerce')
+        return df

qka-2.4.0/qka/core/tdx.py

@@ -0,0 +1,207 @@
+"""
+通达信（TQ）数据源支持
+
+qka 通过本机安装的「支持 TQ 策略」的通达信客户端取数：在进程内 ``import tqcenter``
+（该模块随客户端自带），由 ``tqcenter`` 加载客户端目录下的 ``TPythClient.dll`` 与本机
+运行中的 ``TdxW.exe`` 通信。因此本数据源：
+
+- 仅支持 Windows；
+- 要求用它的机器上装着 TQ 版通达信，且客户端在运行。
+
+「通达信装在哪」是**这台机器怎么连上它**的问题，与「这次要取什么数据」（Data 的
+symbols/period/adjust 等）无关，故独立于 Data 管理：优先用代码显式设置的，其次看
+环境变量 ``QKA_TDX_ROOT``，最后自动从注册表识别。
+"""
+
+import os
+import sys
+import threading
+from pathlib import Path
+from typing import List, Optional
+
+from qka.utils.logger import logger
+
+# 环境变量：指向「支持 TQ 策略」的通达信安装目录
+ENV_VAR = 'QKA_TDX_ROOT'
+
+# 判定「是不是 TQ 版」的标志文件（相对安装目录）。普通版没有这个模块。
+_TQ_MARKER = ('PYPlugins', 'user', 'tqcenter.py')
+
+# 代码级设置（优先级最高，见 set_tdx_root）
+_code_root: Optional[Path] = None
+
+# 进程级复用：tqcenter 的 tq 是类级单例连接，全进程共用一个实例
+_tq_client = None
+_tq_lock = threading.Lock()
+
+
+# ── 路径：识别 / 设置 / 查询 ────────────────────────────────────
+
+def _is_tq_install(root: Path) -> bool:
+    """目录是否是一套带 TQ 组件的通达信安装（依据标志文件是否存在）。"""
+    try:
+        return root.joinpath(*_TQ_MARKER).is_file()
+    except OSError:
+        return False
+
+
+def _iter_registry_tdx_dirs() -> List[str]:
+    """枚举注册表「卸载」表里所有含「通达信」的安装目录。
+
+    覆盖 HKLM / HKCU 两个配置单元，并显式尝试 32 位与 64 位两个视图
+    （TQ 版注册名形如「通达信金融终端64」）。非 Windows 或读不到时返回空列表。
+    """
+    try:
+        import winreg
+    except ImportError:
+        return []
+
+    sub = r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"
+    hives = (winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER)
+    views = (winreg.KEY_WOW64_64KEY, winreg.KEY_WOW64_32KEY, 0)
+
+    found: List[str] = []
+    for hive in hives:
+        for view in views:
+            try:
+                key = winreg.OpenKey(hive, sub, 0, winreg.KEY_READ | view)
+            except OSError:
+                continue
+            try:
+                idx = 0
+                while True:
+                    try:
+                        name = winreg.EnumKey(key, idx)
+                    except OSError:
+                        break
+                    idx += 1
+                    try:
+                        sk = winreg.OpenKey(key, name)
+                    except OSError:
+                        continue
+                    display = _reg_value(sk, "DisplayName")
+                    location = _reg_value(sk, "InstallLocation")
+                    if location and display and "通达信" in str(display):
+                        found.append(str(location))
+            finally:
+                key.Close()
+    return found
+
+
+def _reg_value(key, name: str):
+    """读一个注册表值，不存在返回 None。"""
+    import winreg
+    try:
+        return winreg.QueryValueEx(key, name)[0]
+    except OSError:
+        return None
+
+
+def set_tdx_root(path) -> Path:
+    """显式指定「支持 TQ 策略」的通达信安装目录（优先级最高）。
+
+    Args:
+        path: 安装目录，如 ``r'D:\\new_tdx64'``
+
+    Returns:
+        Path: 规范化后的目录
+
+    Raises:
+        ValueError: 目录下没有 TQ 组件（``PYPlugins/user/tqcenter.py``）
+    """
+    global _code_root
+    root = Path(path).expanduser()
+    if not _is_tq_install(root):
+        raise ValueError(
+            f"{root} 不是支持 TQ 策略的通达信目录（未找到 "
+            f"{Path(*_TQ_MARKER)}）。请指向装有 TQ 组件的那套安装。"
+        )
+    _code_root = root
+    logger.info(f"已指定通达信安装目录: {root}")
+    return root
+
+
+def get_tdx_root_info() -> dict:
+    """查询「当前会使用哪个通达信目录、以及它是怎么来的」。
+
+    只做识别、**不建立连接**，因此可在客户端未启动时安全调用（如界面展示）。
+
+    Returns:
+        dict: ``{'root': str | None, 'source': 'code' | 'env' | 'auto' | None}``
+
+        - ``source='code'``：代码里 ``set_tdx_root()`` 指定的
+        - ``source='env'``：环境变量 ``QKA_TDX_ROOT`` 指定的
+        - ``source='auto'``：从注册表自动识别到的
+        - ``root=None``：以上都没有找到
+    """
+    if _code_root is not None:
+        return {'root': str(_code_root), 'source': 'code'}
+
+    env = os.environ.get(ENV_VAR)
+    if env and _is_tq_install(Path(env)):
+        return {'root': str(Path(env)), 'source': 'env'}
+
+    for candidate in _iter_registry_tdx_dirs():
+        root = Path(str(candidate).rstrip('\\/'))
+        if _is_tq_install(root):
+            return {'root': str(root), 'source': 'auto'}
+
+    return {'root': None, 'source': None}
+
+
+def resolve_tdx_root() -> Path:
+    """取当前生效的通达信目录；找不到时给出可照做的三条出路。"""
+    info = get_tdx_root_info()
+    if info['root']:
+        return Path(info['root'])
+    raise RuntimeError(
+        "未找到支持 TQ 策略的通达信安装目录。请任选其一：\n"
+        "  1) 安装「支持 TQ 策略」的通达信（new_tdx64 版）\n"
+        f"  2) 设置环境变量 {ENV_VAR} 指向其安装目录\n"
+        "  3) 在代码里调用 qka.set_tdx_root(r'...')"
+    )
+
+
+# ── 连接：惰性加载 tqcenter 并初始化 ────────────────────────────
+
+def get_tq():
+    """惰性加载并返回通达信的 TQ 客户端（进程级复用、线程安全）。
+
+    首次调用时：定位安装目录 → 把 ``PYPlugins/user`` 加入 sys.path → ``import tqcenter``
+    → ``tq.initialize(...)``。之后复用同一实例。
+
+    Returns:
+        tqcenter.tq: 通达信数据访问类
+
+    Raises:
+        RuntimeError: 未找到安装目录 / 加载 TQ 模块失败 / 初始化失败（客户端未启动等）
+    """
+    global _tq_client
+    if _tq_client is not None:
+        return _tq_client
+
+    with _tq_lock:
+        if _tq_client is not None:
+            return _tq_client
+
+        root = resolve_tdx_root()
+        plugin_dir = root.joinpath('PYPlugins', 'user')
+        if str(plugin_dir) not in sys.path:
+            sys.path.insert(0, str(plugin_dir))
+
+        try:
+            from tqcenter import tq
+        except Exception as e:  # noqa: BLE001 - 原样上报给调用方
+            raise RuntimeError(f"加载通达信 TQ 模块失败（{plugin_dir}）: {e}") from e
+
+        # 初始化参数只是一个标识用的「策略文件路径」，不要求文件真实存在
+        try:
+            tq.initialize(str(Path(__file__).resolve()))
+        except Exception as e:  # noqa: BLE001
+            raise RuntimeError(
+                "通达信 TQ 初始化失败：请确认客户端（TdxW.exe）已启动。"
+                f"\n原始错误: {e}"
+            ) from e
+
+        _tq_client = tq
+        return _tq_client

{qka-2.3.2.dev2 → qka-2.4.0}/skills/qka/references/data.md

@@ -23,10 +23,10 @@ data = Data(
 | `symbols` | `list[str \| Simulate]` | `None` | 标的列表。元素可以是 A 股代码（**`代码.市场`**，如 `'000001.SZ'`、`'600000.SH'`；也兼容 `sz.000001` 旧写法），也可以是 `Simulate` 对象（模拟标的），两者可混排，见下方「模拟标的」 |
 | `period` | `str` | `'1d'` | 数据周期，当前仅支持 `'1d'` |
 | `adjust` | `str` | `'qfq'` | 复权方式：`'qfq'` 前复权，`'hfq'` 后复权，`'bfq'` 不复权 |
-| `source` | `str` | `'tickflow'` | 数据源。`'tickflow'`（默认）行情覆盖全，**含 ETF / 可转债全历史**；`'baostock'` 提供估值等扩展字段（见 `extra_fields`） |
+| `source` | `str` | `'tickflow'` | 数据源。`'tickflow'`（默认）行情覆盖全，**含 ETF / 可转债全历史**；`'baostock'` 提供估值等扩展字段（见 `extra_fields`）；`'tdx'` 走本机「TQ 版」通达信客户端（仅 Windows，需客户端在运行），仅行情、无扩展字段，安装目录见下方「通达信数据源」 |
 | `benchmark` | `str` | `None` | 基准指数代码，如 `'000300.SH'`。下载后在 `get()` 结果中追加 `benchmark|returns` 列 |
 | `indicators` | `dict` | `None` | 预计算指标，见下方 |
-| `extra_fields` | `list[str]` | `None` | 扩展字段（选股/估值用）。**仅 `source='baostock'` 提供**；`tickflow` 源无这些列，传入会被静默忽略，见下方 |
+| `extra_fields` | `list[str]` | `None` | 扩展字段（选股/估值用）。**仅 `source='baostock'` 提供**；`tickflow` / `tdx` 源无这些列，传入会被静默忽略，见下方 |
 | `warmup` | `int` | `0` | 指标预热天数。回测/取数时自动多读 `warmup` 个交易日历史用于计算指标，使第 1 个交易日即拿到有效指标值（无需手写跳过前 N 根 bar）。仅用于计算，不增加回测 bar 数 |
 
 > **warmup（指标预热）**：若指标/因子需要较长历史窗口（如动量排名需看前 200 天），设 `warmup=200`。
@@ -47,6 +47,30 @@ data = Data(
 |------|------|------|
 | `returns` | `close.diff() / close.shift(1)` | 日收益率，始终存在，无需在 indicators 中声明 |
 
+### 通达信数据源
+
+`source='tdx'` 走本机安装的「支持 TQ 策略」通达信客户端（在进程内 `import tqcenter`，由客户端与本机 `TdxW.exe` 通信）。前提与边界：
+
+- **仅 Windows**，且用它的机器需装着 TQ 版通达信、**客户端在运行**、并已登录；
+- **只接行情**（日线 OHLCV + 成交额），**没有** `extra_fields` 扩展列；
+- 复权由通达信自己按 `adjust` 算好（`qfq`→前复权 / `hfq`→后复权 / `bfq`→不复权），qka 不另算。
+
+安装目录的定位与查询（只有该源需要）：
+
+```python
+import qka
+
+qka.get_tdx_root_info()            # {'root': 'D:\\new_tdx64', 'source': 'auto'} —— 只做识别，不建连接，可随时查
+qka.set_tdx_root(r'D:\new_tdx64')  # 代码里显式指定（优先级最高）
+```
+
+优先级：`set_tdx_root()` > 环境变量 `QKA_TDX_ROOT` > 自动读注册表识别。三者都没有时，取数会抛出带解决步骤的 `RuntimeError`。
+
+```python
+data = Data(symbols=['600519.SH'], source='tdx', adjust='qfq')
+df = data.get(start_date='2024-01-01', end_date='2026-10-09')
+```
+
 ### 模拟标的
 
 `symbols` 的元素除了真实代码字符串，还可以是 `Simulate` 对象——一只由 qka **现场生成**的行情，不下载、不读缓存。写法与真实标的完全同构：
@@ -98,7 +122,7 @@ r_t = drift + reversion * (logAnchor - logP_{t-1}) + vol * eps_t        eps_t ~
 
 `extra_fields` 追加扩展列（选股/估值用），列名同样遵循 `{symbol}|{field}` 约定（如 `000001.SZ|peTTM`），数值自动转为 `float64`。**不是指标，不参与 indicators 预计算**，是随行情一起下载的原始字段。
 
-> ⚠️ **仅 `source='baostock'` 提供**：这些扩展列来自 baostock 的 `query_history_k_data_plus` 接口。默认源 `'tickflow'` 的历史日线固定只有 OHLCV + 成交额，**没有**这些扩展列——此时传入的 `extra_fields` 会被静默忽略（不报错、也不生成对应列）。需要估值/换手率等字段时，显式用 `Data(..., source='baostock')`。
+> ⚠️ **仅 `source='baostock'` 提供**：这些扩展列来自 baostock 的 `query_history_k_data_plus` 接口。默认源 `'tickflow'` 与 `'tdx'` 的历史日线固定只有 OHLCV + 成交额，**没有**这些扩展列——此时传入的 `extra_fields` 会被静默忽略（不报错、也不生成对应列）。需要估值/换手率等字段时，显式用 `Data(..., source='baostock')`。
 
 **不传 `extra_fields` 时，每只股票默认只有 6 个行情列 + 1 个常驻列：**