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 服務器日誌,完整的結構化錯誤信息也會在其中可見。 關於最常見的失敗情形,請參見故障排查。