企业官网建设流程全解析

最近我一直在折腾一个叫 superpowers 的命令行技能框架。起因是团队里一堆重复性工作反复占人手：初始化项目结构、批量改名、生成周报、检查依赖更新、整理变更日志，每个人电脑里都有几个自留的脚本，但脚本散落在各自机器上，换个环境就得重写一遍。后来有人提了一嘴：能不能把所有重复劳动都收集成 skills，随装随用？于是我就把 superpowers 完整跑了一遍，从安装、查技能、引入技能，到动手写自定义技能，两个下午踩了不少坑。这篇文章就把 superpowers 的基本玩法、常见技能清单、安装引入方式，以及我实际遇到过的故障和解决办法一起整理出来，给同样想用但还不清楚“有哪些 skills”“怎么引入技能”的朋友做个参考。

1. 项目概述：superpowers 到底是什么，为什么值得折腾

1.1 从名字说起：技能包，而不是又一个框架

superpowers 字面意思是“超级能力”，但它并不是一个给你提供固定功能的框架，而是一套以“技能包（skills）”为单位的运行环境。你可以把它理解成一个终端超能力管理器：想批量处理图片，装一个 image-tools 技能；想让 git 提交更规范，装一个 git-helper 技能；想一键生成项目骨架，再引入 scaffold-init。所有技能都遵循同一套接口约定，既能单独运行，也能串联调用。

它和传统框架最大的区别在于“约束感”。普通框架会规定你按它的目录规范写代码、按它的生命周期组织逻辑，而 superpowers 的核心引擎只负责三件事：识别技能清单、解析技能参数、执行技能入口。剩下的能力全部由 skill 自己决定。这个设计带来的直接好处是，你完全可以根据需求裁剪环境，不会因为引入一个工具而被拖上一堆用不上的依赖。我在团队里推广时最看重这一点，新人不需要一上来就理解全部能力，装两三个和当前任务相关的技能就能干活。

这个项目解决的核心问题，也不是“多一个工具”，而是“让能力可以被命名、被安装、被复用”。以往你想用同事写的一段逻辑，要么把代码要过来改，要么照着重写，一旦项目结构变化基本就废了。superpowers 把能力封装成带名字、带版本、带参数声明的技能包之后，复用成本一下低了很多。

1.2 它解决的三个痛点

第一个痛点是“脚本不可复用”。几乎每个开发者电脑上都有几个临时脚本，改完文件名、跑完数据清洗就丢在角落，换台电脑或者换了项目目录就找不到。superpowers 的思路是把这类脚本规范成一个技能包：有入口文件、有参数定义、有描述信息，再纳入版本管理。这样到新环境只需要同步配置文件，然后执行sp sync，所有常用技能就能恢复。

第二个痛点是“命令记忆成本高”。平时用到的小工具命令五花八门，有的还带一堆参数组合，时间一长连自己都记不住。superpowers 统一了入口，你只需要记住sp run <skill-name>这一条命令，具体参数可以交互式提示，也可以写进配置文件。它其实是把“怎么执行”沉淀成了技能包内部的描述，把使用者的记忆负担降到最低。

第三个痛点是“团队协作缺抓手”。以前同事想借用你的脚本，你很难把环境、依赖、用法一次性说清楚。现在技能包自带说明、参数定义和示例，同事执行sp list就能看到有哪些能力，执行sp run skill-name --help就能看到用法，体验上非常接近“从应用商店装 App”。对我们这种十人左右的开发小组来说，这个体验升级还是很明显的。

1.3 适合谁用，应该从哪里开始

我建议这几类人可以重点关注 superpowers：一是日常有大量重复文件操作、文档生成任务的开发者和运营；二是需要维护多个项目，希望统一初始化、依赖检查、构建发布流程的工程师；三是团队里负责维护内部工具，想把脚本沉淀成可共享资产的人。

如果你刚开始接触，不要一上来就研究所有概念，先走通“安装 CLI - 拉取一个技能 - 跑通一个场景”这条链路。我自己就是从批量重命名文件开始的，跑通之后才慢慢理解技能包的结构和工作流编排。这个学习路径对新手最友好，因为它能让你在半小时内看到实际效果。

2. 核心技能拆解：superpowers 到底有哪些 skills

