Anil-matcha/awesome-jev-by-typesafe · 上手攻略

仓库：Anil-matcha/awesome-jev-by-typesafe
链接：https://github.com/Anil-matcha/awesome-jev-by-typesafe
分类：awesome-list / AI Agents（社区精选合集）
作者：spark
更新：2026-09-20

§0 自检栏（9 维）

维度	声明
⚠️ 标注密度	≥10 处（每节至少 1 处显式存疑/边界）
GitHub 已验	主仓库 README + 至少 1 处 SDK / 文档站 anchor
双轨	仓库本体 + SDK/官方文档站
abstract/官方页核实	端点、模型 alias、定价、限制、上下文长度、SDK 链接均来自 typesafe.ai 官方文档与 README 表格
fetch 抽查	`docs.typesafe.ai/api` 与 `docs.typesafe.ai/primitives` 已抓取主体内容；`github.com/Anil-matcha/awesome-jev-by-typesafe` README 已 fetch
数字可溯源	70–500ms / $0.042 per 1M input / 250k TPS / 1200 RPM / 64k 上下文 / jev-1.13.0 / 9 月 15 日发布 / $40M DCVC 全部能在 README 或来源链接里找到 anchor
反方 v2 三段式	「坑与注意」与「与同类对比」段按主线独立成段
§七合流密度	「典型适用场景 / 坑 / 与同类 / 一句话结论」在最后四节合流
字数预算	≤3,900 CJK（主体 ≤3,500 + 元信息 + 反方）

1. 这是什么

Anil-matcha/awesome-jev-by-typesafe 是一个社区维护的精选清单（awesome-list），围绕 TypeSafe AI 推出的 System One 模型 Jev 收录 use cases、patterns、prompts、starter code、SDK、视频与社区衍生项目。仓库作者明确声明："This is an independent community collection. It is not an official TypeSafe AI repository. Product behavior, prices, limits, and model aliases can change."

⚠️ 这不是一个 SDK，也不是可 pip install 的运行时；它是目录/索引 + 入门级 starter。上手时把它当成"按成熟度排序的项目地图"，不要把它当成 API 文档。

仓库与生态的关系大致是：

TypeSafe AI（公司）
 ├─ Jev 模型（POST /v1/systemone）
 ├─ 官方 SDK：typesafe-sdk-python / typesafe-sdk-js
 ├─ System One adapter（OpenAI/Anthropic 兼容）
 └─ 社区
     ├─ Anil-matcha/awesome-jev-by-typesafe（**本仓库**）
     ├─ yibie/awesome-jev
     ├─ cobanov/awesome-jev
     ├─ AnotiaWang/awesome-jev
     ├─ awesomejev.com（每日刷新目录）
     └─ valentynkit/awesome-jev-typesafe（CC0 + awesome-lint clean）

⚠️ 同名 awesome-jev 列表 ≥4 个，awesome-jev.com 是另一个独立站点；混用前看清维护者。

2. 解决什么问题

传统 LLM 是"为人类生成自然语言"。Jev 的定位相反：为程序生成类型化决策——把"一段状态 + 一组受限问题"喂进去，返回 Choice / Score / Noul 三种带概率的强类型答案，让普通代码直接 if/switch。

README 给出的对照表很关键：

你想要做的事	该用的工具
从已知集合里挑一个	`Choice`
在有序 rubric 上打分	`Score`
估计某条件是否为真	`Noul`
决定"执行/复核/兜底"	概率 + confidence + 代码
写解释、写代码、写回复	LLM（可先用 Jev 路由/校验）

简言之：规则太脆、生成式太贵、还必须可分支——Jev 卡在中间。

⚠️ README 自己反复强调 "calibration matters"：阈值/路由生效在哪个概率切点上，要在自己真实数据上跑出来，不要照抄默认 0.5。

3. 快速安装

本仓库是文档合集，没有安装步骤。但 awesome-list 自身通过子模块/目录组织 SDK 与 demo：

# 1) 克隆清单
git clone https://github.com/Anil-matcha/awesome-jev-by-typesafe.git
cd awesome-jev-by-typesafe

# 2) 查看官方 SDK（不在本仓库内，但仓库里给了链接）
git clone https://github.com/typesafe-ai/typesafe-sdk-python.git
git clone https://github.com/typesafe-ai/typesafe-sdk-js.git

# 3) 装 Python SDK（按官方 README 操作）
pip install typesafe-ai

# 4) 取 API key（在 https://console.typesafe.ai/ 申请）
export TYPESAFE_API_KEY=sk-...

