Superpowers 如何为新 AI 编程工具做移植能力检查清单、集成形态选择与验收测试【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers当你想让 Superpowers 的技能skills在一个新的 AI 编程工具官方称为 harness即 IDE、CLI 或 agent 运行器中自动触发而不是只在 Claude Code 里可用时你需要为这个项目完成一次移植。仓库文档 docs/porting-to-a-new-harness.md 是这次移植的唯一权威指南它把流程分为两层Part 1–3 解释系统如何跨 harness 工作、如何判断一个 harness 能否被支持Part 4–8 给出从建立集成到分发发布的完整操作。本文围绕这条移植路径整理能力检查清单、三种集成形态的选择依据和验收测试方法。移植前文档要求先做三件事且都不可跳过完整阅读 CLAUDE.md 和.github/PULL_REQUEST_TEMPLATE.md——贡献者规则和新 harness PR的要求是强制的。在已打开和已关闭的 PR 中搜索是否有人尝试过这个 harness如果有先弄清它为什么停滞。检查该 harness 是否只是换了安装器的现有集成。例如 Factory 的 Droid 通过自己的plugin install直接消费 Claude Code 插件不需要在本仓库新增任何文件。只往 README 加一段说明也算合格的移植结果。能力检查清单先判断这个 harness 能不能支持硬性前提会话启动时自动注入这是唯一不可协商的能力harness 必须允许你在每个会话开始时把文本注入模型的上下文且不需要人类伙伴每次手动选择开启。它可以是以下任意形态hook/事件系统会话启动时运行 shell 命令并读取其 stdoutClaude Code、Cursor、Copilot CLI进程内插件/扩展带会话启动或消息生命周期回调能修改消息数组OpenCode、piinstructions 文件约定harness 加载一个由你安装的扩展自带并在 manifest 中声明的上下文文件例如 Gemini 的contextFileName指向扩展自己的 GEMINI.md——不是用户主目录里由你编辑的文件。如果唯一注入方式是让用户每次会话手动操作粘贴 prompt、跑命令、开某个模式这个 harness不能被正确支持验收测试会失败PR 会被关闭。文档指出这是移植失败的头号原因。其余能力项可缺失但要会降级能力用途缺失时的处理技能发现 调用模型按需加载完整技能内容没有原生 skill 工具时认可的替代方案是直接read对应的SKILL.md见 docs/porting-to-a-new-harness.md Part 5既没有 skill 工具也没有文件读取则无法支持文件读 / 写 / 编辑几乎所有技能都操作文件必需无替代运行 shell 命令TDD、验证、git 流程必需子代理 / 任务分发dispatching-parallel-agents、subagent-driven-development可降级技能自带的回退措辞会让模型内联完成或报告缺失能力绝不凭空编造Task调用部分 harness 需要配置开关启用如 Codex 需开启 multi-agentTodo / 任务跟踪多个技能中的进度跟踪可降级回退到计划文件或TODO.mdWeb 抓取 / 搜索少数技能可降级Shell / 多语言脚本执行Windows仅 shell-hook 形态、且需要 Windows 支持时见 Part 7进程内插件形态完全避开此问题可降级的含义是技能本身已经写好了对应缺失工具的 fallback 措辞。你的工具映射tool mapping要做的是工具存在时指向真实工具名不存在时复用那份 fallback 措辞。选择集成形态A、B、C 三种三种结构形态的区别在于bootstrap 如何到达模型。选定形态后再照抄对应参考实现形态决定了后续步骤的分支。先摸清机制不要假设。文档给出几条实证手段搜索该 harness 的文档关键词extension / plugin / hook / skill / MCP / context file / rules file找一个已有的第三方扩展读它的 manifest 和加载方式对文档不全的 harness 可以用strings或 grep 安装树来确认 hook 事件名、配置路径和它实际读取的 instructions 文件让运行中的模型列出它所有可调用的工具名list the exact machine names of every tool you can call是获取真实工具名的权威方法用独特标记测试注入一个无意义 token开新会话确认它到达模型来证明每个假设。特别提醒fork 不会继承父项目的行为——一个 Gemini 派生的 CLI 可能暴露父项目的 manifest 字段和-include 语法却并不同样执行必须用标记验证。然后按路由表定型如果 harness……使用形态参照复制会话启动时运行 shell 命令并读 stdoutAshell-hookCursorhooks/session-start hooks/hooks-cursor.json .cursor-plugin/是带会话/消息生命周期回调的 JS/TS 插件宿主B进程内OpenCode.opencode/若无原生 skill 工具则参照 pi.pi/只有常驻 instructions 文件由扩展声明Cinstructions-fileGeminigemini-extension.json GEMINI.md references/gemini-tools.md有插件安装命令且 installer 保留 manifest 的contextFileNameC经插件安装器Antigravity.antigravity-plugin/agy plugin install携带生成的上下文文件形态不是互斥的技能发现机制和 bootstrap 机制可以是不同形态但两者都必须走安装机制——绝不手改用户的全局或个人配置~/.bashrc、settings.json等。各形态的关键约束形态 Aharness 有 hook 系统 ≠ 有 session-start事件。有 harness 的二进制里含SessionStart字符串但实际只暴露 pre/post-tool 和 stop 事件那些字符串是遥测。必须先确认你要的那个具体事件存在且能写入模型上下文。另外 hook 输出 JSON 的字段名和嵌套层级因 harness 而异hooks/session-start 按环境变量区分三种输出——CursorCURSOR_PLUGIN_ROOT已设置输出{ additional_context: … }Claude CodeCLAUDE_PLUGIN_ROOT已设置且COPILOT_CLI未设置输出{ hookSpecificOutput: { hookEventName: SessionStart, additionalContext: … } }Copilot CLI / SDK 标准其余情况输出{ additionalContext: … }。发错字段、多发一个字段会导致不注入或重复注入Claude Code 会同时读两个字段且不去重。hook 配置的 schema 也各不同对比 hooks/hooks.jsonmatcher: startup|clear|compact、type/shell/async字段和 hooks/hooks-cursor.jsonversion: 1、小写sessionStart键、相对命令、省略 matcher 等字段按最接近的现有文件对齐而不是套一个标准模板。hook 命令字符串引用 harness 导出的 plugin-root 变量变量名因 harness 而异${CLAUDE_PLUGIN_ROOT}或相对路径。形态 B在代码里拼装 bootstrap——读取 skills/using-superpowers/SKILL.md、剥掉 YAML frontmatter、包上EXTREMELY_IMPORTANT标签、前缀技能已加载、不要再调用的说明、正文、内联工具映射然后作为user 角色消息注入不是 system 消息——system 消息每轮重复会膨胀 token多条 system 消息会让部分模型出错。必须复制三个行为去重守卫生命周期回调会重复触发注入前先检查 bootstrap 标记、压缩后重注入harness 做历史压缩/摘要后再次注入、按 harness 自己的消息对象结构构造pi 用{ role, content: [{type, text}], timestamp }OpenCode 操作message.info.role和message.parts[]两者不兼容不要照抄参考实现的字面量。可对照 .opencode/plugins/superpowers.js 和 .pi/extensions/superpowers.ts。形态 C没有注入器也就不拼装字符串。扩展自带的上下文文件由 manifest 声明不是用户的全局文件引入两样东西bootstrap 技能和工具映射参考文件。GEMINI.md 就是两个-include./skills/using-superpowers/SKILL.md和./skills/using-superpowers/references/gemini-tools.md。注意-include 是 Gemini 的特性如果你的 harness 加载 instructions 文件但没有 include 语法要把 bootstrap 内容直接内联进文件。并且不要相信-include 一定被展开——Gemini 派生 harness 可能把它当作模型可选读的文件提示会发一个文件读取调用而不是保证的展开。跑一次独特标记测试若没有工具调用标记就不在上下文里改为内联。执行移植manifest、bootstrap 与工具映射指南 Part 5 的步骤顺序是读透所选形态的参考实现代码才是 spec文档只是摘要→ 创建 manifest/入口 → 接好 bootstrap 注入 → 写工具映射 → 处理无原生 skill 工具的 harness → 加测试 → 本地安装并驱动真实实例验证。写工具映射时把动作词汇表翻译成 harness 的真实工具名覆盖读文件、创建/编辑/删除文件、运行 shell 命令、搜索文件内容/按名找文件、抓 URL/搜索、分发子代理含如何传 agent 类型和启用所需的配置开关、创建/更新 todo、调用技能。真实工具名永远从 harness 本身获取不凭文档缺失就发明。映射文件的位置取决于形态形态 A 放skills/using-superpowers/references/harness-tools.md从 bootstrap 可达SKILL.md 的 Platform Adaptation 一节链接各 harness 参考文件形态 B 通常内联进注入的 bootstrap 字符串pi 两处都放两处都要更新形态 C 放进references/harness-tools.md并让常驻 instructions 文件引入它。移植允许对SKILL.md做的唯一编辑是在 Platform Adaptation 指针列表里加一行指向你的 harness——其余技能内容一律不动。如果 harness 没有原生 skill 工具有三种情况要分清有原生Skill类工具就直接映射过去有技能发现但没有Skill工具pi、Antigravity把技能装进 harness 扫描的位置并告诉模型技能适用时用文件读取工具读SKILL.md——这就是认可的路径完全没有技能系统则模型读不到它找不到的东西using-superpowers/SKILL.md本身不枚举可用技能你必须在 bootstrap 里提供发现路径生成一份技能索引各SKILL.md的namedescriptionfrontmatter放进EXTREMELY_IMPORTANT包裹内或让模型运行时列举skills/*/SKILL.md读 frontmatter 找匹配——后者慢但永不过时优先选后者。自动化测试各形态各有什么测试要与现有每 harness 风格一致形态 A断言 hook 的 stdout 是 harness 消费的精确 JSON 形状且包含 bootstrap。参考 tests/hooks/test-session-start.sh——它对 Claude Codenested 形状、Cursor顶层additional_context、Copilot CLI顶层additionalContext分别验证输出形状互斥比如 nested 形状不允许再出现顶层 context 字段并检查 hooks/hooks.json 中 SessionStart 注册声明了shell: bash。形态 B单测伪造 harness 的插件 API断言生命周期处理器注册成功、bootstrap 只注入一次、去重守卫有效、如适用压缩后重注入有效。参考 tests/pi/test-pi-extension.mjs另加 tests/opencode/ 风格的隔离安装集成检查。如果 bootstrap 有缓存测试文件缺失时缓存的行为OpenCode 的 caching 测试就是这类。这些自动测试覆盖的是接线真正证明集成能触发技能的是下一步的 live 运行。验收测试从 smoke 检查到完整转录先本地安装让一个本地实例指向你的工作树不是已发布构建。形态 A/C 从本仓库本地路径安装插件/扩展或把目录软链到 harness 查找的位置形态 B 注册本地模块如opencode.json的plugin项指向本地路径。每次修改后重装并重启 harness因为 bootstrap 在启动时加载。大多数 harness 是交互式 REPL/TUI无法用管道 stdin 驱动所以指南要求在分离的 tmux 会话中运行并用send-keys/capture-pane控制。非交互的单次 prompt模式如opencode run ...可以做快速 smoke 检查但不要依赖它——文档记录有 harness 的--print模式每次挂起超时。运行前先处理掉首跑引导、do you trust this folder?、沙箱和权限关卡否则分离的 tmux 会话会静默卡住。下面的脚本来自 docs/porting-to-a-new-harness.md Step 7其中harness-launch-command需要你替换为该 harness 实际的启动命令其余命令可直接执行注意副作用脚本会创建/tmp/port-smoke目录并在最后用tmux kill-session结束名为port-test的 tmux 会话。# 1. 在一次性项目目录中分离启动 harness mkdir -p /tmp/port-smoke tmux new-session -d -s port-test -c /tmp/port-smoke harness-launch-command # 2. 等它初始化真实 TUI 加模型握手要 10 秒以上按需调整。 # 然后捕获并处理阻塞的模态框首跑引导、信任询问是模态的 # 模态期间 send-keys 会选中菜单项而不是输入 prompt sleep 12 tmux capture-pane -t port-test -p # 有 onboarding / trust 提示先用 send-keys 处理 # (例如 tmux send-keys -t port-test Enter # 接受 trust 提示——先看捕获内容再操作) # 3. Smoke 检查模型知道自己有 superpowers 吗 # 文本和 Enter 分成两次 send-keys 发送中间留一拍 # 某些 TUI 上同时发会竞态Enter 先于文本落地 tmux send-keys -t port-test What are your superpowers?; sleep 0.4; tmux send-keys -t port-test Enter sleep 5 tmux capture-pane -t port-test -p # 回复应显示它知道技能 # 4. 验收测试精确 prompt注意撇号转义全新会话 tmux send-keys -t port-test Let\s make a react todo list; sleep 0.4; tmux send-keys -t port-test Enter # 轮询直到回合结束——每几秒重新捕获不要只捕获一次 sleep 8 tmux capture-pane -t port-test -p # PASS brainstorming 在任何代码之前触发 # 5. 保存转录供 PR 使用然后清理 tmux capture-pane -t port-test -p /tmp/port-smoke/transcript.txt tmux kill-session -t port-testtmux 的几个坑启动后先等再捕获prompt 文本和Enter用分开的send-keys加短sleep发送Enter是键名不是\n模型回合耗时用循环轮询capture-panecapture-pane只显示可见面板长会话以 harness 自己的转录/日志文件为准结束后务必kill-session。判断逻辑smoke 检查若显示模型不知道自己有 superpowers说明 bootstrap 没有加载——先修这个再跑验收测试。验收测试的通过标准是在干净会话中发送Lets make a react todo list后brainstorming技能在任何代码被写出之前自动触发并保留完整转录PR 要求提供。文档另给了一个不同机制的 smoke 变体OpenCode 安装文档用opencode run --print-logs hello 21 | grep -i superpowers通过日志 grep 达成同一目的——21很关键因为日志走 stderr。完成标准、分发与提交移植完成的定义Part 3 Definition of done是以下全部成立bootstrap 每个会话自动加载且无逐会话 opt-in工具映射存在技能可被实际调用原生或文档化的 read-SKILL.md回退且模型遵循验收测试通过并有转录测试覆盖集成且通过真实用户能通过 harness 自己的机制安装不是手拷文件且版本在适用时登记进 .version-bump.json该文件当前跟踪package.json、各*-plugin/plugin.json、marketplace.json和gemini-extension.json的 version 字段由 scripts/bump-version.sh 保持同步。注意有些安装器会重写或裁剪 manifest有的只保留{name: …}所以已安装文件报告仓库版本并非总能实现——在源 manifest 处跟踪版本不要把被重写的已安装 manifest 当失败。分发的渠道按 harness 生态而定Claude Code 走.claude-plugin/marketplace.json注册Codex 用 scripts/sync-to-codex-plugin.sh 同步到外部 forkGemini/Kimi Code/OpenCode 走 git URL 安装pi 靠仓库根 package.json 的字段Antigravity 用agy plugin install装 staging 目录。一个反复出现的坑plugin install通常只复制它认识的分量skills/agents/commands/mcp/hooks/contextmanifest 没声明的上下文文件会直接从安装中消失——修复方式是声明 bootstrap 为被认识的分量contextFileName类字段而不是放弃去写用户配置。最后提交 PR目标分支是dev一个 PR 只做一个 harness填写 PR 模板的 New harness support 部分并粘贴完整验收测试转录没有这份证明的 PR 会被关闭Superpowers 是零运行时依赖插件不为新 harness 添加第三方运行时依赖type-only 的、编译期消掉的 import 可以发现自己为了移植去改SKILL.md时说明修复点应该在工具映射里而不是技能正文。完整参考集成的入口点、bootstrap 机制、工具映射位置、测试目录和分发渠道见指南末尾的 Appendix A 索引表——不确定时读文件而不是只读表格。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考