ECC 包管理器偏好配置全解setup-pm 命令、六级检测优先级与底层实现剖析【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECCECCThe agent harness performance optimization system通过setup-pm命令统一管理 npm、pnpm、yarn、bun 四类 JavaScript 包管理器的偏好配置确保 Agent 在会话启动、执行安装/运行/测试等任务时自动选择与项目一致的包管理器。本文基于 setup-pm 命令文档、CLI 入口 与 核心检测库 完整讲解命令用法、六级检测优先级、配置文件格式与底层实现并补充文档未覆盖的 JSON Schema 约束、命令安全校验与 hook 集成细节读完后你可以熟练地在任意项目中配置全局/项目级包管理器偏好并理解 ECC 的包管理器检测机制是如何工作的。一、命令定位setup-pm 是什么setup-pm 文档西班牙语版本位于 docs/es/commands/setup-pm.md对应的能力是为当前项目或全局设置你偏好的包管理器供 ECC 在执行包管理相关任务时自动选用。文档 frontmatter 中标注了disable-model-invocation: true即该命令不会由模型自动触发而是由用户显式调用。该命令是一个纯 Node.js 脚本不依赖任何运行时框架直接以node执行# 检测当前包管理器 node scripts/setup-package-manager.js --detect # 设置全局偏好 node scripts/setup-package-manager.js --global pnpm # 设置项目级偏好 node scripts/setup-package-manager.js --project bun # 列出可用的包管理器 node scripts/setup-package-manager.js --list在 CLI 入口 中还可以看到两个文档之外的用法细节不带任何参数或带--help/-h时打印帮助信息后退出见 scripts/setup-package-manager.js直接传一个包管理器名称如node scripts/setup-package-manager.js pnpm等价于--global pnpm即直接设置全局偏好见 scripts/setup-package-manager.js。二、六级检测优先级setup-pm 文档定义的核心机制是ECC 在决定使用哪个包管理器时按以下顺序逐级检测命中即停止环境变量CLAUDE_PACKAGE_MANAGER优先级最高可覆盖一切其他检测方式项目配置.claude/package-manager.jsonpackage.jsonpackageManager字段Lock 文件package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lockb的存在性全局配置~/.claude/package-manager.jsonFallback文档描述为“第一个可用的包管理器pnpm bun yarn npm”。核心检测库 的getPackageManager()函数完整实现了前五级检测每一级命中后都会返回{ name, config, source }三元组其中source标识命中来源environment/project-config/package.json/lock-file/global-config--detect输出里的 “Source” 字段即来自它。有两点源码层面的细节值得注意文档中的优先级列表 pnpm bun yarn npm 实际对应的是 Lock 文件检测顺序scripts/lib/package-manager.js 定义了DETECTION_PRIORITY [pnpm, bun, yarn, npm]当项目中同时存在多个 lock 文件时按此顺序决定归属。第 6 级 Fallback 在当前实现中是“安全默认值 npm”而非扫描系统已安装的包管理器。源码注释明确说明见 scripts/lib/package-manager.js旧版本曾在 Fallback 时调用getAvailablePackageManagers()该函数会为每个包管理器派生子进程Windows 上where.exe、Unix 上which导致会话启动 hook 在 Bun 初始化期间超出 Bun 的 spawn 上限引发 Windows 上的插件冻结。修复后 Fallback 直接返回 npm随 Node.js 恒可用不再派生任何子进程。因此在实际运行中当前版本的最终兜底行为是source 为default、name 为npm。三、三种配置方式与 JSON Schema 约束3.1 全局配置写入~/.claude/package-manager.json--global参数的落盘位置{ packageManager: pnpm }3.2 项目级配置写入项目根目录下.claude/package-manager.json--project参数的落盘位置{ packageManager: bun }3.3 package.json 的 packageManager 字段{ packageManager: pnpm8.6.0 }从 detectFromPackageJson 实现 可以看到该函数读取package.json后取packageManager字段并按拆分只取版本号之前的名字pnpm8.6.0→pnpm再与内置的包管理器表比对因此支持pnpm、pnpm8这类两种写法。3.4 Schema 层面的补充约束schemas/package-manager.schema.json 定义了上述配置文件的数据契约文档未展开的约束包括字段类型说明packageManagerstring必填枚举值仅限npm/pnpm/yarn/bunsetAtstring可选ISO 8601 时间戳记录偏好最后一次被设置的时间且additionalProperties: false—— 配置文件中不允许出现这两个字段之外的任何键。setAt由 setPreferredPackageManager 和 setProjectPackageManager 在保存时自动写入new Date().toISOString()用户无需手工维护读取配置时对 JSON 解析失败做了静默容错视为未配置坏文件不会导致命令报错退出。四、环境变量 CLAUDE_PACKAGE_MANAGER环境变量是最高优先级开关可覆盖项目配置、package.json、lock 文件与全局配置。文档给出的设置方式# Windows (PowerShell) $env:CLAUDE_PACKAGE_MANAGER pnpm # macOS/Linux export CLAUDE_PACKAGE_MANAGERpnpm注意 getPackageManager 中环境变量同样要通过与PACKAGE_MANAGERS表的比对——只有npm、pnpm、yarn、bun四个合法值才会生效设置成其他值会被忽略并继续走后续检测级别。五、--detect 输出解读执行node scripts/setup-package-manager.js --detect时detectAndShow 函数 会打印四个板块Current selection最终选定的包管理器名称与命中来源Source字段取值见第二节的五级来源标识Detection results三个独立探测通道的结果——package.json的 packageManager 字段、lock 文件探测结果、CLAUDE_PACKAGE_MANAGER环境变量当前值Available package managers以✓/✗标记四种包管理器是否已安装在系统上这一步调用getAvailablePackageManagers()派生子进程探测仅在此展示路径中使用Commands当前选定的包管理器对应的三类命令模板——安装命令installCmd、运行脚本runCmd、执行二进制execCmd。--list模式则输出每种包管理器的完整信息是否已安装、lock 文件名、install/run 命令由 listAvailable 函数 生成。六、底层 APIPACKAGE_MANAGERS 命令映射表scripts/lib/package-manager.js 为每种包管理器定义了统一的命令映射表这是 Agent 跨包管理器执行任务的基础属性npmpnpmyarnbunlockFilepackage-lock.jsonpnpm-lock.yamlyarn.lockbun.lock兼容bun.lockbinstallCmdnpm installpnpm installyarnbun installrunCmdnpm runpnpmyarnbun runexecCmdnpxpnpm dlxyarn dlxbunxtestCmdnpm testpnpm testyarn testbun testbuildCmdnpm run buildpnpm buildyarn buildbun run builddevCmdnpm run devpnpm devyarn devbun run dev两个实现细节bun 的 lock 文件存在别名机制bun.lock是主 lock 文件名lockFileAliases: [bun.lockb]兼容旧版二进制 lock 文件见 scripts/lib/package-manager.js。而 setup-pm 文档中列举的bun.lockb正是这一兼容逻辑的来源。yarn 的 install 命令就是裸yarnyarn 1.x 的默认行为runCmd 同样是yarn。在此基础上库向外暴露三个命令生成 APIgetRunCommand(script)对install/test/build/dev四个常见动作返回专用命令其余脚本名拼成runCmd scriptgetExecCommand(binary, args)拼接execCmd binary argsgetCommandPattern(action)生成一个同时匹配四种包管理器写法的正则例如dev动作生成(npm run dev|pnpm( run)? dev|yarn dev|bun run dev)供 ECC 在匹配/拦截用户命令时不区分包管理器使用注意pnpm( run)? dev中的可选run与上表中 pnpm 的 runCmd 为pnpm保持一致。这两个命令生成 API 还内置了shell 注入防护脚本名/二进制名必须匹配^[a-zA-Z0-9_./-]$允许 scoped 包如scope/pkg参数必须匹配更严格的白名单正则拒绝;、|、、、$等 shell 元字符见 scripts/lib/package-manager.js。非法输入会直接抛错而不是拼进命令行。七、全局配置的落盘路径getClaudeDir 解析--global写入的是“Claude 配置目录”下的package-manager.json。从 loadConfig/saveConfig 实现 看该目录由getClaudeDir()解析而 scripts/lib/utils.js 中getClaudeDir()是getAgentDataHome()的别名——即 ECC 统一的 agent 数据根目录。该解析优先读取HOME/USERPROFILE环境变量测试正是利用这一点做隔离默认落在~/.claude。这也解释了为什么 单元测试 可以通过临时改写HOME来验证全局配置的读写而不污染真实用户目录。八、与 session-start hook 的集成包管理器检测不是孤立的 CLI 功能它被会话启动流程直接引用scripts/hooks/session-start.js 在会话开始 hook 中导入getPackageManager与getSelectionPrompt。当六级检测全部落空、又无法从项目文件推断时getSelectionPrompt()会生成一段提示消息列出四种受支持的包管理器及四种配置方式环境变量、全局配置、package.json、lock 文件提示用户完成偏好配置。从源码结构看这是 ECC 在会话早期感知项目技术栈的一部分——hook 选择了无子进程版本的getPackageManager()正对应第二节提到的“避免在会话启动热路径上派生子进程”的设计约束。九、测试验证与实战建议该功能有两组测试覆盖可作为行为核对依据tests/lib/package-manager.test.js针对核心库的约 1700 行测试覆盖PACKAGE_MANAGERS常量完整性、lock 文件探测如package-lock.json→ npm、pnpm-lock.yaml→ pnpm、packageManager 字段解析、隔离 HOME 下的全局配置读写等tests/scripts/setup-package-manager.test.js针对 CLI 脚本本身的行为测试。实战建议多项目开发者优先用--global设定个人偏好如 pnpm让无 lock 文件的新项目也有稳定默认值团队协作项目推荐把偏好写进项目.claude/package-manager.json或package.json的packageManager字段并随仓库提交使每个成员的检测结果一致且优先级高于个人全局配置CI 或临时调试场景用CLAUDE_PACKAGE_MANAGER环境变量做一次性覆盖无需改动任何配置文件配置完成后用--detect验证Source字段是否符合预期例如希望由项目配置命中时应看到project-config而非lock-file--list则可用于确认目标包管理器确实已安装。十、小结setup-pm 以一条轻量 CLI 加上一个纯函数检测库为 ECC 提供了确定性的包管理器选择能力环境变量 → 项目配置 → package.json → lock 文件 → 全局配置 → 安全默认的六级优先级配合统一的命令映射表与注入防护使 Agent 在跨 npm/pnpm/yarn/bun 的项目间执行安装、运行、测试、构建任务时行为一致且可预期。其关键实现集中在 scripts/setup-package-manager.jsCLI 层与 scripts/lib/package-manager.js检测与命令生成层配置契约由 schemas/package-manager.schema.json 定义。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考