企业官网建设流程全解析

最近朋友问我：“你老说 superpowers，那到底是个什么东西？”我想了想，这个词确实容易让人误解。它不是某个科幻模组，也不是什么神秘框架，而是我这段时间一直在打磨的一套“个人开发提效工具链”。核心思路很简单：把重复的编码动作——补测试、写样板、解释老代码、做重构方案——全部封装成一个个可以直接调用的命令，底层接上 codex 这类代码生成引擎，让它替你干活，你做决策和 review。说白了，就是给自己装一层超能力。

这篇东西不是产品文档，也不做任何工具推荐。我把从零开始搭建这套环境的完整思路、踩过的坑、还有在 Java 业务项目里实际落地的过程整理出来，希望对那些已经被重复劳动拖累、又不想盲目复制粘贴 AI 代码的人有一点参考价值。

1. superpowers 到底解决什么问题

1.1 从“会写代码”到“会调度工具”

先说一个真实的场景。去年有段时间，我每天一半以上的时间在做同一类事情：给一个老模块补单元测试、给新接口写模板代码、把一段 200 行的 if-else 改成策略模式。这些工作难度不高，但是量大，而且极其消耗耐心。用传统的 IDE 自动补全和代码模板，只能解决“写代码”这一步，解决不了“知道要写什么”这一步。

superpowers 的思路不太一样。它不试图替你做架构决策，而是把“你脑子里已经在想、但还没动手写”的那些意图，快速变成可执行的代码变更。我理解它的本质是：定下一套规则，把你最常用的开发动作，变成一组稳定的、可复用的“超能力指令”。这就像你不是去学一门新手艺，而是把工具箱重新整理了一遍，让你伸手就能拿到最趁手的工具。

这也是为什么我会强调“工具链”而不是“工具”。单看 codex CLI 也好，某个脚本也好，都只是一个零件。只有当它们被组合起来，并且被一套你自己的规则串起来的时候，才配得上叫 superpowers。

在实际工作中，我看到很多人其实已经有类似的雏形了——比如把一段 prompt 存在备忘录里，用时复制粘贴。差别在于，这样太零散，一次两次还好，次数多了很快就乱了。superpowers 更愿意把这件事做成工程：指令有固定的目录、有版本管理、有明确的输入输出约定，你可以像维护代码一样维护你的“超能力”。

1.2 一套典型的分层能力模型

如果非要给 superpowers 画一个地图，我一般会分成四层。这个分层不是为了好看，而是为了排查问题的时候，知道锅是谁的。

第一层是基础设施。终端、Git、运行时环境，这一层出问题，上面全白搭。第二层是智能内核，也就是 codex 这类代码生成引擎的 CLI 或 API，它负责把自然语言和代码上下文，变成补丁或文件。第三层是指令封装，这是 superpowers 的灵魂：你写好的一堆 prompt 模板、shell 函数、别名、项目约定。第四层是流程集成，把指令接进 IDE、CI、代码评审流程里，让它真正成为团队协作的一部分。

为什么要这么分？因为我发现大多数翻车现场，都出在“你以为的 superpowers 问题”其实是“上一层的配置问题”。比如命令能跑，但生成结果总不对，多半是第三层的指令模板写得不够明确，而不是引擎本身的问题。再比如团队里有人用不了，先查第一层环境，再查 API 凭证，别一上来就骂工具不行。

对个人来说，这个模型的意义在于：你可以从任意一层开始搭建，不必一次性全搞定。我自己就是从第三层开始做的，因为当时觉得写 prompt 最不费钱，结果做着做着才回头补了第一层和第四层的基建。

2. 搭建 superpowers 环境的完整步骤

2.1 前置准备：终端、运行时与 API 凭证

在开始之前，先确认你的工作环境。我在 macOS 和 Linux 上都试过，整体很顺。Windows 上我更推荐先装 WSL2，然后把所有东西都放在 Linux 子系统里跑，这样可以减少很多路径和权限的坑。

运行时方面，codex CLI 是基于 Node.js 的，所以你需要准备一个可用的 Node.js 环境。我一直在用 18 以上的版本，没遇到兼容性问题。你装之前可以先执行node -v看一眼版本，如果太低，用你系统对应的包管理器升一下级，别嫌麻烦，这一步不做好后面命令行工具的报错会让你以为是工具坏了。

接着是 Git。理论上 codex CLI 不强制要求 Git，但因为后面的指令封装大量依赖git diff、git status来了解当前改动，所以建议先初始化好仓库，并把全局 user.name 和 user.email 配好。如果你本身有常用的 Git 配置，直接复用就行。

