TypeScript SDK

System One SDK 是一个开源 TypeScript 工具包，可以独立于 System One 托管 API 使用。用 choice()、score() 和 booleanQuestion() 定义问题，通过 evaluate() 发送评估；或定义 Clairic 字段，通过 extract() 发送抽取。在应用或智能体中使用类型明确的答案。

核心包采用 MIT 许可，没有运行时依赖。安装或使用库本身不要求创建 System One 账户。网络评估使用所连接服务的凭据、可用模型和计费规则。System One 账户积分只适用于我们的托管 API，并不适用于所有 SDK 连接。

截至 2026-10-21，npm 上已发布的包：

其他 @system-one-ai/adapter-* 包把同一个客户端接到更多服务，各自使用该服务自己的凭据与计费。

Core 0.8.0 新增 Clairic 的 extract({ state, fields })。systemOneAdapter@0.7.0 将抽取请求 POST 到 {baseURL}/systemone，请求体带 fields，默认模型为 clairic。详见 Clairic 抽取。不要把 fields 传给 evaluate()。

已弃用的 @system-one-ai/sdk@0.5.3 入口已移除。各包独立发布；请安装都能解析到 core@^0.8.0 的匹配版本。

常见问题

Q: 什么是 System One TypeScript SDK？
A: 面向托管 System One API 的开源客户端，用于以类型化结果调用 Choice、Score、Noul 与 Clairic extract。

安装与运行环境

连接 System One 托管 API（决策与 Clairic 抽取）时：

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

各包提供 ESM、CommonJS 和 TypeScript 类型声明。使用 Node.js 20+，或提供 Fetch 与 AbortController 的兼容环境。服务密钥应留在服务端。Core 不会根据域名选择协议，也不会自动读取环境变量；请显式传入配置。

createSystemOne(options) 是文档中的工厂函数，返回 SystemOne 实例。new SystemOne(options) 是同一个构造函数。

选择服务连接

为所选适配器安装 core 0.8.0；HTTP 适配器再安装 transport-fetch 0.8.0。这些是 SDK 的公开集成选项，不是本站托管服务或模型的列表。各适配器的配置与当前支持情况见 SDK README。

使用我们的托管 API，请阅读托管 SDK 快速开始，从当前模型目录选择准确的模型 ID，并查看能力、限制和积分价格。使用公开名称，例如 jev、clef、clef-flash、clairic。要把 SDK 接到其他服务，请使用该服务的 @system-one-ai/adapter-* 包，并使用你自己的凭据与自己的计费。不要假设某个别名、SDK 默认模型或其他服务提供的模型一定能使用。

从托管 API 开始

将 SYSTEM_ONE_API_KEY 设置为你的 System One 平台密钥，将 SYSTEM_ONE_MODEL 设置为当前模型目录中的准确模型 ID。下方 YOUR_MODEL_ID 是占位符，不是模型别名。示例会产生由你的 System One 账户积分计费的真实请求。

SYSTEM_ONE_API_KEY=replace-with-your-platform-key
SYSTEM_ONE_BASE_URL=https://system-one.dev/v1
SYSTEM_ONE_MODEL=YOUR_MODEL_ID

import { createSystemOne, 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 apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('请设置 SYSTEM_ONE_API_KEY、SYSTEM_ONE_BASE_URL 和 SYSTEM_ONE_MODEL。');
}

const client = createSystemOne({
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  baseURL,
  apiKey,
  model,
  timeoutMs: 30_000,
  maxRetries: 0,
});

const result = await client.evaluate({
  state: { message: '同一笔订单被扣款两次。' },
  questions: {
    team: choice('选择负责审核这条消息的团队。', {
      billing: '付款与退款',
      support: '技术问题',
      review: '需要更多信息',
    }),
    urgency: score('按以下有序标准评估紧急程度。', [
      '常规审核', '及时回复', '立即由人工处理',
    ]),
    duplicate: booleanQuestion('消息是否反映了重复扣款？'),
  },
});

const team: 'billing' | 'support' | 'review' = result.answers.team.choice;
console.log({
  team,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
});

同一组问题工厂也能配合其他适配器使用，但必须遵守相应服务接受的请求契约。直连服务有自己的恢复或幂等规则，不要假设我们的托管 API 规则同样适用。

图片

ImageInput 由 core 导出：可以是内嵌 base64 data URL 字符串，或包含真实编码字节的 { mediaType: 'image/png', base64: '...' }。images 是与 state、questions（或 fields）同级的可选顶层字段。state 仍必填；有图片时允许 ''。images: [] 与纯文本兼容。不支持远程 URL、下载、音频或视频。

托管 Clairic 图片使用 systemOneAdapter@0.7.0 的 extract()。见 Clairic 图片。

托管 Clef／Clef Flash／Clef Omni 的决策图片仍使用标准 Fetch/HTTP。systemOneAdapter 实现 evaluate({ state, questions }) 时不会编码 images。修改 supportsImages 或单独升级 core 不能补齐该编码器。请使用 System One 密钥与目录中支持图片的模型（列出时为 clef、clef-flash 或 clef-omni）。托管服务还校验完整 UTF-8 JSON 大小（支持图片的 Clef 条目最高 13MB）及目录中更严格的限制。附加决策图片后，Playground 提供 HTTP/curl 指引，而不是纯文本 SDK 示例。

