企业官网建设流程全解析

说实话，第一次在终端里看到“superpowers”这个项目名的时候，我以为是哪个中二少年写的玩具脚本。直到我把它接进每天在用的 Codex CLI 工作流，跑完一个真正的 Java 服务重构任务，我才意识到这工具解决的问题有多接地气。

如果你也在用 Codex 这类跑在命令行里的 AI 编程智能体，大概会有同感：它能写代码、能读文件，但真要执行一个跨文件、多步骤的工程化任务，经常会出现“规划很好、落地拉垮”的情况——步子迈太大、中途忘步骤、操作目录越界。superpowers 这个开源技能包做的事，就是把这些复杂执行过程变成一套可复用的“技能”，让智能体在正确的时候调用正确的流程，而不是靠模型当场发挥。

这个项目适合谁？简单说：重度使用 Codex、Claude Code 等终端 AI 编程工具的开发者，尤其是要处理真实工程任务的团队。装上它，相当于给你手下的 AI agent 发了一本带 SOP 的作战手册。下面我从思路拆解、模块解析、安装配置到实战排查，完整聊一遍。

1. 先搞清楚 superpowers 到底是什么东西

1.1 它不是另一个 Copilot，而是一套技能仓库

我见过不少人第一次看到这个项目的时候，下意识以为它是个代码补全插件或者新的 AI 模型。真不是。superpowers 不是 IDE 插件，也不是模型，而是一套用于扩展 AI 智能体的技能框架和技能仓库。它定义了一套约定：每个“技能”都对应一个 Markdown 文件或目录，里面写清楚触发条件、执行步骤、检查清单和验收标准。把这一整套技能放进 agent 可访问的路径之后，agent 会在合适的时机读取并执行对应技能。

用一个生活化的类比：大模型本身像一个聪明但经验不足的新员工，你让他去处理一个不熟悉的业务流程，他可以靠推理硬做，但容易出错、容易遗漏。superpowers 做的事情，就是把这个老员工处理同类任务时沉淀下来的标准作业手册交给他。它不负责思考，但负责提供“成熟的操作流程”，避免模型每次都从零开始推理。

我之所以说这个概念重要，是因为它决定了我们后面怎么配置、怎么维护。如果你把 superpowers 当成一个插件来用，你会觉得很别扭；但如果你把它当成“技能文档库+加载约定”，整个逻辑就通了。Codex CLI 本身已经具备读写文件、执行命令、查看测试结果的能力，缺的正是这种结构化的执行策略。

1.2 为什么社区里总是把它和 Codex 放在一起

搜“codex superpowers”这个关键词能找到很多讨论，背后原因其实很直接。Codex CLI 这类工具的设计哲学是“把控制权交给模型”，但它默认的自主规划能力在长链条任务中并不稳定。比如让 Codex 执行一次跨模块的重构，它可能会跳过某些边界条件，或者在一个目录下反复尝试错误的构建命令，浪费大量 token。

superpowers 恰好补上了这块短板。它通过配置让 Codex 启动时加载一份技能清单，agent 在执行任务前可以先快速扫描技能说明，判断当前场景是否匹配某个技能；如果匹配，就直接按技能里写好的步骤来执行，而不是靠模型自由发挥。用社区里一句调侃的话说：superpowers 让 Codex 从“会写代码的聊天机器人”变成了“会按流程干活的实习生”。

当然，它不是唯一的选择。Claude Code 侧的 skills 生态也在做类似的事，还有各种 MCP 工具也能实现部分能力。但 superpowers 的特点是轻量和约定统一，整个技能包就是一个目录结构，没有复杂的依赖，也不绑定特定厂商，这也是我选择它的原因。

1.3 谁适合用它，谁不适合

先泼一盆冷水：如果你只是偶尔让 AI 帮你写个脚本、改个正则，你大概率不需要 superpowers。它带来的收益要在“高频、复杂、可重复”的工程任务上才会明显放大。

适合的场景包括：

