Imported from Dublin1231/polished-localization-for-claude-code (SKILL.md). Install upstream with npx skills add Dublin1231/polished-localization-for-claude-code. Copyright stays with the author.

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

💡 修改时的安全原则

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 — 修改这个文件的部分内容 🌸

支持的工具类型：

命令解释覆盖范围：

• 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 结构完整性

支持的汉化范围

汉化词条管理

所有翻译词条在 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": [...]
      }
    ]
  }
}

匹配规则说明：

条件式提示

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

"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)
    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：

module.exports = {
  // 现有词条...

  // 添加新词条
  'New English Text': '新的中文翻译',
};

然后重新运行汉化：

node ~/.claude/localize/localize.js

添加 PreToolUse Hook

除了 PostToolUse（执行后提示），还可以添加 PreToolUse（执行前提示）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/pre-warning.sh"
          }
        ]
      }
    ]
  }
}

🔍 调试技巧

测试 Hook 脚本

手动模拟 Claude Code 的调用：

# 测试 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

预期输出格式：

{"systemMessage":"🌸 🖥️ 共3条命令:\n  1. git status — 查看代码仓库状态（有哪些文件被修改了）\n  2. npm install — 安装项目依赖包\n  3. npm run build — 构建/编译项目 🌸"}

查看 Claude Code 的 Hook 日志

Claude Code 的 hook 执行日志在终端中可见。如果提示没有出现：

1. 确认 hook 脚本路径正确（使用正斜杠 /）
2. 确认脚本有执行权限（Linux/macOS: chmod +x）
3. 确认脚本换行符为 LF（不是 CRLF）
4. 手动运行上面的测试命令检查输出

检查 settings.json 格式

# 验证 JSON 格式
node -e "JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8'));console.log('OK')"

💡 实战经验

经验 1：Windows 路径问题

问题： Windows 上 hook 脚本路径包含反斜杠或中文用户名。

解决： settings.json 中的路径使用正斜杠：

"command": "C:/Users/你的用户名/.claude/hooks/tool-tips-post.sh"

Claude Code 会自动通过 Git Bash 执行 .sh 脚本。

经验 2：CRLF 换行问题

问题： 在 Windows 上编辑 .sh 文件后，换行符变成 CRLF，导致 bash 报错。

解决： 确保使用 LF 换行符。在 VS Code 中，点击右下角的 CRLF，切换为 LF。

或在安装脚本中自动处理：

# 将 CRLF 转为 LF
sed -i 's/\r$//' tool-tips-post.sh

经验 3：Hook 输出格式

关键发现： PostToolUse hook 的输出必须是以下格式才能在 UI 中显示：

{"systemMessage":"你要显示的文本"}

• 必须是合法 JSON
• 字段名必须是 systemMessage
• exit code 必须为 0
• stderr 在 exit code 0 时会被静默丢弃

经验 4：命令解释的准确性

原则： 解释应该让完全不懂编程的人也能理解：

• ❌ 执行命令: git status
• ✅ 执行命令: git status — 查看代码仓库状态（有哪些文件被修改了）

每个解释都包含两部分：

1. 功能描述 — 这个命令做什么
2. 括号补充 — 用更通俗的话再解释一遍

经验 5：多命令处理

当 Bash 执行的命令包含多条语句时（用 &&, ||, ; 连接），脚本会：

1. 跳过注释行和空行
2. 按分隔符拆分命令
3. 逐条给出解释
4. 超过 3 条时折叠显示

📋 常见需求示例

需求 1：只显示 Bash 命令提示

修改 settings.json 的 matcher：

"matcher": "Bash"

需求 2：添加时间戳

修改 get_tip() 中的输出：

"Bash")
    timestamp=$(date '+%H:%M:%S')
    echo "🖥️ [${timestamp}] 执行命令: $real_cmd — $(explain_cmd "$real_cmd")"
    ;;

需求 3：隐藏文件路径

修改 get_tip() 中的 Read/Write/Edit 分支，去掉文件名：

"Read")
    echo "📖 读取文件 — 查看文件内容"
    ;;

需求 4：添加声音提醒

