# 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 示例