hu3rror/my-skills

npm-release

Set up npm release automation: a GitHub Actions publish workflow that publishes to npmjs on tag push via Trusted Publisher (OIDC, zero tokens) — direct or staged.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/hu3rror/my-skills --skill npm-release

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

npm 包自动发布(Trusted Publisher + GitHub Actions)

为 npm 包项目落地"push v 标签 → 自动发布到 npmjs"的发布工作流。认证走 npmjs.com 的 Trusted Publisher(OIDC):workflow 内零 token、零 secret,并自动生成 provenance。本 skill 备两套发布流:直接流(tag push 即发布,无人工闸门,默认)与 暂存流*(CI 暂存,维护者本地 npm stage approve 2FA 放行,按仓库约定选用)。

执行须知(重要,先读)

npm 发布链路里有几步一旦执行就不可逆(git push --tags、npm publish、npm stage approve),而排查一次 401/403 往往要来回改 workflow、重新绑定 Trusted Publisher、重新 tag,比多花十秒核对便宜得多。所以本 skill 的每一步都按"先核对、再执行"的顺序写,执行前务必做到:

  • 每个"完成判据"都要用命令的实际输出核对,不要凭上一步的记忆判断"应该没问题"。 例如步骤 1 摸底完的每一项,都应该是刚跑完对应命令、亲眼看到输出后填的值,而不是根据文件名或项目类型推测的。
  • 命令与旗标只从本 skill 正文、[references/workflow-template.yml](references/workflow-template.yml)、[references/workflow-template-staged.yml](references/workflow-template-staged.yml)、[references/troubleshooting.md](references/troubleshooting.md) 里取,不要凭印象改写或补充(尤其是 `npm stage` 子命令和 `gh` 参数)。 这两个工具改动较快,凭记忆拼出的旗标很容易是过时或不存在的;不确定时先 npm stage --help / npm publish --help / gh release create --help 核实存在,再使用。
  • git push / npm publish / npm stage approve、以及 `gh release create`/`edit`(写发布说明,对外发布)这类不可逆或对外操作前,先把"我即将执行 X,因为 Y"说给用户听一遍,拿到当轮的明确授权再动手,不要因为前面步骤顺利就自动往下推进到发布。
  • 遇到报错时,先去 references/troubleshooting.md 按症状查,不要凭经验改一个旗标就重试——同一条错误往往有好几种表面相似但处理方式不同的原因(比如 401 既可能是 token 权限边界,也可能是 workflow 文件名不匹配)。

步骤

1. 摸底

完成判据:下面每一项都已实际执行对应命令并记下输出,而不是靠猜测填的。 逐项核对:

  • cat package.json:name / version / repository 字段 / files / scripts(有无 test、根目录有无 package-lock.json)
  • gh repo view --json visibility:仓库可见性(provenance 需要 public)
  • npm view <name> version:包是否已存在于 npm(决定是否触发"新包首发"例外,见"定制点"与故障排查里的"新包首发")
  • ls .github/workflows/:CI 现状,是否已有同名 workflow 会冲突
  • 读 package.json 的 scripts.test(以及它调用到的构建脚本):是否依赖 Windows PowerShell / System.Drawing 等平台特性,决定步骤 4 的 runs-on

2. 确认发布方式

完成判据:用户明确确认用哪一套。 默认直接流。仅当项目 AGENTS.md 明确要求"发布由维护者亲自执行/人工闸门"时选暂存流(stage)。选定后记入步骤 8 的项目文档;从暂存流切到直接流(或反之)需用户明确同意并同步步骤 8。

3. 配置 Trusted Publisher(仅用户可做)

完成判据:用户确认在 npmjs.com 配置完成。 给用户列出操作,不代操作:

  • 前置:包已存在于 registry、仓库公开
  • npmjs.com → 包 Access → Publishing access → Trusted publishers,绑定仓库 owner/repo + workflow 文件名(必须与步骤 4 生成的文件名一致,如 `publish.yml`)
  • Allowed actions 按所选流核对(npmjs 把 npm stage publish 与 npm publish 设为独立权限):直接流需勾选 Allow npm publish,否则 CI 直接发布会 401/403(见 troubleshooting「Trusted Publisher 未允许直接发布」);暂存流下 npm stage publish 恒允许,无需额外勾选

4. 生成 publish.yml

完成判据:文件就位且每个定制点已核对。 按步骤 2 选定的流复制对应模板到 .github/workflows/:直接流用 references/workflow-template.yml,暂存流用 references/workflow-template-staged.yml,按"定制点"逐项调整。两模板除发布步骤与 permissions 外结构一致。

5. 本地验证

完成判据:项目测试全绿(workflow 含测试步骤时);无测试则跳过并在交付说明中注明。 检查构建脚本路径探测是否可移植(os.homedir() 而非 USERPROFILE,否则 Linux runner 崩溃——见 references/troubleshooting.md)。

6. 演练

完成判据:一次 tag push 跑通到发布/暂存,且用 gh run view 的实际输出确认成功(不是"应该跑完了")。

  1. 定版本号,再 bump。 semver 三问逐条过,档位由结论推出:
  • 破坏?调用方依赖的契约被改(tool/command 的参数、schema、details 形状,或移除了什么)→ major;
  • 新能力?调用方能调起以前调不起的东西(新 tool/command/参数/schema/入口)→ minor;
  • 都不是 → patch。修复错误信号、类型对齐、纯内部重构都算 patch——把行为修对正是 patch 的语义;SDK 对齐(sync)类发布默认 patch。

