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