企业官网建设流程全解析

1. 从“superpowers”说起：一套让编码智能体真正长出“技能树”的方法论

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者某个性能优化库。但如果你最近在折腾编码智能体（coding agents），大概率已经在各种讨论里撞见过它——它其实是一套围绕agentic skills framework构建的软件开发方法论，核心思路是把智能体需要的能力拆成一个个可组合、可复用、可独立加载的“技能”（skills），再通过一套约定把它们拼装起来，让智能体在面对具体任务时能像人一样“调用技能”而不是“硬编码流程”。

我接触这套东西的起因很朴素：手头有几个基于大模型的编码助手，单个任务跑得还行，一旦任务链条变长——比如“读需求→改代码→跑测试→修 bug→写变更说明”——就开始掉链子。要么上下文爆炸，要么中间步骤丢失，要么同一个错误反复犯。后来发现问题的根子不在模型本身，而在于我把所有能力都塞进了一个巨大的提示词里，没有做能力分层。superpowers 这套框架解决的正是这个问题：它把“技能”当成一等公民，每个技能是一个自包含的单元，有明确的触发条件、输入输出和执行边界，智能体在运行时按需加载，而不是一次性把所有知识灌进去。

这篇文章适合三类人看：一是正在用编码智能体做实际项目、但被长链条任务折磨的开发者；二是想给自己团队搭一套智能体协作规范的技术负责人；三是对composable skills这个概念感兴趣、想搞清楚“技能到底怎么组合、怎么引入、怎么安装”的探索者。我会从整体设计思路讲到具体实操，包括技能目录结构、加载机制、组合方式、常见坑和排查技巧，尽量把每一步的“为什么”讲透，让你看完能直接照着搭一套自己的技能框架。

需要先说明一点：superpowers 本身不是一个具体的软件包，它更像一套约定和参考实现。不同团队落地时细节会有差异，下面涉及的具体目录名、配置字段、加载顺序，都是基于社区常见实践和我自己踩坑后总结的合理方案，你可以按自己项目的实际情况调整。

2. 整体设计思路：为什么要把能力拆成“技能”而不是写死流程

2.1 从“一个大提示词”到“技能树”的转变逻辑

早期做编码智能体，最直觉的做法是写一个超长的系统提示词，把编码规范、项目结构、常用命令、注意事项全塞进去。我试过，一开始效果确实不错，模型能记住不少上下文。但项目一复杂就崩了：提示词超过一定长度后，模型对中间部分的注意力明显下降，而且每次任务都要重新加载全部内容，token 成本高得离谱。更麻烦的是，不同任务需要的知识其实不一样——改前端组件和写数据库迁移脚本，需要的上下文几乎不重叠，但大提示词方案强迫它们共享同一份“知识包”。

superpowers 的思路是把这些知识按“能力”切分。一个技能就是一个文件夹，里面包含这个能力的说明、触发条件、执行步骤、示例和边界。智能体在接到任务时，先做一次“技能匹配”，判断当前任务需要哪些技能，然后只加载这些技能的内容。这样做的好处很直接：上下文更聚焦，token 消耗更可控，而且技能可以独立迭代——改一个技能的说明不会影响其他技能。

提示：技能拆分粒度是个关键决策。拆得太粗，等于没拆；拆得太细，匹配和组合的开销会吃掉收益。我的经验是，一个技能对应“一个可独立完成的小任务”，比如“运行单元测试并解析失败用例”就是一个合适的粒度，而“写代码”就太粗，“解析 pytest 输出中的 assertion 行”又太细。

2.2 技能的可组合性到底意味着什么

composable skills这个词听起来抽象，落到实操上其实就三件事：技能可以串联、可以嵌套、可以条件触发。串联是指一个技能的输出可以作为另一个技能的输入，比如“定位失败测试”技能输出失败用例列表，“修复失败用例”技能接收这个列表并逐个处理。嵌套是指一个技能内部可以调用其他技能，比如“提交代码”技能内部会调用“生成变更说明”技能。条件触发是指技能可以根据运行时状态决定是否激活，比如“回滚变更”技能只在检测到测试连续失败三次时才触发。

