> ## 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/mcp 暴露的每一個 MCP 工具——模式定義、示例，以及背後對應的 SDK/REST 端點。

`@hitheo/mcp` 向你的 IDE 智能體暴露十四個工具。每個工具都封裝了 [`@hitheo/sdk`](/sdk-reference/installation) 上的一個方法，並最終調用 `https://www.hitheo.ai/api/v1/*` 上的某個 REST 端點。下面的模式定義是從 `packages/mcp/src/tools.ts` 中原樣摘錄的，因此你的 IDE 在其工具目錄中看到的內容與這裏記錄的完全一致。

這些工具分為兩組:**執行**類工具用於實際運行任務(`theo_complete`、`theo_code` 等),**配置**類工具則根據自然語言描述來構建和調整某個密鑰的編排器(`theo_setup_key`、`theo_set_guardrail` 等)。每次配置變更都會立即保存,並在 `/dashboard/orchestrator?key=…` 的儀表盤畫布上渲染出來。

<Note>
  工具永遠不會看到你的 API 密鑰——`@hitheo/mcp` 在啓動時從 `THEO_API_KEY` 讀取一次密鑰,並代表智能體對底層 HTTP 請求進行簽名。智能體只能看到工具返回的文本/JSON。
</Note>

<Warning>
  每個**配置**類工具(`theo_setup_key`、`theo_configure_key`、`theo_add_skill`、`theo_assign_skill_to_node`、`theo_set_guardrail`、`theo_set_routing`)都要求 MCP 服務器自身所使用的密鑰攜帶 **`billing`** 權限範圍。若缺少該權限範圍,這些調用會返回權限錯誤。
</Warning>

<Note>
  **權限範圍繼承。** 配置類工具會繼承 MCP 服務器用於身份驗證的那個密鑰的權限範圍。將服務器指向一個**團隊密鑰**,它創建的一切——新密鑰(`theo_setup_key`)、路由偏好和護欄策略(`theo_set_routing` / `theo_set_guardrail`)——都會歸屬於該**團隊**、計入團隊賬單,並對每個成員可見。將其指向一個個人密鑰,同樣這些工具就會保持在個人範圍內。你永遠不需要顯式傳入權限範圍,它會跟隨密鑰自動確定。
</Note>

## 工具目錄

### 執行類

