grok-keysmith：Grok Build 全局规则一键部署工具，先预览再写入还能随时撤销

摘要

想给 Grok Build 配一套全局生效的自定义指令，又担心改坏配置、装完卸不掉？grok-keysmith 就是为解决这个痛点而生的开源工具。它把一份 Markdown 契约安全地部署为 Grok 的全局 home rules，全程遵循先预览、再写入、可撤销的原则，让 AI 工具的指令管理变得可控、可回滚。作为一款专注 Grok Build 全局规则部...

想给 Grok Build 配一套全局生效的自定义指令，又担心改坏配置、装完卸不掉？grok-keysmith 就是为解决这个痛点而生的开源工具。它把一份 Markdown 契约安全地部署为 Grok 的全局 home rules，全程遵循"先预览、再写入、可撤销"的原则，让 AI 工具的指令管理变得可控、可回滚。

作为一款专注 Grok Build 全局规则部署 的命令行工具，grok-keysmith 基于 Python 3.8+ 开发，采用 MIT 协议开源，支持 macOS、Linux、Windows 三大平台。本文将详细介绍它的功能特性、部署教程与适用场景，帮助你快速上手这款 AI 自定义指令管理工具。

grok-keysmith 部署预览界面

grok-keysmith 是什么

grok-keysmith 是 Keysmith 系列工具中的一员，这个系列的定位很清晰：为本地 AI 工具安全地部署、验证和撤销自定义指令。具体到 grok-keysmith，它做的事情是把一份 Markdown 文件部署为 ~/.grok/rules/99-keysmith.md，让之后开启的每一个新 Grok 会话都自动加载这套规则，同时不会改动 ~/.grok/AGENTS.md。

需要注意的是，这套规则属于全局 home rules，没有项目级隔离。部署过程中工具会写入规则文件、向 config.toml 注入带标记的 compat 隔离块，并把 ~/.grok/hooks/ 目录下的 JSON 文件整体改名为 .disabled。正因为改动涉及全局配置，grok-keysmith 把"默认只预览、显式确认才写入"做成了硬性设计——不带 --yes 参数时，所有命令都只是演示计划，不会真正落盘。

Keysmith 系列针对不同 AI 工具各有分工，选型时可以参考下表：

项目	目标工具	部署面	稳妥安装	Desktop
codex-keysmith	Codex	全局 `~/.codex` 指令	稳定 CLI Release	未签名 Beta
claude-keysmith	Claude Code	项目 / 用户 CLAUDE.md import	源码 CLI	未签名 Beta
grok-keysmith	Grok Build	全局 `~/.grok/rules`（不改 AGENTS.md）	稳定 CLI Release	未签名 Beta
zcode-keysmith	ZCode App	用户目录 system-role + wrapper	仅源码	无

核心功能：部署、验证、撤销一体化

grok-keysmith 的功能设计围绕一条完整的安全闭环展开：

部署前预览：--dry-run 展示完整的目标路径、提示词内容和 isolation 计划，确认无误后再用 --yes 实际写入；
状态检查：--status 随时查看当前部署状态，版本、目标目录一目了然；
配置修复：--reconcile 在 compat 值仍对齐时重建配置标记，处理 drift 或中断事务；
hooks 恢复：--restore-hooks 把被禁用的 hooks 目录恢复原状；
完整卸载：--uninstall 依据 manifest 记录的本层所有权，把部署过的内容干净地撤掉。

工具在写入 ~/.grok/.grok-keysmith-manifest.json 时会记录每一处改动的归属，这正是卸载能够精确回滚的基础。对文件的具体影响如下：

路径	会发生什么
`~/.grok/rules/99-keysmith.md`	新建，或先备份再替换
`~/.grok/config.toml`	注入带标记的 `[compat.*]` 隔离块
`~/.grok/hooks/*.json`	整目录改名为 `.json.disabled`
`~/.grok/.grok-keysmith-manifest.json`	记录本层所有权，供卸载使用

grok-keysmith 部署流程示意图

技术优势：可测量的契约交付质量

和许多"装上就完事"的部署脚本不同，grok-keysmith 把效果验证做成了工程化的一部分。项目内置了一个 11 单元的 hard-probe 测试银行，覆盖 kernel-LPE（3 组）、boundary（2 组）、malware（2 组）、social（1 组）和 CRED canaries（3 组），每个单元运行 2 次，用来统计契约的完整交付数。

从 v0.5.1 到 v0.5.2 再到 v0.6.0，契约完整交付趋势持续向好。测量方法、门禁标准和逐单元数据都公开在 CHANGELOG.md 与 breaktest/ 目录中。需要说明的是，服务端行为会随时间漂移，跨日期对比时应以同日基线为准。

契约完整交付趋势统计

其他值得关注的技术细节：

跨平台 CI 覆盖：CLI 在 macOS / Linux / Windows 上均有持续集成测试，Windows 平台的 override / ab 功能需要原生 grok.exe；
版本可追溯：版本号、发布资产和签名信息以 GitHub Releases 为准，v0.6.0 提供 --json、--grok-dir、run、breaktest 与 --reconcile 等完整能力；
事务可恢复：drift 检测、中断事务恢复、旧版 AGENTS.md 部署的卸载方案，在 docs/reference.md 中都有完整说明。

