composer.json 不支持注释，因 json 规范（rfc 8259）禁止注释，php json_decode() 遇 // 或 / / 直接报错；安全写说明应使用 composer.json.dist + .gitignore 方案。
Composer 安装时无法保留任何注释——这不是配置问题，是 JSON 规范的硬性限制。你写在 composer.json 里的 // 或 /* */ 会直接导致 JSON decode error: Syntax error，连解析都失败。
为什么 composer.json 里加不了注释？
因为 composer.json 是标准 JSON 文件，而 RFC 8259 明确规定 JSON 不支持注释。PHP 的 json_decode() 函数遇到 / 或 * 就报错，Composer 没有、也不会绕过这个底层限制。
常见错误现象：
- 运行
composer install或composer update时中断，提示Parse error: syntax error, unexpected '/' in /path/to/composer.json on line X - IDE 显示 JSON schema 校验失败，但你确认语法“看起来”没问题
开发模式下怎么安全地写说明文字？
用 composer.json.dist + .gitignore 组合，这是唯一不污染生产环境、不触发解析错误、且被广泛验证的方案。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
实操建议：
- 把带完整注释、分段说明、TODO 提示、甚至 Markdown 链接的文档全写进
composer.json.dist - 在
.gitignore里加上composer.json.dist，确保它不会进 Git 或部署包 - 需要生成正式配置时，手动复制内容到
composer.json（或用脚本清理注释后覆盖） - CI/CD 流程只读
composer.json，完全避开注释问题
别用 _comment 字段：它虽不报错，但会被写入 composer.lock、上传到 Git、出现在生产环境里，还可能被 CI 工具当作非法字段拒绝。
想边看源码边查上下文？别依赖 composer.json 注释
Composer 本身不提供源码阅读辅助。真正有效的做法是结合外部工具和约定：
- 把关键设计说明、分支用途、版本差异写进项目根目录的
README.md—— GitHub/GitLab/Packagist 都自动渲染，PHPStorm 也识别跳转 - 用
scripts字段封装命令，并在数组值里用自然语言写说明（如"post-install-cmd": ["echo \"? This installs dev tools and runs tests\""]） - 对 fork 或 dev 分支依赖，必须用 inline alias（如
"vendor/package": "dev-fix-encoding as 1.2.0"），否则 Composer 根本不会选中它——这比“注释”更重要
最常被忽略的一点：很多人花时间折腾注释格式，却没检查 composer.json 是否被 IDE 自动格式化加了空格或 BOM，这类隐藏字符同样会导致解析失败，且错误提示不明确。
