TypeSafe 不只有 Python：JS SDK 与编码 agent skill 接入

先说结论

• 官方除 Python SDK 外，还提供 JavaScript/TypeScript SDK；包名为 @typesafe-ai/sdk，要求 Node.js 20+，用 TypeSafeClient 和 choice() 等函数构造问题。
• Python 与 JS 两套 SDK 的问题对象写法相似但语法不同：Python 用 Choice(...)、Score(...)、Noul(...)，JS 官方页面至少展示了 choice(...)；访问答案时一个用方括号 key，一个用点号。
• Agent skill 是官方给 Claude Code、Codex 等编码 agent 的上下文包，用于让 agent 按官方规范写请求，减少字段脑补和文档翻找。
• 我的实操建议是：先手写一次 POST https://api.typesafe.ai/v1/systemone 确认响应形状，再上 SDK；API key 走环境变量；日志里记下响应顶层的 model 字段（官方响应示例显示它是 answers 的同级字段）。
• 两个常见坑：Noul 没有 confidence 可读；同一 state 的多个问题应合并到一次请求。

官方 JavaScript SDK 长什么样

官方 JavaScript SDK 文档 给出的安装方式很明确：包名是 @typesafe-ai/sdk，要求 Node.js 20 或更新。官方数据是：安装命令如下。

npm install @typesafe-ai/sdk

然后设置环境变量 TYPESAFE_API_KEY，再创建客户端。官方示例中要注意一个细节：state 被包在对象里，而不是直接传字符串。

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

官方数据：以上包名、初始化方式、systemOne 方法名、state/questions/answers 字段名均来自该文档。该页面还说明，答案类型会根据你的 questions 推断，包里包含 ESM、CommonJS 和 TypeScript 声明，并直接给出了 SDK 的类型声明入口（client.ts 与 types.ts，@v0.6.0）。另外，官方 JS SDK 的 API reference 里是单独成页的——choice()、noul()、score() 三个函数各有独立页面，ScoreQuestion<T> / ScoreResponse<T> / NoulResponse 等接口也各有页面，所以 JS 侧的 Score/Noul 并非“官方没写”，而是没写在这一页里（这一轮我按官方 API reference 的页面清单补上了对照表）。

Python 与 JavaScript 的问题对象对照

Python 侧来自官方 Quick start。它给出的安装方式是 pip install typesafe-sdk，客户端同样叫 TypeSafeClient，但导入的问题类型是大写开头的 Choice、Noul、Score。调用方法也略有不同：Python 用的是 client.system_one(state=..., questions=...)，JS 用的是 client.systemOne({ state: ..., questions: ... })。

下面这张对照表只列官方页面明确出现过的项。JS 侧的小写 choice()、noul()、score() 三个函数在官方 JS SDK 的 API reference 里各自成页，所以能用官方一手页面逐项核对，不必再标「未能核实」。需要说明的是：那三个页面只给出函数签名，没有给出可运行的完整示例，JS 的调用形态仍以官方 JS SDK 主页面那段 choice() 代码为准。

JS 侧 score() 的官方签名是 function score<T>(instructions, criteria): ScoreQuestion<T>，官方对该函数的说明是「Create a score question using an ordered rubric」——也就是说，「rubric 是有序的」这一点在 JS 侧同样是官方定义，不是前端生态的私有写法。Python 侧则是 Score 类 + instructions/criteria 关键字参数。两边都在用「问题对象」描述同一种判断，差别主要在两处：命名约定（大写类名 vs 小写函数）和调用形态（关键字参数 vs 单个 options 对象）。对前端/全栈项目来说，小写函数 + options 对象更贴近日常写法；但这种贴近只省手感，不改变请求语义，别把它当成「JS 版更强」的理由。

官方数据：以上安装、导入、调用、答案访问形式来自官方 Quick start、官方 JavaScript SDK 文档与官方 JS SDK API reference。自己推算：Python 与 JS 的函数名大小写差异反映的是各自语言的命名习惯，官方没有比较过两种 SDK 的能力高低，本文也不做这个比较。

Agent skill：把官方规范“喂”给编码 agent

官方 Agent skill 页面定位很清楚：它是给 Claude Code、Codex 以及其他 agent 环境的 drop-in skill，提供 TypeSafe API 的完整上下文，包括三种问题类型、架构模式和评估结构化的最佳实践。

安装有两种主要方式。Claude Code 用插件市场：

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

其他 agent 则用 skills CLI：

npx skills add typesafe-ai/skills --skill typesafe-ai

它解决的核心问题不是“教会模型新的 API”，而是减少 agent 写集成代码时的字段脑补。官方页面在常见问题里提到：如果 agent 编造请求或响应字段，可能是 skill 版本陈旧导致，更新后重试。也就是说，这个 skill 相当于把官方规范压进 agent 的工作上下文，省掉人肉翻文档、复制字段名、踩命名不一致的坑。

