tdxquant 0.1.0__tar.gz

tdxquant-0.1.0/.gitignore

@@ -0,0 +1,211 @@
+# Byte-compiled / optimized / DLL files
+.idea
+
+# 敏感配置文件
+qdata-core/config.yaml
+*.db
+__pycache__/
+*.py[codz]
+*$py.class
+.tmp*
+# C extensions
+*.so
+.venv/
+data
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+settings.local.json
+.db/

tdxquant-0.1.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+`tdx-api`（包名 `tdx_api`，主类 `TdxAPI`）是通达信量化（TdxQuant）的 HTTP SDK。**不经过任何中间网关、DLL 或 tqcenter.py**——直接 `POST http://127.0.0.1:17709/`（通达信客户端原生监听端口），由 SDK 内部完成字段重命名与 `pandas.DataFrame` 封装。
+
+> 历史上项目曾采用"FastAPI 网关 + tqcenter DLL"双层架构，已删除。`docs/superpowers/specs/2026-06-13-tdx-quant-sdk-design.md` 第三节的网关描述是历史设计，**现状以本文件与 `README.md` 为准**。
+
+## 依赖文档
+通达信量化相关文档位置 :  ../../docs/TdxQuant_doc
+
+
+
+## 常用命令
+
+```bash
+uv sync                                  # 安装依赖（用 .venv，禁止直接动全局 Python）
+uv run pytest                            # 单元测试（字段血缘契约 + DataFrame 拼装，不依赖网络）
+uv run pytest --runintegration           # 集成测试（需通达信客户端在线监听 17709）
+uv run pytest tests/test_schema.py::test_kline_lineage   # 跑单个测试
+uv run pytest -k snapshot                # 按关键字筛选
+```
+
+集成测试默认跳过，必须显式加 `--runintegration` 才运行（见 `tests/conftest.py`）。
+
+## 架构要点（big picture）
+
+### 1. HTTP 协议约定
+
+- 请求体：`{"id": 1, "method": "<tqcenter 方法名>", "params": {...}}`，响应体：`{"id": 1, "result": {...}}`。
+- `method` 是 tqcenter 的底层函数名（如 `get_market_data` / `get_market_snapshot`），**不是** SDK 的方法名。
+- `result.ErrorId != "0"` 时抛 `TdxQuantError(message, error_id)`；网络层错误抛 `TdxQuantConnectionError`。
+- 客户端强制 `trust_env=False`，绕过系统代理（Clash/V2Ray 会劫持 localhost 导致 502）。
+
+### 2. 组合式 mixin 架构
+
+`TdxAPI` 通过多继承组合 5 个 mixin + `_ClientBase`（顺序见 `tdx_api/__init__.py`）：
+- `_ClientBase`（`client.py`）——HTTP 调用 + DataFrame 拼装工具，是唯一持有 HTTP 状态的基类。
+- `MarketMixin` / `FinancialMixin` / `SectorMixin` / `InstrumentMixin` / `CalendarMixin`——纯业务接口，只调用 `self._call(...)` 和 `self._<拼装工具>(...)`。
+
+新增数据接口的做法：在对应 mixin 加方法，调用 `_call` + 已有的拼装工具；若返回结构特殊，在 `_ClientBase` 加一个 `_xxx_to_df` 解析器。
+
+### 3. 字段血缘：schema.py 是唯一真实来源
+
+`tdx_api/schema.py` 中的 `*_FIELD_MAP`（`KLINE_FIELD_MAP` / `SNAPSHOT_FIELD_MAP` / `STOCK_INFO_FIELD_MAP` / `DIVIDEND_FIELD_MAP` / `CB_FIELD_MAP` / `ETF_FIELD_MAP` / `IPO_FIELD_MAP`）定义了 tqcenter 原字段 → SDK 规范字段（snake_case）的映射。
+
+- **改映射必须三处同步**：`schema.py` 的 map → `tests/test_schema.py` 的血缘断言 → `docs/field_lineage.md` 的文档表。`test_schema.py` 是契约测试，锁住字段血缘不漂移，所有新字段断言为合法 snake_case。
+- 未命中映射的原字段：**转小写保留**（不丢弃、不报错）。
+- 专业财务/交易数据编码字段（`FNxxx` / `GPx` / `BKx` / `SCx` / `GOx`）无通用金融命名，一律转小写保留（`Fn193` → `fn193`）。
+
+### 4. 日期与枚举归一化（enums.py）
+
+- 所有对外日期参数经 `validate_date` 校验，严格 `YYYYMMDD`（分钟线 `YYYYMMDDHHMMSS`）；空串/None 视为"不限制"。
+- `Freq` / `Adjust` 用 SDK 友好写法（`daily` / `qfq`），内部经 `freq_to_period` / `adjust_to_dividend` 转成 tqcenter 的 `period`（`1d`）/ `dividend_type`（`front`）。
+
+### 5. 底层参数名陷阱
+
+不同业务接口的"字段筛选"参数名不同，SDK 对外统一叫 `fields`，但传给 `_call` 时要换成底层名：
+- 行情类（`get_market_data` / `get_market_snapshot` / `get_stock_info`）→ `field_list`
+- **财务/交易数据类**（`get_financial_data` / `get_gpjy_value` / `get_bkjy_value` / `get_scjy_value` / `get_gp_one_data`）→ `table_list`
+
+`get_financial` 的底层 `end_time` 必填，`end_date` 留空时 SDK 自动取当天。
+
+### 6. DataFrame 拼装工具（_ClientBase）
+
+结果形态决定用哪个解析器：
+- `_build_kline`：`result.Value.{stock}.{field:[list]}` → OHLCV 长表（行=时间×证券，列含 `datetime, code, open...`）。
+- `_stock_value_to_df`：`result.Value.{stock:{field:[list]}}` → 财务长表，编码字段转小写。
+- `_flat_value_to_df`：`result.Value` 为扁平 dict / `{field:[list]}` / list。
+- `_dict_to_row` + `_rows_to_df`：单证券 dict → 一行（自动转数值、过滤 `ErrorId`/`Error`/`run_id` 元字段）。
+- `_list_to_df`：str 列表→单列 code；dict 列表→自动成表。
+
+`_maybe_numeric` 会尝试转数值类型，但**保留 list/dict 单元格**（五档盘口 bid_prices 等不能被压平）。
+
+### 7. get_snapshot 并发
+
+`get_snapshot` 传入多个代码时用 `ThreadPoolExecutor` 并发（默认 `max_workers=16`），httpx.Client 线程安全复用。**通达信服务端并行上限约 12~16**，超过 ~20 会因排队变慢，不要盲目调大并发。
+
+## 测试约定
+
+- 单元测试（`test_client_unit.py`）用 `TdxAPI.__new__(TdxAPI)` 跳过 HTTP 初始化，只测纯数据拼装方法——新增拼装工具时按此模式补测。
+- 集成测试（`test_integration.py`）顶部 `pytestmark = pytest.mark.integration`，整个模块默认跳过。
+
+## 约定与注意事项
+
+- 所有代码注释、docstring、commit message 使用**中文**；对外对话也用中文。
+- 不要创建未经声明的英文文件名（专业术语如 API/SDK/HTTP 除外）。
+- 数据接口统一返回 `DataFrame`；缓存/下载类（`refresh_cache` / `refresh_kline` / `download_file`）返回 dict。
+- Python ≥ 3.13；依赖走清华 PyPI 镜像（`pyproject.toml` 的 `[[tool.uv.index]]`）。
+- 证券代码格式：6 位 + 市场后缀（`000001.SZ` / `600519.SH` / `.BJ` / `.JJ`）。

