Skip to content
Back to search

cute-claude-hooks (可爱提示钩子)

SkillWorks with Claude CodeGitHub

为 Claude Code 提供完整的中文体验!包含工具提示、界面汉化、完整的自定义指南、实战经验和进阶开发教程, 让用户能够根据自己的需求修改和完善.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gugug168--cute-claude-hooks/badge.svg)](/listings/gugug168--cute-claude-hooks)

HTML

<a href="/listings/gugug168--cute-claude-hooks"><img src="/api/listings/gugug168--cute-claude-hooks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

功能与安装方式对应表

| 功能 | NPM 安装 | 手动/脚本安装 | 版本要求 | |------|:--------:|:------------:|---------| | 📖 工具提示 Hook (tool-tips-post.sh) | ✅ | ✅ | 所有版本 | | 🔔 任务完成通知 Hook (task-done-notify.sh) | ✅ | ✅ | 所有版本 | | 🌐 界面汉化 (配置面板、斜杠命令等) | ⚠️ | ❌ | **仅 ≤ 2.1.112** |

> ⚠️ **界面汉化已失效**:Claude Code v2.1.113 起改为编译二进制,无法再通过字符串替换修改界面文案。工具提示 Hook 不受影响,所有版本均可使用。

方式一:NPM 安装(推荐)

> ⚠️ 安装前请先检查版本:`claude --version`。如果你的版本 ≥ 2.1.113,界面汉化将不可用,但仍可安装工具提示 Hook。

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

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

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

**或者使用 npx(无需全局安装):**

npx cute-claude-hooks-install

方式二:国内加速安装(推荐国内用户)

如果 npm 官方源速度慢,可以使用国内镜像:

# 使用 npmmirror 镜像安装
npm install -g cute-claude-hooks --registry=https://registry.npmmirror.com

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

**或者使用 npx:**

npx cute-claude-hooks-install

安装选项

