Superpowers v6.0.3 架构与流程编排图解

目录

1. 总览

2. 本次拉取后的关键变化

这次 pull 后仓库从之前阅读到的 5.1.0 进入 6.0.3。架构报告必须按新版理解。

3. 分层架构

Superpowers 的代码很薄，但流程很厚。最清晰的看法是把它分成六层。

flowchart TB
  User["Human partner"] --> Harness["Coding harness"]
  Harness --> Adapter["Distribution and adapter layer"]
  Adapter --> Bootstrap["Session-start bootstrap"]
  Bootstrap --> Meta["using-superpowers meta skill"]
  Meta --> Router{"Which skill applies?"}
  Router --> Brain["brainstorming"]
  Router --> Debug["systematic-debugging"]
  Router --> Plan["writing-plans"]
  Router --> TDD["test-driven-development"]
  Router --> SDD["subagent-driven-development"]
  Router --> Finish["finishing-a-development-branch"]
  Brain --> Spec["Spec document"]
  Plan --> PlanFile["Implementation plan"]
  SDD --> Evidence["Briefs, reports, review packages, ledger, commits"]
  TDD --> Evidence
  Debug --> Evidence
  Finish --> Outcome["merge, PR, keep, discard"]
    

4. 启动注入与平台适配

docs/porting-to-a-new-harness.md 把 Superpowers 的跨平台机制总结成三个不变量：技能共享、工具映射按平台提供、bootstrap 必须在每个会话开始时自动注入。

4.1 三种集成形态

4.2 平台入口表

flowchart LR
  subgraph A["Shape A: shell hook"]
    HookCfg["hooks-*.json"] --> RunHook["run-hook.cmd"]
    RunHook --> Shell["session-start script"]
    Shell --> Json["additionalContext JSON"]
  end
  subgraph B["Shape B: plugin callback"]
    Plugin["JS/TS extension"] --> Register["Register skills path"]
    Plugin --> Transform["Mutate message/context"]
  end
  subgraph C["Shape C: context file"]
    Manifest["Extension manifest"] --> Context["Declared context file"]
  end
  Json --> Boot["using-superpowers bootstrap"]
  Transform --> Boot
  Context --> Boot
    

5. 技能库设计

技能是项目的真正核心。每个技能用 frontmatter 描述触发场景，正文则给出强流程、红旗、反合理化、检查清单和交接规则。

6. 主开发流程

主流程是一个状态机，每一步都有下一步的指定技能和产物。

flowchart TD
  Idea["User idea or feature request"] --> Brain["brainstorming"]
  Brain --> Design{"Design approved?"}
  Design -- "no" --> Brain
  Design -- "yes" --> Spec["Write spec and commit"]
  Spec --> HumanSpec{"Human reviewed spec?"}
  HumanSpec -- "changes" --> Spec
  HumanSpec -- "approved" --> Plan["writing-plans"]
  Plan --> PlanFile["Implementation plan"]
  PlanFile --> Worktree["using-git-worktrees"]
  Worktree --> Exec{"Execution path"}
  Exec -- "recommended" --> SDD["subagent-driven-development"]
  Exec -- "fallback" --> Inline["executing-plans"]
  SDD --> Finish["finishing-a-development-branch"]
  Inline --> Finish
  Finish --> Result["merge / PR / keep / discard"]
    

7. SDD 子代理编排

v6 的 SDD 是这次最大变化。它把主会话变成控制器，把实现、review、修复都通过文件交接给子代理，并用 ledger 抵抗上下文压缩。

