1. superpowers 到底是什么：从“工具三件套”到“能力打包”
1.1 同名项目很多，先对齐语境
superpowers 这个名字，光在 GitHub 上搜，就能出来几十个结果。有游戏开发框架，有浏览器扩展，还有一些教学演示项目，都叫这个名字。我今天要说的这个，定位是一套开源的自托管效率工具箱。说人话就是：它不是某一个功能单一的工具，而是把很多零散的 CLI 工具、脚本、配置模板，打包成一套可以统一安装、统一管理、按需启用的“能力集”。装好之后，你不需要记几十条散装命令，而是通过一个统一的入口去调用需要的功能模块。
这个工程的名字起得确实好，抓住了开发者对“超能力”的向往。但在具体使用之前，我建议你先去项目主页确认一下自己拿到的到底是哪个版本。因为 superpowers 可能是一套游戏 IDE、一个 npm 包、一个 Docker 镜像名，也可能就是我下面要讲的这套工具集。这篇文章基于我在本地实际部署的这套“开发者超能力工具箱”来写，思路对所有同类项目都通用。
1.2 它究竟解决什么问题
先说我为什么会对它感兴趣。起因很俗——最近换了台新电脑，装环境装到怀疑人生。node、python、docker、git 相关的一堆命令行工具，装完还要配 PATH、配权限、配各种别名和脚本，前前后后折腾了两天，有些配置还是没完全迁移过来。
后来我想到朋友在团队里推的一套做法：把团队常用的几十条重复操作统一收口，变成一条条带名字的命令。比如初始化一个新项目，原来要点开网页、复制模板、手动装依赖、配 lint、配提交信息规范，现在一行命令就搞定。这套做法的核心就是 superpowers 的模块化思路。我把家里的机器装了一遍，也帮另一台 Linux 服务器部署过，整体用下来最大的感受是：它不是在给你的系统“增加更多东西”，而是给你那些散落各处的工具、脚本、配置建了一个“统一收纳箱”。
这就好比搬家的时候，你不是买了更多家具，而是把所有零碎物件分类打包装箱，到达新家后一个个拆箱归位。superpowers 做的事情就是“打包装箱”和“拆箱归位”，只不过它打包的是命令、脚本和配置。
2. 安装前先想清楚：环境与方案选型
2.1 三套部署方案怎么选
先说结论：不同场景选不同方案，不要一开始就追求“全家桶”。
| 方案 | 安装方式 | 适合场景 | 难度 | 我的推荐度 |
|---|---|---|---|---|
| A. 命令行本地安装 | npm 全局安装 CLI，再初始化用户目录 | 个人开发机、日常使用 | 低 | 最推荐 |
| B. Docker 容器部署 | Docker Compose 拉起服务端 + Web 管理界面 | 服务器、多人共用、想隔离环境 | 中 | 看需求 |
| C. 服务端 + 客户端分离 | 远程装 server，本地装 client 连接 | 团队统一出口、跨多台机器 | 高 | 进阶再玩 |
方案 A 适合绝大多数人。它的优势是轻量、可控、卸载干净。你不需要开一个常驻进程，也不占用额外端口，所有功能都以子命令的方式放在终端的 PATH 里，随时调用。
方案 B 是我在服务器上用的方式。它的好处是环境隔离得非常彻底，你想怎么折腾都不会污染宿主机；缺点是多了一层容器编排，排查问题的时候要稍微多想一层。如果你对 Docker 不熟，建议先在方案 A 上把功能跑通，再决定要不要容器化。
方案 C 是我后面要单独讲的进阶玩法，适合需要统一管理多台机器的团队。首次接触建议先别碰，等你有明确需求再说。
2.2 基础环境准备清单
无论选哪个方案，有几样东西跑不掉。我先列个清单：
- Node.js 版本要满足项目要求。我装的这套要求 Node 14 以上，实际用 18 和 20 都跑过，没遇到兼容问题。版本太低装依赖时会直接报错。
- 包管理器。npm 自带，但如果你的环境里已经有 pnpm 或 yarn，也没问题，命令稍有差异。
- 一个干净的目录规划。建议在用户目录下建一个独立目录，比如
~/.superpowers，把配置和数据都放这里。不要图省事直接放系统临时目录，重启一下就没了。 - 用户的读写权限。这里有个我踩过的坑：一开始我图省事用 root 用户安装，结果模块生成的临时文件全是 root 属主，后来切回普通用户根本没法用。建议全程用普通用户操作，目录权限归自己。
还有一点容易被忽略：想清楚你要用它做什么。是只想跑通一个功能模块，还是想把自己的工作流整个搬进来？我试过一上来就开了十来个模块，结果环境里一堆脚本互相依赖，排查问题的时候非常痛苦。更合理的做法是先跑一个最小可用配置，验证主流程没问题，再逐步加功能。
2.3 为什么一定要先跑“最小可用配置”
这个思路听起来像软件工程里的术语，但实际用起来就是很朴素的道理。第一，你刚装好的环境是干净的，这时候出问题容易定位；等你装了十几个模块再出问题，到底是哪个模块的锅，光靠猜就能猜一晚上。第二，模块之间有依赖关系，比如有的模块要调用另一个模块的脚本，如果你一次全开，依赖顺序错了很难发现。
我自己的做法是：先只启用一个最没技术含量的模块，比如“文件批量重命名”，跑通之后再启用“代码模板生成”，再逐步叠加。每加一个模块就跑一遍全量自检。这个习惯帮我避免了好几次“环境突然崩了但不知道改了啥”的尴尬。
3. 实操记录：最常用的一条命令安装方式
3.1 命令行安装完整实录
我以 macOS 和 Linux 为例，过程几乎一样。首先确保 Node.js 已经就绪：
node -v npm -v然后执行全局安装：
npm install -g @superpowers/cli安装过程会下载主程序和相关依赖。装完之后，验证一下命令是否可用：
sp --version如果提示command not found，说明 npm 的全局 bin 目录不在你的 PATH 里。这个很常见，尤其是用 nvm 管理 Node 版本的场景。解决办法是把对应目录加进 PATH，一般在~/.zshrc或~/.bashrc末尾追加：
export PATH="$(npm prefix -g)/bin:$PATH"加完记得执行source ~/.zshrc或重新开一个终端。
接着初始化用户目录：
sp init这一步会生成默认配置文件和基础目录结构。看到类似superpowers initialized in ~/.superpowers的输出，就表示安装成功了。
3.2 安装后用自检命令验证环境
装完千万别急着直接用，先跑一遍自检。superpowers 自带一个诊断命令：
sp doctor它会检查几件事：主程序版本、Node 版本是否满足要求、用户目录是否存在且可写、配置文件语法是否正确、已启用模块的依赖是否齐全。输出结果像体检报告一样，每个检查项后面会有 PASS、WARN 或 FAIL 标记。
我第一次跑的时候，有一个模块显示 WARN，原因是模块需要用到ffmpeg命令，但系统里没装。这个提醒非常有用，省得我真正调用那个功能的时候才发现环境缺东西。建议把每个 WARN 都看一下，能补的依赖就顺手补上。
如果sp doctor全部通过，就可以开始配置你的第一个模块了。
3.3 Docker 方式部署完整流程
如果你想在服务器上跑，或者不想把本机环境搞得乱七八糟，Docker 是更合适的选择。用 Docker Compose 把它们管理起来。
先准备一个docker-compose.yml：
services: superpowers: image: ghcr.io/superpowers/server:latest container_name: superpowers restart: unless-stopped ports: - "8080:8080" volumes: - ./sp-data:/data environment: SP_HOST: 0.0.0.0 SP_PORT: 8080 SP_DATA: /data然后在同目录执行：
docker compose up -d等容器起来后，访问http://localhost:8080就能看到管理界面。数据都存在./sp-data目录里，备份或者迁移的时候直接打包这个目录就行。
这里有个很容易踩的坑：容器里的进程默认以 root 运行，它往数据卷里写的文件属主是 root，等你需要用宿主机用户去读这些文件时会发现没有权限。解决办法是在 compose 文件里指定用户，把宿主机当前用户的 UID 和 GID 传进去。
services: superpowers: image: ghcr.io/superpowers/server:latest user: "${UID:-1000}:${GID:-1000}"然后启动时带上环境变量：
UID=$(id -u) GID=$(id -g) docker compose up -d这样数据卷里生成的文件就归当前用户了，后面操作省心很多。
4. 配置与模块扩展：把“超能力”真正用起来
4.1 主配置文件拆解
初始化完成之后，~/.superpowers/下会出现几个文件。最重要的是config.yaml和.env。
我摘一段简化后的config.yaml示例：
# 用户目录，所有模块的数据都存在这里 data_dir: ~/.superpowers/data # 服务端监听配置（如果启用 Web 管理界面才有意义） server: host: 127.0.0.1 port: 8080 # 默认语言 locale: zh-CN # 模块开关 modules: batch-rename: enabled: true code-template: enabled: true git-flow: enabled: false这里必须改的是data_dir，建议把它设成绝对路径，避免某些情况下相对路径解析出错。server.host默认是127.0.0.1，如果只有本机访问，保持默认就好；如果要在局域网里让别人访问，改成0.0.0.0才会生效。端口注意别和其他服务冲突。
.env文件主要存一些不方便写在配置文件里的值，比如 API 密钥、外部服务地址。我见过的最常见错误是：有人把.env里的换行符写成了 Windows 风格，结果整行被当成字符串的一部分，解析出来是一坨乱码。如果你在 Windows 上编辑过再传到 Linux 上用，记得先转换换行符。
4.2 模块体系：启用、停用、组合
模块是这套系统最核心的抽象。你可以把模块理解成“做菜时的调料包”：主程序是锅，模块是调料包，想做什么菜就拆哪个包，不想用就放进柜子里。
查看当前模块列表：
sp module list启用一个模块：
sp module enable code-template停用一个模块：
sp module disable code-template模块之间可以组合，这也是它真正的价值所在。举个我实际用过的例子：我每天都要处理一批从客户那边导出的 CSV 文件，原来的流程是先用 Python 脚本改编码，再手动改文件名，最后打开 Excel 调整式。用 superpowers 之后，我把“编码转换”“批量重命名”“模板生成”三个模块组合起来，写一条链式命令就搞定了。
sp run csv-clean --input ./raw --output ./clean --rename-pattern "2025-{date}-{index}.csv"这个命令会先转换编码，再按规则重命名，最后套用模板。整个过程不用开任何编辑器，数据量大的时候还能挂到后台跑。
4.3 自定义一个自己的“超能力”模块
第三方的模块库未必每次都覆盖你的需求，这时候就得自己写。别慌，自定义模块的门槛其实很低，本质就是“放一组脚本和配置文件”。
一个最简单的模块结构长这样：
code-template/ ├── manifest.json ├── index.js └── templates/ └── node-app/ ├── package.json.tpl └── index.js.tplmanifest.json描述这个模块的名字、版本和暴露的命令：
{ "name": "code-template", "version": "1.0.0", "entry": "index.js", "commands": ["new-app", "new-lib"] }index.js定义命令的实际行为。这里的逻辑很自由，你可以用 Node.js 脚本调用任何外部工具，也可以写纯 shell 脚本。我自己的习惯是：凡是涉及文件生成的命令，都用模板引擎渲染；凡是涉及外部工具的调用，都在子进程里执行，并注意把错误码接住。
写完之后，把它放进~/.superpowers/modules/目录：
cp -r code-template ~/.superpowers/modules/ sp module list重新执行列表命令，就能看到自己的模块出现了。这里有个细节：改完模块代码后不用重启任何服务，因为它是在命令执行时动态加载的，改了立即生效。不过如果你改了manifest.json里的字段，建议重跑一次sp doctor，确认新模块能被正确识别。
5. 常见问题与排查技巧实录
5.1 安装阶段翻车现场
结合我自己的部署经历和帮别人排查过的情况，安装阶段最容易出的问题就这几类。
第一，权限混乱。这个我在 2.2 里已经提过。用 root 装的工件，普通用户没法写；用普通用户装的工件，又想去改系统目录的文件。最典型的报错是EACCES: permission denied。解决办法很朴素：全程不要切换身份，安装、初始化、运行都用同一个用户。
第二，Node 版本太低。有些模块依赖fetch或者新版语法，Node 14 以下的版本会直接报SyntaxError: Unexpected token。排查方式很简单，看报错位置是不是在某个模块的源码里，如果是，先升级 Node 再跑一次。
第三，下载超时或中断。主程序安装的时候要下载不少依赖，网络状况不好的情况下容易出现中断。我建议不要反复重试同一命令，而是先清理缓存再装：
npm cache clean --force或者换个包管理器试试。核心思路是不要让坏掉的缓存影响下一轮安装。
5.2 运行阶段常见报错速查表
| 报错信息 | 原因 | 解决方式 |
|---|---|---|
command not found: sp | npm 全局 bin 不在 PATH | 把$(npm prefix -g)/bin加进 PATH |
EACCES: permission denied | 目录属主不对 | 检查并修正目录属主，统一用当前用户操作 |
sp doctor显示 Fatal Error | 配置文件语法出错 | 检查config.yaml缩进，重点看是否用了 Tab |
Cannot find module 'xxx' | 依赖缺失 | 在模块目录下补装依赖，或重跑初始化 |
listen EADDRINUSE :::8080 | 端口被占用 | 换一个端口，或者找出占用端口的进程 |
| 模块启用后没生效 | 名称拼写不匹配 | 用sp module list查准确名称再启用 |
这个表是我每次带新人上手时都会贴出来的。大部分问题不是逻辑多深，而是基础环境没对齐。
5.3 两个我常用的独家排查技巧
第一个技巧是“分层排查”。遇到诡异问题，先用sp doctor --verbose看详细报告，会输出所有模块和环境变量的状态。根据报告迅速锁定问题范围：是主程序坏了，还是某个模块坏了。别从第一个报错信息开始猜，先看整体再缩小范围。
第二个技巧是“保留配置快照”。每次跑通一套能用的配置，就把~/.superpowers/config.yaml和模块列表导出备份一下：
sp module list > modules-backup.txt cp ~/.superpowers/config.yaml config-backup.yaml后期升级或者换机器的时候，直接对照快照还原，能省掉大量重复排查的时间。我用这个办法迁移过一次环境，整个还原过程只花了不到十分钟。
6. 后续还能怎么玩：我的真实经验与建议
6.1 我实际用它做了哪些事
目前我用 superpowers 主要处理三类场景。
第一类是新项目环境初始化。开新项目时要建目录、建配置、装基础依赖、初始化 Git 仓库，以前这一套流程要手动点按很多次，现在一条命令全搞定。
第二类是重复性文件操作。前面说的 CSV 清洗、批量重命名、图片格式转换，这些原本要我写临时脚本的活，现在都沉淀成模块。最直接的好处是：临时脚本用完就丢，下次还得重写；模块写一次，永远在那里。
第三类是团队协作的统一入口。帮团队维护了一个共享模块库，成员之间通过同一套命令做相同的事，减少了很多“为什么你的命令没反应”的沟通成本。
6.2 三个自己动手扩展的方向
如果你装了以后觉得不够用，可以往这三个方向扩展。
一是接外部服务。比如接入消息推送、或内部 API，把模块的执行结果自动发送出去。实现方式是写一个监听事件的后台脚本，在模块执行完成时触发通知。
二是做定时任务。用crontab把某个模块命令挂起来定期执行，日志输出到固定文件，配合告警脚本就能实现简单的自动巡检。
三是做 CI 集成。把模块命令封装到 CI 流程里，提交代码后自动执行环境检查和构建前的准备步骤。这个适合团队里有统一 CI 平台的情况。
6.3 几点想在最后分享的体会
这套东西我用下来的感受是：它本质上是一种“对工作流的整理”，技术难度不算高，核心价值在于你愿意花多少心思去梳理自己的重复劳动。很多人装完就跑了个 demo，然后觉得不过如此，就删掉了。但如果你真的把自己每天重复的操作都列一张清单，再看哪些能收敛成模块，它带来的效率提升是实打实的。
对于新手，我建议从自己最痛的那个操作开始建模块，哪怕它只是一个简单的脚本打包。一个能用、能解决问题的模块，好过十个装了再也没用过的模块。这个思路放之四海皆准。
最后再分享一个小技巧：遇到模块升级报错，别急着回滚。先备份当前配置，看看 release notes 里有没有 breaking change 说明，大多数兼容问题在升级说明里都写得很清楚。备份、读文档、再动手，这三步能解决我碰到的绝大部分升级问题。