这种组合能力带来的最大价值是“流程可编排但不写死”。传统做法是把流程硬编码在代码里，改流程就要改代码。superpowers 的做法是把流程描述成技能之间的依赖关系，智能体在运行时动态解析。我实测下来，这种方式在应对需求变化时优势明显——加一个新步骤只需要新增一个技能并调整依赖声明，不用动核心逻辑。

2.3 和传统工作流引擎的区别在哪

有人会问，这不就是工作流引擎干的事吗？区别在于“决策权在谁手里”。传统工作流引擎的流程是预先定义好的，每一步走哪条分支由规则决定。superpowers 框架里，技能的选择和组合很大程度上交给智能体自己判断——它根据任务描述和当前上下文，从技能库里挑选合适的技能。这意味着流程有一定的“涌现性”，能处理预先没想到的情况，但代价是可控性下降。我的做法是混合：核心流程用显式依赖声明固定下来，边缘情况留给智能体自主判断，同时在技能说明里写清楚“什么情况下不要用这个技能”。

3. 核心细节解析：技能目录、加载机制与组合规则

3.1 一个标准技能目录应该包含什么

技能目录结构没有强制标准，但社区里比较通行的做法是每个技能一个文件夹，里面至少包含这几个文件：

• SKILL.md：技能的主说明文件，写清楚这个技能做什么、什么时候用、怎么用、有什么限制。
• examples/：示例目录，放几个典型输入输出，帮助智能体理解预期行为。
• scripts/：可执行脚本目录，如果技能需要跑命令或调工具，脚本放这里。
• config.yaml：技能级配置，比如超时时间、重试次数、依赖的其他技能。

SKILL.md的写法很关键。我见过不少人把它写成散文，结果智能体匹配时抓不住重点。比较有效的写法是用固定小节：## 用途、## 触发条件、## 输入、## 输出、## 步骤、## 限制。触发条件那一节尤其重要，要写清楚“当任务描述包含哪些关键词或满足哪些条件时应该加载这个技能”，这直接决定了技能匹配的准确率。

注意：SKILL.md里不要写太泛的描述，比如“用于处理代码相关任务”。这种描述会让技能匹配变得模糊，导致该加载的没加载、不该加载的乱加载。尽量用具体的动词和名词，比如“当需要解析 JUnit 测试报告并提取失败用例名称时使用”。

3.2 技能加载的三种模式与选择依据

技能加载模式直接影响到智能体的响应速度和准确性。我总结下来有三种常见模式：

我自己的项目用的是分层加载：维护一个skills-index.yaml，里面只放每个技能的名称、一句话描述和关键词标签。智能体先读索引，判断需要哪些技能，再去加载对应的SKILL.md。这样做的好处是索引文件很小，可以常驻上下文，而详情文件只在需要时加载。实测下来，技能数量到 50 个以上时，分层加载的优势非常明显。

3.3 技能组合的依赖声明与冲突处理

技能之间的依赖关系需要在config.yaml里声明。比如“修复失败用例”技能依赖“定位失败测试”技能，就要写depends_on: [locate-failed-tests]。智能体在加载技能时会自动解析依赖，把被依赖的技能也加载进来。

冲突处理是个容易被忽略的点。两个技能可能对同一个资源有互斥的操作，比如一个技能要“重置数据库”，另一个要“保留数据库状态”。我的做法是在技能配置里加一个exclusive_group字段，同一组里的技能不能同时激活。如果智能体判断需要同时激活两个互斥技能，就触发一个“冲突解决”流程，通常是让智能体根据任务优先级选择一个，或者提示人工介入。

提示：依赖声明不要写得太深。我见过依赖链长达五六层的技能组合，调试起来非常痛苦。建议依赖深度控制在三层以内，超过三层就考虑把中间层合并成一个技能。

4. 实操过程：从零搭建一套可用的技能框架

4.1 环境准备与基础目录搭建

先确定你的项目根目录，然后在下面建一个skills/文件夹。我习惯再分一层类别目录，比如skills/coding/、skills/testing/、skills/review/，这样索引文件可以按类别组织，查找起来更快。每个技能一个子文件夹，命名用短横线连接的小写英文，比如run-unit-tests、parse-test-report。

基础目录结构大概长这样：

