企业官网建设流程全解析

最近一直在折腾superpowers，这个项目很对我的胃口。它不是又一个沉闷的开发框架，而是把“能力”本身当作一套可安装、可组合的技能包系统。简单说，装上它，你的工具链就像角色突然学了新技能一样，能做的事一下子宽了一大截。这篇就完整记录一下我从安装、拆解到实际组合技能包的全过程，以及中途踩进去又爬出来的那些坑。

1. 项目核心思路拆解：superpowers 到底在解决什么问题

1.1 为什么需要“技能包”而不是“新软件”

先说一个很实际的问题，你手上的开发工具、自动化脚本、AI 助手，能力边界其实都被“内置功能”框死了。编辑器就是写代码的，命令行工具就是跑命令，智能助手顶多帮你生成一段模板文本，一旦遇到稍微特殊一点的工作流，比如“分析仓库里的代码规范程度”或者“把零散笔记自动整理成周报”，就得自己动手写脚本、拼接口、反复调参。

superpowers的思路恰好是反着来的：它不给你一个完整的、封闭的大工具，而是提供一个轻量运行时，再配一套标准协议。你在这个运行时上安装一个个“技能包”（skills），这些技能包携带着特定的行为指令、工具脚本和输出目标。安装之后，你的工具就有了“超能力”，可以独立处理一个完整任务，或者被编排成一条工作流。

这种切片化的思路，类比一下就是手机装 App。你不会因为需要一个计算器就换一台手机，而是直接在系统里加一个应用。技能包把工具的“可扩展性”从源码层提升到了运行时层，装完即用，不重写业务代码。

1.2 它与全重框架、单体脚本的本质区别

我用过不少“全家桶”式的框架，它们的问题是一致的：太重了。想实现一个很小的自动化需求，也得拉一整套依赖、理解完整的抽象概念、遵循它们的生命周期规范。周期短的项目，光踩通这些就耗掉一半时间。

superpowers的设计是“最小侵入”。运行时只负责三件事：加载技能包、解析配置、执行能力调用。技能包本身是独立目录，核心是manifest 元数据 + 行为脚本 + 提示词模板。这意味着三件事：

• 技能和工具解耦，技能写在 YAML/TOML 里，执行逻辑可以用任意语言实现，不绑定技术栈
• 技能之间是松耦合的，可以单独安装、移除、升级，不影响其他包
• 没有运行时依赖地狱，核心跑起来只需要一个现代 Node.js 环境

我当时第一反应是，这本质上是把“功能”从“系统”里剥离出来了。你的工具链不再是一个单体项目，而是一个可以随时增减能力的“宿主环境”。面对一人多角色的工作场景，非常顺手。

1.3 适合谁用、适合什么场景

我个人的体会是，它最适合三种人：

• 独立开发者：自己的工具链自己搭，装几个技能包就能把重复工作交给自动化流程，省出时间写核心业务
• 技术团队内部效率小组：把常见的发版检查、代码审查、文档整理等流程做成技能包，团队共享，新人上手成本反而更低
• 内容生产与技术写作人员：利用技能包把信息整理、素材分析、初稿生成、格式规范检查等环节串起来，产出质量稳定性明显提升

理解的难点在于，不要把它当成一个“AI 工具”来看。它有定制的自动化能力，但技能包未必涉及大模型。所谓“技能”，本质上是“一个能独立完成目标事务的能力单元”。这部分想通了，后面的一切都是顺手的事。

2. 安装与基础配置：从零到第一个技能跑起来

2.1 环境准备：装之前先确认这些

先说环境，我实践下来其实要求很低，但有三样必须确认：

确认 Node 版本有个小技巧，终端里跑：

node -v && npm -v

如果输出像v20.10.0和10.2.4这种两行文字，就说明基本环境没问题。低于 18 的话，技能包的 manifest 解析会有兼容问题，后面跑superpowers validate时会报一堆 obscure error，建议直接升级。

