SuperAPI AI 工具集

monorepo

编程与开发

查看项目

更新于 10-31 13:14

技能介绍

用途

该技能帮助 AI 在单体仓库(monorepo)中正确导航与操作。单体仓库会打破许多默认假设:哪个 package.json 才是“真正”的、node_modules 位于何处、应运行哪条测试命令、install 实际做了什么。该技能确保所有操作都针对正确的作用域。

检测

在会话开始或首次编辑文件时,检查以下标志文件:

  • pnpm-workspace.yaml → pnpm workspaces
  • turbo.json → Turborepo
  • nx.json → Nx
  • lerna.json → Lerna
  • package.json 含 "workspaces": [...] → npm / yarn workspaces
  • Cargo.toml 含 [workspace] → Rust workspaces
  • go.work → Go workspaces
  • pyproject.toml 含 Poetry/uv workspace 配置 → Python workspaces

若检测到上述标志,则进入单体仓库模式,并记录到工作流状态中。后续所有命令都必须遵守包作用域。

主要规则

  1. 始终先确定目标包。在任何 install、test 或 build 之前,明确改动位于哪个包,并使用完整路径如 packages/<name>/;以作用域方式运行而不是从根目录运行,例如 pnpm --filter <name> test。

  2. 跨包变更需要协调。如果改动涉及包 A 的 API 且被包 B 使用,应列出所有消费者(例如 grep -r "@your-org/package-a" packages/),在同一 PR 中更新所有消费者,并对所有受影响包运行测试,而不仅是包 A。

  3. 依赖放置很重要。仅被一个包使用的依赖放入该包的 package.json;被两个及以上包使用的依赖放入共享配置包或根 devDependencies;开发工具(eslint、prettier、jest)放根目录;工作区包在消费者 dependencies 中以 "workspace:*" 列出。

  4. 构建顺序遵循依赖图,不要假设按字母顺序构建。可查看 Turborepo 的 turbo.json pipeline 字段、Nx 的 nx graph,或运行 pnpm list --recursive --depth=0。

  5. 测试按作用域运行,而非从根目录运行。错误做法:npm test(运行全部测试,慢且常出错)。正确做法示例:turbo test --filter=[HEAD^1]、nx affected:test、pnpm --filter='...[HEAD^1]' test。[HEAD^1] 计算自上次提交以来受影响的包,CI 应使用相同方式。

常见陷阱

  • node_modules 提升:包 A 可能意外使用包 B 的传递依赖,B 变更时 A 会出错。修复方式为显式声明依赖,不依赖提升。
  • TypeScript 项目引用:在跨引用运行 tsc --build 之前,包 A 的改动不会出现在包 B 中。检查 tsconfig.json 的 references。
  • Jest/Vitest 根配置:可能不会拾取每个包的配置。确认单体仓库工具正确交接(Turborepo 和 Nx 通常可以;原生 pnpm 不行)。
  • CI 矩阵:每个 PR 都运行全套测试会浪费成本,应使用仅受影响检测。
  • 锁文件:npm 7+ 和 pnpm 在根目录保留单一锁文件,不要提交每个包的锁文件。

与工作流的集成

  • 阶段 1 设计:识别计划中涉及的所有包。
  • 阶段 2 测试:仅针对受影响的包。
  • 阶段 3 构建:运行作用域构建,而非根构建。
  • 阶段 4 评审:检查跨包契约(版本间 API 兼容性)。

关联技能

  • skills/framework-expert/SKILL.md:所用框架可能有单体仓库特定的集成。
  • skills/test-writer/SKILL.md:单体仓库中的测试放置(按包还是共享测试目录)。
  • rules/core/verification.md:验证命令在正确作用域中运行(实际执行了哪些测试)。
  • commands/run.md:run-orchestrator 在检测到单体仓库标志时加载该技能。

限制

资料未提供收费、价格、平台支持范围或效果数据。