Composer插件必须同时满足type为"composer-plugin"、主类实现PluginInterface、autoload路径准确加载三条件才被激活；缺一即静默失效，且所有逻辑须在activate()中通过$composer和$io执行。
Composer插件不是“加个类就能用”的东西，它必须同时满足三个硬性条件才能被识别和激活：type为composer-plugin、主类实现PluginInterface、autoload路径能准确加载该类。漏掉任一环，插件就静默失效。
composer.json 必须声明 type 且配置 extra.class
Composer 不靠目录结构或文件名识别插件，只认 composer.json 里的元信息。常见错误是把插件当普通库写，漏掉关键字段：
-
"type": "composer-plugin"—— 缺了这行，Composer 直接跳过激活流程 -
"extra": { "class": "MyVendor\MyPlugin" }—— 类名必须带完整命名空间，且与autoload配置严格对应 -
"require": { "composer-plugin-api": "^2.9" }—— 版本必须匹配你目标 Composer 主版本（2.x 就不能写 ^1.0）
activate() 是唯一可挂载逻辑的入口，别在构造函数里做事
插件类的 __construct() 在 Composer 初始化早期就被调用，此时 $composer 和 $io 还没准备好。所有实际操作必须放在 activate() 方法里：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 监听事件要用
$composer->getEventDispatcher()->addListener()或实现EventSubscriberInterface并在activate()中注册 - 注册自定义命令需实现
CommandProviderInterface，并在activate()中确保命令类可加载 - 修改安装器行为（如支持新包类型）要通过
$composer->getInstallationManager()->addInstaller() - 避免在
activate()中做耗时 I/O 或网络请求，CI 环境下容易超时
监听事件必须匹配具体 Event 子类，签名错就静默失败
Composer 的事件系统不接受泛型回调。比如监听 post-install-cmd，处理器方法必须接收 CommandEvent 实例，而不是 Event 或空参数：
public function onPostInstall(CommandEvent $event) {
// ✅ 正确：类型明确
}
public function onPostInstall($event) {
// ❌ 错误：运行时可能 ArgumentCountError 或不触发
}
- 常用事件类型：
CommandEvent（命令类）、PackageEvent（包安装/更新）、ScriptEvent（脚本执行） -
post-autoload-dump只在 autoloader 文件实际生成时触发，不是每次install都走；开发调试建议加--no-cache -v - 监听器内抛出未捕获异常会中断整个 Composer 命令，务必用
try/catch包裹业务逻辑
路径和配置读取不能依赖 getcwd()，要用 $composer 提供的接口
插件可能在任意工作目录下被加载（比如全局安装、子模块、CI 工作流），getcwd() 和相对路径不可靠：
- 项目根目录应通过
$composer->getConfig()->get('vendor-dir')反推，或直接用$composer->getPackage()->getAutoload()获取已解析的 autoload 配置 - 不要手动
file_get_contents('composer.json')—— 路径可能错，且绕过了 Composer 的 schema 校验和 normalize 处理 - 想改配置？插件不能自动重写
composer.json，只能用$io->writeError()提示用户手动运行composer update
最常被忽略的一点：插件类的命名空间和 autoload 路径必须完全一致，哪怕多一个斜杠或大小写偏差，都会导致类加载失败，PluginInterface 根本不会被实例化——而 Composer 不报错，只会安静地跳过。调试时先确认 composer show --plugin 是否列出你的插件，再看日志输出是否进到 activate()。
