Jev 1.13 踩坑手册：9 种失败模式与替代做法
官方文档里有一页很特别：jaggedness（毛边）文档——TypeSafe 自己整理的「Jev 1.13 已知毛病清单」。开篇一句 Jev isn't perfect，然后列出 9 种失败模式，每种都附替代做法。这一课把这份文档整个搬过来：全表速查、逐条拆解、官方可复制代码，全程约 15 分钟。
这一课完全独立，不碰浏览器也能读——纯 API 用户直接从 进阶手册 跳到这课也不亏。文档标注适用 jev-1.13（最后审阅 2026-10-02），官方也说其中很多会在后续版本修复；但「算术放代码、日期提部件、大 state 先过滤」这套提问习惯，用什么版本都值得养成。
学完你能做什么
- 背出官方 9 种失败模式的名字，每种说得出一句替代做法（对照本课小结的速查表自查）
- 把「让 Jev 数数」的问题改成官方范本：代码迭代候选、每项一个 Noul，计数在代码里加出来
- 把日期比较改成「模型提部件 + 代码组装」：12 个月、31 天、有界年份的 Choice 枚举，带「没写」逃生口
- 给大 state 瘦身：只发该题需要的字段；过滤不了就用 Noul 做相关性闸门
- 上线前跑完三查：选项重排一致性、边界用例、instructions 与 criteria 对齐
你现在的困境
- 答案「十条里九条对」：同一类输入，偶尔一条走进怪分支，找不到规律，也不敢上线
- 明明是道判断题，模型却像在数数、做算术——数字怎么都不对，改措辞也没用
- 想让 Jev 吐一段总结，链式 Choice 拼了半天，又慢又烂，还不知道是方法错了还是模型不行
什么时候用这一招
当你需要：
- 写问题时提前绕开 Jev 1.13 的已知坑，而不是上线后逐个案倒查
- 把一个「答案不对」的问题改写成稳健的问题——计数、日期、大 state、措辞四类高频病因
- 判断一个任务该归谁：Jev 的判断、代码的算术，还是生成模型的文本
而且不想：
- 把 9 种坑挨个踩一遍才学会——官方已经替你踩过，还写了文档
- 上线后被对抗输入教育：criteria 不明确、边界没测过，用户一喂脏数据就翻车
🎒 开始前的准备
- 完成了 Confidence 置信度：知道 confidence 是「答案自身概率分布的形状摘要」——本课的踩坑提醒会用到这个前提
- 用过三种基础题型：Choice 选择题、Score 打分题、Noul 是非题
- （可选）手里有正在开发的 Jev 应用——本课的步骤是「拿着你自己的问题改」，有真实问题收获最大
- （可选）想跑官方计数范本：Python ≥ 3.10 环境装好 typesafe-sdk（安装教程）
核心思路
先看官方的自我评价（jaggedness 文档开篇）：jev-1.13 快、校准、擅长常识判断，在 System One 任务上表现最好。它同时有三类先天弱项：
| 弱项 | 意思 | 对应失败模式 |
|---|---|---|
| 多层间接 | 需要额外间接层级的任务会吃力 | #4 间接引用 |
| 字面理解 | 理解可以相当字面 | #1 字面理解 |
| 数值精度 | 需要数值精度的任务会挣扎 | #2 数学与数字、#3 日期时间比较 |
9 种失败模式基本都是同一件事：把 System Two（慢思考）的活儿塞给了 System One（快判断）。所以全部替代做法可以压成一句口诀：
判断留给 Jev，算术留给代码，生成留给生成模型。
官方在文档结尾还给了四条 avoid 清单，逐条对应：
- ❌ 问模型代码能精确计算的东西
- ❌ 一个问题里藏好几个判断
- ❌ System Two 任务：更多层间接
- ❌ state 里塞超过问题需要的上下文——官方原话：Jev suffers from context rot（上下文腐烂），无关材料直接花你的准确度
💡 这份文档本身的态度
官方没藏着掖着：开篇就是 Jev isn't perfect，结尾还留了 Discord 入口征集新失败模式。把已知毛病写成文档、每种附替代做法——这也是你对待自己 Jev 应用该有的态度：记录坑，附上绕法。
跟我做
第 1 步：用官方 9 种失败模式表做一次 Jev 踩坑体检
为什么：改问题之前先知道病名。官方把已知坑整理成 9 种失败模式，每种附一句替代做法——先拿这张表过一遍你现有的问题，比出错后再回头排查省不少来回。
官方全表（症状与替代做法均出自 jaggedness 文档）：
| # | 失败模式 | 典型症状 | 官方替代做法 |
|---|---|---|---|
| 1 | 字面理解（Literal reading） | 限定词、否定、隐含条件一律按字面读；答的是你写的问题，不是你想的问题 | 精确条件写进 instructions，边界情况放进 criteria；躲不开就拆两个字面问题，代码组合 |
| 2 | 数学与数字（Math and Numbers） | 计数不可靠，误差随规模增大；hex / RGB 不如英文名好使 | 算术全放代码；计数 = 代码迭代候选 + 每项一问 |
| 3 | 日期时间比较（Date and time comparison） | 日期当文本读；先后、间隔、窗口判断不可靠 | 提取部件，代码比较 |
| 4 | 间接引用（Indirection） | 双重否定、属性套属性；跳数越多越不准 | 减少跳数，按名字直接指向相关 state |
| 5 | 大 state 满是无关细节 | 无关细节是干扰项；出错难定位是哪段输入的锅 | 先过滤，只发该题需要的 |
| 6 | 对抗内容（Adversarial content） | 注入指令、误导框架、自我辩护的文本能移动答案 | 写精确问题，上线前测边界 |
| 7 | 矛盾指令与 criteria | instructions 和 criteria 要的东西不一样，模型会困惑 | 把 criteria 当 instructions 的延伸，对齐两者 |
| 8 | Choice 选项顺序 | 顺序影响答案，偏向排在前面的选项 | 重排选项，复查答案一致 |
| 9 | 需要 generation | 链式 Choice 强迫生成：效果差且很慢 | 换生成模型；有界提取转 Choice |
你应该看到：你的每个草稿问题都能归入三类——直接能用的；撞上某一行、需要改写的；压根不该问模型的（代码能精确算）。后面几步只处理第二类。
- 我的问题在表里找到了对应行（或确认不需要改）
第 2 步：把算术搬回代码——计数、数值表示、Score 插值三连坑
为什么：官方原话 Jev is not a calculator——任何数学逻辑都强烈建议放代码；Jev 在语义问题上的表现好过数学问题。失败模式 #2 有三个子坑，逐个看。
坑 A：计数。 jev-1.13 数不可靠——单词里的字符数、段落里术语出现次数、长列表的条目数都算。官方的描述很传神：模型认的是「答案的形状」，不是逐个 tally，而且误差随被数对象的规模增大。动手前先问自己：这个计数为什么需要模型？单位是正则或解析器能找到的，计数就归代码，模型帮不上忙。
官方范本（出自 jaggedness 文档，逐字可复制）——要数列表里有几个水果，改成「每个 item 一个 Noul + 代码求和」：
from typesafe_sdk import Noul, TypeSafeClient
client = TypeSafeClient(model="jev-1.13")
YES = 0.5 # up to you on what you want the threshold to be, depends on your usecase.
items = ["typesafe", "apple", "california", "banana", "likes", "calibration", "orange", "vertex"]
result = client.system_one(
{"items": items},
{
f"item_{i}": Noul(instructions=f"Is `items[{i}]` the name of a fruit?")
for i in range(len(items))
},
)
count = sum(result.nouls[f"item_{i}"].noul > YES for i in range(len(items)))模型只做了 8 次「是不是水果」的判断，一次都没数数；count 是代码把 8 个答案加出来的。按列表内容，apple、banana、orange 三项应判为水果，你应该看到 count = 3。
坑 B：数值表示。 语义表示优于数值表示：颜色问题用 hex 值不如用英文颜色名；给 RGB 三元组或 hex 值判断两个值是否相近——不可靠。同理，高级编程语言的问题表现好过汇编或二进制编码指令。替代：代码做转换，传计算好的数字或命名桶（named bucket），把模型留给真正需要判断的部分——比如「这个颜色读起来像不像警告」。
坑 C：Score 插值。 不要用 Score 输出（期望、概率）计算两个等级之间的精确数值。期望可以用来检查「是否过某个阈值」，但 jev-1.13 的 score levels 数值校准弱——靠在最近两级之间插值重建精确数字，它帮不上忙。
- 代码里搜一遍「让模型输出数量 / 差值 / 精确数值」的问题，全部改成代码计算或 Choice 枚举
第 3 步：日期不比较——模型提部件，代码组装
为什么：jev-1.13 把日期当文本读，不是有序数量。「两个日期谁先谁后、相差多远、是否落在窗口内」都不可靠；混合格式、相对引用（下周四）、领域边界（季度、结算窗口、应计期间）更糟。
官方的分工原则一句话：提取是判断，交给模型；算术不是，留在代码。
日期的每个部件都是小的封闭集合：12 个月、31 天、有界的年份范围。这把提取变成对枚举选项的 Choice，而不是自由解析；还能放一个显式的「没写」（not stated）选项——缺失的部件被报告，而不是被猜。代码把部件组装成真正的日期，之后的一切——排序、时长、偏移、星期——全归代码。
官方 date extraction cookbook 的 7 个 Choice 问题（一次请求全部发出）：
| 问题 | 判断什么 | 逃生口 |
|---|---|---|
| mode | absolute（写了月份的日历日期）/ relative（相对今天）/ none（没写这个日期） | none |
| month | 绝对日期的月份（12 个选项） | none：文本没写 |
| day | 几号（1–31 逐个选项） | none |
| year | 哪一年（1900–2050 逐年一个选项） | none：没写年份，代码补；out_of_range：写了但不在列表，代码标记、不猜 |
| day_anchor | today / tomorrow / day_after / weekday（命名星期几） | none |
| weekday | 周几（7 个选项） | none |
| week_offset | next（下一日历周）/ current（本周）/ none（光秃秃的星期几） | — |
组装后的置信度取「实际用到的部件里最低的那个」，低于 0.60（cookbook 的 REVIEW_BELOW）转人工。完整可运行版本（含相对日期与置信度门控）在 值提取：日期、邮箱、电话、金额。
你应该看到：一次请求返回 7 个部件答案；代码组装出 date 对象；「next Thursday」由代码约定解析（光秃秃的星期几 = 今天起下一个，next = 下一日历周，current = 本周）——模型从头到尾没比较过任何日期。
- 代码里没有「哪个日期更早 / 相差几天 / 是否在窗口内」这类问题，全部改成了部件提取 + 代码比较
第 4 步：字面理解拆两问，间接引用减跳数
为什么：失败模式 #1 和 #4 都病在问题措辞上。字面理解：jev-1.13 答的是你写的问题，不是你想的问题——限定词、否定、隐含条件一律按字面读；人会读出意图，它不会。间接引用：带双重否定或复杂间接的问题可靠性下降，属性套属性、多跳推理都耗费准确度。
字面理解的替代做法，三条：
- 精确条件写进
instructions，要具体 - 边界情况放进
criteria - 官方金句：当你看着一个错误答案、发现自己在解释「我真正想问的是……」时，那段解释就是 instructions 缺失的另一半
实在躲不开解释的地方，拆成两个字面问题，代码组合。比如「保留相关且友善的评论」一句话里藏了两个判断：
from typesafe_sdk import Noul, TypeSafeClient
client = TypeSafeClient(model="jev-1.13") # 本页示例固定用 jaggedness 文档适用的版本
result = client.system_one(
{"comment": "这个服务真好用，就是贵了点"},
{
"is_on_topic": Noul(instructions="Is `comment` about the product itself?"),
"is_friendly": Noul(instructions="Is `comment` friendly in tone?"),
},
)
# 组合逻辑在代码里：改阈值、改逻辑，都不用动 prompt
keep = result.nouls["is_on_topic"].noul > 0.7 and result.nouls["is_friendly"].noul > 0.7间接引用的替代做法：instructions 写得越直接越好；尽可能按名字指出 state 的相关部分（用反引号点路径引用，比如 ticket.messages[0].text），别让模型自己跳。
你应该看到：改写后每个问题只剩一个字面判断；「而且」「不是不」这类连接词从 instructions 里消失；组合逻辑全在代码里。
- 每个 instructions 只有一个判断；否定词最多出现一次
第 5 步：给大 state 瘦身——代码先过滤，Noul 做相关性闸门
为什么：失败模式 #5。state 里与决策无关的内容越多，准确度越低——无关细节是干扰项，而且大 state 让你难定位「哪段输入导致了错误答案」。官方原话：Jev suffers from context rot，state 里的无关材料直接花你的准确度。
替代做法两层：
- 代码先检索、先过滤，只发该题需要的字段
- state 层过滤不了时，用 Noul 问相关性。官方 RAG cookbook 的做法：每个候选段落 4 个 Noul——是否相关、是否含可用证据、是否与查询前提矛盾、是否含注入指令；
is_relevant低于 0.45（cookbook 的relevant_min）直接排除
⚠️ 顺手算清上下文的账
官方在 jaggedness 文档里提醒：state 对 jev-1.13 的两个上下文限制各计一次——per-request 64k（state + 全部问题）和 per-question 32k（state + 单个问题）。内容超了可以开长上下文请求头（TypeSafe-Danger-Zone-Long-Context: true，两个限制都变 262k），但官方明说更慢且更不准——正确顺序是先过滤，不是先开 header。
完整案例见 RAG 段落把关；state 的三种形态与点路径引用回顾 State 状态。
你应该看到：发出去的 state 只含该题用得上的字段；请求体明显变小；同一问题的答案稳定下来。
- 每个问题的 state 都过了「这个字段这题用得上吗」这一关
第 6 步：上线前三查——选项重排、边界用例、指令对齐
为什么：失败模式 #6、#7、#8 没法靠改一次措辞一劳永逸，官方给的替代做法都是「上线前检查」。面向很多用户之前，把这三查跑完。
一查：Choice 选项重排。 官方观察到选项顺序能影响答案，jev-1.13 偏向排在前面的选项。复查方法：重排选项再问一遍，答案要一致。
from typesafe_sdk import Choice, TypeSafeClient
client = TypeSafeClient(model="jev-1.13")
state = {"ticket": {"subject": "无法登录", "message": "从今天早上开始一直报 401"}}
def urgency(options: dict) -> str:
return client.system_one(
state,
{"urgency": Choice(instructions="How urgent is `ticket`?", criteria=options)},
).answers["urgency"].choice
print(urgency({"low": None, "medium": None, "high": None}))
print(urgency({"high": None, "medium": None, "low": None})) # 重排后再问一遍
# 两次不一致 → 这个问题的答案不可信：选项定义要更互斥、更具体二查：对抗内容。 state 是数据，jev-1.13 默认不把它当敌意内容——注入指令、故意误导的框架、为自己分类辩护的文本，都可能移动答案（官方说这点未来会改进）。替代：criteria 写明确；上线前彻底测试你的集成。这个方向的完整安检案例见 LLM 护栏。
三查：指令与 criteria 对齐。 两者要的东西不一样时模型会困惑。官方举的例子：一个 true 映射「否」、false 映射「是」的 Noul，表现会更差。替代：把 criteria 当 instructions 的延伸，用清晰精确的语言对齐；目标是普通人一眼能读懂。
你应该看到：重排后答案一致；空输入、超长输入、带注入的输入这些边界用例都测过；instructions 和 criteria 说的是同一件事。
- 三查都跑过，不一致的选项定义已经改写
检查点 ✅
- 能背出 9 种失败模式的名字，每种说得出一句替代做法（对照本课小结的速查表）
- 计数、日期比较、精确数值全部改成了代码计算——模型只做判断
- 每个 instructions 只有一个字面判断，组合逻辑在代码里
- state 只发该题需要的字段，64k / 32k 两道限制的账算过了
- 上线前三查跑过：选项重排一致性、边界用例、指令对齐
踩坑提醒
❌ 让 Jev 生成文本
现象：想让 Jev 写总结、写回复、输出一段自由文本，用链式 Choice 一个字一个字拼。
原因：失败模式 #9。jev-1.13 没受过生成文本的训练；官方明说链式 Choice 强迫生成「效果不好且非常慢」。
正确做法：答案空间有界时，把提取变成对这些选项的 Choice，而不是问值本身；要自由文本就用生成模型。官方对数据提取的推荐分工：regex 或生成模型先抽出候选选项，jev-1.13 只负责挑出正确的那个——值提取就是这个分工的完整落地。官方原话很直白：If you really need to generate text... there are other models for that.
❌ 拿 confidence 阈值当创可贴
现象：答案偶尔离谱，于是到处加 confidence 阈值，低于阈值一律转人工，以为这样就稳了。
原因：confidence 是「答案自身概率分布的形状摘要」，不是「答案对不对」的证明。撞上字面理解这类坑时，模型会自信地答出字面问题的答案——分布很尖、confidence 很高，但答非所问。问题写得差，阈值救不了。
正确做法：先按本课 9 种模式修问题，再用 confidence 三档用法做分层自动化。另外官方 agent-skill 文档的常见问题里有一条：只关心「选最优」时，直接取最高概率选项即可，不必到处设 confidence 阈值；有统计算法需求就用 probabilities。
❌ 「这些坑 1.14 都修了，不用学」
现象：看到文档标注适用 jev-1.13，而 jev-latest 已指向 jev-1.14.0，觉得整页可以跳过。
原因：官方只说了「很多会在后续版本修复」，没说哪些修了；jaggedness 文档最后审阅是 2026-10-02，早于 1.14 发布（2026-10-14），官方文档站也没有 1.14 版的 jaggedness 清单。另外 jev-1.13.0 还在服务，官方计划弃用前给 60 天预告。
正确做法：把 9 种模式当提问习惯养成——算术放代码、日期提部件、大 state 先过滤，这些与版本无关，对 1.14 同样是好的写法。中文用户再加一条官方提醒：CJK 内容准确度低于英语，上线前用自己的数据测，重点关注 confidence（模型与价格的语言支持一节）。
进阶技巧（可选）
把速查表变成团队清单。 官方 agent-skill 文档建议把问题与阈值常量集中在一个文件里方便人审。9 种失败模式天然是一份 question review 清单：新问题合入前，对照小结的速查表过一遍。配合 TypeSafe Agent Skill 让 Claude Code 帮你改写问题——官方提醒过 agent 不擅长写问题，expect 协作编辑。
反哺你的 Ultrafast 目标。 这套提问习惯同样适用于写浏览器任务的目标：字面、具体、带停止条件——官方示例目标都以 Stop when… 收尾，「把目标写窄」也是官方建议（见 Ultrafast 排错）。
发现新失败模式，报给官方。 jaggedness 文档结尾在征集：发现该上榜的失败模式，去 Discord 反馈。
本课小结
✅ Jev 踩坑的总口诀：判断留给 Jev，算术留给代码，生成留给生成模型；state 只发该题需要的。
✅ 9 种失败模式里，#2 #3 是「该给代码的活」，#1 #4 是「问题措辞」，#5 是「state 组织」，#6 #7 #8 靠「上线前检查」，#9 是「该换生成模型」。
✅ 官方范本记两个：计数 = 代码迭代候选 + 每项一个 Noul；日期 = Choice 枚举部件 + 代码组装，带「没写」逃生口。
✅ confidence 是分布形状摘要，救不了写坏的问题——先修问题，再设阈值。
✅ 这套习惯与版本无关；中文内容额外注意 CJK 准确度，上线前自测。
9 种失败模式速查（症状 → 替代做法）：
| # | 失败模式 | 一句话替代做法 |
|---|---|---|
| 1 | 字面理解 | 精确条件进 instructions，边界进 criteria；拆两问代码组合 |
| 2 | 数学与数字 | 算术全放代码；计数 = 代码迭代 + 每项一问 |
| 3 | 日期时间比较 | 提部件（Choice 枚举），代码比较 |
| 4 | 间接引用 | 减少跳数，按名字指向 state |
| 5 | 大 state 满是无关细节 | 先过滤；过滤不了用 Noul 做相关性闸门 |
| 6 | 对抗内容 | criteria 写明确，上线前测边界 |
| 7 | 矛盾指令与 criteria | criteria 是 instructions 的延伸，对齐两者 |
| 8 | Choice 选项顺序 | 重排选项，复查答案一致 |
| 9 | 需要 generation | 换生成模型；有界提取转 Choice |
下一课预告
进阶手册到此收官。下一课 API 速查：请求、响应与报错 把请求层的知识收进一页。你会学到：
- 请求体规则：32 MiB 上限、UTF-8 JSON 无 BOM、嵌套 ≤ 64 层、数字必须有限
- 状态码表：400 / 401 / 413 / 415 / 422 / 429 / 529 各自的含义与重试策略
- 压缩规则：gzip / zstd 怎么用，什么时候会 415
- SDK 与 curl 直连的请求、响应字段对照
相关教程
附录：源码参考
点击展开查看官方文档出处
更新时间：2026-11-04（官方文档本地信息源 sources/jev/docs/，URL = https://docs.typesafe.ai/<本地路径>）
| 内容 | 文件路径 | 关键位置 |
|---|---|---|
| 9 种失败模式总表与逐节替代做法 | docs/model-jaggedness/jev-1.13.md | 开篇定位（快 / 校准 / 常识判断；三弱项：间接层级、字面理解、数值精度）；失败模式表；结尾 avoid 四条与 Discord 征集入口 |
| 官方计数范本（Noul 逐项判断 + 代码求和） | docs/model-jaggedness/jev-1.13.md | Math and Numbers → Counting：8 个 item、YES = 0.5、result.nouls 求和 |
| 数值表示与 Score 插值 | docs/model-jaggedness/jev-1.13.md | Numeric representations（hex vs 英文名、高级语言 vs 汇编）；Math using score（期望只用于阈值检查） |
| 字面理解 / 间接引用 / 大 state / 对抗 / 矛盾指令 / 选项顺序 / 生成 | docs/model-jaggedness/jev-1.13.md | 各同名小节；Large state 小节的 context limit NOTE |
| 日期提部件完整实现 | docs/cookbooks/date_extraction_cookbook.md | 7 个 Choice（mode / month / day / year / day_anchor / weekday / week_offset）；year 1900–2050 + none / out_of_range；REVIEW_BELOW = 0.60；置信度取所用部件最低值；发布代码固定 TYPESAFE_MODEL = "jev-1.12" |
| Noul 相关性闸门与注入检查 | docs/cookbooks/classifying_rag_passages.md | 4 个 Noul（is_relevant / contains_answer_evidence / contradicts_query_premise / contains_prompt_injection）；relevant_min = 0.45 |
| 上下文限制与长上下文 | docs/models.md | 64k per-request / 32k per-question；TypeSafe-Danger-Zone-Long-Context: true → 262k，更慢且更不准 |
| 版本时间线与语言支持 | docs/models.md；博文 typesafe.ai/blog/jev-1-14（本地 site/jev-1-14.md） | jev-1.14.0 发布 2026-10-14；jev-latest 已指向 1.14.0；1.13 弃用前计划 60 天预告；CJK 准确度较低、上线前自测 |
| 「不必到处设 confidence 阈值」等常见问题 | docs/agent-skill.md | Common issues 一节 |