私有 Composer 包文档是协作与长期维护的前提。需包含精准标题、完整安装命令、最简示例、场景化功能说明、已知限制及避坑提示，确保新成员5分钟内跑通示例、查到配置、避开雷区。
私有 Composer 包的文档不是可选项，而是协作和长期维护的前提。清晰的 README 能大幅降低团队成员接入成本，减少重复提问，也方便未来你自己回看时快速上手。
标题与一句话定位
开头用项目名 + 一句话说明“它解决什么问题”，避免模糊描述。比如：
- ❌ “一个工具包” → ✅ “提供 Laravel 应用中统一处理第三方 API 错误响应的中间件和异常映射器”
- ❌ “增强开发体验” → ✅ “在本地开发环境自动注入调试头信息并记录请求上下文到日志”
让读者 3 秒内判断：这是否是我需要的包？
安装与基础用法（贴实际命令）
把 composer require 命令写全，包括私有源配置提示。不要假设读者知道如何配 private repo：
- 明确写出是否需先在
composer.json的repositories中添加你的私有 Packagist 或 Git URL - 给出完整安装命令，例如：
composer require your-org/your-package:^2.1 - 紧接一个最简可用示例：Laravel 用户怎么注册服务提供者？Symfony 用户怎么导入配置？有没有必须的环境变量？
避免只写“参见 config 文件”——直接贴出关键配置片段，哪怕只有两行。
核心功能分点说明（带场景）
不罗列方法名，而是用“当你想……时，可以……”结构说明价值：
- 当你想统一格式化所有 API 返回的错误码时，调用
ErrorResponse::wrap($exception)，它会自动匹配预设规则并补全 trace_id - 当你需要跳过某次 HTTP 请求的重试逻辑时，在请求选项中传入
'skip_retry' => true - 当你升级到 v3 时，
Client::send()不再返回原始响应对象，改用ResponseData封装类，请检查对getStatusCode()的直接调用
每个点附上一行代码示例，不追求完整流程，只展示接口意图。
常见问题与限制（提前避坑）
把内部已知的边界情况写清楚，比等别人提 issue 更高效：
- 不支持 PHP 8.0 以下版本（因使用了联合类型）
- 缓存驱动默认使用 Laravel 的
cache.default，如需隔离请发布配置并修改cache.store - 测试时若启用
MockHttpClient，需确保HttpServiceProvider已加载，否则会 fallback 到真实客户端
用“⚠️”或“注意：”开头的小段落，不加修饰，直说影响和应对方式。
基本上就这些。私有包的文档不用追求完美，但要确保新同事 clone 后 5 分钟内能跑通第一个例子、查到关键配置、避开已知雷区。越早写，越少返工。
