superpowers：把「软件开发方法论」装进编码 Agent（obra/superpowers 调研）

调研日期：2026-09-17 | 数据来源：GitHub API 实测、官方 README 全文、各 SKILL.md 原文、RELEASE-NOTES.md、hooks 配置、Harness 插件源码、第三方评测
仓库：https://github.com/obra/superpowers ｜ 官网形式：README + 插件市场（无独立站点）
作者：Jesse Vincent（Jesse Vincent 本人 + Prime Radiant 公司）

一句话定位

superpowers 不是一个 skill，而是一套「完整软件开发方法论」的插件化封装——由 14 个可组合 skill + 一段 SessionStart hook 强制注入的引导语组成，把编码 Agent 从「上来就写代码」改造成「先问清楚 → 写设计 → 出计划 → 子代理实现 → 双阶段评审 → 证据验收」的纪律化流水线。

💡 关键认知纠正：它经常被当成「一个很火的 skill」来传播，实际是 14 个 skill 打包 + hook 引导。装它 = 让 Agent 的工作方式被重新定义，而不是多加一个工具函数。这也是它口碑两极分化的根源。

1. 项目背景与热度（2026-09-17 实测）

项 数据
仓库 obra/superpowers
Stars 287,910 ⭐
Forks 25,752
Open Issues 375
Watchers 1,082
贡献者 ~440 人（GitHub API 分页实测 43 页 × 10）
创建时间 2025-10-09
最后推送 2026-09-14（3 天前，活跃）
最新版本 v6.3.0（2026-08-12）
许可证 MIT
主语言 Shell（含 JS/Python/Node 工具链）
仓库体积 约 4.8 MB / 255 个文件
安装量 第三方统计约 300 万+（单 skill brainstorming 约 36.5 万）

作者与背景：Jesse Vincent（GitHub obra），知名 Perl 社区人物、前 Best Practical 创始人；本项目由其公司 Prime Radiant 维护，且在招全职社区工程师（primeradiant.com/jobs），并提供企业商业支持（sales@primeradiant.com）——这是一个有商业实体的项目，不是个人练手仓库。

热度背景：2026 年 6 月登 Hacker News（”Superpowers 6” 讨论）引发大规模争议，成为「重型 Agent 框架 vs 轻量提示」路线之争的标志性项目。

2. 核心机制：它到底怎么”改造”Agent

2.1 双引擎：hook 注入 + 强制技能调用

引擎一：SessionStart hook 注入引导语。 仓库 hooks/hooks.json 配置了在 startup|clear|compact 三种时机触发 run-hook.cmd session-start，把 using-superpowers 技能正文注入每一次会话。这就是”开机即超能力”的实现方式。

引擎二：using-superpowers 的强制调用规则。 该引导语用极强措辞要求 Agent 在任何响应之前先检索技能：

“If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. This is not negotiable. You cannot rationalize your way out of this.”

并附**”红旗表”（Red Flags）**逐条反驳 Agent 的偷懒动机：

Agent 的想法 技能给出的”现实”
“这只是个简单问题” 问题也是任务，先查技能
“我需要先了解上下文” 技能检查在澄清提问之前
“让我先看看代码库” 技能才告诉你怎么看代码库
“我记得这个技能” 技能会演进，读当前版本
“这个技能太重了” 简单事会变复杂，用它
“这个感觉很有产出” 无纪律的行动浪费时间

⚠️ 这就是”仪式感过重”批评的技术根源——钩子强制 + 1% 概率即触发 + 不许合理化绕过。用户指令优先级高于技能（README 明确），但 Agent 默认不会放松。

2.2 brainstorming 的 HARD-GATE 与三档任务分级

brainstorming skill 定义了不可绕过的硬门禁：

<HARD-GATE>：在你告知人类伙伴你打算做什么、且对方批准之前，禁止调用任何实现类技能、写任何代码、脚手架任何项目、采取任何实现动作。这在下面每一条路径上都适用——仪式随任务伸缩，批准门永不伸缩。

并做了三档任务分级（作者在 v6.3.0 专门优化了这项）：

路径 判定 产出 仪式强度
Spike（探针） 可行性问题（”能不能做到…”） 一个答案，不是保留的代码 2-3 句话 + 点头即走
Bounded（有界） 改动已存在于本仓库的流程 聊天里的短设计（几段话），无 spec 文件 中（仍需批准）
Architectural（架构级） 新项目 / 新子系统 / 重构接口 完整问询 → 方案 → 分节设计 → 书面 spec 重（全套）

单向棘轮：拿不准就选更重的路径；任务中途发现隐藏复杂度 → 只能升档不能降档，必须停下来说明。这一条设计相当严谨，直接回应了”小事被重流程拖死”的批评。