然后是 API 凭证。这里我必须提醒一句：假如你的项目里同时存在多种 AI 代码工具的配置，请仔细区分它们的读取逻辑。superpowers 相关的 codex CLI，通常通过环境变量或配置文件读取凭证。我个人的习惯是，把凭证写进项目根目录的.env文件里，用环境变量加载，而不是硬编码到代码或 shell 历史里。

注意：任何形式的密钥都不要提交到 Git 仓库。哪怕是私有仓库，也建议在.gitignore里加上.env。密钥泄露的成本远比你想象的高。

2.2 codex CLI 的安装与初步配置

假设你已经有了 Node.js 和 API 凭证，安装这一步其实很简单。用 npm 全局安装 codex CLI 即可：

npm install -g @openai/codex

装完以后，在项目目录里先登录一次，把 API 密钥写好：

codex login

登录成功之后，它会在用户目录下生成一个配置文件。我习惯直接编辑这个文件，把模型、温度、输出长度一次性配好。以下是我常用的一套配置思路：

model = "gpt-4o-mini" temperature = 0.2 max_tokens = 4096 sandbox_mode = "workspace-write"

温度设成 0.2 是我强烈推荐的。以前我图省事直接把温度拉到 1，生成出来的代码倒是话多，但经常给你加一些自以为是的“额外功能”，改起来比从零写还累。代码生成这种场景，低温更稳。max_tokens根据你的任务定，如果是生成一个文件，4096 基本够用；如果要重构整个类，建议直接调到 8192 或者更高。

sandbox_mode是安全模式，workspace-write表示它可以直接在当前工作区里改文件。刚上手的时候，对于不熟悉的操作，最好保留只读模式，跑几轮确认没问题再放开写权限。

2.3 自建快捷指令：让 superpowers 真正顺手

安装了 codex CLI 之后，它就只是一个裸引擎，跟 superpowers 还有一段距离。我理解真正的“超能力”在于你给它设计的快捷入口。下面分享一下我是怎么组织这些指令的。

我在用户目录下建了一个~/.superpowers/文件夹，里面按功能分成templates/和bin/。templates/放的是各种任务的 prompt 模板，bin/放的是 shell 脚本。比如我要做一个“给指定类生成单元测试”的命令，我不会每次重新敲一段 prompt，而是写好一个模板文件gentest.md，再用一个脚本去读取它并调用 codex CLI。

实际使用中，我最开始用的是两层结构，后来扩展成“项目级上下文 + 通用模板”。什么意思？就是在模板里留一个变量，执行脚本时把当前项目的技术栈、包名、编码规范等通过参数传进去。这样同一个模板在 Spring Boot 项目和纯 Java CLI 项目里，都能跑出合理的结果。

下面是一个简化版脚本的写法，仅供参考：

#!/usr/bin/env bash target_file="$1" template_file="$HOME/.superpowers/templates/gentest.md" project_context="$HOME/.superpowers/templates/java-context.md" cat "$template_file" "$project_context" < "$target_file" | codex exec --dangerously-bypass-approvals-and-sandbox

这里我不建议直接复制这段代码就完事，细节需要根据你自己的目录结构和安全偏好调整。它的价值在于演示了“组合”的思路：把模板、上下文和目标文件拼起来，再统一送给 codex 处理。省去了大量手工复制粘贴 prompt 的时间。

2.4 验证安装：跑通一个最小闭环

环境装好之后，先不要急着处理大任务，找一个很小的 Java 类验证最小闭环。我一般会新建一个只有两个方法的简单类，然后执行一次生成测试的任务，看看输出的结果能否直接编译、能否通过。

比如一个最基本的示例类：

package com.example; public class Calculator { public int add(int a, int b) { return a + b; } public int divide(int a, int b) { if (b == 0) { throw new IllegalArgumentException("divisor cannot be zero"); } return a / b; } }

对着这个文件跑一次生成测试的命令，如果系统能生成出 JUnit 5 的测试代码，并且你用mvn test或gradle test能直接跑通，就说明整个链路是通的。这里注意一个细节：生成之后不要闭眼执行，先看一眼生成的断言是否真的有护城河，而不是那种“调用不报错就算通过”的假测试。这一点我在后面还会专门展开。

最小闭环的意义是帮你隔离问题。如果这一步失败，要么是环境配置问题，要么是凭证问题，要么是模板写的问题，基本跟你的业务代码没太大关系。宁可花这一二十分钟，也别直接跑到老项目里一顿操作，因为那种情况下报错你很难定位。

3. 在 Java 业务项目中落地 superpowers

3.1 为什么拿 Java 场景举例

