使用 TypeSafe 构建应用
TypeSafe 将 AI 判断单元转化为可像编程原语一样使用的小型智能：你可以将小的判断组合成更大的能力。其 System One 模型 返回快速、专注的判断结果，软件可直接消费。Jev 是 TypeSafe 的旗舰模型，也是第一个 System One 模型。它能理解自然语言，返回类型化的答案和概率，而非生成文本或推理解释。代码掌控工作流；模型在普通代码需要语义理解时提供可编程的常识。
通过 OpenRouter 调用 Jev
该技能变体通过 OpenRouter 调用 Jev，而非 TypeSafe 自有 API。TypeSafe 的文档仍是概念和问题设计的参考；仅访问方式、模型 ID 和计费不同。
- 凭证： OpenRouter API 密钥，费用计入 OpenRouter 账户。无需 TypeSafe 账户。从环境变量读取（
OPENROUTER_API_KEY或设置为 OpenRouter 密钥的TYPESAFE_API_KEY）；切勿硬编码，在 Web 应用中保留在服务端。 - System One API（默认）：
POST https://openrouter.ai/api/v1/systemone，带有Authorization: Bearer <OpenRouter 密钥>。它实现了 TypeSafe 的请求和响应结构，并在响应中添加id、provider和usage.cost。 - TypeSafe SDK（
@typesafe-ai/sdk、typesafe_sdk）：通过baseURL/base_url或TYPESAFE_BASE_URL将基础 URL 设置为https://openrouter.ai/api（SDK 会追加/v1/systemone），并通过apiKey/api_key或TYPESAFE_API_KEY传递 OpenRouter 密钥。其余遵循 TypeSafe SDK 文档。 - 不要调用 SDK 的模型列表（
client.models.list()）：在 OpenRouter 上它会访问 OpenRouter 的模型 API，其响应结构 SDK 无法处理。 - 模型 ID：
jev-1.14（当前）、jev-1.13或jev-latest；裸 ID 映射为typesafe/jev-…和~typesafe/jev-latest。固定版本以获得可复现的阈值。查看 OpenRouter 上的 TypeSafe 模型 以了解当前版本、价格和上下文长度；响应中的model字段指示实际提供服务的版本。 - Box（在
state的图像中定位描述的目标）需要jev-1.14或更高版本；1.13 会返回 400 错误。Box 始终返回边缘，因此当目标可能不存在时，请与 Noul 配合使用。 - 替代接口： OpenRouter 自己的 Decisions API（
POST https://openrouter.ai/api/alpha/decisions）及其 TypeScript、Python 和 Go SDK。仅当项目已使用 OpenRouter SDK 时才推荐使用此接口。 - 非 Jev 的类型化 API：
typesafe/jev-router是一个聊天补全路由器，它使用 Jev 选择另一个 LLM。它返回生成的文本，而非类型化答案，因此不适合本技能中的模式。 - 云和沙盒会话： 网络白名单必须包含
openrouter.ai；将密钥作为机密存储，而非普通环境变量。
OpenRouter 文档：OpenRouter 上的 Jev、OpenRouter 上的 TypeSafe SDK、Jev 教程 以及 文档索引（搜索“Jev”以找到 cookbook）。当 OpenRouter 和 TypeSafe 文档关于访问、端点、模型 ID 或定价存在分歧时，对于本设置，以 OpenRouter 文档为准。
阅读实时文档
实时 TypeSafe 文档是权威信息来源。请在任务中阅读它们。 本技能提供方向；文档包含当前概念、提示指导、API 合约、SDK 用法、模型、限制以及工作示例。
- 从 文档索引 开始，查找相关页面和 cookbook。进行针对性阅读，而非加载整个站点。
- Mintlify 通过在页面路径后添加
.md来提供 Markdown，例如 如何使用 TypeSafe 构建。从索引中的链接开始；在需要时将无扩展名的文档页面链接转换为.md。针对https://docs.typesafe.ai解析相对链接。 - 在编写集成之前，请阅读当前 API 或所选 SDK 页面，以及与设计相关的问题指导。对于新工作流，还请检查最接近的 cookbook：它通常比通用分类器展示更好的分解方式。
- 如果索引不可用，请使用下面的直接链接或站点的导航。如果 Markdown 获取失败，请尝试普通页面。如果实时访问不可用，请使用可用的本地文档或已安装的 SDK 类型，说明此限制，并避免臆想版本相关的细节。
| 任务 | 从这里开始；关注相关细节 |
|---|---|
| 理解编程模型 | System One、构建指南 |
| 探索构建什么 | 用例地图，然后从索引中查找相关 cookbook |
| 准备输入和问题 | 状态、原语，然后查看所选原语的页面 |
| 决定如何处理不确定性 | 置信度 |
| 编写 API 代码 | 首先查阅 OpenRouter 上的 TypeSafe SDK，然后针对请求结构查看 HTTP API、Python SDK 或 JavaScript SDK，并使用 OpenRouter 的基础 URL 和密钥 |
| 查找 OpenRouter cookbook | 工具调用门控、验证级联、大规模分类、权限提示自动批准 |
| 更新旧集成 | 迁移指南 和已安装 SDK 的当前参考 |
找到有用的模式
从用户想要的行为开始：应用将显示、选择、更改或移交什么？反向推导出它所需的判断。将已知规则、计算、精确查找和执行保留在代码中。保留用户选择的堆栈和范围；在语义理解有帮助的地方添加 TypeSafe。
在头脑风暴或选择架构时，不要只考虑分类。以下模式是起点：围绕用户目标组合原语，包括那些不符合既定配方的想法。
- 路由并填充已知参数。 一个请求可以选择一个处理器及其类型化的参数。提前提出有用的分支特定问题，仅消费相关答案。探索函数调用和推测性扇出。
- 选择而非生成。 在代码中找到候选值或源文本跨度，使用判断选择预期的那个，然后复制或规范化。代码还可以将源文本组装成格式化的文档或阅读指南。探索值提取和结构恢复。
- 查找并判断证据。 检索候选对象，比较它们与查询的相关性，并选择有用的上下文。探索重新排序和层次分类。
- 将判断转化为可复用的数据。 一次性对多个维度打分，然后让代码或用户控件更改权重、阈值、排序和视图。结合有标签的结果，这些信号可以成为经典的机器学习特征。探索复合评分和特征发现。
- 验证并升级。 检查特定声明或字段及其证据；将不确定或失败的情况提交给人或推理模型。探索引用检查和提取级联。
- 响应状态变化。 代码可以保留目标和观察结果，同时新的判断指导下一个有边界的步骤。保持推断状态与观察到的事实不同，并在将结果应用于已变化的情况之前检查其时效性。
对于开放式请求，提供最能服务于用户目标的少数方向，并推荐一个起点。对于具体请求，选择相关模式并构建；头脑风暴不是强制性的绕路。
设计判断
根据答案的含义选择，然后阅读相关的原语页面：
| 需求 | 原语 | 重要区别 |
|---|---|---|
| 从定义集合中选一个 | Choice | 选择一个选项；其分布比较竞争选项 |
| 某个条件是否成立 | Noul | 是的概率；没有单独的置信度；当多个条件可能同时满足时，每个标签使用一个 |
| 沿描述维度的程度 | Score | 有序级别上的概率加权位置；对于分级排名，使用可比较的每项 Score |
| 描述的目标在图像中的位置 | Box | 仅 Jev 1.14+；无标准；始终返回边缘，因此使用 Noul 询问是否存在 |
为每个问题提供足够的相关 状态：源文本、身份、关系、策略和当前事实。当上下文有多个部分时，首选命名的 JSON 字段。将判断放在 instructions 中，并在 criteria 中定义其可能的答案。问题 ID 供代码使用，不会发送给模型；在问题中包含完整含义。使用反引号路径（如 ticket.messages[0].text）引用嵌套状态。
每个问题只提出一个狭窄、连贯的判断。拆解独立有用的维度，同时不破坏被判断的关系。有边界的动作选择或上下文解释是有效的；原子化并不意味着逐字提取事实或一句话限制。字符串适用于简单问题。当定义、对比、排除或示例能明确指令或标准时，使用结构化对象或数组。Score 级别必须描述具体情境且独立自洽。
确保所需答案可用。当没有项符合时，包含一个无匹配结果；当独立有用时，使用单独的存在判断。对于源值选择，检查候选覆盖率：模型无法选择遗漏的值。
组合与验证
将针对同一状态的独立问题一起提出，包括有用的推测性问题。它们并行运行，无法看到彼此的答案。明确陈述每个推测前提；代码消费适用的答案。当先前答案对于获取证据、构建新状态或确定下一步选项是必需时，才需要第二次请求。额外问题仍消耗 token；测量实际请求预算、成本和端到端延迟。
使用概率和置信度来指导行为，阈值应根据用户的数据和后果进行评估。Choice/Score 的置信度总结了分布集中度，而非整体工作流正确性或操作权限。接近 0.5 的 Noul 表示是和否的概率相似，而非中等强度。几个可接受的备选方案也可能分散概率；低置信度不必使无害的偏好选择无效。忽略未使用分支上的不确定性。
保持策略明确和原始判断可复用。加权得分适合补偿性偏好；任何严重违规规则需要单独的条件。当证据和问题含义不变时，更改权重或显示过滤器无需重新运行推理。类型化输出保证接口，而非事实。System One 模型经过校准决策的训练；在目标领域中验证其性能。
测试代表性用例以及由此产生的应用行为。对于失败，检查确切的状态、问题、候选对象、答案、组合和观察到的结果。区分缺失证据、模型错误、代码错误和服务故障。将 cookbook 阈值和演示结果视为要评估的示例，而非通用规则或永久模型限制。在 Web 应用中，将 API 凭证保留在服务端。