typesafe-ai：让 AI 不再“写作文”，而是直接给答案的 Skill

typesafe-ai 体能是什么？

typesafe-ai 是 TypeSafe AI 公司（注意：不是泛指“类型安全的 AI”）的官方 Agent Skill。TypeSafe AI 的核心产品是 Jev，一个 System One 决策模型。Jev 的定位不是聊天模型，而是可编程的常识判断函数。

与传统 LLM 的关键区别：LLM 生成文本，然后应用需要解析和验证；Jev 直接返回类型化答案。你提前定义选项、等级或布尔问题，Jev 返回的是选项、分数或概率——没有需要 JSON.parse() 的中间文本。

Jev 不负责开放式聊天、长篇写作、代码生成或推理过程说明。它更像工作流里的一个判断节点：代码安排流程，Jev 做语义判断，其他模型承担需要生成文字或展开推理的任务。

typesafe-ai 的主要功能

三种问题原语。Jev 目前提供三种问题类型，对应三种可放进代码的判断结果：

一次调用，多问题并行。同一份 state 上的所有问题在一个请求中并行评估，每个问题独立判断。一个客服工单可以同时问“是否申请退款”（Noul）、“应由哪个团队处理”（Choice）、“紧急程度如何”（Score），全部在一个请求中完成。

结构化的 state 与 criteria。state 支持字符串、JSON 对象或数组。instructions 和 criteria 值接受字符串、JSON 对象、数组或 null，允许结构化描述（如 what、not_for、examples）。

可组合的判断。官方 Skill 强调：把宽泛问题拆成原子问题，再由代码组合。不直接问“这个工单应该如何处理”，而是分别判断严重程度、客户情绪和信息完整度，在代码中设置权重。

typesafe-ai 的核心特色

“判断”而非“生成”。这是最根本的特色。传统做法是用 LLM 生成 JSON，然后解析、验证、处理格式错误。Jev 从接口层就把返回结果限制在固定类型中，选项和等级由调用方提前定义，返回值不会变成一段需要再次解析的说明文字。

概率分布而非单一标签。Choice 返回所有选项的概率分布，Score 返回各等级的概率分布，Noul 返回“是”的概率。代码可以根据阈值决定自动处理还是升级人工。一个 0.98 的路由结果可以安全自动化；一个 0.51 对 0.47 的接近结果应该转人工。

快速与低成本。TypeSafe 报告 Jev 在其工作流评测中比 LLM 快最多 193.6 倍，便宜最多 444.6 倍。约 100ms 的响应时间让它可以放进实时分支判断中。

不微调，只提示。Jev 不接受微调，只接受文本输入。它的能力边界由问题设计决定，而非训练数据。

typesafe-ai 可以用来做什么？

路由与分类。把客服工单分到 billing/technical/account，选择下一个工具或子代理，决定继续、重试、询问用户还是停止。

评分与排序。按有顺序的等级评估紧急程度、风险、情感强度。Score 返回的概率加权均值可以落在两个等级之间（如 1.6 介于“medium”和“high”之间）。

验证与防护栏。检查模型输出是否满足条件，判断某个声明是否被证据支持。可以设置置信度阈值，低于阈值时转人工或升级到推理模型。

提取与结构恢复。在代码中找到候选值或源跨度，用判断选择意图中的那个，然后复制或规范化。

不适合的场景：开放式聊天、长篇写作、代码生成、图像输入（Jev 只接受文本，不解码媒体字节）。

typesafe-ai 适合哪些人？

• 需要在 AI 工作流中做可靠分支判断的开发者：不想让应用依赖 JSON.parse() 的脆弱链条。
• 已经在用 LLM 但受够了解析错误的团队：希望把“提示-解析”步骤变成结构化的类型化判断。
• Agent 构建者：需要在 Agent 循环中快速决定下一步行动、工具选择或是否停止。
• 对概率校准有要求的场景：需要根据置信度设置自动化边界，而非依赖模型“自信的语气”。

不太适合：需要生成文本、代码或长篇解释的场景；需要图像/音频输入的场景；需要微调模型以适配特定领域的场景。

typesafe-ai 如何安装？

typesafe-ai Skill 的官方安装方式非常直接：

Claude Code 插件方式：

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

其他 Agent 通过 skills.sh：

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

安装时选择你的 Agent，默认项目本地安装，加 -g 全局安装。

安装后，在 Claude Code 中可以用 /typesafe:typesafe-ai 显式调用该 Skill。也可以直接向 Agent 提问，例如：“用 TypeSafe 按部门路由客服工单，不确定的转人工审核。”

前置条件：需要 TypeSafe API Key（从 console.typesafe.ai 获取）。

typesafe-ai 怎么使用？

第一步：准备 state。把消息、业务记录、相关政策和应用状态整理成字符串、JSON 对象或文本数组。需要判断的事实放进 state，不要把业务流程藏在问题描述里。

第二步：设计原子问题。每个问题只负责一个可单独判断的因素。例如，不直接问“这个工单应该如何处理”，而是拆成“是否申请退款”（Noul）、“应由哪个团队处理”（Choice）、“紧急程度”（Score）。

第三步：一次发送多个问题。同一份 state 需要的判断放在一个请求中，Jev 并行处理，代码读取自己真正需要的答案。

第四步：在代码中组合结果。用概率、confidence、阈值和业务规则决定自动处理、继续调用还是转人工。Jev 不决定动作，代码决定。

JavaScript 示例（来自官方 SDK 文档）：

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);

