scripts-descriptions 是 Composer 的配置项，用于为 composer.json 中 scripts 下的自定义脚本提供人类可读描述，仅影响 composer list 和 composer run --list 输出，需与 scripts 同级且脚本名严格匹配。
scripts-descriptions 是什么，它在哪起作用
scripts-descriptions 是 Composer 的一个特殊配置项，用于给 composer.json 中定义的自定义脚本（即 scripts 下的命令）添加人类可读的说明。它本身不改变任何行为，只影响 composer list 和 composer run --list 的输出——没有它，自定义脚本只会显示为无描述的命令名。
如何正确声明 scripts-descriptions 配置
必须将 scripts-descriptions 作为顶层字段写在 composer.json 里，与 scripts 同级；键名需完全匹配 scripts 中的脚本名，值为字符串描述。大小写、空格、连字符都必须严格一致。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 错误写法：
"scripts-descriptions": { "post-install-cmd": "Runs after install" }—— 如果scripts里实际是"post-install-cmd"，这没问题；但如果脚本名是"post-install"或"postInstall"，就完全不生效 - 正确示例：
{ "scripts": { "dev-start": "php -S localhost:8000 -t public", "test-ci": "vendor/bin/phpunit --no-coverage" }, "scripts-descriptions": { "dev-start": "Start local dev server on port 8000", "test-ci": "Run PHPUnit without coverage (fast CI mode)" } } - 描述文本支持空格和标点，但不要换行或 JSON 注释（JSON 不允许）
scripts-descriptions 不生效的常见原因
最常遇到的问题不是语法错，而是位置或匹配问题。Composer 只在加载 composer.json 时读取该字段，且不做容错校验：名字对不上就静默忽略。
-
scripts-descriptions写在scripts对象内部（比如当成子字段）→ 完全无效 - 脚本名用了别名（如通过
composer run test调用），但scripts-descriptions里写的是别名而非真实脚本名 → 不显示 - 项目依赖了其他包，而你在根
composer.json里写了scripts-descriptions，却期望它出现在 vendor 包的脚本列表中 → 不可能，它只作用于当前项目的scripts - 运行
composer list但没看到你的描述？先确认是否执行的是当前项目目录下的命令（不是全局或子目录）
它和 script aliases 的关系
Composer 5.0+ 支持 scripts 中用数组定义 alias（例如 "test": ["@test-ci", "@test-static"]），但 scripts-descriptions 只能描述“真实脚本名”，不能为 alias 单独加描述。alias 自身不会出现在 composer list 输出中，也不会触发对应描述。
- 如果你定义了
"test": ["@test-ci"]，那么只有test-ci这个键能被scripts-descriptions描述 -
composer run test仍会执行，但composer list里只显示test-ci及其描述，test不会出现 - 想让 alias 也有说明？只能靠 README 或团队约定，
scripts-descriptions不支持
composer.json 的缩进和逗号，比查文档更快。 
