cute-claude-hooks

# 🌸 Cute Claude Hooks - 完整指南 让 Claude Code 显示可爱的中文提示和界面! --- --- ## 📚 目录 0. [⚠️ 重要警告 - 必读！](#️-重要警告---必读) 1. [功能介绍](#-功能介绍) 2. [快速安装](#-快速安装) 3. [界面汉化](#-界面汉化) 4. [基础自定义](#-基础自定义) 5. [进阶自定义](#-进阶自定义) 6. [添加新功能](#-添加新功能) 7. [调试技巧](#-调试技巧) 8. [实战经验](#-实战经验) 9. [常见需求示例](#-常见需求示例) 10. [问题排查](#-问题排查) 11. [文件位置速查](#-文件位置速查) 12. [恢复默认](#-恢复默认) 13. [相关资源](#-相关资源) 14. [汉化关键词表](#-汉化关键词表) 15. [常见问题](#-常见问题) 16. [技术说明](#-技术说明) 17. [更新日志](#-更新日志) 18. [贡献指南](#-贡献指南) 19. [许可证](#-许可证) --- ## ⚠️ 重要警告 - 必读！ ### 🚫 不要随意修改的关键短语 在自定义钩子脚本时，**以下短语/格式千万不能随意修改**，否则可能导致 Claude Code 无法正常启动或运行： | 类型 | 不能修改的内容 | 原因 | |------|---------------|------| | **JSON 结构** | `{"systemMessage":"..."}` 格式 | Claude Code 依赖此格式解析 hook 输出 | | **特殊标记** | `<{{GUID}}>` 格式的标记 | 系统内部通信标识符 | | **工具名称** | `Bash`, `Read`, `Write` 等工具名 | 与 Claude Code 内部工具对应 | | **钩子字段** | `PreToolUse`, `PostToolUse` 等事件名 | 钩子系统核心字段 | | **环境变量名** | `CLAUDE_CODE_*` 相关变量 | 系统运行时依赖 | ### 💡 修改时的安全原则 1. **只修改显示文本** - 例如工具提示的中文名 2. **保持 JSON 结构完整** - 不要删除或重命名字段 3. **测试后再使用** - 修改后先用简单命令测试 4. **保留备份** - 修改前备份原始文件 ### 🔧 Claude Code 出错时的修复方法 如果修改后 Claude Code 无法正常启动或出错： ```bash # 方法1: 重新安装 Claude Code npm install -g @anthropic-ai/claude-code # 方法2: 清除缓存后重装 npm cache clean --force npm install -g @anthropic-ai/claude-code # 方法3: 恢复钩子默认配置 # 删除自定义钩子，使用原始配置 rm -rf ~/.claude/hooks/ ``` --- ## 🎯 功能介绍 ### 项目做了什么？ `cute-claude-hooks` 是一个为 **Claude Code** 设计的中文增强工具包，包含两大核心功能： #### 1️⃣ 工具操作中文提示 每次 Claude Code 执行操作时，都会在界面上显示一条中文提示，告诉你它刚才做了什么： ``` 🌸 📖 读取文件: package.json — 查看这个文件里写了什么 🌸 🌸 🖥️ 执行命令: git status — 查看代码仓库状态（有哪些文件被修改了） 🌸 🌸 ✏️ 编辑文件: index.js — 修改这个文件的部分内容 🌸 ``` **支持的工具类型：** | 工具 | 图标 | 说明 | |------|------|------| | `Read` | 📖 | 读取文件 | | `Write` | 📝 | 写入文件 | | `Edit` / `MultiEdit` | ✏️ | 编辑文件 | | `Bash` | 🖥️ | 执行终端命令 | | `Glob` | 🔍 | 搜索文件 | | `Grep` | 🔎 | 搜索内容 | | `Agent` | 🤖 | AI子任务 | | MCP 工具 | 🔌 | 第三方扩展 | **命令解释覆盖范围：** - **Git**: status, log, diff, add, commit, push, pull, fetch, checkout, branch, merge, rebase, stash, clone, init, reset, revert, cherry-pick, remote, show, tag, rm, mv - **npm/npx**: install, run, init, build, test, start - **yarn**: add, install, run, build - **pnpm**: add, install, run - **pip/pip3**: install, uninstall, list, show, freeze - **python/python3**: 运行 Python 程序 - **pytest**: 运行 Python 测试 - **文件操作**: ls, cat, head, tail, rm, mkdir, cp, mv, touch, chmod, chown, find, wc, sort, uniq, diff - **网络**: curl, wget, ping, ssh, scp - **Docker**: build, run, ps, stop, rm, images, compose - **系统**: echo, which, env, export, source, cd, pwd, whoami, date - **编译**: make, gcc, g++, cargo, go - **编辑器**: code, vim, vi, nano - **压缩**: tar, zip, unzip - **进程**: ps, kill, top, htop **多命令支持：** 当 Bash 工具执行多条命令（用 `&&`, `||`, `;` 连接）时，会逐条解释每一条命令。 #### 2️⃣ 界面汉化 将 Claude Code 的英文界面翻译为中文，包括： - 配置面板（`/config`） - 斜杠命令说明 - 快捷键提示 - 欢迎界面 - 状态信息 --- ## 📦 快速安装 ### 方式一：NPM 安装（推荐） ```bash # 全局安装 npm install -g cute-claude-hooks # 运行安装脚本 cute-claude-hooks-install ``` 安装向导会提供四个选项： 1. **仅安装工具提示** — 适合只需要中文操作提示的用户 2. **仅安装界面汉化** — 适合只需要汉化界面的用户 3. **全部安装** — 完整中文体验（推荐） 4. **卸载** — 移除所有修改 ### 方式二：npx 一键安装 ```bash npx cute-claude-hooks-install ``` 无需全局安装，直接运行安装脚本。 ### 方式三：手动安装 详见 README.md 中的「Windows 手动安装」章节。 --- ## 🌐 界面汉化 ### 工作原理 界面汉化通过 **关键词全局替换** 实现： 1. 备份 Claude Code 的 `cli.js` 为 `cli.bak.js` 2. 读取 `keyword.js` 中的翻译对照表（151条） 3. 在 `cli.js` 中执行全文替换 4. 每次替换都验证 JSON 结构完整性 ### 支持的汉化范围 | 区域 | 示例原文 | 示例译文 | |------|---------|---------| | 配置面板 | `Theme` | `主题` | | 斜杠命令 | `/help - Get help` | `/help - 获取帮助` | | 快捷键提示 | `Esc to cancel` | `Esc 取消` | | 欢迎界面 | `Welcome back!` | `欢迎回来!` | | 状态信息 | `Auto-compact` | `自动压缩` | ### 汉化词条管理 所有翻译词条在 `localize/keyword.js` 中，格式为： ```javascript module.exports = { 'English text': '中文翻译', // ... } ``` --- ## 🔧 基础自定义 ### 修改工具提示文本 编辑 `~/.claude/hooks/tool-tips-post.sh` 中的 `get_tip()` 函数： ```bash get_tip() { case "$1" in "Read") echo "📖 正在读取文件 — 看看里面写了什么" ;; "Write") echo "📝 正在写入文件 — 创建或更新文件内容" ;; # ... 添加你自己的提示 esac } ``` ### 修改命令解释 编辑 `explain_cmd()` 函数中的 `case` 语句： ```bash git) local sub=$(echo "$rest" | awk '{print $1}') case "$sub" in status) echo "查看仓库状态" ;; log) echo "查看提交历史" ;; # 添加你自己的命令解释 esac ;; ``` ### 修改提示前缀和后缀 在主逻辑中修改 `🌸` 标记： ```bash # 默认 escaped_tip=$(json_escape "🌸 ${tip} 🌸") # 改为你想要的标记 escaped_tip=$(json_escape ">>> ${tip} <<<") ``` ### 添加新的工具类型支持 在 `get_tip()` 函数中添加新的 `case` 分支： ```bash # 添加对 NoteBookEdit 的支持 "NotebookEdit") echo "📓 编辑 Notebook — 修改 Jupyter 笔记本单元格" ;; ``` --- ## 🚀 进阶自定义 ### 修改 Hook 匹配规则 编辑 `~/.claude/settings.json` 中的 `matcher` 字段： ```json { "hooks": { "PostToolUse": [ { "matcher": "Bash|Read|Write|Edit|Glob|Grep|mcp__*", "hooks": [...] } ] } } ``` **匹配规则说明：** | 规则 | 匹配内容 | |------|---------| | `Bash` | 精确匹配 Bash 工具 | | `Bash\|Read` | 匹配 Bash 或 Read（用 `\|` 分隔） | | `mcp__*` | 匹配所有 MCP 工具（通配符） | | `*` | 匹配所有工具 | ### 条件式提示 根据文件类型显示不同提示： ```bash "Read") if [ -n "$file_path" ]; then ext="${file_path##*.}" case "$ext" in py) echo "📖 读取 Python 文件: $(short_path "$file_path")" ;; js) echo "📖 读取 JavaScript 文件: $(short_path "$file_path")" ;; *) echo "📖 读取文件: $(short_path "$file_path")" ;; esac fi ;; ``` ### 自定义 MCP 工具提示 在 `get_tip()` 的 MCP 分支中添加新的服务器： ```bash case "$srv" in "context7") echo "📚 查询文档: $tool" ;; "exa") echo "🌐 网络搜索: $tool" ;; "basic-memory") echo "🧠 记忆操作: $tool" ;; # 添加你自己的 MCP 服务器 "my-server") echo "🔧 我的工具: $tool" ;; *) echo "🔌 $srv: $tool" ;; esac ``` --- ## 🆕 添加新功能 ### 添加新的 Bash 命令解释 在 `explain_cmd()` 函数中添加新的命令组： ```bash # 示例：添加 Kubernetes 命令 kubectl) local sub=$(echo "$rest" | awk '{print $1}') case "$sub" in get) echo "查看 Kubernetes 资源" ;; apply) echo "应用 Kubernetes 配置" ;; delete) echo "删除 Kubernetes 资源" ;; logs) echo "查看容器日志" ;; describe) echo "查看资源详细信息" ;; *) echo "Kubernetes 集群操作" ;; esac ;; ``` ### 添加新的汉化词条 编辑 `localize/keyword.js`： ```javascript module.exports = { // 现有词条... // 添加新词条 'New English Text': '新的中文翻译', }; ``` 然后重新运行汉化： ```bash node ~/.claude/localize/localize.js ``` ### 添加 PreToolUse Hook 除了 PostToolUse（执行后提示），还可以添加 PreToolUse（执行前提示）： ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "~/.claude/hooks/pre-warning.sh" } ] } ] } } ``` --- ## 🔍 调试技巧 ### 测试 Hook 脚本 手动模拟 Claude Code 的调用： ```bash # 测试 Read 工具提示 echo '{"tool_name":"Read","file_path":"test.py"}' | bash ~/.claude/hooks/tool-tips-post.sh # 测试 Bash 工具提示 echo '{"tool_name":"Bash","command":"git status"}' | bash ~/.claude/hooks/tool-tips-post.sh # 测试 Glob 工具提示 echo '{"tool_name":"Glob","pattern":"**/*.js"}' | bash ~/.claude/hooks/tool-tips-post.sh # 测试多命令提示 echo '{"tool_name":"Bash","command":"git status && npm install && npm run build"}' | bash ~/.claude/hooks/tool-tips-post.sh ``` **预期输出格式：** ```json