README 必须包含安装、使用、配置、贡献四大区块，以用户真实搜索路径为准；首行需直击痛点，示例可复制粘贴，仅暴露稳定接口，显式声明版本兼容性与废弃提示。

Composer 包的 README 不是装饰品，它直接决定别人愿不愿意装你的包、能不能快速用起来、出错时敢不敢提 issue。写得模糊或缺失关键信息，composer require 成功后，用户卡在第一步——连怎么实例化类都找不到。

必须包含的 4 个区块：安装、使用、配置、贡献

这不是格式建议，而是用户真实搜索路径：how to install my-package → my-package example usage → my-package config options → my-package pull request。缺一个，就会触发大量重复咨询。

• 安装区块只写一行命令：composer require vendor/my-package；如果需要额外步骤（如发布配置），明确写出 php artisan vendor:publish --tag=my-package-config（Laravel 场景）或 cp vendor/vendor/my-package/config.php ./config/（原生 PHP）
• 使用区块以可复制粘贴的最小完整示例开头，比如调用 MyPackage\Client::make() 而不是 “初始化客户端” 这种描述
• 配置区块列出所有环境变量或配置文件键名，如 MY_PACKAGE_API_KEY、timeout，并标注是否必填、默认值、类型（string/int/bool）
• 贡献区块写清本地开发流程：如何安装依赖（composer install）、运行测试（vendor/bin/phpunit）、代码规范检查（vendor/bin/phpcs）

别把 README 当成 API 文档来写

用户第一次接触你的包，不是来学设计模式的。过度展开类继承关系、事件生命周期、内部 trait 用法，只会让真正想发请求的人翻到第三屏还找不到 $client->send() 的调用方式。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

• 只暴露稳定、公开、有文档保障的接口：如 MyPackage\Http\Client、MyPackage\Transformer::fromArray()
• 私有方法、内部 helper 类、未打 @api 标签的函数，一律不写进 README
• 如有复杂流程（如 OAuth 授权链），用带注释的代码块代替文字描述：

  // 1. 获取授权 URL
  $url = $auth->getAuthUrl();
  // 2. 用户跳转后回调，传 code
  $token = $auth->exchangeCodeForToken($_GET['code']);
  // 3. 使用 token 初始化 client
  $client = new Client($token);

版本兼容性必须显式声明，不能靠猜测

README 里写 “支持 PHP 7.4+” 是无效信息。用户真正需要的是：“PHP 8.2 下 MyPackage\Serializer::jsonEncode() 返回 string|false，而 PHP 8.0 返回 string”，或者 “Laravel 10 需要 v3.2.0+，因移除了 Illuminate\Support\Facades\Response”。

• 在顶部加一行兼容性横幅：Supports PHP ^8.0|^8.1|^8.2, Laravel ^9.0|^10.0, Symfony ^6.0
• 若某功能仅限特定版本，直接绑定到示例旁：

  // PHP 8.1+ only
  $result = match ($status) {
      200 => 'ok',
      default => throw new InvalidStatusException($status),
  };

• 废弃（deprecated）功能要在 README 中明确标出，并给出替代方案，例如：MyPackage\LegacyConnector is deprecated since v2.5.0 — use MyPackage\Http\Client instead.

最难写的其实是第一行——不是 “A package for doing X”，而是 “Use MyPackage\BatchProcessor to run 10k rows without memory overflow”。用户扫一眼就要知道：这东西能不能立刻解决他正在 debug 的那个问题。其他都是为这句话服务的细节。