企业官网建设流程全解析

1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“这玩意儿把 Claude Code 和 Codex CLI 的玩法又往上抬了一层”。点进去看完之后，我大概理解了它想干的事：把零散的、靠个人经验堆出来的 AI 辅助开发流程，抽象成一套可复用、可组合、可迁移的 agentic skills framework。说白了，就是给“让 AI 帮你写代码”这件事，定一套软件开发的章法。

很多人对 Claude Code、Codex CLI 这类工具的理解还停留在“终端里能对话的 AI”。但真正用过一段时间就会发现，问题从来不是模型够不够聪明，而是你怎么组织任务、怎么约束输出、怎么让多个步骤串起来不跑偏。superpowers 这套框架的核心价值，就是回答这个问题。它不绑定某一个具体模型，也不绑定某一个 CLI，而是一套方法论加配套的 skill 组织方式，让你在 Claude Code、Codex CLI 甚至本地模型上，都能跑出一致的工作流。

这篇文章适合三类人看。第一类是已经在用 Claude Code 或 Codex CLI，但总觉得“用得不顺手、每次都要重新解释需求”的开发者；第二类是刚接触 agentic 开发，想搞清楚 skills framework 到底是个什么概念的入门者；第三类是在团队里想推动 AI 辅助开发规范化，需要一套可落地方法论的技术负责人。我会从框架设计思路讲到具体实操，包括 Claude Code 的安装配置、Codex CLI 的命令体系、本地模型接入、常见报错排查，尽量把踩过的坑都摊开说。

需要先说明一点：superpowers 本身是一个偏方法论和 skill 编排的框架，它不是一个装完就完事的软件。理解这一点很关键，否则你会一直在找“superpowers 安装包”而找不到。它的落地依赖 Claude Code、Codex CLI 这类执行载体，框架负责的是“怎么组织”，载体负责的是“怎么执行”。

2. 框架整体设计与思路拆解

2.1 为什么需要 agentic skills framework

传统的 AI 辅助编程，基本是“一问一答”模式：你描述需求，模型给代码，你复制粘贴，出问题再问。这个模式在简单任务上没问题，但一旦任务变复杂，比如“重构一个模块并补全测试”，就会暴露三个致命问题。

第一个问题是上下文漂移。多轮对话之后，模型会逐渐忘记最初的约束条件，你前面说的“不要引入新依赖”，到第十轮可能就被它抛到脑后了。第二个问题是步骤不可复用。你这次调教出一套好用的提示词流程，下次换个项目又得从头来。第三个问题是质量不可控。同一个需求，今天问和明天问，输出质量可能差很多，因为没有固定的检查环节。

superpowers 这套 agentic skills framework 的设计出发点，就是把这三点逐个击破。它把开发任务拆成一个个skill（技能单元），每个 skill 有明确的输入、输出和约束。多个 skill 可以组合成一条workflow（工作流），工作流里的每一步都有校验点。这样一来，上下文被切分成可控的块，步骤被固化下来可以复用，质量也有了检查机制。

我个人的理解是，这套思路借鉴了软件工程里“关注点分离”和“流水线”的经典思想，只不过把执行者从人换成了 AI agent。你不再是对着一个万能助手喊话，而是在指挥一支各司其职的小队。

2.2 核心概念：skill、workflow 与 agent 的关系

要理解 superpowers，得先把三个核心概念理清楚，不然看文档会一头雾水。

Skill是最小执行单元。一个 skill 通常对应一件具体的事，比如“读取指定文件并总结结构”“根据接口定义生成类型声明”“对改动做静态检查”。每个 skill 会定义它需要什么输入、产出什么结果、在什么条件下算成功。你可以把它类比成一个函数，有明确的签名和职责。

Workflow是 skill 的编排。它定义了多个 skill 按什么顺序执行、哪些可以并行、哪一步失败要回滚。比如一个“新增 API 端点”的 workflow，可能是：先读现有路由结构 → 生成 handler 骨架 → 补全类型 → 写测试 → 跑 lint。workflow 是这套框架真正产生价值的地方，因为它把“老手的经验”固化成了可执行的流程。

