qwen-code 仓库的 pnpm Worktree Bootstrap为 Git Worktree 依赖安装瘦身的 Stage 1 迁移实践【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读qwen-code 是一个运行在终端中的开源 AI 编码智能体仓库其日常开发高度依赖 Git worktree 并行推进多分支工作。本文基于仓库内的设计文档 docs/design/2026-08-29-pnpm-worktree-bootstrap.md剖析 qwen-code 如何在不改动 npm 构建、发布链路的前提下引入 pnpm 作为额外 Git worktree 的依赖安装器从问题量化、pnpm-workspace.yaml与.pnpmfile.mjs的迁移细节、node scripts/setup-worktree.js引导脚本的完整逻辑到 Stage 1/2/3 的迁移边界与跨平台验证你将获得一套可直接复用的「npm 主链路 pnpm worktree 引导」双轨依赖管理实战方案。一、问题每个 npm 型 Git worktree 都要付一次「完整依赖树」的账单在 qwen-code 这种多包monorepo仓库中开发者常用git worktree add为每个分支创建独立检出。问题在于每一个由 npm 驱动的 worktree都会重新物化一份完整的依赖树约 1.44 GiB 级别并且npm 会在prepare生命周期中触发仓库级构建与打包esbuild bundle、notice 生成等如果调用者不知道设置QWEN_SKIP_PREPARE1worktree 在开始基于源码的开发之前就要先为「生成的产物」买单——而这些产物此时根本用不上。设计文档给出了一组同 commit、同一 APFS 卷上的实测数据量化了两种方案的差距指标warm-cache npm installwarm-store pnpm install新增磁盘占用约 1.44 GiB约 99 MiB仅依赖安装耗时27 秒22 秒而一次独立的完整构建full build另需约129 秒。也就是说npm 路线下每个新 worktree 至少要付出「1.44 GiB 磁盘 27 秒安装 可能被触发的 129 秒构建」而 pnpm 凭借**共享内容寻址存储store**几乎可以零复制地完成依赖物化。这个数据直接决定了迁移目标不追求替换 npm只把「额外 worktree 的依赖引导」切到 pnpm。二、总体设计双轨并存pnpm 只负责 worktree 引导设计文档明确了 Stage 1 的边界——pnpm 路线仅应用于额外 Git worktree 中的依赖安装仓库的构建命令、CI 构建编排、发布版本号、打包与发布逻辑一律不动package-lock.json对既有的所有 npm 路径保持权威地位npm 依然是包创建、registry 发布、干净产物安装的产品边界直到那些有意读取package-lock.json的脚本被迁移为止。2.1 仓库声明 pnpm 为包管理器仓库根目录 package.json 中通过packageManager字段声明了精确到完整性哈希的 pnpm 版本packageManager: pnpm11.24.0sha512.bd27e345e976dcb0be0b7a1228217b049a817e21b1f355c90dbe7dc46671895a8bc1e6d06c24554505ea93ea0b45f489a27ec1bfbc8de6a9659fca0f16fa0000这个格式由验证函数 scripts/pnpm-package.js 中的getPinnedPnpmPackage强制约束它接受pnpmx.y.z或带sha512.128 hex完整性后缀的形式后者正是corepack use pnpmx.y.z自己写入的格式其余一律抛错packageManager must pin an exact pnpm version。这保证了Corepack 在引导前即可校验 pnpm 包完整性引导过程可保持完全离线只要本地 store 命中。2.2 pnpm-workspace.yaml镜像 npm 的 workspace 边界pnpm-workspace.yaml 是 pnpm 路线的布局基础其关键设计是逐条镜像 npm 的 workspace 列表而非使用 globpackages: - packages/* - packages/channels/base - packages/channels/dingtalk # ... 其余 channel 逐一列出 - integrations/external-context - integrations/external-context-mem0 - !packages/desktop-shell - !packages/live-host nodeLinker: hoisted linkWorkspacePackages: true verifyDepsBeforeRun: false文件头注释明确解释了这样做的理由新增 channel 必须同时修改package.json与pnpm-workspace.yaml两个文件如果这里用 globchannel 会悄悄进入 pnpm 布局而 npm 依然忽略它形成两套布局的隐性分叉。三个值得注意的配置项nodeLinker: hoisted迁移初期仍使用 hoisted提升式链接器因为当前构建与打包脚本里还残留着继承自 npm 平铺布局的假设linkWorkspacePackages: true保持 workspace 内部包相互链接与 npm workspace 行为对齐verifyDepsBeforeRun: false避免每次运行脚本前的依赖校验开销。2.3 overrides锁定与 npm 一致的依赖版本提交到仓库的 pnpm lockfile 仅作为本次 bootstrap 的依赖解析来源。为了让 pnpm 解析结果与现有 npm 安装保持一致pnpm-workspace.yaml 中的overrides保留了 npm 安装当前使用的关键版本overrides: typescript: 5.8.3 microsoft/api-extractortypescript: 5.9.3 qwen-code/mobile-mcptypescript: 5.8.2 ansi-regex: 6.2.2 cliuiwrap-ansi: 7.0.0 baseline-browser-mapping: ^2.9.19 normalize-package-data: ^7.0.1 react: ^19.2.4 react-dom: ^19.2.4 types/react: ^19.2.0 types/react-dom: ^19.2.0 axios: ^1.19.0 react-markdown: ^9.0.0注意这里既有直接覆盖如typescript: 5.8.3也有路径化覆盖如cliuiwrap-ansi: 7.0.0只作用于 cliui 的 wrap-ansi 依赖这正是 pnpm overrides 的粒度优势。设计文档特别指出有两个版本无法仅靠 overrides 保留必须在 manifest 中直接固定packages/core声明精确的types/node版本20.19.1——此前它只由 npm 的 hoisting 提供pnpm 布局下必须显式声明它编译所针对的版本packages/vscode-ide-companion在运行时导入的每个包都写入 manifest——确保 pnpm linker 能物化这些依赖。2.4 allowBuilds依赖安装脚本的显式白名单依赖的安装脚本postinstall 等默认被拒绝除非显式列入allowBuilds见 pnpm-workspace.yamlallowBuilds: google/genai: true qwen-code/qwen-code-corefile:packages/core: true vscode/vsce-sign: true esbuild: true fsevents: false # Darwin-only optional depinstall 脚本仅为 node-gyp rebuild keytar: true msw: true protobufjs: true白名单只包含当前 npm 安装中确实会运行脚本的包。fsevents: false的注释很有代表性它是 Darwin-only 的可选依赖其 install 脚本只是node-gyp rebuildmacOS 冒烟安装未报告 ignored build因此显式记录false以固化 pnpm 已有的行为——白名单既可以是「允许」也可以是「明确拒绝」的声明。2.5 双锁过渡期的桥.pnpmfile.mjs在 manifests 全面改用workspace:协议之前的双锁npm pnpm过渡期仓库用 .pnpmfile.mjs 的readPackage钩子在内存中完成内部依赖的重写export const workspacePackageNames new Set([ qwen-code/acp-bridge, qwen-code/qwen-code-core, // ... 全部 workspace 成员逐一列出 ]); export const hooks { readPackage(packageJson) { for (const field of dependencyFields) { const dependencies packageJson[field]; if (!dependencies) continue; for (const name of Object.keys(dependencies)) { if (workspacePackageNames.has(name)) { dependencies[name] workspace:*; } } } return packageJson; }, };其工作机制与覆盖范围覆盖三类依赖字段dependencies、devDependencies、optionalDependencies覆盖两种书写形式既有的file:依赖以及发布脚本会更新的精确 channel 版本号如qwen-code/channel-xxx: 1.x.y都会被统一重写为workspace:*好处发布版本号 bump 不会让 pnpm lockfile 变陈旧同时已提交的 manifests 与 npm lockfile 保持原样不被触碰退出条件当 manifests 在最终 cutover 中全部改用workspace:后这个兼容钩子即可移除。值得注意的一个维护约束workspacePackageNames集合被测试 scripts/tests/package-scripts.test.js 与各 workspace manifest 交叉校验新增包若未同步登记会直接导致该测试失败。三、引导脚本node scripts/setup-worktree.js新 worktree 的标准引导入口是 scripts/setup-worktree.js。它承担了「离线优先、失败回退、跳过 prepare、安全补装 Husky」四重职责。3.1 执行前的完整性校验与目录定位脚本启动时解析仓库根目录脚本位于repo/scripts通过fileURLToPath(new URL(.., import.meta.url))定位自身所属 checkout因此无论调用者从哪个目录执行都能引导正确的工作区校验 pnpm 版本调用getPinnedPnpmPackage解析根 package.json 的packageManager只接受精确版本 可选完整性后缀查找 CorepackcorepackWindows 上为corepack.cmd必须在 PATH 中。脚本对 Windows 做了大小写不敏感的Path/PATH查找envValue/pathValue/findOnPath三个辅助函数因为 Windows 上环境变量通常以Path到达大小写敏感读取会漏掉它。找不到 Corepack 时 fail closed报错worktree setup failed: Corepack is required to verify the pinned pnpm package并退出 1——那些不再捆绑 Corepack 的 Node 版本必须单独安装它。3.2 冻结 lockfile 离线优先必要时回退 registryconst cachedInstall install(--offline); // 仅当离线安装失败才回退 console.warn(Cached install unavailable; retrying with registry access.); exitWithResult(install(--prefer-offline));安装逻辑使用pnpm install --frozen-lockfile冻结 lockfile并按以下次序决策先尝试--offline完全从共享本地 store 取包不触碰网络只有当缓存安装不完整失败、被信号杀死或状态码 ≥ 128时才回退--prefer-offline允许 registry 访问但优先使用缓存。这样设计的原因是常见 warm-store 路径上无需等待 pnpm 预取其他平台的 optional 二进制如 fsevents、esbuild 的各平台二进制--offline一次命中即可。3.3 跳过 prepare 重活但保留依赖安装脚本const env { ...process.env, QWEN_SKIP_PREPARE: 1, QWEN_SKIP_NOTICE_GENERATION: 1, };脚本设置两个环境变量QWEN_SKIP_PREPARE1跳过仓库构建、bundle 与 npm 布局相关的 notice 生成QWEN_SKIP_NOTICE_GENERATION1bootstrap 私有的 notice 生成守卫。对照 scripts/prepare.js 的实现QWEN_SKIP_PREPARE命中时prepare 会跳过husky、npm run build、npm run bundle三段重活但仍执行npm run generate生成被 gitignore 的git-commit.tscli 的systemInfo会导入它确保后续逐 workspace 构建/类型检查不会因缺模块而失败。注意这里的关键区分跳过的是仓库级构建/bundle而不是依赖安装脚本。allowBuilds白名单中的包esbuild、protobufjs 等的 install 脚本在 pnpm 布局下照常运行——这是与「为了彻底省事而全局--ignore-scripts」的本质区别。3.4 Husky 的「自己补装」与 fail-closed 判定由于QWEN_SKIP_PREPARE1同时抑制了 scripts/prepare.js 中 npm 安装才会走的 Husky 步骤引导脚本在冻结安装成功后自行安装 Husky hookspnpm exec husky并围绕 Git worktree 的 config 共享语义做了严密防护保留既有非默认 hooksPath若core.hooksPath已存在且不等于.husky/_或HUSKY0则跳过 Husky 并原样退出不拥有仓库 config 的 checkout 跳过并报告通过git rev-parse --git-dir --git-common-dir探测——--git-dir与--git-common-dir只有在 linked worktree 中才不同脚本注释明确指出.git是文件/目录/缺失都不可作为代理判断。在 linked worktree 中若 hooksPath 未设置Husky 的git config core.hooksPath .husky/_无--worktree会把值写进该仓库所有 worktree 共享的 config却只在当前 checkout 创建.husky/_包装器——脚本会跳过并提示「先在主 checkout 安装 hooks 后再重跑」探测到无仓库git 不可用或非仓库时同样跳过并报告fail closedHusky 在所有软失败找不到.git、config 写入被拒下都会以 0 退出因此成功需要双重证明——config 值确认 git 将使用 hookscore.hooksPath .husky/_且磁盘上确实存在包装器.husky/_/pre-commit。任一缺失即报错worktree setup failed: Husky did not install hooks并以非零退出树整洁性Husky 在.husky/_内生成的包装器由 .gitignore 忽略因此引导不会污染 worktree 的 git 状态。3.5 安装边界与 Stage 2 的承诺设计文档强调脚本执行不会隐式安装陈旧依赖node scripts/setup-worktree.js这一命令就是显式的安装边界——避免引导过程悄悄改变依赖状态。而基于 pnpm 布局进行构建被明确推迟到 Stage 2Stage 1 的引导不触碰任何构建产物。四、迁移边界与分阶段路线4.1 Stage 1当前仅 worktree 依赖安装只影响额外 Git worktree 的依赖安装路径不改变仓库构建命令、CI 构建编排、发布版本号、打包、发布package-lock.json对所有既有 npm 路径保持权威生成的pnpm-lock.yaml被排除在仓库「人工编写 YAML」的风格检查规则之外因为它是机器生成的锁文件。4.2 Stage 2 / Stage 3后续演进空间Stage 2可独立将 pnpm 布局升级为受支持的构建与开发路径再迁移 CI 安装与缓存Stage 3处理发布安装与构建编排最终 cutovermanifests 全面采用workspace:后移除 .pnpmfile.mjs 兼容钩子npm 仍是产品边界包创建、registry 发布、干净产物安装直到读取package-lock.json的脚本完成迁移。4.3 真实安装约束为什么packageImportMethod: clone-or-copypnpm-workspace.yaml 中的packageImportMethod: clone-or-copy是一处值得展开的工程细节。配置注释解释了根因根postinstall会运行patch-package它原地改写node_modules中的文件在 pnpm 默认的 import 方式下node_modules里的文件是 store 内容寻址条目的硬链接patch 会连带改写 store 条目——其内容不再匹配归档所用的 sha512后果是后续每个 worktree 的--offline阶段都会以ERR_PNPM_NO_OFFLINE_TARBALL失败、回退 registry 并再次 patch store离线路径永远无法命中改用clone-or-copy文件系统支持处用 copy-on-write否则普通拷贝后store 条目保持原样patch-package 只修改 worktree 自己的副本离线安装得以稳定命中。五、验证体系脚本测试 跨平台真实安装门禁5.1 单元/脚本测试设计文档声明 Stage 1 的 pnpm 路径必须满足冻结安装不得修改任何已跟踪文件。脚本测试覆盖四类行为集中在 scripts/tests/package-scripts.test.js 等脚本测试中bootstrap 命令本身setup-worktree的安装与退出语义prepare-skip 环境变量行为QWEN_SKIP_PREPARE/QWEN_SKIP_NOTICE_GENERATION的生效路径版本无关的 workspace 重写.pnpmfile.mjs的readPackage重写逻辑与 workspace 成员集合的一致性进程失败行为fail-closed 分支Corepack 缺失、Husky 未安装 hooks、config 读取失败等。5.2 跨平台真实安装门禁pnpm Worktree Smoke.github/workflows/pnpm-worktree-smoke.yml 是 Stage 1 的真实安装闸门路径过滤触发仅在 pnpm 安装相关输入变化时运行.pnpmfile.mjs、package.json、packages/*/package.json、patches/**、pnpm-lock.yaml、pnpm-workspace.yaml、scripts/setup-worktree.js、scripts/pnpm-package.js等并显式排除packages/desktop-shell与packages/live-host的 package.json三平台矩阵ubuntu-latest、macos-latest、windows-latestfail-fast: false一平台失败不取消其他平台Node 22.x node scripts/setup-worktree.js直接以真实命令执行冻结引导验证 workspace 链接可解析require.resolve(qwen-code/qwen-code-core/package.json, { paths: [packages/vscode-ide-companion] })——确认 hoisted linker 在真实环境下物化了内部依赖验证 worktree 保持干净git status --porcelain必须为空否则引导失败——这正是设计文档「冻结安装不得修改已跟踪文件」的机械化执行并发控制PR 运行可互相取消而 post-merge 的 push 运行不可取消避免静默丢失唯一的回归见证。此外现有 npm 的构建与发布校验完全不受影响——pnpm 布局下的构建被有意推迟到 Stage 2。六、实操速查如何为 qwen-code 引导一个新 worktree综合设计文档与 scripts/setup-worktree.js 的实现典型流程如下# 1. 创建 Git worktree 并检出目标分支 git worktree add ../qwen-code-wt branch # 2. 进入 worktree 后执行 pnpm 引导替代 npm install prepare cd ../qwen-code-wt node scripts/setup-worktree.js前置条件与行为约定需要Node 版本捆绑 Corepack或单独安装 Corepack否则脚本 fail closed首选完全离线的--offline安装共享本地 pnpm store 命中失败才回退--prefer-offline访问 registry引导自动跳过仓库构建/bundle/notice 生成QWEN_SKIP_PREPARE1依赖安装脚本仍按allowBuilds白名单执行Husky hooks 由引导脚本在安装成功后自行补装在共享 config 的 linked worktree 场景下会谨慎跳过并给出提示引导完成后git status应为干净状态后续构建、测试请沿用仓库既有的 npm 命令构建迁移属 Stage 2。七、小结qwen-code 的 pnpm worktree bootstrap 是一次「外科手术式」的包管理器迁移以约 99 MiB 对 1.44 GiB 的磁盘占用、22 秒对 27 秒的安装耗时把每个新 Git worktree 的依赖引导成本压缩一个数量级同时通过nodeLinker: hoisted、overrides、.pnpmfile.mjs兼容钩子、allowBuilds白名单与clone-or-copy导入方式将 pnpm 解析结果对齐到 npm 现状并严守「npm 仍是产品边界」的 Stage 1 红线。三平台路径过滤的 smoke workflow 与脚本测试共同构成其质量闸门而构建、CI 与发布链路的迁移则留给 Stage 2/3 独立演进——这种「先解决高频痛点的最小边界再逐步扩大」的迁移策略值得多包仓库在引入新包管理器时借鉴。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
qwen-code 仓库的 pnpm Worktree Bootstrap：为 Git Worktree 依赖安装瘦身的 Stage 1 迁移实践
qwen-code 仓库的 pnpm Worktree Bootstrap为 Git Worktree 依赖安装瘦身的 Stage 1 迁移实践【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读qwen-code 是一个运行在终端中的开源 AI 编码智能体仓库其日常开发高度依赖 Git worktree 并行推进多分支工作。本文基于仓库内的设计文档 docs/design/2026-08-29-pnpm-worktree-bootstrap.md剖析 qwen-code 如何在不改动 npm 构建、发布链路的前提下引入 pnpm 作为额外 Git worktree 的依赖安装器从问题量化、pnpm-workspace.yaml与.pnpmfile.mjs的迁移细节、node scripts/setup-worktree.js引导脚本的完整逻辑到 Stage 1/2/3 的迁移边界与跨平台验证你将获得一套可直接复用的「npm 主链路 pnpm worktree 引导」双轨依赖管理实战方案。一、问题每个 npm 型 Git worktree 都要付一次「完整依赖树」的账单在 qwen-code 这种多包monorepo仓库中开发者常用git worktree add为每个分支创建独立检出。问题在于每一个由 npm 驱动的 worktree都会重新物化一份完整的依赖树约 1.44 GiB 级别并且npm 会在prepare生命周期中触发仓库级构建与打包esbuild bundle、notice 生成等如果调用者不知道设置QWEN_SKIP_PREPARE1worktree 在开始基于源码的开发之前就要先为「生成的产物」买单——而这些产物此时根本用不上。设计文档给出了一组同 commit、同一 APFS 卷上的实测数据量化了两种方案的差距指标warm-cache npm installwarm-store pnpm install新增磁盘占用约 1.44 GiB约 99 MiB仅依赖安装耗时27 秒22 秒而一次独立的完整构建full build另需约129 秒。也就是说npm 路线下每个新 worktree 至少要付出「1.44 GiB 磁盘 27 秒安装 可能被触发的 129 秒构建」而 pnpm 凭借**共享内容寻址存储store**几乎可以零复制地完成依赖物化。这个数据直接决定了迁移目标不追求替换 npm只把「额外 worktree 的依赖引导」切到 pnpm。二、总体设计双轨并存pnpm 只负责 worktree 引导设计文档明确了 Stage 1 的边界——pnpm 路线仅应用于额外 Git worktree 中的依赖安装仓库的构建命令、CI 构建编排、发布版本号、打包与发布逻辑一律不动package-lock.json对既有的所有 npm 路径保持权威地位npm 依然是包创建、registry 发布、干净产物安装的产品边界直到那些有意读取package-lock.json的脚本被迁移为止。2.1 仓库声明 pnpm 为包管理器仓库根目录 package.json 中通过packageManager字段声明了精确到完整性哈希的 pnpm 版本packageManager: pnpm11.24.0sha512.bd27e345e976dcb0be0b7a1228217b049a817e21b1f355c90dbe7dc46671895a8bc1e6d06c24554505ea93ea0b45f489a27ec1bfbc8de6a9659fca0f16fa0000这个格式由验证函数 scripts/pnpm-package.js 中的getPinnedPnpmPackage强制约束它接受pnpmx.y.z或带sha512.128 hex完整性后缀的形式后者正是corepack use pnpmx.y.z自己写入的格式其余一律抛错packageManager must pin an exact pnpm version。这保证了Corepack 在引导前即可校验 pnpm 包完整性引导过程可保持完全离线只要本地 store 命中。2.2 pnpm-workspace.yaml镜像 npm 的 workspace 边界pnpm-workspace.yaml 是 pnpm 路线的布局基础其关键设计是逐条镜像 npm 的 workspace 列表而非使用 globpackages: - packages/* - packages/channels/base - packages/channels/dingtalk # ... 其余 channel 逐一列出 - integrations/external-context - integrations/external-context-mem0 - !packages/desktop-shell - !packages/live-host nodeLinker: hoisted linkWorkspacePackages: true verifyDepsBeforeRun: false文件头注释明确解释了这样做的理由新增 channel 必须同时修改package.json与pnpm-workspace.yaml两个文件如果这里用 globchannel 会悄悄进入 pnpm 布局而 npm 依然忽略它形成两套布局的隐性分叉。三个值得注意的配置项nodeLinker: hoisted迁移初期仍使用 hoisted提升式链接器因为当前构建与打包脚本里还残留着继承自 npm 平铺布局的假设linkWorkspacePackages: true保持 workspace 内部包相互链接与 npm workspace 行为对齐verifyDepsBeforeRun: false避免每次运行脚本前的依赖校验开销。2.3 overrides锁定与 npm 一致的依赖版本提交到仓库的 pnpm lockfile 仅作为本次 bootstrap 的依赖解析来源。为了让 pnpm 解析结果与现有 npm 安装保持一致pnpm-workspace.yaml 中的overrides保留了 npm 安装当前使用的关键版本overrides: typescript: 5.8.3 microsoft/api-extractortypescript: 5.9.3 qwen-code/mobile-mcptypescript: 5.8.2 ansi-regex: 6.2.2 cliuiwrap-ansi: 7.0.0 baseline-browser-mapping: ^2.9.19 normalize-package-data: ^7.0.1 react: ^19.2.4 react-dom: ^19.2.4 types/react: ^19.2.0 types/react-dom: ^19.2.0 axios: ^1.19.0 react-markdown: ^9.0.0注意这里既有直接覆盖如typescript: 5.8.3也有路径化覆盖如cliuiwrap-ansi: 7.0.0只作用于 cliui 的 wrap-ansi 依赖这正是 pnpm overrides 的粒度优势。设计文档特别指出有两个版本无法仅靠 overrides 保留必须在 manifest 中直接固定packages/core声明精确的types/node版本20.19.1——此前它只由 npm 的 hoisting 提供pnpm 布局下必须显式声明它编译所针对的版本packages/vscode-ide-companion在运行时导入的每个包都写入 manifest——确保 pnpm linker 能物化这些依赖。2.4 allowBuilds依赖安装脚本的显式白名单依赖的安装脚本postinstall 等默认被拒绝除非显式列入allowBuilds见 pnpm-workspace.yamlallowBuilds: google/genai: true qwen-code/qwen-code-corefile:packages/core: true vscode/vsce-sign: true esbuild: true fsevents: false # Darwin-only optional depinstall 脚本仅为 node-gyp rebuild keytar: true msw: true protobufjs: true白名单只包含当前 npm 安装中确实会运行脚本的包。fsevents: false的注释很有代表性它是 Darwin-only 的可选依赖其 install 脚本只是node-gyp rebuildmacOS 冒烟安装未报告 ignored build因此显式记录false以固化 pnpm 已有的行为——白名单既可以是「允许」也可以是「明确拒绝」的声明。2.5 双锁过渡期的桥.pnpmfile.mjs在 manifests 全面改用workspace:协议之前的双锁npm pnpm过渡期仓库用 .pnpmfile.mjs 的readPackage钩子在内存中完成内部依赖的重写export const workspacePackageNames new Set([ qwen-code/acp-bridge, qwen-code/qwen-code-core, // ... 全部 workspace 成员逐一列出 ]); export const hooks { readPackage(packageJson) { for (const field of dependencyFields) { const dependencies packageJson[field]; if (!dependencies) continue; for (const name of Object.keys(dependencies)) { if (workspacePackageNames.has(name)) { dependencies[name] workspace:*; } } } return packageJson; }, };其工作机制与覆盖范围覆盖三类依赖字段dependencies、devDependencies、optionalDependencies覆盖两种书写形式既有的file:依赖以及发布脚本会更新的精确 channel 版本号如qwen-code/channel-xxx: 1.x.y都会被统一重写为workspace:*好处发布版本号 bump 不会让 pnpm lockfile 变陈旧同时已提交的 manifests 与 npm lockfile 保持原样不被触碰退出条件当 manifests 在最终 cutover 中全部改用workspace:后这个兼容钩子即可移除。值得注意的一个维护约束workspacePackageNames集合被测试 scripts/tests/package-scripts.test.js 与各 workspace manifest 交叉校验新增包若未同步登记会直接导致该测试失败。三、引导脚本node scripts/setup-worktree.js新 worktree 的标准引导入口是 scripts/setup-worktree.js。它承担了「离线优先、失败回退、跳过 prepare、安全补装 Husky」四重职责。3.1 执行前的完整性校验与目录定位脚本启动时解析仓库根目录脚本位于repo/scripts通过fileURLToPath(new URL(.., import.meta.url))定位自身所属 checkout因此无论调用者从哪个目录执行都能引导正确的工作区校验 pnpm 版本调用getPinnedPnpmPackage解析根 package.json 的packageManager只接受精确版本 可选完整性后缀查找 CorepackcorepackWindows 上为corepack.cmd必须在 PATH 中。脚本对 Windows 做了大小写不敏感的Path/PATH查找envValue/pathValue/findOnPath三个辅助函数因为 Windows 上环境变量通常以Path到达大小写敏感读取会漏掉它。找不到 Corepack 时 fail closed报错worktree setup failed: Corepack is required to verify the pinned pnpm package并退出 1——那些不再捆绑 Corepack 的 Node 版本必须单独安装它。3.2 冻结 lockfile 离线优先必要时回退 registryconst cachedInstall install(--offline); // 仅当离线安装失败才回退 console.warn(Cached install unavailable; retrying with registry access.); exitWithResult(install(--prefer-offline));安装逻辑使用pnpm install --frozen-lockfile冻结 lockfile并按以下次序决策先尝试--offline完全从共享本地 store 取包不触碰网络只有当缓存安装不完整失败、被信号杀死或状态码 ≥ 128时才回退--prefer-offline允许 registry 访问但优先使用缓存。这样设计的原因是常见 warm-store 路径上无需等待 pnpm 预取其他平台的 optional 二进制如 fsevents、esbuild 的各平台二进制--offline一次命中即可。3.3 跳过 prepare 重活但保留依赖安装脚本const env { ...process.env, QWEN_SKIP_PREPARE: 1, QWEN_SKIP_NOTICE_GENERATION: 1, };脚本设置两个环境变量QWEN_SKIP_PREPARE1跳过仓库构建、bundle 与 npm 布局相关的 notice 生成QWEN_SKIP_NOTICE_GENERATION1bootstrap 私有的 notice 生成守卫。对照 scripts/prepare.js 的实现QWEN_SKIP_PREPARE命中时prepare 会跳过husky、npm run build、npm run bundle三段重活但仍执行npm run generate生成被 gitignore 的git-commit.tscli 的systemInfo会导入它确保后续逐 workspace 构建/类型检查不会因缺模块而失败。注意这里的关键区分跳过的是仓库级构建/bundle而不是依赖安装脚本。allowBuilds白名单中的包esbuild、protobufjs 等的 install 脚本在 pnpm 布局下照常运行——这是与「为了彻底省事而全局--ignore-scripts」的本质区别。3.4 Husky 的「自己补装」与 fail-closed 判定由于QWEN_SKIP_PREPARE1同时抑制了 scripts/prepare.js 中 npm 安装才会走的 Husky 步骤引导脚本在冻结安装成功后自行安装 Husky hookspnpm exec husky并围绕 Git worktree 的 config 共享语义做了严密防护保留既有非默认 hooksPath若core.hooksPath已存在且不等于.husky/_或HUSKY0则跳过 Husky 并原样退出不拥有仓库 config 的 checkout 跳过并报告通过git rev-parse --git-dir --git-common-dir探测——--git-dir与--git-common-dir只有在 linked worktree 中才不同脚本注释明确指出.git是文件/目录/缺失都不可作为代理判断。在 linked worktree 中若 hooksPath 未设置Husky 的git config core.hooksPath .husky/_无--worktree会把值写进该仓库所有 worktree 共享的 config却只在当前 checkout 创建.husky/_包装器——脚本会跳过并提示「先在主 checkout 安装 hooks 后再重跑」探测到无仓库git 不可用或非仓库时同样跳过并报告fail closedHusky 在所有软失败找不到.git、config 写入被拒下都会以 0 退出因此成功需要双重证明——config 值确认 git 将使用 hookscore.hooksPath .husky/_且磁盘上确实存在包装器.husky/_/pre-commit。任一缺失即报错worktree setup failed: Husky did not install hooks并以非零退出树整洁性Husky 在.husky/_内生成的包装器由 .gitignore 忽略因此引导不会污染 worktree 的 git 状态。3.5 安装边界与 Stage 2 的承诺设计文档强调脚本执行不会隐式安装陈旧依赖node scripts/setup-worktree.js这一命令就是显式的安装边界——避免引导过程悄悄改变依赖状态。而基于 pnpm 布局进行构建被明确推迟到 Stage 2Stage 1 的引导不触碰任何构建产物。四、迁移边界与分阶段路线4.1 Stage 1当前仅 worktree 依赖安装只影响额外 Git worktree 的依赖安装路径不改变仓库构建命令、CI 构建编排、发布版本号、打包、发布package-lock.json对所有既有 npm 路径保持权威生成的pnpm-lock.yaml被排除在仓库「人工编写 YAML」的风格检查规则之外因为它是机器生成的锁文件。4.2 Stage 2 / Stage 3后续演进空间Stage 2可独立将 pnpm 布局升级为受支持的构建与开发路径再迁移 CI 安装与缓存Stage 3处理发布安装与构建编排最终 cutovermanifests 全面采用workspace:后移除 .pnpmfile.mjs 兼容钩子npm 仍是产品边界包创建、registry 发布、干净产物安装直到读取package-lock.json的脚本完成迁移。4.3 真实安装约束为什么packageImportMethod: clone-or-copypnpm-workspace.yaml 中的packageImportMethod: clone-or-copy是一处值得展开的工程细节。配置注释解释了根因根postinstall会运行patch-package它原地改写node_modules中的文件在 pnpm 默认的 import 方式下node_modules里的文件是 store 内容寻址条目的硬链接patch 会连带改写 store 条目——其内容不再匹配归档所用的 sha512后果是后续每个 worktree 的--offline阶段都会以ERR_PNPM_NO_OFFLINE_TARBALL失败、回退 registry 并再次 patch store离线路径永远无法命中改用clone-or-copy文件系统支持处用 copy-on-write否则普通拷贝后store 条目保持原样patch-package 只修改 worktree 自己的副本离线安装得以稳定命中。五、验证体系脚本测试 跨平台真实安装门禁5.1 单元/脚本测试设计文档声明 Stage 1 的 pnpm 路径必须满足冻结安装不得修改任何已跟踪文件。脚本测试覆盖四类行为集中在 scripts/tests/package-scripts.test.js 等脚本测试中bootstrap 命令本身setup-worktree的安装与退出语义prepare-skip 环境变量行为QWEN_SKIP_PREPARE/QWEN_SKIP_NOTICE_GENERATION的生效路径版本无关的 workspace 重写.pnpmfile.mjs的readPackage重写逻辑与 workspace 成员集合的一致性进程失败行为fail-closed 分支Corepack 缺失、Husky 未安装 hooks、config 读取失败等。5.2 跨平台真实安装门禁pnpm Worktree Smoke.github/workflows/pnpm-worktree-smoke.yml 是 Stage 1 的真实安装闸门路径过滤触发仅在 pnpm 安装相关输入变化时运行.pnpmfile.mjs、package.json、packages/*/package.json、patches/**、pnpm-lock.yaml、pnpm-workspace.yaml、scripts/setup-worktree.js、scripts/pnpm-package.js等并显式排除packages/desktop-shell与packages/live-host的 package.json三平台矩阵ubuntu-latest、macos-latest、windows-latestfail-fast: false一平台失败不取消其他平台Node 22.x node scripts/setup-worktree.js直接以真实命令执行冻结引导验证 workspace 链接可解析require.resolve(qwen-code/qwen-code-core/package.json, { paths: [packages/vscode-ide-companion] })——确认 hoisted linker 在真实环境下物化了内部依赖验证 worktree 保持干净git status --porcelain必须为空否则引导失败——这正是设计文档「冻结安装不得修改已跟踪文件」的机械化执行并发控制PR 运行可互相取消而 post-merge 的 push 运行不可取消避免静默丢失唯一的回归见证。此外现有 npm 的构建与发布校验完全不受影响——pnpm 布局下的构建被有意推迟到 Stage 2。六、实操速查如何为 qwen-code 引导一个新 worktree综合设计文档与 scripts/setup-worktree.js 的实现典型流程如下# 1. 创建 Git worktree 并检出目标分支 git worktree add ../qwen-code-wt branch # 2. 进入 worktree 后执行 pnpm 引导替代 npm install prepare cd ../qwen-code-wt node scripts/setup-worktree.js前置条件与行为约定需要Node 版本捆绑 Corepack或单独安装 Corepack否则脚本 fail closed首选完全离线的--offline安装共享本地 pnpm store 命中失败才回退--prefer-offline访问 registry引导自动跳过仓库构建/bundle/notice 生成QWEN_SKIP_PREPARE1依赖安装脚本仍按allowBuilds白名单执行Husky hooks 由引导脚本在安装成功后自行补装在共享 config 的 linked worktree 场景下会谨慎跳过并给出提示引导完成后git status应为干净状态后续构建、测试请沿用仓库既有的 npm 命令构建迁移属 Stage 2。七、小结qwen-code 的 pnpm worktree bootstrap 是一次「外科手术式」的包管理器迁移以约 99 MiB 对 1.44 GiB 的磁盘占用、22 秒对 27 秒的安装耗时把每个新 Git worktree 的依赖引导成本压缩一个数量级同时通过nodeLinker: hoisted、overrides、.pnpmfile.mjs兼容钩子、allowBuilds白名单与clone-or-copy导入方式将 pnpm 解析结果对齐到 npm 现状并严守「npm 仍是产品边界」的 Stage 1 红线。三平台路径过滤的 smoke workflow 与脚本测试共同构成其质量闸门而构建、CI 与发布链路的迁移则留给 Stage 2/3 独立演进——这种「先解决高频痛点的最小边界再逐步扩大」的迁移策略值得多包仓库在引入新包管理器时借鉴。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
