Grok MCP — 智能体技能参考
使用此文件来决定调用哪个工具、使用哪个模型，以及何时不调用 Grok。
没有默认模型——你在每次调用时都要传递 model，并有意地选择它：
选择能胜任工作的最便宜模型；仅当质量不足时才升级。
何时使用 Grok MCP 与自己完成
| 任务 | 使用 Grok MCP | 自己完成 |
|---|---|---|
| 用户明确要求使用 Grok | ✅ 始终遵循请求 | — |
| 生成或编辑图像 | ✅ 始终 | ✗ 大多数模型无法生成图像 |
| 分析本地文件图像 | ✅ agent(model=..., image_paths=[...]) | ✗ 需要磁盘上的文件 |
| 大型代码库分析（超过 20 万 token） | ✅ agent(model=<large-context>, tools=["read"]) | ✗ 上下文限制 |
| 比较你的回答与 Grok 的回答 | ✅ 调用两者 | ✅ 调用两者 |
| 通用文本/推理（未提示） | ✗ 不必要的成本 | ✅ 优先 |
| 代码生成（未提示） | ✗ 除非你当前模型不可用 | ✅ 优先 |
默认规则：自己先做。仅在以下情况才使用 Grok：
- 用户明确要求使用 Grok（例如“问 Grok”、“用 Grok”、“用 Grok 生成”）
- 你当前的模型无法完成任务（图像生成、本地文件视觉、上下文耗尽）
- 用户要求比较你的回答与 Grok 的回答
选择模型——每次调用由你决定
每个运行 Grok 模型的工具（agent、带问题的 read、shell、search、
generate_image*）都需要 model。没有角色、没有默认值、没有 auto 路由器。
缺失或未知的模型会直接失败并返回有效选项列表。
**选项来源：**每个工具的描述都列出了当前的 xAI 目录——
ID、上下文窗口、每 100 万 token 的价格（正常和缓存）以及接受图像输入的模型的 [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上重试，缩小任务范围），而不是 重新运行相同的调用。
| 需求 | 选择 |
|---|---|
| 输入超过约 20 万 token | 上下文窗口能容纳的模型——检查 ctx |
| 图像输入 | 标记为 [images] 的模型 |
| 图像生成 | 在最便宜的图像模型上迭代，最终在高质量模型上渲染 |
成本门控——每个 agent() / read / shell / search 调用都必须执行
1. 首先估算并告知用户。 在调用前，向用户写一行：
估算：~<N>K 输入 token，~<R> 轮次，<model> → ~$<X>。对于微小的
单次调用（一个简短问题），一个子句就足够了（“约 2K token，<$0.01”）。根据工具描述中的价格计算（切勿凭记忆）：
- 单次（无
tools）：输入_token × 输入价格 + 预期输出 × 输出价格（1 token ≈ 4 个字符；推理 token 按输出计费）。 - 工具循环：每轮都会重新发送整个对话，因此成本随轮次增加。使用
轮次 × 平均上下文 × 缓存价格加上每轮的新 token 和输出。 本次会话中的历史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 和 token（prompt / cached / completion / reasoning），
以及 iterations 和 stopped。即使成本很小也要这样做，
当运行失败或提前停止时也要报告。仍在 running 的作业尚无成本——
也要说明，然后在收集时报告。如果实际成本超过估算值超过约 50%，也要说明。
reasoning_effort（low/medium/high，某些模型也支持 none）是按调用传递的，并传递给
API。不同模型支持程度不同（目录未说明哪些模型支持）：某些模型拒绝它，其他模型
拒绝 none。当你未设置它时，flagship 模型以 low 运行，而不是其自身的（昂贵的）
默认值，任何其他模型使用其自身默认值；如果模型拒绝该参数，服务器会为其删除默认值。
当深度至关重要时，显式设置它（high）——显式值始终按原样发送，
如果被拒绝，则作为 API 错误返回。
| 任务 | 模型 |
|---|---|
| 快速提问、摘要、提取、分类 | 列表中最便宜的模型 |
| 代码生成/重构 | 如果列出则使用代码模型，否则使用便宜的通用模型 |
| 深度分析、多步推理、审查多个文件 | 最新的旗舰模型（最高版本） |
| 输入超过约 20 万 token | 上下文窗口能容纳的模型——检查 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 | —（无状态） | 任务名称 "<项目>/<任务>"，例如 "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 + images） | 模型窗口的 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"]（添加 shell 用于 git log/grep/测试运行）并描述要查看的内容。
这样文件内容永远不会进入你的上下文：
agent(prompt="审查 src/grok_mcp/tools/agent.py 和 chat.py 中的重复逻辑。",
model="<来自列表的旗舰模型>", tools=["read", "shell"])
限制读取范围。 在提示词中指定文件名（或狭窄的目录）——"读取你需要的任何内容"
对于整个仓库而言，运行可能会达到 170 万 token。对于大文件，告诉 Grok 使用 shell grep -n 定位代码并仅读取行范围（使用 offset/limit 的 read）。
当你已经确切知道哪些文件重要时（一次往返，无需循环），请改用 file_paths。
长时间运行和成本。 每轮都会重新发送整个对话；xAI 会自动缓存未更改的前缀
（tokens.cached，计费约便宜 75%），因此轮次主要支付新内容的成本。
修剪旧结果会导致一次缓存未命中。第三次相同的工具调用会被拒绝；第五次会结束循环。
长时间的调用会在 60 秒后返回 {job_id}——然后轮询 get_job；
background=True 仅跳过等待的第一分钟。
图像。 agent(prompt="此截图显示什么？", 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
有关你当前模型的确切价格，请查看你的提供商当前的费率。