大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



Superpowers - 01 让 AI 真正“懂工程”：Superpowers 软件开发工作流深度解析

Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」：Superpowers 快速开始深度解析

Superpowers - 03 一文搞懂 Superpowers：面向多平台 AI 编码助手的安装与实践指南

Superpowers - 04 从“会写代码”到“会做工程”：Superpowers 工作流引擎架构深度剖析

Superpowers - 05 构建一个“会自己找插件用”的 Agent：深入解析 Superpowers 的技能发现与激活机制

Superpowers - 06 从文档到“结构契约”：Superpowers 技能剖析与 Frontmatter 深度解读

---

面对越来越复杂的 AI 开发场景，单纯“给模型一个工具箱”已经不够了：你需要的是一个能主动使用工具的 agent 行为系统。Superpowers 项目正是为此设计，而其中最关键的一块基础设施，就是本文要展开的主角：SessionStart Hook 注入机制。

本文面向以下读者：

• 经常使用 Claude Code / Cursor / Copilot 等 AI 开发环境，希望把自己的工作流沉淀为可复用技能的工程师
• 正在折腾“插件化 agent 能力”、MCP、工具路由、行为注入的研究者或开发者
• 想深入理解 Superpowers 架构、尤其是「技能发现与激活」底层机制的技术爱好者

我们将从整体架构讲起，再下潜到平台检测、JSON 构造、Bash 转义、跨平台脚本等实现细节，最后结合实际场景给出一些**实践建议。

---

在 Superpowers 的设计中，所有复杂的 TDD、调试、代码审查、子 agent 工作流……都被抽象为一个个技能文件（SKILL.md 等）。但如果 agent 自己不知道这些技能存在，它们就等同于「死代码」。SessionStart Hook 的目标，就是在每次会话启动时，把整个技能系统“挂到 agent 的大脑里”。

Superpowers 的核心理念可以简单概括为一句话：

无论 agent 在做什么，它都必须先检查有没有合适的技能能帮上忙。

为此，插件通过 SessionStart 钩子，在每个新会话（甚至上下文被清空、压缩时）自动注入一个叫 using-superpowers 的引导技能，让 agent 在系统提示中“记住”：

• 你现在有一个技能系统
• 所有技能都通过一个统一的 Skill 工具访问
• 在任何响应前，你必须先看技能能否帮忙，宁愿多用、不准少用。

换句话说，SessionStart Hook 是整个 Superpowers 行为系统的唯一引导入口，没有它，后面的技能、工作流、约束体系统统无法生效。

注入管道分三步走：

1. 平台原生钩子触发（Claude Code / Cursor / Copilot CLI 的 SessionStart 事件）。
2. 调用一个跨平台 shell 包装器 run-hook.cmd。
3. 包装器再调用真正的 hooks/session-start 脚本，读取 skills/using-superpowers/SKILL.md，构造平台需要的 JSON，并通过标准输出返回给平台，由平台注入到 agent 的系统提示中（additionalContext / additional_context 等）。

这样，无论你在哪个平台使用 Superpowers，只要会话启动，agent 的系统提示里就会多出一段引导性的技能说明。

---

要让 SessionStart Hook 生效，首先得告诉各个平台“我有这么个钩子”。Superpowers 为此维护了两个配置文件：hooks.json 与 hooks-cursor.json。

hooks.json 使用的是 Claude 插件格式，关键点包括：

• 事件名使用 SessionStart（PascalCase）。
• 命令配置为："${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start"。
• 支持匹配器："startup|clear|compact"，不仅在新会话启动时触发，还会在：
  • 清除对话历史（clear），
  • 上下文压缩（compact）
    这种“上下文重置”场景下重新注入技能，保证 agent 在上下文被重置后仍然记得技能系统。
    
    

特别要注意 async: false 的配置，这意味着注入必须在 agent 处理任何一条用户消息之前完成，否则就会出现“首轮回复没带技能感知”的竞态条件，直接影响用户体验。