typesafe-ai 使用技巧

拆分问题，而非扩大问题。一个宽泛的问题隐藏了多个判断。官方 Skill 的建议是：任何精确计算（算术、日期比较、计数、字符串匹配、查找）都留给代码，Jev 只获得需要阅读理解能力的判断。

为 Choice 写“情境化”的选项描述。每个选项的描述应该把它与邻近选项区分开。当模型在代码找到的候选中选择时（如文本跨度、ID、行号），候选列表必须包含正确答案，因为模型无法选择被遗漏的值。

Score 的每个等级描述一个可识别的场景。例如用“存在 workaround”而非“中等严重”。模型独立判断每个等级，不看到它的编号或邻近等级。

理解 Noul 的 0.5 不是“中等”。Noul 的 0.5 意味着“同样可能是是或否”，永远不表示“中等程度”。如果你想要程度，用 Score 而不是 Noul。

用 certainty 和阈值做门控。MCP 服务器计算 certainty（Noul: |probability - 0.5| × 2；Choice/Score: confidence）和 decision（act/review/abstain），基于可覆盖的阈值（默认 act_above 0.8，review_above 0.5）。当动作难以撤销时，提高阈值或让 medium certainty 先验证再行动。

固定模型版本。一旦你根据阈值校准了 gate，把 model 固定到版本化 ID（如 jev-1.13.0），因为 jev-latest 可能在你的校准门控下发生漂移。

typesafe-ai 收费吗？

Jev 是付费 API 服务，不是免费工具。TypeSafe AI 采用 API 按量计费模式。你需要从 console.typesafe.ai 获取 API Key，调用 api.typesafe.ai/v1/systemone 时消耗 tokens 并产生费用。

相比 LLM，Jev 的成本优势显著。TypeSafe 报告在其工作流评测中比 LLM 便宜最多 444.6 倍。具体定价需要查阅 TypeSafe 官方文档。

Agent Skill 本身免费开源（MIT 许可证），你只需要为 Jev API 调用付费。

typesafe-ai 的优点与缺点

typesafe-ai 与同类工具对比

vs 传统 LLM + JSON Mode / Function Calling。LLM 生成文本再解析，你处理的是“模型说它选了 billing”的文本。Jev 直接返回 choice: "billing" 和完整的概率分布。LLM 的 confidence 来自模型自我报告，Jev 的 confidence 是 API 返回的独立字段。

vs 微调的小型分类模型。微调模型需要标注数据、训练周期和版本管理。Jev 零样本即可使用，问题设计即“训练”——但代价是无法学习你领域的特殊模式。Jev 支持通过标注示例做校准评测（jev_eval），但模型本身不可微调。

vs 规则引擎。规则引擎处理精确条件（字符串匹配、数值比较），Jev 处理需要语义理解的判断。官方 Skill 的设计原则很明确：精确计算留给代码，Jev 只做阅读理解。

typesafe-ai 常见问题 FAQ

Q：typesafe-ai 和 TypeScript 的“类型安全”有关系吗？
没有。TypeSafe AI 是一家公司名称，不是“类型安全的 AI”的泛称。它做的是类型化决策——Jev 返回的是有固定类型的答案，而非需要解析的文本。

Q：Jev 会生成文本或解释吗？
不会。Jev 不写散文、代码或解释。它只接受文本，返回类型化答案。如果你需要解释，需要另外调用 LLM。

Q：Noul 的 0.5 是什么意思？
“同样可能是是或否”。永远不表示“中等”或“部分”。如果你想要程度，用 Score。

Q：Jev 支持中文吗？
支持，但官方建议英文。Jev 按字面理解，中文问题的准确率略低。decision/certainty/thresholds 的语义与语言无关。

Q：我能微调 Jev 吗？
不能。Jev 不可微调，只接受文本输入。它的能力边界由问题设计决定。

Q：confidence 和 probability 有什么区别？
Probability 是某个选项或等级的概率。Confidence 描述 Choice/Score 分布的集中程度（0 到 1）。TypeSafe confidence 是独立字段，不是 probability 本身。

Q：为什么我的 Jev 调用返回了低置信度答案？
常见原因：问题太宽泛（拆成原子问题）、state 包含无关信息（精简 state）、options 没有覆盖输入（加 other）、Noul 被用于本该用 Score 的程度问题。

typesafe-ai 综合评价

typesafe-ai 解决的是一个被大多数 AI 应用忽略的脆弱环节：把模型输出解析回程序能用的决策。LLM 生成的 JSON 会格式错误、会遗漏字段、会用“自信的语气”给出错误答案。Jev 从接口层消除了这个环节——返回的就是类型化答案和概率。

它的价值在需要可靠分支判断的工作流中最为明显。路由、分类、评分、验证、门控——这些场景不需要文本生成，只需要一个快速的语义判断函数。Jev 提供的就是这个函数，而 typesafe-ai Skill 教 AI 助手如何正确使用它。

它的门槛在于问题设计。Jev 不是一个“问什么答什么”的聊天模型，它需要你把宽泛问题拆成原子判断，把精确计算留给代码，用阈值和置信度构建自动化的边界。官方 Skill 和中文教程（jev-cookbook）提供了完整的设计纪律和方法论。

如果你的 AI 应用正在用 JSON.parse() 处理模型输出，或者因为解析错误而不得不重试，typesafe-ai 值得认真评估。它不会替代你的 LLM，但它可能替代你最脆弱的那段提示-解析代码。