官方插件

官方插件由 pubm 团队一起维护，发布节奏和兼容性要求也与核心项目一致。如果你想直接接入一个维护良好的集成，而不是从头写自己的 plugin，就选它们。

@pubm/plugin-brew

@pubm/plugin-brew 帮助 CLI 项目在每次发布时同步 Homebrew formula。若 PR 已经创建而流水线随后失败，它会登记回滚操作，把那条 Homebrew PR 关掉。

适合的场景

• 通过 Homebrew 分发 CLI 二进制
• 自动更新独立的 tap 仓库
• 保持 formula 的 checksum 与 release assets 对齐

常见配置

import { defineConfig } from "@pubm/core";
import { brewTap } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewTap({
      formula: "Formula/my-tool.rb",
      repo: "https://github.com/my-org/homebrew-tap",
    }),
  ],
});

选项

Option	Type	Description
formula	string	相对于仓库根目录的 formula 路径。
repo	string	可选的远程 tap 仓库 URL。省略时使用当前仓库。
packageName	string	可选的 package 名称过滤器。设置后，插件只会作用于与该 package 名称匹配的发布。适合 monorepo。
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	可选的自定义平台匹配器。会覆盖默认的 os + arch 匹配逻辑。

平台匹配

插件会使用每个 ReleaseAsset 中结构化的 ParsedPlatform 数据，将资产匹配到 formula 的平台条目。默认匹配逻辑覆盖四个平台：

Formula key	匹配条件
darwin-arm64	asset.platform.os === "darwin" && asset.platform.arch === "arm64"
darwin-x64	asset.platform.os === "darwin" && asset.platform.arch === "x64"
linux-arm64	asset.platform.os === "linux" && asset.platform.arch === "arm64"
linux-x64	asset.platform.os === "linux" && asset.platform.arch === "x64"

这取代了之前靠字符串去猜 asset 名称的做法，例如 asset.name.includes("darwin-arm64")。一旦名称改动，旧方法就很容易失效。

自定义平台匹配器

默认的 os + arch 匹配不够用时，就用 assetPlatforms。例如，你只想让 Linux 走 musl 构建：

brewTap({
  formula: "Formula/mytool.rb",
  assetPlatforms: {
    "darwin-arm64": (asset) =>
      asset.platform.os === "darwin" && asset.platform.arch === "arm64",
    "linux-x64": (asset) =>
      asset.platform.os === "linux" &&
      asset.platform.arch === "x64" &&
      asset.platform.abi === "musl",
  },
})

每个谓词都会接收一个 ReleaseAsset，并在该 formula 条目应该使用该资产时返回 true。

凭证与 preflight 检查

@pubm/plugin-brew 会自动声明它需要的凭证和检查，不必手动补配置。

必需凭证：

环境变量	GitHub Secret 名称	用途
PUBM_BREW_GITHUB_TOKEN	PUBM_BREW_GITHUB_TOKEN	带有 repo scope 的 GitHub Personal Access Token，用于推送 formula 更新并创建 pull request。

本地运行时，pubm 会提示输入这个 token，并把它存到系统 keyring。CI 中则通过 PUBM_BREW_GITHUB_TOKEN 环境变量提供。运行 pubm --mode ci --phase prepare 或 pubm secrets sync，可以把已保存的 token 同步到仓库的 GitHub Secrets，供 CI workflow 自动使用。

该插件还会注册一个 preflight check，在 publish 阶段开始前验证 token 是否存在以及是否具备所需的仓库访问权限。

功能

这个插件可以：

• 在 formula 不存在时创建骨架
• 使用结构化平台信息更新 release assets 的 url 和 sha256
• 提交并推送 formula 更改
• 当不适合直接 push 时，回退到 pull request 工作流

相关命令

pubm brew init

可用它根据 package metadata 生成一个起始 formula 骨架。

brewCore

如果你要向 homebrew-core 贡献内容，也就是默认的 Homebrew 仓库，请用 brewCore，不要用 brewTap：

import { brewCore } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewCore({
      formula: "Formula/my-tool.rb",
    }),
  ],
});

Option	Type	Description
formula	string	相对于仓库根目录的 formula 路径。
packageName	string	monorepo 的可选 package 名称过滤器。
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	可选的自定义平台匹配器。

brewCore 会 fork homebrew/homebrew-core，更新 formula，然后自动打开 PR。和 brewTap 一样，它也会自动声明 PUBM_BREW_GITHUB_TOKEN 凭证和对应的 preflight 检查。

@pubm/plugin-external-version-sync

这个插件用于让非 manifest 文件和 package 版本保持一致。若版本同步后流水线失败，它会登记回滚操作，恢复原始文件内容。

当一次发布还要顺带更新这些内容时，就用它：

• README.md 中的安装片段
• 文档示例
• 应用 manifest
• 源码常量
• 元数据 JSON 文件

常见配置

import { defineConfig } from "@pubm/core";
import { externalVersionSync } from "@pubm/plugin-external-version-sync";

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        {
          file: "src/constants.ts",
          pattern: /export const VERSION = "([^"]+)";/,
        },
        {
          file: "manifest.json",
          jsonPath: "metadata.version",
        },
        {
          file: "README.md",
          pattern: /pubm@([\\w.-]+)/,
        },
      ],
    }),
  ],
});

目标类型

regex

适用于任意文本文件：

{
  file: "README.md",
  pattern: /pubm@([\\w.-]+)/,
}

要求：

• 模式必须用且只用一个 capturing group 把版本提取出来
• 文件格式要稳定，这样发布自动化才能安全更新

json

适用于可机器读取的 manifest：

{
  file: "manifest.json",
  jsonPath: "metadata.version",
}

何时使用 pubm sync --discover

如果你不确定仓库里版本字符串出现在哪里，可以运行：

pubm sync --discover

这个命令会扫描可能的版本引用，并输出可用的候选文件和路径，方便你改成 plugin 配置。

何时选官方插件，何时选自定义插件

在这些情况下，优先用官方插件：

• 你的需求已经有现成的集成
• 你希望维护成本更低
• 发布路径足够常见，值得标准化

在这些情况下，再编写自定义插件：

• 你的 registry 或发布后工作流是组织特定的
• 你需要自定义 policy 或部署逻辑
• 你想为操作人员提供额外的 CLI 命令

如果你想扩展到官方集合之外，请阅读 Plugins API Reference。

面向 coding agent 的设置自动化

运行时插件只是其中一部分。这个仓库还在 plugins/pubm-plugin/skills/* 下提供了一个 pubm plugin bundle，供 coding-agent 工作流使用，例如：

• 发布 setup
• preview-first 的发布辅助
• version-sync 发现
• plugin 搭建

如果你正在把 pubm 接到 agent 环境里，就把运行时插件和这些 skill 风格的资源一起用，这样 setup 和 publish 流程会更明确，也更容易重复。

阅读 Coding Agent Integration 指南了解集成布局。