企业官网建设流程全解析

1. 从“superpowers”这个标题说起：它到底是什么

第一次看到“superpowers”这个词，很多人脑子里蹦出来的可能是超级英雄、超能力这类画面。但在技术圈子里，尤其是最近一段时间，这个词被反复提起，语境完全不一样。它指的是一套围绕 AI 编程助手构建的技能扩展体系，核心思路是给 AI 助手装上“外挂”，让它在处理具体开发任务时，能调用预设好的技能模块，而不是每次都从零开始“即兴发挥”。

说白了，superpowers 解决的是一个很现实的问题：你让 AI 帮你写代码、做重构、生成文档，它有时候表现惊艳，有时候又离谱得让人想砸键盘。这种不稳定的根源在于，AI 每次都在用通用能力应对具体任务，缺少针对性的“操作手册”。superpowers 就是把这些操作手册固化下来，变成一个个可复用的技能包，AI 在需要的时候自动加载，行为就稳定多了。

这套东西适合谁？我梳理了一下，大概三类人最需要关注。第一类是日常用 AI 辅助编码的开发者，想让 AI 输出更靠谱、更贴合项目规范；第二类是团队技术负责人，希望统一团队里 AI 工具的使用方式，避免每个人调教出来的结果千差万别；第三类是对 AI 工作流感兴趣的技术爱好者，想搞清楚这套技能机制到底怎么运转、能不能自己扩展。

需要提前说明的是，superpowers 本身不是一个独立的软件，它更像是依附于现有 AI 编程工具的一套配置体系和技能库。你仍然需要有一个基础的 AI 助手环境，superpowers 在这个基础上做增强。理解这一点很关键，否则你会以为装个包就万事大吉了。

2. 核心设计思路拆解：为什么要做成“技能包”而不是“大提示词”

2.1 通用提示词的三个死穴

大多数人用 AI 编程助手的方式，是在对话里写一段长长的提示词，把要求、背景、约束条件全塞进去。这种方式在简单场景下能用，但一旦任务复杂起来，问题就暴露了。

第一个死穴是上下文稀释。你写了两千字的提示词，里面真正关键的约束可能就三五条，但 AI 在处理的时候，所有文字都在争夺注意力，关键信息反而被淹没了。就像你给一个新同事交代工作，啰嗦了半小时，他记住的可能还不如你写在一张便签上的三条要点。

第二个死穴是不可复用。你这次调教好了，下次换个会话窗口，一切归零。团队里其他人更不可能直接受益，每个人都在重复造轮子。

第三个死穴是难以维护。提示词越写越长，改一处可能影响另一处，最后变成一坨谁也不敢动的“祖传提示词”。

2.2 技能包机制怎么解决这些问题

superpowers 的思路是把“大提示词”拆成“小技能”。每个技能只负责一件事，比如“生成符合项目规范的单元测试”“按照约定式提交格式写 commit message”“对指定文件做安全审查”。技能之间有清晰的边界，互不干扰。

这样做的好处很直接。AI 在处理任务时，只会加载当前任务相关的技能，上下文干净，注意力集中。技能可以独立更新，改一个不影响其他。技能可以共享，团队里一个人写好，其他人直接拿来用。

我打个比方。通用提示词就像你每次做饭都从头翻一本厚厚的菜谱，而技能包就像你把常做的几道菜的做法抄成了卡片，做饭时只抽需要的卡片出来看。效率差别一目了然。

2.3 技能加载的触发逻辑

这里有一个关键设计需要理解：技能不是全部常驻的，而是按需加载。AI 助手会根据当前任务的性质，判断需要调用哪些技能。这个判断过程依赖于技能的描述信息——每个技能都有一段简短的说明，告诉 AI“我是干什么的、什么时候该用我”。

这个机制有点像公司里的专家通讯录。你遇到法务问题，不会把法务、财务、人事全叫来开会，而是根据问题类型找到对应的专家。技能描述就是那个通讯录条目，写得越清楚，AI 匹配得越准。