2.1 技能目录总览

很多人搜索“superpowers 有那些 skills”，其实想找的是一份技能清单。下面是我实际用过或见过社区中比较有代表性的技能，先列成表格方便你对照。

这份清单并不是固定的。superpowers 的技能市场里技能数量还会增加，很多团队也会把内部流程封装成私有技能。关键是你要理解：这些技能不是“大而全”的软件，而是聚焦某一个高频动作的小工具集合。scaffold-init 不会替你做完整项目管理，它只负责把目录和基础配置铺好；batch-rename 也不会接管所有文件操作，它就专注于改名这一个动作。

2.2 按场景选技能，别按数量选

每次有人问“有哪些 skills”，我给出的建议都一样：先别关心技能总数，先想想你今天最头疼的重复操作是什么。如果你频繁要建新项目，那就先装 scaffold-init；如果你每天被改文件名折磨，就先用 batch-rename；如果你总忘记提交前跑检查，watcher-run 加 git-flow 的组合更有价值。

我看过不少朋友一上来就把热门技能全装上，结果sp list输出一大串，真正用起来的没几个。这是因为技能是“按需运行”的，装太多反而让心智负担变重。我自己现在的设备上只保留了七到八个技能，其余临时用到的按需安装，用完后sp remove移除。这种“随时装卸”的轻量感，正是这类技能化工具相比单体软件的优势。

2.3 技能之间的组合与依赖

单个技能只能解决单点问题，组合起来才能形成自动化流程。superpowers 支持在配置文件中定义 workflow，按顺序或条件调用多个技能。举个例子，我初始化一个模块时，先用 scaffold-init 铺目录，然后自动触发 template-render 生成 README，最后用 dep-audit 确认基础依赖没有版本冲突。这一条 workflow 执行下来，原本要手动操作的十几分钟工作量被压缩到一条命令。

组合使用时要特别注意技能之间的“契约”关系。前一个技能生成的目录结构、输出文件位置，必须和后一个技能期望的输入一致。比如 scaffold-init 默认生成的标准目录如果被自定义模板覆盖了，后面 template-render 可能找不到模板文件导致失败。所以我不建议在还不熟悉某个技能时贸然把它编排进工作流，先单独跑通，再考虑组合。

3. 安装与引入：从零开始把 superpowers 跑起来

3.1 安装前的环境准备

安装 superpowers 之前，我先确认了本机的运行环境。它默认运行在 Node.js 之上，建议使用 Node 18 或更新版本，npm 和 git 也要提前装好。如果你电脑上同时有多个 Node 版本，我推荐用 nvm 管理，避免在全局安装 CLI 时出现切换版本后命令找不到的问题。

环境检查其实就三步：执行node -v看 Node 版本，执行npm -v看包管理器版本，执行git --version确认 git 可用。我遇到过一台旧电脑 Node 还在 14，sp命令安装成功但启动时报语法错误，升级到 Node 18 之后才正常。所以别跳过这步，版本不对后面都是坑。

3.2 安装 CLI 与初始化工作区

安装 CLI 的命令很简单：

npm install -g @superpowers/cli

装完先跑一下sp --version，能输出版本号就说明第一步成功了。接着在你想使用技能的工作目录里执行：

sp init

这条命令会生成两个东西：一个是superpowers.yml配置文件，另一个是.superpowers/目录，用来存放本地技能和运行缓存。superpowers.yml是核心，它声明了这个项目需要哪些技能、每个技能的版本要求，以及需要编排哪些 workflow。

一个典型的配置文件长这样：

version: 0.4.0 skills: - name: scaffold-init version: ^1.2.0 - name: batch-rename version: ^0.3.1 - name: git-flow version: ^1.1.0 workflows: init-module: steps: - skill: scaffold-init - skill: template-render

配置里的^表示允许同大版本内的更新，这个语义和 npm 的 semver 规则一致。我的建议是，团队协作时不要随意放宽版本范围，锁死大版本能减少“今天还能跑，明天突然坏了”的尴尬。

3.3 引入技能：三种常见方式

引入技能这件事是搜索热词里出现最多的，实际操作中我常用三种方式。

第一种是从技能市场在线安装。比如想装 scaffold-init：

