specsfy-specialist-laravel-package-manager

Laravel 包管理器

适用场景

• 当任务收到一个面向 Laravel 应用的 GitHub 包仓库 URL 时使用。
• 当已安装的 Composer 包需要使用说明页，或 composer.json、composer.lock 与 docs/packages/ 不同步时，也使用此工具。
• 不要用于 npm 包、不使用 Laravel 的 PHP 项目，或在 Packagist 上发布库。

工作流

1. 确认项目根目录，并将 GitHub HTTPS URL 规范化为 github.com/<组织>/<仓库>。仅接受由小写字母、数字、点、下划线或连字符组成的路径段；拒绝无法识别为 GitHub 仓库的 URL。
2. 在推荐任何包或命令之前，先阅读本地说明、composer.json、composer.lock、 .specsfy/PACKAGES.md、docs/packages/README.md 和现有说明页。寻找新替代方案之前，先考虑已安装的包。
3. 在指定仓库中查阅 composer.json、README、配置文档、已发布版本和使用示例。分别记录来源声明的内容、本地项目显示的内容，以及仍未确认的内容。
4. 确定 Composer 名称、PHP 版本、Laravel 版本、附加要求、安装命令、配置文件、发布命令和测试方法。如果仓库未提供兼容的 Composer 包，请在更改项目之前停止，并说明缺失之处。如果该包未在 Packagist 上发布，请检查清单中的 repositories，并在添加 VCS 来源之前请求明确授权。
5. 在 composer.json、composer.lock、vendor/composer/ 和代码中查找该包。如果已安装，请复用，不要再次执行 composer require。
6. 如果尚未安装该包，且当前请求授权安装，请在项目根目录执行 composer require <vendor/nome>。只有当项目本身将该包视为开发依赖时，才使用 --dev。未经确认其用途和授权，不要执行从 README 复制的安装后命令。
7. 创建或更新 docs/packages/<vendor>-<nome>.md，包含 Composer 名称、lockfile 版本、GitHub URL、用途、安装、配置、项目中观察到的用法、测试和查阅的来源。保留受管理部分之外的人工作注释。
8. 创建或更新 docs/packages/README.md，作为项目声明的所有 Composer 包的索引，包含版本、简要用途和各说明页的链接。需要完整列表（包括传递依赖）时，指向 .specsfy/PACKAGES.md。

规范

• composer.lock 记录已安装版本；绝不能仅根据 GitHub 最新标签或清单中的版本约束推断版本。
• 说明页名称使用规范化后的 Composer 名称，将 / 替换为 -。版本变更时应继续更新同一说明页。
• 索引分别列出生产依赖和开发依赖，不将传递依赖描述为项目的选择。
• 如果本地代码中存在实际入口点，每份说明页都应注明应用实际使用的入口点，例如 provider、facade、middleware、command、migration、config 或类。
• 安装、发布和测试命令都应附上执行原因，以及需要更改的文件。
• 绝不要将密钥、.env 中的值、完整的包代码或大量第三方文档复制到 docs/packages/。

反模式

• 未阅读 composer.json 和 lockfile 就安装：这可能引入不兼容的版本，或重复安装已有依赖。
• 将任何 PHP 仓库都视为 Laravel 包：这会混淆通用库、应用和扩展，且未能识别 Composer 契约。
• 未确认影响和授权就执行 php artisan vendor:publish、migrations 或包脚本：这些命令可能更改文件、数据库或配置。
• 仅根据 README 创建通用条目：文档将无法说明该包在使用它的项目中如何体现。

验证

• 确认 URL、Composer 名称、版本和要求均可在一手资料或相应本地文件中找到。
• 执行 composer validate --strict，并在已安装该包时检查 composer show <vendor/nome>。
• 运行项目中已有的测试、formatter 和静态分析工具；不要仅为验证该包而引入新的 runner。
• 检查 docs/packages/README.md 是否列出 composer.json 中的每个直接依赖、每个链接是否指向已有条目，以及条目是否说明尚未确认用途的情况。
• 对照已安装的版本检查链接、命令、配置名称和示例。没有相应资料或测试作为依据时，不要声明兼容性、安全性或可用性。

相关技能

• $specsfy-specialist-laravel 指导如何在 Laravel 的 HTTP、Eloquent、队列、授权和测试中使用该包。
• $specsfy-specialist-technical-research 可在仓库未能解答疑问时，帮助比较文档、版本和一手资料。

请阅读 references/standards.md，了解条目规范、资料来源层级以及适用的 Composer 命令。