2.3 三步走主工作流（README 官方版）

  1. brainstorming — 写码前激活。苏格拉底式问询细化粗糙想法，探索替代方案，分节呈现设计供逐段确认，保存设计文档
  2. using-git-worktrees — 设计批准后。在新分支创建隔离工作区，跑项目初始化，验证测试基线干净
  3. writing-plans — 拆成 2-5 分钟一个的小任务，每个任务给出精确文件路径、完整代码、验证步骤
  4. subagent-driven-development 或 executing-plans — 每任务派发全新子代理，走两阶段评审（先 spec 合规、再代码质量），或分批执行带人工检查点
  5. test-driven-development — 强制 RED-GREEN-REFACTOR：写失败测试 → 看它失败 → 写最小代码 → 看它通过 → 提交。在测试之前写的代码会被删除（”Delete means delete”）
  6. requesting-code-review — 任务间评审。对照计划报告问题并按严重程度分级，Critical 阻塞进度
  7. finishing-a-development-branch — 任务完成后验证测试，给出选项（合并 / PR / 保留 / 丢弃），清理 worktree

官方对计划质量的目标定义很有画面感，也解释了它的设计取向：

计划要清晰到”一个热情但品味差、没判断力、没有项目上下文、且厌恶测试的初级工程师也能照着执行”。

3. 14 个 skill 全清单与逐个拆解

按第三方注册表安装量排序（数据约 2026-08-27），标注官方分类：

# skill 官方分类 安装量 触发时机与作用
1 brainstorming 协作 365K 任何创造性工作之前必须用；探索意图/需求/设计（三档分级 + HARD-GATE）
2 systematic-debugging 调试 261K 遇到任何 bug、测试失败、异常行为、提出修复方案之前
3 writing-plans 文档 250K 已有 spec 或多步任务、动代码之前
4 using-superpowers 元技能 245K 任何对话开始；建立技能查找与调用规则（hook 注入的引导语本体）
5 requesting-code-review 代码质量 230K 完成任务、实现大功能、合并前验证
6 test-driven-development 测试 228K 实现任何功能或 bugfix、写实现代码之前
7 executing-plans 工作流 213K 在独立会话中执行已写好的计划，带评审检查点
8 verification-before-completion 代码质量 213K 声称”完成/修好/通过”、提交或建 PR之前——必须跑验证命令并确认输出，证据先于断言
9 subagent-driven-development 工作流 206K 在当前会话执行含独立任务的实现计划（SDD）
10 receiving-code-review 代码质量 195K 收到评审反馈后——要求技术严谨与验证，不许表演式认同、不许盲目照做
11 dispatching-parallel-agents Agent 运维 192K 面对 2 个以上无共享状态、无顺序依赖的独立任务
12 using-git-worktrees Git 192K 需要与当前工作区隔离的特性开发；保证隔离工作区存在
13 writing-skills 元技能 192K 创建/编辑/验证 skill 时（含技能测试方法论）
14 finishing-a-development-branch Git 188K 实现完成、测试全过、需决定如何整合工作（合并/PR/清理）

三个最值得单独研究的 skill（原文摘录）：

systematic-debugging — 铁律式四阶段

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

“核心原则：永远先找根因再尝试修复。治标式修复就是失败。 违反流程的字面就等于违反调试的精神。”

四阶段：①根因调查（细读错误 → 稳定复现 → 检查最近变更 → 多组件系统先加诊断埋点）②…③…④；每阶段完成才能进下一阶段。特别注意它点名了高风险场景：”时间压力下尤其要用“、”已试过多次修复”、”上一个修复没生效”、”没有完全理解问题”。

test-driven-development — 红线 + DOT 状态机

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

用 Graphviz DOT 画了 RED→GREEN→REFACTOR 状态机（含”失败得不正确”回边），并规定：“如果你没亲眼看到测试失败，你就不知道它测的是不是对的东西”；写码在测试之前？删掉重写——“不要留着当参考、不要边写测试边’适配’、不要看它”。

writing-plans — 计划即交付物
计划必须带固定头部（Goal / Architecture / Tech Stack / Spec 指针 / Global Constraints 全局约束块），并规定任务粒度：每个步骤是一个动作（2-5 分钟）——“写失败测试”是步骤、”跑一遍确认它失败”是另一个步骤。任务边界判定标准很清晰：“只有在评审者能有意义地否决一个任务而批准邻接任务的地方才拆分”。

4. 安装方式（13 种 harness，含你正在用的 Hermes）

这是本项目最突出的工程成就之一——单一代码库适配 13+ 个编码 Agent，安装方式因 harness 而异，多端同用需分别安装。

Harness 安装命令
Claude Code（官方市场，推荐） /plugin install superpowers@claude-plugins-official
Claude Code（自家市场） /plugin marketplace add obra/superpowers-marketplace → /plugin install superpowers@superpowers-marketplace
Hermes Agent hermes plugins install obra/superpowers --enable
Antigravity agy plugin install https://github.com/obra/superpowers
Codex App 侧栏 Plugins → Coding → Superpowers → +
Codex CLI /plugins → 搜 superpowers → Install Plugin
Cursor /add-plugin superpowers
Devin CLI devin plugins install obra/superpowers
Factory Droid droid plugin marketplace add https://github.com/obra/superpowers → droid plugin install superpowers@superpowers
Gemini CLI gemini extensions install https://github.com/obra/superpowers
GitHub Copilot CLI copilot plugin marketplace add obra/superpowers-marketplace → copilot plugin install superpowers@superpowers-marketplace
Grok Build CLI grok plugin install superpowers@xai-official --trust
Kimi Code /plugins → Marketplace → Superpowers
OpenCode 让 OpenCode 抓取并执行 .opencode/INSTALL.md
Pi pi install git:github.com/obra/superpowers
通用（Agent Skills 注册表） npx -y skills add obra/superpowers --agent <harness>

