要将 Superpowers 主仓库的版本更新与 Codex 插件市场的分发同步自动化，需依赖 bump-version.sh 和 sync-to-codex-plugin.sh 两个核心脚本。bump-version.sh 根据 .version-bump.json 配置文件，跨 package.json、.codex-plugin/plugin.json 等文件同步更新版本号，并扫描仓库发现“版本漂移”。sync-to-codex-plugin.sh 则将主仓库内被收录的技能和资源，通过 rsync 安全同步到独立的 Codex 插件仓库，并自动创建提交与 PR，完成从代码变更到市场发布的全链路自动化。

SuperPowers 版本同步脚本：bump-version 与 Codex 插件同步自动化

Superpowers 作为一个面向 coding agents 的技能库，其版本信息分散在仓库的多个清单文件中，例如根目录的 package.json 和面向特定平台的插件清单 .codex-plugin/plugin.json。手动维护这些版本号极易出错并导致“版本漂移”。同时，为了在 Codex 的插件市场中分发，需要将主仓库的特定内容同步到另一个独立的插件仓库。本文将详细讲解如何使用仓库内置的两个脚本 bump-version.sh 和 sync-to-codex-plugin.sh 来解决这两个痛点。

一、bump-version.sh：仓库内版本号同步与审计

bump-version.sh 脚本的核心使命是：当项目需要发布新版本时，确保所有声明文件中的版本字段被同步更新到同一个新版本，并扫描整个仓库，找出可能被遗漏的、未声明的版本字符串引用。

1.1 工作原理与配置文件

脚本的行为由根目录下的 .version-bump.json 文件控制。以下是其当前配置的核心部分：