tdxquant-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: tdxquant
+Version: 0.1.0
+Summary: 通达信量化(TdxQuant) HTTP SDK —— 统一返回 DataFrame，字段金融规范化(snake_case)
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: orjson>=3.11.9
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# tdx-api
+
+通达信量化（TdxQuant）**HTTP SDK** —— 直接调用通达信客户端官方 HTTP 接口（`POST http://127.0.0.1:17709/`），统一返回 `pandas.DataFrame`，字段重命名为金融行业规范的 **snake_case**。
+
+## 工作方式
+
+通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）：
+
+```
+你的代码(SDK) ──HTTP/JSON──► 通达信客户端(127.0.0.1:17709)
+```
+
+1. 启动支持 TQ 的通达信客户端（它会监听 `127.0.0.1:17709`）
+2. SDK 直接 POST 调用，字段重命名 + DataFrame 封装在 SDK 内完成
+
+> 请求格式：`{"id":1, "method":"<tqcenter方法名>", "params":{...}}`，`method` 为 tqcenter 函数名，`params` 为底层参数名。
+
+## 安装
+
+```bash
+uv sync          # 本地开发
+# 或 pip install -e .
+```
+
+> 需要 Python ≥ 3.13、通达信金融终端（量化模拟版 / 专业研究版等支持 TQ 策略的版本）。
+
+## 快速开始
+
+```python
+from tdx_api import TdxAPI
+
+api = TdxAPI()   # 默认 http://127.0.0.1:17709，需通达信客户端在线
+
+# K线（OHLCV 长表）
+df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
+# 实时快照
+snap = api.get_snapshot("000001.SZ")
+# 股票 / 板块 / ETF
+api.get_stock_list()                   # 所有分类合并(带 market/category 列)
+api.get_sector_list()
+api.get_track_etf("000300.SH")
+# 财务
+api.get_financial("600519.SH", fields=["Fn193","Fn194"], start_date="20240101")
+# 交易日历
+api.get_trading_calendar("20260101", "20260613")
+```
+
+从别的机器调用：`TdxAPI(base_url="http://通达信机器IP:17709")`。
+
+## 接口总览
+
+| 类别 | 方法 | 说明 |
+|---|---|---|
+| 行情 | `get_kline` | K线（OHLCV 长表） |
+| | `get_snapshot` | 实时快照（五档） |
+| | `get_instrument_info` / `get_more_info` | 基本信息 |
+| | `get_dividend_factors` | 分红送配 |
+| 财务 | `get_financial` / `get_financial_by_date` | 专业财务（FNxxx） |
+| | `get_stock_trade_data(_by_date)` | 股票交易（GPx） |
+| | `get_sector_trade_data(_by_date)` | 板块交易（BKx） |
+| | `get_market_trade_data(_by_date)` | 市场交易（SCx） |
+| | `get_stock_single_data` | 单点数据（GOx） |
+| | `get_share_capital(_by_date)` | 股本数据 |
+| 板块 | `get_stock_list` | 分类成分股（market 不传返回全部，带 market/category 列） |
+| | `get_sector_list` / `get_user_sectors` | 板块列表 |
+| | `get_sector_stocks` | 板块成分股 |
+| 证券 | `get_convertible_bond` | 可转债 |
+| | `get_ipo_info` | 新股/新债申购 |
+| | `get_track_etf` | 跟踪指数的 ETF |
+| 日历 | `get_trading_dates` / `get_trading_calendar` | 交易日 |
+
+> 交易类（`order_stock`）按需求不做。完整参数与字段说明见 [`docs/api_reference.md`](docs/api_reference.md)。
+
+## 字段命名规范
+
+- 全部 **snake_case 小写**，采用金融行业惯例（OHLCV / bid-ask / nav / pct_chg）。
+- 原字段 → 新字段完整血缘见 [`docs/field_lineage.md`](docs/field_lineage.md)。
+- 通达信专业编码字段（`FNxxx`/`GPx` 等）保留转小写，需对照通达信字段手册。
+
+代码格式：`000001.SZ` / `600519.SH`（6 位 + 市场后缀）；频率 `daily/5min/...`；
+复权 `none/qfq/hfq`；日期严格 `YYYYMMDD`（区间用 `start_date`/`end_date`，按日期点用 `date`）。
+
+## 测试
+
+```bash
+uv run pytest                     # 单元测试（字段血缘契约 + 拼装逻辑）
+uv run pytest --runintegration    # 集成测试（需通达信客户端在线）
+```
+
+## 项目结构
+
+```
+tdx_api/
+├── client.py          # HTTP 客户端（POST 17709）+ DataFrame 拼装
+├── schema.py          # 字段血缘映射表（唯一真实来源）
+├── enums.py           # Freq / Adjust 枚举 + validate_date 日期校验
+├── exceptions.py      # 异常
+└── api/               # 各业务接口（mixin）
+    ├── market.py  financial.py  sector.py  instrument.py  calendar.py
+```
+
+## 常见问题
+
+- **`server return none` / 连接失败**：确认通达信客户端已启动并登录行情；SDK 默认连 `127.0.0.1:17709`。
+- **`502 Bad Gateway`**：本机代理（Clash/V2Ray）劫持 localhost 请求。SDK 已默认 `trust_env=False` 直连，若仍异常请关闭代理。
+- **财务/专业数据为空**：需先在通达信客户端下载对应盘后/专业财务数据。
+- **`get_financial` 报 end_time 缺失**：底层要求结束日期，`end_date` 留空时 SDK 自动取当天。

