使用 TypeSafe 建構
TypeSafe 將 AI 智能單位打造成像程式設計原語一樣可用：你可以將小型判斷組合成更大的能力。其 System One 模型 返回快速、專注的判斷，軟體可以直接消費。Jev 是 TypeSafe 的旗艦產品，也是第一個 System One 模型。它能理解自然語言並返回類型化的答案與機率，而非生成文字或推理解釋。程式碼掌控工作流程；模型則在一般程式碼需要語義理解的地方，提供可程式化的常識。
透過 OpenRouter 呼叫 Jev
此技能變體是透過 OpenRouter（而非 TypeSafe 自身 API）來呼叫 Jev。TypeSafe 的文件仍然是概念與問題設計的參考依據；只有存取方式、模型 ID 與計費方式不同。
- 憑證： 一個 OpenRouter API 金鑰，費用計入 OpenRouter 帳戶。無需 TypeSafe 帳戶。從環境變數（
OPENROUTER_API_KEY或將TYPESAFE_API_KEY設為 OpenRouter 金鑰）讀取；絕不應硬編碼，並在網頁應用程式中保持在伺服器端。 - 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 的 Models 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。它回傳的是生成文字，而非類型化答案，因此不適用於此技能的模式。 - 雲端和沙箱 session： 網路允許清單必須包含
openrouter.ai；將金鑰儲存為機密，而非純文字環境變數。
OpenRouter 文件：OpenRouter 上的 Jev、OpenRouter 上的 TypeSafe SDK、Jev 教學 和 文件索引（搜尋 "Jev" 以找到食譜）。當 OpenRouter 和 TypeSafe 文件在存取方式、端點、模型 ID 或定價上不一致時，對於此設定，以 OpenRouter 的文件為準。
閱讀即時文件
即時 TypeSafe 文件是唯一真理來源。請在執行任務時閱讀它們。 此技能提供方向；文件則包含當前的概念、提示指引、API 合約、SDK 使用方式、型號、限制和實際範例。
- 從文件索引開始，以發現相關頁面和食譜。進行有目標的閱讀，而非載入整個網站。
- Mintlify 透過在頁面路徑後附加
.md來提供 Markdown，例如如何使用 TypeSafe 建構。從索引中的連結；在有用時將無副檔名的文件頁面連結轉換為.md。相對路徑請根據https://docs.typesafe.ai解析。 - 在撰寫整合程式碼之前，請先閱讀目前的 API 或所選 SDK 頁面，以及與設計相關的問題指引。對於新的工作流程，也請檢查最接近的食譜：它通常會比通用的分類器提供更好的分解方式。
- 如果索引無法使用，請使用以下直接連結或網站導航。如果 Markdown 獲取失敗，請嘗試一般頁面。如果無法即時存取，請使用可用的本地文件或已安裝的 SDK 類型，說明此限制，並避免發明依賴版本的細節。
| 任務 | 從此處開始；跟隨相關細節 |
|---|---|
| 了解程式設計模型 | System One、建構指南 |
| 探索可以建構什麼 | 使用案例地圖，然後從索引中取得相關食譜 |
| 準備輸入和問題 | 狀態、原語，然後是所選原語的頁面 |
| 決定如何處理不確定性 | 信心 |
| 撰寫 API 程式碼 | 先看 OpenRouter 上的 TypeSafe SDK，然後看 HTTP API、Python SDK 或 JavaScript SDK 以了解請求格式，使用 OpenRouter 的基礎 URL 和金鑰 |
| 尋找 OpenRouter 食譜 | 工具呼叫閘道、驗證級聯、大規模分類、權限提示自動批准 |
| 更新舊的整合 | 遷移指南 和已安裝 SDK 的現行參考 |
找到有用的形式
從使用者想要的行為開始：應用程式會顯示、選擇、變更或移交什麼？反向推導出它所需的判斷。將已知規則、計算、精確查詢和執行保留在程式碼中。保留使用者選擇的技術棧和範圍；在語義理解有幫助的地方加入 TypeSafe。
在腦力激盪或選擇架構時，不要只考慮分類。以下模式是起點：圍繞使用者的目標組合原語，包括那些不符合既定配方點子的模式。
- 路由並填入已知參數。 一個請求可以選擇一個處理程式及其類型化參數。預先詢問有用的分支特定問題，並僅消費相關答案。探索函數呼叫和推測性扇出。
- 選擇而非生成。 在程式碼中尋找候選值或來源區塊，使用判斷選擇目標值，然後複製或標準化它。程式碼也可以將來源文字組合成格式化的文件或閱讀指南。探索值提取和結構恢復。
- 尋找並判斷證據。 檢索候選項，比較它們與查詢的相關性，並選擇有用的上下文。探索重新排序和階層式分類。
- 將判斷轉化為可重複使用的資料。 一次性對各個維度進行評分，然後讓程式碼或使用者控制調整權重、閾值、排名和檢視。搭配有標籤的結果，這些訊號可以成為經典機器學習特徵。探索複合評分和特徵發現。
- 驗證並升級處理。 針對證據檢查特定聲明或欄位；將不確定或失敗的情況交給人工或推理模型處理。探索引用檢查和提取級聯。
- 回應變化的狀態。 程式碼可以保留目標和觀察結果，同時透過新的判斷來引導下一個有邊界的步驟。保持推斷狀態與觀察到的事實分離，並在將結果應用於已變更的情況之前檢查其新鮮度。
對於開放式請求，提供最能服務使用者目標的少數方向，並推薦一個起點。對於具體請求，選擇相關模式並建構；腦力激盪不是強制性的繞道。
設計判斷
根據答案的意義來選擇，然後閱讀相關的原語頁面：
| 需求 | 原語 | 重要區別 |
|---|---|---|
| 已定義集合中的一個 | Choice | 選取一個選項；其分佈比較競爭選項 |
| 條件是否成立 | Noul | 是的機率；沒有單獨的信心度；當多個可能適用時，每個標籤使用一個 |
| 沿著描述維度的程度 | Score | 有序級別上的機率加權位置；對可比較的逐項 Score 使用以進行分級排名 |
| 描述目標在圖片中的位置 | Box | 僅限 Jev 1.14+；無標準；永遠回傳邊緣，因此詢問 Noul 是否存在 |
為每個問題提供足夠相關的 狀態 來作答：來源文字、身份、關係、政策和當前事實。當上下文有多個部分時，優先使用命名的 JSON 欄位。將判斷放在 instructions 中，並在 criteria 中定義其可能的答案。問題 ID 是給程式碼用的，不會發送給模型；在問題中包含完整的含義。使用反引號路徑（例如 ticket.messages[0].text）來引用巢狀狀態。
每個問題只問一個狹義、連貫的判斷。拆分獨立有用的維度，但不要破壞正在被判斷的關係。有邊界的動作選擇或情境解釋是有效的；原子化不意味著字面的事實提取或一句話的限制。簡單問題使用字串。當定義、對比、排除或範例有助於釐清 instructions 或 criteria 時，使用結構化物件或陣列。Score 級別必須描述具體情況且能獨立理解。
保留所需的答案。當可能沒有任何東西符合時，包含一個無匹配結果；當獨立有用時，使用單獨的存在判斷。對於來源值選擇，檢查候選項的覆蓋範圍：模型無法選擇一個被省略的值。
組合與驗證
在同一狀態上同時詢問獨立的問題，包括有用的推測性問題。它們會並行執行，且無法看到彼此的回答。明確陳述每個推測前提；程式碼消費適用的答案。當需要根據先前的答案來擷取證據、建構新狀態或決定下一步選項時，才需要第二次請求。額外的問題仍會消耗 token；請衡量實際請求預算、成本和端到端延遲。
使用機率和信心來引導行為，並在使用者的資料和後果上評估閾值。Choice/Score 的信心總結了分佈的集中程度，而非整體工作流程正確性或執行權限。接近 0.5 的 Noul 表示是和否的機率相似，而非中等強度。幾個可接受的替代方案也可能分散機率；低信心不一定使無害的偏好選擇失效。忽略未使用分支上的不確定性。
保持策略明確，原始判斷可重複使用。加權評分適用於補償性偏好；「任何嚴重違規」規則需要單獨的條件。當證據和問題含義不變時，更改權重或顯示過濾器無需重新執行推理。類型化輸出保證的是介面，而非真相。System One 模型經過校準決策的訓練；在目標領域驗證其效能。
測試代表性案例以及由此產生的應用程式行為。對於失敗情況，檢查確切的狀態、問題、候選項、答案、組合和觀察到的結果。區分缺少證據、模型錯誤、程式碼錯誤和服務失敗。將食譜閾值和示範結果視為需要評估的範例，而非通用規則或永久性的模型限制。在網頁應用程式中，將 API 憑證保持在伺服器端。