project-root/ ├── skills/ │ ├── skills-index.yaml │ ├── coding/ │ │ ├── apply-patch/ │ │ │ ├── SKILL.md │ │ │ ├── config.yaml │ │ │ └── examples/ │ │ └── refactor-function/ │ ├── testing/ │ │ ├── run-unit-tests/ │ │ └── parse-test-report/ │ └── review/ │ └── generate-changelog/ └── agent-config.yaml

agent-config.yaml里配置技能库路径、加载模式、默认超时等全局参数。这个文件不要写太复杂，保持可读性。

4.2 编写第一个技能：以“运行单元测试”为例

拿run-unit-tests这个技能举例。SKILL.md可以这样写：

## 用途 在当前项目根目录下运行单元测试，并返回结构化的测试结果摘要。 ## 触发条件 当任务需要验证代码变更、检查测试通过率、或需要获取测试失败列表时加载。 ## 输入 - 测试命令（可选，默认从项目配置中读取） - 测试范围（可选，默认全部） ## 输出 - 通过数、失败数、跳过数 - 失败用例列表（含文件路径和行号） - 原始输出日志路径 ## 步骤 1. 读取项目配置，确定测试命令。 2. 在项目根目录执行测试命令，设置超时时间为 300 秒。 3. 解析输出，提取通过/失败/跳过统计。 4. 如果有失败用例，提取失败详情并写入 `test-failures.json`。 5. 返回结构化结果。 ## 限制 - 不负责修复失败用例，只负责运行和报告。 - 如果测试命令不存在或执行超时，返回明确错误信息。

config.yaml里声明超时和依赖：

timeout: 300 depends_on: [] exclusive_group: test-execution

这个技能本身不依赖其他技能，但和“重置测试数据库”技能互斥，所以放在同一个exclusive_group里。

4.3 技能匹配逻辑的实现要点

技能匹配是整套框架里最需要调优的部分。我的实现思路是两阶段：先用关键词做粗筛，再用语义相似度做精排。粗筛阶段，把任务描述分词后和技能索引里的关键词标签做交集，得到候选技能列表。精排阶段，用一个小型嵌入模型计算任务描述和候选技能描述的相似度，取 top-k。

这里有个坑：关键词标签不要写太多，否则粗筛会漏掉真正相关的技能。我的经验是每个技能 3 到 5 个标签比较合适，覆盖主要触发场景即可。另外，任务描述里经常出现同义词，比如“测试”和“用例”、“验证”和“检查”，可以在匹配前做一次同义词归一化，能明显提升召回率。

注意：匹配阈值不要设得太高。我一开始把相似度阈值设到 0.8，结果很多该加载的技能没加载，智能体频繁报“没有可用技能”。后来降到 0.6，配合人工审核日志，效果好了很多。阈值这个东西没有万能值，建议先用一批真实任务跑一遍，看匹配日志再调。

4.4 把技能串起来：一个完整的任务执行流程

假设任务描述是“修复登录模块的失败测试”。智能体的执行流程大概是这样：

1. 读取skills-index.yaml，粗筛出候选技能：run-unit-tests、parse-test-report、locate-failed-tests、apply-patch。
2. 精排后确定需要加载的技能集合，按依赖关系排序。
3. 加载run-unit-tests，执行测试，得到失败列表。
4. 加载parse-test-report，解析失败详情，定位到具体文件和行号。
5. 加载apply-patch，根据失败信息生成修复补丁并应用。
6. 再次运行run-unit-tests验证修复。
7. 如果仍然失败，触发重试逻辑，最多三次；三次后仍失败则输出诊断报告。

这个流程里，每个技能只关心自己的输入输出，不关心上游是谁调用的。这种解耦让技能可以独立测试和替换。比如后来我把apply-patch换成了一个更智能的版本，其他技能完全不用改。

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

5.1 技能加载失败或匹配不到怎么办

这是最常见的问题，表现是智能体说“没有找到相关技能”或者加载了错误的技能。排查顺序建议这样：

• 先看skills-index.yaml里有没有这个技能，关键词标签是否覆盖了任务描述里的核心词。
• 再看SKILL.md的触发条件是否写得太窄，比如只写了“当任务描述包含‘单元测试’时”，但实际任务描述用的是“跑一下测试”。
• 然后检查匹配阈值，临时调低看是否能匹配上。
• 最后看技能目录权限和文件编码，我遇到过一次因为SKILL.md存成了带 BOM 的 UTF-8，解析器读出来第一行是乱码，导致整个技能被跳过。

