composer 本身不生成文档，需在 composer.json 的 "scripts" 中定义如 "docs" 命令调用 phpdocumentor 等工具；支持 shell 命令、多步骤或 php 回调，但须确保工具已安装、路径正确且环境兼容。
Composer 本身不生成文档，但可以通过 scripts 配置项调用外部工具（如 phpDocumentor、phpstan、apidoc）来自动化生成文档；关键在于脚本定义是否正确绑定到生命周期事件，以及执行环境是否具备依赖。
如何在 composer.json 中定义文档生成脚本
脚本必须写在 "scripts" 下，推荐使用 "docs" 或 "generate-docs" 作为自定义命令名，避免与 Composer 内置命令冲突。注意：脚本值是字符串数组或单个字符串，支持 shell 命令和 PHP 回调。
- 用 shell 命令调用 phpDocumentor：
"docs": ["phpdoc -d src -t docs/api"] - 用 vendor 二进制确保一致性：
"docs": ["vendor/bin/phpdoc -d src -t docs/api"] - 支持多步骤（如清理 + 生成）：
"docs": ["rm -rf docs/api", "vendor/bin/phpdoc -d src -t docs/api"] - 若用 PHP 回调，需确保类方法存在且可访问：
"docs": ["My\Doc\Generator::run"]
为什么 composer run docs 报错“command not found”
常见原因不是 Composer 问题，而是执行上下文缺失：当前目录没找到 vendor/bin，或工具未安装，或权限不足。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 确认 phpDocumentor 已本地安装：
composer require --dev phpdocumentor/phpdocumentor - 检查
vendor/bin/phpdoc是否存在（Windows 下可能是phpdoc.bat） - 不要用
sudo composer run docs—— root 用户下vendor可能不可见 - 某些共享主机禁用
exec()，PHP 回调方式也会失败 - 路径含空格时，shell 模式容易出错，建议改用 PHP 脚本封装
如何让文档生成自动触发（如 composer install 后）
Composer 支持事件钩子，但要注意：文档生成属于开发阶段行为，不应绑定到 post-install-cmd 这类生产相关事件，否则部署时会拖慢流程甚至失败。
- 安全做法是只绑定到
post-update-cmd（仅开发者更新依赖后生成）："post-update-cmd": ["@docs"] -
@docs表示复用已定义的docs脚本，避免重复写命令 - 若想每次
composer install都跑，得显式加"post-install-cmd": ["@docs"]，但不推荐 - CI/CD 中更可靠的方式是单独写 pipeline 步骤，而非依赖 Composer 事件
真正麻烦的是跨平台兼容性——rm -rf 在 Windows 上失效，vendor/bin 路径在不同 PHP 版本下可能指向不同位置，还有 phpDocumentor v3 要求 PHP 8.1+。这些细节不手动验证一遍，光靠配置文件里的几行脚本根本跑不起来。