{
  "files": [
    { "path": "package.json", "field": "version" },
    { "path": ".codex-plugin/plugin.json", "field": "version" },
    { "path": ".claude-plugin/plugin.json", "field": "version" },
    { "path": ".cursor-plugin/plugin.json", "field": "version" },
    { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
    { "path": "gemini-extension.json", "field": "version" }
  ],
  "audit": {
    "exclude": [
      "CHANGELOG.md",
      "RELEASE-NOTES.md",
      "node_modules",
      ".git",
      ".version-bump.json",
      "scripts/bump-version.sh"
    ]
  }
}

files 数组：声明了所有需要同步版本的文件及其字段路径。字段路径支持简单的 "version" 和嵌套的 "plugins.0.version"，脚本内部使用 read_json_field 和 write_json_field 这两个辅助函数，通过 jq 安全地读取和写入 JSON，保证格式不被破坏。
audit.exclude 数组：在审计阶段，grep 命令会跳过这些文件和目录，避免在变更日志、脚本自身等地方产生误报。

脚本内部的 declared_files 函数会解析此配置，生成用于遍历的路径和字段列表。

1.2 三种操作模式详解

脚本通过命令行参数提供三种主要操作模式：

步骤 1：检查版本漂移 (--check) 运行 ./scripts/bump-version.sh --check。脚本会遍历所有声明文件，使用 cmd_check 命令读取其版本号并列表显示。如果发现各文件版本不一致，会明确报告“DRIFT DETECTED”及各版本出现的文件数量。这是版本发布前的必要健康检查。

步骤 2：审计仓库 (--audit) 运行 ./scripts/bump-version.sh --audit。cmd_audit 命令会先执行一次 --check，然后确定当前主流版本号（多数文件使用的版本）。接着，它会用 grep 在整个仓库中扫描该版本字符串，并过滤掉 declared_files 函数返回的已声明文件列表。如果在其他文件（如文档、测试或配置脚本）中发现了该版本字符串，脚本会报告“UNDECLARED files”。这能帮你决定是将这些文件加入 files 列表，还是将它们加入 audit.exclude 列表。

步骤 3：执行版本升级 (bump) 要升级到新版本，例如 5.1.0，运行：

./scripts/bump-version.sh 5.1.0

cmd_bump 命令首先会用简单的 semver 正则表达式 ^[0-9]+\.[0-9]+\.[0-9]+ 校验输入格式。然后，它会逐一将 .version-bump.json 中声明的每个文件里的目标字段更新为 5.1.0。更新完成后，脚本会自动运行一次完整的 cmd_audit，以确保没有遗漏。例如，package.json 中的 "version": "5.0.7" 和 .codex-plugin/plugin.json 中的 "version": "5.0.7" 会被同时改为 "version": "5.1.0"。

二、sync-to-codex-plugin.sh：同步到 Codex 插件仓库并创建 PR

这个脚本的目标是将主仓库 (obra/superpowers) 中适用于 Codex 插件的文件，同步到一个名为 prime-radiant-inc/openai-codex-plugins 的 fork 仓库中。该 fork 仓库是 Codex 官方插件市场的上游源。

2.1 核心配置与排除规则

脚本顶部定义了关键配置，这些变量决定了同步的目标和范围：

FORK：目标仓库，即 prime-radiant-inc/openai-codex-plugins。
DEST_REL：在目标仓库中的同步目标路径，即 plugins/superpowers。
EXCLUDES 数组：定义了不应同步到目标仓库的文件和目录模式。这些模式必须以斜杠开头以锚定到源仓库根目录，防止误匹配嵌套目录。例如，/scripts/ 会排除主仓库根目录下的 scripts/ 目录，但不会影响 skills/brainstorming/scripts/ 这样的子目录。

EXCLUDES=(
  # 顶级点文件和基础设施
  "/.claude/"
  "/.codex/"
  "/.github/"
  "/.version-bump.json"
  ".DS_Store"
  # 根目录仪式性文件
  "/CHANGELOG.md"
  "/package.json"
  # 不随插件分发的目录
  "/scripts/"
  "/tests/"
  # ... 其他排除项
)

此列表确保了只有构成插件核心的技能文件、清单和资源被同步。

2.2 完整工作流：从预览到 PR 创建

脚本的执行流程高度自动化且具备幂等性（对同一上游提交运行两次应产生相同的 PR）。核心流程由 sync-to-codex-plugin.sh 脚本控制。

阶段一：预检与预览

环境检查：确认 rsync, git, gh (GitHub CLI) 和 python3 已安装且 gh 已认证。
读取上游信息：从主仓库的 .codex-plugin/plugin.json 中读取当前版本号 (UPSTREAM_VERSION) 和 HEAD 的短 SHA (UPSTREAM_SHORT)。
生成 PR 分支名：根据模式（正常同步或引导）生成带有时间戳的分支名，如 sync/superpowers-abc1234-20231201-120000 或 bootstrap/superpowers-abc1234-...。
构建 rsync 参数：基于 EXCLUDES 数组和 .gitignore 规则构建排除参数。
执行预览：无论是否指定 -n (--dry-run)，脚本都会先执行一次 rsync --dry-run，展示哪些文件将被添加、修改或删除。这能让用户确认同步内容无误。

阶段二：执行同步与创建 PR 如果用户确认（或使用 -y 跳过确认），脚本将：

克隆或准备目标仓库：如果没有提供 --local 路径，它会将 FORK 克隆到一个临时目录。
应用同步：在目标仓库中切换到 BASE 分支（默认为 main），然后创建新的同步分支，执行真正的 rsync，将主仓库的更新同步到 plugins/superpowers/ 目录。
检查变更：如果 rsync 后没有实际文件变更（即内容已同步），脚本会提前退出，避免创建无意义的 PR。
提交并推送：使用 git add、git commit 和 git push 将变更推送到 fork 仓库。提交信息包含上游的版本号、SHA 和 PR 创建命令的溯源信息。
创建 PR：通过 gh pr create 命令在 FORK 仓库自动创建一个 PR，请求合入 BASE 分支，并附上包含上游提交链接和同步命令的详细描述。

引导模式 (--bootstrap) 当目标仓库的 plugins/superpowers/ 目录尚不存在时，使用此模式。它会跳过目录存在性检查并创建该目录，常用于首次将插件内容初始化到目标仓库的场景。后续更新应使用普通同步模式。

三、测试验证：关键场景的保障

tests/codex-plugin-sync/test-sync-to-codex-plugin.sh 脚本通过模拟各种场景来验证同步脚本的健壮性。它覆盖了以下关键用例，确保自动化流程可靠：

预览验证：确保 dry-run 输出包含正确的版本号（来自 .codex-plugin/plugin.json 而非 package.json）、正确的文件列表（如 assets/app-icon.png），并排除了被忽略的文件（如 .private-journal/leak.txt）。
引导测试：验证 --bootstrap 模式能在目标目录不存在时正确创建它，并且在预览阶段不执行实际修改。
脏目录保护：当本地目标仓库的同步路径下有未提交的更改时，尝试应用 (-y) 会失败并报错，防止覆盖本地修改。
无操作合并：当目标仓库的插件内容已经与上游完全一致时，脚本能正确识别“无变更”并跳过提交和 PR 创建。
缺失清单：如果主仓库缺少 .codex-plugin/plugin.json 文件，脚本会提前终止并给出明确错误。

这套测试覆盖了首次引导、日常同步以及各种边缘情况，是维护跨仓库版本一致性和发布流程自动化的重要基石。

四、脚本协同工作流

典型的工作流如下：

开发完成后，更新代码并准备发布新版本。
使用 ./scripts/bump-version.sh 5.2.0 同步更新所有平台清单文件的版本号。
提交此版本变更。
运行 ./scripts/sync-to-codex-plugin.sh -n 预览同步内容，确认无误。
运行 ./scripts/sync-to-codex-plugin.sh -y 执行同步，自动向 Codex 插件仓库创建 PR。
在 Codex 插件仓库合并 PR，即完成一次市场发布。

FAQ

Q: 运行 bump-version.sh --audit 报告了很多未声明文件，该怎么办？ A: 审计脚本会列出所有包含当前版本字符串的文件。你需要检查这些文件：如果它们确实需要在版本更新时被修改（例如，一些配置或文档模板），应将它们添加到 .version-bump.json 的 files 数组中。如果它们只是历史记录或不应被修改（如测试快照文件），应将它们添加到 audit.exclude 数组中。

Q: sync-to-codex-plugin.sh 的“引导模式”和普通同步模式有什么区别？ A: 普通同步模式要求目标路径 (plugins/superpowers/) 在基础分支上已经存在。如果不存在，脚本会报错退出。引导模式 (--bootstrap) 会跳过此检查，并在目标路径不存在时主动创建它，适用于首次将插件内容初始化到目标仓库的场景。后续更新应使用普通同步模式。

Q: 为什么 sync-to-codex-plugin.sh 要求先运行 bump-version.sh 更新版本？ A: 因为 sync-to-codex-plugin.sh 会从主仓库的 .codex-plugin/plugin.json 中读取版本号 (UPSTREAM_VERSION) 用于 PR 的标题、提交信息和描述。如果版本未更新，同步到 Codex 插件仓库的代码将携带旧的版本标签，造成市场版本信息与代码不一致。两个脚本配合使用，确保了从版本号更新到市场发布的全链路自动化。

SuperPowers 版本同步脚本：bump-version 与 Codex 插件同步自动化 #

一、bump-version.sh：仓库内版本号同步与审计 #

1.1 工作原理与配置文件 #

1.2 三种操作模式详解 #

二、sync-to-codex-plugin.sh：同步到 Codex 插件仓库并创建 PR #

2.1 核心配置与排除规则 #

2.2 完整工作流：从预览到 PR 创建 #

三、测试验证：关键场景的保障 #

四、脚本协同工作流 #

FAQ #