• 你每天要接手的代码库五花八门，需要快速分析项目结构、定位核心模块。
• 你经常让 agent 执行构建、跑测试、修编译错误这类流程化任务。
• 你们团队里有统一的工程规范，希望 AI agent 也能遵守同样的流程。
• 你想让 AI 做跨文件重构，但每次它都会搞出一些“管杀不管埋”的问题。
• 你在 Java、Python 这类有明确构建体系的语言上投入很大，需要稳定可复现的自动化辅助。

反过来，如果你的任务都很短、很零散，或者你根本不用命令行 AI 工具，那先别急着装。工具是给流程增效的，没有流程的时候，再强的技能也是空转。这也是我后面要反复强调的：先把工程习惯理顺，再用工具把它固化下来。

2. 核心模块拆解：这些“超能力”到底覆盖了什么

2.1 项目基础侦查能力

superpowers 里最常用的一类技能，是“项目分析类”。这类技能解决的核心痛点是：agent 接手一个陌生仓库时，不知道怎么快速建立全局认知。你让一个没有技能的 Codex 去分析项目，它往往会先列目录树，然后开始猜；有了技能约束，它会按固定流程走。

以analyze-project这类技能为例，它通常包括以下步骤：

1. 读取根目录下的构建文件（pom.xml、build.gradle、package.json、pyproject.toml）。
2. 读取 README、docs 目录，提取项目定位和启动方式。
3. 扫描 git log 最近提交，了解开发活跃度和近期改动方向。
4. 生成一份模块清单，标注每个目录的职责和依赖关系。
5. 输出一份简短的“项目地图”，交给用户确认后再进入后续任务。

这个能力特别适合接手遗留系统。之前我接手一个老旧的 Java 多模块项目，十几个子模块互相依赖，第一次摸代码时头都是大的。让 agent 跑一遍项目分析技能，五分钟之内就产出了模块依赖图、核心入口、常见构建命令，效率比我自己翻一遍高得多。

这类技能的设计要点在于：不要试图一次塞给模型太多信息。技能模板里通常建议输出结构化摘要而不是大段原文，避免上下文被无关内容占满。这也是 superpowers 相比“直接写一段 prompt 让 AI 分析项目”更优的原因——它把输出格式也固化了。

2.2 工程执行与验证能力

比“分析”更硬核的是“执行”。工程类任务最终要落到真实动作上：编译、测试、运行、调试。superpowers 里这部分技能设计得最有讲究，也是社区热词里“superpowers java”被频繁提起的原因。

以run_build_and_tests这类技能为例，它不会简单地让 agent 执行一个mvn test了事，而是给它一套完整的闭环：

1. 根据项目类型识别构建工具，Java 项目优先看 pom.xml 或 build.gradle。
2. 检查本机环境，确认 JDK 版本、构建工具是否可用。
3. 执行编译命令，例如mvn -q -DskipTests compile，减少噪音输出。
4. 如果编译失败，解析错误日志，定位到具体文件和行号。
5. 运行与本次改动相关的测试，而不是全量测试（全量太慢且容易超时）。
6. 汇总测试结果、失败用例、失败原因，输出给用户。

这套流程看似简单，但每一环都踩过坑。比如编译输出默认是 GBK 编码，在 UTF-8 终端里显示乱码，如果技能模板里没有预先设置-Dfile.encoding=UTF-8，agent 解析日志就会出错。再比如测试策略：新手 agent 拿到任务后容易直接跑全量测试，一个大型 Java 项目的全量测试可能要跑二十分钟，token 开销巨大；技能里就该约束它优先跑与改动相关的测试类。

我实际跑过一次 Java 功能增强任务：agent 先识别出这是一个 Maven 多模块项目，然后自动找到我要改的那个模块，修改代码后只运行了该模块的单元测试，整个过程大概两分钟。如果是没有技能的裸 Codex，它很可能先试错几次命令，再跑一个不知道什么时候结束的全量构建。

2.3 面向 Java 等场景的专项设计

