composer 不支持给第三方包添加全局注释，补丁机制仅用于临时修复，强行注入注释会导致维护困难、版本更新失败、协作信息不同步；应改用项目文档、类型声明或封装薄层等可控方式。
composer 本身不支持“给第三方包添加全局注释”这种操作——注释不是可运行逻辑，补丁机制也不会、也不该被用来插入无功能的注释。如果你真这么做了，只会徒增维护负担，且极易在版本更新后失效。
补丁不是文档工具，是临时修复手段
你看到的“用补丁加注释”，本质上是把 composer-patches 当作文档附着器，这违背了它的设计意图。插件只负责在 composer install 时调用系统 patch 命令应用差异，它不校验注释是否有意义，也不关心你加的是 // TODO: fix this 还是 /** @var string $x */。
更关键的是：一旦原包发布新版本，补丁很可能因 hunk 偏移错位而失败，composer install 直接中断报错；而你加的那些注释，既没进上游 PR，也没写进项目文档，纯属“私有幻觉”。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 补丁文件里混入大段注释 →
git apply --check可能误判上下文偏移，导致应用失败 - 注释路径写成
vendor/xxx/src/…→ 补丁格式非法，插件跳过或报错 - 多人协作时，别人
composer install后看不到你的注释（因为没跑 patch）→ 信息不同步
想让团队理解第三方包行为？用这三种真正有效的方式
与其把注释塞进 vendor 源码，不如把解释留在可控、可维护、可搜索的地方：
-
项目级文档：在
docs/3rdparty-notes.md里写清楚 “为什么我们用了monolog/monolog:^3.5”、“StreamHandler的$useLocking在 PHP 8.2 下必须设为false，否则死锁”，并链接到对应 issue 或 PR -
类型声明 + 内联 docblock：在你自己的代码里对第三方对象做强类型注释，例如：
/** @var \Monolog\Handler\StreamHandler $handler */，PHPStan/IDE 都能识别 -
封装薄层（wrapper）：新建
src/Infrastructure/Logging/RobustStreamHandler.php，继承并包装原类，在构造函数或方法里写明限制和绕过原因，这才是可测试、可替换、可归档的“注释”
如果非要用补丁加注释，至少守住这三条底线
极少数场景下（比如调试阶段临时标记、CI 中注入诊断信息），你坚持要打注释补丁，请确保：
- 补丁文件名明确带
-debug或-note后缀，例如：patches/monolog-debug-note.patch，避免和修复类补丁混淆 - 补丁内容只改单个文件、单行附近，用
git diff --no-prefix -U1生成（减少上下文依赖），且提前运行git apply --check patches/xxx.patch验证 - 在
composer.json的extra.patches描述里写清用途，例如："Debug-only note for StreamHandler locking behavior": "patches/monolog-debug-note.patch"，而不是模糊的"Fix logging"
最常被忽略的一点：这类补丁必须在 .gitignore 里排除掉，或者至少加进 CI 的清理步骤——它们不该出现在生产构建中，也不该被当成正式修改提交到主干。
