Superpowers 平台中立化工程:README 平台列表字母序重排的设计、实施与验证【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一套同时面向多个编码智能体运行时(Claude Code、Codex、Cursor、Gemini CLI 等)的技能框架,其 README 必须并列列出所有平台的安装方式,而列表里谁排第一本身会向读者传递一种隐含的平台优先级。本文基于仓库中的 Phase C 设计文档 2026-05-05-platform-neutral-readme-design.md,完整讲解这次零文案修改、纯排序调整变更的设计边界、替换规则、提交策略与字节级可验证的验收标准。读完后,你可以在任何同一份平台列表出现在 README 多处的多平台项目中,应用同一套布局中立化检查方法,并产出一份可用git diff逐行核验的纯移动型改动。背景:排序是平台倾向的最后一类信号Superpowers 的插件运行在多个 harness 上,而技能内容与配套文档最早是面向 Claude Code 撰写的。项目因此把平台中立化按引用类别拆成多个阶段推进,本文的文档是其中第三阶段:Phase A —— 通用文案中立化(设计文档见 2026-05-05-platform-neutral-prose-design.md,实施提交f0e5117):将技能文档中泛指任意运行时的智能体却写成 Claude 的第三人称文案,替换为 your agent / the agent 等平台中立的表述,并把自造术语 Claude Search Optimization (CSO) 重命名为 Skill Discovery Optimization (SDO)。Phase B —— 配置文件引用中立化(设计文档见 2026-05-05-platform-neutral-config-refs-design.md,实施提交6b9f1b2):技能中把CLAUDE.md当作唯一指令文件提及的写法,改为 your instructions file / instruction file 等覆盖 CLAUDE.md、AGENTS.md、GEMINI.md 的通用说法。Phase C —— 布局与排序:即本文档。Phase C 的文档对前两个阶段的成果和剩余问题做了明确的背景陈述:Phase A 和 B 已经中立化了 README 中通用的 Claude 文案与配置文件引用,而剩余的平台倾向信号是布局——README 的两处平台列表把 Claude Code 放在第一位,且其余部分并未严格按字母序排列。文档随即给出了本阶段唯一的行动原则:This phase fixes the ordering. No prose changes. (本阶段只修排序,不改任何文案。)这一原则值得单独强调:在面向读者的文档中,列表顺序会被读作重要性排序,第一位的平台天然获得默认平台的观感。对一个明确支持 10 个以上 harness 的项目而言,这种观感与项目定位相悖;而排序恰好是可以用字母序这种机械规则彻底消除歧义的维度。影响范围:README 中仅有的两处列表设计文档把范围严格限定为 README 的两个列表(以下行号引用均注明是文档撰写时与当前仓库两种口径,因为 README 此后有后续提交):列表位置文档引用的位置当前 README.md 中对应位置Quickstart 平台内联链接列表README.md:7第 8 行(## Quickstart标题下的链接行)Installation 小节排序README.md:35–152第 26–192 行(## Installation到## The Basic Workflow之前的全部###安装子小节)这两处列表承载的是同一组平台:Quickstart 行提供锚点跳转,Installation 一节提供逐平台安装步骤。Phase C 时点(2026-05-05)列表包含 8 个 harness;当前仓库的 Quickstart 行已扩展为 11 个(后续新增 Antigravity、Kimi Code、Pi,见下文演进一节),两处的相对顺序保持一致。不在范围内:三类明确不动的内容设计文档用一节 Out of scope 划定了三条边界,每条都附带了为什么不改的理由,这是这份规格最有参考价值的部分:文案、marketplace 名称、插件 ID、URL 一律不动——它们本身是事实正确的,只有顺序这一维度有偏差。Claude Code 小节的视觉权重不动。当前 README.md 的### Claude Code小节下确实有两个安装子路径(#### Official Marketplace与#### Superpowers Marketplace,见 README.md 的两条/plugin install命令),文档明确指出两者都是真实安装路径,合并会隐藏准确信息——也就是说,即使某个小节篇幅更大,只要内容属实就不为拉平排版而裁剪。每个安装块内部的标题与内容不动——只改变块与块之间的相对位置。这三条边界共同保证了改动的最小性:diff 里不应该出现任何一个词被改写。替换规则:严格字母序与三个移动设计文档给出了新旧顺序的完整对照表(此处完整继承原文档):旧顺序新顺序Claude CodeClaude CodeCodex CLICodex AppCodex AppCodex CLIFactory DroidCursorGemini CLIFactory DroidOpenCodeGemini CLICursorGitHub Copilot CLIGitHub Copilot CLIOpenCode文档随后把 8 个位置的变化压缩成三个移动(Three moves):Codex App 与 Codex CLI 互换(Cl…、Co…之后,App排在CLI前);Cursor 上移两个位次(越过 Factory Droid 与 Gemini CLI);GitHub Copilot CLI 上移一个位次(越过 OpenCode 之前的位置,排到 Gemini CLI 之后、OpenCode 之前)。同时文档点出了一个容易被忽略的细节:Claude Code 保持第一位纯属字母序巧合(Cl…在字母表上先于Co…)——也就是说新顺序没有任何给 Claude Code 保留 C 位的人为例外,规则是统一的严格字母序。这一点很重要:如果规则本身对某个平台开例外,那么字母序就不再是机械可验证的,后续任何新增平台都要重新争论一次。选择严格字母序作为排序规则还有两个工程好处:一是判定无歧义,任何两位维护者对谁该排前面不会得出不同结论;二是可脚本化验证,新增平台后只需一行排序检查命令即可判定列表是否合规。提交策略:一个原子提交覆盖两处列表设计文档的 Commit plan 只有一句话,但理由充分:One atomic commit covering both listings, since changing one without the other would create inconsistency between the quickstart and the installation section. (用一个原子提交同时覆盖两处列表,因为只改一处会在 Quickstart 与 Installation 节之间制造不一致。)两处列表描述的是同一事实集合,它们的相对顺序必须同步。若拆成两个提交,中间态会短暂出现Quickstart 是字母序、Installation 不是的矛盾状态;原子提交则让仓库任意提交点上两处永远一致。仓库历史印证了这一策略被执行到位。Phase C 实施提交为1681f58(2026-05-05),提交信息与规格一一对应:Phase C: alphabetize README platform listings spec Quickstart link list and the per-harness install sub-sections both reorder to strict alphabetical: Claude Code, Codex App, Codex CLI, Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, OpenCode Three blocks moved (Codex App swaps with Codex CLI; Cursor moves up two slots; GitHub Copilot CLI moves up one). Claude Code stays first by alphabetical chance. Each install sub-sections content is byte-identical pre/post — only the positions change. Quickstart anchors verified against the new heading order.从该提交的git show --stat输出可以提取一个有力的证据:整个提交共 76 行新增、29 行删除,其中 47 行新增来自新加入的规格文件本身,README.md 部分恰好是 29 行删除配 29 行新增——删一行加一行完全对称,这正是纯移动、零编辑的统计特征。验证:三条可复核的验收标准设计文档的 Verification 一节给出三条验收标准,每一条都可以用只读命令复核:标准 1:Quickstart 锚点仍指向存在的标题Quickstart 行的链接是页面内锚点(如#claude-code、#codex-app),这类锚点由各### …安装子小节的标题文本按转小写、空格转连字符的规则生成。规格明确要求不重命名任何标题,因为重命名会使 Quickstart 锚点 404。Phase C 只移动小节位置,标题集合不变,因此#claude-code、#codex-cli等锚点在新顺序下依旧解析有效。以当前 README.md 为例,###级安装子小节依次为 Claude Code、Antigravity、Codex App、Codex CLI、Cursor、Factory Droid、Gemini CLI、GitHub Copilot CLI、Kimi Code、OpenCode、Pi,与 Quickstart 行的 11 个锚点一一对应。标准 2:每个安装小节的正文前后字节级一致规格要求 Each install sub-sections body is byte-identical pre/post; only positions changed.(各安装子小节正文在改动前后字节级一致,只有位置变化。)这意味着移动的是整个### 标题 正文块,块内一个字符都不许动——包括代码块里的命令、marketplace 地址和标点。标准 3:git diff只显示小节移动,无内容编辑复核方式(在任意本地克隆上执行,均为只读操作):# 查看 Phase C 提交的整体统计与提交信息 git show --stat 1681f58 # 查看 README 的逐行 diff,应只见区块上下换位,不见行内改写 git show 1681f58 -- README.md对当前 README 的字母序合规性,也可以从 Installation 一节提取小节标题做检查:# 按出现顺序打印 Installation 一节的全部 ### 小节标题,人工/脚本比对字母序 sed -n /^## Installation/,/^## The Basic Workflow/p README.md | grep ^### 实施之后的现状:新 harness 加入与列表演进理解 Phase C 的价值,需要把它放回时间线里看。该提交时点列表为 8 个 harness,而当前 README.md 的 Quickstart 行(第 8 行)为:Claude Code、Antigravity、Codex App、Codex CLI、Cursor、Factory Droid、Gemini CLI、GitHub Copilot CLI、Kimi Code、OpenCode、Pi即 11 个。从提交历史可见,后续依次有 Antigravity(提交36ce0a2)、Kimi Code(提交f61300e、c877866)、Pi(提交71ac601)等新平台接入,并同步更新了 Quickstart 行与 Installation 小节。从当前 README 可见:这些后加平台并未被重新排进严格字母序(例如 Antigravity 排在 Claude Code 之后,而非列表最前),但 Quickstart 行与 Installation 小节的相对顺序始终保持一致——换言之,Phase C 沉淀下来作为硬约束的是两处列表同步,而严格字母序是那个时点对既有 8 项的归一化结果。这一细节恰好说明了设计文档Out of scope边界的意义:Phase C 的规则只约束它自己那次变更,后续每个新增平台如何插入列表,由各自的功能提交自行决定;只要两处列表保持同步,README 就不会出现链接跳到不存在的位置或列表顺序自相矛盾的状态。工程启示:连纯排序变更也值得一份规格把这篇 Phase C 规格(全文约 47 行)对照它的实施提交,可以得到几条可直接复用的经验:规格是范围边界,不是操作手册。全文没有一行第 7 行改成 XX,而是声明改哪些列表、不改哪些东西、按什么规则排、如何验收。实施者在执行时自行完成了具体的行级编辑,规格则保证了不越界——diff 中 29 删 29 增的对称性,就是边界被遵守的证明。字节级一致(byte-identical)是纯移动变更的精确验收用语。比起内容不变这种模糊表述,它可以直接翻译为 diff 特征(删除行与新增行一一对应),让验收从主观判断变成可执行的检查。多份同源列表必须原子同步。凡是同一事实集合在文档中重复出现两次的地方,排序/成员变更都应合并为单个提交,避免中间态不一致。选择机械可验证的规则(严格字母序)优于看起来合理的规则,并且要在文档中显式说明某平台排第一只是巧合——这为后续新增平台免除了争论空间。锚点是隐式契约。Quickstart 内联链接依赖标题文本生成的锚点,任何顺手改标题的冲动都会破坏跳转;规格中no headings renamed这一条,实际上是在保护一份文档内跨区域的链接完整性。这套文案中立(Phase A)→ 引用中立(Phase B)→ 布局中立(Phase C)的分阶段推进方式,加上每个阶段一份带验收标准的独立规格,展示了如何在不动功能代码的前提下,系统性地消除一份公开文档里的隐性平台偏向——其方法论本身,对任何多平台支持的项目都有参考价值。参考路径Phase C 设计文档(本文主体)Phase A 设计文档(通用文案中立化)Phase B 设计文档(配置文件引用中立化)README.md(被重排的对象,含 Quickstart 与 Installation 两处列表)skills/writing-skills/SKILL.md(Phase A 中 CSO→SDO 重命名的所在文件)【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考