官方还给了几个 prompt 起点，例如：

Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.

注意：这个 prompt 不是我编的，是官方页面给出的示例，我在这里仅作为用法展示。

实操建议：先裸请求，再上 SDK

这是我的做法，不是官方文档的步骤顺序。官方 Quick start 给了 API 端点：

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer
Content-Type: application/json

我会先用 curl 手写一次请求，只带一个简单 noul 或 choice，确认 answers 里的字段形状和错误响应结构，然后再决定用 Python SDK 还是 JS SDK。这样做的原因是：SDK 帮你省掉的是序列化和客户端样板，但字段名是否对、响应里什么是主答案什么是元数据，裸请求一眼就能看出来。

API key 我坚持走环境变量 TYPESAFE_API_KEY，两个官方 SDK 都读取这个变量。日志方面，我会把响应里的 model 字段（如果返回）记录到应用日志。官方 Quick start 只提到 Python SDK 默认调用 jev-latest，没有展示响应体里 model 字段的具体位置，所以这条是我自己的排查习惯：一旦出现路由不一致，至少能确认实际跑在哪个模型上。若响应中没有该字段，就忽略。

两个容易踩的坑

第一个坑是把 Noul 当成带 confidence 的答案。官方 Primitives 的表格写得很清楚：Choice 返回 choice、probabilities、confidence；Score 返回 score、legend、probabilities、confidence；Noul 只返回 noul（0 到 1）。所以不要在 Noul 答案上找 confidence，它不是“置信度包装的布尔值”，而是 0 到 1 的单一判断值。

第二个坑是把一次判定的多个问题拆成多次请求。官方 Primitives 明确说，一个请求里的每个问题看到的是同一个 state，独立评估，并在你选择的 ID 下返回答案。官方还建议把多个问题放在一起问。如果你已经要对同一个 state 做多个判断，拆开请求不仅增加往返延迟和 token 成本，还让你人为维护多次 state 一致性。自己推算：对同一 state 的多问题合并为一次调用，是最符合官方“ask several at once”设计的做法。

自己的判断/清单

• 环境准备：Python 项目用 pip install typesafe-sdk，Node 项目确认 Node.js 20+ 后 npm install @typesafe-ai/sdk。
• 密钥管理：设置 TYPESAFE_API_KEY，不硬编码，不提交仓库。
• 先用 curl 打一次 POST https://api.typesafe.ai/v1/systemone，记录请求体和响应。
• 把 questions 和 thresholds 集中到一个文件，便于代码审查和调整。
• 检查 Noul 答案路径：只读 .noul，不要找 .confidence。
• 同一 state 的多问题放进一次 systemOne/system_one 调用。
• 如果让编码 agent 写集成代码，先安装官方 Agent skill 并让它使用 skill，再审查它生成的问题定义。

这次没核实的

• JavaScript SDK 里各类型化答案的完整字段清单（例如 ScoreResponse<T> 上 score/legend/probabilities/confidence 的 TypeScript 类型写法）。官方 JS SDK 的 API reference 为这些接口各开了一页，但我这一轮只核到函数签名与页面清单，没有逐页抄字段类型；这些字段在 HTTP API 层的形状有官方依据（见下文官方 API reference 的响应示例），JS SDK 的封装写法请以官方 API reference 为准，我未能逐项核实。
• API 响应体中 model 字段是否总是存在。这一轮已核到它出现的位置：官方 API reference 的响应示例里，model 是顶层字段，与 answers、usage 同级（值为 "jev-1.13.0"），官方 Quick start 的完整响应示例结构相同。但「某些错误响应或网关改写场景下是否仍然带上」官方未说明，这一层我未能核实。
• JavaScript SDK 的错误处理、重试和超时选项的具体默认值。官方 JS SDK 主页面未写，我未能核实；只核到官方 Client SDKs 汇总页说明「SDK 用默认重试策略自动处理重试」，以及 API reference 里存在 RetryPolicy、APITimeoutError、RateLimitError 等类型页面。
• Agent skill 手动安装到 Codex 等非 Claude 环境的具体目录，是否需要额外配置。官方页面只提到复制 skills/typesafe-ai 目录到 agent 的 skills 目录、以及可 npx skills add typesafe-ai/skills --skill typesafe-ai 后选择 agent，具体落到哪个路径需按 agent 文档确认，我未能核实。

参考来源

• 官方 JavaScript SDK 文档
• 官方 JavaScript SDK API reference（choice / noul / score 与响应接口）
• 官方 Agent skill 页
• 官方 Quick start（Python SDK 与 API 响应示例）
• 官方 API reference（响应体与答案类型字段表）
• 官方 Client SDKs 汇总页
• 官方 Primitives