企业官网建设流程全解析

1. 从“superpowers”这个热词说起：它到底指什么

“superpowers”这个词最近在技术社区和效率工具圈子里被反复提起，很多人第一次看到它，会下意识联想到漫威电影里的超能力，但在当前的技术语境下，它指的是一套围绕AI 编程助手能力扩展的方法论与工具集合。简单来说，它试图解决一个非常具体的痛点：大语言模型在写代码时，往往缺乏对项目上下文、历史决策和团队规范的持续记忆，导致每次对话都像“重新认识你一遍”。而 superpowers 这套思路，就是通过结构化的技能定义、上下文注入和任务编排，让 AI 助手在特定项目里表现得像是“开了挂”。

我第一次接触这个概念是在一个前端重构项目里。当时团队用 AI 辅助生成组件代码，效率确实有提升，但问题也很明显：生成的代码风格不统一、重复引入已经废弃的工具函数、对业务字段的命名习惯完全无视。后来有人提出，能不能把项目的“规矩”提前告诉 AI，让它每次生成之前先读一遍？这个朴素的想法，其实就是 superpowers 类工具的核心逻辑——把隐性的工程知识显性化，再喂给模型。

这篇文章适合几类人看：一是已经在日常开发中重度使用 AI 编程助手，但觉得“不够顺手”的工程师；二是团队技术负责人，想统一 AI 生成代码的质量标准；三是对 AI 工作流感兴趣，想了解如何把零散提示词沉淀为可复用资产的产品或运营同学。我会从核心机制、安装配置、技能编写、实战踩坑几个角度展开，尽量把每个环节的“为什么”讲清楚，让你看完能直接上手搭一套自己的 superpowers 工作流。

需要提前说明的是，superpowers 并不是某一个具体的商业产品，而更像是一种模式。市面上有多个开源项目和个人实现都在用这个名字或类似概念，它们的共同点是：通过文件系统或配置层，为 AI 助手提供可检索、可组合的“技能包”。所以你在搜索“想要安装 superpowers”时，可能会看到不同的仓库和教程，这很正常。关键是理解它的运作原理，这样无论你选哪个实现，都能快速迁移。

2. superpowers 的核心机制：技能包、上下文注入与任务编排

2.1 技能包不是提示词模板，而是带元数据的知识单元

很多人第一次听说 superpowers，会以为它就是“把提示词存成文件”。这个理解只对了一半。普通的提示词模板通常是纯文本，比如“你是一个资深前端工程师，请帮我写一个 React 组件”。而 superpowers 里的技能包，往往包含几个关键部分：触发条件、执行步骤、依赖工具、输出格式约束、以及失败回退策略。

举个例子，一个名为“生成符合团队规范的 API 请求函数”的技能包，可能会这样定义：当用户提到“新增接口调用”时触发；执行步骤包括读取项目中的request.ts封装、检查是否有同名字段已存在、按照useXxxQuery的命名模式生成代码；依赖工具是文件读取和代码搜索；输出格式要求返回 TypeScript 代码块并附带字段映射说明。这种结构化的定义，让 AI 助手不再是“随机发挥”，而是按照预设的工程路径去执行。

我自己的做法是，把技能包分成三层：基础层（如代码格式化、提交信息生成）、领域层（如特定业务模块的 CRUD 生成）、项目层（如某个老系统的兼容性处理）。基础层可以跨项目复用，领域层和项目层则跟着仓库走。这样既保证了通用能力，又不会让技能包变得臃肿。

2.2 上下文注入的关键在于“按需检索”而非“全量塞入”

大语言模型的上下文窗口是有限的，即使现在动辄 128K 甚至更大，把整个项目的代码都塞进去也是不现实的——成本高、噪音大、模型反而容易迷失重点。superpowers 类工具通常采用按需检索的策略：根据当前任务的关键词，从技能库和项目文件中动态拉取最相关的片段。

具体实现上，常见的有两种路径。一种是基于文件路径的约定，比如把所有技能放在.ai/skills/目录下，每个技能一个 Markdown 文件，文件名就是技能 ID。当用户输入任务时，工具会根据关键词匹配文件名和文件内容，选出 Top N 个技能注入上下文。另一种是基于向量检索，把技能描述和项目文档做嵌入，用相似度搜索来召回。前者简单直接，适合中小项目；后者更灵活，但需要额外的嵌入模型和向量库。