2.2 安装运行时与脚手架

superpowers的运行时通过 npm 全局安装，命令非常简单：

npm install -g @superpowers/cli

装完确认一下版本：

superpowers --version

这里容易踩第一个坑：如果提示superpowers: command not found，多半是 npm 全局 bin 目录没加到 PATH。这不是工具的问题，是环境变量配置问题，自己检查一下npm prefix -g输出的目录，把它加到 shell 的 PATH 里就行。我自己的机器上这个目录是/usr/local/bin，加一行到~/.zshrc就彻底解决了。

2.3 初始化你的第一个工作区

运行时装好之后，别急着满世界找技能包，先初始化一个工作区。这个工作区是未来所有技能包的家。

mkdir my-superpowers && cd my-superpowers superpowers init

初始化过程会问你几个问题：

• 工作区名称
• 默认执行语言（我选的是 TypeScript，但选 JavaScript 或 Python 也完全没问题）
• 是否启用内置的自动更新检查

生成之后的目录结构大致如下：

my-superpowers/ ├── superpowers.config.toml ├── skills/ ├── hooks/ ├── templates/ ├── logs/ └── package.json

这个结构是留给你自己生态的骨架。superpowers.config.toml是全局配置，skills目录就是未来存放技能包的地方，hooks用来放自定义生命周期钩子，templates是脚手架模板目录，logs顾名思义是日志。

2.4 配置文件里必须改的三个关键项

默认的superpowers.config.toml可以直接用，但有三个字段我建议你初始化完立刻改掉：

[workspace] name = "my-workbench" default_language = "typescript" auto_update_interval = 86400 [execution] sandbox = true timeout_seconds = 30 max_concurrency = 4 [registry] endpoint = "https://registry.superpowers.dev" cache_dir = ".cache/skills"

第一个是sandbox，强烈建议保持为true。它能阻止技能包在未经允许的前提下读写工作区以外的文件。默认false的话，第三方技能包理论上能碰你系统里的任何路径，这个风险没必要冒。

第二个是timeout_seconds，这决定了单个技能执行的最长等待时间。如果技能包要调用外部 API，30 秒是合理起步。网络状况不太好的话可以放宽到 60 秒。

第三个是registry.endpoint，这是技能包市场地址。默认官方源稳定，不需要动。如果是内网环境，可以自己搭一个私有源，改这一个字段就行。

2.5 验证环境

配置改完，跑一个自检命令确认整体状态：

superpowers doctor

它会检查运行时版本、配置文件合法性、技能包目录可写性、网络到 registry 的连通性。我那次跑出来 5 项全绿，就直接进入下一步了。如果某项红了，按提示处理就好，常见的是权限问题，给logs和.cache目录加可写权限即可。

chmod -R u+rwx logs .cache

这个过程其实很轻，十五分钟以内就能完成。真正的重头戏是技能包本身，下面这部分内容最多。

3. 核心玩法拆解：技能包的类型、结构与安装实战

3.1 技能包的本质：一个自带目标的执行单元

我一直强调一个理解句式：技能包就是一个自带执行目标的封装函数。它不关心你的业务代码怎么写，只关心“给它一份输入，它能不能完成指定动作，然后把结构化的产出物交给你”。

一个技能包通常解决一个具体的领域问题。举例来说：

• 代码审查技能：输入一个 Git 分支或 PR 链接，输出规范性问题清单
• 内容整理技能：输入一堆碎片化笔记，输出结构化 Markdown 文档
• 依赖安全检查技能：输入package.json，输出高危依赖清单
• 文本风格统一技能：输入中英文混合文档，输出符合某种风格指南的修订版

这些技能包不会出现在你的项目依赖里，它们只存活在superpowers的运行时内。所以业务代码和技术工具之间是彻底隔离的。工具链升级、技能包替换，都不会波及你的核心模块。

3.2 三分钟装好一个技能包

