monorepo-builder 是 Symplify 独立工具，非 Composer 内置；需手动配置 repositories、子包 composer.json 及 monorepo-builder.php 路径；merge 仅处理内部包依赖；release 前须确保 Git 干净、用户信息完备并启用版本递增；path 仓库与 monorepo-builder 各司其职，CI 中需切换至真实包源。
monorepo-builder 不是 Composer 的内置功能，它是一个独立的 Symplify 工具，必须显式安装并配合正确的仓库结构和配置才能生效；直接运行 composer install 不会触发任何 monorepo 合并或发布逻辑。
monorepo-builder init 初始化后要手动补全哪些配置
执行 vendor/bin/monorepo-builder init 只生成骨架文件（如 monorepo-builder.php），不自动修改 composer.json 或创建子包目录。你需要立刻做三件事：
- 在根
composer.json的repositories中添加path类型仓库，例如：{"type": "path", "url": "packages/*"}（注意：不支持**递归） - 确保每个子包目录（如
packages/utils）下有合法的composer.json，且含完整name字段（如"myorg/utils"）和autoload - 检查
monorepo-builder.php中的$config->setPackagesDir('packages')是否匹配你的真实路径；默认是packages，但如果你用的是libs或src，必须改掉
merge 命令为什么没把子包 require 写进根 composer.json
vendor/bin/monorepo-builder merge 只合并「子包中声明为 require 且 name 在当前 monorepo 内部」的依赖——它不会拉平所有子包的 require-dev，也不会处理外部包（如 phpunit/phpunit）。常见失效原因：
- 子包的
composer.json里用了"myorg/utils": "^1.0"，但该包本身不在packages/下（路径没被repositories覆盖） - 子包
name和require中的包名大小写不一致（Composer 区分大小写） - 根
composer.json缺少"minimum-stability": "dev"，导致"@dev"版本被忽略
验证方式：运行 vendor/bin/monorepo-builder merge --dry-run，看输出是否列出你预期的包。
release patch 失败时先查哪三个地方
vendor/bin/monorepo-builder release patch 本质是批量修改 + Git 提交 + 打 Tag，失败往往卡在环境准备环节：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Git 工作区是否干净？
git status必须显示nothing to commit, working tree clean，否则命令直接退出 - 是否已配置 Git 用户信息？
git config user.name和git config user.email必须有值，否则 Tag 创建失败 -
monorepo-builder.php中是否启用了$config->enableReleaseVersioning()？没这句，版本号不会自增，Tag 名会重复（如反复打v1.0.0）
另外注意：release 不会自动 push 到远程——它只做本地操作。你得自己跑 git push --tags origin main。
monorepo-builder 和 path repositories 是两套平行机制
很多人误以为装了 monorepo-builder 就不用配 repositories，其实完全相反：monorepo-builder 管版本和发布，path 仓库管开发期依赖加载。两者缺一不可。
典型协作流是：path 仓库让 composer install 把子包软链接进 vendor/ → 开发者改代码实时生效 → monorepo-builder release 统一升版、打 Tag、更新各子包 composer.json 中的依赖约束 → CI 用新 Tag 安装正式包。
最容易被忽略的点：CI 环境里不能依赖 path 仓库（因为没源码目录），所以 release 后必须把子包推到 Packagist 或私有仓库，并在根 composer.json 中切换回 packagist 源——这个切换动作不会自动发生。