Hermes Agent 专门说明（与你的四端环境直接相关）：v6.3.0 新增，.hermes-plugin/plugin.yaml 声明 provides_hooks: [pre_llm_call]，由 __init__.py 定位 skills/ 树、剥离 frontmatter、拼接 references/hermes-tools.md 工具映射后注入。代码注释体现了作者工程习惯——找不到技能树时大声抛错：

“Raises loudly when neither matches — a bootstrap that silently skips is how a broken install masquerades as a working one.“

⚠️ 已知限制：Hermes 没有 post-compaction hook，超长会话在首轮之后压缩会丢失 bootstrap——技能不再触发时需开新会话。

5. 版本演进（v2 → v6.3）

版本 日期 主题
v6.3.0 2026-08-12 Devin CLI + Hermes Agent 支持；brainstorming 仪式随任务规模伸缩；SDD 控制器不再因计划冲突停摆
v6.2.0 2026-07-23 SDD 工作区改为按计划隔离（.superpowers/sdd/<plan>/）；Windows hook 经 Git Bash 派发修复
v6.1.1 2026-07-02 Codex hook 重注册修复
v6.1.0 2026-06-30 压缩 bootstrap 降低每会话 token 成本；Gemini CLI 曾移除
v6.0.0 2026-06-16 重大重写：SDD 评审由”每任务两评审者”合并为单评审者，官方称同质量下快约 2 倍、token 少近 50%

关键节点：v2.0.0 技能仓库分离（曾拆为 obra/superpowers-skills，插件转薄 shim）→ v3.0.x 转向 Anthropic 一方技能系统 → v4.0.0 DOT 流程图作为可执行规范 + 两阶段评审 → v5.0.0 可视化 brainstorm 伴侣 → v6.0.0 史上最大 SDD 架构重写。

贯穿版本的两条主线：①持续降本（v5.0.6 内联自审 → v6.0.0 单评审者 → v6.3.0 批量派发），几乎每个版本都在回应”太贵”的批评；②harness 中立化（技能措辞从 Claude 方言改为通用表述，每端提供工具映射文件）。

值得学习的工程细节：v6.3.0 提到曾有一个会话因本可自主决定的问题被阻塞近 9 小时——这类真实事故驱动的修复（非灾难性冲突记录裁决并继续，仅破坏性/不可逆操作才停下）在产品成熟度上很有说服力。

6. 与同类对比

项目 ★（2026-09-17） 定位 与我方关系
obra/superpowers（本文） 287,910 全生命周期方法论框架（14 skill + hook） 生态标杆，方法论上限最高
jnMetaCode/superpowers-zh 8,136 中文增强版：完整汉化 + 4 个中国原创 skill，宣称支持 26 款工具 国内团队可选替代（MIT，2026-03-20 建仓、09-17 仍更新）
Anthropic 官方 frontend-design ~277K 安装 UI 设计系统，管”长什么样” 互补不竞争
Anthropic Playwright Pro — 55+ 测试模板、浏览器自动化 互补：superpowers 要求先写测试，它提供测试基建
Trail of Bits Security — CodeQL/Semgrep 静态分析找漏洞 互补：它管安全，superpowers 管架构
自写 CLAUDE.md/AGENTS.md — 纯项目规则 互补，但无法替代多阶段编排与子代理委派

结论：superpowers 占据「全生命周期编排」这个独特生态位，同类替代品多是单点能力（设计/测试/安全）。真正的”竞争”对象不是别的 skill，而是模型原生规划能力 + 用户自己的 AGENTS.md。

7. 争议与真实成本（本报告的重点）

口碑两极分化明显，以下是引用来源的客观记录，非本报告立场：

批评方（Hacker News “Superpowers 6” 讨论 + 多篇评测）：

  • Token 是真实账单：有用户报告”烧完整个 Max 套餐”；简单修复”因为一堆验证要花整整一小时”；评测称每任务 token 用量高 30-40%
  • 对强模型属冗余：被比作”精雕细琢的 .vimrc”——2026 年主流模型原生就会规划，再套一层等于”双重保险、双倍开销”
  • 僵化：计划精确到指定文件，在探索型任务上可能有害（”方法论告诉未来的 Agent 该改哪些文件”）
  • 小任务过重：改一行配置也可能被 brainstorming 拉去做需求澄清、写设计文档，再被 TDD 接上

