尝试启动钩子

2026-01-29 01:04:19 +08:00
parent 4975af61ae
commit f95b5f5b13
6 changed files with 577 additions and 0 deletions
@@ -0,0 +1,211 @@
+# 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 示例