typesafe-ai/skills · 上手攻略

仓库：typesafe-ai/skills
链接：https://github.com/typesafe-ai/skills
分类：agent（Agent Skill · 结构化决策模型）
作者：spark
更新：2026-10-24

一、它是什么

typesafe-ai/skills 是一个极简的 Agent Skill 仓库——它基本只有一个 SKILL.md（约 10 KB），装到 Claude Code / Codex / 其他 Agent 宿主后，让你的编码 Agent 掌握 TypeSafe System One API 的完整用法。

背后是 TypeSafe 这家公司做的 Jev：一个和 GPT/Claude 那种「生成文本」路线完全不同的模型。它接收自然语言和结构化的应用状态，吐出带类型、带概率的判断结果，直接被代码消费：

原语（primitive）	用途	返回
Choice	从一组选项里选一个	`choice` + 每个选项的 `probabilities` + `confidence`
Score	按有序档位打分	`score` + 每档 `probabilities` + `confidence` + `legend`
Noul	判断某个陈述是否为真	`noul`（0–1 的概率）
Box	在图片里定位目标	归一化的四条边坐标（需 `TypeSafe-Danger-Zone-Images: true`）

SKILL.md 本身不是软件，它是一份写给 Agent 的操作手册，内容包括：如何读实时文档、如何挑原语、如何构造问题与 criteria、哪些模式可用（路由、扇出、复合打分、置信度门控）、以及一堆指向 docs.typesafe.ai 的链接。

许可：MIT
Stars：2771（卡片记录周增 +0，采集于 2026-10-24）
成熟度：卡片标注 research
最近提交：2026-09-12（注意：距今已一个半月没动，见下文坑位）

二、它解决什么问题

核心命题：不是所有 AI 任务都需要「生成」，很多任务需要的是「判断」。

传统做法是让 LLM 生成一段 JSON 再去 parse——你得到的是「模型觉得」的文本，不是校准过的概率。你无法回答「这个分类有 0.62 还是 0.98 的把握？」「这三条都命中时要不要转人工？」

Jev 的定位是：代码掌握工作流，模型只提供可编程的常识（programmable common sense）。已知规则、计算、精确查表、执行——全留在代码里；只有需要语义理解的那一步交给模型，而且交出去的是一个带概率的判断。

SKILL.md 把这条原则写成了可执行的准则：

Keep known rules, calculations, exact lookups, and execution in code.

配合这套原语，能落地的场景包括：

路由（routing）：工单该给哪个部门？不确定的转人工。
排序/重排（ranking / reranking）：哪条候选最相关？
抽取（extraction）：从候选值里挑出正确的那个 span。
校验（verification）：这个引用真的被原文支持吗？
护栏（guardrails）：这段输入输出有没有危害？
交互式体验：根据判断结果动态组织下一步。

顺带解决一个工程现实问题：让 Agent 写出「能用」的 TypeSafe 集成需要大量上下文（原语语义、patterns、cookbooks、API 契约、SDK 用法、已知失败模式）。这个仓库把这份上下文打包成标准 Skill 格式，一条命令装上。

三、快速安装

Claude Code 插件

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

装完后可在 Claude Code 里直接 /typesafe:typesafe-ai 显式调用。

其他 Agent（Codex 等）

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

交互式选择你的 Agent。默认安装到项目级，加 -g 装到全局。

手动安装

把 skills/typesafe-ai 整个目录（含 reference 文件）复制到你所用 Agent 的 skills 目录。

更新

# Claude Code 插件
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai
# 然后重启 Claude Code 或执行 /reload-plugins
# 想开自动更新：/plugin → Marketplaces → typesafe-ai → Enable auto-update

# skills.sh 安装
npx skills update

使用

直接对 Agent 说话即可，比如：

Use TypeSafe to route incoming support tickets by department, with human review for uncertain decisions.

四、核心用法

4.1 最小可跑示例：Python SDK

先申请 API key（https://console.typesafe.ai/keys），然后：

mkdir typesafe-quickstart && cd typesafe-quickstart
export TYPESAFE_API_KEY="your-api-key"

python3 -m venv .venv
.venv/bin/pip install typesafe-sdk

保存为 route_ticket.py：

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

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."

with TypeSafeClient(model="jev-latest") as client:  # 读取 TYPESAFE_API_KEY
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should handle this",
                criteria={
                    "billing": "Payment or subscription issues",
                    "technical": "Bugs or integration problems",
                    "sales": "Pricing or account questions",
                },
            ),
            "frustration": Score(
                instructions="How frustrated the customer appears",
                criteria=[
                    "Calm, just stating facts",
                    "Frustrated but civil",
                    "Very angry, strong language",
                ],
            ),
            "is_urgent": Noul(
                instructions="The message conveys urgency or time-sensitivity",
            ),
        },
    )

