| name | npm-workspace-publish |
| description | 批量发布 pnpm/npm workspace 内的公开包到 npm 官方 registry。包含 macOS/Linux 用的 bash 脚本和 Windows 用的 PowerShell 脚本,按依赖顺序逐包 build + publish,自动检查登录状态与官方 registry,跳过 private 包。Use whenever the user wants to publish monorepo packages to npm, says 发布包/发包/npm publish/publish packages/workspace 发布, or wants a reusable publish script for @agent-spaces or any workspace repo. |
npm-workspace-publish
批量发布 workspace 内的公开包到 npm 官方 registry。提供两个平台脚本,用户在交互终端自行执行(自己处理登录/OTP)。
何时触发
用户说以下任意一种时加载本 skill:
- "发布包到 npm" / "发包" / "把这几个包发上去"
- "写个发布脚本" / "批量 publish"
- 在 monorepo/workspace 语境下提到
npm publish / pnpm publish
- 想给
@agent-spaces 或任意 workspace 做可复用发布流程
核心流程
所有脚本逻辑一致,顺序固定:
- 切到仓库根 — 脚本自带定位逻辑(支持 git rev-parse 兜底)
- 检查 registry — 非官方(
https://registry.npmjs.org/)时提示并询问是否切换
- 检查登录态 —
npm whoami;未登录则 npm login --auth-type=web(浏览器授权)
- 按依赖顺序逐包:
- 读
package.json,private: true → 跳过并提示
pnpm --filter <name> buildpnpm --filter <name> publish --no-git-checks --access publicnpm view <name>@<version> 校验是否上架(失败不阻断)
- 任一步失败立即退出(
set -e / $ErrorActionPreference = "Stop")
依赖顺序:被依赖的包先发。@agent-spaces 默认 shared → sdk → server,web 是 private 跳过。workspace 依赖写为 workspace:*,pnpm publish 时会自动替换为实际版本号。
脚本位置与使用
本 skill 自带两个脚本,位于 scripts/:
| 平台 | 脚本 | 命令 |
|---|
| macOS / Linux | publish-packages.sh | ./publish-packages.sh |
| Windows PowerShell | publish-packages.ps1 | ./publish-packages.ps1 |
脚本路径(相对仓库根):.agents/skills/npm-workspace-publish/scripts/
复用到其他仓库
两个脚本不绑定 @agent-spaces,改脚本顶部的默认包列表即可:
- bash:
PACKAGES=(shared sdk server)
- ps1:
-Packages @("shared", "sdk", "server")
PowerShell 还支持参数化: ./publish-packages.ps1 -Packages shared,sdk -DryRun
OTP / 2FA 说明
npm 账号开启 2FA 时:
- 交互终端(推荐):
pnpm publish 会提示输入 6 位码,或自动打开浏览器授权。脚本在交互终端跑就能正常弹。
- 非交互终端(如 agent 自动化):npm 出于安全把 OTP 授权 URL 截断成
***,自动弹浏览器会失败。此时必须由用户在交互终端运行,或改用 automation granular token(见下方)。
若要在 CI/agent 环境免 OTP 自动发布:在 npmjs.com 创建 Automation Granular Access Token(限定到具体包+发布权限),设为环境变量 NODE_AUTH_TOKEN,然后把 publish 命令里的认证方式改为 token。
关键约束
- 不自动改版本号:发版前版本号由用户自行决定(
pnpm version patch 或手动改 package.json)。脚本只读 version 字段做展示和校验。
- 不跳过 private 检查:npm 不允许发布名为
<scope>/xxx 的 private 包到公共 registry,脚本遇到 private: true 会跳过并提示,不要试图绕过。
- registry 必须官方:避免误发到私有/镜像源。脚本会校验并在非官方时询问。
- 失败即停:某个包 build 或 publish 失败,脚本立即退出,已成功发布的包不受影响,失败包可修后重跑。
常见异常
| 现象 | 原因 | 处理 |
|---|
EOTP / requires one-time password | 账号开了 2FA | 在交互终端运行脚本,按提示输 6 位码 |
E403 You cannot publish over | 该版本号已发布过 | 先 bump 版本号再跑 |
OTP URL 显示成 *** 打不开 | 非交互终端,npm 截断敏感链接 | 改在用户自己的终端跑脚本 |
EPERM / operation not permitted | registry 非官方或权限不足 | 确认 npm config get registry 为官方,且登录账号对该 scope 有权限 |
| 脚本找不到仓库根 | 层级不匹配 | bash/ps1 脚本均有 git rev-parse --show-toplevel 兜底 |
示例输出
==> 检查 npm 登录状态...
已登录:hunmer (registry: https://registry.npmjs.org/)
================================================ = =
==> [shared] @agent-spaces/shared@0.2.3
================================================ = =
[1/2] build...
[2/2] publish...
✓ @agent-spaces/shared@0.2.3 发布完成
npm view 确认已上架
...
全部完成:
@agent-spaces/shared@0.2.3
@agent-spaces/sdk@0.1.1
@agent-spaces/server@0.4.6
