scripts-descriptions 字段非 composer 原生支持，解析器直接忽略；唯一有效方式是在 scripts 条目中同级配置 description 字符串，仅 composer run --list 显示。
composer list 不显示 scripts-descriptions 字段
直接写 "scripts-descriptions" 到 composer.json 里，对 composer list 或 composer run --list 完全无效。这个字段不是 Composer 原生支持的配置项，解析器会彻底忽略它——既不报错，也不渲染，更不会出现在任何命令输出中。
常见错误现象：改完 composer.json 后运行 composer list，发现描述没出现，还以为是格式或版本问题。其实根本原因是 Composer 根本不读这个键。
- Composer 1.x 和 2.x（包括最新 2.9.6）均未在官方 schema 中定义
scripts-descriptions - 即使拼写完全正确、key 与
scripts中命令名一致，也纯属“静态注释”，仅靠人眼阅读 - 某些 IDE 或第三方 CLI 工具（如旧版
hirak/prestissimo）可能读取该字段并展示，但这属于插件行为，非 Composer 本身能力
真正能在命令行显示描述的唯一方式：description 字段 + composer run --list
从 Composer 2.5 开始，scripts 下每个脚本条目可配 description 字符串，且仅在 composer run --list 中生效——注意，composer list 仍不显示。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
示例写法必须是对象形式：
{
"scripts": {
"test": {
"script": "@php vendor/bin/phpunit",
"description": "Run unit tests with coverage"
},
"cs-fix": {
"script": "@php vendor/bin/php-cs-fixer fix",
"description": "Auto-fix coding standards violations"
}
}
}
-
description必须与script同级，且值只能是字符串（不支持数组、多行或 Markdown） - 仅
composer run --list输出时会显示该描述；composer list只列出内置命令（如install、update），不包含自定义脚本 - 低版本 Composer（description 字段，建议用
composer --version确认
想让 composer list 也显示说明？只能靠命名规范或封装脚本
composer list 的输出逻辑固定，只展示命令名（即 scripts 的 key），无法注入额外文本。想让它“看起来有说明”，只有两种务实做法：
- 用冒号分层命名：
"test:unit"、"build:prod"、"dev:clear-cache"——composer list原样输出，语义清晰，无需额外字段 - 加一条
"help:scripts"脚本，指向一个 PHP 文件，手动解析composer.json并格式化输出带描述的列表（可读extra.scripts-descriptions或硬编码） - 避免在脚本值里塞
# 注释：虽然某些 Composer 版本（≥2.2）能宽松解析行首#并显示在composer list，但行为不稳定、不可靠，且 JSON 标准本身不支持注释，容易被编辑器或 CI 工具误删
scripts-descriptions 字段的实际价值仅限于人工可读性
如果你坚持用 scripts-descriptions，它唯一可靠的作用是：让团队成员 cat composer.json 或在 IDE 里滚动查看时，快速理解每个脚本用途。它不参与执行、不触发校验、不被任何 Composer 命令消费。
- 字段位置必须与
scripts同级，且 key 必须完全一致（大小写、连字符、下划线都不能错） - CI/CD 流程中若依赖该字段做检查（如用
composer-unused --with-scripts-descriptions），需确认工具版本 ≥2.5 且明确支持该约定 - 最易被忽略的一点：它和
extra下任意自定义键一样，只是 JSON 的“装饰”，删掉不影响任何功能，但一旦拼错（比如写成script-descriptions），就彻底失去文档价值