支持方 / 中立数据：

  • 安装成本其实很低：受益于渐进式披露（常驻元数据约 100 token/skill，正文按需加载），14 个休眠技能约 1,400 token + bootstrap。官方 v6.1.0 发布说明专门为压缩 bootstrap 而发，承认它”大小是被持续付费的“
  • 几乎没人质疑方法论本身：批评者对立的是”是否需要常驻 harness 强制它”，而非流程图本身——brainstorm → plan → implement → verify 被公认为”Agent 编码中杠杆率最高的习惯”
  • 一项受控对比：MCP.Directory 报道非平凡任务上 便宜 9%、token 少 14%、输出更好；但简单任务因澄清与设计阶段更贵
  • 一个耐人寻味的细节：有用户关掉 superpowers 后一天内又开了回来；最技术向的批评者是fork 它而不是弃用它
  • 作者在持续回应：v6.x 几乎每个版本都在降本，说明团队把”太贵”当成一等公民问题处理

给国内用户的一致性使用建议（多篇来源共识）：

  1. 复杂功能：全套跑（brainstorming → writing-plans → 执行 → 验证），提示词可以很短
  2. 中等任务：点名裁剪——“用 brainstorming 澄清，设计确认后直接实现；跳过 TDD，不写 design doc”
  3. 小改 / 脚本 / 调参：不要上重型框架，裸跑模型更快
  4. 用户指令优先级最高，可用 “skip clarify” 之类明确指令覆盖

8. 对用户的价值（借鉴点记录）

高价值：方法论本身可复用到自己的 skill 开发

这是一份**「如何写出行为约束型 skill」的范本**，其中被来源反复点名的写法如下（客观记录，非本报告立场）：

  • HARD-GATE 机制：把”必须等人类批准”写成不可绕过的硬门禁，而不是软性建议——比”请先确认”有效得多
  • Red Flags 表：预先枚举 Agent 的偷懒理由并逐条反驳，是对抗提示词合理化的通用手法，任何要求 Agent 守纪律的 skill 都能照搬这个格式
  • 任务三档分级 + 单向棘轮：解决”一刀切流程”的经典设计，仪式可伸缩但批准门不可伸缩
  • “Raises loudly, never silently skip”：失败要大声抛错而非静默跳过——README/SKILL/代码里贯彻的同一原则，值得抄进自己的工具链
  • 计划文件作为持久交付物：Markdown 计划能跨会话重置、跨机器保留，绕开上下文窗口限制
  • hooks 注入 + 元技能自举：SessionStart 注入 bootstrap 这套机制，与本机多端 Agent（zcode/hermes/dsh/workbuddy）的记忆注入思路同源，可交叉参考

分场景适配记录（客观记录各来源的共识，非本报告立场）

场景 多来源共识
复杂功能 / 新模块 / 跨多文件 全套跑（brainstorming → writing-plans → 执行 → 验证），提示词可以很短，让插件自行判断
中等任务 点名裁剪：”用 brainstorming 澄清，设计确认后直接实现；跳过 TDD，不写 design doc”
小改 / 脚本 / 调参 裸跑模型更快（多个来源一致）
探索型研究（如逆向） 有来源指出”计划精确指定文件”在探索型任务上可能构成妨碍
学 skill 工程化 源码本身被多个来源当作行为约束型 skill 的范本

9. 环境

项 要求
运行环境 无额外运行时依赖（纯 Markdown skill + Bash/Node hook 脚本）
仓库体积 约 4.8 MB / 255 个文件（git clone --depth 1 约 2.9 MB）
hook 依赖 SessionStart hook 需 bash；Windows 下上游提供 run-hook.cmd 多语言 polyglot 包装脚本，自动探测 Git for Windows bash / PATH bash，找不到则静默退出（插件仍可用，只是没有自动注入）
平台兼容 13+ harness 全平台支持；上游有专门 Windows 修复记录（v6.2.0 修 PowerShell/cmd.exe 解析失败导致 bootstrap 静默不加载）
网络 安装与更新需访问 GitHub；使用时不联网（遥测除外）
账号 / 密钥 不需要，无 API key、无账号体系

10. workbuddy 安装实测（2026-09-17 实机验证）

⚠️ 本节状态（2026-09-17 23:10 更新）：workbuddy 侧安装已全部回滚，superpowers 迁移至公共 skill 目录。

用户在实测后判断该方案「侵入性偏强」、担心长期引入未知问题，要求将 superpowers 从 workbuddy 移除，改由 zcode / dsh 承载。回滚清单与校验见 §10.4。
下方 10.1–10.3 保留为当时的实测记录与复盘（对在 zcode / dsh 上重装仍有参考价值），不代表当前状态。

10.1 市场内置版（未采用，供对照）

workbuddy 官方插件市场已内置 superpowers：

C:\Users\Admin\.workbuddy\plugins\marketplaces\codebuddy-plugins-official\external_plugins\superpowers\
项 实测值
市场条目 superpowers @ codebuddy-plugins-official
内置版本 v4.0.3（2025-12-26）
skill 数 14（完整）
许可证 MIT
安装状态 未安装

