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