★ FEATURED ARTICLE 如果你也把 Codex CLI 当成日常写代码的搭子一定遇到过这种尴尬让它看一眼设计稿它礼貌回复“我只能处理文本”让它扒一个网页它老老实实给你 curl 回来一堆 HTML 标签让它查点资料它只能凭训练时的记忆瞎猜连个出处都没有。最近我一直在折腾一个叫superpowers的开源项目它正好就是冲着这些短板去的。简单说superpowers 是一套给 Codex CLI 加“技能系统”的扩展方案通过结构化技能文件、项目级挂载和外部工具接入让 Codex 从“只会读写终端文本”的工具人变成能看图、能抓网页、能跑深度研究的助手。这篇内容适合两类人一是已经在用 Codex CLI 但觉得它不够聪明的开发者二是刚听说 Codex 想把它用在真实项目里的新手。我会把安装、配置、核心技能、实战过程、常见坑一次性讲透。1. 为什么需要 superpowers先搞清楚 Codex 的边界在哪1.1 Codex 已经很能打但它是个“近视眼”Codex CLI 是 OpenAI 推出的命令行编程 Agent跑在终端里能读你的代码仓库、改文件、执行命令、跑测试、甚至自己修 bug。我用了很长一段时间坦白说它在“改代码”这件事上确实有一手给它一个报错信息它能顺着调用栈定位到文件改完跑一遍测试确认通过。但你让它跳出纯文本的舒适区问题就来了。最典型的三类场景Codex 原生几乎是无能为力的看不见图像。设计稿、截图、UI 效果图、PDF 里的图表在 Codex 看来就是一坨二进制数据它不知道图里画了什么。程序员日常恰恰离不开设计稿前端开发尤其痛苦。不能主动访问网页。它确实能在你的终端里执行 curl但 curl 拿到的是原始 HTML真正的正文内容、排版结构、关键信息全埋在标签和脚本里靠人眼都费劲让模型去硬啃更不现实。长文档处理很粗糙。一个几十页的 API 文档、一份冗长的竞品分析报告你没法“丢”给 Codex它也没有系统的办法把核心信息抽取出来。这不是 Codex 模型能力不行而是它的工作形态太“干净”了一个终端一堆文本流。真实开发中我们要面对的是屏幕上的像素、网页里的多媒体、格式复杂的文档这些信息形态 Codex 原生根本接不住。1.2 superpowers 到底给 Codex 加了什么superpowers 的做法不是给模型加魔法而是建立了一套技能Skills机制。它把高频操作沉淀成结构化的 Markdown 技能文件每个技能文件里写清楚这个技能解决什么问题、什么条件下触发、执行分几步、每一步具体怎么做、输出格式是什么、有哪些注意事项。然后在项目里通过AGENTS.md这个文件把技能“挂载”给 Codex。Codex 每次启动都会读取项目里的AGENTS.md发现在这个项目里可以做哪些事需要时再去读具体的技能文件按步骤执行。这套设计的好处特别明显。首先它能复用。我在 A 项目里调好的一套“抓取网页并提炼要点”的流程B 项目直接就能用不用每次重新描述需求。其次它稳定。直接跟模型说“帮我看看这个网页”是模糊指令能不能做好全看模型心情而技能文件是精确步骤Codex 会一格一格地走。最后它可审查。技能是纯文本写得好不好、有没有安全隐患打开文件一眼就能看到比黑盒 prompt 强太多。此外superpowers 还支持通过 MCPModel Context Protocol把外部工具接进来。模型不需要自己“知道”某个工具怎么用只需要按技能文件里的说明去调用工具返回的结果再交给模型分析。这也是为什么这个项目敢叫 superpowers——它等于给 Codex 装了一套可扩展的“外设驱动”装什么驱动就有什么超能力。2. 安装与初始化从零搭建带“超能力”的 Codex2.1 装前准备先把地基打牢superpowers 是对 Codex CLI 的扩展前提是你已经装好并登录了 Codex CLI。如果你还没装先做这一步# 安装 Codex CLI npm install -g openai/codex # 确认安装成功 codex --version第一次运行codex会引导你登录 OpenAI 账号按提示操作即可。装好 Codex 之后再来准备 superpowers 的环境要求不多但容易忽略Node.js 版本最好在 18 以上。我用 Node 16 试过一次各种依赖报错升到 20 之后一路畅通。建议先node -v查一下低于 18 就先升级别在版本问题上浪费时间。建议准备一个干净的测试项目目录专门做安装演练。superpowers 安装时会往项目里写文件、改AGENTS.md在一个空目录里先跑通比直接在生产仓库里折腾要稳妥得多。确认网络能正常访问 npm registry。这个听起来像废话但实际很多人卡在安装阶段就是因为 npm 镜像配置问题后面我会单独讲。2.2 三步完成安装与项目激活安装过程比我预想的简单核心就三步。第一步是全局安装脚手架工具第二步是运行 install 命令第三步是检查生成的文件结构。# 第一步全局安装 superpowers 脚手架 npm install -g obra/superpowers # 第二步在你自己的项目根目录里执行 cd your-project npx superpowerslatest install第二步会做几件重要的事创建一个隐藏的.superpowers/目录往里面写入技能文件库检查项目里有没有AGENTS.md没有就新建有就把 superpowers 的技能索引段落追加进去。跑完之后用tree或者编辑器看一眼项目结构正常情况下应该是这样的your-project/ ├── AGENTS.md # 被追加了 superpowers 技能索引 └── .superpowers/ └── skills/ # 内置技能文件按类别分目录存放这里有个关键点AGENTS.md就是 Codex 读取项目说明的入口文件。superpowers 在AGENTS.md里写了类似“本项目启用了 superpowers 技能系统常用技能清单如下……”这样的段落Codex 看到这段就会知道要去.superpowers/skills/里找具体技能定义。如果你发现技能不生效八成就是AGENTS.md没配好后面排查部分会再讲。2.3 config.toml 里的关键配置superpowers 本身不需要改太多配置但 Codex CLI 的配置文件里有两个点值得留意。配置文件在~/.codex/config.toml先打开看看当前内容。# ~/.codex/config.toml model gpt-5-codex # 或你账号可用的最新模型重要的是支持视觉输入 [agent.codex] enable_skills true # 如果存在这个字段务必确认是 true第一个是model 字段。superpowers 里的图像类技能需要模型支持视觉输入如果你的模型不带视觉能力让它读设计稿就会直接报错。我自己的经验是选账号当前可用的最新模型不仅视觉识别准确处理长网页抓取结果时也不容易断片。第二个是技能开关。不同版本的 Codex 配置文件字段名不太一样新版可能在[agent.codex]下有类似enable_skills的选项。这个字段不是所有版本都有如果没有就忽略不用自己硬加加了反而可能报解析错误。一个小技巧改完config.toml后重启终端或者重新打开项目目录确保 Codex 重新读取了新配置。如果你在团队协作或者多台机器上工作.superpowers/目录和AGENTS.md的改动务必提交到 Git 仓库。这样团队里其他人 clone 下来就直接具备同样的技能环境不用每个人重复安装而且技能文件的版本变更也能通过 Git 记录追溯出了问题好排查。3. 核心技能拆解这些“超能力”分别解决什么问题3.1 图像与视觉技能让 Codex“看见”设计稿我最初被这个项目吸引就是因为它的图像技能。装好之后我在项目里做了一次测试把一张产品原型图丢进去在对话里明确说“使用图像查看技能读取docs/ui-design.png描述整体布局和主要交互元素”。Codex 会读取技能文件按里面的步骤先确认文件存在、再加载图像、然后分段描述内容。实际效果确实惊艳。它不仅能描述“这里有左侧导航、顶部有搜索栏”还能进一步分析元素尺寸比例、颜色搭配、间距规范。我在前端项目里最常用的场景是把设计稿交给 Codex让它按照稿子生成 Vue 组件骨架或者对照稿子检查现有页面差在哪里。但这里有个使用细节触发技能时指令越具体效果越好。只说“帮我看看这张图”Codex 不一定能联想到技能文件而“使用图像查看技能读取xxx.png输出布局描述和组件拆分建议”基本上百发百中。实操中还要注意图片尺寸问题。分辨率过高的截图比如 4K 屏全屏截图会被模型缩放或截断信息丢失严重而且 token 消耗会暴涨。我现在的习惯是先把大图压缩到 1200px 宽以内在保证清晰的同时控制开销。压缩这一步用系统自带预览工具或者sips命令都行30 秒搞定后面能省不少时间和 token。3.2 网页抓取与信息提取告别满屏 HTML 噪音第二类高频技能是网页抓取。以前让 Codex 看一个网页它只能 curl然后在一堆 HTML 里挣扎。superpowers 的抓取技能会先把目标 URL 的内容转换成干净的 Markdown 或结构化数据再交给模型分析这个预处理环节直接决定了信息提取质量。我实际测试过几个场景效果比较稳定抓 API 文档写 SDK 封装时让 Codex 抓取接口文档页面提取出所有接口路径、请求参数、响应字段生成 TypeScript 定义和封装函数。抓竞品页面把竞品官网的某个功能介绍页面转成 Markdown然后问它“这个功能的卖点描述集中在哪几个部分用什么词形容用户价值”有一定参考价值。抓 GitHub README调研开源库时先抓 README再让它对比几个库的安装方式、功能特性和维护活跃度。使用的时候我会明确给出 URL 和输出要求比如“使用网页抓取技能访问https://...提取全部接口路径和参数说明以表格输出”。如果页面内容很长建议拆分成几个子任务处理一次抓一个章节比一次性全部塞给模型要稳得多。这个技能也有它的边界有反爬机制的页面、需要登录才能看的页面、纯 JavaScript 渲染的动态页面抓取效果取决于页面结构和抓取工具本身的能力。遇到抓取失败或者抓回来是空壳别硬试换个思路用浏览器技能或者直接让 Codex 根据用户提供的文本内容分析。3.3 深度研究技能让 Codex 学会“做功课”deep-research 是我最近才认真用的技能它解决的问题是让 Codex 不满足于单次搜索或单页抓取而是像一个做调研的人那样拆解问题、追查来源、交叉验证、输出带引用的结论。触发方式和前面类似我会在对话里说“使用深度研究技能调研一下 Rust 和 Go 在 CLI 工具开发上的社区生态差异”。Codex 会先拆解关键词比如 Rust CLI、Go CLI、cobra、clap然后挨个去抓取搜索结果页面、开源项目 README、技术讨论帖最后生成一份带来源链接的对比报告。坦白说它的研究深度和人类研究员还有差距信息来源基本依赖它能抓到的页面质量但在“快速了解一个陌生技术方向”和“技术选型前扫雷”这两个场景下已经能省下大量搜索时间。它输出的报告有个好习惯每条结论后面都带来源 URL。这点我很喜欢因为可以自己点开验证而不是完全相信模型的判断。使用的时候我会克制一点明确限制来源数量和报告长度比如“最多抓取 10 个来源报告控制在 500 字以内”。不加限制的话Codex 会为了“深度”疯狂抓取token 消耗非常快。这种成本控制意识在长期使用 superpowers 时非常重要。3.4 其他值得关注的技能按需启用就好superpowers 内置的技能不止上面三大类还有一些在特定场景下非常好用。我整理了几个自己测试过觉得实用的技能方向主要用途我的评价文档格式处理把 PDF、Word 内容转成可分析的纯文本处理合同、报告等资料时很省心文件批量整理对目录内多个文件做统一分析或重构批量补注释、统一导出格式时好用浏览器自动化模拟浏览器操作特定页面适合处理动态渲染页面但配置成本稍高结构化数据抽取从文本中抽取实体、字段、关系处理日志、问卷、非结构化数据时很强需要注意技能清单是跟着 superpowers 版本走的不同版本的技能数量和名称可能有差异。最靠谱的方法是打开.superpowers/skills/目录看看当前版本内置了哪些技能每个技能文件开头都有触发条件和适用范围说明花十分钟过一遍你就知道这个版本能做什么了。4. 一个完整的实战从设计稿到可运行代码4.1 任务背景与我的方案选择理论讲再多不如跑一次真实任务。我用一个自己最近做的小项目来演示一个内部工具的数据看板页面UI 设计稿已经画好了接口文档也写好了但页面还没开发。我计划用 superpowers 让 Codex 帮我从设计稿直接生成前端页面并完成接口对接。整个任务拆成三个阶段第一阶段用图像技能看懂设计稿第二阶段用网页抓取技能提取接口文档第三阶段让 Codex 生成代码并和现有工程对接。这个拆分方式很重要每个阶段是独立的子任务上下文清晰Codex 不容易把设计稿信息和接口信息搞混。如果你一口气把所有需求都塞在一个会话里模型很容易顾此失彼后面排查问题也麻烦。4.2 实际执行过程记录第一阶段我先把设计稿放到了docs/dashboard-design.png然后在 Codex 里发了一条指令使用图像查看技能读取 docs/dashboard-design.png。 这是一个数据看板的设计稿请描述整体布局结构、主要模块、每个模块包含的图表和数据字段尽量具体。Codex 读完技能文件后开始执行先确认图像存在再逐步输出描述顶部是标题和日期筛选区左侧是四个 KPI 卡片中间主体区域是一个大的趋势折线图右侧是两个表格模块分别展示订单列表和异常告警。底部还有一个占比环形图。它连 KPI 卡片的色块主色和字体大小层级都描述出来了信息量足够支撑写代码。第二阶段我需要接口文档的字段定义。文档在内部 Wiki 的一个页面上我直接把 URL 给了 Codex使用网页抓取技能访问 https://internal.wiki/api/dashboard-doc.html。 提取所有接口的路径、请求参数、响应字段以表格输出。重点标注响应里的 data 结构。抓取结果转成 Markdown 后被 Codex 整理成了接口清单响应字段的统一结构是{ code, message, data: { kpis, trend, orders, alerts, ratio } }。跟我随手翻原始文档核对了几个字段没发现错误数据对应关系准确说明预处理环节把页面里的表格和嵌套结构都正确保留了。第三阶段把设计稿描述和接口字段合并成开发指令基于之前的设计稿结构分析和接口文档字段用 Vue 3 TypeScript 在 src/views/dashboard 下生成页面。 布局按设计稿描述数据用接口文档的字段名。先生成组件骨架再填充业务逻辑。Codex 在会话里同时保留了前两个阶段的信息直接生成了一整套.vue文件。我检查了代码结构布局基本还原了设计稿的模块划分数据变量名和接口返回字段完全对应还有一个 mock 数据文件方便本地调试。整个过程大概二十分钟中间只有一处我手动修正过 — 设计稿里某个指标卡片的单位标注不够清楚Codex 按照自己的猜测写了我改成了正确单位。4.3 过程中踩到的两个坑上面这个流程跑得顺利不代表没有意外。第一个坑是设计稿截图分辨率太高。第一次我丢了一张完整的 2K 截图进去Codex 处理到一半提示输入超过限制。后来我把截图按模块裁成几张图每个功能区单独分析问题立刻解决而且分析得比之前更细致。第二个坑是接口文档页面太长一次抓取之后 Codex 输出了一半就断了。我把指令改成“先抓取接口列表部分输出路径和参数再抓取响应字段部分”分两次执行效果稳定很多。这两件事的核心教训是同一个给 Codex 喂信息的粒度很重要。内容太多就拆任务太杂就分这也是使用 superpowers 所有技能时最值得养成的习惯。5. 常见问题与排查技巧装完不代表能用5.1 问题速查表这几天在多个环境里折腾 superpowers我自己和身边朋友遇到过的典型问题都差不多整理成一张速查表方便你直接对照排查症状常见原因处理方式对话里提到技能Codex 无动于衷AGENTS.md没有被正确写入技能索引重跑npx superpowerslatest install或手动检查AGENTS.md内容图像技能报“无法处理该文件”模型不支持视觉或路径写错检查config.toml的 model 字段确认路径相对当前目录正确npm 安装卡住或报错Node 版本过低、npm 镜像异常升级 Node ≥18检查 npm config 里的 registry 配置抓网页技能返回空内容页面强依赖 JavaScript 渲染或反爬换用浏览器自动化技能或手动保存页面内容后传给 Codextoken 消耗异常大技能没有限制抓取数量和输出长度在指令里强制要求“最多抓 N 个来源”“报告不超过 N 字”Codex 不按技能步骤执行反而自由发挥指令太模糊明说“使用 xxx 技能”并把输出格式一并指定本地多个项目技能版本不一致不同时间安装、版本不同把.superpowers纳入 Git统一版本管理5.2 安全与权限管理别忘了这是一把真刀superpowers 给 Codex 开了很多新通道但能力越大越要管好边界。我最想提醒的是给 Codex 联网和浏览器能力之后它就有了“替你访问外部世界”的能力。如果项目里有敏感信息或者你运行它的环境连了生产网络务必设置好边界。几个我自己的安全习惯在配置里留意是否开启了终端命令自动执行。有些场景下 Codex 会自动跑命令来确认代码是否正确这是好事但我不建议在完全无人值守的模式下让它跑 all-in-one 命令。不要轻易让 Codex 把抓取到的网页内容写进项目核心文件。它抓回来的是外部数据可能包含恶意脚本样本、漏洞描述等内容写进工程文件有潜在风险。我一般让它在输出里展示确认无害后再决定是否落盘。定期审阅技能文件和历史记录。每隔一段时间看看.superpowers/skills/里有没有被改过的痕迹确认没有多出不明来源的技能文件。本质上是把 superpowers 当成有权限的服务来管理遵循最小权限原则不需要的技能就不启用不需要的权限就不开。5.3 让 superpowers 更好用的几个实战小技巧最后分享几个我实际使用中总结出来的技巧不算什么高深的东西但很管用。第一养成“先技能后提问”的对话习惯。每次用 Codex 之前先在脑子里想一下这个任务属于哪类问题有没有对应技能如果有就明确说出来。这能让 Codex 直接进入正确的执行路径而不是从零猜你的意图。第二把你自己常用的操作也写成技能。superpowers 允许在.superpowers/skills/下加自定义技能。我最开始只是用现成的内置技能后来发现团队里有一套固定的代码审查流程每次都花不少时间重复描述。于是把流程写成了一个自定义技能文件触发条件是“使用团队代码审查技能”里面规定了审查范围、检查清单、输出格式。从那以后Codex 每次执行这套流程都一丝不苟比我口头描述稳定太多。第三结合项目背景信息使用。在项目AGENTS.md里除了 superpowers 的技能索引还可以顺手补一段项目简介技术栈是什么、目录结构怎么组织、常用的构建命令有哪些。这样 Codex 在调用技能时能结合项目上下文而不是像个临时工一样对项目一无所知。第四善用 Git 管理和版本对比。技能文件不只能被 Codex 读取它本身也是普通的 Markdown完全可以纳入代码评审流程。我们团队现在的新规则很简单新增技能文件要过评审评审内容就是看这个技能文件会不会让 Codex 做出不安全的行为。这样等于把“给 AI 开权限”这件事也变成可审查的工程实践而不再是一个黑盒。我个人用下来最大的体会是superpowers 真正贵的不是那点 token而是你愿不愿意把自己的工作流沉淀成“机器也能看懂的说明书”。把一次性的指令变成可复用的技能把个人的操作习惯变成团队的共同资产这个转变带来的效率提升远比多几个技能文件大得多。如果你也在用 Codex CLI花一个下午装好它、读一遍内置技能、把你最常干的流程写成自定义技能之后你会回来感谢这个下午的投入。
阅读完成 · 觉得有帮助？
