@zltai/ai-tools

给 Node.js 用的智量通量化工具包。

一、能做什么

装上它，你的程序可以：

| 你想做的事 | 用哪个 | |---|---| | 算技术指标、跑自己写的公式 —— 通达信、同花顺等方言的公式直接编译执行，136 个内置函数 | client.formula | | 取行情 —— K 线、分时、财务、板块分类、排行榜 | client.datafeed | | 查数据资产 —— 用自然语言找表、找字段、找证券 | client.aiquery | | 联网检索 —— 搜新闻、研报、政策、论文 | client.websearch | | 下单与查持仓（含仿真盘） | trade | | 轻量取行情 —— 不落盘、只发 HTTP，适合十来个副本的场景 | marketLight |

一句话：你写公式，它负责编译、取数、算出来。

不需要装 Python、Go 或任何其他语言运行时，只要 Node.js ≥ 20。 每个平台架构一个包，npm 会自动挑对的那个。

二、先拿账号

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

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

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

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

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

三、怎么用

import { client, marketLight, trade } from "@zltai/ai-tools";

// 算一条自己的公式：二十日乖离率
const compiled = client.formula.compile({
  dialect: "tdx",
  source: "OUT:(CLOSE-MA(CLOSE,20))/MA(CLOSE,20);",
});

// 取行情，喂给公式
const bars = client.datafeed.bars({ symbol: "SH600519", frequency: "1d", limit: 120 });
const result = client.formula.execute({ handle: compiled.handle, payload: bars.value });
client.formula.free({ handle: compiled.handle });   // 用完还回去
console.log(result.value.at(-1));                   // 最新一根的因子值

// 用自然语言找数据
const tables = client.aiquery.searchTables({ question: "沪深两市的日线在哪张表" });

// 联网检索
const news = client.websearch.search({ query: "央行 降准", limit: 5 });

看有哪些能力可以调：

import { actions, version, transport } from "@zltai/ai-tools";
console.log(version());     // 版本
console.log(actions());     // 全部动作，形如 "formula.compile"、"datafeed.bars"
console.log(transport);     // 这一次走的是共享库还是协进程

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

四、出问题时

| 症状 | 去哪看 | |---|---| | 装不上、找不到对应平台的包 | 手册「安装与平台覆盖」；先确认 Node ≥ 20 | | 调用报未授权 / 401 / 403 | 第二节重新扫码；钥匙可能过期或没绑到标识上 | | 公式编译报错 | 手册的方言分卷：不同方言的函数与语义不完全一样 | | 取数为空 | 手册「行情取数」：先确认代码写法与频率参数 | | 想知道某个动作收什么参数 | 手册的对应能力卷，或先 actions() 看它在不在 |

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

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

附：技术细节

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

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