Jev 安装完全指南：从零代码 Playground 到 Claude Code 技能包，四条路径任你选

admin@yesmiracle.net (万戈) — Thu, 24 Sep 2026 00:00:00 +0000

上周发了 TypeSafe AI Jev 深度解析，不少人问：文章说得好，但我到底怎么用？

这个问题值得专门写一篇，因为 Jev 的安装路径不是「装一个包就行」那么简单——根据你是在试想法、写脚本、做集成、还是让 AI 编程助手帮你干活，有四条完全不同的路。选错了不是不能用，但会多写很多不必要的代码。

这篇文章把每条路径的 exact 命令都写清楚，跟着走就行。

四条路径怎么选？

你的场景	安装路径	你需要什么	首次出结果
测试 Jev 适不适合你的用例	Web Playground	浏览器 + console.typesafe.ai 账号	2 分钟
从任意语言或脚本调用	直接 HTTPS 调用	API Key + curl 或 HTTP 客户端	5 分钟
构建正式集成（Python/JS/TS）	官方 SDK	pip 或 npm + API Key	10 分钟
让 AI 编程助手帮你写集成	Claude Code 技能包 / skills.sh	Claude Code（或 Codex 等）+ API Key	3 分钟安装，然后一句大白话

不管你选哪条路，前置条件都一样：一个 TypeSafe 账号和一枚 API Key。

第一步：注册账号，获取 API Key

去 console.typesafe.ai 注册。截至 2026 年 9 月 22 日的实测，没有 waitlist、没有审批流程、不需要邀请码——注册完直接进控制台。

用邮箱或 SSO 登录
点左侧「API Keys」或首页的「API key」磁贴
点「Create key」，命名（比如 local-dev），立刻复制——TypeSafe 的 Key 以 sk- 开头，只展示一次
存为环境变量，绝对不要硬编码在代码里：

export TYPESAFE_API_KEY="sk-..."   # bash/zsh

$env:TYPESAFE_API_KEY="sk-..."     # PowerShell

注册是免费的，Key 也是免费的。具体费用参考 Jev 定价指南，这里不展开。

路径一：零代码 Playground（2 分钟）

打开控制台里的 Playground，粘贴一段文本作为「state」，加一个问题，点运行——几秒内看到结果。

Playground 就是为这个场景设计的：在写任何集成代码之前，确认 Jev 的输出对你有用。

把你想评估的场景（客服工单、对话记录、政策描述）贴进 state 字段，然后选一个问题类型：

Noul：判断一个陈述是否成立，返回概率（比如「这条消息包含紧急内容」→ 92%）
Choice：从你给的列表里选最匹配的（比如「该转哪个部门：技术/客服/退款」）
Score：按你定义的评分标准打分（比如「客户情绪 1-10 分」）

点运行，结果立刻出来，不需要装任何东西。

⚠️ 一个重要的限制：Playground 的模型选择器只有两个选项——jev-latest 和 jev-preview，都不是固定版本。这意味着你今天在 Playground 看到的结果，跟下周用同样的输入跑出来的，可能来自不同的底层模型。后面会讲怎么解决。

路径二：curl 直接调 HTTPS API（5 分钟）

从任意语言发 POST 请求到 https://api.typesafe.ai/v1/systemone，带 bearer token 和 JSON body。不需要装 SDK，适合脚本和 CI 场景。

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer emailed twice this week about a failed refund.",
    "model": "jev-latest",
    "questions": {
      "urgency": {"type": "noul", "instructions": "This conveys urgency"}
    }
  }'

请求体三个核心字段：

state：你要评估的文本
model：指定模型版本（jev-latest、jev-preview 或固定版本如 jev-1.13.0）
questions：一个字典，每个 key 是问题名，value 指定类型 + 指令

这条路径适合 serverless function、CI 任务、或者不想为少量调用加依赖的场景。但如果你要做的调用比较多，SDK 能省不少样板代码。

路径三：Python / JavaScript SDK（10 分钟）

Python

pip install typesafe-sdk
# 或用 uv: uv add typesafe-sdk

装好后，客户端自动从环境变量读 API Key：

from typesafe_sdk import TypeSafeClient, Noul

client = TypeSafeClient()  # 自动读 TYPESAFE_API_KEY
r = client.system_one(
    state="...",
    questions={"urgency": Noul(instructions="...")}
)

JavaScript / TypeScript

npm install @typesafe-ai/sdk

JS SDK 使用相同的模式：实例化客户端，传 state 和 questions 对象，拿到结构化结果，不需要自己解析 JSON。

