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

# 安裝與設置

> 安裝 @hitheo/sdk 並配置 Theo 客戶端。

## 安裝

<CodeGroup>
  ```bash npm theme={null}
  npm install @hitheo/sdk
  ```

  ```bash yarn theme={null}
  yarn add @hitheo/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @hitheo/sdk
  ```
</CodeGroup>

**環境要求：** Node.js 18+（需要原生 `fetch` 支持）。可在 Node.js、Deno、Bun 以及邊緣運行時中使用。

## 初始化

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
});

// 一次調用完成連通性與鑑權的健全性檢查
const diagnostic = await theo.verify();
if (!diagnostic.authenticated) console.error(diagnostic.hint);
```

## 配置

| 選項 | 類型 | 默認值 | 說明 |
| - | - | - | - |
| `apiKey` | `string` | **必填** | 你的 `theo_sk_...` API 密鑰 |
| `baseUrl` | `string` | `"https://www.hitheo.ai"` | API 基礎地址（`www` 主機——見下方說明） |
| `timeoutMs` | `number` | `30000` | 一元請求超時時間（毫秒）；同時也是流式連接/首字節等待預算。參見[超時與重試](/sdk-reference/timeouts-and-retries)。 |
| `streamIdleTimeoutMs` | `number` | `120000` | 流式空閒（數據塊之間）超時時間（毫秒）。並非總時長上限。 |
| `maxRetries` | `number` | `2` | 針對 429/5xx 的重試次數（指數退避）。POST 請求的超時不會被重試。 |

<Warning>
  請始終使用 `www` 主機。裸域名 `https://hitheo.ai` 會以 307 重定向到 `https://www.hitheo.ai`，而大多數 HTTP 客戶端（包括 Node 18 內置的 `fetch`）在 3xx 響應上會剝離 `Authorization` 請求頭——重定向後的請求將以未鑑權狀態到達，並返回 `401`。自 `@hitheo/sdk@0.2.0` 起，SDK 已默認使用 `https://www.hitheo.ai`。如果你覆蓋了 `baseUrl`，請參見[401 故障排查](/troubleshooting/401-errors)。
</Warning>

## 包含內容

該 SDK 導出以下內容：

| 導出項 | 類型 | 說明 |
| - | - | - |
| `Theo` | class | 包含全部 API 方法的主客戶端 |
| `TheoStream` | class | 由 `theo.stream()` 返回——可異步迭代，並帶有 `cancel()` 與最終元數據 |
| `EviInstance` | class | E.V.I. 封裝類（通過 `theo.evi()` 創建） |
| `TheoApiError` | class | 基礎類型化錯誤，帶有 `status`、`body`、`url`、`kind` 及解析後的 `details` |
| `TheoTimeoutError` / `TheoCancelledError` | class | `TheoApiError` 的子類，分別用於超時（攜帶 `timeoutMs`）與調用方取消的場景 |
| `TheoUsageError` | class | 在 SDK 誤用時同步拋出（例如向 `complete()`/`stream()` 傳入了異步模式） |
| `defineSkill` | function | 類型安全的技能清單構建函數 |
| `defineConfig` | function | 類型安全的項目配置構建函數 |
| 所有類型 | interfaces | `CompletionRequest`、`CompletionResponse`、`StreamEvent`、`TheoStream`、`VerifyResult`、`ConversationSummary`、`SkillSummary`、`SdkToolDefinition`、`WorkflowRecord`、`WebhookRecord`、`HookRecord`、`UsageReport` 等。完整列表見[類型](/sdk-reference/types)。 |

## 0.3.x 至 0.4.0 版本新增內容

`@hitheo/sdk@0.4.0` 新增了以編程方式進行的**按密鑰編排**與賬戶管理能力——全部為增量特性，不會對現有的補全/流式代碼造成破壞性變更：

* **[`theo.keys`](/sdk-reference/keys)** —— 通過代碼創建密鑰並配置其模型方案、編排器圖與技能白名單。
* **[`theo.routingPreferences` / `theo.routingRules`](/sdk-reference/routing-studio)** —— 編寫並綁定關鍵詞/正則路由規則。
* **[`theo.guardrails`](/sdk-reference/guardrails)** —— 管理網關護欄策略、預設及按密鑰的綁定關係。
* **`theo.billingCheckout` / `theo.billingPortal`** —— 充值額度並打開賬單門戶。
* `/v1/completions` 請求新增了 `memory: false` 標誌（跳過長期記憶注入），以及更豐富的單次請求字段——詳見[創建補全](/api-reference/completions/create)。

## 升級到 0.2.0

如果你正在從 `0.1.x` 升級：

* 對於常規的 `theo.complete()` / `theo.stream()` 用法，**無需修改代碼**。
* 如果你曾顯式固定 `baseUrl: "https://hitheo.ai"`，請將其移除（或改為 `"https://www.hitheo.ai"`），以啓用新的默認值並避免請求頭被重定向剝離。
* `theo.stream()` 現在返回一個 `TheoStream`。`for await` 用法依然有效；此外你還可以使用 `.cancel()` 以及補全完成後的元數據（`conversationId`、`usage`、`requestId`）。
* `CompletionResponse.usage` 現在包含 `prompt_tokens`、`completion_tokens`、`total_tokens`，以及一個可選的 `cached` 布爾值。原有的 `res.usage.cost_cents` 用法仍可正常使用。
* 原先返回 `Promise<unknown[]>` 的列表方法（`conversations`、`skills`、`tools`、`workflows`、`submissions` 等）現在返回類型化記錄——請移除任何 `as any` 類型斷言。
  完整發布說明：[更新日誌](/changelog)。


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