Superpowers 中文版

June 19, 2026 · View on GitHub

在 Pi（oh-my-pi）上使用 superpowers-zh 的完整说明。

安装

superpowers-zh 通过 Pi 的扩展机制集成，直接指向仓库现有的 skills/ 目录——不复制 skill、不建 symlink、无额外运行时依赖。

集成由 package.json 里的 pi 字段声明：

"pi": {
  "skills": ["./skills"],
  "extensions": ["./.pi/extensions/superpowers.ts"]
}

并带 pi-package keyword，便于 Pi 发现这是一个 Pi 包。

按 Pi 的包安装方式安装 superpowers-zh（参考 Pi 文档的包管理命令），Pi 会读取上述 pi 配置，挂载 skills/ 并加载 .pi/extensions/superpowers.ts 扩展。

工作原理

.pi/extensions/superpowers.ts 注册了 Pi 的生命周期钩子：

  1. resources_discover — 把仓库的 skills/ 目录贡献给 Pi 的技能系统；
  2. session_start / session_compact — 标记需要重新注入 bootstrap；
  3. context — 在会话上下文中注入 using-superpowers 的内容（去除 frontmatter）+ Pi 工具映射，作为「You have superpowers」bootstrap，让 skill 在恰当时机被遵循；
  4. agent_end — 一轮结束后停止重复注入。

注入带有唯一标记，已存在时不会重复注入；并且会插入到 compaction summary 之后，避免被压缩流程吞掉。

工具映射

Pi 有原生技能系统，但不暴露 Skill 工具。skill 内容描述「动作」，在 Pi 上对应到小写工具：

  • 「调用某个 skill」→ Pi 原生技能：用 read 加载对应 SKILL.md，或由人类显式 /skill:name
  • 「读/写/改文件」→ read / write / edit
  • 「跑 shell 命令」→ bash
  • 「搜索文件内容」→ grep，「按名找文件」→ find，「列目录」→ ls
  • 「分派子智能体」→ 若装了 pi-subagents 的 subagent 工具则用之；没有则在本会话内完成或说明能力缺失，不要臆造 Task 调用
  • 「待办清单」→ 若装了 todo/task 工具则用之；否则用 plan 文件或仓库内 TODO.md 跟踪；旧的 TodoWrite 引用按此处理

完整映射见 skills/using-superpowers/references/pi-tools.md，扩展也会把同样的映射注入会话。

验证

bash tests/pi/run-tests.sh

该测试动态加载扩展并校验：声明了 pi 包配置、注册了正确的生命周期钩子（且无 pre-compaction 注入）、resources_discover 贡献了 skills/ 目录、session_start 注入了「You have superpowers」+「Pi tool mapping」、pi-tools 参考文档存在。

注：扩展是 TypeScript（仅 import type，运行时无类型依赖）。Node 22.6–23.5 需 --experimental-strip-types（run-tests.sh 已带），23.6+ 默认支持。