与 Claude Code 配合开发：TypeSafe Agent Skill
前三课把官方四种架构模式拆完了：并行提问与投机扇出、智能路由、组合打分。阶段导读里说过，第 4 课解决最后一个问题：这些代码谁来写。
官方的答案：你的 coding agent 来写——前提是给它装上 TypeSafe Agent Skill，一个把 TypeSafe 题型、架构模式、请求写法打包进 agent 工作流的官方 skill。这一课同时拆掉一个流行误解：Jev 不是拿来替换 Claude Code 背后模型的。全程 10 分钟。
学完你能做什么
- 用两条命令在 Claude Code 里装好 TypeSafe Agent Skill，其他 agent（Codex 等）一条
npx命令，并说出更新与自动更新的做法 - 用 3 个官方示例 prompt 驱动 agent：探索项目找接入点、用你的 API key 跑便宜实验、对照官方 cookbook 提重构方案
- 说清 Jev 与 coding agent 的分工：agent 写代码，Jev 在代码里做判断——不存在把 agent 背后的模型换成 Jev 的配置
- 按「问题与阈值收进一个文件」组织 Jev 集成，让 agent 的产出可审、可协作修改
- 用官方 5 个常见问题的排查路径定位故障：skill 不加载、编造字段、路由不符预期……
你现在的困境
- 我让 Claude Code 给项目接 Jev，它没读过文档，张手就写：字段名是编的（比如给 Noul 答案读
.confidence——Noul 根本没有这个字段），一跑就报错。我贴半页文档给它，改完这处又编那处 - 我看好 Jev「快而便宜、答案带概率」，想在项目里找接入点，但官方文档一百多页，不知道让 agent 从哪读起；自己挑着翻译进 prompt，又总漏关键规则
- agent 写的 questions 不敢上线：选项描述含糊、一题塞三个判断、阈值随手写死。代码能跑，答案不稳；review 的时候问题定义散在五个文件里，翻不动
什么时候用这一招
当你需要：
- 让 Claude Code、Codex 等 agent 直接写出正确的 Jev 调用代码——不用每次把文档贴进上下文
- 在现有项目里系统排查：哪些复杂解析、关键词表、脆弱启发式可以换成一道类型化问题
- 让 agent 用真实 API 实验验证问题措辞，而不是拍脑袋断言「应该能跑」
而且不想：
- 手动喂文档：费上下文，还喂不全
- 反复纠正 agent 编造的字段和过期用法
- 收到一坨问题定义散落各处、没人审得动的集成代码
这正是 SKILL.md 里写的适用场景：构建、审查、调试调用 TypeSafe 的代码时；把「LLM prompt 再解析」、关键词匹配或脆弱启发式换成类型化问题时；或者 brainstorm「可编程常识」能塞进应用哪里时。
🎒 开始前的准备
- 读过高效工作流阶段导读：知道本课是阶段第 4 课，解决「谁来写代码」
- 装有 Claude Code，或你在用的其他 coding agent（Codex、Cursor、opencode 等）——本课不教 agent 本身的安装
- 想跑第 4 步实验：第一个请求那课的
TYPESAFE_API_KEY还能用；没有就去 console.typesafe.ai/keys 建一个 - 手边最好有一个真实项目——第 3 步的示例 prompt 就是让 agent 分析你的代码
核心思路
先摆正 Jev 的位置。 官方在 coding-agents 文档里开宗明义：Jev 不是 Claude Code、Cursor、opencode、Copilot、Muse Spark、Grok Bot 或类似工具背后 LLM 的直接替代品；你照常用 coding agent，让它写「调用 Jev 做决策」的代码。
Jev 是 System One 决策模型：不生成文本、不写代码、不对话，只回答类型化问题。官方原话：不存在 model: "jev-latest" 这种配置，能把你的 coding agent 变成 Jev 驱动的 agent——两套系统解决的问题不同。
那 TypeSafe Agent Skill 装的是什么？ 不是换模型，是给 agent 装上下文。官方对 skill 的定义：给 coding agent 关于 TypeSafe API 的完整上下文——题型、架构模式、组织请求的最佳实践。外加一份「live docs 指南」：SKILL.md 明确要求 agent 把 docs.typesafe.ai 当请求语法、SDK、限额的事实来源，而不是凭训练记忆。
| 对比维度 | 没装 skill 的 agent | 装了 skill 的 agent |
|---|---|---|
| API 字段 | 凭记忆写，字段名可能是编的 | 按官方题型写；不确定就查 live docs |
| 问题设计 | 一个 prompt 塞所有判断，输出 JSON 再解析 | 一题一判断，答案类型化，代码直接分支 |
| 架构 | 想到哪写到哪 | 按官方模式组织：并行提问、门控、组合打分 |
| 验证方式 | 断言「应该能跑」 | 实测 API，保留每个案例的 payload |
skill 教给 agent 的核心哲学：判断给 Jev，决策留代码。 SKILL.md 把每个决策看成一张真值表：Jev 供应输入（「客户听起来沮丧吗？」「这条消息在说哪个产品？」），代码持有把输入映射到动作的逻辑。反过来，让 Jev 直接做决定的问题（「这张工单该升级吗？」「agent 下一步该干什么？」）说明问题问错了层——把决策拆成它依赖的判断，决策本身写进代码，可见、可测。前三课的代码全是这个形态：Jev 给 intent 和 complexity，if/elif 决定路由。
如果你是带着别的期待来的，官方还给了一张对照表：
| 你本来想… | 正确做法 |
|---|---|
| 让 coding agent 更擅长写调用 TypeSafe 的代码 | 装 TypeSafe agent skill（本课） |
| 在你构建的应用里用 Jev 做路由、分类、打分、护栏 | 从第一个请求起步，模式看本阶段前三课 |
| 换掉 coding agent 背后的模型 | Jev 不干这个。继续用 LLM coding agent，在产品需要快速、校准、结构化决策的地方单独用 Jev |
| 不写代码先试试 Jev | 开 Playground（console.typesafe.ai/playground），贴 state 加问题 |
跟我做
第 1 步：安装 TypeSafe Agent Skill
为什么：agent 没读过 TypeSafe 文档时，只能凭训练记忆写调用，字段名容易编错。skill 把官方集成经验一次性装进 agent 的工作流，后面所有步骤都建立在这上面。
方式 A（推荐）：Claude Code 插件
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai你应该看到：两条命令正常结束、没有报错。官方文档没有给出具体的输出文案，装没装成，以下一步的验证为准。
方式 B：其他 agent（Codex 等，走 skills.sh）
npx skills add typesafe-ai/skills --skill typesafe-ai按提示选择你正在用的 agent。默认装到当前项目；想全局可用加 -g。
方式 C：让 agent 自己装
把这段官方 prompt 原样贴给 agent，它自己判断环境并执行：
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.⚠️ 只选一种方式
官方明确提醒：多种方式混用会产生重复副本（duplicate copies）。手动安装的话，把 skills/typesafe-ai 整个目录（含参考文件）复制进 agent 的 skills 目录。
- 我只用了一种安装方式
第 2 步：点名调用，确认 skill 已加载
为什么：装好 ≠ agent 会主动用。官方的使用方式是「在 prompt 里点名」——说 "use the TypeSafe skill" 在任何 agent 里都管用；Claude Code 插件还可以直接调命令。
在 Claude Code 里输入：
/typesafe:typesafe-ai或在给其他 agent 的消息里写：
Use the TypeSafe skill when working on this project.你应该看到：agent 的回应里出现 TypeSafe 语境——提起 state、questions、Choice/Score/Noul 这些题型，或主动去读 docs.typesafe.ai 的 live 文档。SKILL.md 把 live docs 定为请求语法与限额的事实来源，装好 skill 的 agent 会先查再写，而不是上来就编。
没加载？官方排查两步：确认安装命令装的就是你正在用的这个 agent（方式 B 安装时会提示选择）→ 重启 agent 再试。
- agent 的回复里有题型 / state / questions 语境，而不是自由发挥
第 3 步：用官方示例 prompt 让 agent 找出项目里的接入点
为什么：最好的入门不是你告诉 agent 在哪接 Jev，而是让带着 skill 的 agent 自己找。官方把这条列为「a good prompt to start with」。
在你的项目目录里，把这段发给 agent（官方原文）：
Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.你应该看到：agent 扫描代码，指出脆弱的解析、关键词表、启发式规则的位置，并提议哪些可以换成「类型化问题 + 代码决策」。
判断提议质量的标准就是核心思路那张真值表：好的提议长成「这里加一道 Choice / Noul，代码按答案分支」；如果 agent 提「让 Jev 决定是否升级工单」，那是把决策塞给了模型——SKILL.md 明说这种问题问错了层，让它拆成判断再改。
- agent 的提议是「加判断、代码分支」的形态，而不是「让 Jev 做决定」
第 4 步：让 agent 跑便宜实验、对照 cookbook 提重构方案
为什么：找到位置只是计划。skill 工作流的第 3 步是「probe the live API」——用真实请求验证问题措辞，直到应用表现符合预期。官方给了两个现成 prompt。
先导出 key（没有就去 console.typesafe.ai/keys 创建）：
export TYPESAFE_API_KEY="<你的API Key>"实验 prompt（官方原文）：
Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.你应该看到：agent 先向你要许可——SKILL.md 要求它先征得同意、说明会发送什么数据（尤其个人或隐私数据）、声明会用到你的 key，然后才发测试请求。测试会用代表性案例 + 难例 + 答案为「否」的负例，每个案例保留完整请求 payload，最后基于最有希望的结果提议改动。
再让 agent 对照官方 cookbook 找重构机会（官方原文）：
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://docs.typesafe.ai/cookbooks) that show how I could
refactor my code to be less fragile or complex.你应该看到：agent 指出与你代码相似的官方 cookbook——比如脆弱的邮箱/电话提取对应 pre-parsed value extraction、复杂分发逻辑对应 intent routing——并给出按 cookbook 模式重构的方案。这些 cookbook 的完整落地就是下一阶段的场景实战。
💡 实验预算与安全
SKILL.md 原话：TypeSafe 非常便宜，一点预算就能跑很远（a little can go a very long way）。给 agent 一个实验预算上限，并确认它的运行环境能访问 API 端点。写进生产代码时，skill 的集成守则要求 key 留在服务端。
- agent 发请求前先征得了我的许可，并说明了会发什么数据
第 5 步：把问题与阈值收进一个文件，交给人审
为什么：agent 写代码快，但官方提醒「Agents aren't great at writing questions」——问题措辞、选项描述、阈值是集成里最需要人把关的部分，也是审阅时最常改的部分。集中到一个文件，你和 agent 的协作编辑才有落点。
比如把智能路由课的路由问题收进 questions.py（结构沿用官方模式页的写法）：
# questions.py —— 所有问题与阈值集中在这里；改措辞、调阈值只动这个文件
from typesafe_sdk import Choice, Score
ROUTING_QUESTIONS = {
"intent": Choice(...), # 完整定义见「智能路由」课第 1 步
"complexity": Score(...),
}
# 阈值也收在这里：兜底线与各动作的风险阈值分开
CONFIDENCE_FLOOR = 0.5 # 分类兜底：低于它先转人工
TRANSFER_THRESHOLD = 0.85 # 高危动作：过了它才免确认自动执行官方的四条协作原则（agent-skill.md「Good vibe coding principles」）：
- 先和 agent 把方案聊透——用上面的示例 prompt 当起点
- 动手实现之前，人先把计划过一遍，确认它说得通
- 常量（问题与阈值）收在一个地方方便审阅；agent 不擅长写问题，预期是协作编辑
- 别把 agent 的断言当事实——鼓励它验证自己的假设
你应该看到：项目里有一个单独文件装着全部问题定义与阈值常量。agent 后续改业务逻辑不碰它；调问题措辞时，你只审这一个文件的 diff。
- 问题与阈值在一个文件里；agent 提的方案我先审再让它动手
检查点 ✅
- 我能说出 Jev 在 coding agent 里的位置：不是背后的模型，是 agent 写的代码里的决策引擎
- Claude Code 里
/typesafe:typesafe-ai能调出 skill；其他 agent 里点名 "use the TypeSafe skill" 生效 - 三个官方示例 prompt 我跑过至少一个：找接入点 / 跑实验 / 对照 cookbook
- 问题与阈值收在一个文件里，改措辞只动它
- agent 编造字段时，我知道第一反应是更新 skill 再重试
踩坑提醒
❌ 装了 skill，agent 还是不用
现象：插件装完，agent 写 Jev 代码时依然自由发挥。官方排查路径：Claude Code 里直接调 /typesafe:typesafe-ai；其他 agent 在 prompt 里点名 "use the TypeSafe skill"。还不行，确认安装时选的目标 agent 没选错，然后重启 agent。
❌ agent 编造请求/响应字段
现象：代码里出现文档里没有的字段——比如给 Noul 答案读 .confidence，而 Noul 只有 0–1 的 noul 值。官方诊断：skill 过期（stale skill）。用你的安装方式更新后重试：
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；手动复制的，整个目录换成 GitHub 最新版。
❌ 结果不符预期，先怀疑模型
现象：分类或路由开始误判。官方排查顺序是先查问题和阈值：阈值太高造成假阴性（该自动的没自动），太低造成假阳性（没把握的被放行）；然后再把问题写得更具体。智能路由课的踩坑提醒有展开。
❌ 到处设 confidence 阈值
官方提醒：只关心选出最优选项时，直接取 confidence 最高的答案即可；有特定统计算法需求，应该用 probabilities。这条在智能路由课已展开，不重复。
❌ agent 写的 TypeSafe 代码审不动
现象：review 时问题定义散落五个文件，找齐一套阈值要翻半天。官方建议：人最该审的是问题措辞和阈值常量，把它们收在一个代码文件里，不用到处翻——就是第 5 步做的事。
进阶技巧（可选）
读一遍 SKILL.md 本身。 skill 就是一个 288 行的 Markdown 文件（MIT 协议，github.com/typesafe-ai/skills），四块核心内容：判断与决策分层（真值表）、state 设计的「人类测试」（只看这个 state，一个聪明人能凭直觉快速回答吗）、问题措辞规则（一题一判断；选项名要描述内容，因为问题 ID 不发给模型）、答案解读（confidence 很少当闸门、Noul 0.7/0.3 起点阈值、看 Score 分布）。大部分规则前几课讲过（Noul、Confidence），剩下值得整篇读的是「黄旗清单」。
用 skill 的五步排查顺序对付「答案看起来不对」。 SKILL.md 给的检查顺序：① 实际发送的 payload → ② state 过不过人类测试 → ③ 选项里到底有没有正确答案 → ④ 问题能不能再拆小 → ⑤ 措辞。全查过仍错，去查模型的已知弱点：Jev 1.13 踩坑手册。
认识「黄旗」（prompt gymnastics）。 官方列的黄旗：为特定测试项写死的 criteria、每挂一个案例就加一条从句、为模型怪癖找说辞的 caveat、拟合特定案例的阈值、断言精确概率的测试、悄悄覆盖答案的代码。这些「为凑出特定值写的措辞」倾向在新输入和下一个模型版本上崩；结构性修复优先——更好的 state、拆出独立问题、或改代码。
本课小结
✅ TypeSafe Agent Skill 两条命令装进 Claude Code（claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai）；其他 agent 一条 npx skills add；只选一种方式，避免重复副本。
✅ Jev 与 coding agent 的分工：agent 写代码，Jev 在代码里做判断；不存在 model: "jev-latest" 配置把 agent 变成 Jev 驱动。
✅ 三个官方示例 prompt：探索项目找接入点、用 TYPESAFE_API_KEY 跑便宜实验、对照 cookbook 提重构。
✅ 协作原则：计划先审再实现；问题与阈值收一个文件；agent 不擅长写问题，预期协作编辑；别把断言当事实。
✅ 五个常见问题的排查：不加载 → 点名 / 查目标 / 重启；编造字段 → 更新 skill；不符预期 → 先查阈值与问题；只选最优 → 不设阈值；难审 → 常量集中。
关键命令速查：
| 事项 | 命令 / 做法 | 出处 |
|---|---|---|
| Claude Code 安装 | claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai | docs/agent-skill.md |
| 其他 agent 安装 | npx skills add typesafe-ai/skills --skill typesafe-ai（项目级默认，-g 全局） | 同上 |
| Claude Code 调用 | /typesafe:typesafe-ai（任何 agent 通用：点名 "use the TypeSafe skill"） | 同上 |
| 插件更新 | claude plugin marketplace update typesafe-ai → claude plugin update typesafe@typesafe-ai，重启或 /reload-plugins | 同上 |
| skills.sh 更新 | npx skills update | 同上 |
| 自动更新 | /plugin → Marketplaces → typesafe-ai → Enable auto-update | 同上 |
| skill 仓库 | github.com/typesafe-ai/skills（MIT；2026-11-03 核对：SKILL.md 288 行，与线上逐字一致） | 实时抓取核对 |
下一课预告
四种模式练完，agent 也能替你写代码了。下一站把整套东西带进真实项目——场景实战：选择你的路线，官方 cookbook 落地成的 15 个完整案例。
你会学到：