sp add scaffold-init # 或者指定版本 sp add scaffold-init@^1.2.0

第二种是引入本地技能目录。自己写的技能还没发布时，可以直接加进来试跑：

sp add ./skills/batch-rename --dev

--dev会把技能标记为开发模式，表示不依赖线上版本，每次运行都读取本地最新代码，方便边写边调。

第三种方式是先编辑superpowers.yml声明技能，然后执行sp sync一次性拉取所有依赖。这种方式适合新环境初始化，比如我在一台新电脑上只需要复制配置文件，然后跑sp sync，所有技能就装好了。

引入之后，用sp list查看当前可用的技能清单，用sp use scaffold-init把某个技能设为默认执行项。这样之后直接运行sp run就会走默认技能，少敲一个参数。

3.4 验证技能是否生效

技能引入成功不等于一定能正常执行，我建议用“只读验证法”来确认环境没装坏。像 scaffold-init 和 batch-rename 这类技能一般会提供 dry-run 模式，只打印将要执行的操作，不真正修改文件系统。验证命令可以是：

sp run scaffold-init --name demo-site --dry-run

如果终端正常输出了[dry-run]前缀的目录结构，说明 CLI、技能包、参数解析这一整条链路都是通的。更保险的方式是执行sp doctor，它会检查技能清单格式、依赖版本、入口文件权限，并把异常项标出来。我第一次跑sp doctor就发现有个本地技能没有可执行权限，顺手chmod +x run.js解决问题。别小看这一步，它能帮你省下无数定位时间。

4. 自定义技能：把重复劳动封装成自己的 superpower

4.1 技能包的基本结构

如果你想真正发挥 superpowers 的威力，一定要学会写自定义技能。一个标准技能包的结构非常简单：

my-skill/ ├── skill.yaml ├── run.js └── assets/

其中skill.yaml是技能清单，负责描述技能的元信息和参数；run.js是入口脚本，真正做事的逻辑都写在里面；assets/目录用于存放模板、配置文件、样例数据等附资源。

skill.yaml里的核心字段包括：

name: my-skill version: 1.0.0 description: 自定义技能的说明 entry: run.js inputs: inputFile: type: file description: 输入文件路径 required: true dryRun: type: boolean default: true

参数类型支持 string、number、boolean、file、choice 等。把参数声明做清楚，后面使用的时候就可以用交互式提示或者命令参数传入，也能自动生成帮助文档。我之前踩过一个坑：某个技能参数忘记声明required，结果同事使用时漏传了参数，技能直接读取到空值，处理完才发现结果不对。所以参数校验一定不能偷懒。

4.2 编写一个简单的“批量重命名”技能

下面写一个完整例子，主题是“批量重命名文件”。这个技能很常用，而且逻辑简单，适合作为第一个自定义技能。先创建目录skills/batch-rename/，然后创建skill.yaml：

name: batch-rename version: 1.0.0 description: 按正则规则批量重命名文件 entry: run.js inputs: dir: type: string default: "." description: 目标目录 pattern: type: string required: true description: 匹配文件名的正则表达式 replacement: type: string required: true description: 替换后的内容 dryRun: type: boolean default: true description: 预览模式，不真正改名

入口脚本run.js这样写：

const fs = require('fs'); const path = require('path'); exports.run = async (ctx) => { const { dir, pattern, replacement, dryRun } = ctx.inputs; const re = new RegExp(pattern); const files = fs.readdirSync(dir).filter((f) => re.test(f)); for (const file of files) { const next = file.replace(re, replacement); console.log(`${file} -> ${next}`); if (!dryRun) { fs.renameSync(path.join(dir, file), path.join(dir, next)); } } return { files, renamed: files.length }; };

引入这个技能后，可以用下面这条命令预览把IMG_001.png改成icon-IMG_001.png：

sp run batch-rename --dir ./images --pattern "^IMG_" --replacement "icon-$&" --dryRun

确认无误后，去掉--dryRun就会真正执行。这里有个小细节：run.js必须导出run方法，superpowers 会把解析好的参数封装成ctx.inputs传入，脚本的返回值会作为执行结果记录到日志里。如果你想把执行结果告诉下游技能，就通过对象返回关键数据。

4.3 发布与共享技能

