跳转至

Superpowers 源码拆解与在线文档站设计

状态： 已批准并进入实现

目标

参考 refs/dg-ai-notes 对 Pi-Agent 的“概念—源码—设计取舍—可迁移方法”拆解方式，对本地 superpowers-main（插件版本 6.2.0）进行一套可独立阅读的中文源码导读，并发布为可搜索、可导航、可长期维护的 MkDocs Material 站点。

读者与边界

  • 读者：想理解 coding agent 工作流、技能系统和多 harness 适配机制的开发者。
  • 分析对象：superpowers-main 本地源码快照；上游仓库为 obra/superpowers。
  • 内容重点：运行时注入、技能发现、工作流编排、TDD/调试/审查闭环、平台适配和测试策略。
  • 不复制完整上游源码，不把拆解写成 API 参考；代码片段只保留解释设计所需的最小上下文。
  • 不引入前端应用或数据库；站点只由 Markdown、MkDocs Material 和 GitHub Actions 构成。

文档架构

站点按一条从“启动”到“交付”的主线组织：

总览 → 启动与注入 → 技能系统 → 设计与计划 → 执行与并行
                                  ↓
             TDD → 调试 → 审查/验证 → 分支收尾与多平台适配

章节职责：

  1. 总览：定义 Superpowers、核心对象、仓库地图和完整生命周期。
  2. 启动链路：解释插件 manifest、SessionStart hook、using-superpowers 注入和 Skill 工具边界。
  3. 技能系统：解释 SKILL.md、description 触发、渐进披露、引用资料与脚本。
  4. 设计与计划：拆解 brainstorming、writing-plans、executing-plans 的状态机和人工确认点。
  5. 执行与协作：拆解 subagent-driven-development、dispatching-parallel-agents、worktree 与 branch finish。
  6. 质量闭环：拆解 TDD、systematic-debugging、verification、requesting/receiving review 的证据链。
  7. 多 harness 适配：比较 Claude、Codex、Cursor、Gemini、Kimi、OpenCode、Pi 等适配层。
  8. 测试与演进：分析测试目录、压力测试、跨平台 hook、版本与发布脚本，并总结可迁移设计。
  9. 附录：技能目录、文件索引、术语表、源码阅读路线和证据口径。

每章都使用同一模板：先回答是什么，再跟踪源码怎么运行，最后总结为什么这样设计以及如何迁移到自己的 Agent。

站点方案

  • mkdocs.yml：站点元数据、Material 主题、中文搜索、导航和 Markdown 扩展。
  • docs/：主页、章节与附录；路径使用稳定的英文 slug，避免中文文件名造成链接兼容问题。
  • .github/workflows/deploy.yml：安装 mkdocs-material，执行 mkdocs build --strict，上传 Pages artifact 并由 actions/deploy-pages 发布。
  • 仓库：公开 GitHub 仓库 Hanqing/superpowers-ai-notes；公开仓库是 GitHub Pages 可访问性的默认前提。

验收标准

  1. 章节覆盖上游源码中的核心技能、hooks、manifest、脚本、测试与适配层。
  2. 关键结论能回指到本地源码路径、文件名和行号范围，避免只做概念性转述。
  3. mkdocs build --strict 通过，无导航、链接或 Markdown 警告。
  4. GitHub Actions workflow 成功，Pages 环境完成部署。
  5. 仓库 README 能给出在线站点、源码依据、构建方法和许可证说明。

设计取舍

方案 A：直接把上游仓库 README 搬到网页

实现成本最低，但无法解释模块之间的因果关系，也不符合参考拆解的深度，放弃。

方案 B：只写逐文件注释

源码覆盖率高，但读者必须自己拼出生命周期，且难以理解“技能如何改变 Agent 行为”，放弃。

方案 C：按生命周期组织的源码拆解 + Material 文档站（采用）

以启动注入为入口，以交付收尾为出口；每章同时给出源码证据、时序、取舍和迁移建议。它比逐文件目录更适合学习，也保留足够的源码索引能力。