注意：技能描述的质量直接决定了加载准确率。描述写得太宽泛，AI 可能在不该用的时候调用它；写得太窄，又可能该用的时候想不起来。这个度需要在实际使用中反复调整。

3. 安装与环境准备：从零搭起一套可用的技能体系

3.1 前置条件确认

在动手安装之前，有几件事必须先确认清楚，否则后面会卡在莫名其妙的地方。

首先，你需要有一个可用的 AI 编程助手环境。superpowers 是增强层，不是替代品。不同的助手环境对技能机制的支持程度不一样，有的原生支持，有的需要额外配置。建议先确认你用的工具是否在支持列表里。

其次，确认你的运行环境版本。这类工具通常对 Node.js 或 Python 版本有要求，版本太低会直接报错。我建议 Node.js 用 18 以上的 LTS 版本，Python 用 3.10 以上。这不是随便说的，低版本在依赖解析和异步处理上差异很大，容易出玄学问题。

第三，确认网络环境能正常访问所需的包管理源。这一步经常被忽略，但实际安装时一半以上的失败都出在这里。

3.2 安装步骤详解

安装过程本身不复杂，但每一步都有坑，我按实际操作顺序说。

第一步，全局安装核心包。打开终端，执行安装命令。这里要注意，如果你之前装过旧版本，先卸载干净再装，否则可能出现版本冲突。卸载和安装之间建议重启一下终端，让环境变量刷新。

# 先卸载旧版本（如果装过） npm uninstall -g superpowers # 重新安装最新版 npm install -g superpowers

第二步，初始化配置。安装完成后，需要运行初始化命令，生成默认的配置文件。这个配置文件决定了技能库的位置、加载策略、日志级别等。

superpowers init

执行完这一步，你的用户目录下会多出一个配置目录，里面包含默认技能库和配置文件。我建议先别急着改配置，用默认配置跑一遍，确认基础功能正常再说。

第三步，验证安装。运行版本检查命令，确认安装成功。

superpowers --version

如果能看到版本号输出，说明核心部分没问题。如果报“command not found”，大概率是全局安装路径没加到环境变量里，需要手动配置 PATH。

3.3 安装后的目录结构说明

初始化完成后，你会看到类似这样的目录结构：

~/.superpowers/ ├── config.json # 主配置文件 ├── skills/ # 技能库目录 │ ├── builtin/ # 内置技能 │ └── custom/ # 自定义技能 ├── logs/ # 运行日志 └── cache/ # 缓存目录

这个结构要记清楚，后面添加自定义技能、排查问题都要在这里操作。skills/builtin目录里的技能是随安装包一起提供的，升级时会被覆盖，所以不要在这里放自己写的东西。自定义技能一律放skills/custom。

提示：建议把~/.superpowers目录纳入你的常规备份范围。技能库积累到一定程度后，这是很有价值的个人资产。

4. 核心技能类型与实操要点

4.1 代码生成类技能的使用要领

代码生成是使用频率最高的一类技能。这类技能的核心价值在于，它能把项目的编码规范、目录结构约定、命名习惯等“隐性知识”固化下来，让 AI 生成的代码直接就能用，而不是生成一堆需要大改的“看起来对但风格完全不对”的东西。

实际使用中，我发现最关键的是在技能里写清楚项目特有的约定。比如你们项目用的是哪种错误处理模式、API 返回值的包装格式是什么、日志用什么库、测试文件放在哪个目录。这些信息如果不在技能里说明，AI 就会按它自己的习惯来，生成的结果虽然能跑，但和项目格格不入。

一个实用的做法是，把你项目里最规范的几个文件作为示例放进技能描述里。AI 看到真实示例，模仿的准确率会大幅提升。这比写一堆抽象规则管用得多。

4.2 代码审查类技能的配置方法

代码审查类技能用来让 AI 帮你检查代码问题。这类技能配置的重点是明确检查范围和检查标准。