"Bash")
    # macOS 声音提醒
    afplay /System/Library/Sounds/Ping.aiff &
    echo "🖥️ 执行命令: $real_cmd"
    ;;

需求 5：记录操作日志

在主逻辑中添加日志记录：

# 在输出 systemMessage 之前记录日志
log_file="$HOME/.claude/hooks/operation.log"
echo "$(date '+%Y-%m-%d %H:%M:%S') | $tool_name | $file_path" >> "$log_file"

🪟 Windows 环境深度自检指南

Windows 用户必读！ 90% 的 Hooks 失效问题都源于环境配置不当。请按以下五个阶段逐一排查。

快速自检命令

将以下内容直接粘贴给 Claude Code，让它帮你排查：

"你现在是一个 Windows 专家级运维工程师。请针对以下五个维度，深度扫描我的系统路径、配置和环境变量，找出可能导致 Claude Code Hooks 失效、命令不识别或路径冲突的问题，并给出修复建议。"

[第一阶段] 基础底座：Shell 与权限

常见问题：

• PowerShell 5.1 (蓝底) → UTF-8 支持不完整，建议升级到 PowerShell 7
• ExecutionPolicy = Restricted → 所有脚本被静默拦截，运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
• 非管理员终端 → 某些 npm 全局安装需要管理员权限

[第二阶段] 核心动力：Node.js 与 NPM

常见问题：

• 路径含空格 (C:\Program Files\nodejs) → 通常没问题，但某些工具可能报错
• 路径含中文 (C:\Users\小明\...) → 会导致 npm 全局包安装失败，建议修改 npm prefix：

  npm config set prefix "C:\npm-global"
  # 然后将 C:\npm-global 加入系统 PATH

• nvm-windows 冲突 → 如果同时装了 nvm-windows 和 Node 官网包，可能路径冲突，建议只保留一个

[第三阶段] 模拟环境：Git Bash 与 Unix 工具 ⚠️ 最关键

⚠️ 头号死穴：core.autocrlf = true

这是 Windows 上 Hooks 失效的第一大原因！当 core.autocrlf = true 时：

1. Git 会在 checkout 时自动把 LF 转为 CRLF
2. .sh 脚本变成 CRLF 换行
3. bash 执行 CRLF 脚本报 \r: command not found

修复：

git config --global core.autocrlf input

为什么用 input 而不是 false？

• input：提交时 CRLF → LF，检出时不动。Windows 写代码没问题，脚本也不会被破坏
• false：完全不管换行符。如果你用 Windows 编辑器写代码，可能会把 CRLF 提交到仓库

验证 sh 可用：

# 应该输出 bash 版本信息
sh --version
# 如果报错，检查 PATH 是否包含 Git\bin
$env:Path -split ';' | Where-Object { $_ -match 'Git\\\\bin' }

[第四阶段] 文件系统：字符编码与路径

常见问题：

• 中文用户名 (C:\Users\古古) → 通常没问题，但某些老旧工具可能报错
• 项目路径含中文 (D:\项目资料\AI工具) → 极易出问题！建议改为英文路径
• 长路径 (C:\Users\xxx\.claude\plugins\cache\...\node_modules\...) → 超过 260 字符会导致 Node 报错

开启长路径支持：

# 管理员 PowerShell 运行
Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1
# 需要重启生效

[第五阶段] 网络与代理

国内用户特别注意：

如果使用公司代理或 VPN：

# 如果代理导致 SSL 错误（不推荐，仅调试用）
npm config set strict-ssl false

# 推荐方式：使用国内镜像
npm config set registry https://registry.npmmirror.com

一键自检脚本

将以下内容保存为 check-env.ps1 运行，或直接粘贴到 PowerShell：

Write-Host "`n🌸 Cute Claude Hooks — Windows 环境自检 🌸`n" -ForegroundColor Magenta

$pass = "✅"; $fail = "❌"; $warn = "⚠️"

# Stage 1: Shell
Write-Host "[第一阶段] Shell 与权限" -ForegroundColor Cyan
$psVer = $PSVersionTable.PSVersion.Major
Write-Host ($psVer -ge 7 ? "$pass PowerShell $psVer" : "$warn PowerShell $psVer (建议升级到 7+)")
$policy = Get-ExecutionPolicy
Write-Host ($policy -ne 'Restricted' ? "$pass 执行策略: $policy" : "$fail 执行策略: $policy (需设为 RemoteSigned)")

