---
title: "为编码代理设置七天依赖包发布冷却期"
canonical: "https://siyuanailab.com/curation/translations/60b45354b3be1bb80c6279c11d1ca85c-80b3fb095b0d9f44a8e1698bd24cb0c0a66816d0e374bfeed06867e48aaedfe8/"
dateModified: "2026-11-10"
datePublished: "2026-11-10"
---

[返回日报条目](https://siyuanailab.com/curation/#entry/60b45354b3be1bb80c6279c11d1ca85c)

 

资料节译

 

# 为编码代理设置七天依赖包发布冷却期

 

[阅读原文](https://dev.to/gabrielanhaia/make-your-coding-agent-wait-7-days-for-new-packages-npm-pnpm-yarn-bun-and-uv-1021)

 

现有资料无法确认原文完整，本页只翻译已取得的材料。

 

现有原件无法确认图片是否齐全。

 

-

 

## **书籍：**[AI That Acts](https://www.amazon.com/dp/B0HBTDV75G)

 

## **系列：***AI in TypeScript* —— 共 5 本书，从你的第一个 LLM 调用到投入生产的智能体 ——[五本都在这里](https://xgabriel.com/ai-in-typescript)

 

## **我的项目：**[Hermes IDE](https://hermes-ide.com/) |[GitHub](https://github.com/hermes-hq/hermes-ide) —— 一款面向使用 Claude Code 和其他 AI 编程工具交付软件的开发者的 IDE

 

**关于我：**[xgabriel.com](https://xgabriel.com/) |[GitHub](https://github.com/gabrielanhaia)

 

恶意版 chalk 发布后仅存活不到 12 小时。Nx 的恶意版本存活了约 4 小时，rspack 的约 1 小时。William Woodruff 梳理了十起知名供应链攻击，发现其中 8 起的可乘之机都不到一周（[他的文章](https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns)）。

 

把你的编程智能体放进这段窗口期里。它判断自己需要一个日期库，几秒后运行 `npm install`，注册表就会把最新版本交给它。没人审查过这个版本，扫描器也没有，连一小时前遭到钓鱼攻击的维护者也没有。

 

解决办法是设置发布时限门槛，也叫冷却期：拒绝任何发布未满 N 天的版本。npm、pnpm、Yarn、Bun 和 uv 现在都有这项功能。它们的配置写法各不相同，使用四种单位；其中一个在几个月前的 npm 版本上完全不起作用。

 

下面列出各包管理器中设置 7 天门槛的方法、配置文件以及引入该功能的版本。

 

| 包管理器 | 文件 | 键 | 单位 | 7 天 | 起始版本 |
| --- | --- | --- | --- | --- | --- |
| npm | `.npmrc` | `min-release-age` | 天 | `7` | 11.10.0 |
| pnpm | `pnpm-workspace.yaml` | `minimumReleaseAge` | 分钟 | `10080` | 10.16 |
| Yarn | `.yarnrc.yml` | `npmMinimalAgeGate` | 时长 | `"7d"` | 4.10.0 |
| Bun | `bunfig.toml` | `minimumReleaseAge` | 秒 | `604800` | 1.3 |
| uv | `pyproject.toml` | `exclude-newer` | 时长 | `"7 days"` | 0.9.17 |

 

各行资料来源：[npm 11.10.0](https://github.com/npm/cli/releases/tag/v11.10.0) 和 [npm 配置文档](https://docs.npmjs.com/cli/v11/using-npm/config)、[pnpm 10.16](https://pnpm.io/blog/releases/10.16)、[Yarn 的 PR #6901](https://github.com/yarnpkg/berry/pull/6901)、[Bun 1.3](https://bun.com/blog/bun-v1.3)、[uv 0.9.17](https://github.com/astral-sh/uv/releases/tag/0.9.17)。

 

单位弄错，门槛就会毫无用处，或者荒谬至极。`minimumReleaseAge: 7`在 pnpm 中是七分钟。`minimumReleaseAge = 7`在 Bun 中是七秒。`min-release-age=10080`在 npm 中则约为 27 年。

 

![An hourglass standing guard in front of a row of freshly delivered package boxes, holding them back while older boxes pass through a gate](/curation/media/e65181ad45b73df9341f9ceb139d8c83f4ffc1a295d15297291538f32220aaa1.webp)

 

*冷却期会让新版本先放置一周，在此期间，你的机器上任何内容都无法安装它。*

 

在 [npm](https://docs.npmjs.com/cli/v11/using-npm/config) 中，这道门槛只需在项目的 `.npmrc` 中添加一行。当前 npm 11 配置文档还列出了一个 exclude 键，可通过名称或 glob 排除你自己的包：

 

```
# .npmrc (commit this one)
min-release-age=7
min-release-age-exclude[]=@myorg/*
```

 

文档称，npm“会构建 npm 依赖树，只安装在指定天数之前就已发布的版本”；如果没有符合条件的版本，“命令就会报错”。如果 `npm audit fix` 因为修复后的版本太新而被拦下，npm 会保留有漏洞的版本、发出警告并以非零状态码退出。这时你就该有意将该包加入排除列表。

 

只排除你在公共注册表上拥有的作用域。[npm 配置文档](https://docs.npmjs.com/cli/v11/using-npm/config)称，你应当在该注册表上拥有自己的私有作用域，“这样其他人就无法发布同名包”。否则，别人可以发布 `@myorg/anything` 并绕过门槛。下面 pnpm、Yarn 和 Bun 的排除列表也一样。

 

陷阱在于版本。`min-release-age`于 [npm 11.10.0](https://github.com/npm/cli/releases/tag/v11.10.0) 中加入，该版本于 2026 年 2 月 11 日发布。较旧的 npm 会读取你的 `.npmrc`，但不认识这个键，因此安装时不会启用门槛。从 npm 11.2.0 开始，至少会出现未知配置警告（[npm 文档](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/)）。低于 11.2.0 则什么提示都没有。仓库里的文件写着 7 天，但这台机器上没有任何东西会执行这项设置。

 

所以在安装任何内容之前都要检查版本。下面这个小脚本适用于 macOS、Linux 和 Windows：

 

```
// scripts/check-npm.mjs
import { execSync } from "node:child_process";
const v = execSync("npm -v").toString().trim();
const [major, minor] = v.split(".").map(Number);
if (major < 11 || (major === 11 && minor < 10)) {
  console.error(`npm ${v} ignores min-release-age.`);
  console.error("Upgrade npm to 11.10 or later.");
  process.exit(1);
}
```

 

将注册表令牌保存在用户级别的 `~/.npmrc` 中。项目的 `.npmrc` 会提交到 git，并随之进入每个工作树。

 

[pnpm](https://pnpm.io/settings/dependency-resolution)以分钟计时。从 pnpm 11 开始，它会从 `pnpm-workspace.yaml` 读取 pnpm 设置，而 `.npmrc` 仅用于注册表和身份验证（[pnpm 11.0](https://pnpm.io/blog/releases/11.0)）：

 

```
# pnpm-workspace.yaml
minimumReleaseAge: 10080   # minutes, 7 days
minimumReleaseAgeExclude:
  - '@myorg/*'
```

 

pnpm 11 的默认值已经是 1440 分钟，也就是一天。关键细节在于 `minimumReleaseAgeStrict`：只有在你自行设置 `minimumReleaseAge` 时，它才会生效。使用默认值时，如果没有其他符合条件的版本，pnpm 会退回到违反年龄规则的版本。显式设置该值后，pnpm 会直接解析失败。排除列表接受名称、glob 和精确版本，例如 `webpack@4.47.0 || 5.102.1`。

 

[Yarn](https://yarnpkg.com/configuration/yarnrc)称之为年龄门槛，并把排除项称为预先批准的包；排除项可使用描述符或名称 glob：

 

```
# .yarnrc.yml
npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
  - "@myorg/*"
```

 

Yarn 的值以分钟为单位：在 [Classmethod 的测试](https://dev.classmethod.jp/articles/yarn-npm-minimal-age-gate/)中，`yarn config get npmMinimalAgeGate` 报告称 `"21d"` 为 `30240`。对于版本范围，Yarn 安装了通过门槛的最新版本，而且门槛也适用于传递依赖。根据 [该 PR 的测试](https://github.com/yarnpkg/berry/pull/6901)，过新的精确版本固定会报错“No candidates found”（未找到候选版本）。

 

[Bun](https://bun.com/docs/runtime/bunfig)以秒计时，设置位于 `[install]` 下：

 

```
# bunfig.toml
[install]
minimumReleaseAge = 604800   # seconds, 7 days
minimumReleaseAgeExcludes = ["@myorg/shared"]
```

 

Bun 文档称，它“会筛掉发布时间比此阈值更近的包版本”。它的排除列表接受包名，也接受 `name@version`，用于排除某个精确发行版。文档没有提到作用域通配符，因此请按名称列出你自己的包。

 

[uv](https://docs.astral.sh/uv/reference/settings/)使用 `exclude-newer`，它接受精确时间戳。从 0.9.17 开始，它也接受相对时长，这才让它能用作冷却期：

 

```
# pyproject.toml
[tool.uv]
exclude-newer = "7 days"
exclude-newer-package = { my-internal-lib = false }
```

 

它接受易读的时长（`"7 days"`、`"1 week"`）和 ISO 8601 格式的时长（`"P7D"`），但不支持月或年。`false`可排除一个包。据 [uv 的解析文档](https://docs.astral.sh/uv/concepts/resolution/)，有三点与 JavaScript 包管理器的行为不同：

 

- uv 会在解析时把“7 天”转换为时间戳，并将其写入 `uv.lock` 。在新一轮解析之前，它会保持不变，例如使用`--upgrade` 时，因此锁文件不会每天变动。
 
- 截止时间按每个文件的上传时间检查，而不是按版本发布日期。昨天上传到旧版本的 wheel 也算太新。
 
- 它只涵盖注册表包，不会对 Git 依赖设置门槛。

 

Git 工作树是受跟踪文件的一份检出副本。主检出目录中任何被忽略或未跟踪的内容都不会随它一起复制。用户级别的 `~/.npmrc` 设置会应用到你机器上的每个工作树，但不会应用到队友的笔记本电脑、CI 或容器。因此，门槛应写入已提交的文件：`.npmrc`、`pnpm-workspace.yaml`、`.yarnrc.yml`、`bunfig.toml` 或 `pyproject.toml`。在仓库的任何检出副本中运行安装命令的智能体都会读取它。

 

[Hermes IDE](https://hermes-ide.com/)就在这里派上用场。我开发了它，所以请结合这一点看待接下来的内容。在 Hermes 中，⌘N（Windows 和 Linux 上是 Ctrl+Shift+N）会为每项任务创建一个独立的 `hermes/<name>` 分支和工作树，并将任务本身作为智能体的首条提示。把任务交给那里的 [Claude Code](https://code.claude.com/docs/en/overview) 后，智能体的 `npm install` 会在一个全新的检出副本中运行，其中已经包含你的 `.npmrc`。

 

![The New task sheet with a refund-endpoint task typed, chips for Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort, and the preview of the claude command Hermes will run](/curation/media/30a4ac53ce4dc23d59c68b74644097ebdd30b2c24c1c669b32e31cd3a143dc18.webp)

 

*⌘N 新建任务面板：Claude Code、orders-api 项目、新建的 `hermes/` 工作树、接受编辑，以及 Hermes 将运行的命令。*

 

已提交的文件负责保存这项设置。npm 版本检查也需要在某处运行。Hermes 会读取仓库中的 `.hermes/worktree.toml`，并在智能体启动前，于每个新任务的工作树中运行其 `setup` 命令。第一条失败的命令会让后续命令停止运行（[recipe 文档](https://github.com/hermes-hq/hermes-ide/blob/main/docs/worktree-recipes.md)）：

 

```
# .hermes/worktree.toml
setup = ["node scripts/check-npm.mjs", "npm ci"]
done_when = ["npm test"]
```

 

Hermes 首次读取该 recipe，以及每次 recipe 变更时，都会显示这些命令，并等你选择“运行设置”。在安装了 npm 11.9 的机器上，检查会失败，`npm ci` 不会运行；失败信息会留在任务的设置卡片中，并发送到你的收件箱，因此在把工作树交给智能体之前，你就能看到它。选择“跳过”会在不运行设置的情况下启动会话，因此也会跳过检查。将 recipe 与 `.npmrc` 放在一起提交，让它们一同保存。

 

![The Review Desk's Worktrees tab listing one Hermes worktree each for orders-api, web-app and orders-types, with branch, task, age and disk size](/curation/media/7e2448e84e15a53a990bc93bbec1b4920e2bf57fa64ae2803fa7b2f581524f83.webp)

 

*审查工作台的“工作树”标签页：每项任务各有一个工作树，各自位于独立的 `hermes/` 分支上，并显示任务、使用时长和磁盘占用。*

 

依赖这个门槛之前，先在自己的机器上测试。TypeScript nightly 很适合测试，因为 `main` 每天太平洋标准时间午夜前都会向 npm 发布一个新构建（[TypeScript 文档](https://www.typescriptlang.org/docs/handbook/nightly-builds.html)）。其最新版本通常发布还不到一天。

 

```
npm -v
v=$(npm view typescript@next version --min-release-age=0)
npm view typescript time --json --min-release-age=0 \
  | grep "\"$v\""
npm install -D "typescript@$v"
```

 

两个 `npm view` 调用都通过 `--min-release-age=0`，这样门槛就无法对你隐藏最新版本或其发布时间。安装会保留你的 `.npmrc` 设置。门槛正常工作时，npm 会报 `npm error code ETARGET` 错误，并显示一条 `notarget No matching version found for typescript@...` 行，指出截止日期。这正是 Classmethod 在固定一个过新的 eslint 版本时遇到的错误[](https://dev.classmethod.jp/articles/npm-v11-min-release-age/)。如果安装反而成功，首行中的 `npm -v` 会告诉你原因。

 

同一个精确版本固定也可以用来测试其他包管理器：`pnpm add -D "typescript@$v"` 应当无法解析，因为你是自行设置 `minimumReleaseAge` 的。依赖它之前先运行测试。

 

要清楚七天无法覆盖哪些情况。Woodruff 的列表中，xz-utils 的可乘之机约有五周，只有更长的冷却期才能接近这个时长。冷却期也会延迟好的版本发布，包括安全修复；排除列表和 npm 的 `audit fix` 警告就是为此准备的。它也不会读取代码，只能确保其他人有一周时间来。

 

编程智能体是配有 shell 工具的模型，而 `npm install` 是它自主执行的调用之一。*AI That Acts* 是我的 *AI in TypeScript* 系列中关于工具调用的书：模型如何选择函数、你允许工具做什么，以及如何围绕这些决策用 TypeScript 构建一个首个可运行的智能体。

 

![AI That Acts — AI in TypeScript](/curation/media/7da7a9b6f0069a4847b4471345dfae93b2d49d80b0aaea8003772a494cca25fe.webp)

 

从你的第一个 LLM 调用到投入生产的智能体，整个系列都在 [xgabriel.com/ai-in-typescript](https://xgabriel.com/ai-in-typescript)。

 

如果你在同一个仓库上运行多个智能体，[Hermes IDE](https://hermes-ide.com/download) 可免费使用，采用 BSL 1.1 许可提供源代码，并支持 macOS、Windows 和 Linux（[GitHub](https://github.com/hermes-hq/hermes-ide)）。

 

AI 翻译；具体表述请与原文对照。
