安装备用方式：uv、npm 与 curl 直连 API

上一课用 venv + pip 走通了主路线，但 TypeSafe SDK 安装不止一条路：官方快速开始同时给了 uv、JavaScript / TypeScript SDK 和 Bash 直连三种备用方式。这节课把三条都走一遍——8 分钟后，按你的项目挑一条用。

学完你能做什么

用 uv 两条命令完成 TypeSafe SDK 安装，并把依赖锁进 uv.lock
用 npm 安装 Jev JavaScript SDK（@typesafe-ai/sdk），跑通和上一课同一个工单三问示例
同一份代码用 TypeScript 直跑（Node.js 22.18+）
用 curl 7.76+ 直连 TypeSafe API，看到一整行原始 JSON 响应
说出三条路线各自的版本门槛，选出适合自己项目的那条

你现在的困境

项目已经在用 uv 了，再回 venv + pip 像开倒车
我们技术栈全是 Node / TypeScript，为一个 API 调用配整套 Python 环境不值
还没决定用哪个 SDK，想先用 curl 看看 API 到底返回什么再动手

什么时候用这一招

当你需要：

在 uv 管理的 Python 项目里加 Jev
在 Node.js、前端或 TypeScript 项目里调 Jev
用任何语言直接 HTTP 调用（先验证效果，或官方没有你语言的 SDK）

而且不想：

手动 python3 -m venv 再 pip install
为一条 curl 请求就装整套 SDK

🎒 开始前的准备

完成了安装与第一个请求—— 这一课会复用同一份 route_ticket.py 示例
环境变量里有 Key：终端里 echo $TYPESAFE_API_KEY 能打印出来（没有就回注册与 API Key）
按你要走的路线备好：Python 3.10+（uv 路线）、Node.js 22+（npm 路线）、curl 7.76+（curl 路线）
命令行用 Bash（macOS / Linux / Windows WSL——官方快速开始的命令按这个环境写）

核心思路

官方快速开始的「写代码发第一个请求」一节给了四个标签页：Python、JavaScript、TypeScript、Bash。上一课走的是 Python 的 venv + pip 路线，这一课把剩下的走完。

三条备用路线对比：

路线	装什么	版本要求	适合谁
uv	`typesafe-sdk`（和 pip 同一个包）	Python 3.10+，需要装 uv	已用 / 想用 uv 的 Python 项目
npm	`@typesafe-ai/sdk`	Node.js 22+（TS 直跑 22.18+）	Node、前端、TypeScript 项目
curl	什么都不装	curl 7.76+	任何语言；快速验证 API 返回

三条路线调的是同一个端点：POST https://api.typesafe.ai/v1/systemone，认证都是 Authorization: Bearer <Key>。区别只在「谁帮你包 HTTP」。

SDK 替你做了三件事，直连时都要自己来：

事	SDK 的做法	curl 直连时
认证	自动读 `TYPESAFE_API_KEY` 拼请求头	手写 `-H "Authorization: Bearer $TYPESAFE_API_KEY"`
限流重试	`429` / `529` 默认指数退避重试	自己写（官方 errors 页明确要求指数退避）
收发格式	状态 + 问题用类包好，答案按 ID 取	自己拼 JSON、自己解析 JSON

跟我做

三条路线互相独立，按你的语言选一条走就行（对比见上表）；步骤编号连续，方便交叉引用。

第 1 步：用 uv 完成 TypeSafe SDK 安装

为什么：uv 是官方快速开始里与 pip 并列的安装方式，两条命令建项目 + 装 SDK，还自动生成跨平台的锁文件 uv.lock。

先确认 uv 在不在：

bash

uv --version

没装的话，用官方安装脚本（macOS / Linux）：

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

装 SDK。在项目目录里执行：

bash

uv init --bare
uv add typesafe-sdk

你应该看到：两条都没有报错；第二条输出类似 Installed 14 packages，列表里有一行 typesafe-sdk==0.7.5（版本号以你安装时为准）。目录里多了 .venv/ 和 uv.lock，pyproject.toml 的 dependencies 里多了 "typesafe-sdk>=0.7.5"。

项目目录里出现了 .venv/ 和 uv.lock

跑上一课的示例——不用激活任何环境：

bash

uv run route_ticket.py

你应该看到：和上一课完全一样的三行：

text

technical
0.67
0.99

route_ticket.py 就是上一课那份官方示例，原样复制过来即可（代码在安装与第一个请求）。

关于 uv 路线的三个细节（依据 uv 官方文档）：

细节	说明
`uv init --bare`	只生成 `pyproject.toml`，不建 src 目录、README 和 git——快速起步够用
`.venv`	uv 在 `pyproject.toml` 旁边管理虚拟环境；`uv run` 会自动保证它和锁文件同步。直接用 `.venv/bin/python route_ticket.py` 也行
`uv.lock`	锁定精确版本，官方建议进版本控制，换机器也能复现同一组依赖

第 2 步：npm 安装 Jev JavaScript SDK 并跑通示例

