开源库的配置说明应通过composer.json的description、scripts、keywords、type字段与readme.md协同实现：description须简洁准确作搜索入口，scripts封装可执行命令，keywords和type影响发现率，readme.md才是用户首看的完整配置文档。
开源库的“配置说明”不是写在 composer.json 里的文档字段，而是靠结构、约定和少量关键字段协同实现的——写错地方，用户根本看不到；写对了，连 README 都不用点开就能上手。
description 字段不是安装指南，是搜索入口
它只出现在 Packagist 搜索结果和 composer show 输出里，长度被截断到约 80 字，且不渲染链接或 Markdown。填安装命令、引用文档地址、堆砌形容词，等于主动放弃被发现的机会。
- ✅ 正确写法：
"description": "PSR-14 event dispatcher with lazy listener resolution"（主语是包本身，动词+名词组合，无空格缩写歧义） - ❌ 错误写法：
"description": "Install with composer require vendor/name. See docs at https://..."（Packagist 不解析链接，也不显示完整字符串） - ⚠️ 常见坑：改完
composer.json后 Packagist 页面没更新——不是缓存问题，是没触发同步（GitHub push 后需 webhook 或手动 fetch）
scripts 是唯一能执行的“配置说明载体”
scripts 字段是 composer.json 中唯一会被 composer run-script 实际调用的部分，适合封装带上下文的命令，比如初始化配置、生成默认文件、检查环境依赖。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 用数组形式支持多步操作：
"post-install-cmd": ["@php bin/init-config.php", "chmod +x bin/run.sh"] - PHP 回调必须是
public static方法，且类已通过autoload注册，否则报Class not found而非脚本错误 - 别在
post-install-cmd里放 autoload 相关逻辑——post-autoload-dump更精准，且composer require也会触发它
README.md 才是真正的配置说明书
Composer 不读 README，但 GitHub、GitLab、IDE、Packagist 全都自动渲染它。用户第一眼看到的安装/配置步骤，99% 来自这里。所有“配置说明”应集中在此，而非分散在 composer.json 的任意字段中。
- 根目录
README.md必须包含：安装命令（composer require vendor/name）、最小 PHP 版本、必需扩展、基础配置示例（如 config/*.php 文件结构）、环境变量说明 - 不要把
README.md第一行复制进description——摘要 ≠ 文档，重复反而稀释信息密度 - 如果包需要发布后配置（如 Laravel Service Provider），在 README 里明确写清
config/app.php加哪行、php artisan vendor:publish是否必要
keywords 和 type 影响用户能否找到你
这两个字段不参与运行，但决定 Packagist 搜索排序和分类。填错 = 主动隐身。
-
keywords填 3–5 个真实搜索词，比如["event-dispatcher", "psr-14", "lazy-loading"]；避免["php", "library"]这类零区分度词 -
type必须准确："library"（默认，可被其他包 require）、"project"（独立应用，不应被 require）、"metapackage"（仅触发依赖安装）；填错会导致 Packagist 分类异常或 CI 构建失败 - 含短横线的 keyword（如
"psr-14"）必须加双引号，否则 JSON 解析失败，整个composer.json无效
最易被忽略的一点：所有配置类说明（包括 scripts 封装的命令）都依赖 autoload 正确生效。改完 psr-4 映射不跑 composer dump-autoload，脚本里的类就永远加载不到——而 Composer 从不提示你漏了这步。
