use-pnpm

Overview

本技能用于处理 pnpm 相关的安装、更新、工作区命令替换、Windows/PowerShell 故障和全局包恢复。重点覆盖 ERR_PNPM_UNEXPECTED_VIRTUAL_STORE、PNPM_HOME 与全局依赖树错位、Corepack 管理 pnpm、NVM Desktop 切换 Node 后的 pnpm 运行时混乱。

目标不是复述事故过程，而是给 future-agent 一套可执行判断路径：先识别 pnpm 由谁管理、全局区在哪里、store 在哪里、虚拟 store 指向哪里，再决定是重建依赖树、修配置，还是切回正确的 Node/pnpm 管理链路。

pnpm 12 断代前提：pnpm 12（Rust 原生版）对配置读取位置、构建审批、供应链校验有四处语义收紧，且 corepack 从此无法安装 pnpm。凡涉及 pnpm 版本判定、升级、CI 安装，先读 references/pnpm12-migration.md 与 references/corepack-eol-and-shim.md。

Low-Model Execution Contract

低等级模型必须把全局升级/审批任务当作“逐步清单”执行，不得凭标题或记忆跳步。相关具体命令只从 references/global-upgrade-checklist.md 复制，并遵守以下硬门：

1. 先完成运行时盘点；任一命令退出非零、路径为空或结果矛盾，立即 STOP，不得继续升级。
2. 一次只执行一个清单步骤；每步记录命令、退出码、关键输出和下一步。不得把多个升级批次、rebuild 或验证命令拼成一条。
3. 遇到交互审批时，只选择清单中“已确认用途”的包；不确定就保持未批准并 STOP。禁止把 --all 当快捷修复。
4. 出现 MSB8040、node-gyp、MSBuild、超时或无输出时，立即停止当前包，保留已写入策略和日志，不扩大审批范围、不重试整批。
5. 只有四项结论都有证据，才能报告完成：包升级、审批策略写入、构建脚本执行、CLI 可运行。缺任何一项都只能报告“部分完成/待处理”。