Skip to main content
@hitheo/mcp 向你的 IDE 智能体暴露十四个工具。每个工具都封装了 @hitheo/sdk 上的一个方法,并最终调用 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=… 的仪表盘画布上渲染出来。
工具永远不会看到你的 API 密钥——@hitheo/mcp 在启动时从 THEO_API_KEY 读取一次密钥,并代表智能体对底层 HTTP 请求进行签名。智能体只能看到工具返回的文本/JSON。
每个配置类工具(theo_setup_key、theo_configure_key、theo_add_skill、theo_assign_skill_to_node、theo_set_guardrail、theo_set_routing)都要求 MCP 服务器自身所使用的密钥携带 billing 权限范围。若缺少该权限范围,这些调用会返回权限错误。
权限范围继承。 配置类工具会继承 MCP 服务器用于身份验证的那个密钥的权限范围。将服务器指向一个团队密钥,它创建的一切——新密钥(theo_setup_key)、路由偏好和护栏策略(theo_set_routing / theo_set_guardrail)——都会归属于该团队、计入团队账单,并对每个成员可见。将其指向一个个人密钥,同样这些工具就会保持在个人范围内。你永远不需要显式传入权限范围,它会跟随密钥自动确定。

工具目录

执行类

配置类(需要 billing 权限范围)


theo_complete

通过 Theo 的编排引擎运行一次 AI 补全。Theo 会自动识别意图、在 300 多个 AI 模型中选择最合适的引擎、注入领域技能、执行工具调用,并返回结果。适用于任何通用 AI 任务:写作、分析、规划、问答。

输入模式

当 theo.config.json 定义了 persona、skills、defaultMode 或 tools 时,这些值会被合并进请求——参见项目配置。

智能体调用示例

响应示例(已截断)

说明

  • 输出末尾附带一行摘要,包含最终选定的模型、模式和费用,方便智能体了解请求是如何被路由的。
  • 费用会在执行完成后进行核对,并反映到你账户的实际计费中。

theo_code

使用 Theo 生成代码。请求会被路由到 Theo Code 引擎,以获得业界领先的代码生成能力,并配有更大的输出预算。返回生成的代码及任何附件(完整文件、项目脚手架)。适用于以编写、生成或搭建代码为主的任务。

输入模式

智能体调用示例

该工具会返回生成的内容,以及一个包含所创建文件详情的 JSON 格式 Artifacts: 区块。

theo_research

针对某个主题运行深度研究。Theo 会规划 3–6 条聚焦的搜索查询、并行执行、去重来源,并综合出一份带引用的结构化报告。这是一个异步操作——MCP 服务器会持续轮询,直到底层任务完成(默认预算:120 秒,轮询间隔 3 秒),然后返回最终报告。

输入模式

智能体调用示例

失败处理

如果研究任务失败或超时,该工具会返回一段以 Research failed: 开头的纯文本,便于智能体判断是否要用更窄的提示词重试。

theo_image

使用 Theo 生成图像。请求会被路由到 Theo Create 引擎,并具备自动的服务商回退能力。返回图像 URL。适用于徽标、插图、原型图、概念图等任何视觉内容。

输入模式

响应示例

每一行对应一张图像;如果请求中要求生成多张,你会得到每张图像各一个 URL,末尾附带一行总费用。

theo_document

生成一份格式化文档。Theo 会创建文档,并返回一个位于 artifacts.hitheo.ai 上的下载链接。适用于报告、演示文稿、电子表格和数据导出。

输入模式

智能体调用示例

响应示例


theo_skill_list

列出可用的 Theo 技能。技能是打包好的领域知识与工具集合,用于扩展 Theo 的能力(类似 AI 的应用程序)。可按 installed(该账户上已启用)或 marketplace(可供安装)进行过滤。

输入模式

该工具返回一个格式化打印的技能记录 JSON 数组(id、slug、name、description、version 等)。智能体通常会将其与 theo_skill_install 搭配使用。

theo_skill_install

从 Theo 市场安装一个技能。安装完成后,该技能的领域知识与工具会在每次补全时可用(包括之后每一次 theo_complete MCP 调用)。

输入模式

响应示例


theo_status

检查 Theo 的健康状态与引擎可用性。返回引擎状态、延迟以及基础设施健康情况。用于验证连接是否正常,或在 IDE 内部诊断问题。

