zlt-ai-tools

给 Python 用的智量通量化工具包。

一、能做什么

装上它，你的程序可以：

一句话：你写公式，它负责编译、取数、算出来，还能告诉你这个因子有没有用。

装完还会带上一批命令行程序（zlt-formula、zlt-datafeed、zlt-trade 等）， 装在环境的 bin/Scripts 里，直接就能敲。

不需要装 Node.js、Go 或其他语言运行时。每个平台架构一个轮子，pip 自动挑。

二、先拿账号

除公式计算外的能力都要账号——行情、问数、检索都在服务端。

# 扫码登录，拿到 API Key 并存进本机凭据库
zlt-qrlogin -identity gateway-api-key -entry <给这把钥匙起个名>

跑起来会存一张二维码图片并告诉你路径，用微信扫它，确认之后钥匙自动落库。 钥匙不会打印在屏幕上，也不进日志和命令行参数——程序取用时从凭据库读， 人不需要看见它。

如果这个微信还没绑手机号，会让你补一次短信验证；照提示做即可。

只算公式、不取数的话，这一步可以跳过。

三、怎么用

算一条公式

from zlt_ai_tools import native

compiled = native.formula.compile(dialect="tdx",
                                  source="OUT:(CLOSE-MA(CLOSE,20))/MA(CLOSE,20);")
bars = native.datafeed.bars(symbol="SH600519", frequency="1d", limit=120)
result = native.formula.execute(handle=compiled["handle"], payload=bars["value"])
native.formula.free(handle=compiled["handle"])       # 用完还回去
print(result["value"][-1])                            # 最新一根的因子值

评一个因子有没有用

from zlt_ai_tools import research

report = research.run_factor_study(
    symbols=["SH600519", "SZ000001", "SH601318", "SZ000858",
             "SH600036", "SZ002415", "SH601899", "SZ300750"],
    start="2026-01-01", end="2026-06-30",
    dialect="tdx", source="OUT:(CLOSE-MA(CLOSE,20))/MA(CLOSE,20);",
    quantiles=5,
)
print(report.ic_mean)           # 因子与下一期收益的相关性
print(report.top_minus_bottom)  # 最高一层减最低一层的收益
print(report.turnover_mean)     # 换手率：太高就吃不到收益
for line in report.diagnostics:
    print(line)                 # 跳过的期、取不到的标的都在这

三个指标要一起看：相关性再高，分层不单调多半是被极端值带的； 前两项再好，换手率覆盖不了成本也是纸面收益。

看有哪些能力可以调

from zlt_ai_tools import native
print(native.version())    # 版本
print(native.actions())    # 全部动作，形如 "formula.compile"、"datafeed.bars"
print(native.transport)    # 这一次走的是共享库还是协进程

方法名按 域.动作 组织，native.<域>.<动作>() 直接调。actions() 是从原生件 自报的清单生成的——以它为准，文档可能滞后，那份清单不会。

四、出问题时

手册在发布页的 manuals 包里（每个版本的 Release 附件），解压后打开 index.html。里面按能力线分卷：公式引擎、行情取数、在线搜索与问数、交易、 量化研究。

报问题时请附上 native.version() 与 native.transport 的输出——这两样决定 了排障从哪开始：版本对不上和通道不同，症状可能一模一样而原因完全不同。

附：技术细节

这些不影响使用，排障或做集成时才需要。

• 两条传输通道：优先走 C 共享库（进程内调用）；musl 发行版（Alpine 等） 上共享库加载不了，自动改走协进程——同一份实现、同一个调用面，transport 告诉你这次走的哪条。
• 包的构成：每个平台架构一个轮子，内含该平台的共享库或协进程程序， 外加同批命令行程序。行情轻客户端、交易客户端与量化研究能力包的源码已内联， 装它不需要另外解析依赖。
• 聚合面自己不实现业务算法：因子研究的计算在 zlt_quantresearcher， 取数与公式由聚合面注入——能力线不反向依赖包装层。
• 图表 SDK 不在本包公开面里：内含上游分支，公开分发要先过许可合规复核。