通过添加"scripts-descriptions"字段或使用插件如DealerDirect Scripts Plugin，在composer.json中为自定义脚本提供描述，提升团队协作效率。

在 composer.json 中定义脚本时，虽然 Composer 本身不直接支持为自定义脚本添加描述，但你可以通过一些约定和工具来让你的 scripts 更清晰易懂。以下是一些实用的方法。

使用注释说明脚本用途

虽然 JSON 不支持注释，但你可以在键名设计上体现意图，或在项目文档中补充说明。更推荐的做法是使用一个特殊的键（如 "scripts-descriptions"）来手动维护脚本说明：

{
    "scripts": {
        "build": "@php bin/build.php",
        "test": "@php vendor/bin/phpunit",
        "lint": "@php vendor/bin/phpcs src/"
    },
    "scripts-descriptions": {
        "build": "生成静态资源或编译代码",
        "test":  "运行单元测试",
        "lint": "检查代码风格是否符合规范"
    }
}

这样团队成员查看 composer.json 时，能快速理解每个命令的作用。

利用 Composer 插件显示描述

安装 composer-scripts-plugin 或类似工具，可以让 composer list 显示脚本描述。例如使用 DealerDirect Scripts Plugin：

composer require --dev dealerdirect/scripts-plugin

然后在 composer.json 中写入带描述的脚本：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

{
    "extra": {
        "scripts-dev": {
            "test": {
                "description": "运行项目测试用例",
                "script": "php vendor/bin/phpunit"
            },
            "coverage": {
                "description": "生成测试覆盖率报告",
                "script": "php vendor/bin/phpunit --coverage-html=reports/"
            }
        }
    }
}

安装插件后，运行 composer list 就能看到这些描述信息。

编写 README 或帮助脚本

在项目根目录添加一个帮助命令，比如：

"scripts": {
    "help": "echo '可用命令：' && echo '  composer build  - 构建生产资源' && echo '  composer test   - 运行测试' && echo '  composer lint   - 检查代码风格'"
}

用户执行 composer help 即可看到清晰说明。这种方式简单有效，适合小型项目。

基本上就这些。通过合理组织键名、添加辅助字段或借助插件，就能显著提升脚本的可读性。关键是让团队成员无需翻文档也能明白每条命令是做什么的。