System One SDK
安装开源 TypeScript SDK，连接你选择的决策服务。
System One SDK 是面向 Agent 和应用的开源 TypeScript 工具包。用 choice()、score() 和 booleanQuestion() 定义问题，通过 evaluate() 发起评估，在代码中直接使用类型明确的结果。
核心包采用 MIT 许可，没有运行时依赖。在 core 之外按需安装对应服务的适配器与 transport。每种连接使用对应服务的凭据与计费方式。
安装
npm install @system-one-ai/core@0.6.0 @system-one-ai/adapter-system-one@0.6.0 @system-one-ai/transport-fetch@0.6.0支持 Node.js 20+，以及提供 Fetch 与 AbortController 的运行环境，例如 Cloudflare Workers。密钥应留在服务端。
SDK 0.6.0 将旧单包拆分为独立安装的包。HTTP 客户端必须显式配置 adapter 和 transport，自定义 Fetch 传入 createFetchTransport(customFetch)。详见 0.6 迁移指南。
选择连接方式
| 服务 | 配置 | 凭据与计费 |
|---|---|---|
| System One API | 主站地址加 /v1，配置 systemOneAdapter 与 createFetchTransport() | 平台 API 密钥、System One 账户积分 |
| TypeSafe | https://api.typesafe.ai/v1，配置 systemOneAdapter 与 createFetchTransport() | TypeSafe 凭据与该服务的计费 |
| OpenRouter | 显式使用 @system-one-ai/adapter-openrouter | OpenRouter 凭据与该服务的计费 |
| Cloudflare Workers AI | 从 @system-one-ai/adapter-cloudflare/workers 导入 createCloudflareWorkers({ binding: env.AI })；安装 0.6.0 的 core 和 adapter-cloudflare | Workers AI 绑定、Cloudflare 计费；无需配置 Fetch transport |
| Vercel AI SDK | 显式使用 @system-one-ai/adapter-vercel | 所配置模型服务的凭据与计费，另装相应依赖 |
使用我们的托管服务，请阅读将 SDK 连接到托管 API。可选适配器的具体配置以 SDK 0.6.0 说明为准，SDK 不会根据域名自动切换协议。
用 TypeSafe 开始
设置服务端环境变量 TYPESAFE_API_KEY，然后运行以下 TypeScript 代码。此示例直接调用 TypeSafe，不使用 System One 平台密钥或积分。
import { SystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';
const client = new SystemOne({
adapter: systemOneAdapter,
transport: createFetchTransport(),
baseURL: 'https://api.typesafe.ai/v1',
apiKey: process.env.TYPESAFE_API_KEY!,
maxRetries: 0,
});
const result = await client.evaluate({
state: { message: 'I was charged twice.' },
questions: {
team: choice('Who should handle this?', {
billing: 'Payments and refunds',
support: 'Technical issues',
}),
urgency: score('How urgent?', ['Routine', 'Soon', 'Immediate']),
refund: booleanQuestion('Does the user request a refund?'),
},
});
result.answers.team.choice; // 'billing' | 'support'
result.answers.urgency.score; // number, starting at 0
result.answers.refund.probability; // P(true), from 0 to 1理解类型与结果
choice() 保留候选项字面量类型，score() 返回可能为小数的数值，booleanQuestion() 返回概率，并不直接返回布尔值。原生协议将布尔问题表示为 noul，SDK 将其映射为 probability。详见决策原语。
SDK 0.6.0 的 State 支持字符串、对象或数组；其输入校验比托管 API 的原生 HTTP 更严格，不能假定所有原生 nullable 输入都可以通过 SDK 发送。需要原始 HTTP JSON、响应头或精确十进制数时，参阅 API 参考。
控制请求
通过 timeoutMs、maxRetries 和调用选项中的 signal 控制请求预算、重试与取消。上方示例关闭自动重试。SDK 不会自动生成幂等键；使用托管 API 时按幂等与重试保存逻辑请求的键，并在结果未知时先检查调用记录。
更多错误类型、适配器和版本信息见 SDK 源码与 README。