# Stage 2: Node
Write-Host "`n[第二阶段] Node.js" -ForegroundColor Cyan
try { $n = node --version 2>$null; Write-Host "$pass Node $n" } catch { Write-Host "$fail Node 未安装" }
$prefix = npm config get prefix 2>$null
Write-Host ($prefix -match '[\u4e00-\u9fff]' ? "$fail npm prefix 含中文: $prefix" : "$pass npm prefix: $prefix")

# Stage 3: Git Bash (关键!)
Write-Host "`n[第三阶段] Git Bash (最关键)" -ForegroundColor Yellow
try { $g = git --version 2>$null; Write-Host "$pass $g" } catch { Write-Host "$fail Git 未安装" }
$autocrlf = git config --global core.autocrlf 2>$null
Write-Host ($autocrlf -eq 'input' ? "$pass core.autocrlf = input" : "$fail core.autocrlf = $autocrlf (必须改为 input!)")
$hookPath = git config --global core.hooksPath 2>$null
Write-Host ($hookPath ? "$warn core.hooksPath = $hookPath (可能拦截 Claude Hooks)" : "$pass 无全局 hooksPath 覆盖")

# Stage 4: Encoding
Write-Host "`n[第四阶段] 文件系统" -ForegroundColor Cyan
$userPath = $env:USERPROFILE
Write-Host ($userPath -match '[\u4e00-\u9fff]' ? "$warn 用户路径含中文: $userPath" : "$pass 用户路径: $userPath")

# Stage 5: Network
Write-Host "`n[第五阶段] 网络" -ForegroundColor Cyan
$reg = npm config get registry 2>$null
Write-Host ($reg -match 'npmmirror' ? "$pass npm 镜像: $reg" : "$pass npm 源: $reg")

Write-Host "`n🌸 自检完成！如有 ❌ 项请参考上方修复建议 🌸`n" -ForegroundColor Magenta

🐛 问题排查

提示不显示

排查步骤：

1. 检查 settings.json 格式

   node -e "console.log(JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8')).hooks)"

2. 手动测试 hook 脚本

   echo '{"tool_name":"Read","file_path":"test.py"}' | bash ~/.claude/hooks/tool-tips-post.sh

   应该输出 {"systemMessage":"..."}

3. 检查脚本换行符

   file ~/.claude/hooks/tool-tips-post.sh
   # 应该显示: ASCII text, not ASCII text, with CRLF line terminators

4. 检查脚本权限（Linux/macOS）

   ls -la ~/.claude/hooks/tool-tips-post.sh
   # 应该有执行权限
   chmod +x ~/.claude/hooks/tool-tips-post.sh

中文乱码

确保系统编码为 UTF-8：

• Windows: 设置 → 时间和语言 → 语言 → 管理语言设置 → 更改系统区域设置 → 勾选 Beta: 使用 Unicode UTF-8
• Linux/macOS: 通常默认 UTF-8

安装脚本报错

# 查看详细错误
cute-claude-hooks-install 2>&1 | tee install.log

📁 文件位置速查

🔄 恢复默认

恢复英文界面

# 方式一：使用卸载命令
cute-claude-hooks-restore

# 方式二：手动恢复
node ~/.claude/localize/localize.js --restore

移除工具提示

编辑 ~/.claude/settings.json，删除 hooks 段：

{
  "hooks": {}
}

完全卸载

# 1. 恢复英文界面
cute-claude-hooks-restore

# 2. 删除 hook 文件
rm -rf ~/.claude/hooks/

# 3. 删除汉化文件
rm -rf ~/.claude/localize/

# 4. 卸载 npm 包
npm uninstall -g cute-claude-hooks

🔗 相关资源

📖 汉化关键词表

当前共有 151 条翻译词条，覆盖 Claude Code 界面的主要文本。

主要分类：

完整词条列表见 localize/keyword.js 文件。

❓ 常见问题

Q: 支持 macOS 和 Linux 吗？

A: 完全支持！安装脚本自动检测操作系统。

