根本原因是Composer版本与merge-plugin版本不匹配：Composer 2.x禁用未签名插件，旧版wikimedia/composer-merge-plugin 1.x不支持签名，须升级为composer-merge-plugin 2.x并正确配置extra.merge-plugin、刷新autoload、解决依赖冲突。

merge-plugin 为什么装不上或不生效

根本原因通常是 Composer 版本和插件版本不匹配。Composer 2.x 默认禁用未签名的插件，而 wikimedia/composer-merge-plugin 1.x（旧版）不支持 Composer 2 的插件签名机制，直接 composer require 会静默失败或报 Plugin installation failed。

• Composer 2.2+ 必须用 merge-plugin 2.x（即 composer-merge-plugin 包，注意名字已变）
• 旧项目若还在用 wikimedia/composer-merge-plugin，必须先卸载：composer remove wikimedia/composer-merge-plugin
• 安装新版本：运行 composer require composer-merge-plugin（无 wikimedia/ 前缀）
• 确认插件已启用：执行 composer config --list | grep merge，应看到 extra.merge-plugin 配置项

如何正确配置 extra.merge-plugin

配置写错是合并失效最常见原因——不是插件没起作用，而是它根本没读到你要合并的文件。

• extra.merge-plugin 必须是顶层 composer.json 的字段，不能嵌套在其他 key 下
• include 是必填数组，值为相对路径（相对于当前 composer.json），例如：["./conf/dev-packages.json"]，不能写成 conf/dev-packages.json（缺 ./ 在某些系统下会失败）
• 被合并的 JSON 文件本身必须是合法 JSON，且顶层必须是对象（不能是数组），否则报 JSON decode error
• 如果要合并多个环境配置，推荐用通配符："include": ["./conf/*.json"]，但注意顺序：字母序靠前的文件优先级高，packages-dev.json 会覆盖 packages-base.json

合并后 autoload 不生效或类找不到

merge-plugin 只合并 require、autoload、repositories 等字段，但不会自动触发 autoloader 重建。你改了被合并的 JSON，composer install 却没重生成 vendor/autoload.php，类自然找不到。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 每次修改被合并的 JSON 后，必须运行 composer dump-autoload 或完整执行 composer install（后者更稳妥）
• 检查最终生效的 autoload 结构：运行 composer show --platform 看是否列出了你期望的命名空间映射；或直接打开 vendor/composer/autoload_static.php 搜索你的 psr-4 映射
• 如果被合并文件里写了 "autoload": {"psr-4": {"MyLib\": "src/"}}，但主项目没声明 "autoload" 字段，merge-plugin 不会自动补全顶层 autoload —— 主 composer.json 至少要有空对象："autoload": {}，否则合并逻辑可能跳过

为什么 vendor 里没下载被合并的包

看起来配置对了，composer install 也没报错，但 vendor/ 下就是没有你通过被合并文件引入的包。问题往往出在依赖解析阶段被忽略。

• merge-plugin 是在 Composer 加载阶段“预处理”配置，但它不改变依赖图解算逻辑。如果被合并的 require 里有包与主项目冲突（比如版本范围互斥），Composer 会直接拒绝安装，并提示 your requirements could not be resolved —— 这个错误容易被淹没在长日志里
• 验证是否真的合并成功：运行 composer config --json extra.merge-plugin，看输出里 include 对应的文件是否被正确读取并展开
• 临时关闭合并调试：把 include 改成一个不存在的路径，再运行 composer install —— 如果报错说“file not found”，说明插件已激活；如果不报错，说明插件压根没加载

路径拼错、JSON 格式非法、Composer 版本错配、autoload 未刷新、依赖冲突被静默跳过——这五点覆盖了 90% 的真实故障。尤其注意被合并文件的路径必须带 ./，这个点连官方文档都曾写错过。