版本差距实测（内置 v4.0.3 vs 上游 v6.3.0）：

能力 v4.0.3 v6.3.0
14 个 skill ✅ ✅
Hermes Agent 支持 ❌ ✅
SDD 单评审者（官方称快 2 倍 / token 少 50%） ❌ ✅
brainstorming 三档分级 + 单向棘轮 ❌ ✅
bootstrap 压缩降本 ❌ ✅
计划按 spec 隔离防污染 ❌ ✅

⚠️ 官方已做 hook 适配——这是本项目最容易被忽略、也最值得学的一点

workbuddy 市场分发的是改写过的版本，不是上游原样搬运。关键差异在 hook：

市场版 v4.0.3 上游 v6.3.0
插件清单 .codebuddy-plugin/plugin.json 无（多 harness 清单，含 .claude-plugin/ 等）
hooks.json 的 command "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd" session-start.sh "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd" session-start + shell:"bash"
matcher startup|resume|clear|compact startup|clear|compact（无 resume）
hook 脚本输出格式 硬编码 hookSpecificOutput.additionalContext 嵌套格式（52 行的专用改写版） 按环境变量三分支（CURSOR_PLUGIN_ROOT / CLAUDE_PLUGIN_ROOT / 兜底顶层）
附带内容 lib/skills-core.js、commands/（3 个斜杠命令）、agents/code-reviewer.md 14 skill + hook + agents

市场版把输出格式写死成嵌套格式、不做任何分支判断——这正说明 workbuddy 认的就是这个格式，官方是为适配它专门改写的。

workbuddy 的插件机制会自动注入 CLAUDE_PLUGIN_ROOT（源码 cli/dist/codebuddy.js）：

if(eA.pluginRoot && (ep.CODEBUDDY_PLUGIN_ROOT = eA.pluginRoot, ep.CLAUDE_PLUGIN_ROOT = eA.pluginRoot), …)

也就是说：凡是从插件加载的 hook，其执行环境里都有 CLAUDE_PLUGIN_ROOT；command 里的 ${CLAUDE_PLUGIN_ROOT} 由 Git Bash 自己展开，脚本内部读到的该变量也会让上游脚本走嵌套格式分支。走插件机制 = 原生可用，零补丁。

反过来说，手写进 settings.json 的 hook 没有 pluginRoot，拿不到这个变量 —— 这正是手动安装方案被迫打补丁的根本原因（详见 10.2 节）。

10.2 实际采用方案：上游 v6.3.0 手动安装（取新版）

git clone --depth 1 https://github.com/obra/superpowers.git ~/.workbuddy/skills/superpowers

实测结果：

  • 版本 6.3.0（package.json 确认），14 个 skill 全部就位，目录 ~/.workbuddy/skills/superpowers/
  • 14 个 SKILL.md 的 frontmatter（name + description）格式与 workbuddy 内置 skill 一致，无需改写
  • hook 脚本开箱可用：hooks/session-start 自带平台分支——未设 CLAUDE_PLUGIN_ROOT / CURSOR_PLUGIN_ROOT 时走 additionalContext 顶层格式（SDK 标准），适配 workbuddy
    → 此结论有误，已修正：workbuddy 恰好落在兜底的「顶层 additionalContext」分支，而该格式不被 workbuddy 识别，hook 会执行但输出被静默丢弃。必须补设 CLAUDE_PLUGIN_ROOT 才能走上嵌套格式分支——这是手动安装方案的核心适配点，详见下文「生效条件」小节

hook 注册（写入 ~/.workbuddy/settings.json）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"C:/Users/Admin/.workbuddy/skills/superpowers/hooks/session-start\"",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

验证记录：

  • ✅ 脚本冒烟测试通过：输出合法 JSON，顶层键 additionalContext，3,321 字符
  • ✅ workbuddy 支持 SessionStart 事件（现有 8 个 hook 事件类型：SessionStart / UserPromptSubmit / Stop / SessionEnd / PreCompact / PreToolUse / SubagentStart / SubagentStop）
  • ✅ settings.json 修改后仍为合法 JSON，与既有 OpenViking 的 8 条 hook 并存未覆盖
  • ✅ 配置文件已备份至 ~/.workbuddy/settings.json.bak-20260917

✅ 无需信任 —— hook 写入即自动执行（2026-09-17 22:30 重启后实测）

workbuddy 的 settings.json hook 写入即自动执行，不存在「信任 / 审核」环节。重启后首个会话启动时的完整执行链（日志 ~/.workbuddy/logs/2026-09-17/workbuddy__*.log 原文）：

[22:30:38.275] [HookExecutor] spawn pid=83628
    shell=C:\Users\Admin\.workbuddy\binaries\PortableGit\versions\1.2.0\bin\bash.exe
    timeout=15000ms
    cmd=bash "C:/Users/Admin/.workbuddy/skills/superpowers/hooks/session-start"

