书籍:AI That Acts
**系列:**AI in TypeScript —— 共 5 本书,从你的第一个 LLM 调用到投入生产的智能体 ——五本都在这里
我的项目:Hermes IDE |GitHub —— 一款面向使用 Claude Code 和其他 AI 编程工具交付软件的开发者的 IDE
关于我:xgabriel.com |GitHub
恶意版 chalk 发布后仅存活不到 12 小时。Nx 的恶意版本存活了约 4 小时,rspack 的约 1 小时。William Woodruff 梳理了十起知名供应链攻击,发现其中 8 起的可乘之机都不到一周(他的文章)。
把你的编程智能体放进这段窗口期里。它判断自己需要一个日期库,几秒后运行 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 和 npm 配置文档、pnpm 10.16、Yarn 的 PR #6901、Bun 1.3、uv 0.9.17。
单位弄错,门槛就会毫无用处,或者荒谬至极。minimumReleaseAge: 7在 pnpm 中是七分钟。minimumReleaseAge = 7在 Bun 中是七秒。min-release-age=10080在 npm 中则约为 27 年。

冷却期会让新版本先放置一周,在此期间,你的机器上任何内容都无法安装它。
在 npm 中,这道门槛只需在项目的 .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 配置文档称,你应当在该注册表上拥有自己的私有作用域,“这样其他人就无法发布同名包”。否则,别人可以发布 @myorg/anything 并绕过门槛。下面 pnpm、Yarn 和 Bun 的排除列表也一样。
陷阱在于版本。min-release-age于 npm 11.10.0 中加入,该版本于 2026 年 2 月 11 日发布。较旧的 npm 会读取你的 .npmrc,但不认识这个键,因此安装时不会启用门槛。从 npm 11.2.0 开始,至少会出现未知配置警告(npm 文档)。低于 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以分钟计时。从 pnpm 11 开始,它会从 pnpm-workspace.yaml 读取 pnpm 设置,而 .npmrc 仅用于注册表和身份验证(pnpm 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称之为年龄门槛,并把排除项称为预先批准的包;排除项可使用描述符或名称 glob:
# .yarnrc.yml
npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
- "@myorg/*"
Yarn 的值以分钟为单位:在 Classmethod 的测试中,yarn config get npmMinimalAgeGate 报告称 "21d" 为 30240。对于版本范围,Yarn 安装了通过门槛的最新版本,而且门槛也适用于传递依赖。根据 该 PR 的测试,过新的精确版本固定会报错“No candidates found”(未找到候选版本)。
Bun以秒计时,设置位于 [install] 下:
# bunfig.toml
[install]
minimumReleaseAge = 604800 # seconds, 7 days
minimumReleaseAgeExcludes = ["@myorg/shared"]
Bun 文档称,它“会筛掉发布时间比此阈值更近的包版本”。它的排除列表接受包名,也接受 name@version,用于排除某个精确发行版。文档没有提到作用域通配符,因此请按名称列出你自己的包。
uv使用 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 的解析文档,有三点与 JavaScript 包管理器的行为不同:
- uv 会在解析时把“7 天”转换为时间戳,并将其写入
uv.lock。在新一轮解析之前,它会保持不变,例如使用--upgrade时,因此锁文件不会每天变动。 - 截止时间按每个文件的上传时间检查,而不是按版本发布日期。昨天上传到旧版本的 wheel 也算太新。
- 它只涵盖注册表包,不会对 Git 依赖设置门槛。
Git 工作树是受跟踪文件的一份检出副本。主检出目录中任何被忽略或未跟踪的内容都不会随它一起复制。用户级别的 ~/.npmrc 设置会应用到你机器上的每个工作树,但不会应用到队友的笔记本电脑、CI 或容器。因此,门槛应写入已提交的文件:.npmrc、pnpm-workspace.yaml、.yarnrc.yml、bunfig.toml 或 pyproject.toml。在仓库的任何检出副本中运行安装命令的智能体都会读取它。
Hermes IDE就在这里派上用场。我开发了它,所以请结合这一点看待接下来的内容。在 Hermes 中,⌘N(Windows 和 Linux 上是 Ctrl+Shift+N)会为每项任务创建一个独立的 hermes/<name> 分支和工作树,并将任务本身作为智能体的首条提示。把任务交给那里的 Claude Code 后,智能体的 npm install 会在一个全新的检出副本中运行,其中已经包含你的 .npmrc。

⌘N 新建任务面板:Claude Code、orders-api 项目、新建的 hermes/ 工作树、接受编辑,以及 Hermes 将运行的命令。
已提交的文件负责保存这项设置。npm 版本检查也需要在某处运行。Hermes 会读取仓库中的 .hermes/worktree.toml,并在智能体启动前,于每个新任务的工作树中运行其 setup 命令。第一条失败的命令会让后续命令停止运行(recipe 文档):
# .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 放在一起提交,让它们一同保存。

审查工作台的“工作树”标签页:每项任务各有一个工作树,各自位于独立的 hermes/ 分支上,并显示任务、使用时长和磁盘占用。
依赖这个门槛之前,先在自己的机器上测试。TypeScript nightly 很适合测试,因为 main 每天太平洋标准时间午夜前都会向 npm 发布一个新构建(TypeScript 文档)。其最新版本通常发布还不到一天。
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 版本时遇到的错误。如果安装反而成功,首行中的 npm -v 会告诉你原因。
同一个精确版本固定也可以用来测试其他包管理器:pnpm add -D "typescript@$v" 应当无法解析,因为你是自行设置 minimumReleaseAge 的。依赖它之前先运行测试。
要清楚七天无法覆盖哪些情况。Woodruff 的列表中,xz-utils 的可乘之机约有五周,只有更长的冷却期才能接近这个时长。冷却期也会延迟好的版本发布,包括安全修复;排除列表和 npm 的 audit fix 警告就是为此准备的。它也不会读取代码,只能确保其他人有一周时间来。
编程智能体是配有 shell 工具的模型,而 npm install 是它自主执行的调用之一。AI That Acts 是我的 AI in TypeScript 系列中关于工具调用的书:模型如何选择函数、你允许工具做什么,以及如何围绕这些决策用 TypeScript 构建一个首个可运行的智能体。

从你的第一个 LLM 调用到投入生产的智能体,整个系列都在 xgabriel.com/ai-in-typescript。
如果你在同一个仓库上运行多个智能体,Hermes IDE 可免费使用,采用 BSL 1.1 许可提供源代码,并支持 macOS、Windows 和 Linux(GitHub)。