Composer的scripts字段不支持注释，JSON语法本身禁止注释；推荐三种替代方案：①根级添加非标准字段scripts-descriptions供人阅读；②脚本命令内置--help支持运行时提示；③README.md中手动维护scripts表格并随PR同步更新。
scripts 字段里不能直接写注释
Composer 的 composer.json 里 scripts 是个纯键值对对象，只认脚本命令，不解析注释。你加 // 或 /* */ 没用，JSON 语法本身就不支持注释，强行加会导致 composer validate 报错：JSON decode error: Syntax error。
想让团队知道 post-install-cmd 干啥、为啥要跑、有没有副作用，得绕开 JSON 注释限制。
用 scripts-descriptions 扩展字段配合 composer-unused 或自定义检查
官方没提供脚本描述字段，但社区有约定做法：在 composer.json 根级加一个非标准字段 scripts-descriptions，手动维护映射关系。它不会被 Composer 解析或执行，纯供人读。
-
scripts-descriptions必须是对象，key 对应scripts中的脚本名，value 是字符串说明 - 团队成员查脚本用途时，直接
cat composer.json | grep -A 10 "scripts-descriptions"就能扫到 - CI 流程中可用
composer-unused（需 v2.5+）配合--with-scripts-descriptions检查描述是否缺失，避免“写了脚本但没人敢动” - 注意：这个字段对 Composer 完全透明，删掉也不影响安装/脚本执行，但别拼错 key 名，否则工具识别不了
在脚本命令里塞 --help 或 -h 参数做运行时提示
如果脚本是 PHP 文件或可执行命令，最实在的办法是让它自己支持帮助输出。比如你的 dev:clear-cache 脚本指向 php bin/console cache:clear，那就改用封装函数：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
#!/usr/bin/env php
<?php
if (in_array('--help', $argv) || in_array('-h', $argv)) {
echo "Usage: composer run-script dev:clear-cache\n";
echo " Clears dev-mode caches, skips prod warmup.\n";
echo " ⚠️ Does NOT clear opcache — run 'opcache-reset' separately.\n";
exit(0);
}
// 实际逻辑...
这样执行 composer run-script dev:clear-cache -- --help 就能弹出说明，比翻 JSON 更及时。
- 必须用
--分隔 Composer 参数和脚本参数，否则--help被 Composer 截获 - PHP 脚本里用
$argv判断，Shell 脚本用$@和case匹配 - 别依赖
echo长文本——有些 CI 环境会截断输出，关键约束写进注释或 README 里更稳
README.md 里同步维护 scripts 表格，用代码块列 command + description
文档落地最靠谱的方式，还是人肉同步。在项目根目录 README.md 里建个表格，字段就两列：Command 和 Description，每行对应一个 scripts 键。
示例片段：
| Command | Description | |---------|-------------| | <code>test</code> | Run PHPUnit with coverage; requires Xdebug enabled | | <code>lint:php</code> | Run PHP-CS-Fixer in dry-run mode — auto-fixes on PR merge | | <code>build:prod</code> | Compile assets, purge cache, generate proxy classes |
- 表格必须手写，别用脚本自动生成——一旦生成逻辑出错，文档反而误导人
- 每次新增/修改脚本，PR 描述里必须包含 “✅ updated README scripts table”
- GitHub/GitLab 页面打开就能看到，新成员不用猜
ci:setup是初始化 DB 还是启动 Selenium
真正难的不是加描述，而是让描述随脚本逻辑一起演进。有人改了脚本行为却忘了更新 scripts-descriptions 或 README，这种脱节比没描述更危险。