[HookManager] event=SessionStart matched 3 distinct hook entries (after dedupe):
    openviking-hooks/session-start.mjs | skills/superpowers/hooks/session-start | workbuddy-builtin/tencent-docx

[22:30:39.124] [SessionHookManager] executeSessionStartHooks source=resume
    hasHooksCheck=0ms executeHooks=982ms total=982ms

关于「信任 / 面板审核」：/hooks 是 CodeBuddy CLI 的内置斜杠命令（disableModelInvocation:true），但 workbuddy 桌面版 GUI 的斜杠命令白名单只有 /compact（源码 SLASH_COMMAND_ALLOWLIST = new Set(["/compact"])）。桌面版没有 hook 面板，也不需要——HookManager.getHooks() 直接读取 settings 合并结果并执行，不设审核闸门。

⚠️ 但「执行了」≠「注入了」—— 发现并修复一处格式不兼容（本报告最有价值的实测收获）

上表日志只证明 hook 被 spawn，不等于上下文进了会话。继续深挖发现：superpowers 的 hook 在 workbuddy 上执行了，但输出被静默丢弃。

根因在 app.asar.unpacked/cli/dist/codebuddy.js 的 parseHookOutput()：它把 hook stdout 的 JSON 解析后，只把 hookSpecificOutput 字段赋给结果对象，顶层其它字段一律不读。

// parseHookOutput —— 只认 hookSpecificOutput
eA.hookSpecificOutput && (ep.hookSpecificOutput = eA.hookSpecificOutput, ...)

// SessionStart 消费端 —— 只读 hookSpecificOutput.additionalContext
if(eg.hookSpecificOutput?.additionalContext)
    eA.hookContexts.sessionStartContext = eg.hookSpecificOutput.additionalContext;
else if(eg.stdout && !eg.suppressOutput){ ... }   // 兜底分支，有任一 hook 提供嵌套格式时不会走到

而上游 hooks/session-start 按环境变量三分支输出：

分支条件 输出格式 workbuddy 是否识别
CURSOR_PLUGIN_ROOT 已设 {"additional_context": …}（snake_case） ❌
CLAUDE_PLUGIN_ROOT 已设 {"hookSpecificOutput":{"additionalContext": …}}（嵌套） ✅
两者均未设（本方案原本的处境） {"additionalContext": …}（顶层） ❌ 被丢弃

workbuddy 不设 CLAUDE_PLUGIN_ROOT，所以脚本走了第三分支——hook 正常执行、退出码 0、输出了合法 JSON，但内容从未进入会话上下文。这种情况从日志表面完全看不出来，属于典型的「静默失效」。

修复：新增一层包装脚本 ~/.workbuddy/hooks/superpowers-session-start，显式设置 CLAUDE_PLUGIN_ROOT 强制走嵌套格式分支：

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SP_ROOT="$(cd "${SCRIPT_DIR}/../skills/superpowers" && pwd)"
export CLAUDE_PLUGIN_ROOT="$SP_ROOT"
exec bash "${SP_ROOT}/hooks/session-start" "$@"

settings.json 中该条 hook 的 command 相应改为 bash "C:/Users/Admin/.workbuddy/hooks/superpowers-session-start"。

修复后实测（模拟 workbuddy 的 hook 调用协议，stdin 传入 {"hookEventName":"SessionStart","source":"resume",…}）：

顶层键: ['hookSpecificOutput']
hookEventName: SessionStart
additionalContext 长度: 3321
开头: <EXTREMELY_IMPORTANT> You have superpowers.

