AIRI 大型 Monorepo 的 pnpm 全局虚拟仓库：Git Worktree 多 Agent 并行开发与 v11 隔离全局包实战

本篇技术指南以 .agents/skills/pnpm/references/features-global-virtual-store.md 为骨架，系统讲解 pnpm 全局虚拟仓库（Global Virtual Store）的配置方式、工作原理及其在 Git Worktree 多 Agent 并行开发中的落地价值，并延伸到 pnpm v11 对全局包（Global Packages）的隔离化设计。AIRI（@proj-airi/root，当前使用 pnpm@11.24.0，见 package.json）是一个横跨 packages/、apps/、plugins/、integrations/、services/、engines/、server/、docs/ 等十余个目录的超大 monorepo，本文会结合该仓库的 workspace 配置、CI 流水线与多 Agent 协作约定，说明这套方案在真实项目中的适用前提与实操要点。读完后，你将掌握如何让同一仓库的多个 checkout（worktree）几乎零成本地共享同一份 node_modules，以及如何安全地在多 Agent 并行开发场景中部署依赖。

一、先理解默认的虚拟仓库：每个项目一份 .pnpm

pnpm 的核心是内容寻址存储（content-addressable store）：所有包在机器上只下载一次，存放在全局 store 中，再由每个项目的 node_modules/.pnpm（虚拟仓库，virtual store）通过 硬链接 引用到全局 store。

默认布局如下（参考 .agents/skills/pnpm/references/core-store.md）：

<store-dir>/                 # 全局内容寻址 store（pnpm store path 可查）
└── files/
    └── <hash>/              # 按内容哈希存放文件

project-a/
└── node_modules/
    ├── .pnpm/               # 虚拟仓库（硬链接指向全局 store）
    │   └── lodash@4.17.21/node_modules/lodash/
    └── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash

关键命令：

pnpm store path        # 查看全局 store 路径
pnpm store prune       # 清理未被引用的包（含全局虚拟仓库链接）
pnpm store status      # 校验 store 完整性

在这种默认模式下，每个项目（或每个 checkout）都会在自己的 node_modules/.pnpm 中创建一套完整的硬链接树。对于同一个仓库的多个 checkout（例如 Git Worktree、并行 Agent 场景），这套硬链接树会被重复创建，占用的目录项与 inode 开销随 checkout 数量线性增长。

二、全局虚拟仓库：把 .pnpm 也共享掉

2.1 启用方式与目录结构

在 pnpm-workspace.yaml 中设置：

enableGlobalVirtualStore: true

启用后，pnpm 不再为每个项目维护独立的 node_modules/.pnpm，而是把唯一的共享虚拟仓库放到 store 根下的 links/ 目录（位置可用 pnpm store path 查看，即 <store-path>/links/）。每个项目的 node_modules 只剩指向它的 符号链接（symlink）：

# 默认：每个项目独立的 .pnpm + 硬链接
project-a/node_modules/lodash -> .pnpm/lodash@4.17.21/node_modules/lodash

# 全局虚拟仓库：符号链接指向共享位置
project-a/node_modules/lodash -> <store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash
project-b/node_modules/lodash -> <store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash  # 同一个目标

注意 links/ 目录中的路径包含一个依赖图哈希（<hash> 段），这正是全局虚拟仓库的核心设计：包的身份 = 依赖图哈希。

2.2 包身份 = 依赖图哈希（NixOS 风格）

两个项目即便都依赖 lodash@4.17.21，只要它们的传递依赖树（transitive dependency tree）相同，就会指向完全相同的目录——这与 NixOS 的 content-addressed 存储哲学一致。反之，如果 peer 依赖不同导致依赖图不同，则会生成独立的条目，互不串扰。

带来的直接收益：

• 近乎零的单 checkout 成本：新增一个 checkout 的 node_modules 只是创建一批符号链接，不再复制硬链接树；
• 瞬时安装：一旦某个版本组合进入全局 store，后续 checkout 的 pnpm install 基本无需下载或解包。

2.3 v11 的默认范围

在 pnpm v11 中，全局虚拟仓库是 pnpm dlx / pnx 与全局安装（global installs）的默认行为；但对于项目安装（project installs），它仍然是 opt-in（需显式开启）且处于 experimental（实验性）阶段（见 .agents/skills/pnpm/references/core-cli.md 与 .agents/skills/pnpm/references/core-store.md）。

就 AIRI 仓库而言，当前根 pnpm-workspace.yaml 未显式写入 enableGlobalVirtualStore，即保持 v11 对项目安装的 opt-in 默认。若要在本地多 checkout 开发时启用，直接在文件末尾追加该键即可；CI 环境会自动禁用（见下文），不会影响流水线。

2.4 与 store 相关配置的配合

全局虚拟仓库是对 store 体系的增量改造，可与以下既有设置共存（参考 core-store.md）：

