白纸黑字，有问必答。

Structured Query AI——面向 AI Agent 的受治理、只读结构化数据工具。问题被转化为有类型、经策略检查的计划；计划在确定性引擎上执行；答案连同可重放的哈希值一并返回。

单一接口同时覆盖文件与实时数据库，以及 445 个模块中的 4,778 个只读计算能力——从中位数到期权定价，一应俱全。

stats.median · finance.npv · option_pricing.black_scholes_call

查询层无需每次冷启动，在进程内运行——处理典型文件时延迟低于毫秒级。

计算层仅初始化一次：首次调用时下载并初始化已签名的运行时，约需 110 秒。此后守护进程保持热态常驻，热态计算调用耗时为 0.83–0.93 ms。

finance.npv = 0.83–0.93 ms (warm) · first provision ≈ 110 s

已签名的运行时支持 Apple Silicon macOS 和 x64 Linux。在 Windows 上，托管计算调用会返回结构化的具名错误，而不会崩溃。

查询层可在任意平台运行，自托管与托管模式亦然，因为计算会被提交至远程引擎。需要 Node 20 或更高版本；Python 3.10 或更高版本。

darwin-arm64 · linux-x64 · node ≥ 20 · python ≥ 3.10

可以。默认情况下，SQAI 安装覆盖全部公开接口的固定版本包。只需指定所需模块，构建服务即会为该子集编译一个已签名、sha256 固定的包，并按过滤器哈希缓存。

过滤后的守护进程拥有独立的 socket 和端口，与完整版本互不冲突。

SQAI_RUNTIME_MODULES → POST /v1/runtime/build · sha256-pinned

Agent 工具永远不会抛出异常。错误以结构化输出的形式返回，包含状态码和命名拒绝原因——策略拒绝、未知能力、缺少种子。

对于工具层以下的一切，一条命令即可在单次执行中检查安装状态、运行时状态及跨语言一致性。

output.status === "error" · sqai doctor --parity --json

是的——由架构保证，而非由权限控制。模型提交的是有类型的意图，而非 SQL；SQAI 将其与哈希固定的能力契约进行校验，应用你的策略，然后才执行。

在 4,778 个能力中，4,574 个对外公开：仅包含只读且确定性的，或带种子时确定性的能力。未通过检验的 204 个——包括所有写操作——均不在打包接口中。任何设置都无法触达从未发布的内容。

read_only && (deterministic || deterministic_when_seeded)

在代码中注册数据源，并将工具集——恰好三个工具——交给模型。一个列出现有内容，一个在不执行的情况下预览计划，一个针对只读接口执行。

数据库只读角色是一个可被取消的标志位，而不包含写能力的编译接口则不然。

sqai.tools() → listSources · explainQuery · queryData

不需要过滤 SQL，而是从源头阻止生成它。

字符串过滤和只读标志守护的是一门始终能表达写操作的语言——而经提示注入的 SQL 出现在模型输出中，已绕过你的输入过滤器。SQAI 的模型以一种语法上不存在写形式的类型化计划作答：DELETE 不是被拒绝的，而是根本无法写出的。

kind: "query" | "computation" · version: "1"

不能。策略在创建客户端时固定于代码中，并在每次执行前在进程内检查。工具 schema 不携带任何形式的允许列表字段，因此提示词无从触达。

显式允许列表只能缩小范围。指定公开接口之外的能力仍会失败——打包接口是上限。

policy_denied_source · policy_denied_field · policy_denied_function

有——仅供人类使用，模型无法触达。未受保护的运行时位于独立的导入路径之后，绕过契约、策略和种子检查，且从不暴露给 Agent 工具集。

工程师可以主动选择退出，Agent 则无论输入什么都无法触达它。

import { getUnsafeRuntime } from "@thyn-ai/sqai/unsafe"

在默认本地模式下，没有任何数据离开。查询平面在进程内解析，计算运行时是您机器上的一个已签名守护进程。唯一的出站请求是首次使用时下载运行时包——下载的是引擎代码，而非您的数据行。

将环境变量指向自托管或托管引擎后，执行计划将发送至该引擎，凭据经过加密，数据不会被复制。

local: in-process · self_hosted: SQAI_ENGINE_URL · api: SQAI_API_KEY

无需密钥的进程内模式支持：CSV、TSV、JSON、内存数据行及 SQLite——Python 中还支持 Excel 和 Parquet。通过引擎支持：PostgreSQL、MySQL、Oracle（含内置 Thin 模式驱动）、SQL Server、Snowflake、BigQuery、ClickHouse、Redshift、对象存储、Redis、Neo4j、Elasticsearch、REST API 及 Git 仓库。

每个数据源呈现相同的类型化结构，下游代码无法区分 CSV 与 Snowflake。数据源一经注册即不可变更。

SqaiSource { fields, typed_fields, row_count, schema_revision }

绝不。SQAI 不是模型，不进行任何训练——没有可供输入的学习循环。在本地模式下，您的数据行根本不会离开机器。

循环中唯一的模型是您自己引入的，它每次最多看到 25 行结果。超出部分会被截断——明确声明，从不静默——完整值保存在一个不透明的结果 ID 下，15 分钟后过期。

maxRowsToModel 25 · maxCellsToModel 250 · maxBytesToModel 32,000

在声明的执行范围内具有确定性——64 位浮点数、单线程、固定运行时——每个结果记录该范围，而非过度声称。

规范序列化器在两个 SDK 中均经过一致性锁定，因此相同的计算在 TypeScript 和 Python 中返回相同的数值及字节完全一致的哈希值。

finance.npv(0.1, [-1000, 300, 420, 560, 680]) = 505.020148896933computation_hash b74f67d0… · TS ≡ PY

从根本上不让它做运算。让模型计算 200 行的总和，得到的是一个貌似合理的数字——却没有任何信号表明它是错的。

使用 SQAI，模型只负责选择计算方式，引擎负责执行。在我们的准确性 A/B 测试中，同一模型在定量问题上的得分，在引擎接管计算的瞬间从 16 题中答对 0 题跃升至全部答对。

accuracy A/B: 0/16 → 16/16

可以——这正是哈希值的用途。每个结果携带一个计划哈希、一个执行前已知的调用哈希、一个执行后已知的计算哈希，以及一个记录运行时版本、平台、精度和种子的确定性信封。

在相同范围内重新运行调用，即使数月之后，哈希值也会逐字节匹配。若底层 schema 发生变更，您将收到一个具名的 schema 版本不匹配错误，而非静默地返回不同的数字。

run1 b74f67d0d7a594aa7ac91f6291612452aa8ccdf603351ebc8d801a6fddd91bc8run2 b74f67d0d7a594aa7ac91f6291612452aa8ccdf603351ebc8d801a6fddd91bc8identical: true

不需要。本地模式零配置——无需密钥、账户或信用卡。运行时在首次计算调用时自动初始化。

登录为可选项，使用设备码方式；它签发一个离线许可证，传输的是已签名令牌，而非您的数据。密钥仅用于指向不同的引擎。

sqai login → RFC 8628 device code · WDJB-MJHT

本地开发和托管计算均免费——SDK 中没有任何许可证检查。

付费套餐限制的是设备数、席位和商业权利，而非计算功能。Developer：免费，单设备，非商业用途。Pro：每月 $25，三台设备，商业用途，异步任务、Webhook、审计日志。Team：每月 $99，十台设备，新增基于 RBAC 的访问控制和席位管理。

Developer $0 · Pro $25/mo · Team $99/mo