5.2 技能之间互相干扰的典型场景

技能干扰通常表现为：一个技能改了文件，另一个技能读到的是旧内容；或者两个技能同时操作同一个资源导致状态不一致。我踩过的坑包括：apply-patch和format-code同时运行，格式化把补丁的缩进改了，导致后续验证失败。解决办法是在config.yaml里给这两个技能设同一个exclusive_group，强制串行执行。

另一个常见干扰是上下文污染。技能 A 在输出里写了一大段调试日志，技能 B 把这段日志当成了有效输入。我的做法是在技能输出里明确区分“结构化结果”和“原始日志”，结构化结果用 JSON 格式，原始日志写到单独文件，技能之间只传递结构化结果。

5.3 性能瓶颈与优化方向

技能数量上去之后，匹配和加载会成为瓶颈。我实测过，50 个技能、全量加载模式下，每次任务启动要多花 2 到 3 秒在加载上。优化方向有几个：

• 用分层加载，索引常驻，详情按需。
• 给技能匹配加缓存，相同或相似的任务描述直接复用上次的匹配结果。
• 把不常用的技能标记为cold，只在明确需要时才加载。
• 定期清理废弃技能，我每两周会 review 一次技能库，把三个月没被匹配到的技能归档。

5.4 常见问题速查表

提示：建议给每个技能加一个version字段，技能更新时递增。这样在排查问题时能快速确认用的是哪个版本，也方便回滚。

6. 技能库的扩展与团队协作实践

6.1 怎么引入外部技能

社区里已经有不少人分享了自己的技能包，引入外部技能时不要直接复制粘贴，先做三件事：读一遍SKILL.md，确认触发条件和你的项目匹配；跑一遍examples/里的示例，确认输出符合预期；检查config.yaml里的依赖和互斥声明，避免和现有技能冲突。我一般会先把外部技能放到skills/_staging/目录下，用几个真实任务试跑一周，确认稳定后再移到正式目录。

6.2 团队协作中的技能管理规范

多人协作时，技能库很容易变成一团乱麻。我们团队的做法是：技能目录按负责人分，每个人维护自己的技能子目录；skills-index.yaml由专人合并，每周更新一次；技能变更走代码评审，重点看触发条件和依赖声明有没有破坏现有组合。另外，每个技能都要有一个owner字段，出问题时能快速找到人。

6.3 技能复用的边界与注意事项

技能复用能省很多事，但要注意边界。一个技能如果被太多地方依赖，改起来就会畏首畏尾。我的经验是，被三个以上其他技能依赖的技能，要么保持极度稳定，要么拆成更细的原子技能。另外，跨项目复用技能时，要注意项目间的环境差异——比如测试命令、目录结构、依赖版本，这些差异最好通过技能级配置来适配，而不是改技能本身。

7. 我个人的一些实操体会

这套框架我用了大半年，最大的感受是：技能拆分的质量直接决定了整套系统的上限。拆得好，智能体像有了工具箱，遇到什么问题拿什么工具；拆得不好，要么工具太少不够用，要么工具太多挑花眼。我现在的习惯是每加一个新技能，先问自己三个问题：这个能力会不会被重复使用？它的输入输出能不能说清楚？它和其他技能的边界在哪里？三个问题有一个答不上来，就先不急着加。

另一个体会是，日志比什么都重要。技能匹配日志、加载日志、执行日志，这三样东西在排查问题时缺一不可。我一开始嫌麻烦没记日志，后来出了问题只能靠猜，效率极低。现在每个技能执行都会写一条结构化日志，包含技能名、版本、输入摘要、输出摘要、耗时和状态，排查问题时直接 grep 就行。

最后分享一个小技巧：给技能库加一个“健康检查”脚本，定期跑一遍所有技能的示例，确认输出没有漂移。模型更新、依赖升级、环境变化都可能导致技能行为改变，健康检查能帮你提前发现这些问题，而不是等线上任务失败了才去查。这个脚本我放在scripts/health-check.sh，每周一早上自动跑一次，结果发到团队频道，省了不少事。