AI DAILY / 2026-09-30

building-with-typesafe-jev：教编码代理使用 Jev 的非官方技能包

aaddrick/building-with-typesafe-jev

AI 编程实践GitHub · 2026-09-26

全文中文翻译 · AI 生成，仅供学习交流

aaddrick/building-with-typesafe-jev

编码代理（coding agent）往往把 Jev 当成又一个聊天模型来对待。这个技能（skill）教会它们专门围绕 Jev 做设计：类型化的问题（typed questions）、校准后的置信度（calibrated confidence），以及按"实现形态"分类的 150 多个社区项目链接，每种形态都附带一段代码草图。它可以安装到 Claude Code、Codex、Antigravity CLI、Muse 和 Muse Code 中。

Jev 是一种 System One 模型（译注：源自 Kahneman 的"系统一/系统二"概念，指快速、直觉式的判断模型）。它不生成文本。你把内容和一组类型化的问题发给它，它会为每个问题返回一个值和一个经过校准的概率，耗时通常在 100 到 200 毫秒之间：

- Choice（选择）：从列表中挑一个选项。例如：把工单分发给计费、物流或客服。
- Score（打分）：把内容放到你描述的量表上。例如：把一个拉取请求（pull request）从"完全不符合规范"到"完全符合规范"打一个等级。
- Noul（概率）：给出一个"是/否"判断为真的概率。例如："这条 shell 命令会删除项目之外的文件吗？"

安装

Claude Code

claude plugin marketplace add aaddrick/building-with-typesafe-jev
claude plugin install building-with-typesafe-jev@building-with-typesafe-jev

当你处理 Jev 相关代码时，技能会自动加载。手动加载请输入：

/building-with-typesafe-jev:building-with-typesafe-jev

Claude Desktop、Cowork 和 claude.ai

第一步。打开 Customize > Plugins（自定义 > 插件），选择 Add（添加），然后选 Add marketplace（添加市场）。

第二步。选择 Add from a repository（从仓库添加）。

第三步。输入 aaddrick/building-with-typesafe-jev。保持 Sync automatically（自动同步）开启，这样当该仓库更新时插件也会同步。然后选择 Sync（同步）。

第四步。在 Building with typesafe jev 旁边选择 Add（添加）。

第五步。Claude 确认插件已安装。它也会出现在同一账号的桌面应用和 Cowork 中。

Codex

codex plugin marketplace add aaddrick/building-with-typesafe-jev
codex plugin add building-with-typesafe-jev@building-with-typesafe-jev

开一个新会话。当任务匹配时，Codex 会自动加载该技能。手动加载请输入：

$building-with-typesafe-jev:building-with-typesafe-jev

Antigravity CLI

agy plugin install https://github.com/aaddrick/building-with-typesafe-jev

确认安装是否成功：

agy plugin list

开一个新会话。当任务匹配时，Antigravity CLI 会自动加载该技能。手动加载请输入：

/building-with-typesafe-jev:building-with-typesafe-jev

来自 Gemini CLI？如果 agy plugin import gemini 把这个扩展带了过来，仍然请运行上面的安装命令，用当前版本覆盖导入过来的旧版本。

Muse (muse.ai)

Muse 会从它自己电脑上的 ~/workspace/skills/ 自动加载技能。把下面的命令粘贴进 Muse 对话框，让 Muse 来运行它：

curl -fsSL https://raw.githubusercontent.com/aaddrick/building-with-typesafe-jev/main/scripts/install_muse.sh | bash

脚本会把技能文件夹复制到那里，并把 SKILL.md 的头部重写成 Muse 能读取的格式。开一个新聊天。当任务匹配时，Muse 会自动加载该技能。如需更新，再次运行该命令即可。

Muse Code

克隆仓库：

git clone https://github.com/aaddrick/building-with-typesafe-jev.git

为每个项目安装技能：

muse skills install building-with-typesafe-jev/skills/building-with-typesafe-jev --scope user

确认安装是否成功：

muse skills list

开一个新会话。当任务匹配时，Muse Code 会自动加载该技能。手动加载请输入：

/building-with-typesafe-jev

其他能读取 SKILL.md 的代理

把 skills/building-with-typesafe-jev/ 整个文件夹复制到你代理的技能目录里，整个文件夹都要保留。

SKILL.md 通过链接引用它旁边的那些文件。

设置 API 密钥（可选，但推荐）

没有密钥技能也能工作。当代理的 shell 中设置了 TYPESAFE_API_KEY 时，代理可以在代码进入你的项目之前，先用真实接口核对它的设计。这样能提前发现错误的字段名，以及那些 Jev 的理解跟你本意不同的问题。每次调用只花费不到一美分。

创建、存储和排查密钥

创建密钥（TypeSafe 控制台四步搞定）

第一步。打开 console.typesafe.ai，在侧边栏里选 API Keys（API 密钥）。