print(response.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)

输出（示例值，Jev 版本间可能变化）：

technical
0.67
0.99

要求 Python ≥ 3.10。SDK extras：typesafe-sdk[http2]、typesafe-sdk[pil]（Pillow 图片）、typesafe-sdk[zstd]（压缩请求体，仅 Python 3.13 及更早）。

异步版本：

from typesafe_sdk import AsyncTypeSafeClient, Choice, Noul, Score

async def main() -> None:
    async with AsyncTypeSafeClient() as client:
        response = await client.system_one(
            state={"document": "I was charged twice. Please fix this ASAP."},
            questions={
                "billing": Noul(instructions="Is this ticket about billing?"),
                "tone": Choice(
                    instructions="What is the customer's tone?",
                    criteria={"calm": None, "frustrated": None, "angry": None},
                ),
                "urgency": Score(
                    instructions="How urgent is this ticket?",
                    criteria=["can wait", "this week", "today"],
                ),
            },
        )

4.2 JavaScript / TypeScript SDK

要求 Node.js ≥ 20（TS 直接运行需 ≥ 22.18）。

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

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.";

const client = new TypeSafeClient({ defaultModel: "jev-latest" });
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);

SDK 会从问题类型推断答案类型，所以 response.answers.department.choice 的类型是 "billing" | "technical" | "sales"。

4.3 直接调 HTTP API

要求 curl ≥ 7.76。端点是 POST https://api.typesafe.ai/v1/systemone：

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.",
  "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"
      }
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}
JSON

完整响应长这样：

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 1.0,
      "probabilities": { "technical": 1.0, "billing": 0.0, "sales": 0.0 }
    },
    "is_urgent": { "type": "noul", "noul": 0.99 }
  },
  "usage": { "input_tokens": 428, "output_tokens": 73 }
}

其他端点：GET /v1/models（列出可用模型名与别名）、POST /v1/systemone（答题）。带图片走 multipart/form-data，或 data_base64，且必须加请求头 TypeSafe-Danger-Zone-Images: true。长上下文需加 TypeSafe-Danger-Zone-Long-Context: true。

4.4 模型别名

请求里可以写 jev-latest（别名），但响应里的 model 字段是实际版本（如 jev-1.13.0）。写日志和排障时请用响应里的真实版本，别名会随官方升级而变。

4.5 SKILL.md 给 Agent 的六类模式（速览）

模式	说明
Route and fill	路由到处理器并填充类型化参数（function calling、speculative fan-out）
Select instead of generate	候选值由代码给出，模型只负责「选」（value extraction、structure recovery）
Find and judge evidence	检索候选、比较相关性、挑出有用上下文（reranking、hierarchical classification）
Turn judgments into data	一次评分，多处复用；权重/阈值/排序在代码里改（composite scoring）
Verify and escalate	对照证据核验声明，不确定的转人或转推理模型（citation checks、extraction cascades）
Respond to changing state	保留目标与观察，新判断指导下一步有界动作

五、典型适用场景

客服工单路由：一个请求同时判「哪个部门 + 有多不满 + 是否紧急」，三问一次调用，文档称并行提问比逐个问 12.2× 便宜、10.0× 快，答案不变。
RAG 答案前的段落筛选：用一次请求给每段打分，代码决定哪些段落能进生成模型。
引用核查：用一次 Choice 决定「引文上下文是否支持这个断言」，抓幻觉引用。
LLM 护栏：每次进出的消息都过一次 TypeSafe，按危害概率 + 严重度分流为 pass / review / block / route。
合规分类：把 SEC 年报分到 75 个行业组，读答案自带的 confidence 决定报细类还是报上一级大类。
抽取级联（extraction cascade）：小模型抽取 → 校验 → 推理模型兜底的两/三级结构化数据抽取流水线。
实体对齐：判断两份商品目录里的 450 对候选是否指同一商品，用一个 Score 加三个 Noul 找出分歧字段。
给 Agent 装「判断力」：不想自己写提示词，就装这个 Skill，让 Agent 按 TypeSafe 的方法论去设计。

六、坑与注意

这一节最值得读——TypeSafe 官方专门开了一页 「Jev 1.13 jaggedness」 列出已知毛刺，最后一次审阅 2026-10-02。以下 9 条是官方原文归纳。

