/cute-claude-hooks

name: cute-claude-hooks (可爱提示钩子)
description: 为 Claude Code 提供完整的中文体验！包含工具提示、界面汉化、完整的自定义指南、实战经验和进阶开发教程, 让用户能够根据自己的需求修改和完善.

🌸 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 无法正常启动或出错：

# 方法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 安装（推荐）

# 全局安装
npm install -g cute-claude-hooks

# 运行安装脚本
cute-claude-hooks-install

安装向导会提供四个选项： 1. **仅安装工具提示** — 适合只需要中文操作提示的用户 2. **仅安装界面汉化** — 适合只需要汉化界面的用户 3. **全部安装** — 完整中文体验（推荐） 4. **卸载** — 移除所有修改

方式二：npx 一键安装

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` 中，格式为：

module.exports = {
  'English text': '中文翻译',
  // ...
}

---

🔧 基础自定义

修改工具提示文本

编辑 `~/.claude/hooks/tool-tips-post.sh` 中的 `get_tip()` 函数：

get_tip() {
    case "$1" in
        "Read")
            echo "📖 正在读取文件 — 看看里面写了什么"
            ;;
        "Write")
            echo "📝 正在写入文件 — 创建或更新文件内容"
            ;;
        # ... 添加你自己的提示
    esac
}

修改命令解释

编辑 `explain_cmd()` 函数中的 `case` 语句：

git)
    local sub=$(echo "$rest" | awk '{print $1}')
    case "$sub" in
        status)  echo "查看仓库状态" ;;
        log)     echo "查看提交历史" ;;
        # 添加你自己的命令解释
    esac
    ;;

修改提示前缀和后缀

在主逻辑中修改 `🌸` 标记：

# 默认
escaped_tip=$(json_escape "🌸 ${tip} 🌸")

# 改为你想要的标记
escaped_tip=$(json_escape ">>> ${tip} <<<")

添加新的工具类型支持

在 `get_tip()` 函数中添加新的 `case` 分支：

# 添加对 NoteBookEdit 的支持
"NotebookEdit")
    echo "📓 编辑 Notebook — 修改 Jupyter 笔记本单元格"
    ;;

---

🚀 进阶自定义

修改 Hook 匹配规则

编辑 `~/.claude/settings.json` 中的 `matcher` 字段：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Read|Write|Edit|Glob|Grep|mcp__*",
        "hooks": [...]
      }
    ]
  }
}

**匹配规则说明：**

| 规则 | 匹配内容 | |------|---------| | `Bash` | 精确匹配 Bash 工具 | | `Bash\|Read` | 匹配 Bash 或 Read（用 `\|` 分隔） | | `mcp__*` | 匹配所有 MCP 工具（通配符） | | `*` | 匹配所有工具 |

条件式提示

根据文件类型显示不同提示：

"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 分支中添加新的服务器：

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()` 函数中添加新的命令组：

# 示例：添加 Kubernetes 命令
kubectl)
    l