内容
# Grok 构建桥
[](https://github.com/Reederey87/grok-build-codex-plugin/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
一个 Codex CLI 插件，允许您将 OpenAI Codex 会话中的代码审查和有界编码任务委托给本地、订阅认证的 Grok Build CLI（xAI）。它附带一个捆绑的 stdio MCP 服务器，包装了本地的 `grok` 二进制文件，以及一个技能，告诉 Codex 何时调用它。Grok 是一个明确的第二意见/审查/任务通道 - 而不是 Codex 自己工作的模型交换。
```
Codex 会话 → grok-build-delegate 技能路由 → MCP 工具 → 本地 `grok` CLI → 结果返回 Codex 审批
```
## 要求
- Node.js >= 18.18
- Grok Build CLI，已安装并登录：
```
curl -fsSL https://x.ai/cli/install.sh | bash
grok login
```
- 具有插件支持的 OpenAI Codex CLI。
## 安装（本地开发）
```
npm install
codex plugin marketplace add /path/to/grok-build-codex-plugin
codex plugin add grok-build@grok-build-dev
node scripts/install-codex-config.mjs
```
存储库根目录兼作市场（`.agents/plugins/marketplace.json`）。在添加之前运行 `npm install` - MCP 服务器在运行时需要 `@modelcontextprotocol/sdk`，并且插件已缓存其 `node_modules`。`codex plugin add` 仍然需要注册 `grok-build-delegate` 技能。
最后一步，`node scripts/install-codex-config.mjs`，安装 MCP 服务器本身。在 codex-cli 0.144.1 上，`${PLUGIN_ROOT}` 在 `.mcp.json` 中**不**解析，当 Codex 的会话 cwd 在此检出之外时 ([openai/codex#22842](https://github.com/openai/codex/issues/22842))，因此仅依赖 `.mcp.json` 会使服务器无法从其他存储库访问。安装程序在 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）中写入绝对路径 `[mcp_servers.grok-build]` 条目 - 无论会话 cwd 如何，都可靠。`.mcp.json` 保留在存储库中，以防上游修复解析。运行 `node scripts/install-codex-config.mjs --remove` 以卸载；有关完整标志参考，请参见 [`dev/README.md`](dev/README.md)。
Codex 有时会使用最小的 PATH 启动插件 MCP 服务器（例如 GUI/launchd 上下文），其中找不到裸 `node` 命令。已安装的配置通过捆绑的启动器（`mcp-server/bin/grok-build-mcp`）运行服务器，该启动器在常见安装位置自行定位 node；设置 `GROK_BUILD_NODE=/path/to/node` 以强制使用特定二进制文件。
## 工具
MCP 服务器公开七种工具。每个工具都需要一个 `cwd`（目标存储库的绝对路径）。
| 工具 | 用途 |
| --- | --- |
| `grok_build_setup` | 检查 CLI/模型发现、身份验证、有界探测、可选的单一/全部模型烟雾就绪、回退和状态存储。 |
| `grok_build_prompt` | 在工作区中运行前景、严格只读的 Grok 提示。 |
| `grok_build_review` | 通过本地 CLI 将路径过滤、内容编辑的 Git 上下文发送到 xAI 进行只读审查。 |
| `grok_build_task` | 运行或排队有界 Grok 任务，可选地带有门控工作区写入。 |
| `grok_build_status` | 列出存储库的活动或所有存储的作业，具有进程存活率。 |
| `grok_build_result` | 返回已完成作业的存储结果和证据。 |
| `grok_build_cancel` | 取消活动作业、终止其进程树并释放其写入锁。 |
`grok_build_task` 默认在前台运行；传递 `background: true` 进行长时间运行，然后轮询 `grok_build_status` 并在作业完成时读取 `grok_build_result`。
`grok_build_review` 将存储库上下文发送到外部 xAI 服务。使用 `preview_only: true` 检查路径过滤的文件列表、字节数、减少数和覆盖率元数据，而不运行推理。执行需要 `external_disclosure_acknowledged: true`。敏感路径名被省略，包含文本的高置信度凭证根据最佳努力被编辑；只读 Grok 调用仅公开内置的 `Read`、`Grep` 和 `Glob` 工具，使用 Grok 的 `strict` 沙盒，不公开 Bash。传递 `model` 以选择审查模型和 `timeout_ms`（最大一小时）以限定审查。差异审查从私有净化快照运行，而不是原始检出。审查输入和不可恢复的 Grok 会话在调用后立即删除；七天修剪作为崩溃恢复保留。
默认情况下，设置通过不运行推理执行模型发现。设置 `run_smoke_test: true` 以测试选定的/默认模型，或传递 `smoke_models: "all"`（或最多八个明确的模型名称）以获取每个模型的 `model_results`。`check_model` 选择准备就绪目标，但不运行推理。
## 配置
MCP 服务器读取的环境变量：
| 变量 | 用途 |
| --- | --- |
| `GROK_BUILD_DEFAULT_MODEL` | 传递给 CLI 的默认 Grok 模型。未设置则使用 Grok 自己的默认值。 |
| `GROK_BUILD_PLUGIN_DATA` | 作业状态和审查输入的目录。覆盖私有每用户状态目录。 |
| `GROK_BUILD_API_FALLBACK` | `true` 以全局允许只读 xAI API 回退。默认为 `false`。 |
| `GROK_BUILD_ALLOW_WRITE` | `true` 以允许写入模式任务。默认为关闭。 |
| `GROK_BUILD_ALLOW_ALWAYS_APPROVE` | `true` 以允许明确请求的不受监督的写入。默认为关闭。 |
| `XAI_API_KEY` | xAI API 密钥。API 回退所需。 |
| `GROK_BUILD_XAI_BASE_URL` | xAI API 基本 URL。默认为 `https://api.x.ai/v1`。 |
| `GROK_BUILD_TRUST_CUSTOM_XAI_BASE_URL` | `true` 以允许将回退的持有者令牌发送到非 xAI HTTPS 主机。本地测试保留循环 HTTP。 |
| `GROK_BUILD_XAI_TIMEOUT_MS` | xAI API 请求超时，毫秒。默认为 `120000`。 |
| `GROK_BUILD_NODE` | 绝对路径到节点二进制文件，供捆绑的启动器使用，绕过其自己的 PATH 搜索。 |
Codex 自己的沙盒和批准策略控制应用 Grok 提出的任何补丁。一个 `~/.codex/config.toml` 的工具审批片段在 [`dev/config-snippet.toml`](dev/config-snippet.toml) 中 - 它将 `grok_build_review` 设置为 `approve`，并在 `prompt` 上保留具有写入能力的 `grok_build_task`。
默认情况下，状态存储在 `$XDG_STATE_HOME/grok-build-mcp`、macOS 应用程序支持、 `%LOCALAPPDATA%` 或 `~/.local/state/grok-build-mcp` 下，具体取决于平台。状态目录使用模式 `0700`，提示/结果/日志文件在 POSIX 模式适用时使用 `0600`。来自前临时位置的作业在未配置明确的数据目录时保持可读以兼容。当未配置明确的数据目录时，保持来自前临时位置的作业可读以兼容。`grok_build_status` 返回编辑后的操作元数据；使用 `grok_build_result` 检索已完成作业的完整结果和证据。当前状态目录中已完成作业记录和日志保留 30 天，并在准备新作业时修剪；状态和结果读取永远不会删除状态。活动作业和旧版兼容性记录不会被修剪。后台工作线程维护短所有权租约；当确认所有记录的进程都消失后，陈旧作业变为 `orphaned`。具有活动进程的陈旧租约保留其写入锁，必须取消，避免重叠的写入者并发出已经重用的死 PID 信号。
## API 回退
默认情况下，所有工作都通过本地的 `grok` CLI 运行。只读 xAI API 回退仅在以下所有条件成立时触发：
- 它被明确允许 - 调用时 `allow_api_fallback: true` 或 `GROK_BUILD_API_FALLBACK=true`；
- 设置了 `XAI_API_KEY`；
- 本地 `grok` CLI 丢失或未经身份验证；并且
- 请求是只读的。
回退结果标记为 `source: "xai_api_fallback"`。请求设置 `store: false`，并且回退从不用于写入模式任务 - 它使用您的 xAI API 积分，因此它仍然是一个明确的只读选择。默认端点是 `https://api.x.ai/v1/responses`。自定义远程 HTTPS 主机还需要 `GROK_BUILD_TRUST_CUSTOM_XAI_BASE_URL=true`；URL 凭证、查询字符串、片段和非循环 HTTP 端点被拒绝。
## 写入模式
写入模式在 v1 中被禁用，默认情况下关闭。必须满足两个门控：
1. 服务器环境具有 `GROK_BUILD_ALLOW_WRITE=true`，并且
2. 调用在 `grok_build_task` 上设置 `write: true`。
`always_approve: true` 请求从不被暗示，并且还需要 `GROK_BUILD_ALLOW_ALWAYS_APPROVE=true`。写入执行仍然在精选的能力集中：桥使用 `dontAsk`，因此已批准的读取/编辑/测试/构建操作已经在无人监督的情况下运行，而不转发 Grok 的全局 `--always-approve` 标志。每个写入作业在运行前后捕获 `git status` 和受保护路径的哈希值。受保护路径的更改会使任务失败，但为审查而保留，而不是自动恢复。应用任何进一步的操作仍然通过 Codex 的正常编辑/批准流程。
委托调用禁用 Grok 内存、子代理和网络搜索。只读调用删除 Bash，仅公开 `Read`、`Grep` 和 `Glob`。写入调用使用 `strict` 沙盒加上 `dontAsk`，公开存储库读取/写入工具，并仅允许项目的测试/构建命令和狭窄的只读 Git 元数据命令。敏感路径和 shell 读取器的拒绝仍然有效。本地 Grok 指令、配置和钩子仍然属于调用者的受信任本地环境。
模型 ID 永远不会被静默别名。显式或环境选择的本地模型必须出现在 `grok models` 中；当未选择模型时，使用 CLI 报告的默认值。
取消首先将作业移动到 `cancelling`，终止记录的 Grok 和工作进程树，等待确认退出，然后仅记录 `cancelled` 并释放写入锁。失败的终止仍然可重试，并保留锁，而不是允许另一个写入者重叠活动进程。
参见 [USAGE.md](USAGE.md) 以获取有关将哪些内容委托给 Grok 而不是保留在 Codex 中的简明标准。
## 社区和安全
- [贡献](CONTRIBUTING.md)
- [支持](SUPPORT.md)
- [安全策略](SECURITY.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [Apache 2.0 许可证](LICENSE)
该项目目前处于 1.0 之前。公共接口和配置可能仍在演变，变更记录在 [CHANGELOG.md](CHANGELOG.md) 中。
## 尝试
启用插件后，询问 Codex：
- “使用 Grok Build 为此存储库运行其设置诊断。”
- “使用 Grok Build 解释此存储库的作用（只读）。”
- “使用 Grok Build 审查我的工作树。”
- “要求 Grok Build 对此分支与 `main` 进行对抗性审查。”
## 开发
```
npm test # node --test over tests/*.test.mjs
npm run build # tsc type-check (JSDoc types, no emit)
```
在不使用 Codex 的情况下驱动工具，使用开发运行器或服务器自测试：
```
node mcp-server/src/dev-runner.mjs setup --cwd "$PWD"
node mcp-server/src/server.mjs --self-test
```
`npm run bump-version` / `npm run check-version` 管理耦合的版本字符串。
## 状态
Grok Build CLI 处于早期测试阶段 - 其标志和 JSON 输出可能会更改。输出解析故意宽容，作业成功从 Grok 的 `stopReason`（`EndTurn` = 干净）读取，而不是退出代码。预计会有粗糙的边缘。
## 许可证
Apache-2.0