字面理解（Literal reading）。Jev 回答的是你写下来的问题，不是你想的问题。范围词、否定、隐含条件都按字面处理。做法：把确切条件写进 instructions，边界情况放进 criteria。当你发现答案不对、然后开始解释「我真正想说的是…」——那句解释就是 instructions 缺失的那一半。实在无法避免解释时，拆成两个字面问题，在代码里组合。
它不是计算器，计数不可靠。数一个词里的字符数、统计某个词在段落里出现几次、长列表里数条目——都会错，而且规模越大误差越大（模型只是「认出答案的形状」，不是在数）。做法：能用正则或解析器算的就别问模型；要按条件数，就在代码里遍历候选、每个问一个问题、自己加总。
数值表示弱。hex 颜色值的表现明显差于英文颜色名；给它 RGB 三元组，它无法可靠判断两个值是否接近。做法：转换在代码里做，传计算好的数字或命名的桶。
不要用 score 做数值插值。可以用期望值检查「是否超过某个阈值」，但别指望在两个档位之间线性插值还原精确数值——score 的档位在数值校准上很弱。
日期当作文本读，不是有序量。「哪个日期在前」「相隔多久」「是否落在某个窗口内」都不可靠，混合格式、相对引用、季度/结算窗口/计提期这类领域边界会更糟。做法：抽取是判断（给模型），算术不是（留在代码）。把日期拆成封闭集合的选择题（12 个月、31 天、有界年份），并给每个部件一个显式的「未提及」选项，缺失被报告而不是被猜。
间接层数越少越好。双重否定、复杂间接、「关于某个属性的属性」的判断会掉准确率。做法：能直接命名 state 里相关部分就直接点名。
state 越臃肿越不准。无关细节是干扰项，而且 state 变大后你更难判断是哪部分导致了错误答案。做法：先在代码里检索+过滤，只送问题需要的字段。⚠️ 另注意：state 会按每个问题各算一次上下文额度。
对抗性内容。state 是数据，Jev 默认不把它当敌意输入。注入指令、刻意误导的框架、为自己分类辩护的文本都能移动答案。做法：criteria 要写明确，上线前充分测试边界情况。
Choice 的选项顺序会影响答案。官方观察到 Jev 有偏向靠前选项的倾向。做法：把选项换个顺序再跑一次，确认答案稳定。
instructions 与 criteria 矛盾会让人和模型都懵。例如一个 Noul 里 true 映射成「否」、false 映射成「是」，表现会明显变差。做法：criteria 当成 instructions 的延伸来写。
它不是生成模型。硬要用 choice 链拼文本会很慢且效果差。做法：抽取场景先用正则或生成模型列出候选，再用 Jev 挑。答案空间有界时，把抽取做成 Choice。
Jev 1.13 在 System One 任务上最强，但需要额外间接层的任务会吃力。
「类型化输出保证的是接口，不是真理」——官方原话。模型是为校准过的决策训练的，但必须在你的目标领域里验证它的表现。cookbook 里的阈值和 demo 结果是「供你评估的例子」，不是通用规则。
官方明确要求避免的四件事：让模型做代码能精确计算的事；把多个判断藏进一个问题里；System Two 类多级间接任务；给 state 超过问题所需的上下文。
仓库最近提交是 2026-09-12，距今约一个半月。SKILL.md 本身指向 docs.typesafe.ai 的实时文档（README 和 SKILL.md 都强调「live docs 才是 source of truth」），所以文档层面的新鲜度不依赖仓库更新——但这意味着 SKILL.md 里没有硬编码的版本号，你不会被过期版本号坑到。
Skill 本身不给你 API key。装完还得自己去 console.typesafe.ai 申请 key 并设 TYPESAFE_API_KEY。官方也提醒：API key 应该存在环境变量里，不要提交到仓库。
「Agent 没用上 skill」是常见问题。Claude Code 里显式 /typesafe:typesafe-ai，其他 Agent 里说「use the TypeSafe skill」；仍不加载就确认装的是不是你用的那个 Agent，然后重启。
「Agent 编造请求/响应字段」通常意味着 skill 版本过期——更新 skill 再试。
审核 TypeSafe 代码的重点是问题和阈值常量。官方建议把它们放在单一文件里便于 review，因为「Agent 不擅长写问题」，你要有心理准备跟它协作修改。
别到处都用 confidence 阈值。只关心选哪个的话，直接取 confidence 最高的选项；有具体统计算法的话，用 probability 而不是 confidence。
阈值调不好会两头出问题：太高漏报、太低误报。官方的排查建议是先看问题和阈值本身，可能还需要把问题写得更具体。
计费口径：响应里的 usage.input_tokens 是计费的输入 token；output_tokens 目前免费。
安装方式只选一种，否则会出现重复副本（官方明确提醒）。

七、与同类对比

