Hooks 配置

概述

Hooks 允许在特定事件触发时执行自定义操作。Superpowers 使用 Hooks 在会话启动时自动注入上下文，确保 AI 助手了解如何使用技能系统。

支持的事件

事件名	触发时机	用途
SessionStart	会话开始时（startup/resume/clear/compact）	加载技能上下文、显示提醒

配置文件结构

Hooks 配置在 hooks/hooks.json 文件中：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

字段说明

matcher

匹配规则，使用正则表达式匹配触发条件。

• startup - 新会话启动
• resume - 恢复会话
• clear - 清除对话后
• compact - 压缩对话后

示例："startup|resume|clear|compact" 表示所有情况都触发。

hooks

Hook 动作数组，每个动作包含：

字段	类型	说明
type	string	动作类型，目前支持 command
command	string	要执行的命令
async	boolean	是否异步执行

async

• false（默认）：同步执行，会阻塞会话启动直到完成
• true：异步执行，不阻塞会话启动

注意： SessionStart Hook 通常应设为 false，确保上下文在会话开始前注入。

内置 Hook 详解

session-start

Superpowers 的核心 Hook，在会话启动时注入 using-superpowers 技能内容。

执行流程：

1. 读取 skills/using-superpowers/SKILL.md 内容
2. 检查是否存在旧版自定义技能目录（~/.config/superpowers/skills）
3. 将内容注入到系统提示中

输出格式：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "..."
  }
}

自定义 Hook 示例

示例 1：自动加载项目配置

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.claude/project-context.md 2>/dev/null || echo ''",
            "async": false
          }
        ]
      }
    ]
  }
}

示例 2：发送通知

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Session started'",
            "async": true
          }
        ]
      }
    ]
  }
}

配置文件位置

平台	位置
Claude Code	~/.claude/plugins/superpowers/hooks/hooks.json
Cursor	~/.cursor/plugins/superpowers/hooks/hooks.json
Codex	~/.codex/superpowers/hooks/hooks.json
OpenCode	~/.config/opencode/superpowers/hooks/hooks.json

最佳实践

不要阻塞会话启动

避免在 SessionStart Hook 中执行耗时操作，或设置 async: true。

错误处理

Hook 脚本应该有完善的错误处理，避免因脚本错误导致会话无法启动。

#!/usr/bin/env bash
set -euo pipefail

# 你的代码...

# 确保总是输出有效的 JSON
echo '{"additionalContext": ""}'

调试技巧

1. 手动运行 Hook 脚本验证输出：

   CLAUDE_PLUGIN_ROOT=~/.claude/plugins/superpowers ./hooks/session-start

2. 检查输出的 JSON 是否有效：

   ./hooks/session-start | jq .

平台兼容性

Superpowers 的 session-start Hook 已经处理了不同平台的输出格式：

• Claude Code：使用 hookSpecificOutput.additionalContext
• Cursor 等：使用 additional_context

禁用 Hook

如需临时禁用 Superpowers 的自动上下文注入，可以修改 hooks.json：

{
  "hooks": {
    "SessionStart": []
  }
}