monorepo-navigator

Monorepo 导航

导航、管理并优化任意规模的 monorepo。涵盖 Turborepo、Nx、pnpm 工作区和 Lerna/Changesets，支持跨包影响分析、仅对受影响的包选择性构建、依赖关系图可视化、远程缓存配置、保留 git 历史记录的多仓库迁移到 monorepo，以及通过自动生成变更日志协调发布包。

关键词： monorepo、Turborepo、Nx、pnpm 工作区、Changesets、依赖关系图、远程缓存、受影响的包、选择性构建、跨包影响、npm 发布、工作区协议

核心功能

• 影响分析 — 确定共享包变更会导致哪些应用出问题、追踪依赖链、可视化 Mermaid 图，并计算影响范围。
• 选择性执行 — 仅对受影响的包运行测试/构建、按自某个 git ref 以来变更的文件进行筛选，并在 CI 中跳过未变更的包。
• 构建优化 — 远程缓存（Turborepo/Vercel、Nx Cloud）、通过输入/输出配置进行增量构建、依赖感知的并行调度，以及构件共享。
• 发布 — 使用 Changesets 协调版本管理、自动生成每个包的变更日志、预发布渠道，以及发布时替换 workspace:*。

适用场景

• 多个包/应用共享代码（UI 组件、工具函数、类型、API 客户端）
• 每次变更都会触发全部重建，导致构建耗时过长
• 从多个仓库迁移到单一 monorepo
• 以协调的版本管理方式发布 npm 包
• 团队跨包协作，需要统一的工具链

先确认

在进行分析或配置之前，请先确认以下信息。如果任何一项未知或不明确，请先询问 — 不要自行假设：

• 工具链 — Turborepo、Nx、pnpm 工作区或 Changesets（决定生成的配置和命令）
• 任务 — 影响/依赖分析、构建优化或发布设置（决定使用 dependency_graph.py、impact_detector.py 还是 package_analyzer.py）
• 仓库根目录和 git ref — monorepo 路径以及用于检测“受影响”范围的基准 ref（决定 --ref 参数以及如何判断变更）

停止规则：只询问最可能改变输出的 2-3 项。如果用户说“直接起草”，则继续操作，并在产物开头列出假设。

工具

工具	用途	命令
dependency_graph.py	生成内部包的 Mermaid 依赖关系图	python scripts/dependency_graph.py . --focus @repo/ui --direction dependents
impact_detector.py	检测哪些包受到文件变更的影响	python scripts/impact_detector.py . --ref origin/main --affected-only
package_analyzer.py	分析包的结构、依赖关系和健康状况	python scripts/package_analyzer.py . --only-shared

参考资料

加载与任务相符的参考资料 — 保持此文件精简，按需查阅详细内容：

• references/tooling-and-configuration.md — 工具选择决策矩阵、推荐的仓库结构、完整的 turbo.json 和 pnpm-workspace 配置、Turborepo/pnpm 关键命令、影响分析命令、远程缓存设置、仅针对受影响包的 CI 工作流、Changesets 发布，以及从多仓库迁移到 monorepo 的步骤。配置或运维 monorepo 时阅读。
• references/operations-and-best-practices.md — 常见问题、最佳实践、故障排查表和成功标准。遇到异常或验证设置时阅读。

范围与限制

此技能涵盖：

• Turborepo、Nx 和 pnpm 工作区配置与优化
• 跨包依赖分析和影响可视化
• 远程缓存设置（Vercel、Nx Cloud、可自托管）
• 基于 Changesets 的协调版本管理和 npm 发布

此技能不涵盖：

• 应用级构建配置（webpack、Vite、esbuild 内部机制）——参见 performance-profiler
• 超出单体仓库专属筛选器范围的 CI/CD 流水线设计——参见 ci-cd-pipeline-builder
• Git 分支策略和发布流程——参见 release-manager
• 依赖项漏洞扫描和许可证审计——参见 dependency-auditor

集成点

技能	集成方式	数据流
ci-cd-pipeline-builder	感知单体仓库的 CI 工作流使用 --filter 标志和远程缓存令牌	Monorepo Navigator 定义筛选模式和缓存配置，供 CI 流水线使用
release-manager	Changesets 版本管理接入发布编排和标签管理	Release Manager 在发布流程中触发 changeset version 和 changeset publish
dependency-auditor	工作区依赖关系图为漏洞和许可证扫描确定范围	Monorepo Navigator 导出软件包依赖树，供 Dependency Auditor 分析
performance-profiler	构建分析数据可识别需要优化的缓慢软件包	Performance Profiler 测量各软件包的构建时间，这些时间由 Turborepo --summarize 汇总
changelog-generator	Changesets 生成各软件包的变更日志，供发布说明使用	Changeset 摘要传递给 Changelog Generator，以生成格式化的发布文档
tech-debt-tracker	跨包耦合和循环依赖会显现为已跟踪的技术债务事项	Monorepo Navigator 的影响分析可识别耦合热点，供 Tech Debt Tracker 记录