3.4 类型选型与请求骨架

3.4 类型选型与请求骨架

本节摘要：本节收束第 3 章：给出一棵"遇到判断先选型"的决策树（答案空间可枚举吗 → 是非闸门吗 → 选项有序吗 → 是否组合判断），以及完整的请求骨架总览（model / state / questions / 问题内四要素）与错误码速览。此后每一章的代码都建立在这张骨架上。选型的通用直觉：Noul 是一道闸、Choice 是归堆、Score 是落位；复杂判断永远"拆成原子问题 + 代码组合"。

学习目标

阅读完本节，你应当能够：

1. 用选型决策树在 30 秒内确定一个需求的类型方案。
2. 默写请求骨架的层级结构与问题内四要素。
3. 记住四个错误码与处理方式。

一、选型决策树

答案空间能枚举吗？──否──▶ 生成题，用 LLM，别用 Jev（第 2.2 节）
      │是
      │
是/非一道闸？────是────▶ Noul（多道闸并行；第 3.1 节）
      │否
      │
选项之间无序？────是────▶ Choice（带 other 逃生门；第 3.2 节）
      │否
      │
有序标尺上落位？──是────▶ Score（一个维度一个；第 3.3 节）
      │否
      │
是一个综合大判断？──────▶ 拆成上面若干个原子问题 + 代码组合
                          （第 6.3 节复合评分 / 第 7.3 节多闸门护栏）
​

三个经验法则：

• 宁可多问：拆细的问题并行求值近零成本（第 5.1 节），混维度的"综合题"才是贵的——代价藏在错误率里。
• 闸门优先：能拆成 Noul 闸门的尽量拆（可解释、可独立调阈值）；Choice 留给真正需要归堆的路由与分类。
• 组合在代码：权重、优先级、取舍是你的业务知识，写在代码里可审计可回归（第 6.3 节）。

二、请求骨架总览

// POST https://api.typesafe.ai/v1/systemone
{
  "model": "jev-latest",                  // 生产建议钉版本：jev-1.13.0
  "state": /* 字符串 | 对象 | 数组 */,     // 模型看到的世界；对象可用 `path` 引用字段
  "questions": {
    "q_id": {                             // ID 自定，不发给模型，是你代码里的变量名
      "type": "noul | choice | score",
      "instructions": "判别标准式自然语言",
      "criteria": [ /* score: 有序等级数组（2~10 级） */ ]
                // 或  { /* choice: 选项名 → 描述（≤255，建议 ≤20） */ }
                // 或  省略（noul）
    }
    // 更多问题…全部并行求值、一次返回
  }
}
​

响应按类型（详表见附录 B）：

容量红线（附录 B 有完整表）：state + 最长问题 ≤ ~32K token（约 15 万字符）；整请求 ≤ ~64K token；仅文本输入。

三、错误码速览

💡 幂等性红利：Jev 调用是纯函数式的（无状态、无副作用），429/529 重试不需要任何防重逻辑——这与调用会产生副作用的 LLM 工作流形成鲜明对比。

本节要点回顾

1. 决策树：可枚举？→ 是非闸（Noul）/ 归堆（Choice）/ 落位（Score）→ 综合题拆原子 + 代码组合。
2. 骨架：model + state + questions（ID 自定 + type + instructions + criteria）。
3. 纪律：宁拆勿混、闸门优先、组合在代码；纯函数调用，重试无忧。

语法层完工。下一章动手：从 curl 裸调协议，到 Python/Node 官方 SDK，再到 LangChain 与 Vercel AI SDK——五种环境跑通同一个决策。