安裝 SDK

安裝

npm install @hitheo/sdk

yarn add @hitheo/sdk

pnpm add @hitheo/sdk

環境要求： Node.js 18+，需支持原生 fetch。

初始化客戶端

import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
  // 可選：
  // baseUrl: "https://www.hitheo.ai",   // 默認值（規範的 `www` 主機）
  // timeoutMs: 30_000,                  // 默認值
  // maxRetries: 2,                      // 默認值 — 在 429/5xx 時重試
});

配置選項

選項	類型	默認值	說明
`apiKey`	`string`	必填	你的 `theo_sk_...` API 密鑰
`baseUrl`	`string`	`https://www.hitheo.ai`	API 基礎 URL（請始終指向 `www` —— 頂級域名會重定向，且部分 HTTP 客戶端在 3xx 跳轉時會剝離 `Authorization` 頭）
`timeoutMs`	`number`	`30000`	請求超時時間（毫秒）
`maxRetries`	`number`	`2`	在 429/5xx 錯誤時的最大重試次數

重試行為

SDK 會在以下情況下自動重試：

429 請求過多 — 遵循 Retry-After 響應頭
5xx 服務器錯誤 — 指數退避（1 秒、2 秒、4 秒，上限 8 秒）

客戶端錯誤（400、401、403、404）不會被重試。

其他可用工具

CLI

SDK 附帶一個可在終端中使用的 CLI 工具：

npm install -g @hitheo/sdk
theo init        # 在項目中配置 Theo
theo status      # 檢查連接與健康狀態（同時探測 apex 和 www）
theo verify      # 機器可讀的 JSON 診斷結果（適合 CI 使用）
theo complete "What is quantum computing?"

完整命令請參見 CLI 參考。

MCP 服務器 —— IDE 集成

通過 MCP 在 Cursor、Claude Code、Warp、Windsurf 和 VS Code 中使用 Theo： First, set your API key as an environment variable:

export THEO_API_KEY=theo_sk_...

Then pick your IDE:

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide cursor

Run this in your terminal:

claude mcp add theo npx -y @hitheo/mcp

Or run:

theo mcp install --ide claude-code

Add to .warp/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide warp

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide windsurf

Add to .vscode/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide vscode

Auto-detect and configure all installed IDEs at once:

npm install -g @hitheo/sdk
theo init

This detects Cursor, Claude Code, Warp, Windsurf, and VS Code, writes the correct config for each, and creates a theo.config.json for project-level settings.

Restart your IDE after adding the config.

入門

快速開始

核心概念

故障排查

技能

指南

MCP 服務器

Playground

控制台

安全與合規

更新日誌

安裝

初始化客戶端

配置選項

重試行為

其他可用工具

CLI

MCP 服務器 —— IDE 集成

​安裝

​初始化客戶端

​配置選項

​重試行為

​其他可用工具

​CLI

​MCP 服務器 —— IDE 集成

安裝

初始化客戶端

配置選項

重試行為

其他可用工具

CLI

MCP 服務器 —— IDE 集成