热词里有“superpowers java”，说明 Java 是很多人实际使用的场景。Java 项目为什么尤其需要这种技能包？因为它的工程链路比脚本语言长太多：多模块依赖、编译类型检查、Spring 容器加载、测试隔离，任何一个环节出错，agent 都可能陷入长时间的错误尝试。

一套好的 Java 专项技能，通常包含这些约定：

• 技术栈自动识别：检测pom.xml、build.gradle，提取 Java 版本、Spring Boot 版本、依赖管理方式。
• 构建命令白名单：只允许执行mvn或gradle的特定子命令，避免 agent 乱试。
• 测试策略：识别src/test/java结构，定位与改动相关的测试类，按需执行。
• 错误诊断模板：遇到编译错误时，先看是语法错误、依赖缺失还是版本冲突，再决定下一步，而不是反复重新构建。

举个实际例子：我在一个 Spring Boot 项目里让 agent 添加一个 REST 接口。技能先识别出项目是 Maven 多模块结构，确认 Controller 层所在模块，然后检查依赖是否已包含 Web 相关 starter。之后它才动手写代码，写完直接编译验证。这中间每一步的顺序和执行边界都有技能约束，agent 不会跑去改无关的 pom 文件。

Java 专项技能还有一个重要考量：类路径问题。运行java -cp或mvn exec:java时，classpath 很复杂，技能模板里最好直接给出推荐的运行方式，比如用spring-boot:run或让用户自行启动，避免 agent 在命令行里手拼 classpath 拼到怀疑人生。

2.4 技能触发规则与上下文控制

最后一个关键模块是技能触发机制。superpowers 里的每个技能都包含一段元信息，用来告诉 agent“什么时候应该使用我”。这直接决定了技能被调用的准确率。

一份典型的技能元信息如下所示：

--- name: analyze-project description: 分析项目结构并生成模块依赖清单，适合接手新代码库时使用 when_to_use: 用户要求理解项目、梳理模块、了解代码架构 ---

为什么要刻意写一个when_to_use？因为 agent 的上下文窗口是有限的。如果每个任务都把全部技能塞进去，光是技能描述就把上下文撑爆了，更别说干正事。正确的做法是让 agent 先扫描技能列表的简短描述，再根据场景决定是否读取某个技能全文。这个“两级读取”策略是把技能包做大的基础。

如果你发现自己装了十几个技能后 agent 反而变傻了，大概率是触发描述写得太宽泛。我见过有人把when_to_use写成“任何编程任务”，结果 agent 每个任务都想调用这个技能，反而偏离了用户真实意图。正确写法是具体场景化，比如“仅当用户提到Maven构建失败时使用”。

3. 安装与配置：让 superpowers 真正跑起来

3.1 环境准备

在动手安装之前，先确认你具备这些基础条件：

• 一个可以用的 Codex CLI 或其他兼容 agent 工具。superpowers 依赖 agent 本身具备读写文件、执行命令的能力，如果 agent 只是纯聊天接口，那技能体系跑不起来。
• 本机能够正常访问 GitHub 等代码仓库，用于拉取技能包。
• 有基本的 Git 使用能力，至少会 clone、checkout 这些命令。
• 如果你要在 Java 项目里跑技能，本机需要装好 JDK 和 Maven/Gradle，并配置好环境变量。

这些条件听起来很简单，但我在实际配置时遇到过一个情况：公司内网机器访问不了外网仓库，技能包拉不下来，后来是通过内网镜像解决的。所以如果你在公司环境，提前确认网络访问策略能省不少事。

3.2 安装步骤与目录结构

安装的第一步是把技能包仓库克隆到本地，然后把它复制到约定目录。以我的环境为例，我的技能目录放在~/.config/superpowers/skills下面，你也可以放在项目内部，比如.superpowers/skills，看习惯。