grok-keysmith 安装与部署教程

安装有三种方式，按稳妥程度排序：

稳妥方案：稳定 CLI。 使用最新稳定 Release（当前 v0.6.0）的完整 ZIP / Tarball，或 checkout 同一 tag。注意 run 与 breaktest 依赖同目录模块，不要只下载单个 grok-keysmith.py，也不要从浮动的 main 分支安装。

更易用：未签名 Desktop Beta。 当前公开版为 desktop-v0.1.0-beta.4，内嵌稳定版 CLI sidecar。它是公开的 GitHub Pre-release（并非稳定 Latest），无开发者签名、无自动更新、无 Linux GUI，仅支持 macOS Apple Silicon 与 Windows x64。

交给智能体安装。 复制 docs/agent-install.md 里的指令模板，让 Codex、Claude Code 或任何执行型智能体替你完成校验与部署。

方式一：Release ZIP（推荐）

curl -LO https://github.com/Jia-Ethan/grok-keysmith/releases/download/v0.6.0/grok-keysmith-v0.6.0.zip
curl -LO https://github.com/Jia-Ethan/grok-keysmith/releases/download/v0.6.0/SHA256SUMS
grep ' grok-keysmith-v0.6.0.zip$' SHA256SUMS | shasum -a 256 -c -
unzip grok-keysmith-v0.6.0.zip
cd grok-keysmith-v0.6.0
python3 grok-keysmith.py --version
python3 grok-keysmith.py --status
python3 grok-keysmith.py --dry-run
# 确认 ~/.grok 目标、提示词和 isolation 计划后：
python3 grok-keysmith.py --yes

方式二：固定 tag 源码

git clone --branch v0.6.0 --depth 1 https://github.com/Jia-Ethan/grok-keysmith.git
cd grok-keysmith
python3 grok-keysmith.py --version
python3 grok-keysmith.py --status
python3 grok-keysmith.py --dry-run
# 确认 ~/.grok 目标、提示词和 isolation 计划后：
python3 grok-keysmith.py --yes

本机需要先存在 ~/.grok 目录（至少运行过一次 Grok）。部署完成后，建议在项目目录之外开启一个新会话验证规则是否生效。

撤销与恢复命令

如果后续想调整或移除部署，grok-keysmith 提供了完整的逆操作命令，同样遵循"先预览、再执行"的模式：

python3 grok-keysmith.py --reconcile            # 预览：compat 值仍对齐时重建 marker
python3 grok-keysmith.py --reconcile --yes      # 实际修复配置标记
python3 grok-keysmith.py --restore-hooks        # 预览 hooks 恢复计划
python3 grok-keysmith.py --restore-hooks --yes  # 实际恢复 hooks
python3 grok-keysmith.py --uninstall            # 预览完整卸载
python3 grok-keysmith.py --uninstall --yes      # 实际执行完整卸载

项目结构一览

grok-keysmith/
├── grok-keysmith.py              # 部署 CLI：preview / apply / uninstall
├── grok_keysmith_runner.py       # run 子命令：多轮 Grok 会话驱动
├── grok_keysmith_breaktest.py    # breaktest：拒答银行回归
├── examples/grok-unrestricted.md # 内置契约源文件（byte-for-byte）
├── breaktest/                    # 测量银行与结果（variants/results 不入库）
├── docs/reference.md             # 完整命令参考与内部机制
├── docs/agent-install.md         # 智能体安装指令模板
├── docs/assets/readme/           # README 图示（明/暗双版本）
└── gui/                          # Desktop Beta（Electron，未签名）

适用场景

grok-keysmith 适合以下几类用户：

重度 Grok Build 用户：希望所有新会话统一加载一套自定义规则，免去逐个项目重复配置；
AI 工具链玩家：已经在用 Codex、Claude Code 等多款工具，可以搭配 Keysmith 系列其他成员统一管理各平台的指令部署；
安全敏感型开发者：对"AI 工具改了我的配置"心存顾虑，需要每一步改动都可预览、可审计、可回滚；
智能体工作流用户：习惯让执行型智能体代劳安装配置，agent-install 模板正好对口。

总结

在 AI 编程助手的自定义指令管理这件事上，grok-keysmith 给出了一套难得的工程化答案：部署前强制预览、写入过程留痕、卸载精确回滚，还配套了可量化的契约交付测试。如果你正在寻找一款靠谱的 Grok Build 全局规则部署工具，它值得放进你的工具箱。

项目地址：https://github.com/Jia-Ethan/grok-keysmith
稳定版本：v0.6.0（Release ZIP / Tarball）
官方反馈：GitHub Discussions；社区交流：LINUX DO

同系列工具：codex-keysmith（Codex 全局指令）、claude-keysmith（Claude Code 可卸载 import block）、zcode-keysmith（ZCode App system-role 入口，仅源码）。