企业官网建设流程全解析

如果你已经跟我把 Codex CLI 跑起来，并且在 Windows 终端里敲过几次codex，你可能会有这种感觉：这工具能用，但用起来多少有点“没头没脑”。你跟它说写一个登录页，它真的会唰唰给你写一个登录页；但你要是让它改一个三个月前的老模块，它能把自己的思路绕进去，写了又改、改了又删，最后给你留下一个没有测试、没有提交记录、也没人敢合的分支。

出现这个问题的原因，并不是 Codex 的模型不够聪明，而是你在用它的时候，没有给它一套“干活的方法论”。这也是我想在这个系列第四篇里聊 Superpowers 的原因：它给 Codex CLI 补上的正是这一层——用一批预设好的技能，让代理先规划、再动手、边写边验证，而不是让模型自由发挥。

这篇教程面向的是 Windows 用户。网上关于 Superpowers 的讨论不少，但很多默认你是 Mac 或 WSL 环境，真正把 Windows 上那些坑讲清楚的并不多。如果你已经装好了 Codex CLI，想让它从“偶尔惊艳的工具”变成“稳定靠谱的同事”，这一篇应该能帮上忙。

1. 先别急着复制命令，搞清楚 Superpowers 到底替你做了什么事

很多人安装这类东西，习惯性git clone一把梭，看到进度条走完就觉得自己装好了。但 Superpowers 不是那种装完就完事的工具，它的用法决定了你是不是真的装对了。所以我先把原理讲明白，这样你在排错时也能知道问题出在哪个环节。

1.1 裸 Codex 和带技能的 Codex，差别在“有没有章法”

裸的 Codex CLI 本身是个很纯粹的助手：你给它一句话，它给你一段代码。它背后的大模型很强，强到让很多人误以为“只要我描述得够清楚，它就能输出好结果”。但实际用上一周你就会发现，真正拖后腿的往往不是生成能力，而是任务处理路径太随意。

举个例子，你让它修一个 bug。裸 Codex 的做法通常是：

• 扫一眼相关代码；
• 命中某个可疑点；
• 直接改给你；
• 顺利的话你还能收到一句“问题应该解决了”。

问题在于，它没有“先复现问题再动手”的纪律，也没有“改完以后跑一遍相关测试”的自觉，更不会主动确认这个改动会不会连带影响其他模块。模型本身其实知道这些步骤，只是你给的提示没有强制它按这个路径走，它就选了最省事的生成路径。

Superpowers 做的就是这件事：把一套成熟的工程方法论，拆成一堆 Markdown 格式的技能文件，注入到 Codex 的工作上下文里。每个技能都有明确的触发条件和执行步骤。比如它可以让 Codex 在动手写代码前，先输出一份任务拆解清单；或者在改完代码后，把边界条件、验收标准、测试计划单独列出来。

1.2 技能的本质是“给模型的剧本”，不是“给程序的插件”

对于第一次接触这个概念的人，我建议你把它理解为“剧本”。Superpowers 里的技能文件只是文本，里面写了“当你接到这类任务时，请按以下顺序执行：第一步做什么，第二步做什么，每一步的输出格式是什么”。Codex 读取这些文本后，就会照着剧本来表演，而不是即兴发挥。

这样设计的最大好处是：你不需要懂插件开发，也能自定义技能。你打开技能文件，看到里面就是普通的人类语言指令，你想让 Codex 在输出前多问一个问题，直接改文字就行。这可比写代码、调接口友好太多了。

所以安装 Superpowers，本质上做的是三件事：把技能文件放到 Codex 能读到的目录里；让 Codex 在启动时知道这些文件的存在；通过一条提示语触发具体技能。后面安装流程里所有命令，都是围绕这三件事展开的。

为了让你更直观地感受到差别，我把裸 Codex 和加上 Superpowers 之后的 Codex 做个对比：

熟悉这套玩法后，你就知道 Superpowers 解决的不是“Codex 不够强”的问题，而是“Codex 太自由”的问题。

2. 装之前先把 Windows 环境收拾利落，不然命令一样会翻车

我见过太多人卡在这一步：明明教程里的命令是照着敲的，结果报错报得莫名其妙。其实多半不是 Superpowers 的问题，而是 Windows 环境本身埋了雷。这里列几个最常见的检查项，每一步都有必要亲自确认一遍，不要跳过。

