> ## 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.