为什么：JavaScript / TypeScript SDK 是官方两大客户端 SDK 之一，和 Python SDK 用同一套「state + questions」写法，答案类型还能从问题定义自动推断。

先核对 Node 版本——这里有个容易踩的坑：

bash

node --version

官方快速开始的 JavaScript 标签页写「Node.js 20 or later」，但那是旧版本的口径：SDK 文档页和更新日志都写 Node.js 22 or newer（v0.7.0 起的破坏性变更），npm 包的 engines 字段也是 >=22。以 22+ 为准（细节见下面踩坑提醒）。

装 SDK：

bash

npm install @typesafe-ai/sdk
npm pkg set type=module

第二条把项目标记成 ES module——官方示例用 import 语法，不设置的话 Node 加载会报错。

你应该看到：第一条输出 added 1 package；目录里多了 node_modules/、package.json、package-lock.json。package.json 里有 "@typesafe-ai/sdk": "^0.7.0"，第二条执行完还多出 "type": "module"。

用编辑器新建 route_ticket.js，贴入官方示例：

javascript

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

const ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.";

const client = new TypeSafeClient({ defaultModel: "jev-latest" }); // Reads TYPESAFE_API_KEY.
const response = await client.systemOne({
  state: ticket,
  questions: {
    department: choice("Which team should handle this", {
      billing: "Payment or subscription issues",
      technical: "Bugs or integration problems",
      sales: "Pricing or account questions",
    }),
    frustration: score("How frustrated the customer appears", [
      "Calm, just stating facts",
      "Frustrated but civil",
      "Very angry, strong language",
    ]),
    is_urgent: noul("The message conveys urgency or time-sensitivity"),
  },
});

console.log(response.answers.department.choice);
console.log(response.answers.frustration.score);
console.log(response.answers.is_urgent.noul);

跑它：

bash

node route_ticket.js

你应该看到：三行输出，和 Python 路线一致：

text

technical
0.67
0.99

node route_ticket.js 打出了 technical / 0.67 / 0.99

用 TypeScript 直跑（可选）

同一份代码，原样存成 route_ticket.ts（内容和 route_ticket.js 完全一致），直接：

bash

node route_ticket.ts

你应该看到：同样的三行输出。这要求 Node.js 22.18 或更高（支持直接运行 TypeScript）；并且 SDK 会从你的问题定义推断答案类型——response.answers.department.choice 的类型就是 "billing" | "technical" | "sales"，编辑器里自动补全直接可用。

第 3 步：用 curl 直连 TypeSafe API

为什么：官方快速开始的 Bash 示例就是「不带 SDK 的完整 HTTP 请求」。任何能发 HTTP 的语言（Go、Java、Rust……）都可以照这个结构调 Jev；也适合先验证 API 返回再决定装不装 SDK。

用编辑器新建 route_ticket.sh，贴入官方示例：

bash

#!/usr/bin/env bash
set -euo pipefail
: "${TYPESAFE_API_KEY:?Set TYPESAFE_API_KEY first.}"

curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "state": "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}
JSON

跑它：

bash

bash route_ticket.sh

你应该看到：一整行原始 JSON——和 SDK 路线打印的三个值不同，这是完整响应，包含每个答案的 confidence 和 probabilities，以及 usage 计量。格式化后的完整样例在上一课的「读懂完整返回」里，字段含义不再重复：安装与第一个请求。

没设 Key 时脚本会先在本地拦下来：route_ticket.sh: line 3: TYPESAFE_API_KEY: Set TYPESAFE_API_KEY first.——这就是开头第 3 行那句守卫的作用，免得把空 Key 白白发给服务器。

bash route_ticket.sh 打出了一整行 JSON，里面有 "answers"

curl 路线的两个提醒：

项	说明
`--fail-with-body`	需要 curl 7.76+：HTTP 报错时退出码非 0，但仍会打印响应体，方便看错在哪
`429` / `529`	直连方案要自己写指数退避重试（SDK 默认带了）；收到就看一眼响应体，歇一下再发

检查点 ✅

uv 路线：.venv/、uv.lock、pyproject.toml 三样都在，uv run route_ticket.py 出三行答案
npm 路线：package.json 里同时有 "@typesafe-ai/sdk" 和 "type": "module"
curl 路线：bash route_ticket.sh 输出一整行 JSON，里面有 answers
我知道三条路线调的是同一个端点：POST /v1/systemone
我知道版本门槛：Python 3.10+ / Node 22+（TS 直跑 22.18+）/ curl 7.76+

踩坑提醒

❌ npm pkg set type=module 报 `npm error code ENOENT`

现象：空目录里直接跑 npm pkg set type=module，报 Could not read package.json ... no such file or directory。

原因：npm pkg set 是「改 package.json」的命令，目录里还没有这个文件时它不会替你创建（实测 npm 10.9.7）。

正确做法：按官方顺序来——先 npm install @typesafe-ai/sdk（npm 会自动生成 package.json），再 npm pkg set type=module。

❌ node 报 Warning: Failed to load the ES module