格式与 OpenViking 的 approve() 输出（{"decision":"approve","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}）完全一致，可被 workbuddy 识别。

💡 选择包装脚本而非改 command 内联变量：workbuddy 如何把 command 字符串交给 shell（bash -c 还是分词 spawn）未在文档中约定，包装脚本不依赖该假设，且把适配逻辑与上游代码隔离——git pull 更新 superpowers 不会冲突。

⚠️ 修复带来的副作用：多个 hook 的 additionalContext 会互相覆盖（已决策：保持现状）

workbuddy 聚合多个 hook 结果时用的是对象展开，同名键后者覆盖前者：

eA.hookSpecificOutput && (el.hookSpecificOutput = {...el.hookSpecificOutput||{}, ...eA.hookSpecificOutput})

修复前只有 OpenViking 提供 hookSpecificOutput，所以它的注入独占；修复后 superpowers 也提供，而它在 settings.json 中排在 OpenViking 之后，因此会覆盖掉 OpenViking 的 <openviking-context>（会话快照 / user-profile 注入）。

影响评估：OpenViking 的核心记忆能力走的是 UserPromptSubmit 的 auto-recall.mjs（每轮注入 <openviking-memory-recall>，落在 userPromptSubmitContext 槽位，与 SessionStart 槽位互不干扰），不受此影响；受影响的仅是 SessionStart 一次性注入的 profile 与目录摘要。

决策结论（2026-09-17，用户明确指示「不要动 OpenViking 的配置」）：合并两条 hook 的方案作废，保持现状——superpowers 内容注入生效，OpenViking 的 SessionStart 快照让位。已用 settings.json.bak-20260917-2245 备份 diff 验证 OpenViking 条目及其余 7 个 hook 事件逐字节未变，本次适配仅改动第 67 行（superpowers 的 command 路径）。

补充（源码复核）：workbuddy 聚合多 hook 结果的规则是——stdout 拼接、hookSpecificOutput 对象展开（后者覆盖同名键）；消费端 if(eg.hookSpecificOutput?.additionalContext) 走赋值分支，else if(eg.stdout…) 走追加分支。这解释了修复前的静默失效：OpenViking 提供了嵌套格式，if 分支命中并取走 OpenViking 的内容，superpowers 的 stdout 虽被拼进聚合 stdout，但 else 分支被跳过，因此完全未注入。另确认 hookSpecificOutput.initialUserMessage 写入后全代码无读取点（死字段），无法借它让两份 context 共存。

结论小结：

  1. hook 自动执行，无需任何信任/审核操作 —— 此前流传的「/hooks 面板信任」说法不成立
  2. workbuddy 自带 PortableGit（~/.workbuddy/binaries/PortableGit/versions/1.2.0/bin/bash.exe），Windows 下 bash 命令无需依赖外装 Git，也无需改用上游的 run-hook.cmd
  3. matcher 里的 resume 有效——上游默认是 startup|clear|compact，本方案额外加了 resume，日志显示 source=resume 时确实触发了 hook 执行（但注入是否成功取决于上述格式问题）
  4. 跨 harness 的 hook 适配不能只看「有没有执行」——必须验证输出格式与目标 harness 的解析逻辑是否对齐，这是一个容易静默失败的环节

⚠️ 已知差异（相对上游 Claude Code 环境）：

  • 上游 hook 经 ${CLAUDE_PLUGIN_ROOT} 定位插件根目录，workbuddy 无此变量 → 本方案改为绝对路径直接调用脚本（脚本内部自行推算 PLUGIN_ROOT），并在包装脚本中补设 CLAUDE_PLUGIN_ROOT 以对齐输出格式
  • 上游 hooks/hooks.json 在此方案下不被读取（它是插件清单的一部分，本方案未走插件机制），故 hook 需手动注册进 settings.json
  • 更新方式为 git pull（非插件市场自动更新）

10.3 三条安装路径对比（复盘：为什么手动路径”事情多”）

路径 版本 需补丁 更新方式 hook 输出格式 备注
A. 市场插件（workbuddy 官方） v4.0.3 无 插件市场自动 脚本已硬编码嵌套格式 最省事；落后上游 8 个月 / 2 个大版本
B. 上游 clone + 手写 hook（本方案） v6.3.0 1 个 wrapper git pull 需自补 CLAUDE_PLUGIN_ROOT 版本最新，适配成本自负
C. 上游 clone + 自行插件化 v6.3.0 理论上无 需重新打包 走插件机制自动获得该变量 需自建 .codebuddy-plugin/plugin.json 与市场索引，复杂度最高

根因复盘：手动路径（B）绕开了 workbuddy 的插件机制，而 superpowers 的 hook 恰好依赖该机制提供的 CLAUDE_PLUGIN_ROOT。这不是 superpowers 或 workbuddy 单方面的缺陷，而是「一套代码适配 13+ harness」这一分发策略的具体代价——上游靠环境变量分支来区分 harness，而 workbuddy 只在插件加载路径上提供该变量，手写配置不在这条供给链上。

选型建议：

  • 在意 v6 的方法论改进（SDD 单评审官方称 token 少约 50%、三档分级 + 单向棘轮、bootstrap 压缩）→ 选 B（本方案，补丁已就位）
  • 只要零维护、能接受 v4.0.3 → 选 A
  • 想要”新版本 + 原生机制”且愿意承担打包成本 → 选 C

10.4 回滚记录（2026-09-17 23:10 完成）

决策依据：用户判断该方案「侵入性偏强」、担心引入未知问题；workbuddy 只需通过既有符号链接共享 skill 目录即可，无需在 workbuddy 内做 hook 级适配。superpowers 后续改由 zcode / dsh 承载。

已删除：

对象 说明
~/.workbuddy/skills/superpowers/ 上游 v6.3.0 clone（删除前已核验为无本地改动的干净 clone，可随时重克隆）
~/.workbuddy/hooks/superpowers-session-start §10.2 的包装脚本；hooks/ 目录随之空置，一并移除
settings.json 中 hooks.SessionStart[1] superpowers 的 hook 注册条目
settings.json.bak-20260917 / -2245 / -pre-rollback superpowers 时期产生的三份配置备份

回滚校验（删除前执行）：

  • settings.json 解析合法；hooks 仍含全部 8 种事件类型；SessionStart 回到 1 条（仅 OpenViking）
  • 与「superpowers 安装前备份」做递归结构比对 → 完全相等（old == d → True）
  • CRLF 行尾风格保持，未发生整文件重写；enabledPlugins / claw / sandbox 等字段均未受影响
  • 全盘扫描：~/.workbuddy 内除供应商字体库同名的 superpowers.svg 外无残留

保留未删（附理由）：

  • ~/.workbuddy/workspace/sessions/<sessionId>/modify_backup*/ —— workbuddy 自身的编辑历史快照，属应用内部机制而非本方案产物，删除可能破坏该会话的改动回溯能力
  • 本调研报告、OpenViking 记忆记录 —— 属研究产物，非配置改动

迁移结果：superpowers 已 clone 至公共 skill 目录 …\AI_workspace\skill\superpowers（v6.3.0 / b36e082，14 个 skill）。该目录被 ~/.workbuddy/skills/external 符号链接指向，故 workbuddy 侧扫描总数仍为 129（14 个 skill 由 workbuddy 本地迁至共享目录，总量不变）。

⚠️ 副作用提示：这 14 个 skill 在 workbuddy 中仍会被索引（进入每会话的 skill 清单），但无 hook 注入——using-superpowers 的「1% 概率即强制调用」纪律不会生效，它们只是 14 个可被按需调用的普通 skill。若需在 workbuddy 侧彻底隐藏，可考虑 settings.json 的 skillOverrides 逐项设为 off（尚未实施，属可选优化）。

11. 安全风险评估

许可与来源：

  • ✅ MIT 许可证，可自由使用/修改/分发/商用，无附加限制
  • ✅ 作者为 Jesse Vincent（知名开源开发者，Perl 社区人物），由公司 Prime Radiant 维护，有公开 Discord 与企业支持渠道
  • ✅ 无账号体系、无需 API key、无凭证收集

遥测（唯一网络行为）：

  • ⚠️ brainstorming 的可视化伴侣会从 Prime Radiant 网站加载 logo，携带 Superpowers 版本号；官方明确声明不包含项目信息、提示词、Agent 详情，不追踪点击
  • ✅ 提供三重关闭开关：SUPERPOWERS_DISABLE_TELEMETRY（设任意真值）、DISABLE_TELEMETRY、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

代码执行面：

  • hook 脚本以 bash 执行，内容已逐行审阅（session-start 仅读取本地 SKILL.md 并做 JSON 转义输出，无外部请求、无 eval、无 base64 解码）
  • 无网络回调、无凭证文件读取、无混淆代码
  • 风险等级：低（纯静态 Markdown skill + 本地只读 hook）

⚠️ 使用注意：

  • 本方案用绝对路径注册 hook，路径变更（如移动 skills 目录）会导致 hook 失效，需同步更新 settings.json
  • 上游代码随 git pull 更新，上游变更会自动生效——若在意此点，建议固定到特定 tag 而非跟随 main

12. 待研究清单

  • bookkeeping：hook 信任后验证 bootstrap 是否真的注入会话 → 2026-09-17 22:30 已实测完成：无需信任，hook 自动执行（见第 10.2 节实测执行链）
  • 重启后复验：wrapper 修复后确认 bootstrap 真的注入会话 → 2026-09-17 23:10 作废：workbuddy 侧安装已整体回滚，无 hook 待复验（见第 10.4 节）
  • 待决策：是否把 OpenViking + superpowers 两条 SessionStart hook 合并 → 已决策：不合并；随后升级为 workbuddy 侧整体回滚（用户判断侵入性偏强），详见第 10.4 节
  • 在 zcode / dsh 上安装 superpowers（新的落点）：先确认二者的 hook / plugin 机制，以及是否提供 CLAUDE_PLUGIN_ROOT 一类变量——若有，上游脚本可直接走嵌套分支，无需 §10.2 那层包装
  • 实测 token 增量：superpowers bootstrap 单次约 3,321 字符 ≈ 800–900 token（数值保留作参考；workbuddy 侧已无此项开销）
  • 评估是否对共享目录里的 superpowers 14 个 skill 在 workbuddy 侧加 skillOverrides: off（规避其进入每会话 skill 清单；尚未实施）
  • 三档分级（spike / bounded / architectural）在非编码任务（如知识库整理）上的实际表现
  • systematic-debugging 四阶段法在验证码逆向调试场景的适配度
  • writing-skills 元技能与本地 skill-vetter 安全审查流程的配合方式
  • 上游 tag 固定策略（避免 main 分支变更自动生效）
  • 对照市场内置版 v4.0.3 与上游 v6.3.0 的行为差异（如需回退时参考）
  • superpowers-chrome v1.6.2（同作者，市场内，Chrome DevTools Protocol MCP）待研究

refer

说明：本页为调研整理笔记。star/fork/issue/推送时间/贡献者数均为 2026-09-17 GitHub API 实测值（贡献者数由分页 Link header 推算约 430-440）。安装量为第三方注册表统计（claudeskills.info / skills.sh），口径与官方不一致，仅作量级参考。Token 成本与效果数据来自第三方评测与社区讨论，属单点测量，不宜当结论。workbuddy 安装部分（第十节）为 2026-09-17 实机验证记录。技能安装与用法以官方 README 为准。