╔════════════════════════════════════════╗
║     🌸 Cute Claude Hooks 安装向导 🌸   ║
╠════════════════════════════════════════╣
║  [1] 仅安装工具提示 (推荐新手)         ║
║  [2] 仅安装界面汉化                    ║
║  [3] 全部安装 (完整中文体验) ← 推荐    ║
║  [4] 卸载                              ║
╚════════════════════════════════════════╝

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 1,001 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: cute-claude-hooks (可爱提示钩子)
  3. description: 为 Claude Code 提供完整的中文体验!包含工具提示、界面汉化、完整的自定义指南、实战经验和进阶开发教程, 让用户能够根据自己的需求修改和完善.
  4. ---
  5. # 🌸 Cute Claude Hooks - 完整指南
  6. 让 Claude Code 显示可爱的中文提示和界面!
  7. ---
  8. ---
  9. ## 📚 目录
  10. 0. [⚠️ 重要警告 - 必读!](#️-重要警告---必读)
  11. 1. [功能介绍](#-功能介绍)
  12. 2. [快速安装](#-快速安装)
  13. 3. [界面汉化](#-界面汉化)
  14. 4. [基础自定义](#-基础自定义)
  15. 5. [进阶自定义](#-进阶自定义)
  16. 6. [添加新功能](#-添加新功能)
  17. 7. [调试技巧](#-调试技巧)
  18. 8. [实战经验](#-实战经验)
  19. 9. [常见需求示例](#-常见需求示例)
  20. 10. [问题排查](#-问题排查)
  21. 11. [文件位置速查](#-文件位置速查)
  22. 12. [恢复默认](#-恢复默认)
  23. 13. [相关资源](#-相关资源)
  24. 14. [汉化关键词表](#-汉化关键词表)
  25. 15. [常见问题](#-常见问题)
  26. 16. [技术说明](#-技术说明)
  27. 17. [更新日志](#-更新日志)
  28. 18. [贡献指南](#-贡献指南)
  29. 19. [许可证](#-许可证)
  30. ---
  31. ## ⚠️ 重要警告 - 必读!
  32. ### 🚫 不要随意修改的关键短语
  33. 在自定义钩子脚本时,**以下短语/格式千万不能随意修改**,否则可能导致 Claude Code 无法正常启动或运行:
  34. | 类型 | 不能修改的内容 | 原因 |
  35. |------|---------------|------|
  36. | **JSON 结构** | `{"systemMessage":"..."}` 格式 | Claude Code 依赖此格式解析 hook 输出 |
  37. | **特殊标记** | `<{{GUID}}>` 格式的标记 | 系统内部通信标识符 |
  38. | **工具名称** | `Bash`, `Read`, `Write` 等工具名 | 与 Claude Code 内部工具对应 |
  39. | **钩子字段** | `PreToolUse`, `PostToolUse` 等事件名 | 钩子系统核心字段 |
  40. | **环境变量名** | `CLAUDE_CODE_*` 相关变量 | 系统运行时依赖 |
  41. ### 💡 修改时的安全原则
  42. 1. **只修改显示文本** - 例如工具提示的中文名
  43. 2. **保持 JSON 结构完整** - 不要删除或重命名字段
  44. 3. **测试后再使用** - 修改后先用简单命令测试
  45. 4. **保留备份** - 修改前备份原始文件
  46. ### 🔧 Claude Code 出错时的修复方法
  47. 如果修改后 Claude Code 无法正常启动或出错:
  48. ```bash
  49. # 方法1: 重新安装 Claude Code
  50. npm install -g @anthropic-ai/claude-code
  51. # 方法2: 清除缓存后重装
  52. npm cache clean --force
  53. npm install -g @anthropic-ai/claude-code
  54. # 方法3: 恢复钩子默认配置
  55. # 删除自定义钩子,使用原始配置
  56. rm -rf ~/.claude/hooks/
  57. ```
  58. ---
  59. ## 🎯 功能介绍
  60. ### 项目做了什么?
  61. `cute-claude-hooks` 是一个为 **Claude Code** 设计的中文增强工具包,包含两大核心功能:
  62. #### 1️⃣ 工具操作中文提示
  63. 每次 Claude Code 执行操作时,都会在界面上显示一条中文提示,告诉你它刚才做了什么:
  64. ```
  65. 🌸 📖 读取文件: package.json — 查看这个文件里写了什么 🌸
  66. 🌸 🖥️ 执行命令: git status — 查看代码仓库状态(有哪些文件被修改了) 🌸
  67. 🌸 ✏️ 编辑文件: index.js — 修改这个文件的部分内容 🌸
  68. ```
  69. **支持的工具类型:**
  70. | 工具 | 图标 | 说明 |
  71. |------|------|------|
  72. | `Read` | 📖 | 读取文件 |
  73. | `Write` | 📝 | 写入文件 |
  74. | `Edit` / `MultiEdit` | ✏️ | 编辑文件 |
  75. | `Bash` | 🖥️ | 执行终端命令 |
  76. | `Glob` | 🔍 | 搜索文件 |
  77. | `Grep` | 🔎 | 搜索内容 |
  78. | `Agent` | 🤖 | AI子任务 |
  79. | MCP 工具 | 🔌 | 第三方扩展 |
  80. **命令解释覆盖范围:**
  81. - **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
  82. - **npm/npx**: install, run, init, build, test, start
  83. - **yarn**: add, install, run, build
  84. - **pnpm**: add, install, run
  85. - **pip/pip3**: install, uninstall, list, show, freeze
  86. - **python/python3**: 运行 Python 程序
  87. - **pytest**: 运行 Python 测试
  88. - **文件操作**: ls, cat, head, tail, rm, mkdir, cp, mv, touch, chmod, chown, find, wc, sort, uniq, diff
  89. - **网络**: curl, wget, ping, ssh, scp
  90. - **Docker**: build, run, ps, stop, rm, images, compose
  91. - **系统**: echo, which, env, export, source, cd, pwd, whoami, date
  92. - **编译**: make, gcc, g++, cargo, go
  93. - **编辑器**: code, vim, vi, nano
  94. - **压缩**: tar, zip, unzip
  95. - **进程**: ps, kill, top, htop
  96. **多命令支持:** 当 Bash 工具执行多条命令(用 `&&`, `||`, `;` 连接)时,会逐条解释每一条命令。
  97. #### 2️⃣ 界面汉化
  98. 将 Claude Code 的英文界面翻译为中文,包括:
  99. - 配置面板(`/config`)
  100. - 斜杠命令说明
  101. - 快捷键提示
  102. - 欢迎界面
  103. - 状态信息
  104. ---
  105. ## 📦 快速安装
  106. ### 方式一:NPM 安装(推荐)
  107. ```bash
  108. # 全局安装
  109. npm install -g cute-claude-hooks
  110. # 运行安装脚本
  111. cute-claude-hooks-install
  112. ```
  113. 安装向导会提供四个选项:
  114. 1. **仅安装工具提示** — 适合只需要中文操作提示的用户
  115. 2. **仅安装界面汉化** — 适合只需要汉化界面的用户
  116. 3. **全部安装** — 完整中文体验(推荐)
  117. 4. **卸载** — 移除所有修改
  118. ### 方式二:npx 一键安装
  119. ```bash
  120. npx cute-claude-hooks-install
  121. ```
  122. 无需全局安装,直接运行安装脚本。
  123. ### 方式三:手动安装
  124. 详见 README.md 中的「Windows 手动安装」章节。
  125. ---
  126. ## 🌐 界面汉化
  127. ### 工作原理
  128. 界面汉化通过 **关键词全局替换** 实现:
  129. 1. 备份 Claude Code 的 `cli.js` 为 `cli.bak.js`
  130. 2. 读取 `keyword.js` 中的翻译对照表(151条)
  131. 3. 在 `cli.js` 中执行全文替换
  132. 4. 每次替换都验证 JSON 结构完整性
  133. ### 支持的汉化范围
  134. | 区域 | 示例原文 | 示例译文 |
  135. |------|---------|---------|
  136. | 配置面板 | `Theme` | `主题` |
  137. | 斜杠命令 | `/help - Get help` | `/help - 获取帮助` |
  138. | 快捷键提示 | `Esc to cancel` | `Esc 取消` |
  139. | 欢迎界面 | `Welcome back!` | `欢迎回来!` |
  140. | 状态信息 | `Auto-compact` | `自动压缩` |
  141. ### 汉化词条管理
  142. 所有翻译词条在 `localize/keyword.js` 中,格式为:
  143. ```javascript
  144. module.exports = {
  145. 'English text': '中文翻译',
  146. // ...
  147. }
  148. ```
  149. ---
  150. ## 🔧 基础自定义
  151. ### 修改工具提示文本
  152. 编辑 `~/.claude/hooks/tool-tips-post.sh` 中的 `get_tip()` 函数:
  153. ```bash
  154. get_tip() {
  155. case "$1" in
  156. "Read")
  157. echo "📖 正在读取文件 — 看看里面写了什么"
  158. ;;
  159. "Write")
  160. echo "📝 正在写入文件 — 创建或更新文件内容"
  161. ;;
  162. # ... 添加你自己的提示
  163. esac
  164. }
  165. ```
  166. ### 修改命令解释
  167. 编辑 `explain_cmd()` 函数中的 `case` 语句:
  168. ```bash
  169. git)
  170. local sub=$(echo "$rest" | awk '{print $1}')
  171. case "$sub" in
  172. status) echo "查看仓库状态" ;;
  173. log) echo "查看提交历史" ;;
  174. # 添加你自己的命令解释
  175. esac
  176. ;;
  177. ```
  178. ### 修改提示前缀和后缀
  179. 在主逻辑中修改 `🌸` 标记:
  180. ```bash
  181. # 默认
  182. escaped_tip=$(json_escape "🌸 ${tip} 🌸")
  183. # 改为你想要的标记
  184. escaped_tip=$(json_escape ">>> ${tip} <<<")
  185. ```
  186. ### 添加新的工具类型支持
  187. 在 `get_tip()` 函数中添加新的 `case` 分支:
  188. ```bash
  189. # 添加对 NoteBookEdit 的支持
  190. "NotebookEdit")
  191. echo "📓 编辑 Notebook — 修改 Jupyter 笔记本单元格"
  192. ;;
  193. ```
  194. ---
  195. ## 🚀 进阶自定义
  196. ### 修改 Hook 匹配规则
  197. 编辑 `~/.claude/settings.json` 中的 `matcher` 字段:
  198. ```json
  199. {
  200. "hooks": {
  201. "PostToolUse": [
  202. {
  203. "matcher": "Bash|Read|Write|Edit|Glob|Grep|mcp__*",
  204. "hooks": [...]
  205. }
  206. ]
  207. }
  208. }
  209. ```
  210. **匹配规则说明:**
  211. | 规则 | 匹配内容 |
  212. |------|---------|
  213. | `Bash` | 精确匹配 Bash 工具 |
  214. | `Bash\|Read` | 匹配 Bash 或 Read(用 `\|` 分隔) |
  215. | `mcp__*` | 匹配所有 MCP 工具(通配符) |
  216. | `*` | 匹配所有工具 |
  217. ### 条件式提示
  218. 根据文件类型显示不同提示:
  219. ```bash
  220. "Read")
  221. if [ -n "$file_path" ]; then
  222. ext="${file_path##*.}"
  223. case "$ext" in
  224. py) echo "📖 读取 Python 文件: $(short_path "$file_path")" ;;
  225. js) echo "📖 读取 JavaScript 文件: $(short_path "$file_path")" ;;
  226. *) echo "📖 读取文件: $(short_path "$file_path")" ;;
  227. esac
  228. fi
  229. ;;
  230. ```
  231. ### 自定义 MCP 工具提示
  232. 在 `get_tip()` 的 MCP 分支中添加新的服务器:
  233. ```bash
  234. case "$srv" in
  235. "context7") echo "📚 查询文档: $tool" ;;
  236. "exa") echo "🌐 网络搜索: $tool" ;;
  237. "basic-memory") echo "🧠 记忆操作: $tool" ;;
  238. # 添加你自己的 MCP 服务器
  239. "my-server") echo "🔧 我的工具: $tool" ;;
  240. *) echo "🔌 $srv: $tool" ;;
  241. esac
  242. ```
  243. ---
  244. ## 🆕 添加新功能
  245. ### 添加新的 Bash 命令解释
  246. 在 `explain_cmd()` 函数中添加新的命令组:
  247. ```bash
  248. # 示例:添加 Kubernetes 命令
  249. kubectl)
  250. local sub=$(echo "$rest" | awk '{print $1}')
  251. case "$sub" in
  252. get) echo "查看 Kubernetes 资源" ;;
  253. apply) echo "应用 Kubernetes 配置" ;;
  254. delete) echo "删除 Kubernetes 资源" ;;
  255. logs) echo "查看容器日志" ;;
  256. describe) echo "查看资源详细信息" ;;
  257. *) echo "Kubernetes 集群操作" ;;
  258. esac
  259. ;;
  260. ```
  261. ### 添加新的汉化词条
  262. 编辑 `localize/keyword.js`:
  263. ```javascript
  264. module.exports = {
  265. // 现有词条...
  266. // 添加新词条
  267. 'New English Text': '新的中文翻译',
  268. };
  269. ```
  270. 然后重新运行汉化:
  271. ```bash
  272. node ~/.claude/localize/localize.js
  273. ```
  274. ### 添加 PreToolUse Hook
  275. 除了 PostToolUse(执行后提示),还可以添加 PreToolUse(执行前提示):
  276. ```json
  277. {
  278. "hooks": {
  279. "PreToolUse": [
  280. {
  281. "matcher": "Bash",
  282. "hooks": [
  283. {
  284. "type": "command",
  285. "command": "~/.claude/hooks/pre-warning.sh"
  286. }
  287. ]
  288. }
  289. ]
  290. }
  291. }
  292. ```
  293. ---
  294. ## 🔍 调试技巧
  295. ### 测试 Hook 脚本
  296. 手动模拟 Claude Code 的调用:
  297. ```bash
  298. # 测试 Read 工具提示
  299. echo '{"tool_name":"Read","file_path":"test.py"}' | bash ~/.claude/hooks/tool-tips-post.sh
  300. # 测试 Bash 工具提示
  301. echo '{"tool_name":"Bash","command":"git status"}' | bash ~/.claude/hooks/tool-tips-post.sh
  302. # 测试 Glob 工具提示
  303. echo '{"tool_name":"Glob","pattern":"**/*.js"}' | bash ~/.claude/hooks/tool-tips-post.sh
  304. # 测试多命令提示
  305. echo '{"tool_name":"Bash","command":"git status && npm install && npm run build"}' | bash ~/.claude/hooks/tool-tips-post.sh
  306. ```
  307. **预期输出格式:**
  308. ```json
  309. {"systemMessage":"🌸 🖥️ 共3条命令:\n 1. git status — 查看代码仓库状态(有哪些文件被修改了)\n 2. npm install — 安装项目依赖包\n 3. npm run build — 构建/编译项目 🌸"}
  310. ```
  311. ### 查看 Claude Code 的 Hook 日志
  312. Claude Code 的 hook 执行日志在终端中可见。如果提示没有出现:
  313. 1. 确认 hook 脚本路径正确(使用正斜杠 `/`)
  314. 2. 确认脚本有执行权限(Linux/macOS: `chmod +x`)
  315. 3. 确认脚本换行符为 LF(不是 CRLF)
  316. 4. 手动运行上面的测试命令检查输出
  317. ### 检查 settings.json 格式
  318. ```bash
  319. # 验证 JSON 格式
  320. node -e "JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8'));console.log('OK')"
  321. ```
  322. ---
  323. ## 💡 实战经验
  324. ### 经验 1:Windows 路径问题
  325. **问题:** Windows 上 hook 脚本路径包含反斜杠或中文用户名。
  326. **解决:** settings.json 中的路径使用正斜杠:
  327. ```json
  328. "command": "C:/Users/你的用户名/.claude/hooks/tool-tips-post.sh"
  329. ```
  330. Claude Code 会自动通过 Git Bash 执行 `.sh` 脚本。
  331. ### 经验 2:CRLF 换行问题
  332. **问题:** 在 Windows 上编辑 `.sh` 文件后,换行符变成 CRLF,导致 bash 报错。
  333. **解决:** 确保使用 LF 换行符。在 VS Code 中,点击右下角的 `CRLF`,切换为 `LF`。
  334. 或在安装脚本中自动处理:
  335. ```bash
  336. # 将 CRLF 转为 LF
  337. sed -i 's/\r$//' tool-tips-post.sh
  338. ```
  339. ### 经验 3:Hook 输出格式
  340. **关键发现:** PostToolUse hook 的输出**必须**是以下格式才能在 UI 中显示:
  341. ```json
  342. {"systemMessage":"你要显示的文本"}
  343. ```
  344. - 必须是合法 JSON
  345. - 字段名必须是 `systemMessage`
  346. - exit code 必须为 0
  347. - stderr 在 exit code 0 时会被静默丢弃
  348. ### 经验 4:命令解释的准确性
  349. **原则:** 解释应该让完全不懂编程的人也能理解:
  350. - ❌ `执行命令: git status`
  351. - ✅ `执行命令: git status — 查看代码仓库状态(有哪些文件被修改了)`
  352. 每个解释都包含两部分:
  353. 1. **功能描述** — 这个命令做什么
  354. 2. **括号补充** — 用更通俗的话再解释一遍
  355. ### 经验 5:多命令处理
  356. 当 Bash 执行的命令包含多条语句时(用 `&&`, `||`, `;` 连接),脚本会:
  357. 1. 跳过注释行和空行
  358. 2. 按分隔符拆分命令
  359. 3. 逐条给出解释
  360. 4. 超过 3 条时折叠显示
  361. ---
  362. ## 📋 常见需求示例
  363. ### 需求 1:只显示 Bash 命令提示
  364. 修改 settings.json 的 matcher:
  365. ```json
  366. "matcher": "Bash"
  367. ```
  368. ### 需求 2:添加时间戳
  369. 修改 `get_tip()` 中的输出:
  370. ```bash
  371. "Bash")
  372. timestamp=$(date '+%H:%M:%S')
  373. echo "🖥️ [${timestamp}] 执行命令: $real_cmd — $(explain_cmd "$real_cmd")"
  374. ;;
  375. ```
  376. ### 需求 3:隐藏文件路径
  377. 修改 `get_tip()` 中的 Read/Write/Edit 分支,去掉文件名:
  378. ```bash
  379. "Read")
  380. echo "📖 读取文件 — 查看文件内容"
  381. ;;
  382. ```
  383. ### 需求 4:添加声音提醒
  384. ```bash
  385. "Bash")
  386. # macOS 声音提醒
  387. afplay /System/Library/Sounds/Ping.aiff &
  388. echo "🖥️ 执行命令: $real_cmd"
  389. ;;
  390. ```
  391. ### 需求 5:记录操作日志
  392. 在主逻辑中添加日志记录:
  393. ```bash
  394. # 在输出 systemMessage 之前记录日志
  395. log_file="$HOME/.claude/hooks/operation.log"
  396. echo "$(date '+%Y-%m-%d %H:%M:%S') | $tool_name | $file_path" >> "$log_file"
  397. ```
  398. ---
  399. ## 🪟 Windows 环境深度自检指南
  400. > **Windows 用户必读!** 90% 的 Hooks 失效问题都源于环境配置不当。请按以下五个阶段逐一排查。
  401. ### 快速自检命令
  402. 将以下内容直接粘贴给 Claude Code,让它帮你排查:
  403. > "你现在是一个 Windows 专家级运维工程师。请针对以下五个维度,深度扫描我的系统路径、配置和环境变量,找出可能导致 Claude Code Hooks 失效、命令不识别或路径冲突的问题,并给出修复建议。"
  404. ---
  405. ### [第一阶段] 基础底座:Shell 与权限
  406. | 检查项 | 命令 | 正确状态 |
  407. |--------|------|---------|
  408. | 终端版本 | `$PSVersionTable.PSVersion` | PowerShell 7+ (推荐) |
  409. | 执行策略 | `Get-ExecutionPolicy` | `RemoteSigned` 或 `Unrestricted` |
  410. | 管理员权限 | `([Security.Principal.WindowsPrincipal]::new([Security.Principal.WindowsIdentity]::GetCurrent())).IsInRole('Administrators')` | 按需判断 |
  411. **常见问题:**
  412. - **PowerShell 5.1 (蓝底)** → UTF-8 支持不完整,建议升级到 [PowerShell 7](https://aka.ms/PSWindows)
  413. - **ExecutionPolicy = Restricted** → 所有脚本被静默拦截,运行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
  414. - **非管理员终端** → 某些 npm 全局安装需要管理员权限
  415. ---
  416. ### [第二阶段] 核心动力:Node.js 与 NPM
  417. | 检查项 | 命令 | 正确状态 |
  418. |--------|------|---------|
  419. | Node 版本 | `node --version` | v14.0.0+ |
  420. | Node 路径 | `where node` | 路径无中文、无空格 |
  421. | npm 全局前缀 | `npm config get prefix` | 非用户文档目录 |
  422. | npm 全局包路径 | `npm root -g` | 路径无中文 |
  423. **常见问题:**
  424. - **路径含空格** (`C:\Program Files\nodejs`) → 通常没问题,但某些工具可能报错
  425. - **路径含中文** (`C:\Users\小明\...`) → 会导致 npm 全局包安装失败,建议修改 npm prefix:
  426. ```powershell
  427. npm config set prefix "C:\npm-global"
  428. # 然后将 C:\npm-global 加入系统 PATH
  429. ```
  430. - **nvm-windows 冲突** → 如果同时装了 nvm-windows 和 Node 官网包,可能路径冲突,建议只保留一个
  431. ---
  432. ### [第三阶段] 模拟环境:Git Bash 与 Unix 工具 ⚠️ 最关键
  433. | 检查项 | 命令 | 正确状态 |
  434. |--------|------|---------|
  435. | Git 安装 | `git --version` | git version 2.x |
  436. | sh 可用性 | `sh --version` | GNU Bash 4.x+ |
  437. | Git\bin 在 PATH | `$env:Path -split ';' | Select-String 'Git\\bin'` | 存在 |
  438. | Git\usr\bin 在 PATH | `$env:Path -split ';' | Select-String 'Git\\usr\\bin'` | 存在 |
  439. | 换行符策略 | `git config --global core.autocrlf` | **`input`** (必须是这个!) |
  440. | Hooks 路径 | `git config --global core.hooksPath` | 为空或未设置 |
  441. **⚠️ 头号死穴:`core.autocrlf = true`**
  442. 这是 Windows 上 Hooks 失效的第一大原因!当 `core.autocrlf = true` 时:
  443. 1. Git 会在 checkout 时自动把 LF 转为 CRLF
  444. 2. `.sh` 脚本变成 CRLF 换行
  445. 3. bash 执行 CRLF 脚本报 `\r: command not found`
  446. **修复:**
  447. ```bash
  448. git config --global core.autocrlf input
  449. ```
  450. > **为什么用 `input` 而不是 `false`?**
  451. > - `input`:提交时 CRLF → LF,检出时不动。Windows 写代码没问题,脚本也不会被破坏
  452. > - `false`:完全不管换行符。如果你用 Windows 编辑器写代码,可能会把 CRLF 提交到仓库
  453. **验证 sh 可用:**
  454. ```powershell
  455. # 应该输出 bash 版本信息
  456. sh --version
  457. # 如果报错,检查 PATH 是否包含 Git\bin
  458. $env:Path -split ';' | Where-Object { $_ -match 'Git\\\\bin' }
  459. ```
  460. ---
  461. ### [第四阶段] 文件系统:字符编码与路径
  462. | 检查项 | 命令 | 正确状态 |
  463. |--------|------|---------|
  464. | UTF-8 区域设置 | 打开: `intl.cpl` → 管理 → 更改系统区域设置 | 勾选 "Beta: 使用 Unicode UTF-8" |
  465. | 长路径支持 | `Get-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled` | `LongPathsEnabled = 1` |
  466. | 用户名路径 | `echo $env:USERPROFILE` | 无中文字符 |
  467. **常见问题:**
  468. - **中文用户名** (`C:\Users\古古`) → 通常没问题,但某些老旧工具可能报错
  469. - **项目路径含中文** (`D:\项目资料\AI工具`) → 极易出问题!建议改为英文路径
  470. - **长路径** (`C:\Users\xxx\.claude\plugins\cache\...\node_modules\...`) → 超过 260 字符会导致 Node 报错
  471. **开启长路径支持:**
  472. ```powershell
  473. # 管理员 PowerShell 运行
  474. Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1
  475. # 需要重启生效
  476. ```
  477. ---
  478. ### [第五阶段] 网络与代理
  479. | 检查项 | 命令 | 正确状态 |
  480. |--------|------|---------|
  481. | HTTP 代理 | `echo $env:HTTP_PROXY` | 按需设置 |
  482. | HTTPS 代理 | `echo $env:HTTPS_PROXY` | 按需设置 |
  483. | npm 代理 | `npm config get proxy` | 按需设置 |
  484. | SSL 验证 | `npm config get strict-ssl` | `true` |
  485. **国内用户特别注意:**
  486. 如果使用公司代理或 VPN:
  487. ```powershell
  488. # 如果代理导致 SSL 错误(不推荐,仅调试用)
  489. npm config set strict-ssl false
  490. # 推荐方式:使用国内镜像
  491. npm config set registry https://registry.npmmirror.com
  492. ```
  493. ---
  494. ### 一键自检脚本
  495. 将以下内容保存为 `check-env.ps1` 运行,或直接粘贴到 PowerShell:
  496. ```powershell
  497. Write-Host "`n🌸 Cute Claude Hooks — Windows 环境自检 🌸`n" -ForegroundColor Magenta
  498. $pass = "✅"; $fail = "❌"; $warn = "⚠️"
  499. # Stage 1: Shell
  500. Write-Host "[第一阶段] Shell 与权限" -ForegroundColor Cyan
  501. $psVer = $PSVersionTable.PSVersion.Major
  502. Write-Host ($psVer -ge 7 ? "$pass PowerShell $psVer" : "$warn PowerShell $psVer (建议升级到 7+)")
  503. $policy = Get-ExecutionPolicy
  504. Write-Host ($policy -ne 'Restricted' ? "$pass 执行策略: $policy" : "$fail 执行策略: $policy (需设为 RemoteSigned)")
  505. # Stage 2: Node
  506. Write-Host "`n[第二阶段] Node.js" -ForegroundColor Cyan
  507. try { $n = node --version 2>$null; Write-Host "$pass Node $n" } catch { Write-Host "$fail Node 未安装" }
  508. $prefix = npm config get prefix 2>$null
  509. Write-Host ($prefix -match '[\u4e00-\u9fff]' ? "$fail npm prefix 含中文: $prefix" : "$pass npm prefix: $prefix")
  510. # Stage 3: Git Bash (关键!)
  511. Write-Host "`n[第三阶段] Git Bash (最关键)" -ForegroundColor Yellow
  512. try { $g = git --version 2>$null; Write-Host "$pass $g" } catch { Write-Host "$fail Git 未安装" }
  513. $autocrlf = git config --global core.autocrlf 2>$null
  514. Write-Host ($autocrlf -eq 'input' ? "$pass core.autocrlf = input" : "$fail core.autocrlf = $autocrlf (必须改为 input!)")
  515. $hookPath = git config --global core.hooksPath 2>$null
  516. Write-Host ($hookPath ? "$warn core.hooksPath = $hookPath (可能拦截 Claude Hooks)" : "$pass 无全局 hooksPath 覆盖")
  517. # Stage 4: Encoding
  518. Write-Host "`n[第四阶段] 文件系统" -ForegroundColor Cyan
  519. $userPath = $env:USERPROFILE
  520. Write-Host ($userPath -match '[\u4e00-\u9fff]' ? "$warn 用户路径含中文: $userPath" : "$pass 用户路径: $userPath")
  521. # Stage 5: Network
  522. Write-Host "`n[第五阶段] 网络" -ForegroundColor Cyan
  523. $reg = npm config get registry 2>$null
  524. Write-Host ($reg -match 'npmmirror' ? "$pass npm 镜像: $reg" : "$pass npm 源: $reg")
  525. Write-Host "`n🌸 自检完成!如有 ❌ 项请参考上方修复建议 🌸`n" -ForegroundColor Magenta
  526. ```
  527. ---
  528. ## 🐛 问题排查
  529. ### 提示不显示
  530. **排查步骤:**
  531. 1. **检查 settings.json 格式**
  532. ```bash
  533. node -e "console.log(JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8')).hooks)"
  534. ```
  535. 2. **手动测试 hook 脚本**
  536. ```bash
  537. echo '{"tool_name":"Read","file_path":"test.py"}' | bash ~/.claude/hooks/tool-tips-post.sh
  538. ```
  539. 应该输出 `{"systemMessage":"..."}`
  540. 3. **检查脚本换行符**
  541. ```bash
  542. file ~/.claude/hooks/tool-tips-post.sh
  543. # 应该显示: ASCII text, not ASCII text, with CRLF line terminators
  544. ```
  545. 4. **检查脚本权限**(Linux/macOS)
  546. ```bash
  547. ls -la ~/.claude/hooks/tool-tips-post.sh
  548. # 应该有执行权限
  549. chmod +x ~/.claude/hooks/tool-tips-post.sh
  550. ```
  551. ### 中文乱码
  552. 确保系统编码为 UTF-8:
  553. - Windows: 设置 → 时间和语言 → 语言 → 管理语言设置 → 更改系统区域设置 → 勾选 Beta: 使用 Unicode UTF-8
  554. - Linux/macOS: 通常默认 UTF-8
  555. ### 安装脚本报错
  556. ```bash
  557. # 查看详细错误
  558. cute-claude-hooks-install 2>&1 | tee install.log
  559. ```
  560. ---
  561. ## 📁 文件位置速查
  562. | 文件 | 位置 | 说明 |
  563. |------|------|------|
  564. | Hook 脚本 | `~/.claude/hooks/tool-tips-post.sh` | 工具提示脚本 |
  565. | 用户配置 | `~/.claude/settings.json` | hooks 配置 |
  566. | 汉化字典 | `~/.claude/localize/keyword.js` | 翻译词条 |
  567. | 汉化引擎 | `~/.claude/localize/localize.js` | 替换脚本 |
  568. | Claude Code 备份 | `~/.claude/localize/cli.bak.js` | 原始英文文件 |
  569. | Claude Code 主体 | Claude Code 安装目录的 `cli.js` | 被汉化的目标文件 |
  570. ---
  571. ## 🔄 恢复默认
  572. ### 恢复英文界面
  573. ```bash
  574. # 方式一:使用卸载命令
  575. cute-claude-hooks-restore
  576. # 方式二:手动恢复
  577. node ~/.claude/localize/localize.js --restore
  578. ```
  579. ### 移除工具提示
  580. 编辑 `~/.claude/settings.json`,删除 `hooks` 段:
  581. ```json
  582. {
  583. "hooks": {}
  584. }
  585. ```
  586. ### 完全卸载
  587. ```bash
  588. # 1. 恢复英文界面
  589. cute-claude-hooks-restore
  590. # 2. 删除 hook 文件
  591. rm -rf ~/.claude/hooks/
  592. # 3. 删除汉化文件
  593. rm -rf ~/.claude/localize/
  594. # 4. 卸载 npm 包
  595. npm uninstall -g cute-claude-hooks
  596. ```
  597. ---
  598. ## 🔗 相关资源
  599. | 资源 | 链接 |
  600. |------|------|
  601. | GitHub 仓库 | https://github.com/gugug168/cute-claude-hooks |
  602. | npm 包 | https://www.npmjs.com/package/cute-claude-hooks |
  603. | Claude Code 官方 | https://claude.ai/code |
  604. | Claude Code 文档 | https://docs.anthropic.com/en/docs/claude-code |
  605. | 问题反馈 | https://github.com/gugug168/cute-claude-hooks/issues |
  606. ---
  607. ## 📖 汉化关键词表
  608. 当前共有 **151** 条翻译词条,覆盖 Claude Code 界面的主要文本。
  609. **主要分类:**
  610. | 分类 | 词条数 | 示例 |
  611. |------|--------|------|
  612. | 配置面板 | 30+ | Theme → 主题, Model → 模型 |
  613. | 斜杠命令 | 20+ | /help → 获取帮助 |
  614. | 状态信息 | 25+ | Auto-compact → 自动压缩 |
  615. | 快捷键 | 15+ | Esc to cancel → Esc 取消 |
  616. | 欢迎界面 | 10+ | Welcome back → 欢迎回来 |
  617. | 其他界面 | 50+ | 各类提示和说明文本 |
  618. 完整词条列表见 `localize/keyword.js` 文件。
  619. ---
  620. ## ❓ 常见问题
  621. ### Q: 支持 macOS 和 Linux 吗?
  622. **A:** 完全支持!安装脚本自动检测操作系统。
  623. ### Q: 更新 Claude Code 后汉化会丢失吗?
  624. **A:** 会的。Claude Code 更新会覆盖 cli.js。重新运行 `cute-claude-hooks-install` 选择「仅安装界面汉化」即可。
  625. ### Q: 工具提示支持哪些命令?
  626. **A:** 支持 80+ 常用命令的中文解释,涵盖 git、npm、pip、docker、文件操作、网络命令等。
  627. ### Q: 可以只安装工具提示不汉化界面吗?
  628. **A:** 可以。安装时选择「仅安装工具提示」。
  629. ### Q: 中文用户名路径会有问题吗?
  630. **A:** 一般不会。如果遇到编码问题,确保系统编码为 UTF-8。
  631. ### Q: 修改 hook 脚本后需要重启 Claude Code 吗?
  632. **A:** 不需要。每次工具执行都会调用 hook 脚本,修改立即生效。
  633. ### Q: 为什么提示没有显示颜色?
  634. **A:** Claude Code 的 hook 系统通过 `systemMessage` 渲染文本,目前不支持 ANSI 颜色代码。提示会以默认颜色显示。
  635. ---
  636. ## 🔬 技术说明
  637. ### Hook 工作流程
  638. ```
  639. Claude Code 执行工具
  640. ↓
  641. 触发 PostToolUse 事件
  642. ↓
  643. 匹配 matcher 规则
  644. ↓
  645. 执行 hook command (tool-tips-post.sh)
  646. ↓
  647. 从 stdin 读取工具信息 JSON
  648. ↓
  649. 提取 tool_name, file_path, pattern, command
  650. ↓
  651. 调用 get_tip() 生成中文提示
  652. ↓
  653. 输出 {"systemMessage":"..."} 到 stdout
  654. ↓
  655. Claude Code 读取并显示在界面上
  656. ```
  657. ### JSON 输入格式(stdin)
  658. Claude Code 通过 stdin 传递工具信息:
  659. ```json
  660. {
  661. "tool_name": "Bash",
  662. "file_path": "src/index.js",
  663. "pattern": "**/*.js",
  664. "command": "git status && npm install"
  665. }
  666. ```
  667. ### JSON 输出格式(stdout)
  668. Hook 必须输出以下格式:
  669. ```json
  670. {"systemMessage":"🌸 🖥️ 执行命令: git status — 查看代码仓库状态 🌸"}
  671. ```
  672. **注意事项:**
  673. - 必须是单行合法 JSON
  674. - `systemMessage` 中的换行用 `\n` 表示
  675. - 双引号用 `\"` 转义
  676. - 反斜杠用 `\\` 转义
  677. ### 多命令解析逻辑
  678. 1. 从 `command` 字段提取 bash 命令
  679. 2. 将 JSON 转义的 `\n` 转为实际换行
  680. 3. 跳过注释行(`#` 开头)和空行
  681. 4. 按分隔符 `&&`, `||`, `;` 拆分
  682. 5. 对每条命令调用 `explain_cmd()` 生成解释
  683. 6. 超过 3 条时折叠为 `...(还有N条)`
  684. ---
  685. ## 📝 更新日志
  686. ### v1.0.6 (当前版本)
  687. - 🔄 **重大更新**: Hook 输出改为 `systemMessage` JSON 格式
  688. - 📖 **新增**: 80+ 命令的中文解释(小白友好)
  689. - 📋 **新增**: 多命令场景的逐条解释
  690. - 🧹 **移除**: 命令截断(`head -c`),现在显示完整命令
  691. - 🔧 **修复**: 跳过 Bash 命令中的注释行
  692. - 🔧 **修复**: JSON 转义换行符 `\n` 正确转换为实际换行
  693. ### v1.0.5
  694. - 🌸 界面汉化引擎改为 Node.js 实现
  695. - 📝 关键词字典改为 JavaScript 模块
  696. - 🧹 移除 Python/Shell 版本的汉化脚本
  697. ### v1.0.4
  698. - 🪟 Windows 兼容性改进
  699. - 🔧 修复路径中的中文编码问题
  700. ### v1.0.0
  701. - 🎉 初始版本发布
  702. - 📖 基础工具中文提示
  703. - 🌐 界面汉化支持
  704. ---
  705. ## 🤝 贡献指南
  706. ### 如何贡献
  707. 1. Fork 本仓库
  708. 2. 创建功能分支:`git checkout -b feature/your-feature`
  709. 3. 提交修改:`git commit -m 'feat: 添加某某功能'`
  710. 4. 推送分支:`git push origin feature/your-feature`
  711. 5. 创建 Pull Request
  712. ### 贡献方向
  713. 特别欢迎以下贡献:
  714. - 🌍 **新的汉化词条** — 补充 keyword.js 中缺少的翻译
  715. - 🔧 **新的命令解释** — 为 explain_cmd() 添加更多命令
  716. - 📸 **效果截图** — 展示实际使用效果
  717. - 📝 **文档改进** — 修正错误或补充说明
  718. - 🐛 **Bug 修复** — 修复已知问题
  719. - 🌐 **多语言支持** — 添加其他语言版本
  720. ### 提交规范
  721. 使用 Conventional Commits 格式:
  722. ```
  723. feat: 添加 kubectl 命令解释
  724. fix: 修复 Windows 中文路径编码问题
  725. docs: 更新 SKILL.md 安装说明
  726. refactor: 简化 get_tip() 函数逻辑
  727. ```
  728. ---
  729. ## 📄 许可证
  730. MIT License - 自由使用、修改和分发
  731. ---
  732. <p align="center">
  733. Made with 🌸 by <a href="https://github.com/gugug168">gugug168</a>
  734. </p>
README.md · README · 430 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="./assets/readme/hero.svg" width="100%" alt="Cute Claude Hooks:为 Claude Code 提供中文工具提示;旧版界面汉化有明确版本边界。">
  3. </p>
  4. 中文增强工具包。当前真实可用核心是工具提示与完成通知;界面汉化仅适用于 Claude Code 2.1.112 及以前版本。
  5. ## 一眼看懂
  6. | 价值 | 真实证据 |
  7. | --- | --- |
  8. | 为 Claude Code 提供中文工具提示;旧版界面汉化有明确版本边界。 | 工具提示可用 · 三平台 · 兼容性声明 |
  9. ## 从这里开始
  10. ```text
  11. npm install -g cute-claude-hooks
  12. ```
  13. ## 完整说明
  14. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  15. [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-orange.svg)](https://claude.ai/code)
  16. [![npm version](https://img.shields.io/npm/v/cute-claude-hooks.svg)](https://www.npmjs.com/package/cute-claude-hooks)
  17. [![Cross Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-green.svg)](https://github.com/gugug168/cute-claude-hooks)
  18. [![GitHub Actions](https://github.com/gugug168/cute-claude-hooks/actions/workflows/test-localization.yml/badge.svg)](https://github.com/gugug168/cute-claude-hooks/actions/workflows/test-localization.yml)
  19. > ⚠️ **重要版本兼容性公告 (2025-05)**
  20. >
  21. > Anthropic 从 **Claude Code v2.1.113** 开始将 npm 包从 Node.js 脚本 (`cli.js`) 改为**编译二进制** (`claude.exe`)。
  22. > 这导致所有基于字符串替换的界面汉化方案**彻底失效**,包括本项目的界面汉化功能。
  23. >
  24. > | Claude Code 版本 | 工具提示 Hook | 界面汉化 |
  25. > |-----------------|:------------:|:--------:|
  26. > | ≤ 2.1.112 | ✅ 可用 | ✅ 可用 |
  27. > | ≥ 2.1.113 | ✅ 可用 | ❌ **已失效** |
  28. >
  29. > **工具提示 Hook 不受影响**,所有版本均可正常使用。界面汉化功能等待后续适配方案。
  30. > 🌸 让 Claude Code 拥有中文体验!工具提示 Hook,专为编程小白设计(界面汉化仅支持 ≤ 2.1.112 版本)
  31. ## 📸 效果预览
  32. ### 🎯 工具提示效果
  33. 每个 Claude Code 执行的操作都会显示中文提示,让你清楚知道它在做什么:
  34. ![工具提示详细效果](./screenshots/03-tool-tips-detailed.png)
  35. ![工具提示带翻译效果](./screenshots/03-tool-tips-with-translation.png)
  36. ### 🌐 界面汉化效果(⚠️ 仅 ≤ 2.1.112,新版已失效)
  37. ![配置面板中文效果](./screenshots/02-config-chinese.png)
  38. ![斜杠命令中文效果](./screenshots/04-slash-commands-chinese.png)
  39. > ⚠️ 以上界面汉化截图来自旧版本(≤ 2.1.112)。新版 Claude Code(≥ 2.1.113)已改为编译二进制,此功能无法使用。
  40. ### 📝 汉化对照表
  41. | 原文 (English) | 译文 (中文) |
  42. |---------------|------------|
  43. | Welcome back! | 欢迎回来! |
  44. | Auto-compact | 自动压缩 |
  45. | Thinking mode | 深度思考模式 |
  46. | Esc to cancel | Esc 取消 |
  47. | Enter to submit · Esc to cancel | Enter 提交 · Esc 取消 |
  48. | Recent activity | 最近活动记录 |
  49. | Tips for getting started | 入门技巧 |
  50. ### 📋 支持的命令解释
  51. | 命令类型 | 示例命令 | 中文解释 |
  52. |---------|---------|---------|
  53. | **GitHub CLI** | `gh run list` | 🚀 列出 GitHub Actions 运行记录(查看自动化测试历史) |
  54. | | `gh auth status` | 🔐 检查 GitHub 登录状态(看是否已登录、登录的是哪个账号) |
  55. | | `gh repo create` | 📦 在 GitHub 上创建新仓库(新建一个代码存储库) |
  56. | **Git** | `git push` | 📚 推送到远程仓库(上传代码到服务器) |
  57. | | `git log` | 📜 查看提交日志(看所有修改记录) |
  58. | | `git status` | 📊 查看工作区状态(哪些文件改了) |
  59. | **npm** | `npm install` | 📦 安装依赖包(下载项目所需的库) |
  60. | | `npm run build` | 🏗️ 构建项目(编译打包代码) |
  61. | **pip** | `pip install` | 📦 安装 Python 包(下载 Python 库) |
  62. | | `pip list` | 📋 列出已安装的包(查看 Python 库) |
  63. | **网络** | `curl` | 🌐 获取网页内容(下载或查看网页数据) |
  64. | | `ping` | 🌐 测试网络连接(检查能否连上某个地址) |
  65. | **文件** | `cat` | 📖 查看文件内容(打开文本文件阅读) |
  66. | | `mkdir` | 📁 创建新目录(新建文件夹) |
  67. > 💡 支持 **100+** 常用命令的详细中文解释!
  68. ---
  69. ## ✨ 特性
  70. - 📖 **中文操作提示** - 每个操作都有详细的中文解释,小白也能看懂(所有版本可用)
  71. - 🌸 **界面汉化** - 配置面板、命令说明、快捷键提示全中文(⚠️ 仅 ≤ 2.1.112)
  72. - 🖥️ **跨平台** - Windows/macOS/Linux 通用
  73. - 📦 **轻量级** - 无依赖,秒级安装
  74. - 🔧 **易自定义** - 完整的自定义指南
  75. - 🇨🇳 **国内加速** - 支持 npmmirror 镜像安装
  76. - 🧪 **自动测试** - GitHub Actions 三平台自动测试
  77. ---
  78. ## 📦 安装
  79. ### 功能与安装方式对应表
  80. | 功能 | NPM 安装 | 手动/脚本安装 | 版本要求 |
  81. |------|:--------:|:------------:|---------|
  82. | 📖 工具提示 Hook (tool-tips-post.sh) | ✅ | ✅ | 所有版本 |
  83. | 🔔 任务完成通知 Hook (task-done-notify.sh) | ✅ | ✅ | 所有版本 |
  84. | 🌐 界面汉化 (配置面板、斜杠命令等) | ⚠️ | ❌ | **仅 ≤ 2.1.112** |
  85. > ⚠️ **界面汉化已失效**:Claude Code v2.1.113 起改为编译二进制,无法再通过字符串替换修改界面文案。工具提示 Hook 不受影响,所有版本均可使用。
  86. ### 方式一:NPM 安装(推荐)
  87. > ⚠️ 安装前请先检查版本:`claude --version`。如果你的版本 ≥ 2.1.113,界面汉化将不可用,但仍可安装工具提示 Hook。
  88. ```bash
  89. # 全局安装
  90. npm install -g cute-claude-hooks
  91. # 运行安装脚本
  92. cute-claude-hooks-install
  93. # 恢复英文界面
  94. cute-claude-hooks-restore
  95. ```
  96. **或者使用 npx(无需全局安装):**
  97. ```bash
  98. npx cute-claude-hooks-install
  99. ```
  100. ### 方式二:国内加速安装(推荐国内用户)
  101. 如果 npm 官方源速度慢,可以使用国内镜像:
  102. ```bash
  103. # 使用 npmmirror 镜像安装
  104. npm install -g cute-claude-hooks --registry=https://registry.npmmirror.com
  105. # 运行安装脚本
  106. cute-claude-hooks-install
  107. ```
  108. **或者使用 npx:**
  109. ```bash
  110. npx cute-claude-hooks-install
  111. ```
  112. ### 安装选项
  113. ```
  114. ╔════════════════════════════════════════╗
  115. ║ 🌸 Cute Claude Hooks 安装向导 🌸 ║
  116. ╠════════════════════════════════════════╣
  117. ║ [1] 仅安装工具提示 (推荐新手) ║
  118. ║ [2] 仅安装界面汉化 ║
  119. ║ [3] 全部安装 (完整中文体验) ← 推荐 ║
  120. ║ [4] 卸载 ║
  121. ╚════════════════════════════════════════╝
  122. ```
  123. ---
  124. ## 🎯 功能详解
  125. ### 1️⃣ 工具提示 (Tool Tips)
  126. 安装后,Claude Code 每次执行操作都会显示中文提示:
  127. ```
  128. ✅ 操作成功示例:
  129. 🌸 小白提示:🔐 检查 GitHub 登录状态(看是否已登录、登录的是哪个账号) 🌸
  130. 🌸 小白提示:🚀 列出 GitHub Actions 运行记录(查看自动化测试历史) 🌸
  131. 🌸 小白提示:📦 安装依赖包(下载项目所需的库) 🌸
  132. ```
  133. ### 2️⃣ 界面汉化 (Localization) — ⚠️ 仅支持 Claude Code ≤ 2.1.112
  134. > **注意**: Claude Code 从 v2.1.113 开始改为编译二进制发布,界面汉化功能已失效。此功能仅在旧版本(≤ 2.1.112)上可用。
  135. 将 Claude Code 的英文界面翻译成中文:
  136. - ✅ `/config` 配置面板汉化
  137. - ✅ 斜杠命令说明汉化
  138. - ✅ 快捷键提示汉化
  139. - ✅ 欢迎界面汉化
  140. - ✅ 状态信息汉化
  141. ### 3️⃣ 恢复功能 (Restore) — 仅 ≤ 2.1.112
  142. 随时可以恢复到英文界面:
  143. **Windows:**
  144. ```powershell
  145. ~/.claude/localize/restore.ps1
  146. ```
  147. **macOS/Linux:**
  148. ```bash
  149. ~/.claude/localize/restore.sh
  150. ```
  151. ---
  152. ## 🪟 Windows 手动安装(自动安装失败时使用)
  153. 如果 `cute-claude-hooks-install` 运行后中文提示没有出现,按以下步骤手动安装:
  154. ### 前提条件
  155. - 已安装 [Git for Windows](https://git-scm.com/downloads/win)
  156. - 已安装 [Node.js](https://nodejs.org/) 14+
  157. ### 步骤一:复制 hook 脚本
  158. ```powershell
  159. # 创建 hooks 目录
  160. mkdir -Force "$env:USERPROFILE\.claude\hooks"
  161. # 复制脚本(替换为你的 npm 全局目录)
  162. $npmDir = (npm root -g).Trim()
  163. copy "$npmDir\cute-claude-hooks\tool-tips-post.sh" "$env:USERPROFILE\.claude\hooks\"
  164. ```
  165. ### 步骤二:确认 bash 可用
  166. ```powershell
  167. # 检查 bash 是否在 PATH 中
  168. bash --version
  169. # 如果找不到,设置环境变量指向你的 Git Bash
  170. # 将下面的路径改为你实际的 Git Bash 安装路径
  171. $env:CLAUDE_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"
  172. ```
  173. ### 步骤三:手动编辑 settings.json
  174. 打开 `~/.claude/settings.json`,添加或修改 `hooks` 段:
  175. ```json
  176. {
  177. "hooks": {
  178. "PostToolUse": [
  179. {
  180. "matcher": "Bash|Read|Write|Edit|Glob|Grep|mcp__*",
  181. "hooks": [
  182. {
  183. "type": "command",
  184. "command": "\"C:/Users/你的用户名/.claude/hooks/tool-tips-post.sh\""
  185. }
  186. ]
  187. }
  188. ]
  189. }
  190. }
  191. ```
  192. > **注意**:路径使用正斜杠 `/`,不要用反斜杠 `\`
  193. ### 步骤四:验证
  194. ```powershell
  195. # 手动测试 hook 脚本
  196. echo '{"tool_name":"Read","file_path":"test.py"}' | bash "$env:USERPROFILE\.claude\hooks\tool-tips-post.sh"
  197. ```
  198. 如果看到 `{"systemMessage":"🌸 📖 读取文件: test.py — 查看这个文件里写了什么 🌸"}`,说明脚本正常工作。
  199. ### 常见问题排查
  200. | 问题 | 解决方案 |
  201. |------|---------|
  202. | `bash: command not found` | 安装 [Git for Windows](https://git-scm.com/downloads/win) 并确保在 PATH 中 |
  203. | 脚本无输出 | 检查 .sh 文件换行符是否为 LF(非 CRLF) |
  204. | 中文用户名路径乱码 | 确保系统编码为 UTF-8:设置 → 时间和语言 → 语言 → 管理语言设置 → 更改系统区域设置 → 勾选 Beta: 使用 Unicode UTF-8 |
  205. | settings.json 格式错误 | 用 `node -e "JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8'));console.log('OK')"` 验证 |
  206. ### Windows 五步深度自检
  207. > Windows 用户遇到疑难问题?把下面这段粘贴给 Claude Code,让它帮你排查:
  208. >
  209. > ```
  210. > "你现在是 Windows 专家级运维工程师。请深度扫描我的系统环境,找出导致 Claude Code Hooks 失效的问题。检查项:1) PowerShell 版本和执行策略 2) Node.js 路径是否含中文/空格 3) sh 是否可用(Git bin 是否在 PATH 中)4) git config core.autocrlf 值(必须是 input,true 会导致 CRLF 损坏脚本)5) 系统是否开启 UTF-8 编码支持。"
  211. > ```
  212. 详细排查步骤见 [SKILL.md - Windows 环境深度自检](./SKILL.md#-windows-环境深度自检指南)。
  213. ## 🔧 快速自定义
  214. ### 修改提示文本
  215. 编辑 `~/.claude/hooks/tool-tips-post.sh` 中的 `get_tip()` 函数:
  216. ```bash
  217. # 修改工具提示文本
  218. "Read")
  219. echo "📖 正在读取文件 — 看看里面写了什么"
  220. ;;
  221. # 修改命令解释
  222. git)
  223. case "$sub" in
  224. status) echo "查看仓库状态" ;;
  225. log) echo "查看提交历史" ;;
  226. esac
  227. ;;
  228. ```
  229. > **注意:** Claude Code 的 hook 输出不支持自定义颜色,提示会以默认颜色显示。
  230. ### 添加新的汉化词条(仅 ≤ 2.1.112)
  231. 编辑 `~/.claude/localize/keyword.js`:
  232. ```javascript
  233. module.exports = {
  234. // 添加新的翻译条目
  235. 'Your English text': '你的中文翻译',
  236. // ...
  237. }
  238. ```
  239. 然后重新执行 `node ~/.claude/localize/localize.js` 即可。
  240. ---
  241. ## 📁 文件结构
  242. ```
  243. cute-claude-hooks/
  244. ├── 📄 README.md # 本文档
  245. ├── 📄 SKILL.md # 完整自定义指南
  246. ├── 📄 LICENSE # MIT 许可证
  247. ├── 🔧 tool-tips-post.sh # 工具提示 Hook 脚本
  248. ├── 📁 bin/ # 安装脚本
  249. │ ├── 📦 install.js # 统一安装器(hooks + 汉化)
  250. │ └── 📦 restore.js # 恢复英文界面
  251. ├── 📁 localize/ # 界面汉化模块
  252. │ ├── 📝 keyword.js # 关键词翻译字典 (151词条)
  253. │ └── 🔧 localize.js # Node.js 全局替换汉化引擎
  254. ├── 📁 .github/
  255. │ └── 📁 workflows/
  256. │ └── 🧪 test-localize.yml # 跨平台自动测试
  257. └── 📁 screenshots/ # 截图目录
  258. ```
  259. ---
  260. ## 🧪 自动测试
  261. 本项目使用 GitHub Actions 进行跨平台自动测试:
  262. [![Test Claude Code Localization](https://github.com/gugug168/cute-claude-hooks/actions/workflows/test-localization.yml/badge.svg)](https://github.com/gugug168/cute-claude-hooks/actions/workflows/test-localization.yml)
  263. | 平台 | 状态 | 测试内容 |
  264. |-----|------|---------|
  265. | 🐧 Linux (Ubuntu) | ✅ 通过 | Hook脚本语法 + 界面汉化 (135词条) |
  266. | 🍎 macOS | ✅ 通过 | Hook脚本语法 + 界面汉化 (135词条) |
  267. | 🪟 Windows | ✅ 通过 | Hook脚本语法 + 界面汉化 (135词条) |
  268. ### 测试覆盖
  269. - ✅ **工具提示测试** - 验证 Hook 脚本输出中文提示
  270. - ✅ **界面汉化测试** - 验证 cli.js 成功翻译 151 个词条
  271. - ✅ **全局替换验证** - 匹配双引号/单引号/模板字符串中的所有键值
  272. - ✅ **备份文件检查** - 确保 cli.bak.js 备份存在
  273. ---
  274. ## 📚 完整文档
  275. 查看 [SKILL.md](./SKILL.md) 获取:
  276. - 🌸 界面汉化详细说明
  277. - 🎨 颜色/Emoji 自定义
  278. - 🔧 进阶自定义技巧
  279. - 🆕 添加新功能
  280. - 📖 实战经验和踩坑记录
  281. - 💡 常见需求示例
  282. ---
  283. ## 🤝 贡献
  284. 欢迎提交 Issue 和 PR!特别是:
  285. - 🌍 新的汉化词条
  286. - 🔧 新的命令解释
  287. - 📸 效果截图
  288. - 📝 文档改进
  289. - 🐛 Bug 修复
  290. ### 贡献截图
  291. 如果你使用了本项目,欢迎贡献效果截图:
  292. 1. Fork 本仓库
  293. 2. 将截图放入 `screenshots/` 目录
  294. 3. 提交 Pull Request
  295. ---
  296. ## 🌸 推荐搭配
  297. 如果你想要更完整的中文体验,可以搭配使用:
  298. - **Claude Code** - Anthropic 官方 AI 编程助手
  299. ---
  300. ## 📄 许可证
  301. [MIT License](./LICENSE) - 自由使用、修改和分发
  302. ---
  303. <p align="center">
  304. Made with 🌸 by <a href="https://github.com/gugug168">gugug168</a>
  305. </p>
  306. <p align="center">
  307. 如果这个项目对你有帮助,请给一个 ⭐ Star 支持一下!
  308. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.