git clone <你的技能仓库地址> ~/superpowers mkdir -p ~/.config/superpowers/skills cp -r ~/superpowers/skills/* ~/.config/superpowers/skills/

技能目录的内部推荐结构如下：

superpowers/ skills/ analyze-project/ SKILL.md templates/report.md run-java-build/ SKILL.md scripts/parse-errors.py refactor-in-babysteps/ SKILL.md

每个技能目录里至少有一个SKILL.md，它既包含元信息，又包含完整的操作步骤。如果有辅助脚本，可以放在技能目录下的scripts/或templates/子目录里。这样每个技能自带依赖，不需要搞全局一堆工具脚本，技能够独立、也够健壮。

需要提醒的是：不要直接改仓库里的原始技能然后覆盖，这样将来拉取更新时会冲突。正确做法是先 fork 一份到自己的仓库，或者复制到独立配置目录后再改。我自己把技能目录纳入了 dotfiles 仓库管理，所有团队共享的配置都能同步走 Git，多人协作时统一版本方便很多。

3.3 关键配置文件与参数说明

在 Codex CLI 的配置里，需要让 agent 知道技能目录在哪里，并设置合理的权限策略。下面是我常用的一个配置模板：

skills_dir = "~/.config/superpowers/skills" approval_policy = "on-request" [command_permissions] allow = [ "bash:mvn:*", "bash:gradle:*", "bash:git diff:*", "bash:git log:*", "bash:ls:*", "bash:cat:*", ] deny = [ "bash:rm -rf *", "bash:git push:*", ]

这里有几个参数值得细说：

• skills_dir：技能目录路径，agent 启动时会扫描这个目录下的所有技能。
• approval_policy：设置审批策略，我建议先保持on-request，即每条命令执行前询问用户。等你对技能足够信任，再考虑放宽为on-failure或按命令前缀自动批准。
• command_permissions.allow：允许 agent 执行的命令前缀白名单。Java 项目里给出mvn:*和gradle:*可以避免它去试一些奇怪的命令。

有一个我强烈不建议的设置：把auto_approve一次性全部打开，尤其是bash:rm:*这种危险操作一定要放在 deny 列表里。快手一时爽，误删火葬场。AI agent 偶尔会做出完全出乎意料的操作，保留人工审批环节是必要的安全底线。

3.4 初始化验证

装完之后，先做一个快速验证：让 agent 调用一个最基础的分析技能，看看是否正常加载。

可以这样问：请使用 analyze-project 技能分析当前目录，生成一份简要的项目描述。

正常的响应应该是 agent 先读取技能文件，然后按照步骤逐条执行。如果 agent 回答“未找到该技能”，大概率是技能目录路径没配置对，或者技能包文件权限有问题。检查ls -l确保文件可读，再确认配置里的skills_dir与真实路径一致。

我习惯把初始化验证也做成一个小技能，叫healthcheck，专门检查 environment 是否完整、技能是否加载成功、目录权限是否正常。这样换一台新电脑部署时，既能验证配置，又能留下诊断信息，省得每次重新排查环境问题。

4. 实操流程：带上“超能力”干一个真实活儿

4.1 场景设定：给一个 Java 服务增加 REST 接口

我以一个实际例子演示完整的实操流程。假设当前项目是一个 Spring Boot 的订单服务，我要让 agent 给它新增一个查询订单详情的 REST 接口。

第一轮对话，我会给出明确任务：

请为订单模块新增一个 GET /orders/{id} 接口，返回订单详情。先分析项目结构，再制定改动方案，最后实施并验证。

这个任务对裸 Codex 来说不算很难，但容易出现两个问题：一是直接跳到写代码，没有先确认项目现有的分层规范；二是改完后不编译不测试，直接交差。有了 superpowers，agent 会按技能流程走。

4.2 执行过程与人工决策点

实际执行时，agent 先调用了analyze-project技能，读取了根目录的pom.xml，确认这是一个 Maven 项目，Spring Boot 版本是 2.7.x。然后它读取了src/main/java/com/example/order目录结构，找到现有的 Controller、Service、Mapper 分层。

到了这一步，agent 输出一个简短的计划，等待我确认。这是很重要的一个人工决策点——在开始改代码之前，让 agent 把计划说出来，我来确认是否符合项目现状。

计划确认后，agent 进入implement-change技能。它没有像新手那样直接创建一个大类，而是按项目现有风格写了一个 OrderController，并在 OrderService 里增加对应方法，同时在 Mapper 里补 SQL。全部代码改完后，它按run-java-build技能执行了mvn -q -DskipTests compile，确认编译通过，再针对订单模块跑了一次单元测试。

关键输出片段如下：

$ mvn -q -DskipTests compile BUILD SUCCESS $ mvn test -Dtest=OrderServiceTest -pl order-service Tests run: 12, Failures: 0, Errors: 0, Skipped: 0

这个结果看起来很直接，但背后是技能对命令和测试范围的控制。如果没有技能约束，agent 很可能直接跑mvn test，整个项目几十个模块的测试全部执行，又慢又消耗 token；现在它只跑了相关模块的 12 个测试，整个流程在一分钟内完成。

4.3 技能验收：让 agent 输出变更报告

我坚持要求：每次技能执行完，agent 必须输出一份简短的变更报告，包含以下内容：

• 改动涉及的文件列表。
• 每个文件的核心改动说明。
• 编译与测试结果。
• 潜在风险和后续建议。

这不是强加给 agent 的额外负担，而是把“验收”固化为技能的一部分。如果不做这一步，agent 很容易把改动糊弄过去，你也不好判断哪里有风险。模板可以直接写在技能文件的末尾，让 agent 按格式填充。

变更报告示例：

### 变更报告 - 改动文件： - src/main/java/com/example/order/controller/OrderController.java - src/main/java/com/example/order/service/OrderService.java - src/main/java/com/example/order/mapper/OrderMapper.java - 核心改动：新增 GET /orders/{id} 接口，Service 层补查询逻辑，Mapper 新增订单详情查询。 - 测试结果：编译通过，OrderServiceTest 12 项全部通过。 - 风险点：接口未做参数校验，建议后续补充。

有了这份报告，我能快速判断 agent 的工作质量，同时把风险点纳入后续任务里。这个过程也让我逐渐建立对 agent 的信任，愿意把更多任务交给它去做。

4.4 实战中的参数调优经验

多跑几次之后，我开始调整配置里的参数，让流程更顺手。一个重要的调整是：把常用技能分目录排序。agent 扫描技能时，我对analyze-project、run-java-build这类高频技能的描述写得非常精炼，确保它优先命中；对低频的、风险高的技能，描述中特意加了更多限定词，防止误触发。

另一个经验是：技能里的步骤不要写太多“也许”“可能”这类模糊词。技能是 SOP，不是建议书。你越明确，agent 执行的偏差就越小。比如技能里直接写“先检查 pom.xml 中 spring-boot-maven-plugin 是否存在，不存在则跳过”，远比“检查构建配置是否完整”可控。

另外，我在技能里加了“超时保护”的习惯：对于长跑命令，比如全量测试，要求 agent 设置 timeout 参数，避免命令卡死占用整个会话。这类细节在文档里很难找到，但实际用起来非常关键。

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

5.1 agent 总是不调用技能怎么办

这个问题最常出现。装上 superpowers 之后，agent 仍然按自己的思路硬来，不读取技能。我排查之后发现，大部分情况是技能描述不够精准，或者 agent 的模型版本对技能元信息的理解偏弱。

解决办法分两步：

第一步，精简when_to_use描述，把它写得更具体、更贴近真实任务表达。比如不要写“用户要求理解项目”，而是写“用户说'分析这个项目'、'项目结构是什么'、'小程序怎么上手'”。描述越贴近用户真实说法，命中率越高。

第二步，如果描述已经很具体还是不听，检查一下 agent 是否真的加载了技能。你可以在对话中主动问它：你先看看有没有合适的技能可用。如果 agent 能正确列出，说明加载正常；如果它说没有技能，那还是配置路径的问题。

我自己的习惯是把最常用的几个技能描述放在技能列表最前面，因为 agent 扫描时依赖简介做预筛选，前面的内容更容易进入上下文。虽然这个顺序不是强制的，但实测下来确实有效。

5.2 命令执行权限导致构建失败

假设备好了 Maven 白名单，agent 执行mvn -q -DskipTests compile却被拦下来了，提示命令不在允许列表中。这种情况通常是因为命令前缀匹配不够宽松。

Codex 的权限匹配是按前缀来的。bash:mvn:*一般能匹配任意以mvn开头的命令，但如果命令实际写成cd /path && mvn compile，那前缀就不是mvn，匹配失败。

解决办法是调整白名单，把cd之类的复合命令提前拆开。在技能模板里写明“先使用 cd 命令进入目标目录，再单独执行 mvn 命令”，而不是让 agent 写一条超长复合命令。这样权限匹配清晰，日志也更容易追踪。

5.3 Java 环境下 agent 乱改构建文件

Java 项目里最头疼的一个问题：agent 为了通过编译，擅自修改pom.xml，比如升级依赖版本、加插件。这在裸 Codex 场景下经常出现，因为模型面对编译错误会尝试“解决”它，而不是“报告”它。

我的对策是在run-java-build技能里明确加一条规则：遇到编译错误时，禁止修改 pom.xml，除非用户明确允许；正确做法是输出错误详情和可能的依赖冲突分析，交给用户决策。

这个规则本质上是把“操作边界”写进 SOP。agent 也是会被规则约束的，只要技能里写清楚，它就会遵守。如果你发现它还是乱改，说明技能里的规则描述不够强硬，建议加上“这是必须遵守的约束，违反将导致任务失败”这类明确措辞。

5.4 上下文被技能描述占满

装了太多技能之后，agent 每次都会扫描全部技能描述，几十个技能加起来可能占用数千 token，对上下文窄的模型影响明显。

解决办法是淘汰低频技能，把不常用的归入单独的skills-extra/目录，不参与默认加载；只把高频、核心的技能放在主目录。我平时主目录只保留 6 到 8 个技能，其他的按需移动到临时目录再加载。这是一个很实用的取舍策略——技能包的价值在于精，而不是多。

另一个技巧是让技能描述保持简短，把详细步骤放在SKILL.md正文里，agent 只会在确认需要时读取正文，这样就不会一开始就占满上下文。两级读取的设计一定要用起来。

5.5 多人协作时技能版本分裂

当团队里每个人都自己 clone 一份技能包，很容易出现版本分裂：你调试好的技能，在同事机器上表现不一样，因为他的技能包还是旧版。

我的做法是把技能包纳入 Git 仓库管理，并在项目里固定引用。

git submodule add <技能仓库地址> .superpowers

这样团队所有人拉取主仓库时，自动拉取同一个版本的技能包，避免口径不一致。同时约定：技能包的更新走 Pull Request 流程，改技能和改代码一样需要评审。用这个方式跑了一段时间后，大家对技能的统一性越来越有信心，很多原来靠口头传递的工程经验，都沉淀成了一份份可评审的技能文档。

写在最后

实际用下来，我给 superpowers 的定位是：它本身不是什么神秘技术，而是一套帮助你把工程经验“显式化”的框架。最有价值的收获不是某个具体技能有多好用，而是它逼着我把团队里那些“老师傅口头经验”变成了可复制、可评审、可迭代的文档。

最后分享一个小技巧：新技能不要一上来就写全，先从一个最小场景开始，只覆盖三到五个步骤，跑通之后再逐步补充边界情况和异常处理。我之前图省事，一次写了一个二十多步骤的“全能重构技能”，结果 agent 执行到一半经常迷路；后来精简到八个步骤反而稳得多。技能是用来约束 agent 的，也是用来约束我们自己思路的，写得越克制，效果越可靠。