检查范围要具体。不要写“检查代码质量”这种模糊描述，而要写“检查是否存在未处理的 Promise rejection”“检查是否有硬编码的敏感信息”“检查循环里是否有不必要的重复计算”。范围越具体，AI 的检查越有针对性，误报也越少。

检查标准要可操作。比如“变量命名要清晰”这种标准，AI 理解起来很模糊。改成“布尔变量必须以 is/has/can 开头”“常量必须全大写加下划线”，AI 就能准确执行。

我自己的经验是，代码审查技能不要贪多，一次专注三到五个检查点就够了。检查点太多，AI 的注意力分散，每个都查得不深。宁可分多个技能，按场景调用。

4.3 文档生成类技能的模板设计

文档生成类技能的价值在于统一文档风格。团队里每个人写文档的习惯不一样，有的喜欢详细，有的喜欢简洁，最后文档库看起来像拼凑的。用技能把文档模板固定下来，输出就一致了。

模板设计有几个要点。第一，结构要固定，标题层级、章节顺序都定死。第二，必填项和选填项要区分清楚，必填项缺失时 AI 应该主动追问。第三，要包含示例，让 AI 知道每个部分大概写多少、写到什么程度。

我见过一个很好的实践，是在文档技能里内置一个“检查清单”，AI 生成完文档后，自己对照清单检查一遍，缺什么补什么。这个自检机制能显著提升输出质量。

4.4 技能组合使用的策略

单个技能解决单点问题，但实际任务往往是复合的。比如“给这个模块加一个新功能”，可能涉及代码生成、测试生成、文档更新三个环节。

superpowers 支持技能组合，你可以定义一个“工作流技能”，把多个基础技能串起来。AI 执行时按顺序调用，前一个的输出作为后一个的输入。

组合的时候要注意依赖关系。比如测试生成依赖代码生成的结果，那代码生成必须先执行。这个顺序要在工作流定义里写清楚，否则 AI 可能并行处理，导致测试基于旧代码生成。

注意：工作流技能调试起来比单技能麻烦，建议先把每个单技能调通，再组合。组合后如果出问题，逐个拆开验证，定位是哪个环节的毛病。

5. 自定义技能开发：从使用者变成创造者

5.1 技能文件的基本结构

一个技能就是一个目录，里面至少包含一个描述文件和一个执行逻辑文件。描述文件告诉 AI 这个技能是干什么的、什么时候用；执行逻辑文件定义具体怎么做。

描述文件通常用 YAML 或 JSON 格式，包含技能名称、描述、触发条件、输入参数、输出格式等字段。其中描述和触发条件最重要，直接决定 AI 能不能在正确的时机调用它。

执行逻辑可以是一段提示词模板，也可以是一段脚本。如果技能逻辑简单，用提示词模板就够了；如果涉及文件操作、命令执行等，就需要写脚本。

5.2 写一个自定义技能的完整过程

我拿一个实际例子来说：写一个“生成数据库迁移脚本”的技能。

第一步，确定技能的边界。这个技能只负责根据模型定义的变化，生成对应的迁移脚本，不负责执行迁移，也不负责回滚。边界清晰，技能才稳定。

第二步，写描述文件。描述要回答三个问题：这个技能做什么、什么时候用、需要什么输入。触发条件要写清楚，比如“当用户提到数据库结构变更、模型字段增删时触发”。

第三步，写执行逻辑。核心是把模型定义和数据库当前状态的差异分析清楚，然后按照项目使用的迁移框架的语法生成脚本。这里要把迁移框架的版本、命名规范、文件存放位置都写进技能里。

第四步，测试。找几个典型的模型变更场景，看技能生成的脚本是否正确。特别要测试边界情况，比如字段重命名、类型变更、添加索引等。

第五步，迭代。根据测试结果调整描述和逻辑，直到稳定。

5.3 技能调试的实用技巧