我日常大部分工作是在 Java 项目里，倒不是说 Java 比别的语言高级，而是它有几类痛点特别适合用这套工具链来缓解。第一是样板代码多，比如 DTO、VO 的 getter/setter 虽然现在有 Lombok 了，但不同层的转换逻辑仍然是体力活。第二是测试覆盖率要求，很多质量门槛就卡在这，而写测试恰恰是重复度最高的事情之一。第三是老代码的重构成本，Java 项目跑得越久，遗留代码越多，每次改动都像地下探险。

所以我会把 superpowers 用在三个高频任务上：补单元测试、做局部重构、解释不熟悉的旧模块。下面分开讲，每个我都给实际的操作方法和注意点。

3.2 高频场景：为现有类补全单元测试

假设你接手了一个转账服务的实现，方法签名大概长这样：

public TransferResult transfer(String fromAccountId, String toAccountId, BigDecimal amount) { // 这里有余额校验、风控检查、账户状态判断、流水记录 }

你要补全它的单元测试，最原始的做法是读一遍源码，找出所有分支，再手写用例。这个流程用 superpowers 的话，只需要把类文件传进去，再根据自己的测试规范给一段约束说明。

我自己常用的约束说明包括这些点：测试框架用的是 JUnit 5，不使用 Mockito 的复杂静态 mock，如果依赖外部服务则用接口替身；断言要覆盖正常流程、余额不足、对方账户冻结、金额为负数等边界；测试类与源码类放同一个包路径下。把这些约束写进既定模板后，执行一次就能生成一批候选测试。

需要注意的是，生成结果不是终点。我实际 review 生成测试时，最常发现的三个问题是：断言太弱、边界缺失、把实现细节锁死。断言太弱就是只验证了没有异常，没验证返回值对不对。边界缺失就是没把“金额为零”“除数为零”这种输入放进去。锁死实现细节则是测试过于依赖内部方法调用顺序，跟实现绑定太紧，以后重构一点就挂。你拿到生成结果后，先在这三个维度扫一遍，再决定是接受还是重新生成。

经过多轮实测，我会把生成结果分三类：一类是完全可以合入的，一类只需要微调，一类需要大改。而大改的那类，往往不是模型的问题，而是我给的模板约束还不够，比如没有传具体的方法签名，或者没说明团队里的异常规范。补全测试这件事，模板质量决定了生成结果的天花板。

3.3 高频场景：老代码重构的稳妥路线

重构老代码是我认为最需要讲究策略的地方。很多 AI 工具的激进做法是“把整个类丢进去，请帮我重构”，跑出来一个巨大的补丁，看着很专业，实际上根本不敢合。我的做法是分三步走。

第一步，解释。让 codex 先解释这个类当前做了哪些事、主要的复杂点在哪，这一步不写任何代码，只做分析。第二步，方案。基于第一步的分析，要求它给出两到三种重构方向，比如改策略模式、改枚举、拆方法，并列出每种方案的改动范围和风险。第三步，小步实施。挑其中一个风险最小的方案，让它只改一小块方法，而不是整类变动。

我特别想强调第三步。有一次我尝试直接让工具把一整段 200 行的判断逻辑抽成策略类，生成了 6 个新文件和 1 个大补丁。看起来结构很清晰，结果编译不过，修了大半天。后来我改成让它先只抽一个分支，编译通过、测试通过之后，再继续下一个分支。这个节奏变化让成功率提升了一个量级。

重构的关键不是代码生成能力，而是你对步骤的控制力。这一点 superpowers 帮上忙的前提是，在你下达指令时就已经设定好“只改resolveDiscount方法，不动其他方法”的边界。边界越清晰，生成结果越可控，review 的时候也越有底气。

3.4 接入团队协作流程的注意点

个人用顺了以后，自然会想把它带到团队流程里。我的经验是：可以接入，但必须有纪律。最基础的纪律是，凡是 AI 生成的改动，不能直接推主干，要走正常的合并请求流程，并且必须有测试通过记录。

我建议的新流程是这样的：在本地开一个新分支，执行 superpowers 生成代码变更，然后在分支上跑编译、跑测试、跑静态检查，确认一切正常，再提交合并请求。这样即使生成结果有问题，也不会影响到主干上的其他人。配合持续集成的话，让 CI 在合并前自动执行测试覆盖率和代码规范检查，会给团队多一层保护。

另外还要注意，团队项目往往有一堆约定，比如异常处理方式、日志格式、命名规范。这些约定如果不写进模板里，生成结果就是“通用的好代码”，而不是“符合你们项目风格的好代码”。所以我后来会在模板里附加一个project-context.md，专门存放当前仓库的约定内容。谁改了约定，就顺手维护这个文件，时间长了它就是一个活文档。

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

4.1 环境类问题：命令找不到、权限受限、网络异常

这套环境本身不算复杂，但毕竟涉及多个组件，新手容易在环境环节被劝退。我整理过几类最常撞上的情况。

一是命令找不到。明明装完了 codex，执行codex却提示 not found。这多半是 npm 全局安装目录没有加入 PATH。你可以用npm prefix -g查看全局安装路径，然后把对应的bin目录加到 shell 的 PATH 里，或者直接换用 nvm / fnm 管理 Node，这类问题会少很多。

二是权限受限。如果你配置的是只读沙箱，它在尝试修改项目文件时会直接报错。解决方案不是盲目关掉沙箱，而是检查你的操作意图是否真的需要写权限。如果只是生成代码到标准输出，保持只读模式反而更安全；如果是自动补全文件，那就明确放开写权限，但限制范围。

三是网络异常。codex CLI 依赖外部 API 服务。如果你发现请求超时或者返回连接错误，先确认基础网络环境是否正常，再看 API 服务状态页面。这里我不展开太多，重点在于不要一头扎进代码调试，先把问题定位到网络这一层，能省很多时间。

4.2 密钥与成本控制

API 凭证的管理是我最看重的一环。除了前面说的不要把密钥提交到 Git，还有两个实际建议。一是优先使用环境变量。我在 shell 配置里通过加载.env的方式注入凭证，这样既不在代码里写死，又能按项目区分不同 key。二是设置月度消费限额。AI 代码生成虽然不贵，但高频使用起来积少成多，尤其在团队共享账号时容易失控。在平台后台开启限额，设置一个自己心里有数的数字，比事后看账单好得多。

这里顺带提一个安全小技巧：如果你需要在日志或对话中打印某段代码，而代码里可能有内部信息，我会先把敏感的字符串占位符替换掉，再提交给外部 API。不要在工具链里裸奔你公司的机密代码，这是底线。

4.3 上下文过大的处理经验

不少人第一次用这类工具，就试图把整个项目的源码都塞进去，让 AI“全面了解项目”。这个思路可以理解，但实际可行性不高。API 的上下文长度是有限的，而且哪怕塞得进去，大量与当前任务无关的代码反而会稀释对关键信息的注意力。

我的做法是：先定位，再裁剪。用git status看改了哪些文件，用git diff --stat看单个文件的行数，用rg搜索相关类和方法调用，只把最相关的 1 到 3 个文件组合进上下文里。如果任务确实涉及一个很大的类，我只会截取关键方法区段，而不是整份文件。

刚开始这样做会觉得有点反直觉，总觉得信息给得越多越准确。实际测下来，精炼上下文加上明确的目标描述，生成质量的提升非常明显，反而比“全集投喂”更可靠。建议你把“先裁剪再提问”养成习惯。

4.4 生成结果质量偏低的排查思路

最后聊一下最让人挫败的情况：生成结果看着不错，跑起来就是不对劲，或者逻辑跟预期有出入。这时候我会按顺序检查三件事。

第一，检查提示词里的约束是否具体。是不是只说了“写一个测试”，没有说明用 JUnit 5、不 mock 静态方法、注重边界？约束越具体，结果越接近预期。第二，检查项目上下文是否准确。有没有把当前项目的依赖版本、JDK 版本标注清楚？如果它默认用了项目里不存在的库，极大概率会生成一堆编译不过的代码。第三，检查期望是否合理。一次让 AI 生成一个完整的微服务是不现实的，但让它生成一个 Controller 的骨架、一个 Service 的接口实现，则会稳得多。把任务切小，成功率就会上去。

还有一个通用技巧：如果你发现某一类生成结果总是不行，别硬刚，改造模板。把一次失败的案例记下来，调整模板中的措辞，重新生成。久而久之，你的模板会变得越来越懂你，这也是我理解的“ superpowers 需要自己养成”的意思。工具是通用的，但你和工具之间的默契是私有的。

写在最后

如果你今天就想动手，我的建议特别简单：别去想着一步到位搭一个无比完整的系统。先把 codex CLI 装好，挑一个你手头最烦、最重复的任务——比如给一个老类补测试——用最简单的脚本封装一次。跑通一个小闭环，你对自己工作的感知会完全不一样。

回头再看 superpowers 这个词，我觉得它更像是一种工作习惯：每星期都往里加一条用得上的指令，删掉一条已经失败的指令，慢慢形成一套属于你自己的个人基建。我现在的指令目录里躺着二十多个脚本，真正高频用的也就四五个。但那四五个帮我省下来的时间，已经足够我读完一整本书了。工具的威力从来不在多，而在你愿不愿意花时间把它打磨得趁手。