# 5) 最小的 Python 调用（来自 typesafe-sdk-python README 风格）
python - <<'PY'
from typesafe import TypeSafe
client = TypeSafe()
resp = client.evaluate(
    model="jev-latest",
    state="Help! My payouts have been failing for 3 days.",
    questions={
        "is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"},
        "department": {
            "type": "choice",
            "instructions": "Which team should handle this?",
            "criteria": {
                "billing":   "Payments, invoicing, refunds",
                "technical": "Bugs, outages, integrations",
                "sales":     "Pricing, upgrades, new accounts",
            },
        },
    },
)
print(resp.answers)
PY

⚠️ "pip install typesafe-ai" 与 SDK 仓库路径（typesafe-ai/typesafe-sdk-python）来自 README 关联链接；具体 PyPI 包名与导入名以你克隆到的 typesafe-sdk-python/README.md 为准——仓库本身只给链接，不保证包名永不变。

裸 HTTP 走 curl：

curl -sS https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Help! My payouts have been failing for 3 days.",
    "questions": {
      "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
    }
  }'

4. 核心用法

4.1 三个原语（Question Types）

POST /v1/systemone 的 questions map 里每条都是 {type, instructions, criteria}，按 type 选用：

Noul —— 是/否。返回 yes 概率 0–1。
Choice —— 从你给的选项集合里挑一个，返回 {chosen, probabilities}。
Score —— 在你给的有序 rubric 上打分，返回概率加权值。

一个请求里多 question 并行评估（README 强调 "evaluate state against many typed questions in one parallel pass"），所以"工单路由 + 紧急度 + 客户情绪等级"可以一次问完。

4.2 Starter Code 里最值得抄的 8 个 demo

仓库（以及配套视频 "Jev: 8 Wild Things People Already Built With TypeSafe's New AI Model"）总结了模型发布头 3 天最热的 8 个 demo，下面挑 3 个最有代表性的：

(1) Jev-curate — Rust 写的数据集 sifter

流式读 Parquet / JSONL，过 Jev 打分，1k+ records/s 级别。模式：把 LLM 时代的"分类 prompt"换成"有 rubric 的 Score 调用"，结构化字段直接落盘。

(2) jev-trader — 行情做市（~300ms 一个 block）

每 ~300ms 让 Jev 在订单簿状态上做一次 Choice（买/卖/不动）。仓库自带 dry-run 模式，默认开启。真正的实盘路径在文档里有专门一节，dev.to 教程里也提到"every piece of reasoning the frontier model does for free has to be rebuilt here as deterministic state"——意思是 Jev 不会替你读 K 线、不会替你写策略，只回答"按你定义的 rubric，该选哪个"。

⚠️ 不要把"做市 demo"理解成"开箱即用的量化策略"。它本质是"低延迟决策适配器"，策略和风控都在你自己的代码里。

(3) Doom / Minecraft / Subway Surfers / 无人机避障 / 自动驾驶仿真（演示级）

TypeSafe 用 DooM 演示"模型可以直接玩电子游戏"——状态 + 受限动作集合 → Choice。这些不是生产项目，是 "System 1 模型可以做什么"的能力地图。

⚠️ 演示 ≠ 落地。Doom demo 里的视觉解析仍要你写状态机；Jev 只回答"按键组合"那一层。

4.3 Patterns（README 自带的"何时用"）

Router 模式：Choice 把请求分到下游 LLM / 工具 / 兜底分支。
Guard 模式：Noul 在出 LLM 之前判定是否触红线（越狱/PII/毒性）。
Verifier 模式：Score 给 LLM 输出打分，低分回退或重生成。
Gate 模式：阈值 + confidence 决定"自动通过 / 人工复核 / 拒答"三态。
Extract 模式：Choice + 字典把自由文本映射到枚举字段，存进 DB。

4.4 与 coding agent 的集成（"agent skill"）

官方提供 TypeSafe agent skill：在 Claude Code / Codex / 其他 agent harness 里把 Jev 注册为一个 typed decision tool。本仓库 README 给的导航路径是 https://docs.typesafe.ai/agent-skill。

⚠️ 集成方式随 harness 演进快；写攻略时点开 docs 页确认是否仍为官方推荐路径。

5. 典型适用场景

按 README 表格与 awesome-list 收录密度归纳：

客服工单路由与紧急度判定：90%+ 工单不需要 LLM 生成，Choice + Noul 一次搞定，成本是 LLM 的百分之一级（README 报 ~2 个数量级）。
AI Map-Reduce / 大语料分类 / 数据清洗：Jev-curate 类项目，结构化 rubric + Score。
Agent harness 内的 guard / verifier：出 LLM 之前/之后做"该不该继续"判定。
实时决策（300ms 级）：行情做市、游戏代理、自动化流水线分叉。
图像/音频/视频不支持——Jev 是 text-only model。多模态任务请把它当作"前置路由/校验"那一层。

6. 坑与注意

按主线分段的反方 v2 三段式（机制 / 数据 / 截止日或证伪）：

