JSON标准不支持注释，因此composer.json中添加//或/ /会导致解析错误；可用_comment字段临时占位但非真注释；推荐使用composer.json.dist文件写注释并配合.gitignore排除。
Composer 读不到 // 或 /* */ 注释，不是 bug 是 JSON 规范
JSON 标准本身不支持注释，composer.json 是纯 JSON 文件，所以无论你写 // 这是注释 还是 /* 也没用 */，Composer 解析时都会直接报错：JSON decode error: Syntax error。这不是 Composer 的限制，是底层 json_decode() 的硬性要求——它只认 RFC 8259 定义的 JSON。
常见错误现象：加了注释后运行 composer install 或 composer update，直接中断并提示类似：
Parse error: syntax error, unexpected '/' in .../composer.json on line X
这时候别怀疑 Composer 版本或缓存，先删掉所有斜杠和星号注释。
用 _comment 字段临时占位，但仅限开发环境
Composer 不解析 _comment（下划线开头）这类字段，所以有人把它当注释用。它不会报错，也能被保留进文件，看起来像注释：
{
"_comment": "这个包只用于本地调试，CI 环境请勿启用",
"require-dev": {
"phpunit/phpunit": "^10.5"
}
}但要注意：
-
_comment会被写入 lock 文件、上传到 Git、同步到生产环境——它不是真注释，只是个没意义的键 - 多个
_comment字段会覆盖（JSON 键唯一），不能重复声明 - 某些 IDE 或校验工具可能警告“未知字段”，CI 流程若开启严格 schema 校验会失败
真正安全的注释方案：用 composer.json.dist + .gitignore
把说明文字写在同目录下的 composer.json.dist 文件里——它不是 Composer 的配置文件，只是个普通文本，可自由加注释、分段、写链接。然后靠 .gitignore 确保它不进生产部署：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
# .gitignore composer.json.dist
实际工作流是：
- 日常编辑
composer.json.dist（含完整注释、示例、TODO） - 需要提交时，手动或用脚本生成干净的
composer.json（仅保留合法 JSON 结构） - CI/CD 构建阶段只读
composer.json，完全绕过注释问题
这个做法不依赖 Composer 行为，兼容所有版本，也不会污染 lock 文件或引发解析歧义。
别碰 $schema 或自定义 parser，成本远超收益
有人想用 JSON Schema 的 description 字段，或者写个 pre-commit 脚本把注释转成字段。这些方案的问题很实在：
-
description只能挂在某个值下面，无法跨层级注释整个 section - 自定义 parser 意味着每次改
composer.json都要多一道转换，团队协作时极易漏步骤 - 一旦某次忘记转换，
composer.lock就会基于带注释的非法 JSON 生成，后续所有环境都崩
JSON 不支持注释这件事，本质是格式契约。接受它，比绕它走更省事。
最常被忽略的一点：很多人以为 composer.json 是“给 Composer 看的配置”，其实它更是“给人类维护者看的契约文档”。所以重点不在怎么塞进注释，而在怎么让契约本身足够自解释——比如用清晰的包名、合理的 require-dev 分组、语义化的脚本命名，比任何 _comment 都管用。
