npm Stage-only Token 能直接给 AI Agent 发包吗？2026 验收

本周建议动作： 让 Agent 只执行构建、测试和 npm stage publish，由维护者独立检查暂存包并用 2FA 批准；如果你的 CI 已满足 OIDC 条件，优先评估 Trusted Publishing，而不是继续扩大长期写令牌的权限。

最后更新于 2026 年 9 月 19 日，本文信息核实自 npm staged publishing、访问令牌、Trusted Publishing 文档，以及 2026 年 9 月的官方变更记录。

1适用团队与验收边界

这篇文章适合允许 AI Coding Agent 自动修改代码、打包或准备 npm 版本，但不希望 Agent 获得最终发布权的开源维护者与研发团队。

如果你负责 CI/CD、GitHub Actions、远程 Mac 构建、跨平台二进制或原生依赖发布，本文重点是帮你拆开三种身份：代码与构建身份、暂存提交身份、正式批准身份。需要了解临时 Mac 构建环境的团队，也可以先查看 远程 Mac 使用说明，再对照本文检查凭据边界。

先把判断说清楚：

• ✅ 可以启用： Agent 创建提交、运行测试、生成 tarball，并用 Stage-only Token 执行 npm stage publish。
• ❌ 不能假设： Stage-only Token 等于只读权限，或等于“Agent 无法修改任何包状态”。
• ⚠️ 必须保留： 维护者的人工复核、2FA 批准、可追溯构建记录与可撤销凭据。

npm 的官方定义是，Stage-only Token 只能把版本放入暂存区，维护者之后再审核和批准；直接执行 npm publish 会失败，并返回 E_STAGE_REQUIRED。但同一令牌仍保留移动 dist-tag 和弃用版本等写操作。(npm 访问令牌文档)

2发布时间线：从代码生成到正式公开

你可以把一次 AI Agent 发包拆成下面这条时间线，而不是把“Agent 运行成功”当成“版本已经安全发布”。

T0：代码生成与提交。 Agent 修改源代码、锁文件、构建配置和测试文件。此时它不应接触维护者的 2FA，也不应拥有用于最终批准的会话。

T1：构建与测试。 CI 或远程 Mac 安装依赖、执行构建、生成平台产物并运行测试。构建结果要绑定仓库提交、工作区标识和运行日志，不能只保留 Agent 的文字总结。

T2：暂存提交。 自动化使用 Stage-only Token 执行 npm stage publish。这个动作不需要 2FA，版本会进入暂存区域，但不会立即对公开安装生效。npm CLI 的 staged publishing 文档明确要求，暂存发布与正式批准是两个不同步骤。(npm staged publishing 文档)

T3：人工复核。 维护者查看暂存版本、下载 tarball，检查版本号、文件清单、入口字段、许可证、构建产物和变更范围。

T4：正式批准。 维护者使用 CLI 或网页完成批准，并通过交互式 2FA。只有这一步完成后，版本才进入公开可用状态。

因此，Stage-only Token 对直接公开发布动作形成了阻断，但它并没有把 Agent 变成完全没有写权限的执行者。

注意： 暂存区不是自动安全区。它只延后“新版本进入公开仓库”的动作，不会替你检查包内是否混入调试文件、密钥、错误依赖或不应发布的构建目录。

3维护者：暂存版本与正式责任

维护者最容易犯的错误，是看到暂存成功、测试通过，就把批准动作当成形式操作。实际上，Stage-only Token 的价值正是把最终责任重新交回人，而不是替你完成审核。

你至少要独立检查以下内容：

• 版本号是否符合当前发布计划，是否意外跳过补丁或主版本。
• npm pack --dry-run 预期文件与暂存 tarball 是否一致。
• package.json 的 main、module、exports、bin 和 files 字段是否指向正确产物。
• 构建结果是否来自目标提交，而不是工作区残留或 Agent 上一次任务的缓存。
• 是否包含 .env、私钥、测试数据、内部脚本、源码地图或不应公开的原生构建文件。
• 变更是否超出本次任务范围，尤其要检查 Agent 是否修改了发布脚本、依赖源和权限配置。
• 暂存记录是否能对应到仓库提交、构建日志、测试结果和操作者身份。

官方 staged publishing 流程支持列出暂存版本、查看暂存详情和下载 tarball，再由维护者批准或拒绝。你应把这些动作产生的记录保存到发布审计目录，而不是只依赖网页上的当前状态。

对于低风险工具包，可以先采用“Agent 暂存、单人 2FA 批准”。如果包被大量项目依赖、包含安装脚本、原生二进制或供应链影响范围较大，则应增加独立复测和双人审核。

4AI Coding Agent：动作范围与剩余权限

采用 staged publishing 后，最终批准仍需要维护者完成 2FA；Agent 只负责暂存，不负责证明人在场，也不能把批准环节隐藏在自动化脚本中。

