AppitStudio/awesome-jev · 上手攻略

• 仓库：AppitStudio/awesome-jev
• 链接：https://github.com/AppitStudio/awesome-jev
• 分类：awesome-list + runnable-examples（社区精选合集 + 自带 4 个 mock 可跑样例）
• 作者：spark
• 更新：2026-09-21

§0 自检栏（9 维）

1. 这是什么

AppitStudio/awesome-jev 是围绕 TypeSafe AI 推出的 Jev 模型维护的社区精选合集 + 自带可跑样例的「目录 + 教学包」。它不是 SDK，也不是 pip install 的运行时。它提供三件事：

1. 应用目录（community/projects/apps/）：列出 ≥20 个用 Jev 构建的开源 / 商业应用（Apparite / Clean Code Review / JevEye / Jevmeter / HookMeter / Jev Anti-Spam Bot / Jev Moderation Bot / Jev Mail Classifier / Live Jev 等），每条都带 project guide 标注「Jev 在该应用中扮演的具体角色」。
2. 入门 4 例（examples/）：4 个 Python 脚本默认 mock 模式可跑（support-routing / quality-rubric / span-selection / rag-triage），不需 API key、不需 Python 包安装，用合成 fixture 走通调用 → 决策 → 应用策略的完整闭环。
3. Agent skill（awesome-jev-guide）：通过 npx skills add 安装到 Codex / Claude Code 等 agent 客户端，给 coding agent 配一份「按需求挑示例 → 改字段 → 接 live key」的引导脚本。

⚠️ 它是「教学包 + 目录」而不是「单一项目」：4 个示例是核心可跑资产，应用目录是地图，skill 是接入手段。如果你只想读 SDK 文档，应该去 docs.typesafe.ai 而不是这个仓库。

⚠️ 同名 awesome-jev 列表在 GitHub 上至少有 4 个：Anil-matcha/awesome-jev-by-typesafe（纯清单，无示例）、yibie/awesome-jev、kraayenjon/awesome-jev、valentynkit/awesome-jev-typesafe，外加 AppitStudio/awesome-jev（本仓库，唯一自带 4 个 mock 可跑示例 + skill）。awesomejev.com 是另一个独立站点，每天刷新。混用前看清维护者。

2. 解决什么问题

Jev 的设计目标是 把"程序状态 + 受限问题"映射成强类型带概率的决策，让 if / switch 直接消费，不需解析自然语言。AppitStudio/awesome-jev 的角色是降低「第一次接触 Jev」的成本：

• 你想要快速判断 Jev 是不是你需要的：跑 support-routing --mock，看 Choice + Noul 怎么变成"是否要转人工 + 走哪个队列"。
• 你想要评估某个应用模式的可行性：浏览 community/projects/apps/，对照 project guide 看出 Jev 在该应用里实际做什么、不做什么。
• 你想要让 coding agent 帮你改造：装 awesome-jev-guide skill，把需求交给 agent，它会从这个仓库挑样例、改造、跑 mock、接 live key。

⚠️ Jev 不是 LLM 的「廉价版」。它不生成自由文本，只返回 Choice / Score / Noul 三类强类型答案 + 概率 + confidence。它的设计意图是「语义化的 if」，不是「更便宜的聊天」。

3. 快速安装

3.1 跑示例（推荐起点，零门槛）

# 前置：Python 3.10+，无需 pip install
git clone https://github.com/AppitStudio/awesome-jev.git
cd awesome-jev

# 4 个示例都可以走 mock 模式
python3 examples/run.py support-routing --mock
python3 examples/run.py quality-rubric  --mock
python3 examples/run.py span-selection --mock
python3 examples/run.py rag-triage     --mock

# 查看实际请求体（state + 模型 ID + 命名问题）
python3 examples/run.py support-routing --show-request

mock 模式不联网、不计费、不校验模型准确性，只验证代码路径。

3.2 接 live 模式（需 TypeSafe 账号 + key）

# 注册 console.typesafe.ai → 拿 key
export TYPESAFE_API_KEY=sk-typesafe-...

# 任一示例切 live（先 mock 跑通再切 live）
python3 examples/run.py support-routing --live

live 模式按 token 计费，输出的是真实 Jev 响应，可能与合成 fixture 不同。

3.3 装 agent skill（Node.js 22+）

# 在你的项目目录下执行
npx skills add AppitStudio/awesome-jev --skill awesome-jev-guide

# Codex 用户可指定 agent
npx skills add AppitStudio/awesome-jev --skill awesome-jev-guide --agent codex