安装技能包走 registry 源是最省事的方式：

superpowers add skill code-reviewer

这个命令会在几秒内完成下载、校验、注册三步。之后你可以在工作区里查到所有已安装技能：

superpowers list

输出类似：

已安装技能包 ┌─────────────────┬──────────┬──────────────┬────────────┐ │ 名称 │ 版本 │ 状态 │ 依赖内置工具 │ ├─────────────────┼──────────┼──────────────┼────────────┤ │ code-reviewer │ 1.2.0 │ ready │ git,node │ └─────────────────┴──────────┴──────────────┴────────────┘

有时你想装一个还没上官方源、但在 GitHub 上已经有仓库的技能包。这种情况就改用 git 地址安装：

superpowers add skill git@github.com:someauthor/some-skill.git

有些老手习惯直接把技能包目录 clone 到skills/下，再运行superpowers refresh。这条路也行，但我不太推荐。一是少了版本管理，二是后续更新麻烦。能走 registry 就走 registry。

3.3 从哪里找技能包

技能包的主要来源是官方 registry，网址是https://registry.superpowers.dev，上面有技能包的目录、版本、维护状态。在终端里也能直接搜：

superpowers search skill code

这会返回名称里带 code 的所有技能包，并显示简要说明、标签和下载量。我常用的搜索词就是code、doc、crypto、data、automation这些，覆盖面基本够了。

还有一批技能包散落在 GitHub 上，质量参差不齐。装上之后先用superpowers inspect检查一下它的 manifest 和脚本内容，确认没有恶意命令再实际使用。这个习惯我从第一天就养成了，虽然没有遇到过明摆着搞破坏的包，但作为安全底线还是值得坚持。

3.4 技能包内部到底长什么样

拿一个最简技能包举例，目录结构如下：

code-reviewer/ ├── manifest.toml ├── src/ │ ├── main.ts │ └── utils.ts └── assets/ └── prompts/ └── review_system.txt

manifest.toml是技能包的身份证，包含包名、版本、入口文件、所需工具、超时设置等元数据。示例片段：

[package] name = "code-reviewer" version = "1.2.0" description = "审查代码规范、发现潜在缺陷与安全隐患" entry = "src/main.ts" language = "typescript" [package.requires] tools = ["git", "node"] [execution] timeout = 30 allowed_network = true

src/main.ts是执行逻辑，它接收标准输入，处理后输出标准结构。assets/prompts目录通常放着提示词模板，如果你的技能包接入了大模型编辑器，这些提示词就会在推理时发挥关键作用。

这个结构有一个很关键的优点：任何技能包都可以被审查。它不像黑盒插件一样塞给你一堆二进制，所有行为都是可见的文本。这对追求可控性的团队来说，是非常重要的特质。

3.5 卸载与禁用：可逆操作，放心试

装多了肯定有觉得鸡肋的，卸载也很干净：

superpowers remove skill code-reviewer

如果只是暂时不想用，但又不想删掉配置，可以禁用：

superpowers disable skill code-reviewer

禁用状态下，技能包保留在目录里，在superpowers list中会标记为 disabled，但不会被任何工作流调用。这个设计很贴心，因为重新启用比重新安装快得多。我实际使用中反复横跳过很多次，完全无压力。

4. 实操实录：从下载技能到跑通一条自动化工作流

4.1 选定场景：把“素材收集-初稿生成-格式规范”串起来

这次实操，我给自己设定了一个很现实的场景：每周写一篇工具评测类文章，但素材分散在十几个书签、几十条零散笔记和几个网页里。过去手动整理材料就要浪费大半天。现在用superpowers，把三个技能包装进同一条工作流：

• content-collector：负责汇总输入源，解析网页正文、抽取关键信息
• draft-writer：基于收集到的结构化素材，生成初始内容框架和段落文字
• format-normalizer：统一标题层级、修复中英文标点、检查与风格指南的一致性