你需要重点审查的不是提示词写得多安全，而是 Agent 实际拿到的工具和脚本：

• 是否能直接调用 npm publish、npm deprecate 或 dist-tag 相关命令。
• 是否能读取仓库外的 .npmrc、环境变量、缓存目录和其他项目凭据。
• 是否能修改发布工作流、切换包名、替换 registry 或改变构建来源。
• 是否能把 Stage-only Token 传给子 Agent、外部脚本或日志采集器。
• 是否能在同一任务中访问多个包，而令牌实际被授予了过宽的包范围。

npm 的访问令牌可以限制包或 scope，也可以只选择指定包；官方文档显示，创建 granular token 时可在“所有包”和限定包之间选择，限定范围最多可选择 50 个包或 scope。这个限制不是自动出现的，你必须在令牌创建和定期复核时主动选择。(npm 创建访问令牌文档)

建议每个自动发布任务都绑定独立工作区、独立分支或临时目录，并保留以下证据：

1. Agent 读取的提交哈希。
2. 构建命令与 Node.js、npm CLI 版本。
3. 测试报告和生成文件清单。
4. npm stage publish 的暂存标识。
5. 任务结束后的令牌撤销、环境销毁或工作区清理记录。

如果 Agent 只能完成代码生成，却能通过隐藏脚本移动 dist-tag，那么你的权限边界仍然没有成立。

5Stage-only Token 与 Trusted Publishing

npm 暂存发布和 Trusted Publishing 的选择，取决于你的 CI 类型、Runner 环境和是否能接受人工批准，而不是简单比较“令牌”和“OIDC”哪个听起来更安全。

Stage-only Token 更适合以下情况：

• 现有流水线暂时无法使用受支持的 OIDC。
• 你需要快速把直接发布改造成暂存发布。
• 构建环境或内部 CI 仍依赖传统环境变量认证。
• 团队已经有令牌轮换、IP 限制、日志脱敏和撤销流程。

但它仍是长期凭据，泄露后攻击者可以尝试执行其他允许的包写操作。因此，令牌应限制到目标包，并在 CI 日志、缓存、工作区快照和 Agent 上下文中排除。

Trusted Publishing 更适合以下情况：

• 你使用受支持的 GitHub Actions 云端 Runner、GitLab CI/CD 共享 Runner 或 CircleCI 云环境。
• 工作流可以配置 OIDC 身份，并且 npm 包侧能够精确匹配仓库、工作流和环境。
• 你希望减少长期 npm 写令牌的暴露与轮换成本。
• 你仍然愿意保留 staged publishing 的人工批准步骤。

npm 官方 Trusted Publishing 文档目前列出的支持范围包括 GitHub Actions 的云端 Runner、GitLab.com 共享 Runner 和 CircleCI 云环境；自托管 Runner 当前不在支持范围内。Trusted Publishing 使用短期 OIDC 凭据，但 npm stage approve、npm stage reject 等需要交互式身份确认的动作仍不能靠 OIDC 自动完成。(npm Trusted Publishing 文档)

2026 年 9 月的更新还允许同一个包配置多个 Trusted Publisher，并建议将配置默认限制为暂存。每个配置都独立匹配仓库、工作流和环境，不能把“配置数量增加”误解为“权限自动互相限制”。(GitHub 关于 npm Trusted Publishing 的更新)

你的迁移结论可以这样定：

• 保留令牌： OIDC 不适用于当前 Runner，且已完成令牌最小化和泄露演练。
• 迁移 OIDC： 使用受支持的云端 CI，并能把 workflow、environment 与包授权绑定。
• 双轨运行： 先让 OIDC 负责暂存、旧令牌只保留回退用途，完成几轮可复核发布后再撤销旧令牌。

6安全团队：四类必须留存的证据

安全团队验收时，不要只测试“直接 npm publish 是否失败”。这只能证明一个动作被收窄，不能证明令牌、环境和包权限都处于最小范围。

建议至少完成下面四组测试：

直接发布拒绝

使用 Stage-only Token 执行 npm publish，确认操作被拒绝，并保存命令输出、时间、包名和令牌标识。官方文档定义的失败结果是 E_STAGE_REQUIRED，但你仍应在自己的 CLI 版本和工作流中复现，而不是只引用文档。(npm 访问令牌文档)

暂存包可复核

执行 npm stage publish 后，使用维护者身份列出暂存记录，查看 stage 详情并下载 tarball。检查下载内容与构建日志是否一致，确认批准前版本没有进入公开安装路径。

剩余写权限受控

单独测试 dist-tag 移动、版本弃用和其他包管理动作。测试时使用无害的测试包或受控标签，禁止直接在高影响生产包上试错。Stage-only Token 不是“只允许上传 tarball”的权限模型，官方已明确列出其仍保留部分写权限。

凭据边界可证明

检查令牌是否出现在：

