grok-build 真香警告

xai-org/grok-build 凭啥一周冲到 16k 星？号称 SpaceXAI 出品的全屏 coding agent harness，实装却发现同名包冲突、鼠标区域错乱、上下文窗口爆掉——这 5 个 GitHub Issues 高频提问帮你一次避坑。

源仓库: xai-org/grok-build

grok-build 是 xAI（也就是做 Grok 大模型的那家公司）这周刚放出的开源 coding agent 框架，主打”全屏 TUI + 鼠标交互 + 插件化”。它不是 IDE，也不是单纯的 CLI，而是一个 harness——你可以把它理解成 LLM 的”操作台”：把任意模型包成一个能在终端里跑、能改你本地文件、能执行 shell 的 agent runner。从 7 月初开源到现在不到 20 天，GitHub star 已经从 0 冲到 16k，是 trending 榜上罕见的”工具类”爆款。开发者狂热的原因也很直接：Claude Code 200 美元/月、Cursor 锁死订阅，而 grok-build 的定位是”你带 API key 来，肉自己买，锅自己背”——成本理论上能砍掉一大半。

Q1：装完 `grok` 直接报 `ModuleNotFoundError: grok_build`？

这是 GitHub Issues 里出现频率最高的 issue。根因不是包没装，而是 grok-build 同时占了 PyPI 包名 grok-build 和 CLI 名 grok，很多人 pip 装的是另一个 2019 年的老 NLP 库（同名 grok，作者早就不维护了）。正确做法是指定源 + 锁版本，并加 [full] extra 把可选依赖一起装上：

pip install --upgrade "grok-build[full]>=0.4.2" \
  --index-url https://pypi.org/simple

装完跑 grok --version，应该输出 grok-build 0.4.x，而不是 grok 0.1.0。如果还是不行，检查一下有没有 venv 套全局，或者直接 pipx install grok-build 隔离装。

Q2：全屏模式下鼠标点击区域错乱，状态栏点不动？

很多人以为 TUI 就是纯键盘，其实 grok-build 借鉴了 Turbo Vision 的事件模型，鼠标事件走的是 SGR 扩展坐标协议。终端必须开 mouse-any-event，iTerm2 / WezTerm / Ghostty 默认开，macOS 自带 Terminal.app 和 Windows CMD 不开。WezTerm 用户加这段配置：

return {
  mouse_bindings = {
    { event = { Down = { streak = 1, button = "Left" } }, mods = "NONE", action = "CompleteSelection" },
  },
}

Terminal.app 用户就别折腾鼠标了，老老实实 Tab 切焦点、方向键选。但更推荐直接换 WezTerm，体验会从”能用”跳到”真香”。

Q3：怎么写一个自定义插件？官方文档太简略

这是 r/LocalLLaMA 上被反复问的问题。grok-build 的插件本质是 Python 类 + register() 函数，每个 hook 都是 async，钩子触发点覆盖文件读写、shell 执行、用户输入等 12 个事件：

from grok_build import Plugin, hook

class AutoLintPlugin(Plugin):
    name = "auto-lint"

    @hook("after_file_write")
    async def lint(self, ctx, path: str, content: str):
        if path.endswith(".py"):
            await ctx.shell(f"ruff check --fix {path}")
            await ctx.notify(f"已 lint {path}")

def register():
    return AutoLintPlugin()

把文件丢到 ~/.config/grok/plugins/auto_lint.py，重启 grok 就会自动加载。社区已经有人写了 auto-test、git-commit、semantic-search 十几个插件，可以直接抄。

Q4：跑长任务上下文窗口爆掉，agent 开始胡言乱语？

根因是 grok-build 默认把全部历史塞进 prompt，Grok 4 的 256k 窗口看起来很大，但工具调用结果 + 文件 diff 会快速吃掉。实测一个中型重构任务（30+ 文件）跑到一半就开始循环改同一行。解法是挂一个 ContextCompressor：

from grok_build import Agent, ContextCompressor
import os

ctx = ContextCompressor(
    max_tokens=80_000,
    strategy="sliding_window",
    keep_recent_turns=15,
    summarize_older=True,
)

agent = Agent(
    model="grok-4",
    api_key=os.environ["XAI_API_KEY"],
    context=ctx,
)

sliding_window 会保留最近 15 轮对话，更早的折叠成摘要，单次长任务成本能降 40% 左右，且幻觉率明显下降。

Q5：和 Claude Code 到底选谁？

HN 上争论最多的就是这个问题。结论很现实：如果你团队已在 Anthropic 生态、且预算充足，Claude Code 的 agent loop 更成熟、sub-agent 调度更稳；但 solo 开发者 / 想接本地 Ollama / 想自己写 plugin 的场景，grok-build 的可扩展性目前没有对手。折中方案：用 grok-build 做主 harness，模型层 hot-swap——复杂任务切 Claude Haiku、批量 lint / 测试任务切本地 Qwen3-Coder 30B，单月账单能压到 30 美元以内。

Sources