Cursor 的钩子系统与 Claude 略有不同，需要单独一个 hooks-cursor.json。
主要区别体现在：

Cursor 的 agent 直接调用 bash 脚本，因此不需要 polyglot 包装器，命令直接指向 hooks/session-start 即可。

---

实现 SessionStart Hook 最难的部分不在“怎么注入”，而在“在不同平台上输出正确的 JSON 结构”。

hooks/session-start 会根据环境变量识别当前运行的平台，并输出不同结构的 JSON：

• Cursor：
  • 检测条件：CURSOR_PLUGIN_ROOT 存在。
  • 输出字段：顶层 additional_context（蛇形命名）。
• Claude Code：
  • 检测条件：CLAUDE_PLUGIN_ROOT 存在，且 没有 COPILOT_CLI。
  • 输出字段：

     } 

  • 注意这里是嵌套在 hookSpecificOutput 下的 additionalContext。
• Copilot CLI 或未知平台：
  • 检测条件：其他情况（可能只有 COPILOT_CLI 或都没有）。
  • 输出字段：顶层 additionalContext。

这三种结构差别看似微小，但对 Claude 来说，如果你在同一平台同时输出 additional_context 和 hookSpecificOutput.additionalContext，它会两者都读，导致相同的技能文本在上下文中出现两遍，白白浪费 token。

session-start 中的平台检测顺序是刻意设计的：

1. 先看 CURSOR_PLUGIN_ROOT。因为 Cursor 会顺带设置 CLAUDE_PLUGIN_ROOT，如果不优先判断，会误把 Cursor 当作 Claude。
2. 再看 CLAUDE_PLUGIN_ROOT 且无 COPILOT_CLI。Copilot 可能同时设置这两个变量，所以必须确认没有 COPILOT_CLI 才能断言是 Claude。
3. 最后归类为 Copilot 或未知平台，使用顶层 additionalContext。

如果你在移植或改脚本时随手改了顺序，很容易在某些平台上输出错误结构，表现为：

• 技能文本出现两次（上下文膨胀）。
• 或者平台根本解析不到你注入的内容，导致 agent 完全“失忆”。

---

SessionStart Hook 注入的并不是所有技能的内容，而是一个非常特殊的引导技能：skills/using-superpowers/SKILL.md。

using-superpowers 本身不会直接帮你写代码、跑测试，它更像是 agent 的「行为守则」。注入后的系统提示中主要完成这几件事：

• 告诉 agent：
  • 你当前处于一个带 Superpowers 的环境。
  • 所有技能都通过一个统一的 Skill 工具被发现和调用。
• 约定行为优先级：
  • 用户指令 > 技能指令 > 默认系统行为。
• 定义“必须调用技能”的规则：
  • 只要存在 1% 的可能某个技能有用，你就应该调用。
  • 在任何回答（哪怕只是澄清提问）之前，都要先检查技能列表。

这样，其他具体技能（TDD、调试、代码审查、子任务拆分等）就可以专注于“解决问题”，而 using-superpowers 负责保证 agent 一定会去用它们。

为了避免 agent 出现“我大概知道这些技能，但懒得用”这类行为，SKILL.md 中还设计了一个有趣的机制：

• 列出了一张包含 12 条“危险信号”的思维表格，用来识别 agent 在「给自己找理由不查技能」。
• 一旦出现类似“这次不需要用技能也能搞定”这样的内部推理模式，就会被视为违反规范。

通过这种带有元认知风格的约束，Superpowers 在提示层面尽可能压制“模型偷懒”，让技能系统真正成为默认路径。

---

当你要把一个富文本 Markdown 文件（SKILL.md）塞进 JSON 字符串时，就会遇到各种转义问题：引号、反斜杠、换行、制表符……如果转义不正确，要么 JSON 解析失败，要么注入内容错乱。Superpowers 在这里做了不少工程优化。

hooks/session-start 实现了一个完全用 Bash 字符串替换实现的 escape_for_json 函数：