tdxquant-0.1.0/README.md

@@ -0,0 +1,107 @@
+# tdx-api
+
+通达信量化（TdxQuant）**HTTP SDK** —— 直接调用通达信客户端官方 HTTP 接口（`POST http://127.0.0.1:17709/`），统一返回 `pandas.DataFrame`，字段重命名为金融行业规范的 **snake_case**。
+
+## 工作方式
+
+通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）：
+
+```
+你的代码(SDK) ──HTTP/JSON──► 通达信客户端(127.0.0.1:17709)
+```
+
+1. 启动支持 TQ 的通达信客户端（它会监听 `127.0.0.1:17709`）
+2. SDK 直接 POST 调用，字段重命名 + DataFrame 封装在 SDK 内完成
+
+> 请求格式：`{"id":1, "method":"<tqcenter方法名>", "params":{...}}`，`method` 为 tqcenter 函数名，`params` 为底层参数名。
+
+## 安装
+
+```bash
+uv sync          # 本地开发
+# 或 pip install -e .
+```
+
+> 需要 Python ≥ 3.13、通达信金融终端（量化模拟版 / 专业研究版等支持 TQ 策略的版本）。
+
+## 快速开始
+
+```python
+from tdx_api import TdxAPI
+
+api = TdxAPI()   # 默认 http://127.0.0.1:17709，需通达信客户端在线
+
+# K线（OHLCV 长表）
+df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
+# 实时快照
+snap = api.get_snapshot("000001.SZ")
+# 股票 / 板块 / ETF
+api.get_stock_list()                   # 所有分类合并(带 market/category 列)
+api.get_sector_list()
+api.get_track_etf("000300.SH")
+# 财务
+api.get_financial("600519.SH", fields=["Fn193","Fn194"], start_date="20240101")
+# 交易日历
+api.get_trading_calendar("20260101", "20260613")
+```
+
+从别的机器调用：`TdxAPI(base_url="http://通达信机器IP:17709")`。
+
+## 接口总览
+
+| 类别 | 方法 | 说明 |
+|---|---|---|
+| 行情 | `get_kline` | K线（OHLCV 长表） |
+| | `get_snapshot` | 实时快照（五档） |
+| | `get_instrument_info` / `get_more_info` | 基本信息 |
+| | `get_dividend_factors` | 分红送配 |
+| 财务 | `get_financial` / `get_financial_by_date` | 专业财务（FNxxx） |
+| | `get_stock_trade_data(_by_date)` | 股票交易（GPx） |
+| | `get_sector_trade_data(_by_date)` | 板块交易（BKx） |
+| | `get_market_trade_data(_by_date)` | 市场交易（SCx） |
+| | `get_stock_single_data` | 单点数据（GOx） |
+| | `get_share_capital(_by_date)` | 股本数据 |
+| 板块 | `get_stock_list` | 分类成分股（market 不传返回全部，带 market/category 列） |
+| | `get_sector_list` / `get_user_sectors` | 板块列表 |
+| | `get_sector_stocks` | 板块成分股 |
+| 证券 | `get_convertible_bond` | 可转债 |
+| | `get_ipo_info` | 新股/新债申购 |
+| | `get_track_etf` | 跟踪指数的 ETF |
+| 日历 | `get_trading_dates` / `get_trading_calendar` | 交易日 |
+
+> 交易类（`order_stock`）按需求不做。完整参数与字段说明见 [`docs/api_reference.md`](docs/api_reference.md)。
+
+## 字段命名规范
+
+- 全部 **snake_case 小写**，采用金融行业惯例（OHLCV / bid-ask / nav / pct_chg）。
+- 原字段 → 新字段完整血缘见 [`docs/field_lineage.md`](docs/field_lineage.md)。
+- 通达信专业编码字段（`FNxxx`/`GPx` 等）保留转小写，需对照通达信字段手册。
+
+代码格式：`000001.SZ` / `600519.SH`（6 位 + 市场后缀）；频率 `daily/5min/...`；
+复权 `none/qfq/hfq`；日期严格 `YYYYMMDD`（区间用 `start_date`/`end_date`，按日期点用 `date`）。
+
+## 测试
+
+```bash
+uv run pytest                     # 单元测试（字段血缘契约 + 拼装逻辑）
+uv run pytest --runintegration    # 集成测试（需通达信客户端在线）
+```
+
+## 项目结构
+
+```
+tdx_api/
+├── client.py          # HTTP 客户端（POST 17709）+ DataFrame 拼装
+├── schema.py          # 字段血缘映射表（唯一真实来源）
+├── enums.py           # Freq / Adjust 枚举 + validate_date 日期校验
+├── exceptions.py      # 异常
+└── api/               # 各业务接口（mixin）
+    ├── market.py  financial.py  sector.py  instrument.py  calendar.py
+```
+
+## 常见问题
+
+- **`server return none` / 连接失败**：确认通达信客户端已启动并登录行情；SDK 默认连 `127.0.0.1:17709`。
+- **`502 Bad Gateway`**：本机代理（Clash/V2Ray）劫持 localhost 请求。SDK 已默认 `trust_env=False` 直连，若仍异常请关闭代理。
+- **财务/专业数据为空**：需先在通达信客户端下载对应盘后/专业财务数据。
+- **`get_financial` 报 end_time 缺失**：底层要求结束日期，`end_date` 留空时 SDK 自动取当天。