| 工具 | 用途 | SDK | REST |
| - | - | - | - |
| [`theo_complete`](#theo_complete) | 通用編排補全 | [`theo.complete()`](/sdk-reference/completions) | [`POST /api/v1/completions`](/api-reference/completions/create) |
| [`theo_code`](#theo_code) | 具有長輸出預算的代碼生成 | [`theo.code()`](/sdk-reference/completions) | [`POST /api/v1/code`](/api-reference/code/generate) |
| [`theo_research`](#theo_research) | 帶引用的深度研究(異步) | [`theo.research()`](/sdk-reference/completions) | [`POST /api/v1/research`](/api-reference/research/create) |
| [`theo_image`](#theo_image) | 圖像生成 | [`theo.images()`](/sdk-reference/media) | [`POST /api/v1/images`](/api-reference/images/generate) |
| [`theo_document`](#theo_document) | 生成 PDF / DOCX / PPTX / XLSX / CSV | [`theo.documents()`](/sdk-reference/media) | [`POST /api/v1/documents`](/api-reference/documents/generate) |
| [`theo_skill_list`](#theo_skill_list) | 列出已安裝或市場中的技能 | [`theo.skills()`](/sdk-reference/skills) | [`GET /api/v1/skills`](/api-reference/skills/list) |
| [`theo_skill_install`](#theo_skill_install) | 從市場安裝一個技能 | [`theo.installSkill()`](/sdk-reference/skills) | [`POST /api/v1/skills`](/api-reference/skills/install) |
| [`theo_status`](#theo_status) | 引擎健康狀態與延遲 | [`theo.health()`](/sdk-reference/client) | [`GET /api/v1/health`](/api-reference/health/check) |

### 配置類(需要 `billing` 權限範圍)

| 工具 | 用途 | REST |
| - | - | - |
| [`theo_setup_key`](#theo_setup_key) | 創建一個新密鑰,並同時生成一個已保存、可見的編排器(預設 / 按模式路由 / 完整圖) | `POST /api/v1/keys` + `PUT …/orchestrator-graph` |
| [`theo_configure_key`](#theo_configure_key) | 重新規劃一個已有密鑰(選項與 setup 相同) | `PUT …/orchestrator-graph` |
| [`theo_add_skill`](#theo_add_skill) | 安裝並將某個技能掛接到密鑰上(可選限定到某一模式) | `PUT …/keys/{id}/skills` |
| [`theo_assign_skill_to_node`](#theo_assign_skill_to_node) | 將技能掛接到圖中的節點(按 id / 標籤 / 模式 / 引擎匹配) | `PUT …/orchestrator-graph` |
| [`theo_set_guardrail`](#theo_set_guardrail) | 以輸入/輸出節點(或密鑰級別)的形式添加護欄 | `PUT …/keys/{id}/guardrails` |
| [`theo_set_routing`](#theo_set_routing) | 追加路由規則並插入一個 Router 節點 | `PUT …/keys/{id}/routing-preference` |

***

## `theo_complete`

通過 Theo 的編排引擎運行一次 AI 補全。Theo 會自動識別意圖、在 300 多個 AI 模型中選擇最合適的引擎、注入領域技能、執行工具調用,並返回結果。適用於任何通用 AI 任務:寫作、分析、規劃、問答。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `prompt` | `string` | ✅ | 發送給 Theo 的提示詞或問題。 |
| `mode` | `"auto" \| "fast" \| "think" \| "code" \| "research" \| "roast"` | — | 執行模式。`auto` 讓 Theo 自行分類;`fast` 使用輕量模型;`think` 使用深度推理;`code` 針對代碼進行優化。默認值:`auto`。 |
| `skills` | `string[]` | — | 要激活的技能標識(例如 `["deep-research", "content-writer"]`)。 |
| `conversation_id` | `string` | — | 通過 ID 延續一個已有對話。 |

當 `theo.config.json` 定義了 `persona`、`skills`、`defaultMode` 或 `tools` 時,這些值會被合併進請求——參見[項目配置](/mcp/project-config#merge-semantics)。

### 智能體調用示例

```text theme={null}
Use theo_complete to draft a release-note summary for the diff in HEAD~3..HEAD.
```

### 響應示例(已截斷)

```text theme={null}
Here's a release-note summary for the last three commits:
- ...

---
Tools used: web_search (ok), summarize_diff (ok)
Model: Theo Reason | Mode: think | Cost: 3¢
```

### 說明

* 輸出末尾附帶一行摘要,包含最終選定的模型、模式和費用,方便智能體瞭解請求是如何被路由的。
* 費用會在執行完成後進行核對,並反映到你賬戶的實際計費中。

***

## `theo_code`

使用 Theo 生成代碼。請求會被路由到 Theo Code 引擎,以獲得業界領先的代碼生成能力,並配有更大的輸出預算。返回生成的代碼及任何附件(完整文件、項目腳手架)。適用於以編寫、生成或搭建代碼為主的任務。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `prompt` | `string` | ✅ | 描述你想生成的代碼。 |
| `language` | `string` | — | 目標編程語言(例如 `typescript`、`python`、`go`)。 |
| `framework` | `string` | — | 目標框架(例如 `nextjs`、`express`、`fastapi`、`react`)。 |

### 智能體調用示例

```text theme={null}
Use theo_code to scaffold a FastAPI service with a /health route and a /chat
SSE route. language=python, framework=fastapi.
```

該工具會返回生成的內容,以及一個包含所創建文件詳情的 JSON 格式 `Artifacts:` 區塊。

***

## `theo_research`

針對某個主題運行深度研究。Theo 會規劃 3–6 條聚焦的搜索查詢、並行執行、去重來源,並綜合出一份帶引用的結構化報告。**這是一個異步操作**——MCP 服務器會持續輪詢,直到底層任務完成(默認預算:120 秒,輪詢間隔 3 秒),然後返回最終報告。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `prompt` | `string` | ✅ | 研究問題或主題。 |
| `depth` | `"basic" \| "advanced"` | — | `basic` 更快;`advanced` 更徹底。默認值:`basic`。 |

### 智能體調用示例

```text theme={null}
Use theo_research with depth="advanced" to compare PostgreSQL native partitioning
vs Citus for a write-heavy time-series workload.
```

### 失敗處理

如果研究任務失敗或超時,該工具會返回一段以 `Research failed:` 開頭的純文本,便於智能體判斷是否要用更窄的提示詞重試。

***

## `theo_image`

使用 Theo 生成圖像。請求會被路由到 Theo Create 引擎,並具備自動的服務商回退能力。返回圖像 URL。適用於徽標、插圖、原型圖、概念圖等任何視覺內容。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `prompt` | `string` | ✅ | 描述要生成的圖像。 |
| `style` | `string` | — | 視覺風格(例如 `photorealistic`、`illustration`、`3d`、`pixel`)。 |
| `aspect_ratio` | `"1:1" \| "16:9" \| "9:16" \| "4:3" \| "3:4"` | — | 寬高比。默認值:`1:1`。 |

### 響應示例

```text theme={null}
Image 1: https://artifacts.hitheo.ai/img/<id>.png [theo-vision]

Cost: 5¢
```

每一行對應一張圖像;如果請求中要求生成多張,你會得到每張圖像各一個 URL,末尾附帶一行總費用。

***

## `theo_document`

生成一份格式化文檔。Theo 會創建文檔,並返回一個位於 `artifacts.hitheo.ai` 上的下載鏈接。適用於報告、演示文稿、電子表格和數據導出。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `prompt` | `string` | ✅ | 描述要生成的文檔。 |
| `format` | `"pdf" \| "docx" \| "pptx" \| "xlsx" \| "csv"` | — | 輸出格式。默認值:`pdf`。 |

### 智能體調用示例

```text theme={null}
Use theo_document with format="pptx" to build a 7-slide pitch deck for an
AI-native EHR called SentryOS.
```

### 響應示例

```text theme={null}
Document: SentryOS Pitch Deck
Format: pptx
Download: https://artifacts.hitheo.ai/doc/<id>.pptx

Cost: 3¢
```

***

## `theo_skill_list`

列出可用的 Theo 技能。技能是打包好的領域知識與工具集合,用於擴展 Theo 的能力(類似 AI 的應用程序)。可按 `installed`(該賬戶上已啓用)或 `marketplace`(可供安裝)進行過濾。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `filter` | `"installed" \| "marketplace"` | — | 過濾為已安裝的技能或市場目錄。默認值:顯示全部可見項。 |

該工具返回一個格式化打印的技能記錄 JSON 數組(`id`、`slug`、`name`、`description`、`version` 等)。智能體通常會將其與 [`theo_skill_install`](#theo_skill_install) 搭配使用。

***

## `theo_skill_install`

從 Theo 市場安裝一個技能。安裝完成後,該技能的領域知識與工具會在每次補全時可用(包括之後每一次 `theo_complete` MCP 調用)。

### 輸入模式

| 字段 | 類型 | 是否必填 | 說明 |
| - | - | - | - |
| `skill_id` | `string` | ✅ | 要安裝的技能 ID。 |

### 響應示例

```text theme={null}
Skill skill_a1b2c3 installed successfully.
```

***

## `theo_status`

檢查 Theo 的健康狀態與引擎可用性。返回引擎狀態、延遲以及基礎設施健康情況。用於驗證連接是否正常,或在 IDE 內部診斷問題。

### 輸入模式

無參數。

### 響應示例

```text theme={null}
Status: healthy
Version: 2026-03-28
Engines:
  theo-core: healthy
  theo-vision: healthy
  theo-search: healthy
```

如果工具返回的結果不是 `Status: healthy`,請在主機上運行 [`theo verify`](/cli-reference/overview#commands) 進行排查。

***

## `theo_setup_key`

一次調用即可創建一個**新的** Theo API 密鑰,並構建出一個**已保存、可見的編排器**——無需在畫布上手動搭建。可通過三種方式之一指定方案(優先級:**`graph` > `routing` > `use_case`**):

* **`use_case`** ——單引擎預設。`coding` 將某個代碼引擎固定為確定性的直通後端(適合作為 Warp / Cursor 的即插即用後端);`chat` 固定為快速引擎;`raw` 由你自行選擇引擎。
* **`routing`** ——按模式綁定引擎。Theo 的分類器會將每個請求劃分為某種模式,你可以為每種模式固定一個引擎。
* **`graph`** ——一個完整的自定義編排器圖 `{ enabled, nodes, edges }`,將按原樣應用。

返回原始密鑰(**只顯示一次**)以及一個儀表盤鏈接。編排器會立即啓用。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `use_case` | `"coding" \| "chat" \| "raw"` | 單引擎預設。`coding` 為默認值。 |
| `model` | `string` | 為該預設固定的引擎 id(例如 `anthropic/claude-opus-4.8`)。對於 `raw`**必填**。 |
| `routing` | `Array<{ mode, model }>` | 按模式綁定引擎,例如 `[{ "mode": "fast", "model": "arca-velox-5.1" }, { "mode": "think", "model": "arca-magnus-5.1" }]`。 |
| `graph` | `{ enabled, nodes[], edges[] }` | 高級選項:完整的圖。會覆蓋 `use_case` / `routing`。 |
| `name` | `string` | 新密鑰的可選名稱。 |

### 智能體調用示例

```text theme={null}
Use theo_setup_key to make a key where light requests go to Arca Velox and heavy
ones to Arca Magnus.
```

```json theme={null}
theo_setup_key { "routing": [
  { "mode": "fast",  "model": "arca-velox-5.1" },
  { "mode": "think", "model": "arca-magnus-5.1" }
] }
```

### 響應示例(已截斷)

```text theme={null}
✅ Created key "orchestrator (via MCP)".

API key (shown once — store it now):
  theo_sk_…

Built & saved an orchestrator graph (classifier → one engine per mode):
  fast → arca-velox-5.1
  think → arca-magnus-5.1

Review or extend this setup in the dashboard:
  https://www.hitheo.ai/dashboard/orchestrator?key=…
```

***

## `theo_configure_key`

重新規劃一個**已有**密鑰——選項與 `theo_setup_key` 相同(`use_case` / `routing` / `graph`,優先級相同)。變更會立即反映在儀表盤畫布上。返回一個儀表盤鏈接。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `key_id` | `string` | **必填。** 要配置的 API 密鑰 UUID。 |
| `use_case` | `"coding" \| "chat" \| "raw"` | 單引擎預設。 |
| `model` | `string` | 引擎 id 覆蓋值;對於 `raw`**必填**。 |
| `routing` | `Array<{ mode, model }>` | 按模式綁定引擎。 |
| `graph` | `{ enabled, nodes[], edges[] }` | 完整的圖;會覆蓋其他選項。 |

### 智能體調用示例

```text theme={null}
Use theo_configure_key on key <uuid> to send everything to Claude Opus.
```

```json theme={null}
theo_configure_key { "key_id": "<uuid>", "use_case": "raw", "model": "anthropic/claude-opus-4.8" }
```

***

## `theo_add_skill`

安裝一個技能(如需,從市場安裝),並將其掛接到某個密鑰的允許列表上,使該密鑰能夠調用它。可選地限定到單一**模式**。該操作具有冪等性——重複添加同一個(技能, 模式)組合不會產生任何變化。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `key_id` | `string` | **必填。** API 密鑰 UUID。 |
| `skill` | `string` | **必填。** 技能標識、名稱或 id(例如 `deep-research`)。 |
| `mode` | `string` | 可選:限定到某一模式(`fast` / `think` / `code` / `research` / `roast` / `genui` / `data_extraction` / `vision`)。省略則應用於所有模式。 |

### 智能體調用示例

```text theme={null}
Add the deep-research skill to key <uuid>, but only for the think mode.
```

```json theme={null}
theo_add_skill { "key_id": "<uuid>", "skill": "deep-research", "mode": "think" }
```

如果無法解析出對應的技能,該工具會返回 `No skill matches "…"`,以便智能體調用 [`theo_skill_list`](#theo_skill_list) 後重試。

***

## `theo_assign_skill_to_node`

將一個技能掛接到某個密鑰編排器圖中的一個或多個**模型節點**上,使該技能只作用於這些節點。目標節點可通過節點的**id**、**標籤**、其所處理的**模式**,或其運行的**引擎**來匹配——技能會掛接到**每一個**匹配到的節點上。因此,如果查詢中指定的引擎或模式被兩個及以上節點共用,則會命中所有這些節點(例如 `sonnet` 會掛接到運行 `anthropic/claude-sonnet-4.6` 的每一個節點)。

要求該密鑰已經擁有一個圖。如果沒有任何匹配,該工具會返回可用節點的列表。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `key_id` | `string` | **必填。** API 密鑰 UUID。 |
| `node` | `string` | **必填。** 節點 id、標籤、其處理的模式(`code`),或其運行的引擎(`sonnet`、`arca-magnus-5.1`)。會匹配所有具有該模式/引擎的節點。 |
| `skill` | `string` | **必填。** 技能標識、名稱或 id。 |

### 智能體調用示例

```text theme={null}
Put the deep-research skill on every node running sonnet on key <uuid>.
```

```json theme={null}
theo_assign_skill_to_node { "key_id": "<uuid>", "node": "sonnet", "skill": "deep-research" }
```

```text theme={null}
✅ Skill "deep research" (deep-research) attached to 2 nodes (think, code) on key <uuid>.
```

***

## `theo_set_guardrail`

將一個 [Gateway Guardrails](/guides/guardrails) 策略綁定到某個密鑰。可以傳入一個已有策略的**名稱/id**,或一個**預設**名稱(例如 `PII-safe`、`Injection guard`),由該模板創建策略並綁定。在擁有編排器圖的密鑰上,該策略會以一個**護欄節點**的形式加入畫布:

* **input** 節點(位於 Entry 之後,或在限定範圍時位於分類器之後)負責檢查**提示詞**;
* **output** 節點(位於模型之後)負責檢查**回覆**。

**phase(階段)**默認從策略自身的規則階段(`input` / `output` / `both`)中推斷,除非你顯式傳入 `phase`。傳入 **`mode`**(某個模式或引擎名稱)可將護欄限定到該分支——它會掛接到所有具有該模式/引擎的節點。對於**沒有**圖的密鑰,該策略會在密鑰級別綁定(按其規則同時檢查兩個階段)。`remove: true` 會清除護欄;附加 `phase` 可僅移除輸入或輸出檢查點。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `key_id` | `string` | **必填。** API 密鑰 UUID。 |
| `policy` | `string` | 一個已有策略的名稱/id,或一個預設名稱。 |
| `phase` | `"input" \| "output" \| "both"` | 運行位置。省略則從策略中推斷。同時用於過濾 `remove`。 |
| `mode` | `string` | 可選:限定到某一分支——某個模式(`think`)或引擎(`sonnet`、`anthropic/claude-opus-4.8`)。會命中所有匹配的節點。 |
| `remove` | `boolean` | 解綁護欄。與 `phase` 組合使用可僅移除輸入或輸出。 |

### 智能體調用示例

```text theme={null}
Add PII-safe on the output of key <uuid>.
```

```json theme={null}
theo_set_guardrail { "key_id": "<uuid>", "policy": "PII-safe", "phase": "output" }
```

```text theme={null}
Add an injection guard on the input of just the think branch of key <uuid>.
```

```json theme={null}
theo_set_guardrail { "key_id": "<uuid>", "policy": "Injection guard", "phase": "input", "mode": "think" }
```

```text theme={null}
Remove only the output guardrail from key <uuid>.
```

```json theme={null}
theo_set_guardrail { "key_id": "<uuid>", "remove": true, "phase": "output" }
```

***

## `theo_set_routing`

將一個 Routing Studio 偏好綁定到某個密鑰——可以是一個已有的**偏好**(按名稱/id),也可以直接內聯創建規則(`pattern` 關鍵詞/正則 → `mode`)。規則默認是**累加**的:新規則會追加到該密鑰當前的路由上(並去重),因此再次請求添加第二條規則時,第一條規則仍會保留。傳入 `replace: true` 可改為重置。對於擁有圖的密鑰,會插入一個單獨的**Router 節點**(`Entry → … → Router → Classifier`),使規則真正生效並顯示在畫布上;如果某條規則的目標模式沒有對應的引擎節點,則會觸發一條警告。`remove: true` 會清除路由。

### 輸入模式

| 字段 | 類型 | 說明 |
| - | - | - |
| `key_id` | `string` | **必填。** API 密鑰 UUID。 |
| `preference` | `string` | 要綁定的已有路由偏好的名稱或 id。 |
| `rules` | `Array<{ pattern, mode, engine? }>` | 要添加的規則:關鍵詞/正則 → 模式(可選固定引擎)。 |
| `name` | `string` | 由 `rules` 創建偏好時的可選名稱。 |
| `replace` | `boolean` | 替換該密鑰的規則,而不是追加(默認:追加)。 |
| `remove` | `boolean` | 從該密鑰解綁路由偏好。 |

### 智能體調用示例

```text theme={null}
On key <uuid>, route anything mentioning "invoice" to code.
```

```json theme={null}
theo_set_routing { "key_id": "<uuid>", "rules": [ { "pattern": "invoice", "mode": "code" } ] }
```

第二次調用會在第一次的基礎上追加:

```text theme={null}
✅ Added 1 routing rule to key <uuid> (2 total):
  /contract/i → think
```

***

## 參考

**引擎**(配置界面——此處有意展示真實引擎名稱):`arca-velox-5.1`(快速)、`arca-magnus-5.1`(深度推理)、`anthropic/claude-sonnet-4.6`、`anthropic/claude-opus-4.8`、`anthropic/claude-haiku-4.5`、`google/gemini-2.5-pro`、`openai/gpt-4.1`,以及你自己的 `custom:<providerId>:<model>`。

**模式:** `fast`、`think`、`code`、`research`、`roast`、`genui`、`data_extraction`、`vision`、`image`、`video`。

**護欄預設:** 例如 `PII-safe`、`Injection guard`。若不匹配,該工具會列出所有可用的策略和預設。

***

## 錯誤

當任何工具拋出異常(網絡錯誤、API 錯誤信封、輪詢超時)時,MCP 服務器會將其格式化為:

```text theme={null}
Theo error: <message>
```

智能體會將這段文本視為一個普通的工具結果,而不是 JSON-RPC 錯誤,因此它可以讀取並做出應對,而不是直接放棄。如果你的 IDE 會展示 MCP 服務器日誌,完整的結構化錯誤信息也會在其中可見。

關於最常見的失敗情形,請參見[故障排查](/mcp/troubleshooting)。


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