2.1 Node.js 版本别太老，也别太新

Superpowers 依赖 Node.js 来跑安装脚本和部分辅助命令。Windows 上安装 Node.js 本身就很简单，官网下载 LTS 版本一路 Next 就行。但这里有个隐藏陷阱：很多 Windows 用户电脑里可能同时存在多个 Node 版本，或者装了某个软件自带的旧版 Node，命令行里node -v显示出来的版本和你想的根本不是同一个。

建议你在 PowerShell 里执行两个命令确认：

node -v npm -v

我实测下来，Node.js 18 LTS 往上都问题不大，20 和 22 更稳。如果你用的是 16 甚至更老的版本，建议先升级。这不是我在制造焦虑，而是 Superpowers 里有些脚本用到了比较新的语法，Node 版本老了会直接报语法错误，那种报错很容易让人误以为是安装步骤出了问题。

再说一个细节：确认 npm 全局包安装路径。Codex CLI 本身很可能是通过 npm 全局安装的，运行npm root -g可以看到全局目录。把路径记下来，后面排错时可能会用到。如果这个目录在C:\Program Files\nodejs等带空格的路径下，部分命令行工具在解析时也可能出问题，到时候记得优先怀疑路径空格。

2.2 Git for Windows 必须装，但别忽略了执行策略

Superpowers 是从 GitHub 仓库克隆下来的，所以 Git 是硬性依赖。Windows 上装 Git 之前，先检查一下：

git --version

如果提示没有这个命令，去 Git 官网下载 Windows 版安装包。安装时我建议保持默认选项，尤其是“Git from the command line and also from 3rd-party software”这个选项，这样才能在 PowerShell 里直接调用 git。

但光装了 Git 还不够。Windows 的 PowerShell 默认执行策略大概率是Restricted，这就意味着你下载或克隆下来的.ps1脚本、甚至某些.js文件在调用时都可能被系统拦下来。运行时你会看到类似“因为在此系统上禁止运行脚本”的报错，看起来很不讲道理。解决办法是调整当前用户的执行策略：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

参数RemoteSigned的意思是：本机创建的脚本可以运行，从网络上下载的脚本必须经过签名。这个设置比Unrestricted安全得多，也足够日常使用。如果你不敢随意改，可以先用Get-ExecutionPolicy看一下当前值，再决定要不要动。

2.3 路径里面出现空格或中文用户名，是你的第一号敌人

Windows 用户目录默认是C:\Users\你的用户名，如果你的 Windows 登录名是中文，或者姓名字段里带了空格，那安装 Superpowers 时很容易踩坑。

原因不复杂：很多 Node 脚本在解析路径时，会用空格来拆分参数。路径一有空格，脚本就把一个完整路径硬生生拆成了两段，然后对着不存在的文件报错。你说它离谱吧，它在 Windows 上就是这么真实。

解决方案有两个。一个是把仓库克隆到一个全英文、无空格的纯路径下，比如C:\tools\superpowers，然后在配置里用这个绝对路径。另一个是通过环境变量指定技能目录，具体在下一节安装流程里会说到。

为了让你提前有个概念，我列一个路径规划表：

如果你已经装了 Codex CLI，应该知道.codex目录就在用户主目录下。Windows 下创建这个目录本身没问题，问题只在于里面的技能文件能不能被正确加载。路径长得越规矩，后面省的事越多。

3. 正式安装流程：克隆、装依赖、注册技能，一件件来

这节进入正题。我会用最标准的 PowerShell 操作演示一遍完整流程，并且把每一步背后做的事情说清楚，这样你不管是按步骤执行，还是想自己微调，心里都有底。

3.1 把 Superpowers 仓库放到一个稳定位置

先打开 PowerShell，切到你准备好的干净路径下。我这里按C:\tools举例：

cd C:\tools

然后克隆仓库：

git clone https://github.com/obra/superpowers.git superpowers

克隆期间如果网络不稳定，可能会中断。Windows 上遇到这种情况最常见的原因是安全软件实时扫描拖慢了 Git 的写入速度，并不一定是你的网络有问题。真遇到克隆到一半卡住，先等一会儿，再不行就删掉半成品目录重新克隆一次。

克隆完成后进入仓库目录：

cd superpowers

这时候你可以先看一眼目录结构，确认skills文件夹确实存在。ism那里面装的就是技能文件。