现象：运行 node route_ticket.js，报 Failed to load the ES module: route_ticket.js. Make sure to set "type": "module" in the nearest package.json file or use the .mjs extension.

原因：项目没标记成 ES module（或被设成了 commonjs），而官方示例用的是 import 语法。

正确做法：npm pkg set type=module；或者照报错提示，把文件扩展名改成 .mjs。

❌ 照「Node 20+」准备了环境，装的是要 22+ 的新版 SDK

原因：官方快速开始页 JavaScript 标签写「Node.js 20 or later」，但 SDK 现在的 npm 最新版（0.7.0）engines 是 node >=22，更新日志里 v0.7.0 也明确是破坏性变更「require Node.js 22 or newer」。历史上的 0.5.7 / 0.6.0 才支持 20+——快速开始那句话是对旧版的。

正确做法：node --version 先核对，不够 22 就升级 Node，或改走本课的 uv、curl 路线。

❌ uv add 完用 `python route_ticket.py` 还是 ModuleNotFoundError

原因：系统里的 python 不是 uv 管理的那个环境，SDK 装在项目的 .venv 里。

正确做法：按官方示例统一用 uv run route_ticket.py（它先确保 .venv 与锁文件同步）；或显式指定 .venv/bin/python route_ticket.py。

进阶技巧（可选）

SDK 还替你管压缩。 Python SDK 从 v0.7.5 起默认用 zstd 压缩请求体；JavaScript SDK 在 Node 22.15+ 上自动压缩 1 KiB 以上的请求体，想关掉传 compression: false。Python 3.13 及更早版本要显式加 extras：uv add "typesafe-sdk[zstd]"（另有 http2、pil 两个 extras）。

没有官方 SDK 的语言。 Go、Java、Rust……照第 3 步的结构发 POST /v1/systemone 就行，state / questions / answers 的字段定义见 API 速查。

直连方案上生产前。 把 429 / 529 的指数退避重试包进你的 HTTP 客户端——这是官方 errors 页对直连用户的明确要求，SDK 路线不用管这个。

本课小结

✅ uv 路线：uv init --bare + uv add typesafe-sdk，两条命令完成 TypeSafe SDK 安装，uv run 直接跑。

✅ npm 路线：npm install @typesafe-ai/sdk + npm pkg set type=module，JavaScript 和 TypeScript（22.18+ 直跑）跑通同一个示例。

✅ curl 路线：--fail-with-body 直连 API，看到带 confidence 和 probabilities 的完整原始 JSON。

关键配置字段回顾：

字段	推荐值	说明
Python 包名	`typesafe-sdk`	pip / uv 同一个包；`uv add typesafe-sdk`
JS 包名	`@typesafe-ai/sdk`	npm 安装；v0.7.0 起要求 Node 22+
ES module	`type=module`	官方 JS / TS 示例用 `import`，必须设置
端点	`POST https://api.typesafe.ai/v1/systemone`	三条路线共用
认证	`Authorization: Bearer <Key>`	SDK 自动带；curl 用 `$TYPESAFE_API_KEY`
环境变量	`TYPESAFE_API_KEY`	三条路线共用，代码里不写密钥

下一课预告

三条路线都走通了还差最后一步兜底：装不上跑不通怎么办：起步排错。

你会学到：

用 3 条命令在 60 秒内定位环境、Key、网络哪一环出了问题
400 / 401 / 413 / 422 / 429 状态码分别代表什么、怎么处理
哪些错误 SDK 会自动重试（429 / 529），直连时怎么自己写
报错时怎么带上 request_id 和最小复现代码去提问

安装备用方式：uv、npm 与 curl 直连 API ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

跟我做 ​

第 1 步：用 uv 完成 TypeSafe SDK 安装 ​

第 2 步：npm 安装 Jev JavaScript SDK 并跑通示例 ​

用 TypeScript 直跑（可选） ​

第 3 步：用 curl 直连 TypeSafe API ​

检查点 ✅ ​

踩坑提醒 ​

❌ npm pkg set type=module 报 npm error code ENOENT ​

❌ node 报 Warning: Failed to load the ES module ​

❌ 照「Node 20+」准备了环境，装的是要 22+ 的新版 SDK ​

❌ uv add 完用 python route_ticket.py 还是 ModuleNotFoundError ​

进阶技巧（可选） ​

本课小结 ​

下一课预告 ​

安装备用方式：uv、npm 与 curl 直连 API

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

跟我做

第 1 步：用 uv 完成 TypeSafe SDK 安装

第 2 步：npm 安装 Jev JavaScript SDK 并跑通示例

用 TypeScript 直跑（可选）

第 3 步：用 curl 直连 TypeSafe API

检查点 ✅

踩坑提醒

❌ npm pkg set type=module 报 `npm error code ENOENT`

❌ node 报 Warning: Failed to load the ES module

❌ 照「Node 20+」准备了环境，装的是要 22+ 的新版 SDK

❌ uv add 完用 `python route_ticket.py` 还是 ModuleNotFoundError

进阶技巧（可选）

本课小结

下一课预告