Agent是执行载体。Claude Code、Codex CLI 这些工具扮演的就是 agent 的角色，它们负责实际调用模型、执行终端命令、读写文件。superpowers 不关心你用哪个 agent，它关心的是 skill 和 workflow 怎么定义。这也是为什么它能同时适配 Claude Code 和 Codex CLI——框架层和执行层是解耦的。

三者关系可以用一句话概括：agent 提供能力，skill 封装能力，workflow 组织能力。理解了这层，后面所有的配置和操作都会顺很多。

2.3 为什么选择 Claude Code 和 Codex CLI 作为主要载体

市面上能跑 agentic workflow 的工具不少，但 superpowers 社区里讨论最多的还是 Claude Code 和 Codex CLI。这不是偶然。

Claude Code 的优势在于终端原生和文件系统操作能力强。它直接在终端里跑，能读写项目文件、执行命令、看 git 状态，这些能力对 workflow 落地至关重要。而且它的 skill 机制相对开放，你可以用自然语言描述复杂的多步任务，它会自己规划执行路径。对于需要频繁和代码库交互的场景，Claude Code 的体验是目前比较顺的。

Codex CLI 的优势在于命令体系清晰和可脚本化程度高。它的/compact、/model、/resume这些命令，让会话管理变得很可控。特别是/compact，能在上下文快满的时候压缩历史，这对长 workflow 特别有用。另外 Codex CLI 对本地模型的支持相对友好，想接 LM Studio 跑本地模型的话，配置起来比 Claude Code 省事。

两者不是二选一的关系。我的实际做法是：探索性、需要大量文件操作的任务用 Claude Code；流程固定、需要反复执行的任务用 Codex CLI。superpowers 的 skill 定义是通用的，换载体不用重写。

3. 核心细节解析与实操要点

3.1 Claude Code 安装配置全流程

Claude Code 的安装，不同系统差别不小，我按平台分开说，顺便把常见的坑标出来。

macOS 安装相对最省心。官方推荐的方式是通过包管理器安装，装完之后在终端直接敲命令就能启动。需要注意的是，第一次启动会引导你登录账号，如果你所在的环境访问受限，可能会遇到提示说服务在当前地区不可用。这种情况通常和账号注册地、网络环境有关，建议先确认账号状态是否正常。

Ubuntu 安装要稍微注意权限问题。如果你用普通用户安装，可能会在全局命令链接那一步失败，需要加 sudo 或者配置用户级的 bin 目录。我一般建议直接用用户级安装，避免污染系统环境。装完之后记得把对应的 bin 目录加到 PATH 里，不然会提示 command not found。

Windows 安装是坑最多的。最常见的一个报错是提示与 64 位版本不兼容，这通常是因为装到了 32 位的运行环境里，或者系统缺少必要的运行库。解决办法是确认系统架构、装对应版本，必要时用 WSL 来跑。说实话，Windows 上跑这类终端工具，WSL 的体验比原生好太多，我强烈建议 Windows 用户直接上 WSL。

安装完成后，验证是否成功很简单：敲一下版本命令，能正常输出版本号就说明装好了。如果报错，先看错误信息里提到的路径和权限，八成问题出在这两处。

提示：安装过程中如果遇到账号相关的限制提示，先别急着反复重装，多半不是安装本身的问题，而是账号或环境配置的问题，重装解决不了。

3.2 VS Code 接入 Claude Code 的配置要点

很多人不习惯纯终端操作，想在 VS Code 里用 Claude Code。这条路是通的，但配置有几个关键点。

首先是插件安装。在 VS Code 的扩展市场里搜对应的插件，装完之后需要配置。配置的核心是告诉插件 Claude Code 的可执行文件在哪、用哪个模型、工作目录是什么。这几项配错任何一项，插件都会连不上。

其次是工作目录的设置。这一点特别容易被忽略。如果你不指定工作目录，插件可能会用 VS Code 当前打开的文件夹，也可能用默认目录，导致 AI 读不到你想要的代码。我的习惯是每个项目单独配一个工作目录，避免跨项目串味。