3.2 安装依赖并执行注册脚本

Superpowers 本身带了一些辅助脚本，需要先安装依赖：

npm install

这一步会生成node_modules目录，安装过程可能需要一两分钟。如果网络不出问题，你看到类似added 100+ packages的输出就说明依赖装好了。

接下来是注册。Superpowers 有配套的安装命令，不同版本命令可能略有差异，以我目前常用的版本为例：

npx superpowers install codex

如果这个命令在你当前版本里不存在，不要慌。你可以先运行npm run看一下仓库里有哪些可执行脚本，通常会发现类型install:codex或者setup这样的选项，挑名称带 codex 的那个执行即可。

这条命令做的事情说穿了也不神秘：它会把skills文件夹里的技能文件，复制或者链接到 Codex CLI 的技能目录里，也就是C:\Users\你的用户名\.codex\skills。如果你的机器上还没有.codex目录，脚本会顺手创建一个。

3.3 手动绑定技能目录（备用方案）

有时候受限于权限或者版本问题，自动注册命令就是跑不起来。这时候也别折腾了，用手动方案一样能成，而且原理更透明。

如果你只是想让 Codex 能用上技能，最简单的方法是把技能目录复制过去：

$codexSkills = "$HOME\.codex\skills" New-Item -ItemType Directory -Path $codexSkills -Force Copy-Item -Path "C:\tools\superpowers\skills\*" -Destination $codexSkills -Recurse

如果你想用链接方式，让技能目录始终跟随仓库更新，那可以用符号链接。注意，Windows 上创建符号链接需要开发者模式或管理员权限。PowerShell 里执行：

New-Item -ItemType SymbolicLink -Path "$HOME\.codex\skills" -Target "C:\tools\superpowers\skills"

如果提示没有权限，可以改用传统方式，在管理员权限的命令提示符或者 PowerShell 里执行：

cmd /c mklink /D "%USERPROFILE%\.codex\skills" "C:\tools\superpowers\skills"

无论哪种方式，最后你打开资源管理器，看到C:\Users\你的用户名\.codex\skills目录里躺着todos、brainstorming、subagents这些子文件夹，就说明技能文件已经就位。

3.4 让 Codex 每次启动时都能感知技能

文件就位之后还差一步：让 Codex 知道该去哪里找技能。Codex CLI 启动时会读取当前用户目录下的AGENTS.md文件（Windows 下就是C:\Users\你的用户名\.codex\AGENTS.md），如果这个文件里写明了技能目录的路径和用法，Codex 在会话开始后就会自动把技能拉入视野。

你可以在.codex目录下手动创建或编辑AGENTS.md，加入类似下面的内容：

# Codex 全局指令 - 技能目录位于 ~/.codex/skills - 当用户要求使用某项技能时，先读取对应技能目录下的技能说明文件，再按技能说明执行 - 常见技能包括：todos（任务拆解）、brainstorming（方案讨论）、subagents（子代理执行）

这里有个很容易被忽略的 Windows 细节：Codex CLI 对~的处理在绝大多数情况下是正常的，但如果你是在自定义配置里写路径，我建议直接把~展开成完整路径，减少解析问题的概率。

改完配置文件后，最好重新打开一个终端窗口，让 Codex 重新加载环境。这一步经常被忽略，很多人改完配置发现没生效，其实只是没有重启终端。

4. Windows 上最常见的四个安装报错，我一个个帮你拆掉了

安装这件事，照着流程做一般不会出大问题。真正让人崩溃的是报错。我把 Windows 环境下最常遇到的几个坑整理出来，每个都会说清楚现象、原因和解决路径。你照着这个思路排查，能省下大量在搜索引擎里翻答案的时间。

4.1 现象一：PowerShell 死活不让你跑脚本

报错提示可能是这样的：

无法加载文件 C:\tools\superpowers\scripts\setup.ps1，因为在此系统上禁止运行脚本

看见这个报错先别怀疑人生，它跟你的脚本一点关系都没有。这就是 PowerShell 默认执行策略Restricted在起作用。解决方式我在前面提过，直接运行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

执行完以后，再跑一次之前的命令。如果还报错，确认一下你是否把作用域写对了。只写在CurrentUser范围就够了，可以不动系统级策略。

4.2 现象二：git clone 到一半提示文件名过长