tdxquant-0.1.0/docs/api_reference.md

@@ -0,0 +1,139 @@
+# 接口参考（tdx_api.TdxAPI）
+
+> 字段血缘见 [`field_lineage.md`](field_lineage.md)。所有数据接口返回 `pandas.DataFrame`；
+> 缓存/下载类操作返回 `dict`。
+
+## 构造
+
+```python
+TdxAPI(base_url="http://127.0.0.1:17709", timeout=120.0)
+```
+
+直连通达信客户端官方 HTTP 端口（需客户端在线）。支持 `with TdxAPI(...) as api:` 上下文。
+`api.health()` 返回连通状态 dict。
+
+## 代码与参数约定
+
+- **证券代码**：`000001.SZ` / `600519.SH` / `000300.SH`（6 位 + 市场后缀）。
+- **频率 `freq`**：`1min / 5min / 15min / 30min / 60min / daily / weekly / monthly`。
+- **复权 `adjust`**：`none` 不复权 / `qfq` 前复权 / `hfq` 后复权。
+- **日期**：统一字符串 `YYYYMMDD`（如 `20260613`），分钟线可 `YYYYMMDDHHMMSS`。严格校验，格式不符报错。区间型参数用 `start_date` / `end_date`，按日期点型用 `date`。
+
+---
+
+## 行情类
+
+### `get_kline(code, freq="daily", adjust="none", start_date="", end_date="", fields=None, fill_data=True)`
+
+K线数据，返回 OHLCV 长表。
+
+| 参数 | 说明 |
+|---|---|
+| `code` | 证券代码或列表 |
+| `freq` | 频率 |
+| `adjust` | 复权类型 |
+| `start_date` / `end_date` | 日期区间 `YYYYMMDD`（控制返回范围） |
+| `fields` | 返回字段筛选（原字段名） |
+| `fill_data` | 是否填充缺失 |
+
+返回列：`datetime, code, open, high, low, close, volume, amount, forward_factor, open_interest`
+
+### `get_snapshot(code, fields=None, max_workers=16)`
+
+实时快照，索引 `code`。返回五档买卖、昨收/现价/涨速等（见字段血缘快照表）。
+
+多个代码默认走线程池并发（复用同一 `httpx.Client`）：单次约 3.5ms，全市场 5500+ 只约 **5s**（串行约 19s）。
+`max_workers=None` 或 `1` 退回串行；注意通达信客户端服务端并行上限约 12~16，超过 20 会因排队变慢。
+
+### `get_instrument_info(code, fields=None)` / `get_more_info(code, fields=None)`
+
+证券基本信息 / 更多信息，索引 `code`。
+
+### `get_dividend_factors(code, start_date="", end_date="")`
+
+分红送配，index 为除权除息日。列：`div_type, cash_dividend, rights_price, share_bonus, rights_issue`。
+
+---
+
+## 财务类
+
+> 字段为通达信编码（`FNxxx`/`GPx`/`BKx`/`SCx`/`GOx`），SDK 转小写保留；返回长表带 `code` 列。
+> 专业财务需客户端先下载专业财务数据。
+
+### `get_financial(stock_list, fields=None, start_date="", end_date="", report_type="report_time")`
+专业财务。`report_type`: `report_time`(截止日) / `announce_time`(公告日)。
+
+### `get_financial_by_date(stock_list, fields=None, date="")`
+指定日期专业财务（`date` 为报告期 `YYYYMMDD`）。
+
+### `get_stock_trade_data(stock_list, fields=None, start_date="", end_date="")` / `get_stock_trade_data_by_date(stock_list, fields=None, date="")`
+股票交易数据（`GPx`）。
+
+### `get_sector_trade_data(...)` / `get_sector_trade_data_by_date(...)`
+板块交易数据（`BKx`），参数同上（区间用 `start_date`/`end_date`，按日期用 `date`）。
+
+### `get_market_trade_data(fields=None, start_date="", end_date="")` / `get_market_trade_data_by_date(fields=None, date="")`
+市场交易数据（`SCx`，无个股维度）。
+
+### `get_stock_single_data(stock_list, fields=None)`
+单点数据（`GOx`，非序列）。
+
+### `get_share_capital(code, date_list=None, count=1)` / `get_share_capital_by_date(code, start_date="", end_date="")`
+股本数据（总股本 / 流通股本等）。
+
+---
+
+## 板块 / 分类
+
+### `get_stock_list(market=None)`
+分类成分股，返回 `code, market, category` 三列。`market` 不传则遍历所有主要分类（所有A股 / 沪深主板 / 沪深300 / 中证500 / 中证1000 / ETF / 可转债 / 创业板 / 科创板 / 北交所等）合并返回，同一股票属于多个分类时出现多行；传具体值（如 `"5"` / `"23"`）只返回该分类。`category` 为中文分类名，完整映射见 `sector.py` 的 `STOCK_CATEGORY`。
+
+### `get_sector_list(list_type=0)`
+全部板块，列 `code, name`。
+
+### `get_user_sectors()`
+用户自定义板块，列 `code, name`。
+
+### `get_sector_stocks(block_code, block_type=0, list_type=0)`
+板块成分股，返回单列 `code`。`block_code` 可为板块代码（`880081.SH`）或名称（`钛金属`）；
+`block_type=1` 时传入自定义板块简称。
+
+---
+
+## 证券
+
+### `get_convertible_bond(code, fields=None)`
+可转债信息。列：`bond_code, underlying_code, conversion_price, coupon_rate, ...`
+
+### `get_ipo_info(ipo_type=0, ipo_date=0)`
+新股/新债申购。`ipo_type`: 0 全部 / 1 新债 / 2 新股；`ipo_date`: 0 今天 / 1 今天及以后。
+列：`code, name, subscribe_date, subscribe_price, subscribe_code, max_subscribe, issue_pe`。
+
+### `get_track_etf(zs_code)`
+跟踪指定指数的 ETF。列：`code, name, last_price, pre_close, iopv, total_share, scale`。
+
+---
+
+## 日历 / 缓存
+
+### `get_trading_dates(market="SH", start_date="", end_date="", count=-1)`
+交易日列表，列 `date`。需客户端下载上证指数（999999）盘后数据。
+
+### `get_trading_calendar(start_date, end_date, market="SH")`
+交易日历，列 `date`。`market` 默认 SH（上交所）。
+
+### `refresh_cache(market="AG", force=False) -> dict`
+刷新行情缓存。
+
+### `refresh_kline(stock_list, period="") -> dict`
+缓存历史 K线（仅 1m/5m/1d）。
+
+### `download_file(code, down_time="", down_type=1) -> dict`
+下载十大股东（`down_type=1`）/ ETF 申赎清单（`down_type=2`）。
+
+---
+
+## 异常
+
+- `TdxQuantError`：业务错误（网关返回 `error_id != 0`），含 `.error_id` / `.error_msg`。
+- `TdxQuantConnectionError`：网络/连接错误。