再就是模型选择。VS Code 插件里可以指定用哪个模型，如果你接了第三方 API 或者本地模型，这里要填对。填错的话表现是能连上但回复很慢或者报错。

实测下来，VS Code 插件的体验和终端版有差异。终端版在文件操作和命令执行上更直接，插件版在代码补全和行内建议上更顺手。我的建议是两个都装，按场景切换：写代码时用插件，跑 workflow 时用终端。

3.3 Codex CLI 命令体系与常用操作

Codex CLI 的命令体系是它的一大亮点，几个核心命令必须掌握。

/compact是我用得最多的。当会话历史变长、上下文快满的时候，用它来压缩。压缩之后模型会保留关键信息，丢掉冗余对话，这样能继续在同一个会话里干活，不用重开。对于长 workflow，这个命令能救命。

/model用来切换模型。同一个会话里，你可能想让不同步骤用不同模型——简单任务用快模型，复杂推理用强模型。这个命令让切换变得很轻量。

/resume用来恢复之前的会话。有时候你关掉终端去干别的，回来想接着之前的进度，用它就能把上下文捞回来。这个功能对多天推进的项目特别实用。

除了这几个，还有一些辅助命令，比如查看当前状态、清理会话等。建议花十分钟把命令列表过一遍，知道有哪些能力，用的时候才不会抓瞎。

删除 Codex CLI 的指令也要知道。如果你要卸载或者清理配置，得找到对应的配置目录，手动删掉相关文件。不同系统配置目录位置不一样，macOS 和 Linux 通常在用户主目录下的隐藏文件夹里，Windows 在 AppData 里。删之前建议备份，免得误删了重要配置。

3.4 本地模型接入：以 LM Studio 为例

想省钱或者想数据不出本地，接本地模型是个好选择。以 LM Studio 为例说下流程。

第一步是在 LM Studio 里加载模型并启动本地服务。启动后它会给你一个本地地址，通常是 localhost 加一个端口。这个地址就是后面要填的 API 端点。

第二步是在 Claude Code 或 Codex CLI 里配置这个端点。你需要把 API base URL 指向本地地址，模型名填 LM Studio 里加载的那个模型的名字。有些工具还需要你填一个 API key，本地模型随便填个占位符就行。

第三步是测试连通性。发一个简单请求，看能不能正常返回。如果连不上，先检查 LM Studio 的服务是不是真的在跑，再看端口有没有被占用，最后看防火墙有没有拦。

这里有个经验：本地模型的上下文窗口通常比云端小，跑长 workflow 容易爆。所以接本地模型时，workflow 要设计得更精简，或者多用/compact压缩。另外本地模型的指令遵循能力参差不齐，skill 的约束要写得更明确，别指望它自己领会。

3.5 第三方 API 接入技巧

除了官方和本地模型，接第三方 API 也是常见需求。比如用 CC Switch 这类工具，把请求转发到 DeepSeek、Qwen、GLM 等模型上。

接入的核心是端点、密钥、模型名三件套。端点填第三方服务提供的地址，密钥填你申请到的，模型名填对方支持的模型标识。三样都对上，基本就能通。

但有几个坑要注意。第一是格式兼容性，不同服务商的 API 格式可能有细微差异，有的工具能自动适配，有的需要你手动调。第二是速率限制，第三方服务通常有 QPS 或 token 限制，workflow 跑太快会被限流，建议在 skill 里加适当的重试和退避。第三是模型能力差异，同一个 prompt 在不同模型上效果可能差很多，skill 里的约束要针对目标模型调优。

我的做法是，先用一个最小 workflow 测通链路，确认能正常调用，再逐步加复杂度。一上来就跑完整 workflow，出问题很难定位是配置问题还是模型问题。

4. 实操过程与核心环节实现

4.1 从零搭建一个最小可用 workflow

光说概念没用，我带你搭一个最小 workflow，跑通之后你就理解整套机制了。

假设我们要做一个“给现有函数补测试”的 workflow。它包含三个 skill：第一个 skill 读取目标文件，识别出没有测试覆盖的函数；第二个 skill 针对每个函数生成测试用例；第三个 skill 运行测试并报告结果。

