mcpField
D
debug-hooks

debug-hooks

github.com/parcadei开发3.9k501 次安装39 周前更新
代码仓库

关于 debug-hooks

用于系统排查 Claude Code 钩子的技能，指导开发者检查输出、注册、文件、手动测试、静默故障，以及 TypeScript 修改后的重新构建。

主要功能

  1. 01检查日志与缓存输出
  2. 02核对项目和全局注册
  3. 03检查钩子脚本与编译文件
  4. 04手动运行钩子
  5. 05查找静默故障并重新构建 TypeScript

适用场景

  1. 01排查钩子未触发
  2. 02追踪钩子没有输出的原因
  3. 03检查重复的钩子注册
  4. 04使 TypeScript 修改更新到可运行文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/parcadei/continuous-claude-v3 --skill debug-hooks

安装后在 Claude Code 中输入/debug-hooks确认已加载。

详细介绍

调试钩子

用于调试 Claude Code 钩子的系统化工作流。

适用场景

-“钩子未触发” -“钩子输出错误” -“SessionEnd 无法正常工作” -“PostToolUse 钩子未触发” -“为什么我的钩子没有运行？”

工作流

1. 先检查输出（先观察，再编辑）
# Check project cache
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/

# Check specific outputs
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/

# Check for debug logs
tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null

# Also check global (common mistake: wrong path)
ls -la ~/.claude/cache/ 2>/dev/null
2. 验证钩子注册情况
# Project settings
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

# Global settings (hooks merge from both)
cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'
3. 检查钩子文件是否存在
# Shell wrappers
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh

# Compiled bundles (if using TypeScript)
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs
4. 手动测试钩子
# SessionEnd hook
echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh

# PostToolUse hook (Write tool example)
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh
5. 检查静默失败

如果使用 stdio: 'ignore' 进行分离式启动：

// This pattern hides errors!
spawn(cmd, args, { detached: true, stdio: 'ignore' })

修复方法： 添加临时日志：

const logFile = fs.openSync('.claude/cache/debug.log', 'a');
spawn(cmd, args, {
  detached: true,
  stdio: ['ignore', logFile, logFile]  // capture stdout/stderr
});
6. 编辑后重新构建

如果编辑了 TypeScript 源代码，则必须重新构建：

cd $CLAUDE_PROJECT_DIR/.claude/hooks
npx esbuild src/session-end-cleanup.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/session-end-cleanup.mjs

仅修改源代码不会生效——Shell 包装脚本运行的是打包后的 .mjs。

常见问题

症状可能原因修复方法
钩子从未运行未在 settings.json 中注册在设置中的正确事件下添加钩子
钩子运行但没有输出分离式启动隐藏了错误添加日志，手动检查
会话 ID 错误使用了“最近的”查询显式传入 ID
本地正常，CI 中不正常缺少依赖项检查 npx/node 是否可用
运行两次同时在全局和项目中注册删除重复项

调试检查清单

  • 输出是否存在？（ls -la .claude/cache/）
  • 是否已注册？（grep -A10 '"hooks"' .claude/settings.json）
  • 文件是否存在？（ls .claude/hooks/*.sh）
  • 打包文件是否为最新？（ls -la .claude/hooks/dist/）
  • 手动测试是否正常？（echo '{}' | ./hook.sh）
  • 是否不存在静默失败？（检查是否使用了 stdio: 'ignore'）

来源会话

根据 10 个会话整理而成（占所有经验的 83%）：

  • a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c

评论

支持 Markdown