工作原理
模型提出方案。
SQAI 裁决。
智能体从不编写 SQL，也从不生成可执行代码。它写出一个类型化请求——每个请求都走同一条路径：对照固定合约验证，对照策略检查，由确定性引擎执行，并附带可供重放的哈希值返回。
每个请求——ask()、compute() 或 AI SDK 工具调用——都走同一条路径。所有检查通过之前，任何内容都不会触达引擎。
01类型化意图
引擎可解析的请求，而非需要信任的字符串。
模型输出的是类型化对象——从不是 SQL，从不是代码。查询意图是 QuerySpec：对具名数据源进行聚合的指标。计算意图是 ComputationSpec：合约中的具名函数，附带参数与绑定。一个可辨识联合类型，两种形态——两者均无处容纳可执行字符串。
这就是全部的创作空间。形态无法表达的，模型便无法请求。
QuerySpec结构解析{"kind": "query",联合标签——query 或 computation"version": "1",规范版本，已固定"source_name": "sales",已连接的数据源，按精确名称"metric": "revenue",待聚合的列"aggregation": "sum",sum · avg · count · min · max 之一"group_by": "region"可选——按字段拆分结果}同样可选filter · limit · order
计算形态module · function · args · kwargs · bindings · seed?
02合约校验
单一合约，哈希固定。未知请求被拒绝并附带指引。
规范对照能力合约进行验证——该合约是一个经哈希固定的生成文件，列出每项操作、其精确签名及确定性标志。能力可达的前提是：只读且确定性，或在给定种子时确定性。具备写入能力及非确定性的操作并非在运行时被拦截——它们从未被生成进入可用接口。
未知函数以 unsupported_operation 失败，并从同一索引返回 nearest_matches——模型自我修正，而非陷入循环。
contract_hashsha256:79f1c5a6c7164e7e9e1750e70a5c03292fa87eb52d8148a740c06695924be9a1
- 4,778
- 合约中列出的操作
- 4,574
- 向 SDK 开放，只读
- 4,564
- 完全确定性
- 10
- 需要种子的模拟
- 204
- 排除在接口之外
准入条件read_only && (deterministic || deterministic_when_seeded)
遇未知名称时unsupported_operation + nearest_matches
03策略校验
由您的允许列表决定是否执行及如何执行。
策略在 createSQAI() 构建实例时固定，并在任何内容执行之前于进程内强制执行——作用于数据源、每个指标、分组、过滤器、绑定列及函数名。策略只能收窄合约：指定不在合法接口内的能力，仍会抛出 unsupported_operation。
模型的工具输入不携带任何 allowed* 字段。请求中没有任何内容可以扩大访问权限——因此提示注入也无从扩大。
allowedSources模型可命名的数据源
- "sales"
allowedFields每个数据源可读取的列
- sales.region
- sales.revenue
- sales.order_date
allowedFunctions默认值——所有只读能力，仅此而已
- "all-readonly"
拒绝精确、有据可查、不可撤销
- policy_denied_source
- policy_denied_field
- policy_denied_function
source: "sqai" · 不可重试
04确定性引擎
运行前已固定：float64，单线程，单运行时。
首先，绑定解析。模型命名了数据源和字段；SQAI 通过引擎的行对齐原语 extractColumns 提取实际值，空值按对处理。SQAI 从不自行压缩数组——因此被哈希的输入与实际执行的输入完全一致。
请求此时才触达引擎。运行时经过签名、版本控制与固定：float64 精度，单线程。首次 compute() 调用约需 110 秒完成初始化，此后常驻内存——finance.npv 热态耗时 0.83–0.93 ms。
0.1.04d64142e4c1ff63d299cfc8b172fdf97cb59169b545e1e02978e678a632ce6e1darwinarm64float641—2ea5ede72acd2912fe9e1230cef34afad4c9436bfa8a709bac2da02b478e3212随每次结果一并记录——边界声明保证的范围，而非过度承诺。
05结果与溯源
两个哈希：一个在前，一个在后。
invocation_hash 在执行前盖章——覆盖模块、函数、参数、已解析绑定、种子、合约与作用域。computation_hash 在执行后盖章：将调用哈希与规范结果折叠而成。重放即再次运行并逐字节比对。
两个 SDK 共用同一规范序列化器，因此相同计算在 TypeScript 和 Python 中产生字节完全一致的哈希。查询结果遵循同等规范：对规范解析计划生成 plan_hash，附带决策路径及其运行时的精确作用域。
3188.1687606249325finance.npv · 绑定至实时列 · 热态 0.83 ms
执行前盖章
invocation_hash
8223a694250fc751fcf8a7777b8e1f524c44ff1f0e7e83451467f554a6123950
模块 · 函数 · 参数 · 已解析绑定 · 种子 · 合约 · 作用域
执行后盖章
computation_hash
ff5280ea128113f528dd1e9a28b9bc4a81469075ed7c981c7176fb172d98085d
调用哈希，与规范结果折叠合并
在 TypeScript 与 Python 中字节完全一致——在一种语言中计算的结果，可在另一种语言中重放并验证。
两者均计算自contract_hash sha256:79f1c5a6…
在查询平面上plan_hash f87610d8afeb…decision_path "exact_spec"deterministic_scope "local_registered_source"
06发现循环
不猜测。先发现，再试运行，再执行。
字段名与函数签名来自发现，而非臆造。AI SDK 仅暴露三个工具——其中只有一个会执行。
- 01
listSources()我能访问什么？
已连接的数据源，含精确字段名、类型及每个字段的允许操作。从不执行。
- 02
listSources({ capabilitySearch: "npv" })我能计算什么？
同一工具，检索确定性目录——匹配模块、精确签名，以及是否需要种子。
- 03
explainQuery({ … })能否运行？
试运行。返回已解析的计划、置信度及预览 invocation_hash——仅为预览，非已执行的哈希。
- 04
queryData({ … })执行。
唯一会执行的工具。返回结果及其完整溯源；超大结果可通过 result_id 检索。
工具从不抛出异常——每种结果均有类型ok · needs_clarification · rejected · error