storeDir: ~/.local/share/pnpm/store   # 自定义 store 位置
enableGlobalVirtualStore: true
sideEffectsCache: true                 # 原生模块构建结果缓存（默认开启）

pnpm store prune 在 v11 中也会清理全局虚拟仓库中不再被引用的 links（见 core-cli.md）。

三、全局虚拟仓库的三条限制与对策

3.1 CI 环境自动禁用

CI 中全局虚拟仓库会被自动禁用——因为 CI 的 store 是临时缓存的，没有"热 store"可供共享，全局虚拟仓库无法带来收益。AIRI 的 CI 流水线（.github/workflows/ci.yml）也确实在每次运行中执行 pnpm install --frozen-lockfile，配合 pnpm/setup@v2 的缓存，属于标准做法。因此该特性主要面向本地多 checkout 开发，而非 CI。

3.2 信任边界：共享可变状态

全局虚拟仓库是一份所有 checkout 共享的、可写的 store 状态。这意味着它只适合相互信任的项目 / 用户 / 作业之间共享。如果多个 Agent 或分支同时操作同一 store，任何一个对 store 的破坏性操作都会影响所有使用者。必要的防护手段：

• 用文件系统权限保护 <store-path>/links/ 与 store 目录本身；
• 明确约定共享该 store 的 Agent / 分支处于同一信任边界内。

AIRI 仓库的 Agent 协作约定中反复强调 worktree 隔离（见 services/computer-use-mcp/AGENTS.md："Do not let Gemini CLI edit the same worktree concurrently with Codex"），这正是"共享 store + 独立 worktree"模型的配套纪律：依赖可共享，写入必须按 worktree 隔离。

3.3 ESM 提升限制：NODE_PATH 不生效于 ESM

全局虚拟仓库的依赖提升（hoisting）依赖 NODE_PATH 环境变量，而 Node 对 ESM import 会忽略 NODE_PATH。因此，如果某个 ESM 依赖 import 了未声明的包（phantom dependency），在全局虚拟仓库布局下会直接解析失败。

两个官方推荐的修复路径：

1. packageExtensions：在 pnpm-workspace.yaml 中为有问题的包补齐缺失的依赖声明——AIRI 的 workspace 已经在使用该机制（见 pnpm-workspace.yaml，例如为 @huggingface/transformers 补充 onnxruntime-common 可选依赖、为 vitepress 补充 vite/vue peer 依赖）；
2. 配置依赖 @pnpm/plugin-esm-node-path：作为 config dependency 引入，为 ESM 场景恢复 node-path 解析能力。

四、Git Worktree 多 Agent 开发：方案落地

4.1 为什么需要 Worktree + 全局虚拟仓库

Git Worktree 允许你在同一个 .git 对象库之上同时检出多个分支，每个分支各占一个独立目录。AIRI 的协作方式正是典型的多 Agent 场景：不同 Agent 同时处理不同分支（例如功能、修复、评审），且文档明确要求"不同 Agent 使用不同 worktree，避免并发写入同一目录"。

但纯 Worktree 无法解决依赖成本问题：每个 worktree 都会生成一套 node_modules。Worktree + 全局虚拟仓库组合后：

• 每个 worktree 拥有自己完整的 node_modules 树（Agent 可以在不同分支上安装不同版本而不冲突）；
• 所有包内容都来自同一个共享 store，磁盘与安装成本趋近于零。

4.2 实操步骤

以 bare 仓库为中枢，按分支 / Agent 建 worktree：

# 以 bare 仓库作为 hub，每个分支 / Agent 一个 worktree
git clone --bare https://github.com/your-org/your-monorepo.git your-monorepo
cd your-monorepo
git worktree add ./main main
git worktree add ./feature-auth feat/auth
git worktree add ./fix-api fix/api-error

在仓库根配置 workspace 与全局虚拟仓库：

packages:
  - 'packages/*'
enableGlobalVirtualStore: true

首次安装填充 store，后续 worktree 近乎瞬时：

cd main && pnpm install            # 首次安装填充全局 store
cd ../feature-auth && pnpm install # 后续 worktree：几乎瞬间完成，只是符号链接

不再需要的 worktree 用以下命令移除：

git worktree remove ./feature-auth

需要留意的是 worktree 场景下 .git 会以文件形式指向公共对象库（AIRI 仓库的 Godot 测试代码中也有相关注释，见 engines/stage-tamagotchi-godot/tests/stage-tamagotchi-godot.tests/Program.cs），一些依赖 .git 位置的工具链需要按此调整。

4.3 pnpm 官方仓库自身的实践

pnpm 官方仓库本身就在使用这套方案，并提供了辅助脚本（pnpm worktree:new <branch|pr>）。其前提假设与本节一致：所有 worktree / Agent 共享同一个信任边界。也就是说，只有当你有能力约束所有并行 Agent 对 store 的读写行为时，全局虚拟仓库才值得开启。

4.4 何时开启、何时不开启