• 首先处理反斜杠：\ → \\。
• 处理双引号：" → "。
• 将换行、回车、制表符替换为字面量 、 、 。
• 使用 ${s//old/new} 这种内建替换，而不是逐字符循环。

这样做有几个好处：

• 不依赖 sed / awk 等外部命令，在各种奇怪的 shell 环境（尤其是 Windows 上被 PATH 折腾过的 Git Bash）更稳。
• 性能远好于逐字符循环，适合处理动辄上 KB 的技能内容。

对于想在自己项目中采用类似模式的人来说，这是一个很实用的模式：

在 shell 脚本里构造 JSON 时，优先用内建字符串替换 + printf，避免多进程多工具带来的不确定性。

文章中特别强调了一个看似冷门但非常致命的 bug：

• Bash 5.3+ 在处理包含大量转义内容的 heredoc 时，存在可复现的挂起问题。
• 这会导致你的 SessionStart 脚本在会话启动时直接卡死，表现为“agent 没反应”或“首条消息超时”。

为规避这一点，Superpowers 统一使用 printf 输出最终 JSON，而不是：

cat <<EOF { "additionalContext": "..." } EOF 

任何对脚本输出逻辑的修改，都被强烈建议继续使用 printf，否则就有可能重新踩到这个坑。

---

在 Claude Code 和 Copilot CLI 上，hooks.json 里配置的命令不是直接调用 session-start，而是调用 run-hook.cmd。这背后是一套“多语言钩子包装器”模式，用来解决 Windows CMD 与 Unix shell 的兼容问题。

run-hook.cmd 这个脚本有点魔法性质：

• 对 Windows CMD 来说，它是一个合法的 .cmd 文件，执行逻辑大致是：
  • @echo off 处理参数。
  • 调用 Git Bash，并通过 cygpath 做路径转换。
  • 执行对应的 bash 脚本（比如 hooks/session-start）。
  • 在进入任何 Bash 代码之前就通过 exit /b 结束 CMD 流。
• 对 Bash 来说，同一个文件又是合法的 shell 脚本：
  • 使用 : << 'CMDBLOCK' 这样一个空操作 heredoc 把所有 CMD 段落“吃掉”。
  • 之后执行真正的 SCRIPT_DIR/SCRIPT_NAME。

这种 polyglot 写法的好处是：

• Windows 环境可以通过 .cmd 直接调用，不需要用户去手动指定 Bash。
• Unix 环境又可以把它当普通 shell 脚本使用。
• 所有钩子共享这一包装器，只需通过第一个参数指定脚本名（例如 session-start），配置简单、复用性高。

在故障排查表里，关于 run-hook.cmd 的问题主要有两类：

• 配置指向了 .sh：
  • 结果是在 Windows 上点击时直接被文本编辑器打开，而不是执行。
  • 正确做法是始终指向 run-hook.cmd，再由它去执行 bash 版本。
• bash is not recognized：
  • 通常是用户没安装 Git for Windows，或者安装路径没有被包装器正确找到。
  • 解决方案是安装/修正 Git，并必要时调整 run-hook.cmd 中的 bash 路径。

如果你正在为自家项目设计跨平台钩子执行机制，这个 polyglot 模式非常值得参考。

---

Superpowers 在演进过程中，曾使用 ~/.config/superpowers/skills 作为自定义技能目录，后来迁移到 ~/.claude/skills。为了避免用户“悄悄在旧目录继续放技能”，session-start 在注入主内容前会做一次检查：

• 如果检测到旧目录存在，就在注入载荷末尾追加一段警告文本。
• 这段警告被特殊标签包起来，并要求 agent 在首次回复时明确提醒用户进行迁移。

这种设计看似“有点烦”，但从迁移可靠性角度看非常合理：

• 迁移提示不会静默消失。
• 在迁移完成并删除旧目录后，这个检查也不再带来额外开销。

对于需要迁移配置路径、数据目录的项目来说，这是一个值得借鉴的模式：通过 agent 主动提醒用户完成迁移，而不是悄悄写在 README 里指望用户自己发现。

---

实际使用中，最让人头疼的往往不是“怎么注入”，而是“为什么不生效”。文中给出了一张非常实用的故障排查表，我们可以归纳成几个典型场景：

1. Agent 完全忽略技能
   • 通常是钩子根本没触发：
     • 插件没安装好、hooks.json 未被平台加载。
     • 环境变量如 CLAUDE_PLUGIN_ROOT 未配置。
2. 技能文本出现两次
   • 多见于 JSON 结构输出错误：
     • 对 Claude 同时输出 additional_context 与 hookSpecificOutput.additionalContext。
     • 平台检测顺序与实际运行环境不匹配。
3. 会话启动时卡死
   • 大概率是 Bash 5.3+ heredoc bug：
     • 解决方案是确认改脚本使用的是 printf 而不是 heredoc。
4. Windows 上脚本被编辑器打开
   • 命令误指向 .sh 文件，而不是 run-hook.cmd。
5. Cursor 完全没收到注入内容
   • 把 Cursor 错误地配置成使用 hooks.json。
   • Cursor 需要 hooks-cursor.json，且字段必须是 additional_context（蛇形命名）。

文中还给了一个非常推荐的调试方法：

CLAUDE_PLUGIN_ROOT=$(pwd) bash hooks/session-start 

直接在仓库根目录手动执行钩子脚本，检查输出的 JSON 是否符合目标平台预期。这比在完整 agent 环境中“盲调”要高效得多。

---

理解了 SessionStart Hook 的细节之后，更关键的是把它放到整个 Superpowers 架构中去看。

文中明确指出：SessionStart 是 Superpowers 唯一的引导机制：

• 所有后续技能（头脑风暴、TDD、调试、代码审查、Git 工作流等）都依赖于最初注入的 using-superpowers。
• 如果 SessionStart 注入失败，整个技能系统就处于“冬眠”状态，agent 只剩下模型本身的通用能力。

这也意味着，在扩展或移植 Superpowers 时，你可以改技能，可以改工作流，但绝不能忽略 SessionStart Hook 这一层的兼容性与稳定性。

结合文中内容，可以给出一些面向真实工程场景的建议：

• 在新平台集成时：
  • 先搞清楚平台支持的钩子事件与 JSON 格式。
  • 优先实现一个最小可用的 SessionStart 注入，再逐步扩展技能体系。
• 在调试注入问题时：
  • 始终先在命令行单独运行脚本，确认 JSON 输出无误。
  • 再检查平台配置（hooks.json / hooks-cursor.json）是否指向正确脚本。
• 在扩展 SessionStart 注入内容时：
  • 小心控制注入体积，只注入“索引型”“行为契约型”内容。
  • 把真正大体量的说明、例子、模板留在技能内部，通过 Skill 调用时按需加载。
• 在设计自家技能系统时：
  • 借鉴 using-superpowers 的做法：

 
            
    
              
 
               
把“必须查技能”“不准偷懒”写成清晰的行为约束。
 
               
使用类似“危险信号表格”的方式约束 agent 的元推理。
 
              
 

---

SessionStart Hook 看起来只是一个“会话启动时执行的脚本”，但在 Superpowers 的架构设计里，它承载的是：把一堆静态技能文件，变成一个真正“驱动 agent 行为”的操作系统。

它解决的不是“多一个工具能干什么”，而是“如何让 agent 每一步行动都在技能系统的监管与帮助下进行”。在未来更复杂的 AI 工程实践中，这种“以引导钩子为中心”的设计，很可能会成为构建可控、可审计、多工具协作 agent 的标准模式之一。

如果你正在搭建自己的 agent 能力体系，建议亲手读一遍 Superpowers 的 hooks 与 skills/using-superpowers 代码与文档，尝试在自己的项目中实现一个最小版本的 SessionStart 引导机制。这会比单纯在提示词里堆规则，有更高的可维护性与可迁移性。