自定义技能只留在本地太浪费了。superpowers 提供打包和发布能力，让你可以把技能分享给团队或社区。打包命令是：

sp pack ./skills/batch-rename

执行后会生成一个batch-rename.spkg文件，这个文件可以拷贝给同事，也可以上传到内部仓库或技能市场。发布到市场用sp publish，发布前最好确认技能有清晰的描述、版本号以及至少一个可运行示例。很多技能发布后没人用，不是功能不行，而是说明太敷衍。

我在团队内更推荐用.spkg文件离线分发。把打包好的技能放到共享目录，同事执行sp install ./batch-rename.spkg就能装好，不依赖外网。这种方式对网络受限的工作环境特别实用。

5. 常见问题与排查技巧实录

5.1 技能加载失败排查

我遇到最多的报错是sp run xxx提示skill not found。这个报错看起来像是技能没装，但实际原因可能有三类：技能没有写进superpowers.yml；技能确实装到了但目录不一致；入口文件没有正常导出run方法。

排查时可以按顺序来：先执行sp list看技能在不在清单中；再看.superpowers/skills/目录下有没有对应的技能文件夹；最后检查run.js是否存在并导出了正确接口。如果还是一头雾水，试试sp debug skill-name，它会输出更详细的运行日志。日志里基本能看出是参数解析失败还是脚本抛了异常。

5.2 版本冲突与依赖问题

技能本身是隔离运行的，但有些技能需要调用系统里已经安装的工具，比如 git、ffmpeg、go。这时候不同技能对工具版本的要求可能冲突。一个技能要求 ffmpeg 5.x，另一个技能只需要 4.x，如果简单地把两个技能放在同一环境里跑，很可能有一个会异常。

我的解决办法是尽量让技能通过npx或brew指定版本运行，把依赖“内化”到技能包里。比如批量处理视频的技能，可以固定执行npx ffmpeg-static来避免使用系统动态版本。如果冲突已经出现，先执行sp status查看当前技能和依赖树，再sp clean清理缓存后重试。多数情况下重装依赖可以解决。

5.3 离线环境下怎么用

有些工作环境不能访问外网，在线安装技能会一直卡住。提前在有网环境把技能打包成.spkg文件，拷贝到目标机器后使用离线安装：

sp install ./batch-rename.spkg --offline

也可以配置本地私有仓库地址，让sp sync从内网镜像源拉取技能包。修改~/.superpowersrc文件里的registry字段指向内网地址即可。注意离线安装时最麻烦的是技能包内部的第三方依赖，如果技能依赖 npm 包，你得先在有网环境里把这些依赖也一并打包进.spkg，否则离线机器上仍然无法拉取依赖。

5.4 性能与安全注意事项

superpowers 的技能本质就是代码，安装一个技能等于在本地运行一段不熟悉的程序，安全必须重视。我的原则是：只安装来自可信来源的技能，优先选作者明确、下载量高、更新频率正常的技能。别人的技能入口代码如果做了奇怪的网络请求或文件删除操作，要立刻停下。

在配置文件里可以开启沙箱模式：

sandbox: true timeout: 300

沙箱模式会限制技能的写权限和网络访问，超时设置则避免技能因为死循环一直占用 CPU。我自己每次写自定义技能时，会先用 dry-run 模式跑一遍，确认所有日志输出正常后再关掉只读开关。这个习惯帮我避免过好几次误删文件的低级事故。

6. 写在最后的几点实操建议

实践下来我最大的感受是，superpowers 这类“技能化工具”最值得借鉴的不是某个具体功能，而是它逼着你去梳理自己的重复劳动。以前我遇到重复操作，第一反应是写个一次性脚本用完就扔；现在我会想，这个操作能不能封装成一个带参数、带说明、带版本号的技能，下次直接sp run调起来。

给新手的建议也很简单：先从一个小场景切入，比如批量改文件名、生成周报、初始化项目目录，跑通一个技能之后再研究工作流和自定义技能。别急着把所有热门技能装一遍，技能多了反而不知道怎么用。把superpowers.yml纳入 git 仓库，这样新环境只需要一条sp sync就能恢复所有技能。最后一个小技巧：写完自定义技能一定要写--help的参数说明，因为一个月后你自己也会忘，更别说团队里其他人了。