我在实际使用中更倾向于第一种，原因是可解释性强。当 AI 生成结果不符合预期时，我可以直接去看它加载了哪些技能文件，快速定位是技能写错了，还是检索没匹配上。向量检索虽然召回率高，但排查问题时要多绕一层，对于追求稳定性的工程场景，简单方案往往更可靠。

2.3 任务编排让多个技能按顺序协同

单个技能能解决的问题有限，真正体现 superpowers 价值的是任务编排。比如“新增一个完整的业务模块”这个任务，可以拆解为：读取数据库 Schema → 生成 TypeScript 类型定义 → 生成 API 请求函数 → 生成表单组件 → 生成列表页面 → 生成单元测试。每个步骤对应一个技能，编排层负责按顺序调用，并把上一步的输出作为下一步的输入。

这里有个容易忽略的细节：步骤之间的数据传递格式。如果上一步输出的是自然语言描述，下一步很难稳定解析。所以我在定义技能时，会强制要求输出结构化数据，比如 JSON 或特定格式的代码块。编排层只负责传递这些结构化片段，而不是让模型去“理解”上一段的散文。这样做的好处是，整个流程的确定性大幅提升，即使中间某一步需要人工确认，也能快速定位到具体环节。

3. 安装与配置：从零搭一套可用的 superpowers 环境

3.1 选择适合你的实现方案

前面提到，superpowers 不是单一产品，所以“安装”这个词需要拆开看。目前主流的落地方式有三种，我列个表对比一下，你可以根据自己的技术栈和团队情况选。

我个人的建议是：如果你只是想让 AI 助手在写代码时更懂你的项目，先从编辑器插件型入手，把技能文件放在项目根目录的.ai/文件夹里，大多数插件都能识别。等用顺了，再考虑迁移到 CLI 或自建服务。不要一上来就追求“大而全”，那样很容易在配置阶段就耗尽耐心。

3.2 目录结构与配置文件的最小可用示例

不管选哪种方案，目录结构的约定是通用的。下面是我在多个项目中沉淀下来的最小结构，你可以直接复制：

project-root/ ├── .ai/ │ ├── skills/ │ │ ├── base-format.md │ │ ├── api-generator.md │ │ └── component-generator.md │ ├── context/ │ │ ├── project-overview.md │ │ └── coding-standards.md │ └── config.json ├── src/ └── package.json

config.json里主要配置几个东西：技能目录路径、上下文文件路径、每次注入的最大技能数量、以及是否开启自动检索。一个典型的配置长这样：

{ "skillsDir": ".ai/skills", "contextFiles": [".ai/context/project-overview.md", ".ai/context/coding-standards.md"], "maxSkillsPerRequest": 3, "autoRetrieve": true, "retrievalMode": "keyword" }

这里maxSkillsPerRequest设成 3 是我踩过坑之后的经验值。设得太少，复杂任务覆盖不全；设得太多，模型注意力被分散，反而容易忽略关键约束。3 到 5 之间是比较舒服的区间，具体看你的技能颗粒度。

3.3 验证环境是否生效的简单方法

配置完之后，怎么知道 superpowers 真的在工作？我的做法是做一个对照测试。先问 AI 一个项目相关的问题，比如“帮我写一个用户登录的 API 请求函数”，观察它是否引用了项目里的request.ts封装、是否遵循了命名规范。然后临时把.ai/skills/目录改名，再问同样的问题。如果两次输出有明显差异，说明技能注入生效了；如果几乎一样，那就要检查配置路径或检索逻辑。

这个测试看起来简单，但能帮你排除大部分“以为配好了其实没生效”的情况。我见过不少团队，配置文件写了一大堆，结果路径拼写错误，AI 一直在“裸奔”，白白浪费了前面的设计工作。

4. 编写高质量技能包：从“能跑”到“好用”的进阶技巧

4.1 触发条件要具体，避免“万能技能”

新手写技能包，最容易犯的错误是范围太宽。比如写一个“生成代码”的技能，触发条件写成“当用户需要写代码时”。这种技能几乎等于没写，因为 AI 每次生成代码都会触发它，但它又没有提供任何具体约束，最后输出的还是模型自己的默认风格。

正确的做法是收窄触发条件。比如“当用户提到新增 React 函数组件，且组件名以 Page 结尾时触发”，然后在这个技能里明确规定：必须使用项目里的usePageQuery钩子、必须导出默认组件、必须包含 loading 和 error 状态处理。条件越具体，技能的可复用性和稳定性就越高。