这三个技能包的组合，覆盖了从原始素材到成稿雏形的完整链路。核心思路是把“中间产物”设计成约定好的 JSON 结构，让每个技能包只管自己的输入与输出。

4.2 执行任务的两种方式

第一种是单次运行。在工作区目录里，直接传一个输入文件：

superpowers run content-collector --input ./raw/links.json

第二种是带上下文的批量运行。把三个技能包按顺序串起来，其中前一个的输出就是后一个的输入，这就是工作流模式。我建议先准备一个简单的编排文件：

# flow.yaml flow: - skill: content-collector input: ./raw/links.json - skill: draft-writer input: @content-collector - skill: format-normalizer input: @draft-writer

然后执行：

superpowers run --flow flow.yaml --output ./output/

这个跑起来非常顺畅。@content-collector这种引用语法意味着，后面技能包的输入直接取前面技能包的标准输出。整个过程不需要胶水代码，不需要临时文件中转，最终产物落在./output/目录里。我第一次跑通的时候，感觉这就是脚本流水线的正确打开方式。

4.3 执行过程中的日志与可视化

运维过定时脚本的人都懂，进度不可见是最痛苦的。superpowers在 stdout 上会实时输出每个技能的状态：

[superpowers] 技能包 "content-collector" 启动 [superpowers] 技能包 "content-collector" 完成，输出 124 个结构块 [superpowers] 技能包 "draft-writer" 启动 [superpowers] 技能包 "draft-writer" 完成，输出 5400 字草稿 [superpowers] 技能包 "format-normalizer" 启动 [superpowers] 技能包 "format-normalizer" 完成，输出格式已规范化

进度、耗时、错误定位一目了然。如果某个环节卡住，终端会打印出具体的调用栈和上下文，不用盲猜问题出在哪个包上。这一点在调试多技能流水线时，简直就是救命设计。

所有历史日志都会落在logs/目录下，按天滚动。跑完一个流程后去翻日志，能看到每个技能包的实际耗时、使用的输入来源，以及最终状态。

4.4 对结果做二次调整

技能包给出的结果不一定直接能用。比如我的draft-writer生成初稿时，风格偏正式，不够口语化。我的处理方法是手动过一遍，把重点段落改得更直白，然后把它发送给format-normalizer再跑一次：

superpowers run format-normalizer --input ./output/draft.md --output ./output/final.md

整个过程在十分钟内完成，对比以前纯手工整理，效率提升非常明显。尤其推荐给需要高频产出内容的团队，技能包把“枯燥的加工环节”全部消化掉了，人只需要在关键节点上做判断和修改。

5. 自定义技能包：把重复劳动封装成自己的能力

5.1 什么情况值得自研技能包

市面上的技能包虽然多，但真正贴合自己工作场景的往往还是要自己写。我的判断标准是：如果一件事你需要重复处理三次以上，且每次的步骤完全一致，就值得封装成技能包。

比如我有个高频操作：从公司内部代码仓库拉取最近三天的变更，按模块归类，生成一份更新摘要。这属于典型的“外部技能包做不了”的场景，因为它依赖内部系统、内部路径和内部规范。这时候自研一个私有技能包是效率最高的解。

5.2 用脚手架生成技能包骨架

superpowers提供了一个很省事的脚手架命令：

superpowers create skill internal-changelog

执行后会在当前工作区生成一个标准化目录，包括manifest.toml、src/main.ts、README.md。接下来只需要填业务逻辑。

5.3 一个完整技能包的 manifest 参考

我自定义的internal-changelog包，manifest 是这样的：

[package] name = "internal-changelog" version = "0.1.0" description = "从 Git 仓库生成按模块分组的最近变更摘要" entry = "src/main.ts" language = "typescript" [package.requires] tools = ["git", "node"] [execution] timeout = 60 allowed_network = false

