本技能面向需要为已有 TypeScript 仓库引入构建模式（project references）图的场景，目标是在不破坏现有构建、公共 API 与运行时行为的前提下完成迁移。
一、用途 将现有仓库的构建或类型检查入口接入 tsc -b，使根配置采用 solution 风格（files 为空、references 列表），由根命令统一构建各项目，并支持增量构建与声明输出。
二、主要能力
- 引用图设计：从 package.json 依赖与源码实际导入两方面推导项目引用，检查缺失的直接边与循环引用，确保整张图可从根 solution 到达。
- 工作区校验：在 npm/yarn/pnpm/lerna 工作区中，使用 @monorepo-utils/workspaces-to-typescript-project-references --check 比对各包 tsconfig 引用与其工作区依赖，差异通过修改引用解决，不移动或排除源码。
- 配置诊断：用 tsc --showConfig、tsc -p <project> --listFilesOnly 检查 include、files、exclude、outDir、rootDir、tsBuildInfoFile 等继承配置的实际解析位置，覆盖 .ts、.tsx、.mts、.cts 各类文件。
- isolatedDeclarations 迁移：需 TS 5.5+ 且 requires declaration 或 composite，需为导出函数、变量、类、对象成员补全显式注解，按依赖顺序逐包处理，并注意打包器与声明插件可能切换声明生成器。
- 公共 API 保护：比较变更前后 .d.ts 或 API 报告，区分签名变化与仅打印差异，不手工编辑快照文件。
三、使用方式 先按锁文件执行冻结安装，记录根 build、typecheck 及全部测试与 API/声明检查的基线；随后盘点包与现有构建链，设计引用图；将 tsc -b 接入现有根构建或类型检查脚本（而非新增无人调用的脚本）；保留原有打包器与任务运行器，缓存需至少一次无缓存运行；最后依次执行引用检查、格式化与 lint、干净的 tsc -b --verbose 及第二次增量构建、原生 build/typecheck/完整测试。
四、适用场景 已有较大规模 TypeScript 仓库需要划分项目边界、实现增量构建与独立声明输出；monorepo 中包间依赖与引用需保持一致；计划启用 isolatedDeclarations。
五、限制 需使用仓库本地编译器，不应临时通过 npx 安装无关的 tsc 包；不应为通过迁移而放宽 strict、checkJs 等检查或使用 @ts-ignore；无法运行的测试需如实报告；isolatedDeclarations 在低于 5.5 的固定版本中应跳过并说明。