• CI 日志和失败堆栈。
• npm 缓存、构建缓存和工作区快照。
• 远程执行平台的任务输出。
• Agent 的工具调用上下文和子任务参数。
• 生成的诊断包、压缩包或错误报告。

同时保存撤销与轮换记录。没有撤销证据的“令牌已清理”只能算口头声明。

7远程 Mac：构建环境与批准身份分离

远程 Mac 构建 npm 包时，令牌应该放在哪里？暂存身份可以短时注入构建任务，但维护者的 2FA、批准会话和最终发布凭据不应保存在同一台构建主机或同一任务目录。

当项目包含 macOS 原生依赖、跨平台二进制、Swift 辅助工具或 Apple 工具链时，远程 Mac 可以负责：

• 检出指定提交。
• 安装固定版本的依赖。
• 生成 macOS 产物和 npm tarball。
• 执行平台测试。
• 使用暂存身份提交待审核版本。

但它不应负责最终批准。你需要把“构建主机”和“审批设备”拆开，并在任务结束时清理：

• 环境变量中的 npm 凭据。
• 临时 .npmrc。
• shell 历史记录。
• npm 缓存中的认证配置。
• 工作区、压缩包和任务快照。
• Agent 可继续访问的子任务上下文。

如果你还没有固定远程构建和清理流程，可以参考 远程 Mac 构建指南，再把暂存 tarball、源码提交、构建日志和测试结果绑定为同一份交付记录。若无法证明这些记录一一对应，就不应仅凭 Agent 报告批准发布。

8发布验收清单

下面这份清单适合在试点前逐项打勾。任意一项无法完成，都应暂停扩大范围。

• [ ] Stage-only Token 只授权目标包，没有默认覆盖全部可管理包。
• [ ] Agent 执行 npm publish 时确实被拒绝，并保存了 E_STAGE_REQUIRED 证据。
• [ ] Agent 只能执行构建、测试和 npm stage publish，不能调用最终批准流程。
• [ ] 维护者可以列出、查看并下载暂存版本。
• [ ] 暂存 tarball 能对应到明确的仓库提交和构建记录。
• [ ] 版本号、产物文件清单、入口字段和依赖范围经过人工检查。
• [ ] 已单独测试 dist-tag、弃用版本等剩余写权限。
• [ ] 令牌不会进入日志、缓存、快照或子 Agent 上下文。
• [ ] 维护者的 2FA 不在远程 Mac 或无人值守 Runner 中保存。
• [ ] 任务完成后能证明凭据、临时 .npmrc 和工作区已清理。
• [ ] 已建立令牌撤销、轮换和异常发布回退流程。
• [ ] 高影响包有独立复测或双人审核，而不是单人批准。
• [ ] 如果使用 OIDC，已核对 Runner 类型、id-token: write、工作流文件和环境条件。
• [ ] 团队明确知道 2027 年 1 月是 npm 计划移除 bypass-2FA 令牌直接发布能力的目标时间，而不是不可变的服务承诺。(npm 访问令牌文档)

9分组启用：低风险先行，高影响回退

发布负责人可以按风险分三组，而不是一次性把所有包交给 Agent。

低风险包： Agent 生成代码、构建并暂存，维护者检查 tarball 后用 2FA 批准。适合先验证流程记录、凭据清理和失败回退。

中风险包： 在上述流程中加入独立测试任务、产物哈希核对和发布前差异检查。涉及原生依赖、安装脚本或跨平台二进制时，远程 Mac 构建必须单独记录。

高影响包： 使用 Trusted Publishing 或严格限定的 Stage-only Token，保留独立复测、双人审核和可撤销发布窗口。无法隔离凭据、无法还原产物来源，或无法证明直接发布已被拒绝的团队，应继续人工发布，不要为了自动化指标强行启用。

你最终应从三种结论中选一种：

• 有限开放： 仅允许低风险包采用 Agent 暂存。
• 双轨迁移： OIDC 负责受支持 CI 的暂存，Stage-only Token 作为受控回退。
• 继续人工发布： 当前环境无法隔离批准身份或保存完整证据。

与继续使用一个拥有长期写权限的传统发布令牌相比，当前方案的真实缺点通常是：权限覆盖面更大、泄露后持续时间更长、轮换依赖人工、Agent 很难证明自己没有访问到额外上下文。对于需要 macOS 原生工具链的团队，临时远程 Mac 如果没有工作区清理和凭据隔离，同样会把构建环境变成新的风险点。

此时，租赁 vpstix 的 Mac 作为短期隔离构建环境，比把维护者 2FA 和长期发布令牌长期留在共享主机上更容易控制边界；但它仍不能替代 npm 暂存、人工批准和 OIDC 权限验收。你可以先通过本文前面的远程 Mac 资料了解交付边界，再按清单决定试点范围。

如果你的发布流程包含 macOS 原生依赖、无人值守构建或 AI Agent 自动准备版本，先把暂存身份、批准身份和构建主机拆开，再考虑扩大自动化覆盖面。