这里特别说一下allowed_network = false。因为这个技能包只读取本地仓库，不需要访问外网，关掉网络调用反而更安全，可以避免潜在的数据外泄。对外部 API 的访问，按需开启，不要无脑全开。

5.4 主逻辑的标准写法

技能包的入口脚本要遵循一套输入输出约定。输入默认从 stdin 读取 JSON，输出写到 stdout。下面是一个简化版的main.ts：

#!/usr/bin/env node import { readFileSync } from "fs"; interface Input { repoPath: string; days: number; } interface ChangelogEntry { module: string; summary: string; } const input: Input = JSON.parse(readFileSync(0, "utf-8")); const entries: ChangelogEntry[] = [ { module: "core", summary: "修复了缓存穿透问题，优化了查询性能", }, { module: "api", summary: "新增批量删除接口，补充了对应的 OpenAPI 描述", }, ]; console.log(JSON.stringify({ entries }, null, 2));

这只是示意代码，真实场景中你会在这里执行git log命令、解析提交记录、按关键字归类模块。但不管逻辑多复杂，守住“输入是 JSON、输出是 JSON”的约定，技能包就能被运行时正常接管。

5.5 本地验证与调试

开发技能包时，不需要发布到远端，本地直接验证：

superpowers inspect internal-changelog superpowers test internal-changelog --input ./test/fixture.json

inspect会解析 manifest 并检查入口文件的语法是否合法。test会真正执行一次技能逻辑，并打印输出结果。我把一个典型 fixture 放在test/fixture.json里，反复跑了几轮，把边界情况逐一处理掉，整个包就算成型了。

5.6 发布到私有源还是留在本地

如果技能包只给自己用，放在工作区的skills/目录下就足够了。如果团队里其他人也想用，可以把技能包推到私有 Git 仓库，然后同事通过superpowers add skill <repo-url>安装。更规范的是搭建一个私有 registry 服务，把包上传上去统一管理。具体方案取决于团队规模，不为这个小团队场景过度设计。

6. 真实场景复盘：我拿 superpowers 做的三件具体工作

6.1 自动化代码审查辅助

我给其中一个项目装上了code-reviewer技能包，每次往测试分支推送代码之后，跑一次审查：

superpowers run code-reviewer --input ./git/diff/current.json

它的输入是一份包含变更信息的 JSON 文件，输出是问题清单，用严重级别分类。我把它的输出导到 PR 描述里，再手动筛选一遍，比自己扫代码高效得多。有些低级错误比如忘记了处理空指针、异常被吞，它能抓出来，人工再过一遍就只会关注真正的逻辑决策。

6.2 个人知识库的自动整理

我有个本地笔记目录，里面一半是英文文档的摘录，一半是中文随笔，杂乱无章。我用content-collector配合draft-writer做了个半自动化流程：

superpowers run content-collector --input ./notes/raw superpowers run draft-writer --input @content-collector --output ./notes/processed

经过技能包处理后，所有笔记按主题聚合成结构化文档，标题统一用了约定的层级，标签从内容里自动提取。旧笔记变成了一棵清晰的知识树，我做周报时直接从这里取材料。

6.3 团队内部分享文案的快速产出

团队周会前的分享材料，以前我要找模板、查历史、改格式，每次都是重复动作。现在用一个内部技能包share-brief，输入主题关键词，输出一份包含背景、目标、现状、建议四段式的简报草稿。虽然最终的措辞还是我自己梳理，但框架和基础内容不再从零开始。

6.4 怎么样才算“用得好”

我用到现在最大的心得是：别把 superpowers 当成一个独立的“工具”来膜拜，它是一套承载能力的容器。当你把重复出现的流程拆成技能包，组合出属于自己的工作流时，这个过程本身就在积累资产。三个月前我搭的第一个流程，现在还在用，而且因为技能包版本管理的存在，我升级了一版只改配置，业务逻辑没动过。

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

7.1 安装或执行时报 command not found