我通常会用一个简单的判断标准：如果一个技能包超过 200 行，就考虑拆分成多个。因为太长的技能文件，模型在检索时很难完整加载，而且维护起来也痛苦。拆分的维度可以按业务模块、按代码类型、按操作阶段，怎么清晰怎么来。

4.2 输出格式约束是稳定性的关键

前面提到过结构化输出的重要性，这里展开说一下具体怎么写。假设你要生成一个 API 请求函数，可以在技能包里这样约束输出：

## 输出格式 请严格按照以下结构输出，不要添加额外解释： ```typescript // 文件路径: src/api/[模块名].ts import { request } from '@/utils/request'; export interface [接口名]Params { // 参数字段 } export interface [接口名]Result { // 返回字段 } export function [接口名](params: [接口名]Params) { return request.post<[接口名]Result>('/api/[路径]', params); }

字段命名规则：

• 参数字段使用 camelCase
• 接口名使用 PascalCase，以 Params / Result 结尾
• 路径使用 kebab-case

这种约束看起来繁琐，但实际用起来非常省心。因为 AI 不需要“猜”你想要什么格式，它只需要填空。而且当输出不符合预期时，你可以直接对照技能文件，看是哪条规则没写清楚，迭代起来有据可依。 ### 4.3 失败回退策略：让 AI 知道“搞不定时怎么办” 这是最容易被忽略、但实际价值极高的一部分。AI 不是万能的，当它遇到技能包里没有覆盖的情况时，如果没有明确的回退指令，它可能会强行编造一个看似合理但实际错误的方案。我在技能包里会加一段“异常处理”： > 如果当前任务涉及技能包未定义的业务字段，不要自行猜测字段含义，而是输出“需要人工确认：字段 X 的含义”并停止生成。如果项目中没有找到指定的工具函数，输出“未找到依赖：工具函数 Y”并列出可能的替代方案。 这段约束加上之后，AI 的“幻觉”明显减少。因为它知道，遇到不确定的情况，停下来问比瞎猜更安全。对于团队协作来说，这种“知道边界”的能力比“什么都能写”更重要。 ## 5. 实战踩坑记录：那些文档里不会写的教训 ### 5.1 技能文件之间的冲突与优先级问题 当技能包数量超过十个之后，冲突几乎不可避免。我遇到过一个典型场景：一个技能规定“所有日期字段使用 ISO 8601 格式”，另一个技能规定“日期字段使用时间戳”。两个技能同时被检索到，AI 就懵了，生成的代码里两种格式混着用。 解决这个问题的办法是**引入优先级机制**。在技能文件的元数据里加一个 `priority` 字段，数值越大优先级越高。当多个技能对同一件事有不同规定时，高优先级的覆盖低优先级的。同时，在项目上下文文件里明确写出“全局规范”，作为所有技能的兜底约束。这样三层结构——全局规范 > 高优先级技能 > 低优先级技能——就能把冲突降到可接受的范围。 另外，我建议**定期做技能审计**。每隔两周，把 `.ai/skills/` 目录过一遍，看看有没有功能重叠的、有没有已经过时的、有没有从来没被触发过的。技能库和代码库一样，不维护就会腐烂。 ### 5.2 上下文窗口被“噪音”占满的排查过程 有一段时间，我发现 AI 生成代码的质量突然下降，经常忽略一些明明写在技能包里的约束。排查了半天，最后发现是**上下文文件里塞了太多无关内容**。当时项目概述文件被不断追加，从最初的 50 行膨胀到了 800 多行，里面混杂了历史决策记录、会议纪要、甚至一些废弃的方案讨论。这些内容在检索时被大量加载，把真正重要的技能约束挤到了后面，模型自然就“记不住”了。 修复方法很简单：把项目概述文件拆成“核心规范”和“历史归档”两部分，只有核心规范会被注入上下文，历史归档放在另一个目录，需要时手动查询。同时给上下文文件加一个**行数上限**，超过就强制拆分。这个教训让我意识到，superpowers 的效果不仅取决于技能写得好不好，还取决于**信息密度的管理**。少即是多，在上下文注入这件事上尤其成立。 ### 5.3 团队协作中的技能版本管理 个人使用 superpowers 时，技能文件随便改改问题不大。但一旦团队多人共用，版本管理就成了刚需。我们团队的做法是：把 `.ai/` 目录纳入 Git 管理，技能文件的修改走正常的代码评审流程。每次合并请求里，如果改了技能文件，必须说明改了什么、为什么改、影响哪些任务类型。 这样做的好处是，技能库的演进有迹可循。当某个 AI 生成结果出问题时，可以快速回溯到是哪次技能修改引入的。另外，我们还会在技能文件头部加一个简单的变更记录： ```markdown ## 变更记录 - 2024-06-01: 新增字段命名约束，修复与 api-generator 的冲突 - 2024-05-15: 初始版本