Windows 的老牌毛病。Superpowers 技能文件里有一些嵌套层级比较深的路径，Windows 默认的MAX_PATH限制是 260 个字符，一旦路径超过这个长度，Git 就会报错。

解决办法是在 Git 里开启长路径支持：

git config --global core.longpaths true

设置完后，删掉克隆了一半的目录，重新克隆一次。如果还是不行，那就是 Windows 系统级的长路径支持没打开。进“设置—系统—系统信息—高级系统设置—环境变量”，新增一个系统变量：

变量名：LongPathsEnabled 变量值：1

改完重启终端再试。这一步在程序员群体里其实很常见，解决后几乎一劳永逸。

4.3 现象三：安装脚本执行时报错，看起来和换行符有关

这类报错很隐蔽。Windows 上 Git 默认会把代码仓库里的LF换行符自动转成CRLF，而 Superpowers 的脚本大多是在 macOS/Linux 环境下写的，两者换行符不一致，轻则脚本行为异常，重则直接报错。

解决方法是关闭 Git 的自动换行转换。你可以在克隆仓库前设置：

git config --global core.autocrlf false

如果你已经克隆完了仓库，可以进入仓库目录后执行：

git config core.autocrlf false

然后把仓库删掉重新克隆，确保换行符已经是原样保留。我不建议你手动用编辑器去把所有文件转一遍，那样容易改坏其他内容，重新克隆是最干净的。

4.4 现象四：技能装好了，但 Codex 回答时完全没反应

这类问题最气人，因为安装步骤看起来全都成功了。你在 Codex 里提到“使用 todos 技能”，它却像没听见一样，照旧直接给你写代码。

排查路径应该按下面这个顺序走：

1. 确认AGENTS.md文件内容正确，并且放在C:\Users\你的用户名\.codex\下；
2. 重新打开终端，让 Codex 重新加载；
3. 在当前项目目录下打开 Codex，确认它是把AGENTS.md读进去了。你可以在提示里直接问它“你读了哪些指令文件”，它会如实回答。

如果它说没读到，检查路径。Windows 下最容易犯的错就是用户目录判断错误。你可以在 PowerShell 里执行：

echo $HOME

看看输出结果是不是C:\Users\你的用户名。如果输出跟你预想的不一样，说明终端当前用的用户环境有问题，所有配置都要按实际输出路径调整。

5. 安装验证：用一个真实任务，观察技能是否真正接管了 Codex

装完之后最让人心痒的就是想知道到底成没成。我强烈建议你不要只盯着目录结构看，而是实际跑一个任务，通过 Codex 的行为变化来判断。

5.1 先检查技能文件的完整状态

做完前三步，你应该能在C:\Users\你的用户名\.codex\skills下看到类似下面的结构：

skills/ todos/ SKILL.md brainstorming/ SKILL.md subagents/ SKILL.md ...

如果技能文件都在，说明安装环节已经成功。这时候可以进入下一步验证，看 Codex 的运行行为。

5.2 用一段能触发技能指令的提示词测一次

在 PowerSheell 里进入一个临时目录，比如C:\temp\test，启动 Codex：

cd C:\temp\test codex

然后输入一段带明确技能指令的提示，例如：

请使用 todos 技能，帮我规划一次登录模块的重构，先不要写代码，只输出任务拆解清单。

如果 Superpowers 生效，你会看到 Codex 的行为明显区别于裸跑：它不会急着生成代码，而是先输出一张结构化的清单。清单里可能会包含“确认现有登录流程”“梳理接口依赖”“划分重构步骤”“制定测试方案”这样的条目。

不夸张地说，这一步是判断安装是否成功的金标准。目录再好看，Codex 的行为没变化，那都是白搭。

5.3 用日志确认 Codex 到底读没读指令

如果你观察不到明显变化，不要急着下结论。执行codex --verbose进入会话，重新跑一次同样的提示，然后看日志输出。不同版本的 Codex 日志输出格式不同，但一般会包含“loading instructions from ... AGENTS.md”之类的内容，确认它确实读取了全局指令文件。

如果日志里没有相关记录，问题大概率还是出在路径或文件名上。Windows 上大小写不敏感是常态，但某些版本对隐藏文件.codex目录的识别反而有细微要求。确认一下.codex目录是不是真的在用户主目录下，而不是在某个项目的根目录下。

6. 装好只是开始，Windows 下的日常使用细节值得你多留个心眼

