简体中文

Keysmith 系列为本地 AI 工具安全部署、验证和撤销自定义指令。claude-keysmith 把一份 Markdown 存进 keysmith 目录，并在 CLAUDE.md / CLAUDE.local.md 插入可识别、可卸载的 import block。

[!WARNING] 项目 / local scope 只影响该仓库；user scope 会影响加载 ~/.claude/CLAUDE.md 的新会话。--runtime 还会对齐 settings.json 的 systemPrompt，并安装 managed shell wrapper。默认只预览，显式 --yes 才写入。先阅读 examples/claude-project-rules.md、examples/claude-append-prompt.md 和 docs/privacy-security.md。

选择哪个 Keysmith

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

安装方式

稳妥：稳定 v7.1 源码 CLI。 没有独立 CLI 安装包；按下方命令固定 clone v7.1 tag，再运行 claude-instruct.py。不要 curl | python。
更易用：未签名 Desktop Beta。 见 desktop-v0.1.0-beta.2：macOS Apple Silicon DMG 与 Windows x64 NSIS，内嵌 v7.1 CLI。无 Linux GUI、无自动更新、无签名。步骤见 docs/platform-support.md。

快速开始（稳定 v7.1）

git clone --branch v7.1 --depth 1 https://github.com/Jia-Ethan/claude-keysmith.git
cd claude-keysmith
python3 claude-instruct.py --version  # claude-keysmith v7.1
python3 claude-instruct.py install --scope project --project-dir /path/to/repo
python3 claude-instruct.py install --scope project --project-dir /path/to/repo --yes
python3 claude-instruct.py status --scope project --project-dir /path/to/repo

可选 user-scope runtime：先 install --scope user --runtime 预览，再加 --yes。macOS / Linux 随后 source ~/.zshrc；Windows PowerShell 用 python .\\claude-instruct.py 并 . $PROFILE。

会修改什么

路径	会发生什么
`CLAUDE.md` 或 `CLAUDE.local.md`	插入或替换同名 managed import block
相邻 `keysmith/<name>.md`	新建，或先备份再替换
`~/.claude/settings.json`、shell profile	仅 `--runtime`：对齐 `systemPrompt` 并写入 managed wrapper

不修改 Claude 二进制、MCP、hooks、permissions 或凭证。完整表见 docs/reference.md。

如何撤销

# 项目级卸载先预览，确认后加 --yes
python3 claude-instruct.py uninstall --scope project --project-dir /path/to/repo
python3 claude-instruct.py uninstall --scope user --runtime --yes
python3 claude-instruct.py restore --target PATH --backup PATH --yes

v7.1 提供备份枚举和中断事务恢复：

python3 claude-instruct.py backups --scope user --json
python3 claude-instruct.py recover --scope user
python3 claude-instruct.py recover --scope user --yes

uninstall --runtime 不自动回滚 settings.json 的 systemPrompt；可对已知的安装前备份执行 restore。写操作中断时，先用 recover 预览，再加 --yes。

平台与 Beta 限制

CLI：Python 3.8+；wrapper 支持 macOS / Linux zsh 与 Windows PowerShell 5.1 / 7。CMD、Git Bash 不在正式范围。
Desktop：仅 macOS Apple Silicon 与 Windows x64；未签名，可能触发 Gatekeeper / SmartScreen。
版本与产物以 Releases 和 docs/platform-support.md 为准。

进阶文档

Runtime wrapper / settings：docs/reference.md
Journal、锁、恢复：docs/transaction-recovery.md
JSON 契约：docs/json-contract.md
Desktop / 智能体安装：docs/desktop-gui.md · docs/agent-install.md

贡献、安全与系列

python3 -m py_compile claude-instruct.py
python3 -m pytest tests

安全边界见 docs/privacy-security.md。官方反馈：GitHub Discussions；社区交流：LINUX DO。

codex-keysmith — Codex 全局指令
claude-keysmith — Claude Code 可卸载 import block
grok-keysmith — Grok Build home rules（~/.grok/rules/99-keysmith.md，不改 AGENTS.md）
zcode-keysmith — ZCode App system-role 入口（仅源码，无 Desktop）

Claude Keysmith

README