212 lines
4.3 KiB
Markdown
212 lines
4.3 KiB
Markdown
# Claude Code Hook 使用指南
|
||
|
||
## 📁 当前可用的 Hooks
|
||
|
||
### 1. `hello.py` - 原始 Hook
|
||
- **功能**: 基础的项目状态检测
|
||
- **用途**: 向 AI 传递项目上下文信息
|
||
|
||
### 2. `welcome.py` - 欢迎信息 Hook ⭐
|
||
- **功能**: 显示彩色的欢迎信息
|
||
- **内容包括**:
|
||
- 用户名
|
||
- 当前时间
|
||
- 工作目录
|
||
- Git 分支
|
||
- Git 工作目录状态
|
||
- **特点**: 美观的彩色输出
|
||
|
||
### 3. `system_info.py` - 系统信息 Hook ⭐
|
||
- **功能**: 显示详细的系统和项目统计
|
||
- **内容包括**:
|
||
- 操作系统信息
|
||
- Python 版本
|
||
- 项目文件统计（Python/JS/TS/Markdown 文件数）
|
||
- Git 仓库统计（提交数、分支数、最新提交）
|
||
- **特点**: 详细的项目概览
|
||
|
||
## 🔧 如何使用
|
||
|
||
### 选择要启用的 Hook
|
||
|
||
在 `.claude/settings.json` 中配置（如果不存在则创建）：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"SessionStart": [
|
||
{
|
||
"type": "command",
|
||
"command": "python ~/.claude/hooks/welcome.py"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
或者使用多个 Hook：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"SessionStart": [
|
||
{
|
||
"type": "command",
|
||
"command": "python ~/.claude/hooks/welcome.py"
|
||
},
|
||
{
|
||
"type": "command",
|
||
"command": "python ~/.claude/hooks/system_info.py"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 在 Windows 上路径
|
||
|
||
Windows 上使用：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"SessionStart": [
|
||
{
|
||
"type": "command",
|
||
"command": "python C:\\Users\\starm\\.claude\\hooks\\welcome.py"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📝 Hook 工作原理
|
||
|
||
### 输入格式
|
||
Hook 通过 stdin 接收 JSON 格式的输入数据。
|
||
|
||
### 输出格式
|
||
Hook 必须输出 JSON 格式的数据：
|
||
|
||
```python
|
||
output = {
|
||
"hookSpecificOutput": {
|
||
"hookEventName": "SessionStart",
|
||
"additionalContext": "传递给 AI 的上下文信息"
|
||
}
|
||
}
|
||
print(json.dumps(output))
|
||
```
|
||
|
||
### 显示内容给用户
|
||
|
||
有两种方式显示内容给终端用户：
|
||
|
||
#### 方式 1: 输出到 stderr
|
||
```python
|
||
print("这是显示给用户的信息", file=sys.stderr)
|
||
```
|
||
|
||
#### 方式 2: 返回消息
|
||
```python
|
||
output = {
|
||
"hookSpecificOutput": {
|
||
"hookEventName": "SessionStart",
|
||
"message": "显示给用户的消息",
|
||
"additionalContext": "传递给 AI 的上下文"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🎨 自定义你的 Hook
|
||
|
||
### 修改显示内容
|
||
|
||
编辑 Hook 文件，自定义要显示的信息：
|
||
|
||
```python
|
||
# 在 welcome.py 或 system_info.py 中修改
|
||
def display_custom_info():
|
||
print(f"{GREEN}自定义内容:{END} 你的信息", file=sys.stderr)
|
||
```
|
||
|
||
### 添加新的检测
|
||
|
||
```python
|
||
# 检测项目类型
|
||
if os.path.exists("package.json"):
|
||
project_type = "Node.js"
|
||
elif os.path.exists("Cargo.toml"):
|
||
project_type = "Rust"
|
||
# 添加更多检测...
|
||
```
|
||
|
||
## 📊 可用的 Hook 事件
|
||
|
||
| 事件 | 触发时机 | 用途 |
|
||
|------|---------|------|
|
||
| `SessionStart` | 会话开始 | 显示欢迎信息、系统信息 |
|
||
| `PreToolUse` | 工具使用前 | 验证、阻止操作 |
|
||
| `PostToolUse` | 工具使用后 | 格式化、测试 |
|
||
| `Notification` | 通知发生 | 发送提醒 |
|
||
|
||
## 🚨 注意事项
|
||
|
||
1. **JSON 输出必须有效**: Hook 必须输出有效的 JSON，否则会失败
|
||
2. **使用 stderr 显示信息**: 终端输出应该使用 stderr，避免干扰 JSON 返回值
|
||
3. **错误处理**: 添加适当的异常处理，避免 Hook 崩溃
|
||
4. **性能**: Hook 会影响启动速度，保持轻量级
|
||
|
||
## 🎯 示例：创建自定义 Hook
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
import json
|
||
import sys
|
||
import os
|
||
|
||
def main():
|
||
# 加载输入
|
||
try:
|
||
input_data = json.load(sys.stdin)
|
||
except json.JSONDecodeError:
|
||
sys.exit(1)
|
||
|
||
# 显示自定义信息
|
||
print("🎨 我的自定义 Hook", file=sys.stderr)
|
||
|
||
# 返回输出
|
||
output = {
|
||
"hookSpecificOutput": {
|
||
"hookEventName": "SessionStart",
|
||
"additionalContext": "传递给 AI 的信息"
|
||
}
|
||
}
|
||
print(json.dumps(output))
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
## 🔍 调试 Hook
|
||
|
||
测试 Hook 是否工作：
|
||
|
||
```bash
|
||
# 直接运行 Hook（需要提供 JSON 输入）
|
||
echo '{}' | python ~/.claude/hooks/welcome.py
|
||
```
|
||
|
||
查看 Hook 日志（如果有）：
|
||
|
||
```bash
|
||
# 检查 Claude Code 日志
|
||
cat ~/.claude/logs/*.log
|
||
```
|
||
|
||
## 📚 更多资源
|
||
|
||
- Claude Code 官方文档
|
||
- Hook 配置参考
|
||
- 社区 Hook 示例
|