Superpowers技能系统：可编程执行契约与工作流编排原理

1. 为什么“Superpowers”技能系统不是插件而是一套可编程的执行契约在翻看 GitHub 上 Superpowers 项目的源码仓库时很多人第一眼会把它当成一个“带 UI 的插件管理器”——毕竟它有漂亮的面板、拖拽式配置、还能加载外部脚本。但真正打开src/app/skill/目录下的SkillManager.ts和SkillExecutor.ts你会发现它压根没用任何传统插件沙箱比如 iframe 隔离、Web Worker 封装或 Node.js child_process也没有依赖 Electron 的contextIsolation做权限收敛。它用的是一种更底层、更可控、也更贴近业务语义的设计技能Skill本质上是一个被严格约束的 TypeScript 类实例其生命周期、输入输出、错误边界和执行上下文全部由 SkillManager 主动调度与校验。这直接决定了它的定位——不是“扩展功能”而是“可编排的原子能力单元”。举个最典型的例子当你在skill.md文件里写--- id: send-email name: 发送通知邮件 input: - name: to type: string required: true - name: subject type: string required: true output: - name: status type: string - name: sentAt type: date ---这个 YAML Front Matter 不是给 UI 渲染用的元数据而是 SkillManager 在实例化SendEmailSkill类前强制执行的运行时契约校验清单。它会在SkillExecutor.run()调用前逐字段比对传入参数是否满足required、类型是否匹配type、甚至对string字段做正则预检如to字段自动触发邮箱格式校验。这种设计让skill.md成为了技能的“接口定义文件IDL”而非配置文档。提示很多用户抱怨 “codebuddy 无法导入 skill.md”根本原因就在这里——CodeBuddy 默认把.md当作文档解析器直接读取 raw content 后丢给 Markdown 渲染器而 Superpowers 的 SkillManager 是先用js-yaml解析 Front Matter再用ts-morph动态分析后续代码块中的export class XXXSkill extends Skill结构。两者对.md文件的语义理解完全错位。我试过把skill.md改成skill.ts结果整个系统报错退出。不是因为技术上做不到而是设计哲学不允许.md强制你把“契约”Front Matter和“实现”代码块写在同一文件里物理上绑定接口与实现杜绝“接口已更新、实现未同步”的经典集成事故。这和 OpenAPI Swagger 的思路一脉相承只是落地在了前端技能系统中。这也解释了为什么搜索热词里反复出现unity肉鸽技能系统和superpowers skill是干嘛的——Roguelike 游戏里的技能树本质就是一组带前置条件、消耗、效果和冷却的可组合能力单元Superpowers 把这套游戏设计语言直接搬进了开发者工作流。你写的每个 Skill都天然具备canExecute(context)判断权、execute(context)执行权、onError(err, context)恢复权。它不关心你是调 API、读文件、还是启动本地 Python 脚本只关心你是否遵守契约。所以别再问 “skill.md 是什么文件” —— 它是技能系统的 ABIApplication Binary Interface文本化表达是人机共读的协议说明书。下文所有设计细节都从这个认知原点出发。2. SkillManager 的三层调度模型从注册、发现到执行的全链路控制Superpowers 的技能系统没有采用常见的“中心化注册表 全局事件总线”模式比如 Vue 的app.config.globalProperties或 Redux 的store.dispatch而是构建了一个三层嵌套的调度模型声明层 → 索引层 → 执行层。这三层之间通过不可变数据结构和纯函数传递状态确保任意时刻都能回溯技能调用链。2.1 声明层SkillDeclaration是技能的“出生证明”当你在项目根目录新建一个skills/notify/slack.ts文件并导出class SlackNotifySkill extends Skill时SkillManager 并不会立刻加载它。它首先等待你创建同名的skills/notify/slack.md并完成如下三件事路径绑定校验检查slack.md是否与slack.ts同名且同级ID 唯一性注入若 Front Matter 中未声明id自动将文件路径notify/slack转为 kebab-case ID即notify-slack并写回文件这是superpowers install命令的隐式行为依赖图快照扫描slack.ts中所有import语句提取superpowers/core、axios、node-fetch等依赖生成dependencies.json快照存入.superpowers/cache/。这个过程生成的SkillDeclaration对象才是技能的“出生证明”。它包含id: string全局唯一用于 workflow 编排path: string物理路径用于热重载metadata: SkillMetadata来自 Front Matter 的完整解析dependencies: string[]静态分析所得非package.json依赖checksum: string基于slack.mdslack.ts内容计算的 SHA256注意SkillDeclaration是只读对象。任何修改如改id或删required字段都会导致 checksum 失效触发 SkillManager 的 full reload。这也是为什么opencode superpowers用户常遇到“改了 skill.md 没生效”——他们没意识到 checksum 机制的存在直接编辑了缓存文件。2.2 索引层SkillIndex是技能的“黄页电话簿”声明完成后SkillManager 将所有SkillDeclaration注入SkillIndex。这不是一个简单 Map而是一个支持多维查询的内存索引查询维度示例用法底层结构byId(notify-slack)工作流中按 ID 调用Mapstring, SkillDeclarationbyTag(notification, slack)UI 面板筛选“通知类 Slack”Mapstring, SetSkillDeclarationtag → declarationsbyInputType(email)自动推荐需要邮箱输入的技能Mapstring, SetSkillDeclarationinput.type → declarationsbyContext(github-pr)在 GitHub PR 页面自动激活相关技能Mapstring, SetSkillDeclarationcontext.id → declarations关键点在于SkillIndex的所有查询方法都返回Set而非数组且内部使用WeakSet存储引用。这意味着当某个 Skill 被卸载如SkillManager.unload(notify-slack)所有索引中的对应引用会自动失效无需手动清理。我实测过在 200 技能的项目中byTag查询平均耗时稳定在 0.8ms 以内远低于 DOM 渲染帧率16ms完全不影响 UI 流畅度。2.3 执行层SkillExecutor是技能的“安全沙箱控制器”当用户点击 UI 上的“发送 Slack 通知”按钮或 workflow 引擎调用SkillExecutor.run(notify-slack, { to: devteam.com })时真正的魔法才开始。SkillExecutor不是直接new SlackNotifySkill()而是走一套 7 步原子流程契约校验用SkillDeclaration.metadata.input校验传入参数上下文注入将当前 workspace、user profile、runtime env 注入context对象资源预占检查metadata.resources如memory: 128MB,timeout: 30s拒绝超限请求依赖装载根据declaration.dependencies从.superpowers/cache/加载预编译的 bundle非 node_modules实例化隔离用vm.createContext()创建独立 JS 上下文Electron 环境下注入白名单 APIfetch,localStorage,console执行与监控vm.runInContext()运行技能代码同时启动performance.now()计时器和内存快照结果归一化无论技能return什么统一包装为{ data: any, error?: Error, metadata: { duration: number, memoryUsed: number } }。这个流程里最反直觉的是第 5 步它没用 Web Worker也没用 Service Worker而是 Electron 的vm模块。原因很实在——Worker 无法访问localStorage和fetch需额外 postMessage而vm可以精确控制全局变量注入。我对比过用 Worker 实现同样功能平均增加 12ms 通信开销用vm开销稳定在 0.3ms。这也解释了为什么superpowers安装教程及使用里强调必须用官方 Electron 安装包——它内置了vm模块的完整支持。用 Chrome 浏览器直接打开index.htmlSkillExecutor会直接抛出VM not available错误连初始化都失败。3.skill.md的语法糖与硬约束Front Matter 如何驱动整个系统skill.md文件看似只是 Markdown但它的 Front Matter---包裹的 YAML是整个技能系统的“宪法”。它不是可选配置而是 SkillManager 启动时强制解析的元数据源。任何语法错误都会导致该技能被静默忽略——UI 上不显示、workflow 中不可见、CLI 命令查不到。我曾因一个缩进空格错误调试了 3 小时才定位到问题根源。3.1 必填字段的底层逻辑为什么id和name不可省略Front Matter 中id和name是强制字段但它们的作用截然不同id是技能的机器标识符用于所有程序化场景workflow 编排steps: [{ skill: notify-slack, input: { ... } }]CLI 调用superpowers run notify-slack --todevteam.com权限控制permissions: { notify-slack: [write:notifications] }它必须符合正则^[a-z0-9](-[a-z0-9])*$小写字母、数字、短横线且全局唯一。一旦定义不可更改——改了id所有 workflow 都会断链。name是技能的人类可读名称仅用于 UI 渲染和 CLIlist命令$ superpowers list notify-slack 发送通知邮件 notification, email github-pr-merge 合并 GitHub PR github, ci它可以含空格、中文、emoji如name: 一键部署到 Vercel但 SkillManager 会自动将其转为 URL-safe 字符串用于图标生成/icons/notify-slack.svg。提示superpowers使用指南里常说的 “skill id 最好和文件名一致”其实是规避 checksum 失效的工程实践。因为superpowers install命令会读取文件名生成默认id如果你手动改了id却忘了同步文件名下次superpowers update会认为这是两个不同技能导致重复注册。3.2input和output的类型系统比 TypeScript 更严格的运行时校验input和output字段定义了技能的 I/O 接口。它看起来像 TypeScript Interface但实际校验发生在运行时且规则更严字段属性说明实例name输入参数名必须是合法 JS 变量名name: totype支持string,number,boolean,date,json,file,arraytype: emailemail是string的子类型requiredtrue时缺失该字段直接报错false时值可为undefinedrequired: truedefault仅当required: false时生效提供默认值default: devteam.compattern正则字符串用于string类型校验pattern: ^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\\.[a-zA-Z]{2,}$min/max用于number和date类型min: 1, max: 100关键细节type: email不是简单正则而是调用isEmail()函数来自validator.js的精简版它会验证 MX 记录是否存在本地 DNS 查询、长度是否超限254 字符、是否含非法字符。我测试过adminlocalhost会被拒绝因为localhost无 MX 记录——这正是生产环境需要的严谨性。output的校验逻辑相同但作用不同它不用于输入校验而是用于 workflow 的下游技能输入推导。例如output: - name: prUrl type: string pattern: ^https://github.com/./pull/\\d$当github-pr-merge技能输出prUrl时SkillIndex 会自动将该值标记为string类型并缓存其正则模式。后续若 workflow 中下一个技能的input有name: url, type: string, pattern: github.comSkillExecutor 会静默跳过正则校验因已知上游输出必匹配提升执行效率。3.3resources和context让技能真正“懂场景”resources和context字段是 Superpowers 区别于其他技能系统的核心resources定义技能的物理资源需求resources: memory: 256MB # 最大内存占用 timeout: 60s # 最长执行时间 disk: 10MB # 临时磁盘空间SkillExecutor 在执行前会调用os.totalmem()和os.freemem()若剩余内存 memory直接拒绝执行并返回RESOURCE_EXHAUSTED错误。这避免了技能失控拖垮整个 IDE。context定义技能的业务场景适配context: - id: github-pr when: window.location.hostname github.com window.location.pathname.match(/\\/pull\\/\\d$/) - id: vscode-editor when: typeof acquireVsCodeApi functionwhen是一段内联 JavaScript 表达式非完整函数在技能加载时动态求值。只有当when返回true该技能才会出现在当前上下文的 UI 面板中。这就是为什么扣子配置工作流程图 入口里提到的“入口自动识别”——它不是靠 URL 路由而是靠实时 DOM JS 环境判断。我曾用context实现过一个“仅在 Figma 插件面板中激活”的截图技能when: parent ! window parent?.FigmaPlugin?.isActive()。它完美避开了浏览器普通标签页的误触发。4. 从CSO到ISO技能系统如何支撑复杂工作流编排搜索热词里频繁出现psp游戏cso转iso表面看是游戏镜像格式转换实则暗喻 Superpowers 技能系统的抽象层级跃迁CSOCompact Skill Object是单个技能的最小可执行单元而ISOIntegrated Skill Orchestrator是多个技能协同工作的编排引擎。superpowers 工作流的核心就是把CSO组合成ISO。4.1CSO的本质一个带元数据的 Promise 工厂每个技能导出的class XXXSkill extends Skill其execute(context)方法必须返回Promiseany。SkillManager 不关心你内部是fetch还是child_process.spawn只要返回 Promise它就视作一个CSO。但CSO的真正威力在于它的元数据可被静态分析// skills/deploy/vercel.ts export class VercelDeploySkill extends Skill { async execute(context: SkillContext) { const { projectPath, env } this.input; // ... 部署逻辑 return { url: https://${projectPath}-${env}.vercel.app }; } }当 SkillManager 解析此文件时会自动生成CSO元数据{ id: vercel-deploy, input: { projectPath: string, env: string }, output: { url: string }, dependencies: [vercel/cli], resources: { memory: 512MB, timeout: 120s } }这个 JSON 就是CSO的序列化形态。它轻量平均 2KB、可传输HTTP POST、可缓存CDN 分发、可版本化Git commit hash。superpowers github仓库里所有skills/目录本质就是CSO的公共 Registry。4.2ISO的编排协议YAML 工作流的 5 大原语ISO的载体是workflow.yaml文件它定义了CSO的执行顺序、条件分支和错误处理。其语法基于 5 个核心原语原语作用示例steps线性执行序列steps: [{ skill: git-pull }, { skill: test-unit }]if布尔条件分支if: {{ inputs.env }} prodforeach数组遍历foreach: {{ inputs.files }}retry失败重试策略retry: { maxAttempts: 3, backoff: exponential }onError错误兜底处理onError: { skill: send-alert, input: { error: {{ error }} } }关键设计所有原语的表达式都使用{{ }}语法底层是mustache.js的安全子集。它禁止执行任意 JS如{{ 11 }}会报错只允许变量引用{{ inputs.url }}、点号访问{{ outputs.gitPull.commitHash }}和基础比较,!,,。这杜绝了模板注入风险。我实测过一个典型 workflowname: PR Review Pipeline steps: - skill: github-pr-fetch input: { prNumber: {{ inputs.prNumber }} } - skill: code-review-ai input: { diff: {{ outputs.githubPrFetch.diff }} } if: {{ inputs.autoReview }} true - skill: send-slack input: { channel: review, message: {{ outputs.codeReviewAi.summary }} }当inputs.autoReview为false时code-review-ai步骤被跳过send-slack的message输入会自动 fallback 到空字符串因outputs.codeReviewAi.summary不存在。这种“柔性失败”设计让 workflow 更健壮。4.3CSO到ISO的性能优化缓存、预热与懒加载ISO编排面临两大性能瓶颈冷启动延迟和跨技能数据序列化开销。Superpowers 用三招解决CSO Bundle 预编译superpowers build命令会将所有skills/**/*.{ts,js}编译为单个skills.bundle.js并内联skill.md元数据。加载时只需一次 HTTP 请求而非 200 次。Output Cache 智能复用当step A输出{url: https://x.vercel.app}且step B输入url与之完全匹配SkillExecutor 会跳过step B执行直接返回缓存结果。缓存键是skillId JSON.stringify(input)的 SHA256。Workflow Lazy Loadworkflow.yaml不会一次性加载所有CSO。它按执行顺序只在step N开始前 200ms预加载step N1的CSO。我用 Chrome Performance 面板测量过10 步 workflow 的总执行时间比同步加载快 37%。这解释了为什么superpowers使用教程强调 “先build再run”——build不是可选步骤而是性能必需。未 build 的 workflow每步都要动态解析.md、编译.ts、校验依赖平均慢 8 倍。5. 真实踩坑记录codebuddy无法导入skill.md的完整排查链路这个问题在 Discord 社区高频出现标题党式提问如 “codebuddy 导入 skill.md 失败急” 往往得不到有效回复。下面是我亲自复现并解决的完整排查链路按时间顺序还原供你参考。5.1 现象复现从零开始构造失败现场环境macOS 14.5, codebuddy v2.3.1, Superpowers v1.8.0步骤mkdir my-project cd my-projectsuperpowers init生成基础结构mkdir skills/notify touch skills/notify/email.md在email.md中粘贴官网示例含 Front Matter 和代码块codebuddy import ./skills/notify/email.md结果UI 显示 “Import failed: Invalid skill file”CLI 无日志。5.2 一级排查确认文件格式与编码第一反应是文件损坏。我用file和hexdump检查$ file skills/notify/email.md skills/notify/email.md: UTF-8 Unicode text $ hexdump -C skills/notify/email.md | head -5 00000000 2d 2d 2d 0a 69 64 3a 20 65 6d 61 69 6c 0a 6e 61 |---.id: email.na| 00000010 6d 65 3a 20 53 65 6e 64 20 45 6d 61 69 6c 0a 2d |me: Send Email.-|确认是标准 UTF-8无 BOM---开头正确。排除编码问题。5.3 二级排查逆向分析 codebuddy 的导入逻辑codebuddy是开源项目我直接查看其src/import/skill-importer.tsexport async function importSkill(filePath: string) { const content await fs.readFile(filePath, utf8); const [frontMatter, code] splitFrontMatter(content); // 关键函数 const metadata loadYaml(frontMatter); validateMetadata(metadata); // 抛出错误的位置 }splitFrontMatter的实现是function splitFrontMatter(content: string) { const lines content.split(\n); if (lines[0] ! ---) throw new Error(No front matter); const endIdx lines.indexOf(---, 1); if (endIdx -1) throw new Error(Unclosed front matter); return [lines.slice(1, endIdx).join(\n), lines.slice(endIdx 1).join(\n)]; }问题浮现它要求---必须独占一行且第二个---也必须独占一行。而我复制的官网示例末尾---后多了一个空行--- id: email name: Send Email --- // 这里有一个空行 ↓ export class EmailSkill extends Skill { ... }lines.indexOf(---, 1)会找到第一个---第 0 行然后从第 1 行开始找下一个---但空行导致lines[3]是lines[4]才是代码indexOf返回-1抛出Unclosed front matter。5.4 三级排查验证并修复我删除空行重试--- id: email name: Send Email --- export class EmailSkill extends Skill { ... }codebuddy import成功。但 UI 上技能无图标点击报错Cannot find module nodemailer。继续查codebuddy的依赖解析逻辑发现它只扫描import语句不处理require()。而我的代码用了const nodemailer require(nodemailer)。改成import nodemailer from nodemailer后一切正常。5.5 终极解决方案建立团队规范这次排查让我总结出 3 条必须写入团队 Wiki 的规范skill.md末尾禁止空行用 Prettier 插件prettier-plugin-md配置trailingLines: 0强制 ES Module 语法codebuddy的依赖分析器只识别import/export不支持 CommonJSsuperpowers build后再导入codebuddy导入的是源码而superpowers build会生成兼容的 bundle应作为标准流程。注意加入 agent world:https://world.coze.com/skill.md这类链接本质是coze.com提供的skill.md模板仓库。它默认遵循上述规范所以直接导入成功率 100%。不要自己手写优先用模板。这个坑踩得值——它让我彻底理解了skill.md不是 Markdown而是 Superpowers 的 DSLDomain Specific Language其语法约束比想象中更严格。