Grok MCP — 代理技能參考
使用此檔案來決定該調用哪個工具、該使用哪個模型，以及何時不該調用 Grok。
沒有預設模型 — 你必須在每次呼叫時傳遞 model，並且有意識地選擇它：
選擇能夠完成工作的最便宜模型；只有在品質不足時才升級。
何時使用 Grok MCP 與自行處理
| 任務 | 使用 Grok MCP | 自行處理 |
|---|---|---|
| 使用者明確要求 Grok | ✅ 一律尊重請求 | — |
| 生成或編輯圖片 | ✅ 一律 | ✗ 大多數模型無法生成圖片 |
| 分析本地檔案圖片 | ✅ agent(model=..., image_paths=[...]) | ✗ 需要檔案在磁碟上 |
| 大型程式碼庫分析 (>200K 代幣) | ✅ agent(model=<大型上下文>, tools=["read"]) | ✗ 上下文限制 |
| 比較你的答案與 Grok 的答案 | ✅ 同時呼叫兩者 | ✅ 同時呼叫兩者 |
| 一般文字 / 推理（未提示） | ✗ 不必要的成本 | ✅ 優先選擇 |
| 程式碼生成（未提示） | ✗ 除非你當前的模型不可用 | ✅ 優先選擇 |
預設規則：先自行處理。在以下情況才求助於 Grok：
- 使用者明確要求使用 Grok（例如：「問 Grok」、「使用 Grok」、「用 Grok 生成」）
- 你當前的模型無法完成任務（影像生成、本地檔案視覺、上下文耗盡）
- 使用者要求比較你的答案與 Grok 的答案
選擇模型 — 你的決定，每次呼叫都需做出
所有執行 Grok 模型的工具（agent、附帶問題的 read、shell、search、generate_image*）都需要 model。沒有角色、沒有預設值、沒有 auto 路由器。遺失或未知的模型會立即失敗，並顯示可用的選擇列表。
**選擇的來源：**每個工具的描述都列出了當前的 xAI 目錄 — id、上下文視窗、每 1M 代幣的價格（正常與快取）以及接受圖片輸入的模型的 [images] 標記。該列表是在伺服器啟動時從即時 xAI API 填充的；list_models(refresh=true) 會重新擷取目錄，報告變更的內容，並重新整理工具描述。切勿從記憶體中硬編碼模型名稱或價格 — 請閱讀列表。
**角色標籤。**伺服器根據即時目錄標記模型，而非根據名稱 — 因此以下策略在模型互換時仍然有效：cheapest（最低價格）、flagship（最新世代、最深、最貴）、code（針對程式碼調整）。根據標籤和顯示的價格進行選擇。
預設策略 — 從便宜的開始，只有在有證據時才升級：
- 例行工作（問題、摘要、提取、分類、程式碼編輯、檔案審查） → 使用
cheapest模型，若模型支援則設定reasoning_effort="low"。 - 僅在便宜的執行結果明顯不足，或任務涉及跨多個檔案的深入多步驟分析時，才升級到
flagship。不是為了「保險起見」。 - 長時間或工具密集型執行：使用
tools=["read"]+ 指定檔案、background=True，以及你根據以下估算選擇的明確max_cost_usd— 切勿依賴伺服器預設值。 - 閱讀結果：
cost_usd、stopped和hint。hint表示執行提前結束或在旗艦模型上成本過高 — 遵循提示（在cheapest上重試、縮小任務範圍），而不是重新執行相同的呼叫。
| 需求 | 選擇 |
|---|---|
| 輸入大於約 200K 代幣 | 上下文視窗符合的模型 — 檢查 ctx |
| 圖片輸入 | 標記為 [images] 的模型 |
| 影像生成 | 在最便宜的影像模型上迭代，最終渲染使用高品質模型 |
成本閘門 — 每次 agent() / read / shell / search 呼叫都必須執行
**1. 先估算，並告知。**在呼叫之前，向使用者寫一行：
Estimate: ~<N>K input tokens, ~<R> rounds, <model> → ~$<X>。對於一個很小的單次呼叫（一個簡短問題），一個子句就足夠了（「約 2K 代幣，< $0.01」）。根據工具描述中的價格計算（切勿從記憶體中計算）：
- 單次（無
tools）：input_tokens × in-price + expected_output × out-price（1 個代幣 ≈ 4 個字元；推理代幣按輸出計費）。 - 工具循環：每一輪都會重新發送整個對話，因此成本會隨著輪次增加。使用
rounds × average_context × cached-price加上每一輪的新代幣和輸出。來自此工作階段的過去cost_usd值是最佳的校準依據 — 優先於理論計算。 - 不確定？採用上限：這也將是你傳遞為
max_cost_usd的值。
2. 超過 $2 需要使用者同意。如果估算超過 $2，請勿立即呼叫：顯示估算值、模型以及相較於更便宜執行所能獲得的優勢，並等待明確的同意。同意僅限於該任務，而非後續任務。低於或等於 $2 時，無需詢問即可繼續。
3. 一律傳遞 max_cost_usd：估算值 + 約 30% 的緩衝空間，上限為 $2，除非使用者同意更多（則最多為他們同意的金額）。伺服器的 GROK_MAX_COST_USD（預設為 $2.5）是一個硬性上限，而不是預算：較高的 max_cost_usd 會被上限值限制，因此需要更多成本的執行必須拆分，或者操作員必須提高上限。
**4. 一律報告任務消耗了多少。**在每次完成的呼叫之後 — 包括使用 get_job 收集的背景工作 — 告訴使用者：模型、cost_usd 和代幣數（prompt / cached / completion / reasoning），以及 iterations 和 stopped。即使成本很小也執行此操作，並且在執行失敗或提前結束時也執行此操作。仍在 running 中的工作尚無成本 — 請告知，然後在收集時報告。如果實際成本超過估算約 50% 以上，也請告知。
reasoning_effort（low/medium/high，部分模型也支援 none）是每次呼叫時傳遞給 API 的參數。支援因模型而異（目錄未說明哪些模型支援）：有些會拒絕此參數，其他模型則拒絕 none。當你未設定時，flagship 模型會以 low 執行，而非其自身的（昂貴的）預設值，而任何其他模型則使用其自身的預設值；如果模型拒絕此參數，伺服器會為其捨棄預設值。在深度重要時明確設定它（high）— 明確的值會按原樣發送，而拒絕則會以 API 錯誤的形式返回。
| 任務 | 模型 |
|---|---|
| 快速提問、摘要、提取、分類 | 列表中最便宜的模型 |
| 程式碼生成 / 重構 | 如果列表中有程式碼模型則使用，否則使用便宜的通用模型 |
| 深入分析、多步驟推理、審查多個檔案 | 最新的旗艦模型（最高版本） |
| 輸入大於約 200K 代幣 | 上下文視窗符合的模型 — 檢查 ctx |
| 圖片輸入 | 標記為 [images] 的模型 |
| 影像生成 | 在最便宜的影像模型上迭代，最終渲染使用高品質模型 |
工具 → 模型快速參考
agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)
用於將文字（和圖片）發送給 Grok 的唯一工具。
| 參數 | 預設值 | 備註 |
|---|---|---|
model | 必要 | 請參閱選擇模型 |
tools | [] | Grok 可自行呼叫的工作區工具：read、write、shell、fetch、search。未知名稱 → 立即報錯 |
image_paths | — | 與提示一起發送的本地圖片（模型必須是 [images]）；必須對伺服器可見 — 請參閱路徑 |
max_iterations | 100 | 工具循環中的模型輪次（伺服器上限 — 你只能降低它） |
max_seconds | 1800 | 執行的實際時間預算（伺服器上限） |
max_cost_usd | 2.5 | 執行的估算美元預算（伺服器上限 — 較高的值會被限制） |
conversation | —（無狀態） | 任務名稱 "<project>/<task>"，例如 "grok-mcp/security-audit" — 在同一個任務的多次呼叫之間保持上下文；Grok 按需拉取歷史記錄（get_recent_history/search_history）。新任務 → 新名稱；一次性呼叫 → 省略（不保留歷史記錄；背景工作仍會將其結果保留數天）。專案前綴很重要：透過 HTTP 時，伺服器無法區分專案。≤ 200 個字元，無控制字元 |
file_paths | — | 伺服器端注入的檔案內容（你選擇檔案） |
reasoning_effort | flagship 為 low，否則為模型預設值 | 每次呼叫；明確的值會按原樣發送 |
background | False | 立即返回 {job_id}；使用 get_job(job_id) 收集。長時間執行不需要此設定 — 請參閱限制 |
未知參數會被拒絕，並顯示有效參數的列表。
返回（美觀 JSON）：
{
"answer": "...",
"model": "grok-4.3",
"reasoning_effort": "low",
"tokens": {"prompt": 6909, "cached": 576, "completion": 49, "reasoning": 141},
"cost_usd": 0.0085,
"tool_calls": [{"tool": "read", "args": {"path": "README.md"}, "result_chars": 22463}],
"iterations": 2,
"stopped": "answer",
"hint": "僅在執行提前結束或在旗艦模型上成本過高時出現"
}
stopped 表示循環如何結束：answer（正常）、max_iterations、context（視窗幾乎已滿）、loop（重複相同的工具呼叫）、time（max_seconds）或 cost（max_cost_usd）。在每種情況下，最後一輪都會在沒有工具的情況下執行，因此 answer 始終包含 Grok 根據收集到的資訊所能得出的結論 — 工作永遠不會被丟棄。
限制（伺服器環境變數，預設值）
| 限制 | 預設值 | 環境變數 | 會發生什麼事 |
|---|---|---|---|
| 前台呼叫持續時間 | 60 秒 | GROK_FOREGROUND_TIMEOUT | 呼叫移至後台：你得到 {job_id, status: "running", note} — 使用 get_job 收集。不會遺失任何內容；你永遠不會遇到客戶端超時 |
| 執行持續時間 | 1800 秒 | GROK_JOB_MAX_SECONDS / max_seconds | 最終答案，stopped: "time" |
| 執行成本 | $2.5 | GROK_MAX_COST_USD / max_cost_usd | 最終答案，stopped: "cost" |
| 模型輪次 | 100 | GROK_MAX_ITERATIONS / max_iterations | 最終答案，stopped: "max_iterations" |
| 輸入（提示 + file_paths + 圖片） | 模型視窗的 60% | GROK_INPUT_MAX_RATIO | 在進行任何 API 呼叫之前被拒絕，並列出視窗符合的模型 |
| 一個工具結果 | 視窗的 15% | GROK_TOOL_RESULT_MAX_RATIO | Grok 得到「結果太大 — 請讀取行範圍或使用 grep」 |
| 整個對話 | 視窗的 80% | GROK_CONTEXT_MAX_RATIO | 舊結果被修剪一次，然後新結果被拒絕，接著 stopped: "context" |
| Shell 命令 | 240 秒 | GROK_SHELL_TIMEOUT | 命令被終止，錯誤返回給 Grok |
路徑
使用 Docker 設定時，伺服器只能看到其掛載的目錄（工作區和 ASSETS_DIR）：image_paths、file_paths 以及 Grok 讀取的路徑必須位於這些目錄中 — 主機的 /tmp 或暫存路徑是不可見的；請先將檔案複製到工作區。Stdio 伺服器可以看到其使用者能看到的內容，但受限於 GROK_READ_ALLOWED_PATHS（如果已設定）。伺服器無法看到的路徑會立即被拒絕，並顯示可見根目錄的列表。
**自動專案上下文：**當伺服器在 git 專案（stdio）內執行時，
agent()會將檢測到的語言和框架預置到系統提示中。在 Docker 設定中不會注入任何內容。如果system已以[Project Context]開頭，則跳過注入。
**讓 Grok 自行收集上下文。**不要自己讀取檔案並將其貼到提示中 — 傳遞 tools=["read"]（為 git log/grep/測試執行添加 shell）並描述要查看的內容。檔案內容隨後絕不會進入你的上下文：
agent(prompt="Review src/grok_mcp/tools/agent.py and chat.py for duplicated logic.",
model="<flagship from the list>", tools=["read", "shell"])
**限定讀取範圍。**在提示中指明檔案名稱（或一個狹窄的目錄）— 在整個儲存庫上使用「讀取你需要的任何內容」會導致執行達到 170 萬個代幣。對於大型檔案，告訴 Grok 使用 shell grep -n 定位程式碼，並僅讀取行範圍（使用 offset/limit 的 read）。
當你已經確切知道哪些檔案重要時，請改用 file_paths（一次往返，無需循環）。
**長時間執行與成本。**每一輪都會重新發送整個對話；xAI 會自動快取未更改的前綴（tokens.cached，計費約便宜 75%），因此各輪主要支付新增內容的費用。修剪舊結果會導致一次快取未命中。第三次相同的工具呼叫將被拒絕；第五次會結束循環。長時間的呼叫在 60 秒後會以 {job_id} 的形式返回 — 然後輪詢 get_job；background=True 僅跳過等待的第一分鐘。
圖片。agent(prompt="What does this screenshot show?", model=..., image_paths=["<workspace>/shot.png"]) — 檔案必須位於伺服器可以看到的目錄中（請參閱路徑）。每次呼叫提出一個具體問題；當需要將圖片與程式碼進行比較時，請與 tools 結合使用。
generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)
model 是必要的 — 工具描述列出了影像模型及其每張圖片的價格。
成本準則：
- 使用最便宜的影像模型進行迭代，直到提示正確為止，然後僅在最終渲染時切換到更高品質的模型。
- 返回
{path, model, prompt, format}。
output_path 必須是絕對路徑。父目錄會自動建立。
使用參考圖片（品質層級的模型能更好地轉移風格）：
- 當風格一致性與現有圖片重要時，傳遞
ref_image_paths。它最多接受 3 個絕對路徑，按順序排列 — 提示可以按位置來引用它們，例如*「第一個的幾何形狀，第二個的邊緣角色」*。你傳遞的每個路徑都會被轉發；不會靜默地丟棄任何內容。 - 每個模型的上限（目前影像模型為 3 個）由 xAI 強制執行，如果你超過上限，其訊息會原樣顯示。
- 參考檔案是根據其魔術位元組進行 MIME 偵測的，因此無論先前的結果以何種副檔名儲存，都可以直接作為參考重新輸入。
aspect_ratio（預設"1:1"）和resolution（預設"1k"，也支援"2k"）與無參考時一樣適用。輸出不會繼承參考圖片的比例 — 除非你另有說明，否則 16:10 的參考仍會產生正方形，因此當你需要的不僅僅是 1k 正方形時，請同時明確傳遞這兩者。
成本比較：你當前的模型 vs. Grok
有關你目前模型的精確價格，請查閱你的提供者當前...