怎么使用《Jev 入门蓝皮书》
这本书写给这样一位开发者：你已经能让 AI 编程助手写出脚本，现在想把客户消息、文章草稿或用户请求接进一个可检查的工作流。真正卡住你的往往不是按钮怎么画，而是程序读到一句自然语言之后，究竟该走哪条分支。
我们从一个很小的目标开始：读入一条客户消息，提出明确的问题，把结果写进本地文件。随后把这个过程扩展成工单分拣、文章检查和工具路由。完成全书不以记住多少术语为标准，而以你能否解释一次判断的输入、标准、输出和后续动作来衡量。
读完以后，你会得到什么
三个案例共用 Python 配套代码，每个案例都有合成输入、离线返回样本和真实 API 调用入口。数据里的客户、订单和业务情境均用于教学；它们不是经过授权披露的客户业务记录。
| 案例 | 你提供什么 | 你检查什么 | 最终得到什么 |
|---|---|---|---|
| 工单分拣 | 带编号的客户消息 | 部门、紧急程度、复核条件 | 本地分类结果与复核队列 |
| 文章检查 | Markdown 草稿与检查标准 | 文中是否出现具体的必要内容 | 一份可读的发布前检查报告 |
| 工具路由 | 用户请求与应用状态 | 意图、参数、权限、工具错误 | 模拟 FAQ 或订单查询结果 |
本书是 CoolJev 制作的独立学习资料，与 TypeSafe 官方文档配合使用。官方接口与产品事实以章内链接为依据，核对日期为 2026 年 9 月 20 日。遇到版本差异，优先查当前官方文档，再检查本书配套代码的版本记录。
准备工作：先跑通，再接入
你需要能打开终端、进入文件夹、保存 UTF-8 文本。代码以 Python 3.10 或更新版本为学习基线；不会写完整项目也没关系，但请自己读懂 if、字典和异常处理。后面给出的编程助手指令可以帮助你理解代码，不能代替你确定业务标准。
离线案例只使用 Python 标准库，不需要安装 SDK，不需要 API Key。真实调用另外需要可用的 TypeSafe 账号、API Key、网络和相应访问权限。账号是否开放、余额及限制以你的控制台为准；下载本书并不会获得模型访问权限。
在配套项目根目录运行：
python -m examples.hello_jev tickets --mode offline
如果 python 不存在，先按快速上手创建虚拟环境。命令的意义是检查“读数据 → 接收一种返回结构 → 执行本地规则 → 保存结果”这条链路。此时你没有向 Jev 提问。
本书怎样标记证据
| 标记或措辞 | 它能说明什么 | 它不能说明什么 |
|---|---|---|
| 官方文档 | 当前公开接口与产品说明 | 你的业务数据一定达到同样表现 |
| 教学示意 | 一个概念、公式或分支如何工作 | 数字来自某次模型调用 |
offline_fixture |
本地代码能处理预先编写的返回样本 | 模型准确率、响应时间、真实费用 |
| 真实 API 调用 | 某次请求实际收到的结果与记录 | 少数样本代表所有任务 |
本版编写时没有可用的 API Key，因此不把离线案例包装成模型实测。网页和 PDF 中的示例数值若未附真实调用记录，均按教学示意理解。你拿到 Key 后，可以用相同输入运行 --mode live，保留模型版本、问题版本和原始返回，再评价业务效果。
选一条阅读路线
第一次接触 Jev，按是什么 → 快速上手 → Python API → 问题设计阅读。已经接通接口但结果不好，先读问题设计，再读置信度与评测。只想解决一个业务问题，可以进入相应案例，按章节中的前置链接补齐知识。
阅读时留一份自己的判断记录：原文是什么、你认为正确的结果是什么、标准哪一句支持这个结果、错误会造成什么后果。把分歧写下来，比反复改成“请更准确地判断”更有用。等你能稳定解释这些记录，再把本地文件接进工单系统或内容流程。
每章末尾的练习都可以用纸笔开始。没有账号时，先检查问题有没有歧义、代码能否回退；有真实调用后，再检查模型能否满足标准。这两种进度都很有价值，但应分别记录。