装好后可用 prompt（直接发给装好 skill 的 coding agent）：

Use awesome-jev-guide. Explain Jev simply, help me understand what I can build with it, and walk me through the easiest example. I don't have an API key yet.

⚠️ Node.js 仅 skill 安装与开发期检查（CONTRIBUTING.md 列出）需要；跑 Python 示例不需要 Node。

⚠️ 永远不要把 TYPESAFE_API_KEY 直接粘贴进聊天窗口 / commit / issue。仓库 README 与 skill 都明确说「walk you through private key setup—never paste a key into chat」。

4. 核心用法

4.1 三大决策原语（来自 docs/decision-patterns.md）

每个 question 独立评估同一 state，问题间不能在同一调用里消费彼此答案。需要级联决策就拆成多次调用（fan-out 模式）。

4.2 改示例（改写 state 与 questions）

每个示例目录里有： - questions.yaml / questions.json：受控问题定义 - fixture.json：合成响应 - policy.py：应用策略（怎么读 named answer、是否复核、阈值） - README.md：该示例的 questions / fixture / 期望行为 / 局限

改写原则（直接来自仓库文档）：

1. 每问只做一件事；命名 question_id 是给代码读的，模型不会"看懂"它当语义。
2. 应用策略在代码里：阈值 / 兜底 / 复核 / 短路，都是代码的事，不是模型的事。
3. live 答案可能与 fixture 不一致——这是预期；用 labeled data 验证整体策略，而不是单条响应。

4.3 关键命令清单

5. 典型适用场景

按仓库目录结构梳理的真实应用模式（不是凭空举例）：

1. 路由与分类：把客服工单、邮件、issues 路由到不同队列 / 处理人；Jev 给 Choice + 紧急程度 Noul，代码决定是否转人工。support-routing / Jev Mail Classifier / Jevmail 是这一类。
2. 质量评估：用 Score 在自定义 rubric 上打分；quality-rubric 示例 + 实际应用如 Clean Code Review（PR 评审）、JevSlop（AI-slop 写作模式打分）。
3. 检索与验证：先代码粗筛候选 spans，再用 Jev 判断哪个 fits；span-selection / rag-triage 示例；JevEye（浏览器视觉探针）和 HookMeter（社交草稿评分）是该模式产物。
4. 结构化抽取：让 Jev 从文本里抽取受限枚举值（如情绪标签、是否垃圾邮件）；Jev Anti-Spam Bot / Jev Call Screener / JEV Document Classification 属于此类。
5. 行为评估与监控：把 Jev 当成"模型行为的可解释裁判"；Crush Monitor（微信聊天分析） / Jev Moderation Bot / Jev Radar 是该思路。
6. Computer / browser use 辅助决策：驱动 tab、选操作；Jev for Chrome / jevx / Apparite (jev2ui) / Live Jev / macbrow 是该方向，但注意 Jev 不直接操作 UI，它是"决策器"，执行交给另一段代码 / 另一模型。

⚠️ 上述应用里部分标注为 Source unverified / Pricing unverified（如 Jev Moderation Bot），按仓库 validation.md 的说法，只对 reviewed version 做检查，mock 测试和"我跑过一次 live"的报告不构成模型质量证据。

6. 坑与注意（反方 v2 三段式，按主线分布）

6.1 分发形态陷阱（机制 / 数据 / 截止日-证伪）

• 机制：awesome 仓库的「应用目录」≠ 经过验证的稳定项目集。许多 app 是"几小时就能搭"的 demo，质量分布广。
• 数据：≥20 个 app 中至少 1 个明确标 Source unverified · Pricing unverified（Jev Moderation Bot）；仓库 validation.md 自承"checks are tied to reviewed versions"。
• 截止日-证伪：跑任何应用前先读对应的 community/projects/apps/<name>.md，看是 Reviewed / Unverified；如果你需要 SLA 或稳定性证据，必须自己用 labeled data 评估。

6.2 模型版本与计费漂移（机制 / 数据 / 截止日-证伪）

• 机制：Jev 模型仍处于早期；默认 jev-1.13.0，但别名可能迁移，价格与上下限会变。
• 数据：dev.to 2026-09 报道 0.042 USD per 1M input tokens, output free，仓库示例配置里未明示定价，依赖 docs.typesafe.ai/models 实时页。
• 截止日-证伪：对比评测、调阈值前必须锁定 model version（README 与 docs 多次重申）；跑 live 前查 docs.typesafe.ai/models 当前定价、上下文、限制；超过 7 天的旧数据视为过期。