Clef 和 Clef Flash 接受 PNG、JPEG、WebP，最多四张，每张解码后最多 4MB，合计最多 8MB。请读取 capabilities.inputs 中的 image，不要通过包版本推断能力。

保留问题与答案类型

choice() 保留选项名的字面量类型。score() 返回数值，可以是小数。booleanQuestion() 返回 P(true)，不是布尔值；原生 HTTP 协议将这种问题称为 noul，适配器负责转换两种表示。

共享问题定义时，使用 defineQuestions()，并从问题集推导请求与结果类型：

import { choice, defineQuestions } from '@system-one-ai/core';
import type { Answers, EvaluateRequest, EvaluationResult } from '@system-one-ai/core';

const questions = defineQuestions({
  team: choice('选择负责审核的团队。', {
    billing: '付款与发票',
    support: '技术支持',
  }),
});

type TeamRequest = EvaluateRequest<typeof questions>;
type TeamResult = EvaluationResult<typeof questions>;
type TeamAnswers = Answers<typeof questions>;

const request: TeamRequest = {
  state: { message: '请解释一下这张发票。' },
  questions,
};

Core 的 evaluate() 要求非 null 的 state 和显式 instructions 字段。其 Description 类型允许 null，但所选服务或模型不一定接受。布尔 criteria 可省略或为对象，不能为 null。官方 TypeSafe 客户端的 nullable 输入契约更宽，详见决策原语。这些文档中的可移植示例使用明确文本和非 null 描述。

结果经过跨适配器规范化，并非原始 HTTP 正文。概率分布、confidence 和 token 计数可能缺失，未知不等于零。Confidence 不一定等于选中选项的概率。result.model 可能提供与请求 ID 不同的实际模型名称。需要原始文本、精确小数处理和托管计费头时，请使用 HTTP API或官方客户端替代方案。

Fetch transport

@system-one-ai/transport-fetch@0.8.0 的 createFetchTransport() 发送适配器准备好的请求，处理认证、总超时、取消、重试，以及成功响应的大小上限（maxResponseBytes，默认 8MB）。将自定义 Fetch 作为第一个参数传入，而不是 SystemOneOptions 的字段：

import type { Fetch } from '@system-one-ai/core';

const customFetch: Fetch = (input, init) =>
  globalThis.fetch(input, { ...init, cache: 'no-store' });

const customClient = createSystemOne({
  apiKey,
  model,
  baseURL: 'https://system-one.dev/v1',
  adapter: systemOneAdapter,
  transport: createFetchTransport(customFetch),
  maxRetries: 0,
});

自定义实现必须保留请求、认证头、取消信号，并返回真实 Response。不要在传输封装中记录凭据或提交内容。

protocol-system-one@0.8.0 把本库的问题和答案转换成 System One 原生的请求／响应格式，或反向转换。托管适配器及其他兼容 HTTP 适配器会自动安装它。

超时、取消、重试与错误

Core 的 timeoutMs 是整次评估的总预算，包含凭据解析、重试、等待和响应读取，默认 10,000 ms。客户端 maxRetries 设置额外尝试次数（默认 2，范围 0–100）；单次调用可使用 timeoutMs、maxRetries、headers 和 signal 覆盖或补充客户端设置。

这个续接示例使用「从托管 API 开始」中的 client，以及「保留问题与答案类型」中的 request。运行会发起一次独立的 System One 评估，不是第一个示例的重试。

const resultWithDeadline = await client.evaluate(request, {
  timeoutMs: 15_000,
  maxRetries: 0,
  signal: AbortSignal.timeout(15_000),
});
console.log(resultWithDeadline.answers.team.choice);

Fetch transport 可重试连接失败、HTTP 408、429 与 5xx。在应用具备恢复策略前，先使用 maxRetries: 0。SDK 不会生成幂等键。调用托管 API 时，应在发送前保存键和实际请求，遵循幂等与重试。取消或超时不能证明服务端已停止，也不能证明没有扣费。

Core 导出 SystemOneError、ConfigurationError、ValidationError、UnsupportedFeatureError、ResponseValidationError、APIError、ConnectionError、BindingError、TimeoutError 和 RequestAbortedError。已发布的 core 0.8.0 中，APIError 提供 statusCode、requestId 和 retryAfterMs，不提供完整正文或全部响应头。托管错误分类需要使用原生 Fetch 或官方客户端的错误响应头。

从旧包迁移

@system-one-ai/sdk@0.5.3 已弃用。替换旧导入，不要同时保留两套客户端布局：

参阅维护中的 0.6 迁移指南、SDK 源码与 README及 MIT 许可。当前托管示例使用 core 0.8.0、adapter-system-one@0.7.0 与 transport-fetch@0.8.0。包版本与托管 API／模型能力相互独立。

接下来

• 用 Clairic 抽取类型化字段
• 通过 SDK 调用托管 API
• 选择模型