第二步。点击右上角的 Create key（创建密钥）。

第三步。用密钥的存放位置来命名它，比如机器名或代理名。然后点击 Create key（创建密钥）。

第四步。现在就复制这个密钥。控制台只会显示一次。如果丢了，就再创建一个新的，然后把旧的撤销。

存储密钥（macOS、Linux、Windows）

把密钥放在一个只属于你自己的独立文件中，并把它导出为 TYPESAFE_API_KEY。代理通常会在没有终端的 shell 里启动，所以每一节都把密钥放在那些 shell 能看到的地方。请根据你的系统选择对应的做法。

macOS（zsh，默认 shell）

把密钥保存到一个只有你能读的文件里：

mkdir -p ~/.config/typesafe && umask 077 && printf 'export TYPESAFE_API_KEY=%s\n' 'YOUR_KEY' > ~/.config/typesafe/env

从 ~/.zshenv 加载它。每个 zsh 都会读这个文件，包括代理在没有终端时启动的那些 shell。

~/.zshrc 只有交互式 shell 才会读。

echo '[ -f ~/.config/typesafe/env ] && . ~/.config/typesafe/env' >> ~/.zshenv

打开一个新终端检查一下。下面的命令只会打印密钥的长度，不会打印密钥本身：

echo ${#TYPESAFE_API_KEY}

Linux + bash（Ubuntu、Debian、Mint、Fedora、Arch）

把密钥保存到一个只有你能读的文件里：

mkdir -p ~/.config/typesafe && umask 077 && printf 'export TYPESAFE_API_KEY=%s\n' 'YOUR_KEY' > ~/.config/typesafe/env

从 ~/.bashrc 的顶部加载它。Ubuntu、Debian、Mint 和 Arch 在 ~/.bashrc 开头放了一行守卫逻辑，当没有附加终端时就提前退出。在那行守卫下面的任何代码在代理 shell 里都跑不到。而写在文件最顶部则在所有发行版上都是安全的：

sed -i '1i [ -f ~/.config/typesafe/env ] && . ~/.config/typesafe/env' ~/.bashrc

打开一个新终端检查一下：

echo ${#TYPESAFE_API_KEY}

Linux + zsh

和 Linux 一样改 ~/.zshenv 即可。

Linux + fish

fish 会读 ~/.config/fish/conf.d/ 下的每一个文件，不管有没有终端：

mkdir -p ~/.config/fish/conf.d; and echo 'set -gx TYPESAFE_API_KEY YOUR_KEY' > ~/.config/fish/conf.d/typesafe.fish; and chmod 600 ~/.config/fish/conf.d/typesafe.fish

string length -- $TYPESAFE_API_KEY

Windows（PowerShell）

把密钥存为用户环境变量。新打开的终端和应用都会看到它。已经打开的终端则看不到：

[Environment]::SetEnvironmentVariable('TYPESAFE_API_KEY','YOUR_KEY','User')

打开一个新终端检查一下：

$env:TYPESAFE_API_KEY.Length

WSL

Windows 的环境变量默认进不到 WSL。在 WSL 内部，按"Linux + bash"的步骤操作即可。

桌面应用和 IDE 扩展

从 Dock、开始菜单或桌面启动器启动的应用，不会读取你的 shell 配置文件。

- Windows：上面设置的用户环境变量已经覆盖了这些应用。
- Linux（systemd）：在 ~/.config/environment.d/typesafe.conf 中加一行 TYPESAFE_API_KEY=YOUR_KEY，然后注销重新登录。
- macOS：从终端启动应用，或在应用自身的设置里设置这个变量。macOS 没有一个简单的、用户级的、能被所有桌面应用读取的配置文件。

如果代理看不到密钥

让代理运行 echo ${#TYPESAFE_API_KEY}（Windows 上是 $env:TYPESAFE_API_KEY.Length）。如果它打印了 0 或什么都没有，请按顺序检查以下情况：

- 你是在存储密钥之前就已经启动了代理。

代理的 shell 会复制启动它的那个程序的环境变量。退出代理，然后从一个新终端重新启动它。

- 你是从 Dock、开始菜单或 IDE 启动的代理。

这些应用不会读取你的 shell 配置文件。请参见上面的"桌面应用和 IDE 扩展"。

- Codex 对环境做了过滤。

如果 ~/.codex/config.toml 在 [shell_environment_policy] 下设置了 include_only，请把 TYPESAFE_API_KEY 加进去。如果它设置了 ignore_default_excludes = false，Codex 会丢掉所有名字里带 KEY 的变量。删掉那行。

- WSL。

Windows 的环境变量不会进入 WSL。按 Linux 的步骤把密钥存到 WSL 里面。

评测方法

我们给一个编码代理布置了六个 Jev 任务，比如一个客服工单分流函数，以及一个针对 shell 命令的审批关卡。每个任务分别跑了 10 次：用本技能、不用技能、用官方技能，每个分支都跑在各自隔离的容器里。代理只拿到了文档但没有 API 密钥，所以评分环节只检查它写的代码。需要主观判断的检查项交给来自三个不同服务商的三个大语言模型评委（Claude Opus、GPT-6 Sol、Kimi K3），由多数票决定。

| | 不用技能 | 本技能 | 官方技能 |
|----------------|---------------|---------------|---------------|
| 平均得分 | 0.65 ± 0.05 | 0.96 ± 0.02 | 0.77 ± 0.04 |分数是每个任务 10 次运行中通过的检查项占比。

技能带来差异的地方（10 次运行中通过了多少次）

代理写的代码……

| 行为 | 不用技能 | 本技能 | 官方技能 |
|----------------------------------------------|---------|--------|----------|
| 在代码里直接写死数字，而不是向 Jev 要一个带名字的字段值作为问题的输入 | | | |
| 固定或记录了 Jev 的模型版本 | | | |
| 给部门列表留了一个兜底选项 | | | |
| 在遍历 1,200 个类别时保留了多条路径 | | | |
| 为破坏性命令保留了一段纯代码兜底 | | | |
| 把 score 解读成从 0 到 n-1 的位置 | | | |查看每一项检查 →这些行里每一项都比"不用技能"或"官方技能"（或两者都）领先超过 95% 置信水平的偶然因素。

里面有什么

技能是分层加载的，所以代理只读任务需要的那一部分。

| 文件 | 内容 | 代理什么时候读它 |
|-------------------|-------------------------------------------------------------------------------|-----------------------------------|
| SKILL.md | 该选哪种原语、11 条设计规则、如何使用概率和置信度、常见错误 | 每一个 Jev 任务 |
| api-reference.md | HTTP 接口、Python 和 JavaScript SDK、限制、错误、环境变量 | 当它要写代码时 |
| patterns.md | 4 种官方模式以及来自 18 本 cookbook 的技巧，含它们各自的阈值 | 当它在设计一个工作流时 |
| prior-art/INDEX.md| 从"我想做的东西"映射到一种形态的索引，以及失败过的点子 | 在它设计新东西之前 |
| prior-art/*.md | 11 个形态文件：每个含一段代码草图、字段层面的经验教训，以及相关项目链接 | 每个设计读一两个 |

前人方案库（prior-art library）

大多数目录按行业来给项目分类。这个库按"实现形态"来分类。一个游戏机器人、一架无人机和一个交易机器人共享同一种形态：控制循环（control loop）。这样分类之后，三者共用同一段代码草图和同一套字段经验。

11 种形态：

- 控制循环（Control loops）：游戏、无人机、机器人、市场。
- 从候选项中挑选（Select from candidates）：浏览器和手机上的代理、不用大语言模型的工具调用、信息抽取、路由器。
- 关卡（Gates）：工具调用的审批、"完成"检查、CI、付费关、内容关。
- 流式过滤器（Stream filters）：低质内容过滤器、审核、邮件、日志、批量打标签。
- 排序与匹配（Ranking and matching）：重排器、实体匹配、图谱和分类体系的遍历。
- 评判与评测（Judges and evals）：评分量表评判器、轨迹打分、代码评审作为分流。
- 增量与实时（Incremental and real-time）：配音、语音、按键驱动的界面。
- 代理的上下文与记忆（Agent context and memory）：压缩、记忆关卡、记忆过期、算力控制。
- 与大语言模型搭配（Pairing with an LLM）：规划者与执行者、先校验再升级、知识蒸馏。
- 把回答当作数据（Answers as data）：给经典模型的特征、研究工具、基准。
- 嵌入到基础设施中（Embedding in infrastructure）：SQL 函数、向量数据库、CI 钩子、Home Assistant。

索引里还列出了一些在实践中失败了的点子：国际象棋、作为唯一评审的代码评审、感知（perception）、以及未经核验就照单全收的校准（calibration taken on trust）。一次失败的尝试能为下一位构建者省下重复踩坑的工夫。

这套技能与官方技能的不同

官方 TypeSafe 的技能只有一个文件的设计指引。要查 API 细节时，它会每次都把代理打发去实时文档。两个技能名字不同，互不冲突，所以你可以两个都装，不过评测里没有同时跑过两者。

本技能把更多东西直接装进技能本身：精确的 API 形态、cookbook 阈值、社区中失败过的模式，以及前人方案库。代理不需要走网络请求就能做设计，还能先看看别人都做了什么。

Jev 变化很快。这份技能是 docs.typesafe.ai 和社区在 2026-09-25 的快照，并且它会告诉代理：当发生冲突时以实时文档为准。如果发现某个事实有误，请通过 issue 附上来源链接告知我们。

致谢

关于 API 的事实来自 TypeSafe AI 的公开文档和 cookbook。前人方案部分来自公开发布自己项目的构建者们、Hacker News 社区，以及下面这些索引：