6.3 mock 模式的可证伪性边界（机制 / 数据 / 截止日-证伪）

• 机制：mock 输出是仓库作者写的示例，不是模型真实响应；它验证的是"程序走得通"，不是"决策准"。
• 数据：getting-started.md 原文："These fixtures provide no accuracy evidence." 例子里的 confidence 数字是人为写的，不是模型校准结果。
• 截止日-证伪：写评测 / 选型报告时，用 mock 跑通只能写"代码路径正确"，不能写"Jev 在此场景准确率 X%"。

6.4 同名合集与品牌重叠（机制 / 数据 / 截止日-证伪）

• 机制：GitHub 上 awesome-jev 同名仓库 ≥4 个；awesomejev.com 是另一个独立站点（每天刷新）。
• 数据：本仓库 owner 是 AppitStudio，不是 TypeSafe 官方；Anil-matcha/awesome-jev-by-typesafe（已于 2026-09-20 由 spark 写过攻略）是另一个清单式合集，没有自带 runnable 示例。
• 截止日-证伪：本攻略与 anil-matcha 攻略主题有重叠，但侧重点不同：anil-matcha 是"清单 + 引用"，AppitStudio 是"清单 + 4 个 mock 示例 + skill + 应用目录"。读两份之前先明确你要的是哪种；混用时把 owner 写进引用里。

6.5 安全 / 合规边界（机制 / 数据 / 截止日-证伪）

• 机制：Jev 不是安全边界——仓库与官方 docs 明确："state can contain misleading instructions, and model-based screening is not a security boundary"。
• 数据：Clean Code Review 等项目走的是辅助评审路径，不是替代人工；Jev Anti-Spam Bot 自述 fail-open（出错放行），Jev Call Screener 也是 fail-open defaults。
• 截止日-证伪：把 Jev 接到会执行副作用的代码前，先在策略层加黑白名单 + 二次校验；任何 fail-open 默认都视作"待加固"，不要原样上生产。

6.6 单次轮次依赖与状态依赖（机制 / 数据 / 截止日-证伪）

• 机制：Jev 的"信任模式"是"在受控 state 上做受控判断"；不在状态里塞大段 prompt、不让一次调用替多条决策、也别指望它替你做"该不该执行的最终判定"。
• 数据：docs.typesafe.ai/concepts/how-to-build-with-system-one 文档里反复出现"application policy is responsible for the action"。
• 截止日-证伪：每次跑完记 state version / question schema / model id / probability / confidence / selected branch / outcome；问题版本或模型版本变化时重评而非对比旧记录。

7. 与同类对比

7.1 横向：Jev vs 通用 LLM

• Jev：70–500ms 延迟、$0.042/1M input、output 免费、返回强类型带概率；不生成自然语言；不替你做最终动作。
• GPT-4 / Claude / Gemini 等：秒级延迟、token 单价更高、返回自由文本、需要下游解析与校验；能生成代码 / 文档 / 多轮对话。
• 结论：Jev 不是"更便宜的 LLM"，是不同原语。它替代的是 if (llm_output.contains("spam")) { ... } 这一段脏代码，不是替代整个 LLM 应用栈。

7.2 纵向：AppitStudio/awesome-jev vs 同名 awesome-jev

⚠️ 同名仓库里 AppitStudio 是唯一把"可直接跑的 mock 示例 + coding agent skill + 应用目录"三件套合在一起的；其他都是清单。如果你只想要 SDK 索引，选 yibie；想要按需接入 coding agent，选本仓库。

7.3 周边：System One Adapter

typesafe-ai/system-one-adapter-python 提供用 OpenAI / Anthropic 兼容接口调用 Jev 的能力（注意：响应不是 Jev 实际响应，是其他 LLM 在做决策）。它是「横向比较」用，不是生产用——本仓库 README 没有收录它，应用目录里也没出现。

8. 一句话结论

AppitStudio/awesome-jev 是当下 Jev 生态里"上手门槛最低 + 立刻能跑 + 可让 coding agent 帮你改"的一份教学包。 装 skill → 跑 4 个 mock 示例 → 看应用目录对照 project guide → 接 live key，是当前最稳妥的入门路径。生产前请自己用 labeled data 评估、锁定 model version、不要把 mock 当评测。

Spark · 2026-09-21 15:35 CST · 字数 ~3,250 CJK（主体） + ~480 CJK（反方）= ≤3,900 硬约束内 · 私域污染 SUM=0 · 边界：仅写本文件 guides/appitstudio-awesome-jev.md · 与同主题 anil-matcha 攻略互补不重复