维度	TypeSafe / Jev	直接调 LLM + parse JSON	本地小模型 / 分类器	传统 ML 分类器
输出形态	类型化 + 校准概率 + confidence	自由文本，需自解析	类别标签（无概率或概率粗）	类别标签 + 概率
语义理解	✅ 常识级判断强	✅ 最强	弱	❌ 需特征工程
计数/精确计算	❌ 明确不擅长	❌ 同样不擅长	❌	✅ 代码即可
状态化上下文	✅ state 显式建模	靠 prompt 拼接	✅	靠特征
成本	input token 计费，output 免费	高（生成大量 token）	极低（本地）	训练成本
延迟	快（专用决策模型）	慢	很快	极快
离线	❌ 依赖云 API	❌	✅	✅
生态成熟度	新（Skill 仓库 2026-09 最后更新）	极成熟	成熟	成熟

核心差异不是「谁更准」，而是「你拿到什么形状的结果」。 LLM parse JSON 给你的字符串；Jev 给你的带概率分布和 confidence 的结构体，可以直接做门控、排序、复合加权。SKILL.md 里那句「Typed output guarantees the interface, not truth」划清了界限——它替代的是「让 LLM 做判断后自己解析不确定性」这一层，不是替代全部 LLM 能力。

和 Claude Code 等编码 Agent 的关系：官方有一页专门叫「Jev with coding agents」，讲在有编码 Agent 的场景下 Jev 是什么、不是什么。本仓库的 SKILL.md 则更激进：直接教 Agent 怎么设计 TypeSafe 集成。两者是互补而非竞争。

八、一句话结论

推荐：如果你正在写「让 LLM 判断一下然后按结果分支」的代码——路由、筛选、校验、护栏——这个 Skill 值得装：它让 Agent 拿到正确的 Jev 用法（含那 9 条官方毛刺清单，比多数第三方教程诚实），把「不确定就转人工」这类需求变成可落地的置信度门控；但别让它替你做算术、计数和日期比较，也别在没验证校准度之前把它的概率直接当事实。

附：本文来源与核验状态

来源	用途	状态
`https://raw.githubusercontent.com/typesafe-ai/skills/main/README.md`	仓库说明、安装命令、skill 列表	✅ 已 fetch（2026-10-23 21:31 UTC）
`https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md`	SKILL.md 全文：原语、模式、设计准则	✅ 已 fetch
`https://docs.typesafe.ai/llms.txt`	文档索引（定位 API/SDK/cookbook 页面）	✅ 已 fetch
`https://docs.typesafe.ai/api.md`（→ `/api/system-one.md`）	OpenAPI 契约、请求/响应 schema、示例	✅ 已 fetch
`https://docs.typesafe.ai/introduction/quickstart.md`	Python/JS/TS/Bash 四套可跑示例、环境要求	✅ 已 fetch
`https://docs.typesafe.ai/sdk/python.md`	Python SDK 异步/同步用法、extras	✅ 已 fetch
`https://docs.typesafe.ai/model-jaggedness/jev-1.13.md`	9 条已知失败模式（坑节主干）	✅ 已 fetch（末次审阅 2026-10-02）
`https://docs.typesafe.ai/agent-skill.md`	安装/更新、示例提示词、常见问题	✅ 已 fetch
仓库卡片 `organized/repo_cards/4602-typesafe-ai-skills.md`	分类、stars 2771、MIT、最近提交 2026-09-12	✅ 已读

待核 / 不确定处： - ⚠️ 模型版本漂移：文档示例中响应 model 为 jev-1.13.0，请求用别名 jev-latest。别名当前指向哪个具体版本未核（需 GET /v1/models 实查），官方也明说别名会变。 - ⚠️ 定价未查：文档只说 input token 计费、output token 免费，未提供具体单价。本攻略未查 pricing 页，请以 console.typesafe.ai 实际显示为准。 - ⚠️ skills/ 目录下除 typesafe-ai/SKILL.md 外是否还有 reference 文件未确认：官方 agent-skill 页说手动安装要复制「包含其 reference 文件的整个目录」，但本次只 fetch 了 SKILL.md 本身，未列举目录内容。 - ⚠️ cookbook 中的性能数字未逐一核验：并行提问 12.2× 便宜 / 10.0× 快、重排 top-1 从 5%→18%、top-10 从 38%→62%、SEC 年报 75 组分类等数字均转述自 docs.typesafe.ai 的 cookbook 描述，未跑 benchmark 复现，也未核实其基线与数据集版本。 - ⚠️ 仓库 stars 2771 与周增 +0：卡片采集于 2026-10-24，本次未独立用 GitHub API 核对 stars 数。 - ⚠️ 本攻略未调用 TypeSafe API（无 key、未注册），所有代码为文档原文转录。