errors

错误模式分析

分析从 Claude Code 会话中捕获的错误，识别模式并获取可操作的见解。

快速入门

/errors              # Batch analysis of historical error patterns
/debug               # CC 2.1.30 real-time debug for current session

如何选择

命令	用途	范围
/errors	批量分析错误模式（最近 24 小时/7 天）	历史模式
/debug	实时调试当前会话状态	当前会话
fix-issue	针对特定错误执行完整的 RCA 工作流	单个问题

CC 2.1.169+： 对于在 /clear 和重启后仍然存在的错误，claude --safe-mode 会在禁用所有自定义设置（CLAUDE.md/plugins/skills/hooks/MCP）的情况下启动——这是深入分析前区分“ork/hook/MCP 错误”和“CC 错误”的一步测试。

快速分析

# Run batch analysis on last 24h of errors
python .claude/scripts/analyze_errors.py

# Analyze last 7 days
python .claude/scripts/analyze_errors.py --days 7

# Generate markdown report
python .claude/scripts/analyze_errors.py --report

捕获内容

错误收集器 hook 会捕获：

• 工具名称（Bash、mcp__memory__search_nodes 等）
• 错误消息（前 500 个字符）
• 工具输入（失败的命令/查询）
• 时间戳和会话 ID

位置： .claude/logs/errors.jsonl

当前错误规则

查看会触发警告的已学习模式：

cat .claude/rules/error_rules.json | jq '.rules[] | {id, signature, count: .occurrence_count}'

文件

文件	用途
.claude/hooks/posttool/error-collector.sh	将错误捕获到 JSONL
.claude/hooks/pretool/bash/error-pattern-warner.sh	在执行高风险命令前发出警告
.claude/scripts/analyze_errors.py	批量模式分析
.claude/rules/error_rules.json	已学习的错误模式
.claude/logs/errors.jsonl	原始错误日志

常见模式

连接被拒绝/端口错误

pattern: ECONNREFUSED|connection refused|ERR_CONNECTION_REFUSED|connect ECONNREFUSED
fix: The port may have changed or the service isn't running.
     1. Check services: portless list (if installed)
     2. Use named URLs: api.localhost instead of localhost:PORT
     3. Fallback: lsof -iTCP -sTCP:LISTEN -nP | grep -E 'node|python|java'
     4. Install Portless to avoid port guessing: npm i -g portless

pattern: ERR_CONNECTION_RESET|ECONNRESET|socket hang up
fix: Service may have crashed. Check process logs, restart the service,
     and use agent-browser to verify the app is responding:
     agent-browser open "https://myapp.localhost"

PostgreSQL 连接错误

pattern: role "X" does not exist
fix: Use Docker connection: docker exec -it orchestkit-postgres-dev psql -U orchestkit_user -d orchestkit_dev

pattern: relation "X" does not exist
fix: Check MCP postgres server connection string - may be connected to wrong database

Hook 错误（CC 2.1.98）

从 CC 2.1.98 开始，hook 错误会直接在转录记录中显示 stderr 的第一行——无需使用 --debug：

pattern: hook.*error|hook.*failed|PreToolUse.*error
diagnosis: Read the stderr line shown in the transcript.
  1. If path error → check CLAUDE_PLUGIN_ROOT is set
  2. If JSON parse error → hook is returning invalid JSON
  3. If timeout → hook exceeds 50ms budget (PreToolUse) or 100ms (PostToolUse)
  4. If "module not found" → run: cd src/hooks && npm run build

相关技能

• ork:fix-issue：修复已识别的错误
• debug-investigator：调查错误根因

添加新规则

当模式重复出现 2 次或以上时，analyze_errors.py 会自动生成规则。 如需手动添加规则，请编辑 .claude/rules/error_rules.json：

{
  "id": "custom-001",
  "pattern": "your regex pattern",
  "signature": "human readable signature",
  "tool": "Bash",
  "occurrence_count": 1,
  "fix_suggestion": "How to fix this"
}