第一步，定义 skill 的输入输出。第一个 skill 输入是文件路径，输出是函数列表。第二个 skill 输入是单个函数，输出是测试代码。第三个 skill 输入是测试文件，输出是运行结果。每个 skill 的职责单一，这样出问题容易定位。

第二步，在 Claude Code 里描述这个 workflow。你可以用自然语言把三个步骤串起来，明确每步的约束，比如“生成的测试要覆盖边界条件”“不要修改原函数”。Claude Code 会按你的描述规划执行。

第三步，跑一遍看结果。第一次跑大概率不完美，可能测试生成得不全，或者运行报错。这时候不要急着改 workflow，先看是哪一步出的问题。如果是生成质量不行，调整第二个 skill 的约束；如果是运行环境问题，检查测试框架配置。

第四步，把跑通的 workflow 固化下来。把 skill 定义和编排逻辑存成文件，下次直接复用。这就是 superpowers 框架的价值——一次调优，长期复用。

4.2 参数选择与上下文管理

workflow 跑得好不好，上下文管理占一半功劳。这里说几个关键参数。

上下文窗口大小决定了你一次能塞多少信息。云端模型通常窗口大，本地模型窗口小。设计 workflow 时，要估算每一步大概消耗多少 token。一个粗略的经验是，读一个中等大小的源文件大概几千 token，生成测试又是几千，跑几轮就上万了。窗口不够就得靠/compact或者拆分 workflow。

温度参数影响输出的随机性。生成代码时温度别太高，不然会冒出奇怪的写法；做头脑风暴时可以调高一点。不同工具设置温度的方式不一样，有的在配置文件里，有的在命令参数里。

最大输出长度要设合理。设太短，生成的代码被截断；设太长，浪费 token 还可能跑偏。一般按任务复杂度设，简单任务几千，复杂任务上万。

我踩过的一个坑是：没控制好上下文，导致 workflow 跑到一半模型开始胡言乱语。后来学乖了，在每个 skill 之间加一个检查点，确认上一步输出合理再继续，不合理就压缩或者重来。

4.3 让 AI 直接执行终端命令的注意事项

Claude Code 和 Codex CLI 都能直接执行终端命令，这个能力很强大，但也很危险。

强大的地方在于，workflow 可以真正闭环。比如生成代码之后直接跑测试、跑 lint、跑构建，不用你手动复制命令。这让自动化程度大幅提升。

危险的地方在于，AI 可能执行你不想执行的命令。比如它可能误删文件、误改配置、跑一个耗时很长的任务。所以权限控制必须做好。

我的做法是分三级。第一级是只读操作，随便跑。第二级是写操作但限定在项目目录内，允许但要有日志。第三级是系统级操作，比如装包、改全局配置，必须手动确认。Claude Code 和 Codex CLI 都支持某种形式的确认机制，一定要开启。

另外，在 workflow 里执行命令要加超时。有些命令可能卡住，没有超时的话整个 workflow 就挂那了。设个合理的超时，超了就跳过或者报错，别让它无限等。

4.4 飞书等协作工具与 workflow 的衔接

团队协作场景下，把 workflow 和飞书这类工具连起来，能省不少事。

思路是这样的：workflow 跑完之后，把结果推送到飞书群或者文档里。比如代码审查 workflow 跑完，把发现的问题整理成消息发到群里；或者测试 workflow 跑完，把报告写进飞书文档。

实现方式通常是调用飞书的开放接口。你需要在飞书那边创建一个应用，拿到凭证，然后在 workflow 的最后一步加一个 skill，负责把结果格式化并发送。这一步的关键是结果格式化，要让消息在飞书里读起来清晰，别一股脑把原始输出扔过去。

我实际用下来，这个衔接对团队效率提升明显。以前代码审查结果要人工整理转发，现在自动就推送到位了。但要注意别推送太频繁，不然会变成骚扰。建议按需触发，或者做每日汇总。

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

5.1 安装与登录类问题速查

这张表是我自己踩坑总结的，基本覆盖了安装阶段八成的问题。遇到报错先对号入座，能省很多瞎折腾的时间。