调试技能最头疼的是“AI 不按预期调用”。明明写了触发条件，但 AI 就是不用。这种情况我遇到过很多次，总结下来原因通常有三个。

一是描述写得太抽象。AI 匹配技能靠的是语义相似度，描述越具体、越贴近实际使用场景的说法，匹配越准。把“处理数据”改成“当用户要求对 CSV 文件做去重和格式转换时触发”，效果立竿见影。

二是技能太多，互相干扰。技能库大了之后，相似技能之间会竞争。解决办法是定期清理不用的技能，或者给技能分组，按项目加载。

三是优先级配置问题。有的技能框架支持设置优先级，高优先级的技能会先被考虑。如果某个技能总是抢不到，检查一下优先级配置。

5.4 技能库的版本管理

自定义技能积累多了，就需要版本管理。我建议把skills/custom目录做成一个独立的 Git 仓库，每次修改都提交，写清楚改了什么、为什么改。

这样做的好处是，技能改坏了可以回滚，多人协作时可以合并，换电脑时可以快速恢复。技能库是越用越值钱的东西，值得认真对待。

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

6.1 安装类问题速查

安装类问题里，权限问题最容易被误判。很多人看到“permission denied”就以为是系统问题，其实配置一下 npm 的用户级安装目录就能解决，不需要动系统权限。

6.2 技能不生效的排查思路

技能不生效，按这个顺序排查：先确认技能文件在正确的位置，再确认描述文件格式正确，然后确认触发条件写对了，最后看日志里有没有加载记录。

日志是关键。~/.superpowers/logs目录下的日志会记录每次技能加载的决策过程。如果日志里显示技能被加载了但没执行，问题在执行逻辑；如果根本没加载，问题在描述或触发条件。

我踩过的一个坑是，技能描述文件里用了中文标点，导致解析失败。这种问题日志里会有明确的解析错误提示，但如果不看日志，光看现象会完全摸不着头脑。

6.3 输出质量不稳定的应对

同样的技能，有时候输出很好，有时候一塌糊涂。这种波动通常来自三个因素。

一是输入信息的完整度。AI 拿到的上下文越完整，输出越稳定。如果技能依赖项目信息，确保这些信息在调用时能被正确传入。

二是技能描述的清晰度。描述里有歧义，AI 的理解就会飘。把描述当成给新人的操作手册来写，越明确越好。

三是模型本身的随机性。这个没法完全消除，但可以通过在技能里增加“自检”环节来缓解。让 AI 生成完后再对照要求检查一遍，能过滤掉大部分低级问题。

6.4 性能优化的几个方向

技能库大了之后，加载和执行会变慢。优化方向有几个。

精简技能数量，合并功能重叠的技能。每个技能都有加载开销，数量越多越慢。

优化技能描述，减少不必要的文字。描述文件在每次决策时都要被读取，太长会影响速度。

合理使用缓存。对于不常变化的技能，可以启用缓存，避免重复解析。

提示：性能问题通常在技能超过五十个之后才明显。如果只是日常使用，不用太早操心这个。

7. 我个人的一些使用体会

用了一段时间 superpowers 之后，最大的感受是：它改变的不是 AI 的能力上限，而是 AI 的稳定性下限。以前用 AI 写代码，好的时候惊为天人，差的时候想砸电脑。现在有了技能约束，输出质量的下限被抬高了，虽然偶尔还是会有惊喜或惊吓，但整体可控多了。

另一个体会是，技能库的积累是个长期过程。刚开始可能只有几个技能，用着用着发现某个场景反复出现，就把它固化成技能。半年下来，技能库就成了你个人经验的数字化沉淀。这个东西的价值，随着时间推移会越来越明显。

还有一点，不要指望技能能解决所有问题。有些任务就是需要人的判断，AI 再强也替代不了。技能的作用是把重复性的、有明确规则的部分自动化，让人能腾出精力处理真正需要思考的部分。想清楚这个定位，用起来就不会有落差。