pi-extensions 是一个基于 npm workspaces 的 Monorepo，统一管理 37 个可独立安装的 Pi Coding Agent 扩展，并配套了一套完整的构建、测试与 Changesets 发布流水线。本文带你快速读懂它的工程体系：从 esbuild 构建、Vitest 测试隔离，到 Changesets 独立版本管理与自动化发布，全部拆解清楚，适合想学习大型 Monorepo 工程实践的新手读者。

项目全景：一个扩展仓库如何组织

仓库根目录只保留了最核心的配置与脚本，所有业务代码都按"一包一目录"的方式组织：

几个关键设计决策（见 AGENTS.md）：

• 每个扩展独立可安装：包名统一使用@narumitwnpm scope，如@narumitw/pi-goal，用户只装需要的部分；
• 单一入口点：每个扩展只声明一个入口，./src/index.ts或构建产物./dist/index.ts（由 Pi 的 Jiti 运行时直接加载）；
• 废弃即隔离：不再维护的包移入deprecated/，不参与 workspace 脚本，避免污染门禁。

构建体系：esbuild + 共享 runtime builder

构建入口是根 package.json 中的npm run build，它遍历所有 workspace 执行各自的构建。真正的构建策略集中在 scripts/runtime-builder.mjs：

各包只保留"入口、banner、临时目录前缀、eager 边界"等包级差异，共享同一套 esbuild 打包、确定性 staging、SHA-256 基线校验与失败回滚逻辑。

这种"策略集中、差异声明"的做法值得借鉴。以 packages/pi-goal/package.json 为例：

"scripts": { "build": "node scripts/build-runtime.mjs", "prepack": "npm run build" }

构建细节可参考 docs/runtime-builder.md：打包时外部化 Pi 自带的 peer 依赖、保留动态 import 边界、验证生成的相对导入路径，确保产物在 Pi 的 Jiti 运行时中可独立加载。

测试体系：Vitest + 共享模块边界 + 耗时报告

npm test由 scripts/run-tests.mjs 驱动，完整链路为：构建 → 测试代码编译 → Vitest 运行，每个阶段单独计时并输出。几个亮点：

1️⃣ 影响面测试选择

通过PI_EXTENSIONS_TEST_BASE环境变量提供 diff 基线后，select-affected-tests.mjs 只挑选受影响的测试文件运行；本地默认跑全量，CI 按变更裁剪。

2️⃣ 隔离与共享双项目

vitest.config.ts 定义了两个 project：

• isolated：默认每个测试文件独立 fork，保证状态互不污染；
• shared：仅运行经过人工审计、列入 test/shared-module-tests.ts 白名单的 203 个文件，共享模块状态以换取速度。

配合forks线程池、最多 2 个并发 worker、5 秒单测超时，在保证集成测试（会 spawn Git、LSP、MCP 子进程）稳定的前提下把全量中位数从 241s 压到174s，下降 27.7%——完整数据与准入规则见 docs/test-performance.md。

3️⃣ 性能报告与字节码缓存

• 自定义 reporter test/vitest.timing-reporter.ts 把每个文件/包的耗时写入node_modules/.cache/pi-extensions-test-report.json，控制台只打印最慢的 5 个包；
• 开启 Node 原生字节码缓存加速重复加载，同时尊重NODE_DISABLE_COMPILE_CACHE等既有开关。

4️⃣ 提交前快速门禁

Husky 的 pre-commit 钩子执行 scripts/pre-commit.sh：对暂存文件跑 Biome 检查 + 增量类型检查，把反馈周期压缩到秒级。

静态检查：三条并行的质量闸

npm run check先执行构建，再通过 scripts/run-checks.mjs 并行运行三项检查：

其中边界检查体现了"扩展互不依赖"的核心原则：包之间只能通过 Pi 公共 API 或可复用库通信，直接 import 另一个扩展的源码会被静态拦截。

发布体系：Changesets 独立版本 + 自动化流水线

这是本工程最值得学习的部分。

Changeset：把"发版意图"写进 PR

修改会影响已发布行为时，开发者在 PR 中运行：

npm run changeset

交互式选择受影响的包和 SemVer 级别（patch/minor/major），生成一个 Markdown 文件提交到 .changeset/ 目录。规则见 .changeset/README.md：

• 包版本完全独立：fixed、linked保持为空，互不捆绑；
• 纯文档、测试、工具类改动不需要 changeset；
• pi-tui-kit新 API 与其首个消费方可以共用一个 changeset，但要求"先发布 Kit，再发布消费方"。

三段式自动发布：version → publish → none

changeset 合并进main后，发布工作流自动选择模式（见 docs/release-workflow.md 与 docs/publish-workflow.md）：

1. version：存在未消费的 changeset → 自动创建/更新一个Version PR，只改版本号、changelog 和 lockfile，合并即触发下一轮；
2. publish：存在未发布的版本号 → 先npm run build，再以NPM_CONFIG_IGNORE_SCRIPTS=true打包（避免prepack二次构建竞争），产物连同 SHA256 哈希作为 artifact 传给 publish job；
3. none：无事可做，跳过。

发布守护：不重打包、先验证

publish-packed-packages.mjs 是官方 Changesets publisher 外的一层 guard：

• 发布依赖方之前，先按精确名称和版本从 registry 拉取依赖 tarball，用SRI 哈希校验完整性（如 verifyRegistryIntegrity）；
• 校验失败或发布失败即停止后续批次，绝不重打包或覆盖已发布版本——npm 发布不是原子操作，恢复策略详见 docs/coordinated-releases.md；
• 权限最小化：只有 publish job 持有 npm Trusted Publishing 的id-token: write，version job 用 PAT 保证生成的 PR 能触发 CI。

依赖安装策略

docs/dependency-installation.md 定义了严格的供应链防线：CI 用npm ci、安装脚本白名单allowScripts精确到"包名+版本"身份、新解析的第三方依赖强制3 天最小发布龄（仅pi-tui-kit自身豁免），preflight 脚本 scripts/check-install-policy.mjs 在安装前逐项校验。

命令速查表

总结：三条可复用的工程经验

1. 门禁分层：pre-commit 秒级反馈 →npm run check并行静态检查 →npm test全量测试 → CI 发布前再跑一遍，越靠近发布的门禁越重；
2. 测试提速靠"审计过的例外"：不是无脑共享模块，而是用白名单 + 状态准入规则（docs/test-performance.md）逐文件评审后才允许进入 shared 池；
3. 发布意图与发布动作解耦：changeset 文件让每个 PR 自带发版说明，自动 Version PR 让人类只做最终合并决策，发布侧用哈希校验守住产物完整性。

这套体系让 37 个扩展既能独立演进版本，又能共享一套可靠的构建、测试与发布基础设施——这正是大型 Monorepo 工程实践的教科书式案例。