把"档位 + 一句话理由"陈述给用户(push 授权同轮即可),再改 package.json version。 完成判据:档位与三问结论一致且已陈述给用户。

  1. bump 版本(package.json version)→ commit。多行 commit message 用 git commit -F <临时文件> 提交(PowerShell 双引号会拆坏内嵌引号/换行的多行消息);gh 的 --json + jq 过滤器在 PowerShell 里用单引号包裹,避免 " 转义问题。
  2. 查既有 tag 是否签名(git for-each-ref refs/tags/<上一版本tag> --format="%(contents:signature)",非空即签名):既有 tag 签名时直接 git tag -a vX.Y.Z -m "vX.Y.Z"(gpg-agent 缓存了 passphrase 时能直接成功,失败超时按故障排查处理);既有 tag 未签名时用 git -c tag.gpgsign=false tag -a vX.Y.Z -m "vX.Y.Z" 保持一致。
  3. push 前先向用户复述一句"即将 push main 分支 + tag vX.Y.Z,会触发发布 workflow",拿到当轮授权后再执行:git push origin main + git push origin refs/tags/vX.Y.Z(push 属受限操作)。
  4. gh run watch 跟随本次 run,run 结束后额外 gh run view --log-failed(即使显示成功也建议扫一眼,确认没有静默跳过的 step)。
  5. 直接流:确认 npm publish 成功(run 结束后第 5 步已扫过 --log-failed)再 npm view <name> version 核实新版本已可见。暂存流:从日志取 stage-id——gh run view <id> --log | Select-String "staged with id",行格式 + <name>@<version> (staged with id <uuid>);stage-id 交付给用户,approve/reject 由用户本人执行(见"后续人工步骤",需 2FA)。

7. 发布说明(Release Notes)

完成判据:GitHub Release 里有分类整理过的说明(写入前已展示全文并取得当轮授权,见执行须知),而不只是 gh release create --generate-notes 生成的 Full Changelog: vX...vY 一行比较链接。 按 write-release-notes skill 写发布说明:素材、分类模板、展示确认、create/edit、验证都在那里,版本号直接用步骤 6 bump 出的 vX.Y.Z。npm 差异就一条:直接流下 workflow 已建占位 Release(--generate-notes),步骤 6 发布成功后 gh release edit 覆盖为分类说明;暂存流下 workflow 不建 Release,维护者 approve 发布后由 agent 手动 gh release create。两种流的 Release 写入都是对外发布:先按 write-release-notes 步骤 4 展示分类说明全文、拿到当轮授权,再 create/edit(执行须知)。仓库若约定不建 Release,跳过与否按 write-release-notes 步骤 1 的仓库约定检查执行。

8. 沉淀

完成判据:AGENTS.md 发布约定与相关文档已同步。 更新 AGENTS.md 发布约定段:触发条件、谁负责 bump/tag/push、发布闸门(直接流全自动 / 暂存流 approve 2FA)、错误回滚(直接流 npm unpublish <version>,72 小时内可撤回,超期用 npm deprecate;暂存流 npm stage reject 发布前可撤回)、发布说明由 agent 在步骤 7 撰写(而非只依赖 CI 自动生成)。仓库有 GLOSSARY.md 等领域文档时补发布流词条。

定制点

生成 workflow 时逐项核对:

  • 触发 tag 模式:仓库约定(如 v*)与 package.json version 的对应;保留模板内 tag↔版本一致性校验
  • node 版本:setup-node node-version;模板默认 Node 24(LTS,自带 npm ≥ 11.17)。暂存流需 npm 11.15.0+(官方要求,Node 22 系只带 npm 10 不满足);直接流无 npm 11 门槛(provenance 需 npm 9.5.0+)
  • runner:默认 ubuntu-latest;测试依赖 Windows 特性(PowerShell/System.Drawing)时 windows-latest
  • 依赖安装:有 package-lock.json 用 npm ci,无则 npm install
  • 测试命令:有测试则在 workflow 内跑;构建脚本需工具路径时在该 step 加 env(如 PI_ESBUILD_DIR)
  • 认证:Trusted Publishing 下零 token(setup-node v7 起不再注入 dummy NODE_AUTH_TOKEN,OIDC 流更干净);仅当项目坚持 GAT token 认证时才需要 NODE_AUTH_TOKEN env + secret
  • 发布说明:直接流模板保留 gh release create --generate-notes 兜底步骤;暂存流模板不建(发布前版本未真正发布),approve 后由 agent 手动 gh release create。正式分类说明按步骤 7 撰写,用 gh release edit 覆盖占位内容

后续人工步骤(暂存流)

bash
npm stage download <stage-id>   # 可选:发布前检查 tarball
npm stage approve <stage-id>    # 2FA 后真正发布
npm stage reject <stage-id>     # 错误暂存回滚

Related skills

  • my-pi-extension-maintenance — 当本次发布是为了发布一次 pi SDK 同步(版本对齐/镜像语义跟进)时,验收要点(行为变化无法避免时才需用户确认、README 兼容性说明)在 maintenance skill 里;发布前先用它核对改动是否齐整。SDK 同步/类型修复类发布默认 patch(semver 三问见步骤 6)。
来自同一仓库

更多 Skills

全部 Skills