这是大多数生产集成应该走的路。SDK 帮你处理了重试、请求格式化、响应类型化，并且是用同一个 client 类来 pin 模型版本。

路径四：Claude Code 技能包（3 分钟安装，然后一句话描述需求）

这是这篇文章里最值得重点说的路径，因为几乎没人写过。

TypeSafe 发布了一个 MIT 许可证的官方技能包：github.com/typesafe-ai/skills。它教 AI 编程助手 Jev 的三个问题类型和集成模式，你只需要用大白话描述需求，助手自己写集成代码。

如果你用 Claude Code

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

显式调用：

/typesafe:typesafe-ai

后续更新：

claude plugin marketplace update typesafe-ai && claude plugin update typesafe@typesafe-ai

如果你用 Codex 或其他 skills.sh 兼容的助手

npx skills add typesafe-ai/skills --skill typesafe-ai
# 加 -g 全局安装
# 更新用: npx skills update

装了能干什么？

装好之后，你可以跟你的编程助手说一句：「用 TypeSafe 把工单按部门路由，不确定的转人工审核」——它自己写客户端代码、选问题类型、配置信度阈值。不需要你查 SDK 文档手写调用。

💡 但要注意：技能包只让助手正确写出 Jev 调用代码，不会让你数据的置信度阈值自动正确。第一次跑完，拿一批真实标注过的样本验证一下，再上生产。

模型版本管理：jev-latest、jev-preview 还是固定版本？

这是容易踩坑的地方，因为控制台里只有两个选项：jev-latest 和 jev-preview，而且控制台 UI 不支持 pin 版本。

jev-latest → 最新的稳定发布版
jev-preview → 下一个候选版本（没有预览版时等于 latest）

两者都是别名。今天用 jev-latest 调出来的结果，三个月后可能完全不同。

要 pin 版本只能在代码里做：

client = TypeSafeClient(model="jev-1.13.0")

或者直接 API 调用时在 JSON body 里设 "model": "jev-1.13.0"。

💡 早点决定用 latest 还是 pin 版。如果你针对某个模型版本调过置信度阈值，切换到不同版本意味着所有阈值要重新验证。

装完之后做什么？

四条路径殊途同归，最后都调同一个 API。关键问题就一个：你的第一个用例该用 Noul、Choice 还是 Score？

Noul：真假判断（这条消息紧急吗？）
Choice：从列表里选（该转哪个部门？）
Score：按标准打分（客户情绪指数？）

大多数团队第一次会选错——不是 API 难，是直觉上 Score 更「全面」，但很多时候 Choice 更精准。怎么选、各有什么最佳实践，参考 Jev 的 Choice, Score, Noul 原语指南。

如果你的集成需要对接 LMS 系统，同步参考 LMS API 文档指南和 LMS Webhook 集成指南。

总结

Jev 的安装不是「装一个 pip 包」那么简单的事——四条路径对应完全不同的使用场景。但好消息是，它们都通向同一个 API。

不确定？打开 Playground，贴一个你工作流里的真实例子，看看结果
要集成？上 SDK，加环境变量，写十行代码
用 AI 编程助手？装技能包，一句话搞定

选对你当前场景的那条路就行。

FAQ

Q1: 注册 Jev 需要 waitlist 吗？ 不需要。实测 console.typesafe.ai 注册没有 waitlist、邀请码或审批步骤。注册完直接进控制台，当场生成 API Key。

Q2: 不写代码能试 Jev 吗？ 可以。控制台 Playground 让你贴文本作为 state，选 Noul/Choice/Score 问题类型，点运行立刻出结果。最快的方式。

Q3: 控制台里能 pin 特定模型版本吗？ 不能。控制台只有 jev-latest 和 jev-preview 两个别名。要 pin 固定版本（如 jev-1.13.0）必须在代码里设 model 参数。

Q4: jev-latest 和 jev-preview 有什么区别？ jev-latest 是最新稳定版，jev-preview 是下一个候选版（没有预览版时等于 latest）。两者都会随时间变化，不像固定版本那样稳定。

Q5: TypeSafe 官方技能包支持 Claude Code 以外的工具吗？ 支持。Claude Code 通过插件市场安装；Codex 和其他 skills.sh 兼容的工具通过 npx skills add 安装，仓库相同。

Q6: SDK 怎么自动读取我的 API Key？ Python 和 JS SDK 在无参实例化客户端时自动读 TYPESAFE_API_KEY 环境变量。不需要在代码里传 Key。

API on AI博士 万戈