AbdelStark/awesome-typesafe · 上手攻略

• 仓库：AbdelStark/awesome-typesafe
• 链接：https://github.com/AbdelStark/awesome-typesafe
• 分类：AI工具导航 / TypeSafe生态
• 作者：Tom
• 更新：2026-09-21

是什么

awesome-typesafe 是一个关于 TypeSafe AI（System One / Jev 模型）生态的精选资源列表，由社区维护（与 TypeSafe 公司无附属关系）。

TypeSafe 的核心产品是 Jev——一个专门做「结构化决策」的模型：不给自由文本，而是返回类型化的概率决策（Choice 多选一、Score 打分、Noul 二选一）。这个列表收录了官方资源 + 社区项目，帮助开发者理解 Jev 的模型形态、用它构建应用、测试边界，以及复现社区实验。

内容包括： - 官方文档、SDK、API 参考 - 概念指南、设计模式、Cookbooks - 研究论文与博客 - 各语言的客户端库（Rust、Go、Java、Kotlin、PHP、Ruby、Swift、Scala、Elixir、C# 等） - Agent 工具、浏览器 Agent、金融/交易、游戏等社区案例

解决什么问题

Jev 和传统的 text-generation LLM 完全不同——它输出的不是文字，而是结构化的概率决策。对于第一次接触 TypeSafe 的开发者来说，最大的障碍是「不知道这玩意儿怎么用、可以用在哪里、有什么现成的库」。

这个列表的价值在于： - 新手入口：从官方 Quickstart 到设计模式，按学习路径组织 - 多语言支持：不管你用什么技术栈，都能找到现成的 SDK - 应用参考：看其他人在工单路由、游戏、SQL 生成、Home Assistant 等场景怎么用的 - 最新动态：有 Discord、X、LinkedIn 社区信息

快速上手

直接打开 GitHub 页面浏览：https://github.com/AbdelStark/awesome-typesafe

或访问在线版：https://abdelstark.github.io/awesome-typesafe/

官方必读（按顺序）

1. Introduction — Jev 是什么，Choice/Score/Noul 三种原语是什么
2. Quick start — 最短路径：拿到 API key → 发出第一个决策请求（Python 或 JS）
3. How to build with System One — 设计指南：如何把一个业务流程拆成多个窄判断，策略和副作用留在代码里
4. Patterns — 置信度门控路由、复合打分、投机式展开、意图路由
5. TypeSafe Console — 申请 key 并在线调试 Jev 请求

核心 API 调用（Python）

pip install typesafe-sdk

from typesafe_sdk import TypeSafeClient

client = TypeSafeClient(
    api_key="tsk_your_key_here",  # 从 console.typesafe.ai 获取
    base_url="https://api.typesafe.ai",  # 官方端点
)

response = client.system_one(
    state="Your order arrived damaged and I was charged twice.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which team should handle this?",
            "criteria": {
                "returns": "Exchanges, refunds, wrong or damaged items",
                "billing": "Charges, invoices, payment problems",
            },
        },
        "urgent": {
            "type": "noul",
            "instructions": "Does this need urgent human attention?",
        },
    },
)

print(response.choices["department"].choice)   # e.g. "returns"
print(response.nouls["urgent"].noul)            # e.g. 0.87

注：上方是官方云端 API 方式；如果你想用本地模型（如 jaredpalmer/kev），可以用 system-one-adapter-python 让同一套代码跑在本地。

核心概念

Confidence（置信度）字段：choice 的 confidence = (p_max − 1/K) / (1 − 1/K)，score 的 confidence 衡量分布集中程度。不是准确率，不要当成「这个答案 80% 可信」来用。

典型适用场景

• 工单/客服路由：最经典用法，一次请求同时判断部门 + 紧急度 + 情绪
• 置信度门控：confidence 高于阈值才执行动作，低则人工复核
• SQL 生成前的策略判断：在让 LLM 生成 SQL 之前，先用 Jev 判断「这是不是查询类请求、需不需要加防护」
• 游戏 AI：Chess 示例中用 Choice 选走法，Score 评估局面（见 Kev 项目）
• Home Assistant：HA-Jev 项目把 Jev 决策接到 Home Assistant 自动化
• SEO 审计：BTK 研究用 Jev 批量判断 1,204 个页面的 SEO 状态，每次 12 个查询批处理

社区亮点项目

• s1-rs — Rust derive 层，支持 Choice/Score/Noul、置信度门控、网络免费测试
• HA-Jev — Home Assistant 集成，把 Jev 决策变成传感器和自动化动作
• jevql — 让 Jev 决策走进 SQL：WHERE jev(alias, 'condition')，Postgres 端过滤 + Jev 端判断
• Hunch — Ruby gem：if Hunch.likely?("fraudulent", given: order) 直接做控制流
• scala-jev-sdk — Scala 3 客户端，支持 cats-effect、ZIO 等 effect 系统

完整列表见仓库 README，涵盖客户端库、Rust/Go/Java/Kotlin/PHP/Ruby/Swift/Scala/Elixir/C#、Agent 工具、浏览器 Agent、金融交易、游戏等十几个分类。

坑与注意

1. 独立社区项目：列表本身由社区维护，各社区项目的质量参差不齐。README 也说了「read the code, licenses, data-handling notes, and evaluation caveats before using them in a consequential system」，用之前先过一遍代码。

2. Confidence 不是准确率：这是 Jev 的设计特点，第一次用容易误解。Confidence 是分布集中度的数学变换，不等于模型答对的比例。

3. 生态还在快速演进：README 最后更新日期 2026-09-17，且明确说明「Jev and its ecosystem are moving quickly」。选型前建议确认各 SDK 和项目是最新版本。

4. 本地模型 vs 云端：TypeSafe 是托管云服务（需要 API key 和费用）；如果想完全本地，可以看看 system-one-adapter-python 用本地 LLM，或 jaredpalmer/kev。

5. 非官方声明：awesome-typesafe 不是 TypeSafe 官方维护的仓库，官方维护的是 typesafe-ai 组织下的各 SDK。

与同类对比

一句话推荐结论

如果你在用或打算用 TypeSafe Jev 做结构化决策，awesome-typesafe 是最完整的社区导航——覆盖官方资源、各语言 SDK、应用案例，无论你是想快速入门还是深入某个语言生态，都能在这里找到入口。