这个基本就是 PATH 没配置全。检查npm prefix -g的输出，确认全局 bin 目录在$PATH中。以 macOS/Linux 为例，临时解决可以这样：

export PATH="$(npm prefix -g)/bin:$PATH"

想永久生效，把上面这行加到~/.zshrc或~/.bashrc。

7.2 技能包下载慢或连接超时

如果你的网络环境访问默认 registry 源不稳定，可以考虑启用镜像源。在superpowers.config.toml的[registry]部分加一行：

endpoint = "https://mirror.internal.example.com/superpowers"

如果你的团队有自建源，指向自建源通常更快。不要随便在公共社区求第三方镜像地址，来源不明的东西最容易埋雷。

7.3 技能包执行时报EACCES: permission denied

普遍原因是你运行superpowers的用户对logs或.cache目录没有写权限。直接修复：

sudo chown -R $(whoami) logs .cache sudo chmod -R u+rwx logs .cache

如果你在 CI 里跑，需要注意 CI 工作目录的权限配置，提前在流水线脚本里把这两行加进去。

7.4 manifest 解析失败或技能包变为 unknown status

多数情况是 manifest 里某个必填字段没填，或者版本号格式不规范。先用：

superpowers validate <skill-name>

它会输出具体哪个字段有问题。我遇到过的典型是entry路径写错了，指向不存在文件，改成正确路径后一切恢复正常。

7.5 自定义技能包执行成功但输出为空

先确认主脚本有没有往 stdout 输出 JSON。如果逻辑里把结果只写到了日志文件、没有console.log(JSON.stringify(result))，运行时就拿不到输出。我早期写技能包时踩过这个坑，排查了好一阵才意识到是输出协议没遵守。

7.6 多个技能包并发执行时资源竞争

superpowers支持并发执行，默认并行度是 4。如果你的机器配置一般，或者技能包逻辑里面启动了子进程，容易内存飙升。调低并行度：

[execution] max_concurrency = 2

7.7 快速排查表

8. 进阶技巧与避坑心得

8.1 版本冻结是省心之源

技能包会持续更新，新版本确实带来新能力，但也有可能改变接口行为。如果你有一条跑通很久的稳定工作流，建议锁定技能包版本：

superpowers pin skill code-reviewer 1.2.0

这样后续升级不会破坏现有流程。想升级时再手动解绑：

superpowers unpin skill code-reviewer superpowers upgrade skill code-reviewer

我见过太多人因为某个依赖偷偷升级导致整个流水线挂了，所以这条我一直放在第一位。

8.2 善用 hooks 做发布前检查

hooks/目录可以放置一些自定义生命周期脚本。比如我在superpowers run每次执行结束时都会触发一个after-runhook，它负责把关键输出摘要同步到内部团队群。这算是一个轻量的事件机制，适合做通知、归档、外部联动等场景。

8.3 写技能包时先定义输入输出再写逻辑

我踩过一次比较深的坑：先写了处理逻辑，再回头补输入输出结构，导致改了两版才跑通。建议是先把manifest.toml和输入类型定义写清楚，把输入样例造好，再去实现main.ts。数据和逻辑分离，调试成本直线下降。

8.4 关于安全的一个极简主义原则

外部技能包装进来之前，至少抽一分钟用superpowers inspect看看它调了哪些工具、有没有请求网络权限、entry 指向了哪个文件。allowed_network这个字段是最后的开关，默认能不开就不开。技能包生态天然是开放的，开放生态里自己守住底线很重要。

对我个人来说，superpowers最大的吸引力不是某个具体技能包有多强，而是它把一个“工具链”变成了一套“可积累的能力体系”。每一次把重复劳动封装成技能包，都是在给自己省未来的时间。如果你也正被大量可自动化但尚未自动化的流程缠住，不妨从一个小场景开始，装上环境、选一个技能包、跑通一条最简工作流。先别急着贪多，把一个场景彻底跑顺，你会自然体会到这套扩展式玩法带来的爽感。