1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区和效率工具圈子里被反复提起很多人第一次看到它是在某个开源项目的讨论区或者是在朋友转发的一条“效率翻倍”的分享里。简单来说superpowers 是一套面向 AI 编程助手的能力扩展框架它的核心思路是把零散的提示词、工作流和工具调用整合成一套可复用、可组合的“技能包”让 AI 助手在处理复杂任务时不再只是“一问一答”而是能像一位有经验的工程师那样按步骤、有章法地推进工作。我第一次接触这个概念的时候其实有点懵——市面上各种“增强插件”“提示词库”已经够多了为什么还要再搞一套后来实际用了一段时间才明白superpowers 解决的不是“AI 能不能回答问题”而是“AI 能不能稳定地、可预期地完成一件多步骤的事”。比如你要让 AI 帮你重构一个模块普通对话模式下它可能给你一段看起来不错的代码但缺少上下文校验、缺少边界处理、缺少回滚方案而 superpowers 的思路是把这类任务拆成“分析现状→制定方案→分步执行→验证结果”这样的技能链每一步都有明确的输入输出约束。这篇文章适合几类人看一是已经在用 AI 编程助手、但觉得“它总是差一口气”的开发者二是想搭建自己团队内部 AI 工作流的技术负责人三是对“提示词工程”已经审美疲劳、想看看更工程化做法的效率工具爱好者。我会从设计思路、核心机制、安装配置、实操流程、常见坑几个角度把 superpowers 这套东西掰开揉碎讲清楚尽量让你看完就能上手试。需要提前说明的是superpowers 本身是一个相对年轻的生态不同版本、不同宿主环境下的表现会有差异。我下面提到的具体命令和配置是基于我实际跑通的一套环境总结出来的你在自己机器上操作时如果遇到版本不匹配优先去看对应项目的 README 和 issue 区那是最准的。2. 核心设计思路拆解为什么不是又一个提示词库2.1 从“提示词”到“技能”的思维转变大多数人用 AI 助手的习惯是遇到问题→写一段提示词→拿到结果→不满意→改提示词→再试。这个循环在简单任务上没问题但一旦任务变复杂提示词就会膨胀成几百字甚至上千字的“小作文”而且每次都要重新组织复用性极差。superpowers 的第一个设计选择就是把提示词从“一次性文本”升级为“可持久化的技能单元”。一个技能单元通常包含几个部分触发条件什么情况下该用这个技能、执行步骤分几步做、每步做什么、约束规则不能做什么、必须检查什么、输出格式结果长什么样。这四块合在一起就形成了一个自包含的“能力模块”。你可以把它理解成给 AI 助手写的一份“标准作业程序”而不是一段随用随弃的对话。这个转变带来的直接好处是当你第二次遇到同类任务时不需要重新描述一遍需求直接调用对应技能就行。而且因为约束规则是写死的AI 的输出稳定性会明显提升——它不会今天给你一个方案、明天给你另一个完全不同的方案。2.2 组合优于堆砌技能链的编排逻辑单个技能能解决的问题有限superpowers 真正有意思的地方在于技能可以组合成链。比如“重构一个函数”这个任务可以拆成代码理解技能→风险评估技能→重构执行技能→测试验证技能。每个技能负责一段前一个的输出是后一个的输入形成一条流水线。这种设计和传统“写一个超长提示词让 AI 一次搞定”相比优势在哪我总结下来主要是三点。第一是可调试性如果最终结果不对你可以定位到是哪个环节出了问题而不是面对一个黑盒干瞪眼。第二是可替换性如果某个环节你有更好的实现直接换掉那个技能就行不影响其他部分。第三是可积累性你每解决一类新问题就沉淀一个新技能时间越长这套东西越好用。提示技能链不是越长越好。我见过有人把简单任务拆成七八步结果每步之间的上下文传递损耗比收益还大。一般来说单个任务拆成三到五步是比较舒服的区间。2.3 和主流方案的区别它不绑定特定模型市面上不少效率框架是绑定特定模型或特定平台的换一个环境就废了。superpowers 在设计上刻意保持了模型无关性——它的技能定义是纯文本加结构化标记理论上任何支持函数调用或工具调用的 AI 助手都能跑。这一点对团队协作很重要因为你不希望自己辛苦积累的技能库因为换了工具就全部作废。当然模型无关也意味着它不能利用某些模型的独有特性这是一个取舍。我的建议是如果你只是个人用选一个顺手的模型就行如果是团队用优先考虑可迁移性别把宝押在单一平台上。3. 核心机制与关键概念详解3.1 技能文件的结构长什么样一个典型的技能文件本质上是一个带有元信息的 Markdown 或 YAML 文档。我拿一个“代码审查”技能举例它的结构大概是这样name: code-review trigger: 当用户要求审查一段代码时 steps: - 读取代码并识别语言与框架 - 检查命名规范与代码风格 - 检查边界条件与异常处理 - 检查性能敏感点 - 输出分级问题列表 constraints: - 不直接修改代码只给建议 - 每个问题必须给出具体行号 output: 按严重程度分级的 Markdown 列表这个结构看起来简单但每个字段都有讲究。trigger决定了技能什么时候被激活写得太宽会导致误触发写得太窄又会在需要时用不上。steps是执行骨架但不要写成死板的指令要给 AI 留出根据实际情况调整的空间。constraints是最容易被忽略但最重要的部分它决定了输出的下限。3.2 上下文传递技能链最容易翻车的地方技能链跑起来之后前一个技能的输出怎么传给后一个技能这是整个框架里最微妙的部分。如果传递的信息太多后面的技能会被噪音干扰如果传递太少又会丢失关键上下文。我的经验是只传结论和必要数据不传中间过程。举个例子在“分析→重构→验证”这条链里分析技能的输出应该是一份精简的问题清单和重构建议而不是它分析时读过的所有代码。重构技能拿到这份清单后自己去读相关代码。这样每个技能都只关注自己该关注的信息整体效率反而更高。注意如果你的技能链里出现“后一个技能抱怨信息不足”的情况先别急着加传递内容而是检查前一个技能的输出格式是不是太啰嗦了。十有八九是噪音太多把关键信息淹没了。3.3 触发机制手动调用还是自动匹配superpowers 支持两种触发方式手动指定和自动匹配。手动就是你明确告诉助手“用某某技能来处理这个任务”自动则是助手根据当前上下文判断该用哪个技能。两种方式各有适用场景。手动触发适合结果要求高、不容出错的任务比如生产环境的配置修改。自动匹配适合探索性、重复性的任务比如日常的代码格式化建议。我个人的习惯是涉及写操作的一律手动涉及读操作和生成建议的可以自动。自动匹配的准确率取决于技能描述的清晰度。如果你发现助手总是匹配错技能八成是几个技能的trigger描述有重叠。这时候要么把描述写得更具体要么干脆合并成一个技能。4. 安装与配置实操从零跑通一套环境4.1 环境准备与前置检查在动手安装之前先确认你的基础环境。superpowers 本身通常是以插件或扩展的形式挂载在某个 AI 助手宿主上的所以你需要先有一个能正常工作的助手环境。我建议的准备清单如下一个支持工具调用或函数调用的 AI 助手客户端本地有可写的配置目录用来放技能文件基础的命令行操作能力会用 cd、ls、cat 这类命令如果涉及代码任务本地要有对应的运行时和测试框架检查环境是否就绪可以跑一个最小验证让助手执行一个简单的两步任务看它能不能正确调用工具。如果这一步就出问题先别急着装 superpowers把基础环境修好再说。4.2 安装步骤与目录结构规划安装过程本身通常不复杂难的是目录结构怎么规划。我踩过的坑是一开始把所有技能文件都堆在一个目录里结果技能一多就乱成一锅粥找起来费劲还容易命名冲突。后来改成按领域分目录清爽很多。推荐的目录结构是这样的superpowers/ ├── skills/ │ ├── coding/ # 编码相关技能 │ ├── writing/ # 写作相关技能 │ ├── analysis/ # 分析相关技能 │ └── ops/ # 运维相关技能 ├── chains/ # 技能链定义 ├── config.yaml # 全局配置 └── logs/ # 执行日志分目录的好处不只是好找更重要的是可以按目录批量启用或禁用。比如你在做写作任务时可以把 coding 目录整个禁掉减少误触发。安装命令本身根据宿主不同会有差异常见的是通过包管理器安装或者直接把仓库克隆到配置目录。我建议第一次装的时候先用最小配置跑通别一上来就把所有技能都启用那样出了问题很难定位。4.3 配置文件的关键参数说明配置文件里有几个参数值得单独说。第一个是max_chain_depth控制技能链的最大深度默认值通常是 5。这个值设太小会导致复杂任务跑不完设太大又可能陷入无限循环。我的建议是设在 4 到 6 之间根据你的任务复杂度调整。第二个是context_window_budget控制每个技能能用的上下文预算。这个参数直接影响到技能链能不能跑通——如果预算太小后面的技能拿不到足够信息预算太大又浪费资源。一个粗略的估算方法是把整条链上所有技能的输出长度加起来再乘以 1.5 的安全系数。第三个是retry_policy定义某个技能执行失败后的重试策略。默认可能是重试两次但对于写操作类的技能我建议把重试次数设为 0失败就停下来人工介入避免重复写入造成数据损坏。# config.yaml 示例 max_chain_depth: 5 context_window_budget: 8000 retry_policy: read_ops: 2 write_ops: 0 logging: level: info path: ./logs/5. 完整实操流程用 superpowers 完成一次代码重构5.1 任务定义与技能链设计假设我们要重构一个 Python 模块里的一个函数这个函数目前逻辑混乱、缺少异常处理、命名也不规范。用 superpowers 的做法第一步不是直接让 AI 改代码而是先设计技能链。我设计的链是这样的code-analyze→refactor-plan→refactor-execute→test-verify。四个技能各司其职。code-analyze负责读懂现有代码并列出问题refactor-plan根据问题清单制定重构方案refactor-execute执行实际修改test-verify跑测试并确认行为一致。为什么要在分析和执行之间加一个“制定方案”的环节因为直接让 AI 从“发现问题”跳到“改代码”它很容易改着改着就跑偏了改出一些你没要求的东西。中间加一层方案确认相当于给它划了一条轨道。5.2 分步执行与中间结果检查链跑起来之后每个技能执行完都会产出一个中间结果。我的习惯是在每个中间结果处停一下人工扫一眼。虽然这会降低自动化程度但对于重要任务这个检查成本是值得的。code-analyze的输出通常是一份问题列表格式类似问题类型位置严重程度说明命名不规范第 12 行中变量名d含义不明缺少异常处理第 20-25 行高文件读取未捕获 IOError逻辑冗余第 30-35 行低重复的条件判断看到这份列表你就能判断分析技能有没有认真干活。如果它只列了一两条无关痛痒的问题说明触发条件或者约束规则需要调整。refactor-plan的输出应该是一份可执行的修改计划包含改哪些地方、怎么改、预期效果。这一步如果方案不合理直接打回去重跑别让它带着错误方案进入执行阶段。5.3 验证环节与回滚准备refactor-execute执行完之后test-verify会跑测试。这里有个关键点测试用例必须提前准备好不能等改完再想怎么测。如果原项目没有测试那在重构之前先补几个覆盖核心行为的测试这是铁律。回滚准备同样重要。在执行任何写操作之前确保代码在版本控制里或者至少有一份备份。我见过有人直接在生产代码上跑重构技能结果改崩了又没有备份只能凭记忆往回改那场面相当难受。提示如果你的技能链涉及文件写入建议在refactor-execute技能里加一条约束——“每次修改前先创建备份文件命名规则为原文件名加 .bak 后缀”。这条约束看起来笨但关键时刻能救命。6. 常见问题与排查技巧实录6.1 技能不触发或触发错误这是最常见的问题表现是助手该用技能的时候不用不该用的时候乱用。排查思路分三步走。第一步检查trigger描述是否和当前任务匹配有时候你写的描述太学术化助手理解不了。第二步看是不是有多个技能的触发条件重叠了导致助手不知道该选哪个。第三步确认技能文件有没有被正确加载有些宿主需要重启才能识别新技能。我遇到过一次特别隐蔽的情况技能文件里有个不起眼的语法错误导致整个文件被静默跳过助手一直用的是默认行为。后来养成习惯每次加完新技能先手动触发一次确认它能跑。6.2 技能链中途断掉链跑到一半停了通常有几个原因。一是某个技能的输出格式不符合下一个技能的输入要求导致解析失败。二是上下文预算用完了后面的技能拿不到必要信息。三是某个技能触发了约束规则里的禁止条件主动中止了。排查的时候先看日志里最后一个成功执行的技能是哪个然后检查它的输出。如果输出格式没问题再看上下文预算的使用情况。我一般会在配置里把日志级别调到 debug这样能看到每个技能实际消耗了多少上下文。6.3 输出质量不稳定同一个技能有时候输出很好有时候一塌糊涂。这种波动通常来自两个地方一是模型本身的随机性二是上下文里混入了无关信息。对于前者可以在技能定义里加一条“输出前先自检”的步骤让助手自己过一遍。对于后者要检查技能链上游有没有传递冗余信息。还有一个容易被忽略的点技能定义里的示例。如果你在技能里放了示例输出助手会倾向于模仿示例的风格和详细程度。示例写得太简略输出就会偏简略示例写得太啰嗦输出就会啰嗦。所以示例要精心挑选代表你想要的“标准水平”。6.4 常见问题速查表现象可能原因排查动作技能完全不触发文件未加载/语法错误检查日志手动触发测试触发但输出为空约束条件过严放宽 constraints逐步收紧链中途停止上下文预算不足调大 budget 或精简上游输出输出格式错乱下游技能解析失败检查上游输出格式是否符合约定重复执行同一技能触发条件重叠合并或细化 trigger 描述写操作失败权限或路径问题检查文件权限和目录是否存在7. 进阶玩法把 superpowers 用出复利效应7.1 技能库的版本管理当你积累了几十个技能之后版本管理就变得重要了。我的做法是把技能库当成代码库来管用 Git 做版本控制每次修改都写清楚改了什么、为什么改。这样当某个技能改坏了可以快速回滚当你想知道某个技能为什么长这样翻提交记录就行。分支策略上我建议主分支只放经过验证的稳定技能新技能先在开发分支上跑一段时间确认没问题再合并。如果团队多人共用技能库还要约定好命名规范避免两个人写了功能重复的技能。7.2 团队协作中的技能共享团队场景下技能共享能带来很大的效率提升但也会带来一些问题。最大的问题是上下文差异——同一个技能在你机器上跑得好在同事机器上可能因为环境不同而失败。解决办法是在技能定义里明确声明依赖项比如需要哪些工具、哪些环境变量、哪些目录结构。另一个问题是技能的所有权。一个技能被多人修改后很容易变得面目全非。我的建议是每个技能指定一个负责人其他人提修改建议而不是直接改。这个规则听起来有点官僚但在技能数量多了之后能省掉很多扯皮。7.3 从单点技能到领域工作流superpowers 真正发挥威力是在你把某个领域的完整工作流都技能化之后。比如“发布一个新版本”这件事可以拆成版本号更新→变更日志生成→构建→测试→打包→发布→通知。每个环节一个技能串起来就是一条自动化流水线。这种领域工作流的价值在于一致性。不管是谁来执行发布走的都是同一套流程不会因为某个人忘了某一步而出问题。而且当流程需要调整时改一个技能就行所有使用这条流水线的人都自动受益。我个人的体会是从单点技能到领域工作流中间有一个明显的门槛你需要对那个领域的流程有足够清晰的理解才能把它拆成合理的技能。如果流程本身是混乱的技能化只会把混乱固化下来。所以动手之前先把流程理清楚。8. 我踩过的坑和几条实在建议第一个坑是过度设计。刚开始用的时候我恨不得把每个操作都拆成技能结果技能数量爆炸维护成本比收益还高。后来想明白了只有那些重复出现、步骤明确、容易出错的任务才值得技能化。一次性的任务直接对话解决就行。第二个坑是忽视约束规则。我早期写的技能constraints部分基本是空的觉得“让 AI 自由发挥更好”。结果就是输出质量忽高忽低完全不可控。后来把约束规则补上虽然输出变得“保守”了一些但稳定性大幅提升。对于工程类任务稳定比惊艳重要得多。第三个坑是不做测试就上生产。这个不用多说了任何自动化流程在正式使用前都要在测试环境跑够足够的次数。我现在的习惯是新技能至少跑通十次不同场景才敢放到日常使用里。最后分享一个小技巧给技能写“使用说明”。不是给 AI 看的是给人看的。每个技能文件开头加一段注释说明这个技能适合什么场景、有什么已知限制、最近一次验证是什么时候。过几个月再回来看这段注释能帮你快速回忆起这个技能是干嘛的省掉大量重新理解的时间。这套东西说到底核心不是技术而是把经验沉淀下来的习惯。你每解决一个问题就多想一步“这个解法能不能复用”慢慢积累superpowers 才会真的变成你的“超能力”。
)