安装成功后，真正的日常使用才算开始。以下几条是 Windows 环境下使用 Superpowers 的一些经验总结，每条都是我实际用下来觉得有价值、值得提前注意的。

6.1 符号链接和复制目录，按你的更新习惯选

我在前面提到过两种绑定技能目录的方式：符号链接和直接复制。日常使用中选哪种，主要看你对更新频率的预期。

如果你希望 Superpowers 上游仓库一更新，技能就自动同步，那就用符号链接。每次启动 Codex，它读到的是仓库里的实时文件。代价是，如果你手动改了技能文件，可能被上游更新覆盖。

如果你更希望自己定制技能内容，并且不想被上游改动打扰，那就用复制目录。缺点是要手动同步更新，升级时比较麻烦。我的习惯是：基本不动上游技能，只新增自己的技能文件。这种情况下复制目录反而更稳当。

6.2 项目内的技能调用，建议把本目录的 AGENTS.md 也配好

Codex 不仅会读取用户全局的AGENTS.md，它也可能读取当前项目目录下的AGENTS.md。这在多项目工作中非常实用。

你可以在某个项目的AGENTS.md里写明这个项目特有的约束，比如“禁止使用某个依赖包”“所有接口必须写单元测试”“代码风格遵循 eslint 配置”，这样当你在该项目里调用 Superpowers 技能时，Codex 会把项目约束和通用技能结合起来，输出结果的质量会明显提升。

这一点在 Windows 上尤其值得注意，因为很多开发者是直接在 Windows 上跑项目，而不是在 WSL 里，全局配置和项目配置的层级关系容易搞混。你可以在项目目录下用一条命令临时测试：

codex "告诉我你读过哪些 AGENTS.md"

如果它列出的文件里包含当前项目的配置，说明项目级配置加载正常，技能跟配置的协同机制是通的。

6.3 更新技能库的方法，其实比你想的更简单

Superpowers 本身就是 Git 仓库，所以更新逻辑很简单。进入仓库目录：

cd C:\tools\superpowers git pull

pull 完成后，如果装的是依赖变了，再跑一次npm install。如果你用的是符号链接，技能文件会自动同步，不需要重新把技能注册一遍。如果你用的是复制目录，那就再复制一次技能文件：

Copy-Item -Path "C:\tools\superpowers\skills\*" -Destination "$HOME\.codex\skills" -Recurse

复制时如果遇到文件占用报错，先关闭正在运行的 Codex 会话再试。Windows 下文件锁是很常见的问题，不用慌，关掉占用它的程序就行。

6.4 UTF-8 乱码问题，提前设置一劳永逸

Windows PowerShell 的默认编码在很多版本下还是跟 UTF-8 有点不对付。Superpowers 技能文件里的中文、表情符号或者其他 Unicode 字符，在旧版终端里可能会显示成乱码，虽然不影响脚本执行，但很影响排查问题。

建议你在 Windows Terminal 的设置里，把默认代码页切成 UTF-8。也可以在 PowerShell 里执行：

chcp 65001

这种设置只对当前窗口有效，想要全局生效，就去系统区域设置里勾选“使用 Unicode UTF-8 提供全球语言支持”。注意，这个选项可能影响部分老软件的显示，动手前自己权衡一下。我实际用下来，开发环境里基本都是 UTF-8，改了之后几乎没有副作用。

6.5 给自己留一个“无技能”的备用法

最后分享一个我自己的习惯。Superpowers 很香，但不是每个任务都必须用它。简单到一句话就能说清楚的改动，强行套技能流程反而是负担。

当你需要快速验证一个想法时，直接在纯 Codex 环境下跑就好。等想法开始变得复杂、需要多文件改动时，再切换回技能模式。这种“按需切换”的使用方式，才是把工具价值最大化的关键。

我在实际使用中发现，Superpowers 最让我上瘾的不是它让 Codex 变“听话”了，而是它在不知不觉中帮我把项目里那些“应该做但总忘做”的事情补齐了——写测试、列计划、确认边界条件。这些东西过去靠人盯着，现在靠一套技能文件，稳定执行，不闹情绪。

如果你在 Windows 上把技能装好、跑通、用顺手了，你会发现 Codex 从一个“写代码很快的实习生”，慢慢变成了“有自己工作节奏的同事”。这个转变，比任何一次升级带来的快感都踏实。