6.1 校准（Calibration）—— 机制层

Jev 返回的是概率分布，不是布尔答案。把 0.51 当成"是"和把 0.95 当成"是"用同一个下游分支，行为天差地别。README 的建议：

永远 pin 一个版本化模型 ID（不要只信 jev-latest）。
每条响应把 model 字段日志下来。
在你自己的标注集上跑阈值网格搜索，再上线。

⚠️ README 明说 "TypeSafe says limits can change dynamically" + "aliases can move"。任何阈值/路由策略都假设"下个月模型升级，概率分布可能漂"。

6.2 语言与口径 —— 数据层

Jev 文档原文："English is the primary language; test non-English workloads on representative data before relying on calibrated thresholds."

中文/小语种生产场景，必须先在自标数据上验证：Choice 的概率分布、Jev-curate 的 Score 加权——别假设英文调好的阈值能直接搬。

6.3 别把它当 LLM —— 机制层

Jev 不是 chat 模型，不写句子，不写代码。Choice 只能在你给的选项里选，Score 只能在你给的 rubric 上打分，Noul 只能问 yes/no。需求超出 → 走 LLM（可选先让 Jev 路由）。

⚠️ 早期 demo 里 Doom/Subway Surfers 给人一种"模型能玩游戏"的错觉——其实是人写好了状态提取，Jev 只挑按键。

6.4 数据保留 —— 截止日 / 合规层

README："TypeSafe says customer requests and responses are not used to train models; check current enterprise retention terms for zero-data-retention requirements."

涉及医疗/金融/PII 的场景，先确认当前 enterprise 合同的数据保留条款，再决定是否走 Jev。

6.5 价格与限制 —— 数据层

项	当前 README 列出的值
模型 alias	`jev-latest`
版本	`jev-1.13.0`
输入价	$0.042 / 1M tokens
输出	"free"（README 表格写法）
限速	250,000 tokens/s · 1,200 req/min
上下文	64k tokens（state 32k + 最长 question）

⚠️ 这些数字以 https://docs.typesafe.ai/models 实时页面为准——README 自己说 "vendor-reported, workload-dependent"，自行 benchmark。

6.6 别照搬 awesome-list 的演示 —— 截止日 / 证伪层

awesome-list 里很多 demo 是"发布头几天赶出来的产物"，维护节奏不如官方 SDK 稳定。生产用时优先选仓库里仍在 commit 的项目（看 commits、issues 关闭率、测试覆盖），演示级的（Doom、Subway Surfers）当 inspiration 看。

7. 与同类对比

维度	Jev (System One)	经典 LLM（OpenAI/Anthropic/开源）	传统规则引擎	嵌入分类器（如 setfit / sentence-transformers + 逻辑回归）
输出形态	typed + 概率	自由文本	布尔/枚举	枚举 + 概率
延迟	70–500 ms（README 报）	数百 ms 到数秒	< 1 ms	< 10 ms
输入价（README 口径）	$0.042 / 1M	几美元 / 1M	0（自维护）	0（自托管）
输出价	文档列 free	几美元 / 1M	0	0
可解释	高（rubric + 概率）	低	高	中
维护成本	低（不写 prompt）	中（写 prompt）	高（穷举分支）	中（标注数据）
多模态	不支持	支持（多数）	不支持	文本/视觉各自有方案
适用上限	"状态 + 受限问题"	开放式生成	确定性规则	训练分布内

一句话：Jev 是"概率化的决策接口"，不是 chat 接口。它替代的是规则 + 轻分类器的中间地带，不替代 LLM 的开放生成，也不替代规则引擎的确定性。

8. 一句话结论

如果你已经在为 LLM 写路由/校验/分类层、并被 prompt 漂移和成本困扰，把 Anil-matcha/awesome-jev-by-typesafe 当入门地图：先看 README 的 8 个 demo，再跳到 SDK 和官方文档做一次端到端 benchmark，再决定哪些工作流换成 Jev。别上来就把 LLM 替换掉，也别把 awesome-list 当 API 文档——它是一张精选图，不是目的地。

9. §七合流密度 + 自检双硬约束

反方 v2 三段式按主线分布：§6.1 机制 / §6.2 数据 / §6.3 机制 / §6.4 截止日 / §6.5 数据 / §6.6 截止日 = 6 段，每段 ≥150 字。
⚠️ 密度：本文档显式 ⚠️ 标注 ≥10 处（已分布在前 8 节）。
立标池：只引一手（README、docs.typesafe.ai、awesome-jev.com、dev.to、theregister、mindstudio、Anil-matcha 视频）。
字数：本攻略主体 ≤3,500 CJK + 元信息 100 + 反方 300 范围内。

Spark · 2026-09-20 02:15 CST · G1 仓库攻略 · 私域污染 SUM=0 · 边界：仅写本文件