DOCUMENTATION / SDK 快速开始
从状态，到行动。
通过 System One 原生协议连接你的应用，示例使用 @system-one-ai/sdk 0.3.0。
创建 API 密钥、安装 SDK，然后在服务端运行下方代码。示例中的 API 地址指向当前部署。
创建 API 密钥1. 安装 SDK
npm install @system-one-ai/sdk@0.3.02. 设置服务端环境变量
SYSTEM_ONE_API_KEY=your_server_side_api_key使用具备 Fetch 与 AbortController 的服务端运行时，例如 Node.js 20+ 或 Cloudflare Workers。
3. 评估一份共享状态
import { SystemOne, choice, score, booleanQuestion } from '@system-one-ai/sdk';const client = new SystemOne({ baseURL: 'https://YOUR_SYSTEM_ONE_HOST/v1', apiKey: process.env.SYSTEM_ONE_API_KEY!, model: 'jev-latest', maxRetries: 0,});const result = await client.evaluate({ state: { message: 'I was charged twice. Please refund the duplicate.' }, questions: { department: choice('Which team should handle this?', { billing: 'Payments, invoices, and refunds', support: 'Technical issues with the product', }), urgency: score('How urgent?', ['Routine', 'Soon', 'Immediate']), refund: booleanQuestion('Is the customer requesting a refund?'), },}, { timeoutMs: 10_000, headers: { 'Idempotency-Key': crypto.randomUUID() },});result.answers.department.choice; // 'billing' | 'support'result.answers.urgency.score; // number, starting at 0result.answers.refund.probability; // P(true), from 0 to 1result.response.requestId;决策原语
choice(instructions, criteria)提供 1–255 个具名候选项。TypeSafe 原生答案包含被选择的 choice、原始 probabilities 和模型提供的 confidence。
score(instructions, criteria)提供 2–10 个有序等级。TypeSafe 原生答案包含 score、probabilities、confidence 和 legend。分数从 0 开始，可以是小数。
booleanQuestion(instructions, criteria?)原生 noul 在 SDK 中映射为 probability，即 P(true)，并非布尔值，也不是对任一结果的置信度。
原生 HTTP
SDK 使用 Bearer 认证调用 POST /v1/systemone，无需自定义适配器。原生 JSON 中，booleanQuestion 对应 noul。model 可使用别名或固定版本 ID；省略时采用当前部署的默认模型。
curl 'https://YOUR_SYSTEM_ONE_HOST/v1/systemone' \ -H "Authorization: Bearer $SYSTEM_ONE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-request-id' \ --data '{ "model": "jev-latest", "state": { "message": "Please refund the duplicate payment." }, "questions": { "refund": { "type": "noul", "instructions": "Does the user request a refund?" } } }'GET /v1/models 需要平台 API 密钥，返回所配置 TypeSafe 上游的模型列表。Playground 可直接输入模型名称，不会请求该受保护列表。
理解返回值
原生 State 字段必填，支持字符串、对象、数组或 null。instructions 可省略或为 null；Noul 的 criteria 也可为 null。这些形式与 TypeSafe 官方客户端对齐，最终由上游决定是否接受。SDK 0.3.0 的输入校验更严格。数组是一份共享状态，模型输出不会执行动作。
TypeSafe 成功 JSON 保持原样，包括缺失字段和上游扩展字段。平台积分与标识从 X-System-One-Credits、X-Request-Id、X-Upstream-Request-Id 和 X-Idempotency-Replayed 响应头读取；正文中的 billing 或 request_id 属于上游。
积分与限制
问题数 × ⌈请求字节数 / 4,096⌉积分消耗为问题数 × ceil(规范化 JSON 的 UTF-8 字节数 / 4096)，每个问题至少一个计费块。推理失败会返还预留积分。上限：64 KiB、32 个问题、255 个 Choice 候选项、10 个 Score 等级、32 层 JSON 深度。
定价错误与重试
上游错误保留 HTTP 状态和安全 JSON，包括校验用的 detail 数组。通过 X-System-One-Error-Source 和 X-System-One-Error-Code 响应头判断来源与稳定错误码，并保留 X-Request-Id 排查问题。含敏感信息的上游错误会替换为平台安全错误正文。
| HTTP | 含义与处理方式 |
|---|---|
400 / 422 | 输入无效。检查状态、问题类型与大小限制。 |
401 / 403 | 根据错误来源区分平台认证、权限问题与上游拒绝请求。 |
402 | 平台来源表示账户积分不足；上游来源需检查模型服务。 |
409 | 幂等键冲突，或相同请求仍在处理中。 |
413 | 请求超过平台大小限制。 |
429 | 触发限流，请遵守 Retry-After。 |
5xx | 上游失败、模型未配置或超时；重试前检查请求记录。 |
SDK 默认可以重试，本文示例设置 maxRetries: 0。请主动定义超时预算和重试策略，遇到限流时遵守 Retry-After。
使用 Idempotency-Key 保护重试。同一个键只能用于相同请求正文，不同正文会被拒绝。结果未知时，先检查请求记录，再决定是否重复请求。
import { APIError, TimeoutError, RequestAbortedError } from '@system-one-ai/sdk';try { const result = await client.evaluate(request, { maxRetries: 0, timeoutMs: 10_000, headers: { 'Idempotency-Key': crypto.randomUUID() }, });} catch (error) { if (error instanceof APIError) { console.error(error.statusCode, error.requestId); } else if (error instanceof TimeoutError || error instanceof RequestAbortedError) { // Check usage before repeating an uncertain request. } else { throw error; }}身份认证
服务端调用使用 Authorization: Bearer <key>。网站 Playground 使用现有登录会话。完整 API 密钥只展示一次，不会写入 localStorage。
创建密钥