Q: 更新 Claude Code 后汉化会丢失吗？

A: 会的。Claude Code 更新会覆盖 cli.js。重新运行 cute-claude-hooks-install 选择「仅安装界面汉化」即可。

Q: 工具提示支持哪些命令？

A: 支持 80+ 常用命令的中文解释，涵盖 git、npm、pip、docker、文件操作、网络命令等。

Q: 可以只安装工具提示不汉化界面吗？

A: 可以。安装时选择「仅安装工具提示」。

Q: 中文用户名路径会有问题吗？

A: 一般不会。如果遇到编码问题，确保系统编码为 UTF-8。

Q: 修改 hook 脚本后需要重启 Claude Code 吗？

A: 不需要。每次工具执行都会调用 hook 脚本，修改立即生效。

Q: 为什么提示没有显示颜色？

A: Claude Code 的 hook 系统通过 systemMessage 渲染文本，目前不支持 ANSI 颜色代码。提示会以默认颜色显示。

🔬 技术说明

Hook 工作流程

Claude Code 执行工具
       ↓
触发 PostToolUse 事件
       ↓
匹配 matcher 规则
       ↓
执行 hook command (tool-tips-post.sh)
       ↓
从 stdin 读取工具信息 JSON
       ↓
提取 tool_name, file_path, pattern, command
       ↓
调用 get_tip() 生成中文提示
       ↓
输出 {"systemMessage":"..."} 到 stdout
       ↓
Claude Code 读取并显示在界面上

JSON 输入格式（stdin）

Claude Code 通过 stdin 传递工具信息：

{
  "tool_name": "Bash",
  "file_path": "src/index.js",
  "pattern": "**/*.js",
  "command": "git status && npm install"
}

JSON 输出格式（stdout）

Hook 必须输出以下格式：

{"systemMessage":"🌸 🖥️ 执行命令: git status — 查看代码仓库状态 🌸"}

注意事项：

• 必须是单行合法 JSON
• systemMessage 中的换行用 \n 表示
• 双引号用 \" 转义
• 反斜杠用 \\ 转义

多命令解析逻辑

1. 从 command 字段提取 bash 命令
2. 将 JSON 转义的 \n 转为实际换行
3. 跳过注释行（# 开头）和空行
4. 按分隔符 &&, ||, ; 拆分
5. 对每条命令调用 explain_cmd() 生成解释
6. 超过 3 条时折叠为 ...(还有N条)

📝 更新日志

v1.0.6 (当前版本)

• 🔄 重大更新: Hook 输出改为 systemMessage JSON 格式
• 📖 新增: 80+ 命令的中文解释（小白友好）
• 📋 新增: 多命令场景的逐条解释
• 🧹 移除: 命令截断（head -c），现在显示完整命令
• 🔧 修复: 跳过 Bash 命令中的注释行
• 🔧 修复: JSON 转义换行符 \n 正确转换为实际换行

v1.0.5

• 🌸 界面汉化引擎改为 Node.js 实现
• 📝 关键词字典改为 JavaScript 模块
• 🧹 移除 Python/Shell 版本的汉化脚本

v1.0.4

• 🪟 Windows 兼容性改进
• 🔧 修复路径中的中文编码问题

v1.0.0

• 🎉 初始版本发布
• 📖 基础工具中文提示
• 🌐 界面汉化支持

🤝 贡献指南

如何贡献

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 提交修改：git commit -m 'feat: 添加某某功能'
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

贡献方向

特别欢迎以下贡献：

• 🌍 新的汉化词条 — 补充 keyword.js 中缺少的翻译
• 🔧 新的命令解释 — 为 explain_cmd() 添加更多命令
• 📸 效果截图 — 展示实际使用效果
• 📝 文档改进 — 修正错误或补充说明
• 🐛 Bug 修复 — 修复已知问题
• 🌐 多语言支持 — 添加其他语言版本

提交规范

使用 Conventional Commits 格式：

feat: 添加 kubectl 命令解释
fix: 修复 Windows 中文路径编码问题
docs: 更新 SKILL.md 安装说明
refactor: 简化 get_tip() 函数逻辑

📄 许可证

MIT License - 自由使用、修改和分发