别小看这几行字，在排查问题时能省下大量沟通成本。

6. 把 superpowers 用出效果的几个关键认知

6.1 它不是“让 AI 更聪明”，而是“让 AI 更懂你”

很多人对 superpowers 的期待是“装上之后 AI 就能写出完美代码”，这个预期本身就偏了。大语言模型的基础能力是固定的，superpowers 做的是信息对齐——把你脑子里的隐性知识、项目里的显性规范，用模型能理解的方式表达出来。它不会让模型突然学会新的编程语言，但能让模型在你熟悉的领域里少犯低级错误。

理解这一点很重要，因为它决定了你的投入方向。与其花时间研究怎么“调教”模型，不如花时间梳理项目的编码规范、整理常用工具函数、把重复性的决策写成技能包。这些工作即使没有 AI，对团队也是有价值的资产。

6.2 从“高频小任务”开始，不要一上来就搞大流程

我见过一些团队，兴致勃勃地设计了一套覆盖需求分析、架构设计、编码、测试、部署的全流程 superpowers 方案，结果用了两周就放弃了。原因很简单：流程越长，不确定性越大，维护成本越高。一个环节出问题，整条链路就断了，而排查成本远超收益。

更务实的做法是，先挑一个高频、边界清晰、输出格式固定的小任务，比如“生成 API 请求函数”或“生成表单校验规则”，把它做到 90% 以上的准确率。等这个技能稳定运行一段时间，团队建立了信心，再逐步扩展到相邻环节。这种“小步快跑”的策略，在 AI 工作流建设上同样适用。

6.3 人工确认环节不能省

无论技能包写得多完善，我始终坚持在关键节点保留人工确认。比如生成数据库迁移脚本、修改公共工具函数、涉及权限判断的逻辑，这些场景下 AI 的输出只作为草稿，必须由人 review 后才能合并。这不是对 AI 不信任，而是对工程负责。

superpowers 的价值在于把人的精力从重复劳动中解放出来，集中到真正需要判断力的地方。如果因为用了 AI 就跳过 review，那是本末倒置。我在团队里推行的原则是：AI 可以生成，但合并请求的 reviewer 必须是人，而且 reviewer 要能说清楚这段代码为什么是对的。

7. 关于“想要安装 superpowers”的一些直接建议

如果你看完前面这些，还是不知道从哪下手，我给你一个最小启动清单，照着做就行。

第一步，在你的项目根目录建一个.ai/skills/文件夹，先放一个技能文件，内容就写你最常让 AI 做的那件事的规范。比如你经常让 AI 写 React 组件，那就写清楚：组件文件放哪、用什么导出方式、状态管理用哪个库、样式方案是什么。不用追求全面，先把最痛的那个点覆盖住。

第二步，在你的 AI 助手对话里，手动把技能文件内容粘贴进去，测试几次，看看输出是否符合预期。如果不符合，就改技能文件，直到满意为止。这一步是纯手工验证，不要急着上自动化。

第三步，等你确认技能文件有效之后，再去配置自动检索和注入。这时候你已经有了一个可用的“种子技能”，后面的扩展都是在这个基础上生长出来的。

第四步，坚持记录。每次 AI 生成结果不符合预期，不要只改代码，要回头想想是技能文件缺了哪条约束。把这条约束补进去，技能库就进化了一次。这个过程重复几十次之后，你会发现 AI 助手真的变得“懂你”了。

最后分享一个我自己的习惯：我会在.ai/context/project-overview.md的开头写一句话——“本项目所有 AI 生成内容，默认遵循以下规范，除非技能文件另有说明。”这句话像一个总开关，提醒模型先看全局约束，再看具体技能。别小看这一句话，它能让整个技能体系的稳定性提升一个档次。