场景	建议
同一仓库的大量 checkout（worktree、并行 Agent）	开启，收益最大
多个互不信任的项目 / 用户 / CI 作业	不开启，或严格隔离 store 权限
CI 环境	自动禁用，无需关心
存在 ESM 幽灵依赖且未做 packageExtensions 修复	先修复依赖声明，再开启

五、pnpm v11 的隔离全局包（Global Packages）

5.1 设计动机：全局工具互不破坏

v11 重新设计了 pnpm add -g：每个全局安装的包（或包组）拥有独立的安装目录，各自带有独立的 package.json、node_modules/ 与 lockfile，从而避免不同全局工具因 peer / hoisting 冲突而互相破坏。安装产物位于 {pnpmHomeDir}/global/v11/{hash}/，并共享全局虚拟仓库。

5.2 核心命令

pnpm add -g typescript prettier      # 空格分隔 = 各自独立的隔离安装
pnpm add -g eslint,prettier          # 逗号分隔 = 共享同一个安装组
pnpm remove -g eslint                # 只移除 eslint 所在的安装组
pnpm add -g --allow-build=esbuild esbuild   # 预先批准 build scripts
pnpm list -g                         # 深度 0 时始终可用
pnpm bin -g                          # 全局 bin 目录 = $PNPM_HOME/bin

5.3 易错点与行为细节

• pnpm install -g（无参数）不再支持——请改用 pnpm add -g <pkg>；
• bin 位于 $PNPM_HOME/bin（不是 $PNPM_HOME 本身）。升级后需要运行 pnpm setup 把该目录加入 PATH。AIRI 仓库的工具链脚本会显式透传 PNPM_HOME 环境变量，正是因为它对子进程解析全局 bin 至关重要（见 apps/stage-tamagotchi/scripts/desktop-overlay-live-window-smoke.ts）；
• 注册本地包的 bin：pnpm add -g . 取代了旧版 pnpm link --global；
• pnpm list -g --depth=<n>（n>0）只对单个安装组生效；
• v11 中 pnpm link 只接受路径参数（参考 core-cli.md），需要全局暴露 bin 一律走 pnpm add -g .。

AIRI 根脚本中已有 pnpm dlx nolyfill 的使用（package.json），dlx/pnx 在 v11 默认走全局虚拟仓库，且会遵守 minimumReleaseAge、trustPolicy 等供应链安全设置（见 core-cli.md）——这正好呼应了 AIRI 根 pnpm-workspace.yaml 中配置的 minimumReleaseAge: 4320 等安全策略。

六、在 AIRI 仓库中观察到的配套实践

本仓库虽未显式开启项目级全局虚拟仓库，但其配置体系已经为这套方案铺好了全部配套基础：

• 统一 workspace 配置：根 pnpm-workspace.yaml 使用 packages glob 覆盖 packages/**、apps/**、plugins/**、integrations/**、services/**、engines/**、server/** 等全部子包，并配置了 catalog、overrides、patchedDependencies、allowBuilds、packageExtensions 等完整体系；
• camelCase 配置模型：v11 起所有 pnpm 设置位于 pnpm-workspace.yaml（camelCase），.npmrc 仅保留认证/registry 信息，package.json#pnpm 字段不再被读取（见 .agents/skills/pnpm/references/core-config.md）；
• CI 走 frozen-lockfile：.github/workflows/ci.yml 在 lint / build / test / typecheck 各 job 中统一执行 pnpm install --frozen-lockfile，符合全局虚拟仓库"CI 自动禁用"的预期；
• Nix 构建同样使用 pnpm 11：nix/common.nix 显式锁定 pnpm_11 并配合 fetchPnpmDeps，说明仓库的依赖管理整体绑定在 v11 语义上；
• 多 Agent worktree 纪律：services/computer-use-mcp/AGENTS.md 明确禁止不同 Agent 并发编辑同一 worktree，与全局虚拟仓库的信任边界要求天然匹配。

七、关键要点速查

• enableGlobalVirtualStore: true ⇒ 项目的 node_modules 变成指向一个共享、哈希寻址 store 的符号链接集合；
• 最适合同一仓库的多个 checkout（Git Worktree、并行 Agent）；CI 中自动禁用；
• 包身份 = 依赖图哈希：依赖树相同的项目共享同一目录，peer 不同则自动分条；
• 警惕 ESM 包 import 未声明依赖（NODE_PATH 对 ESM 无效），用 packageExtensions 或 @pnpm/plugin-esm-node-path 修复；
• v11 全局安装按包隔离，逗号分隔共享安装组，bin 位于 $PNPM_HOME/bin，升级后记得 pnpm setup；
• 共享 store 是共享可变状态，务必保证所有使用方处于同一信任边界，并用文件系统权限保护 store 路径。

参考的仓库内文档：features-global-virtual-store.md、core-store.md、core-config.md、core-cli.md、best-practices-performance.md。