flowchart TD
  Start["Read plan once
note global constraints"] --> Preflight["Pre-flight plan review
find conflicts before Task 1"]
  Preflight --> Ledger["Check .superpowers/sdd/progress.md"]
  Ledger --> Brief["scripts/task-brief PLAN N
writes task brief file"]
  Brief --> Impl["Implementer subagent
reads brief, writes report file"]
  Impl --> Status{"DONE / CONCERNS / CONTEXT / BLOCKED"}
  Status -- "NEEDS_CONTEXT" --> Context["Controller adds context"] --> Impl
  Status -- "BLOCKED" --> Escalate["More context, stronger model, split task, or ask human"] --> Impl
  Status -- "DONE" --> Package["scripts/review-package BASE HEAD
writes diff package file"]
  Package --> Review["Task reviewer
brief + report + diff package"]
  Review --> Verdict{"Spec OK and quality approved?"}
  Verdict -- "no" --> Fix["One fix subagent for all Critical/Important findings"] --> Package
  Verdict -- "yes" --> Mark["Append progress ledger
mark todo complete"]
  Mark --> More{"More tasks?"}
  More -- "yes" --> Brief
  More -- "no" --> Whole["Whole-branch review
requesting-code-review"]
  Whole --> Finish["finishing-a-development-branch"]
    

7.1 文件交接机制

7.2 Reviewer 的新版职责

8. 可视化 Brainstorm Companion

brainstorming/visual-companion.md 描述了一个浏览器伴侣：当问题“看图比读文字更清楚”时，agent 可以启动本地小服务器，推送 mockup、流程图、布局选项，让用户在浏览器里点击选择。

flowchart LR
  Agent["Agent"] --> Start["scripts/start-server.sh"]
  Start --> Server["server.cjs
HTTP + WebSocket"]
  Server --> Browser["Browser tab
?key=session token"]
  Agent --> Screen["Write newest HTML
content directory"]
  Screen --> Server
  Browser --> Events["state/events
clicks and selections"]
  Events --> Agent
  Server --> Security["Token auth, cookie, sandboxed files,
no-store headers, 4h idle timeout"]
    

8.1 安全模型

• URL 带一次性 ?key=...，HTTP 和 WebSocket 都必须携带 key。
• 浏览器首载后把 key 放入 tab-scoped storage/cookie，刷新和静态资源也能验证。
• 文件服务拒绝 symlink、dotfiles、路径穿越和 macOS resource fork。
• 服务器写入 key 文件时尽量设置 owner-only 权限。
• 默认绑定 loopback，可通过 --host 和 --url-host 支持远程/容器场景。

8.2 图文协作循环

9. 质量门禁

10. 测试与 eval

v6 文档把测试分成两类。

cd evals
uv sync --extra dev
export ANTHROPIC_API_KEY=sk-...
uv run drill run triggering-test-driven-development -b claude

11. 贡献约束

仓库的 CLAUDE.md 和 PR 模板对 agent 贡献非常强硬。原因是维护者明确观察到大量 agent PR 被拒，常见问题包括没读模板、重复 PR、编造问题、隐藏 agent 来源、把项目特定内容塞进 core。

12. 读源码路线

如果你要继续深挖，建议按这个顺序读。

1. README.md：项目定位、支持平台、基础 workflow。
2. RELEASE-NOTES.md：v6.0.0 到 v6.0.3 的设计变化，尤其 SDD、visual companion、new harness。
3. skills/using-superpowers/SKILL.md：全局技能触发协议。
4. hooks/session-start、hooks/session-start-codex、.opencode/plugins/superpowers.js、.pi/extensions/superpowers.ts：不同 bootstrap 形态。
5. docs/porting-to-a-new-harness.md：跨平台集成的 invariants 和三种 shape。
6. skills/brainstorming/SKILL.md 与 skills/brainstorming/visual-companion.md：从需求澄清到可视化协作。
7. skills/writing-plans/SKILL.md：新版 plan 的 Global Constraints、Interfaces、task right-sizing。
8. skills/subagent-driven-development/SKILL.md、implementer-prompt.md、task-reviewer-prompt.md：新版 SDD 的控制器、实现者、reviewer 协议。
9. skills/test-driven-development/SKILL.md、skills/systematic-debugging/SKILL.md、skills/verification-before-completion/SKILL.md：三大质量纪律。
10. docs/testing.md：插件测试与行为 eval 的分工。

结论

Superpowers 的设计不是“给代理多几条建议”，而是把软件交付拆成可触发、可验证、可恢复的流程单元。v6 的重点是跨平台中立化、SDD 降本增严、文件化交接、可视化协作安全加固，以及把技能行为测试提升为 eval 问题。

本报告生成自本地仓库 /Users/chenmeili/Documents/GitHub/superpowers，拉取后 HEAD 为 896224c，版本为 6.0.3。