# pnpm 12.11 让 npm 依赖携带 Agent Skills：批准一次以后，升级还要查什么？

> Canonical: https://vxi.me/posts/pnpm-agent-skills-approval-scope/
> Locale: zh-cn
> Published: 2026-10-13
> Updated: 2026-10-13
> Markdown: https://vxi.me/posts/pnpm-agent-skills-approval-scope.md

# pnpm 12.11.0 Skills 权限实测：批准一次，究竟意味着什么？

**描述：**基于 pnpm v12.11.0 源码与固定版本文档，梳理 Skills 的发现范围、审批与链接行为，并用独立合成模型检验关键分支，帮助开发者评估依赖升级和权限管理方式。

## 发现与权限边界

我一开始把问题想得比较简单：依赖里多了个 `SKILL.md`，pnpm 要么安装时就把它放进 Agent 目录，要么完全不管。顺着 pnpm 12.11.0 的固定版本源码看下去，我发现中间还隔着发现、权限判断和链接几步；这些边界，才是判断“批准一次”意味着什么的关键。

我当时先追发现逻辑，以为只要依赖树里出现 Skill 文件，就会进入审批流程。结果发现扫描范围更窄：pnpm 检查 lockfile 中各 workspace importer 的直接依赖，并且只扫描一层 Skills 目录。间接依赖不在这条发现路径里，不能把“依赖树里有文件”和“pnpm 会发现它”画等号。

接着我把安装、链接和 Agent 加载拆开看。包里的文件可以已经落在依赖目录中；权限状态决定 pnpm 是否为它创建指向目标目录的符号链接；之后 Claude Code 或其他 Agent 是否读取、如何处理，则由各自客户端决定。pnpm 源码处理的是链接，不解析或执行 Skill 内容。

权限分支包括待批准、拒绝和批准几种状态。批准由包级操作处理，`pnpm approve` 同时涉及构建脚本与 Skills 权限；这不等于逐个文件审阅。构建脚本权限和 `permissions.skills` 是不同的权限面，包的构建脚本获批，不代表 Skill 内容经过了单独审查。

最让我停下来确认的是批准覆盖范围。v12.11.0 的官方文档说明，一次包级批准涵盖该依赖的全部 Skills，也延续到它之后的版本。升级时要留意新版本带来的指令变化：旧批准状态可能仍然适用，但新版本可以新增或改写 Skill。

workspace 里同时出现多个可用版本时，源码会为已安装的合格 registry 版本选择最高版本。这会影响实际链接到哪份内容，所以只看 `package.json` 里的版本范围并不足够。要判断升级后 Agent 可能读到什么，还得检查实际选中的包版本及其包含的 Skill。

目标目录也有明确条件。v12.11.0 会参考 `CLAUDECODE`、`CURSOR_AGENT`、`GEMINI_CLI` 环境变量或 workspace 中已存在的 Agent Skills 目录；`skills.dirs` 可以显式覆盖。显式配置为空会禁用 Skills；批准时若没有自动检测到目标目录，则会触发无目标错误。

```yaml
# pnpm-workspace.yaml
skills:
  dirs:
    - .claude/skills
    - .cursor/skills
```

我当时还以为，撤销权限会一并删掉相关目录里的内容。源码和独立文件系统模型展示的边界更窄：模型观察到已由它创建的链接会被移除，手工创建的本地 Skill 保持不动；目标路径被真实目录占用时不会被替换。包删除、目标目录缺失等分支，也要按各自的链接清理与错误处理逻辑理解。

## 合成模型与测试结果

为了把这些分支具体化，我用 Node 22.16.0 标准库写了独立合成文件系统模型：创建临时假依赖、合成 `SKILL.md` 和符号链接，再计算内容指纹。八组情形分别覆盖待批准、拒绝、批准、升级后新增 Skill、撤销、路径冲突、仅间接依赖，以及没有自动检测目标目录。

模型覆盖的八组情形都通过；其中升级情形观察到内容指纹变化，并出现第二个 Skill 链接。第一次跑模型时，有一组因我用“期望链接数量为零”判断是否存在已批准 Skill 而失败，误把“没有目标目录”判错。定位后改为单独检查已批准的 Skill 数量，再次运行后八组均通过。

## 仓库检查与适用范围

落到仓库检查时，可以先用 `pnpm permissions` 或 `pnpm permissions list` 查看权限，再对照 workspace 配置。依赖升级后，检查新版本里的 Skills 文件及其差异；更在意指令漂移的项目，可以固定依赖版本，并在 CI 中比较 `SKILL.md`。

```sh
pnpm permissions
pnpm permissions list
```

### 边界 / 限制

这次分析以 pnpm v12.11.0 源码和固定版本文档为基线，测试使用 Node 独立运行的合成模型，范围覆盖文件系统行为。模型没有接入 pnpm CLI、真实安装更新或 Agent；客户端发现和执行规则也会随各自版本变化。pnpm 12.11.1 的环境识别改动不应倒算成 12.11.0 的功能。包级批准带来的后续版本信任范围，是升级审查需要考虑的设计边界。

**参考链接：**[pnpm v12.11.0 源码](https://github.com/pnpm/pnpm/tree/v12.11.0) · [pnpm v12.11.0 文档](https://github.com/pnpm/pnpm/tree/v12.11.0/docs)