> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由工作室

> 通過 SDK 管理按客戶設置的路由偏好以及按密鑰設置的規則。

路由工作室（Routing Studio）讓你能夠針對自己的業務領域調整 Theo 路由引擎的判斷傾向。SDK 暴露了三個命名空間：

* `theo.routingPreferences` — 共享偏好對象（一套規則集，可綁定多個密鑰）。
* `theo.routingRules` — 無需顯式偏好對象即可編輯單個密鑰的規則。
* `theo.keys.getRoutingPreference` / `setRoutingPreference` — 將共享偏好綁定到某個密鑰。

完整的 ContractIQ 演示請參見[路由工作室指南](/guides/routing-studio)，底層 HTTP 結構請參見 [API 參考](/api-reference/routing-preferences/list-preferences)。

## 共享偏好

### 列出

```typescript theme={null}
const prefs = await theo.routingPreferences.list();
```

### 獲取

```typescript theme={null}
const pref = await theo.routingPreferences.get(prefId);
```

### 創建

`scope: "team"` 需要一個有效的組織以及團隊配置權限。通過 `Idempotency-Key` 請求頭實現冪等。

```typescript theme={null}
const pref = await theo.routingPreferences.create({
  name: "ContractIQ Legal",
  description: "Contract terms get the analytical engine.",
  rules: [
    {
      pattern: "\\b(clause|provision|indemnity|warranty)\\b",
      target_mode: "think",
      confidence: 0.92,
      description: "Contract terms get the analytical engine.",
    },
  ],
  examples: [
    { prompt: "Look at this clause", expected_mode: "think" },
    { prompt: "Compare these two indemnity sections", expected_mode: "think" },
  ],
  confidence_floor_overrides: { think: 0.65 },
});
```

### 更新

```typescript theme={null}
await theo.routingPreferences.update(pref.id, { enabled: false });
```

傳入 `rules` 或 `examples` 會替換整個集合。

### 刪除

會級聯移除所有指向該偏好的密鑰綁定。

```typescript theme={null}
await theo.routingPreferences.delete(pref.id);
```

### 測試（針對路由引擎重放）

會將同一條提示重放兩次——一次不應用偏好（基線），一次應用偏好——以便你渲染出並排對比的差異。

```typescript theme={null}
const diff = await theo.routingPreferences.test(pref.id, {
  prompt: "Compare these two warranty sections",
  mode: "auto",
});
console.log(diff.baseline.resolved_mode);        // "fast"
console.log(diff.with_preference.resolved_mode); // "think"
```

兩個數據塊的結構都與調用方在真實補全請求中收到的 `routing` 遙測數據一致。

## 按密鑰的路由規則

這是無需偏好對象的快捷方式：服務端會在後台自動查找或創建一個隱藏的按密鑰偏好，並確保綁定行指向它。當你只需調整單個密鑰時，可以使用這種方式。

### 獲取

```typescript theme={null}
const snap = await theo.routingRules.get(keyId);
console.log(snap.active);          // 若這些規則當前驅動着補全請求，則為 true
console.log(snap.shared_binding);  // 當該密鑰綁定到某個共享偏好時會被填充
```

### 生效規則

這是當前實際驅動該密鑰補全請求的快照，並附帶一個 `source` 枚舉，方便你渲染繼承來源的上下文信息。

```typescript theme={null}
const eff = await theo.routingRules.effective(keyId);
console.log(eff.source);          // "key" | "org_default" | "user_default" | "none"
console.log(eff.preference_name); // "This key's rules" | "ACME Legal Default" | null
```

### 設置

替換該密鑰的規則 / 示例 / 覆蓋項，並確保綁定指向那個隱藏行。

```typescript theme={null}
await theo.routingRules.set(keyId, {
  rules: [
    {
      pattern: "\\b(clause|provision|indemnity|warranty)\\b",
      target_mode: "think",
      confidence: 0.92,
      description: "Contract terms get the analytical engine.",
    },
  ],
  examples: [{ prompt: "Look at this clause", expected_mode: "think" }],
});
```

### 清除

會移除綁定（該密鑰隨後回退到組織默認 → 用戶默認 → 無），並刪除那個隱藏的偏好行。指向共享偏好的現有綁定不受影響。

```typescript theme={null}
await theo.routingRules.clear(keyId);
```

## 密鑰綁定（共享偏好）

將一個已存在的共享偏好綁定到某個密鑰，或清除該綁定。

```typescript theme={null}
// 讀取當前綁定
const { preference_id, inherits_default } =
  await theo.keys.getRoutingPreference(keyId);

// 綁定一個偏好
await theo.keys.setRoutingPreference(keyId, pref.id);

// 清除綁定（密鑰回退到組織默認 → 用戶默認 → 無）
await theo.keys.setRoutingPreference(keyId, null);
```

## 類型

SDK 為每種數據結構都導出了一等類型——`switch` 和 `if` 分支無需使用 `as any` 即可完成類型收窄：

* `RoutingPreferenceSummary` — 完整的偏好行。
* `RoutingRuleInput` — 單條關鍵詞/正則規則（`pattern`、`target_mode`，可選的 `target_engine`、`confidence`，可選的 `description`）。
* `RoutingExampleInput` — 少樣本（few-shot）示例（`prompt`、`expected_mode`，可選的 `expected_engine`）。
* `RoutingPreferenceTestResult` — `test` 返回的 `{ baseline, with_preference }` 數據封裝。
* `KeyRoutingRulesSnapshot` — 按密鑰的快照，包含 `active` 與 `shared_binding`。
* `KeyEffectiveRouting` — 帶有 `source` 枚舉的生效路由快照。

## 遙測

當某個偏好參與了一次補全請求的路由決策時，`meta` 和 `done` 這兩個 SSE 事件會附帶一個 `customer_preference` 數據塊：

```json theme={null}
{
  "routing": {
    "reason": "customer_preference",
    "explanation": "Routing Studio rule matched: \"clause\".",
    "customer_preference": {
      "id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e",
      "name": "ContractIQ Legal",
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
```

在你的產品中讀取 SDK 裏 `meta` 事件的 `routing` 字段，即可渲染出相同的效果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.