composer-plugin-api 是 Composer 定义的虚拟接口契约，用于声明插件兼容的生命周期规范版本；不能写 "^2.0" 因其不存在，2.0.0–2.1.x 实际无对应 API，最低有效版本是 2.2.0。
composer-plugin-api 是什么，为什么不能直接写 "composer-plugin-api": "^2.0"
它不是个可安装的包，而是 Composer 内部定义的一套接口契约，插件通过声明它来告诉 Composer：“我实现了哪个版本的插件生命周期规范”。你填错会导致 PluginManager 根本不加载你的插件，且无明确报错——只在 composer diagnose 里提示 “plugin not loaded”，非常隐蔽。
真正起作用的是 composer-plugin-api 这个虚拟包名在 composer.json 的 require 或 conflict 字段中的声明方式：
-
"composer-plugin-api": "^1.1.0"→ 兼容 Composer 1.x（1.10.0+）和早期 2.0.0～2.1.x -
"composer-plugin-api": "^2.2.0"→ 仅兼容 Composer 2.2.0 及以上（因 2.2 引入了PluginInterface::activate()新签名） - 别写
"^2.0"：Composer 2.0.0～2.1.x 不提供2.0.0这个 API 版本号，实际最低是2.2.0
如何查清你插件要支持的 Composer 最低版本
看你要用的 API 是否存在于目标 Composer 版本中。最可靠的方式不是查文档，而是翻对应 Composer tag 的源码：
- 打开 Composer 2.2.22 的 Plugin 目录，看
PluginInterface.php里方法签名 - 对比
2.5.8（当前稳定）的同一文件，确认getPluginCapabilities()、activate()参数是否变化 - 若用了
$io和$composer以外的参数（如$api），那必须声明"composer-plugin-api": "^2.5.0"
常见误判点：composer-plugin-api 版本 ≠ Composer CLI 版本。比如 Composer 2.4.4 实际提供的是 2.4.0 插件 API；而 2.2.22 提供的是 2.2.0 —— 二者不可混用。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
composer.json 中声明的三种典型模式
根据插件目标用户范围选择，不是越新越好：
- 向后兼容老项目（如企业私有库仍用 Composer 1）：
"require": { "composer-plugin-api": "^1.1.0" }，同时代码里用class_exists('Composer\Script\Event')做运行时降级 - 专注现代项目（放弃 Composer 1）：
"require": { "composer-plugin-api": "^2.2.0" }，可安全使用activate(Composer $composer, IOInterface $io, array $parameters) - 强制拦截不兼容版本（防用户硬装）：
"conflict": { "composer-plugin-api": " + <code>"require": { "composer-plugin-api": "^2.5.0" }，避免因 API 缺失导致静默失败
测试插件是否真被识别，绕过缓存陷阱
本地开发时改了 composer-plugin-api 声明，但 composer install 没反应？大概率是 Composer 缓存了插件元信息。必须手动清理：
- 删掉
vendor/composer/autoload_plugins.php - 删掉
composer.lock（或至少删掉其中packages-dev下你的插件条目） - 运行
composer clear-cache（虽不总必要，但能排除干扰） - 再执行
composer install -v，观察输出里是否出现Loading plugin YourVendor\YourPlugin
最容易被忽略的是：Composer 会把插件类名哈希后缓存在 autoload_plugins.php 里。哪怕你改了 composer.json，只要这个文件没重建，就永远走旧路径。
