tyquant 取数
把 A 股量化平台 tyquant 的线上接口封装成一个零依赖 CLI，覆盖两大能力：
股价预测 与 策略回测跟踪。数据与 tyquant H5 前端同源同口径。
何时使用
用户问到下列任一问题时启用：
- 「最近哪只股票涨得最多 / 有什么推荐」
- 「茅台下周/下月能涨到多少」「XX 的预测方向是什么」
- 「这个预测准不准 / 历史准确率多少」
- 「有哪些策略 / 某个策略收益回撤怎么样」
- 「某次回测的净值、调仓、持仓、风险指标」
不适用于：实盘下单、账户持仓、订阅状态（需 JWT，本技能不接）。
架构约定（改动脚本前必读）
本层是纯透传，只做四件事，不做第五件：
- 归一化 —— 口语（「茅台」「sh600519」）→ 后端代码格式。
- 取数 —— 调后端接口，带端点故障转移。
- 裁剪 —— 把数百 KB 响应压到 7KB 以内，避免打爆上下文。
- 元数据透传 ——
as_of/latest_bar_date/degraded/missing_fields原样带出。
凡是"算出来"的东西都不在这里做：可交易性过滤、排名噪声判定、区间可用性、
方向命中率、FIFO 盈亏、单位换算 —— 全部交给后端接口。本层一旦参与计算，
H5 前端与 AI 就会对同一只票给出两套结论。需要新字段时改后端接口，不要在这打补丁。
运行方式
脚本入口是 <skill>/scripts/tq.py（<skill> = 本 SKILL.md 所在目录）。
零第三方依赖，Python ≥ 3.8，Windows / Linux / macOS 均可直跑。
python <skill>/scripts/tq.py doctor # 连通性自检（排障第一步）
python <skill>/scripts/tq.py list # 列出全部 20 个工具
python <skill>/scripts/tq.py schema <tool> # 查看某工具参数
python <skill>/scripts/tq.py call <tool> --key value # 取数（推荐键值对传参）
python <skill>/scripts/tq.py resolve 山西汾酒 # 中文名 → 代码
传参方式二选一，推荐键值对（Windows 下 JSON 引号易出错）：
python <skill>/scripts/tq.py call stock_forecast --symbol 茅台 --horizon 3m
python <skill>/scripts/tq.py call stock_forecast '{"symbol":"600519.SS","horizon":"3m"}'
通用开关：--compact 输出单行紧凑 JSON（省 token，默认开启更佳）；
--timeout N 覆盖超时。退出码 0 成功 / 1 执行失败 / 2 用法错误 / 3 未知工具。
端点配置
优先级：环境变量 TYQUANT_BASE_URL（逗号分隔多个）→ 脚本同目录/上级 config.json
→ 内置默认值。所有端点按顺序尝试，第一个连通的被粘滞复用。
默认主入口 http://47.95.121.161:8888/api（直连后端），内置兜底 https://tyquant.tojoyai.com/api（走 SLB/nginx，供 :8888 停用后使用）。
必须以 /api 结尾 —— 该主机根路径是 H5 前端（Vite SPA），只有 /api 前缀才是后端接口。
⚠️ 兜底端点依赖 tyquant.tojoyai.com 配有有效 TLS 证书。证书未配好前该入口的证书校验会失败，
仅当主入口也连不上时才会被尝试并最终报错——排障时若两个端点都失败，优先检查主入口与网络。
export TYQUANT_BASE_URL="http://your-host:8888/api" # 换成自己的部署地址
export TYQUANT_API_KEY="你的key" # 可选：豁免服务端限流
服务端已启用 per-IP 限流（默认 120/分钟 + 40 突发），超额返回 429。
带合法 TYQUANT_API_KEY 的请求会随每个请求发出 X-API-Key 头并豁免限流；
未设置时不发任何鉴权头，行为不变。遇到 429 时提示用户配置该环境变量。
问题 → 命令 路由表
| 用户问法 | 命令 |
|---|---|
| 哪只涨得最多 / 今天买什么 | call dragon_tiger --top_n 20 --rank_by predicted_return |
| 哪个预测最可信 | call dragon_tiger --top_n 20 --rank_by direction_da |
| 某只票的预测 | call stock_forecast --symbol <标的> --horizon 1m |
| 某只票准不准 | call stock_direction_accuracy --symbol <标的> |
| 预测价 vs 实际价 | call stock_prediction_compare --symbol <标的> --n 20 |
| 系统整体预测水平 | call prediction_accuracy_summary |
| 大盘怎么样 | call market_overview |
| 某只票最近走势 | call stock_daily_bars --symbol <标的> --limit 30 |
| 某只票基本信息 | call stock_basics --symbol <标的> |
| 有哪些策略 | call strategy_list |
| 策略详情 | call strategy_detail --strategy_id <id> |
| 回测列表（取真实 run_id） | call backtest_runs --limit 20 |
| 净值/回撤曲线 | call backtest_nav_curve --run_id <run_id> |
| 调仓成交台账 | call backtest_trades --run_id <run_id> --limit 30 |
| 风险指标与归因 | call backtest_risk_metrics --run_id <run_id> |
| 最新持仓 | call backtest_positions --run_id <run_id> |
| 多个 run 对比 | call backtest_compare --run_ids <id1>,<id2> |
标准工作流
1. 选股（「哪只涨得多」）
不要逐只调用 stock_forecast —— 服务端已扫全市场，一次拿榜：
python <skill>/scripts/tq.py call dragon_tiger --top_n 20 --rank_by predicted_return --compact
回答时必须带上 as_of / updated_at（数据基准日），并说明这是模型预测而非实盘结果。
items[].direction_da 是该股历史方向准确率（小数，0.40 = 40%），
direction_da_n 是样本数 —— 样本数小的准确率不足为凭，回答时一并说明。
用户问「哪个判断最可信」时改用 --rank_by direction_da。
2. 单股预测
python <skill>/scripts/tq.py call stock_forecast --symbol 茅台 --horizon 3m
python <skill>/scripts/tq.py call stock_direction_accuracy --symbol 茅台
horizon 是交易日不是自然日：1w=下 1 个交易日，1m=5 个交易日，3m=20 个交易日。
close_predictions.h1/h5/h20 各自有 predicted_close、interval_lower/upper、
interval_status。interval_status 为 unavailable_* 时区间是 null，
说明该周期尚未完成严格样本外校准，不要拿别的口径脑补区间。
3. 策略 / 回测跟踪（顺序不能乱）
strategy_list 里的 run_id 来自 landed 快照，与回测历史库不同源。
查净值/成交/持仓前必须先换真实 run_id：
python <skill>/scripts/tq.py call strategy_list --limit 30
python <skill>/scripts/tq.py call backtest_runs --limit 20 # 取库中真实 run_id
python <skill>/scripts/tq.py call backtest_risk_metrics --run_id <真实run_id>
拿到 found=false + 「回测历史库中不存在」就是 run_id 用错了，回到 backtest_runs。
回答时的硬规矩
- 单位必须区分，否则百倍误差：
-/strategies、/history/runs的收益类字段是百分数（865.99 = 865.99%）
-/analysis.risk的max_drawdown/annualized_volatility/var_95是小数（-0.3793 = -37.93%）
-/prediction/*的da/pdr/rhr是小数（0.669 = 66.9%）
-dragon_tiger的predicted_return/prob_up是百分数 - 报数据必带基准日：
as_of/updated_at/latest_bar_date。落地数据有滞后属正常。 - 预测 ≠ 实盘：所有策略数字都是回测结果，回答时必须显式说明。
- 回测价 ≠ 行情价：
trades.price/positions.price/cost_basis是后复权价，
/tdx/daily是不复权实际成交价，同日同股不相等（个股复权因子实测 1.4× ~ 21×）。
看到数量级差异不是数据错误，跨源比价才需注意。 - 不自行过滤榜单：停牌/退市/ST 的剔除归后端 land 侧。本层看到什么报什么，
需要提示时在回答里如实说明，不静默剔除。 - 降级字段如实转述：
degraded/missing_fields非空时说明该维度数据缺失，
不要把降级后的排序当成用户要的排序（例如rank_by=prob_up会回退成score）。
完整口径清单、已知降级字段与排查手册见 references/caveats.md；
20 个工具的参数与后端端点对照见 references/api_catalog.md。
排障
接口报错时按顺序做：
python <skill>/scripts/tq.py doctor—— 看endpoint_used、health.status、
sample.as_of（样例数据基准日）。health.services.backtest.status = "disabled"是正常的（回测引擎为可选组件），
不代表服务不可用，也不影响/history/*系列读取已完成的回测。- 读
references/caveats.md的「排障决策树」一节，按错误类型定位。