5.2 模型调用与响应异常排查

模型调用出问题，表现通常是：连不上、响应慢、输出乱、中途断。

连不上先查网络和端点配置。响应慢先看是不是模型太大或者上下文太长。输出乱通常是 prompt 或温度的问题。中途断多半是上下文超限或者超时。

我遇到过一个比较隐蔽的问题：第三方 API 返回格式和工具预期不一致，导致解析失败。表现是能连上但一直报错。解决办法是抓一下原始返回，对比工具文档里说的格式，看差在哪。有时候是字段名不一样，有时候是嵌套结构不同，改配置或者加一层转换就行。

还有一个常见问题是模型不遵循 skill 约束。这在小模型上特别明显。解决办法是把约束写得更硬，用明确的祈使句，别用“建议”“最好”这种软词。必要时在 skill 里加校验步骤，输出不符合就重来。

5.3 上下文超限与性能优化

上下文超限是长 workflow 的头号杀手。症状是跑到一半模型开始重复、遗忘或者报错。

应对手段有几个。最直接的是/compact压缩。其次是拆分 workflow，把一个大流程拆成几个小流程，每个跑完存结果，下一个读结果继续。再就是精简 skill 的输入，别把整个文件都塞进去，只给相关片段。

性能优化方面，并行化是个好思路。workflow 里没有依赖关系的 skill 可以并行跑，省时间。比如同时生成多个模块的测试，没必要串行。但并行要注意资源竞争，别同时写同一个文件。

另外，缓存中间结果能省很多重复计算。比如读文件解析出的结构，存下来给后续 skill 用，别每次都重新读。

5.4 独家避坑经验

说几个文档里不会写、但实际很要命的坑。

第一个坑：别在 workflow 里跑交互式命令。有些命令会等你输入，AI 不知道要输入什么，就卡住了。跑之前确认命令是非交互的，或者用参数跳过交互。

第二个坑：文件路径用绝对路径。相对路径在不同工作目录下会解析成不同结果，AI 很容易搞混。统一用绝对路径，省心。

第三个坑：git 状态要干净再跑 workflow。如果工作区有未提交的改动，AI 改完文件之后你分不清哪些是它改的、哪些是你之前改的。跑之前先 commit 或者 stash。

第四个坑：别让 AI 碰敏感文件。比如密钥文件、生产配置，在 workflow 里明确排除。一旦被误改，后果可能很严重。

第五个坑：定期备份 skill 定义。调好的 workflow 是资产，丢了要重来。存到 git 里，或者至少定期导出。

6. 框架的延展玩法与个人体会

superpowers 这套 agentic skills framework 真正有意思的地方，是它能延展出很多玩法。

比如你可以把常用的代码审查规则做成 skill 库，团队共享。新人提交代码，自动跑一遍审查 workflow，把常见问题挡在人工审查之前。再比如你可以把部署流程做成 workflow，从构建到测试到发布一条龙，减少手动操作出错。

我还见过有人把 remotion 这类视频生成工具接进 workflow，用 AI 生成脚本、生成素材、渲染视频，整个流程自动化。这说明这套框架的边界不限于写代码，任何有明确步骤的任务都能往里套。

我个人的体会是，这套框架最大的价值不是省了多少时间，而是把经验沉淀下来了。以前老手的开发习惯只存在脑子里，现在能写成 skill 和 workflow，让整个团队受益。新人上手快，老人也不用反复解释。

当然，它也不是银弹。workflow 设计得好不好，直接决定效果。设计得糙，还不如手动干。所以前期投入时间打磨 skill 是值得的，别指望随便写写就能跑出好结果。

最后分享一个小技巧：从最小的 workflow 开始，跑通了再加复杂度。我见过太多人一上来就想搭个大而全的流程，结果处处报错，最后放弃。先用两三个 skill 跑通一个简单任务，建立信心，再逐步扩展。这个节奏最稳。

另外，社区里关于 Claude Code 和 Codex CLI 的讨论一直在更新，命令和配置可能会变。遇到问题先查官方文档，再看社区讨论，别死磕过时的教程。工具在进化，用法也得跟着更新。