输入模式

无参数。

响应示例

如果工具返回的结果不是 Status: healthy,请在主机上运行 theo verify 进行排查。

theo_setup_key

一次调用即可创建一个新的 Theo API 密钥,并构建出一个已保存、可见的编排器——无需在画布上手动搭建。可通过三种方式之一指定方案(优先级:graph > routing > use_case):
  • use_case ——单引擎预设。coding 将某个代码引擎固定为确定性的直通后端(适合作为 Warp / Cursor 的即插即用后端);chat 固定为快速引擎;raw 由你自行选择引擎。
  • routing ——按模式绑定引擎。Theo 的分类器会将每个请求划分为某种模式,你可以为每种模式固定一个引擎。
  • graph ——一个完整的自定义编排器图 { enabled, nodes, edges },将按原样应用。
返回原始密钥(只显示一次)以及一个仪表盘链接。编排器会立即启用。

输入模式

智能体调用示例

响应示例(已截断)


theo_configure_key

重新规划一个已有密钥——选项与 theo_setup_key 相同(use_case / routing / graph,优先级相同)。变更会立即反映在仪表盘画布上。返回一个仪表盘链接。

输入模式

智能体调用示例


theo_add_skill

安装一个技能(如需,从市场安装),并将其挂接到某个密钥的允许列表上,使该密钥能够调用它。可选地限定到单一模式。该操作具有幂等性——重复添加同一个(技能, 模式)组合不会产生任何变化。

输入模式

智能体调用示例

如果无法解析出对应的技能,该工具会返回 No skill matches "…",以便智能体调用 theo_skill_list 后重试。

theo_assign_skill_to_node

将一个技能挂接到某个密钥编排器图中的一个或多个模型节点上,使该技能只作用于这些节点。目标节点可通过节点的id、标签、其所处理的模式,或其运行的引擎来匹配——技能会挂接到每一个匹配到的节点上。因此,如果查询中指定的引擎或模式被两个及以上节点共用,则会命中所有这些节点(例如 sonnet 会挂接到运行 anthropic/claude-sonnet-4.6 的每一个节点)。 要求该密钥已经拥有一个图。如果没有任何匹配,该工具会返回可用节点的列表。

输入模式

智能体调用示例


theo_set_guardrail

将一个 Gateway Guardrails 策略绑定到某个密钥。可以传入一个已有策略的名称/id,或一个预设名称(例如 PII-safe、Injection guard),由该模板创建策略并绑定。在拥有编排器图的密钥上,该策略会以一个护栏节点的形式加入画布:
  • input 节点(位于 Entry 之后,或在限定范围时位于分类器之后)负责检查提示词;
  • output 节点(位于模型之后)负责检查回复。
phase(阶段)默认从策略自身的规则阶段(input / output / both)中推断,除非你显式传入 phase。传入 mode(某个模式或引擎名称)可将护栏限定到该分支——它会挂接到所有具有该模式/引擎的节点。对于没有图的密钥,该策略会在密钥级别绑定(按其规则同时检查两个阶段)。remove: true 会清除护栏;附加 phase 可仅移除输入或输出检查点。

输入模式

智能体调用示例


theo_set_routing

将一个 Routing Studio 偏好绑定到某个密钥——可以是一个已有的偏好(按名称/id),也可以直接内联创建规则(pattern 关键词/正则 → mode)。规则默认是累加的:新规则会追加到该密钥当前的路由上(并去重),因此再次请求添加第二条规则时,第一条规则仍会保留。传入 replace: true 可改为重置。对于拥有图的密钥,会插入一个单独的Router 节点(Entry → … → Router → Classifier),使规则真正生效并显示在画布上;如果某条规则的目标模式没有对应的引擎节点,则会触发一条警告。remove: true 会清除路由。

输入模式

智能体调用示例

第二次调用会在第一次的基础上追加:

参考

引擎(配置界面——此处有意展示真实引擎名称):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 服务器会将其格式化为:
智能体会将这段文本视为一个普通的工具结果,而不是 JSON-RPC 错误,因此它可以读取并做出应对,而不是直接放弃。如果你的 IDE 会展示 MCP 服务器日志,完整的结构化错误信息也会在其中可见。 关于最常见的失败情形,请参见故障排查。