@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。權限範圍繼承。 配置類工具會繼承 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 引擎,以獲得業界領先的代碼生成能力,並配有更大的輸出預算。返回生成的代碼及任何附件(完整文件、項目腳手架)。適用於以編寫、生成或搭建代碼為主的任務。
輸入模式
智能體調用示例
Artifacts: 區塊。
theo_research
針對某個主題運行深度研究。Theo 會規劃 3–6 條聚焦的搜索查詢、並行執行、去重來源,並綜合出一份帶引用的結構化報告。這是一個異步操作——MCP 服務器會持續輪詢,直到底層任務完成(默認預算:120 秒,輪詢間隔 3 秒),然後返回最終報告。
輸入模式
智能體調用示例
失敗處理
如果研究任務失敗或超時,該工具會返回一段以Research failed: 開頭的純文本,便於智能體判斷是否要用更窄的提示詞重試。
theo_image
使用 Theo 生成圖像。請求會被路由到 Theo Create 引擎,並具備自動的服務商回退能力。返回圖像 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 節點(位於模型之後)負責檢查回覆。
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。若不匹配,該工具會列出所有可用的策略和預設。
