🏗️ 双 SDK 架构
Composer Skills 不是一个 SDK，而是两个装在同一个模块里。它们解决不同的问题、走不同的底层路径、有不同的运行时要求。理解它们的边界，是用好这个项目的前提。
🌐 vs 🛠️ 两个 SDK 概览
| 🌐 Packagist API SDK | 🛠️ Composer CLI SDK | |
|---|---|---|
| 包路径 | pkg/client、pkg/repository | pkg/composer |
| 底层机制 | HTTP 调用 Packagist REST API | 执行本地 composer 二进制（os/exec） |
| 需要 PHP？ | ❌ 不需要（纯 Go） | ✅ 需要（PHP 7.4+） |
| 需要 Composer？ | ❌ 不需要 | ✅ 需要（Composer 2.0+，可自动安装） |
| 数据来源 | Packagist 服务器（远程） | 本地 PHP 项目（composer.json/composer.lock） |
| 方法数 | 20 | 234 |
| 典型用途 | 搜索包、看统计、拉安全公告 | 安装/更新依赖、本地审计、管理项目 |
🌐 Packagist API SDK
包路径：github.com/scagogogo/composer-skills/pkg/client
它是一组类型化的 HTTP 客户端，直接和 Packagist 服务器通信。返回值是 Go 结构体，不碰本地 PHP 环境。
go
c := client.NewComposerClient(30 * time.Second)
// 远程搜索
results, _ := c.SearchPackages("logging", 10, 1)
// 远程包详情
pkg, _ := c.GetPackage("monolog/monolog")
// 远程安全公告（全仓库维度）
advisories, _ := c.GetSecurityAdvisories()
// 全站统计
stats, _ := c.GetStatistics()pkg/repository 在 client 之上提供更高层的仓库操作封装，适合做包镜像、索引下载等场景。
何时选它
- 你的程序运行在没有 PHP 的环境（纯 Go 服务、CI runner、Lambda）。
- 你需要的是 Packagist 全局数据，而不是某个本地项目的状态。
- 你只查询、不修改（搜索、统计、公告）。
🛠️ Composer CLI SDK
包路径：github.com/scagogogo/composer-skills/pkg/composer
它通过 os/exec 调用本机 composer 可执行文件，封装了全部标准 Composer 子命令（234 个方法，20 个分类）。所有操作都针对一个具体的本地 PHP 项目（由 SetWorkingDir 指定）。
go
comp, _ := composer.New(composer.DefaultOptions())
comp.SetWorkingDir("/path/to/php/project")
// 本地依赖管理
comp.Install(false, true)
comp.RequirePackage("monolog/monolog", "^3.0", false)
// 本地安全审计（针对该项目已安装的依赖）
result, _ := comp.AuditWithJSON()
// 本地包检查
tree, _ := comp.ShowDependencyTree("symfony/console")何时选它
- 你要对一个真实 PHP 项目做操作（安装、更新、审计、脚本）。
- 你需要本地
composer.json/composer.lock的结构化信息。 - 你要做 DevOps 自动化：检测环境、装 Composer、跑 install、验证 schema。
🤔 何时用哪个
一个简单的判断标准：数据来自哪里？
- 数据来自 Packagist 服务器（"世界上有哪些 logging 包"、"monolog 有没有新漏洞公告"）→ 用 🌐 Packagist API SDK。
- 数据来自 本地项目（"这个项目装了哪些依赖"、"这个项目有漏洞吗"、"装一下依赖"）→ 用 🛠️ Composer CLI SDK。
两者经常配合使用。例如一个安全扫描器：
- 用 🌐
client.GetSecurityAdvisories()拉取全量远程公告。 - 用 🛠️
comp.GetDirectDependencyNames()拿到本地项目依赖列表。 - 在 Go 里做交叉比对，输出"本项目受影响的具体漏洞"。
📊 能力对比速查
| 能力 | 🌐 Packagist API | 🛠️ Composer CLI |
|---|---|---|
| 搜索包 | ✅ SearchPackages | ✅ Search |
| 包详情 | ✅ GetPackage | ✅ ShowPackage |
| 安全公告 | ✅ GetSecurityAdvisories（全仓库） | ✅ AuditWithJSON（仅本项目） |
| 统计信息 | ✅ GetStatistics | ❌ |
| 安装/更新依赖 | ❌ | ✅ Install/Update |
| 依赖树 / why | ❌ | ✅ ShowDependencyTree/WhyPackage |
| 过期包 | ❌ | ✅ OutdatedPackages |
| 创建项目 / 脚本 | ❌ | ✅ CreateProject/RunScript |
| composer.json 读写 | ❌ | ✅ ReadComposerJSON/WriteComposerJSON |
安全公告的差异
GetSecurityAdvisories（Packagist API）返回的是全仓库级别的公告流；AuditWithJSON（Composer CLI）只审计当前项目已安装依赖的漏洞。两者互补，不可互相替代。
🧭 下一步
- 🌐 Packagist API SDK 概览 —— 20 个 API 方法详解。
- 🛠️ Composer CLI SDK 概览 —— 234 个方法按分类索引。
- 🔧 自动安装机制 —— Composer CLI SDK 如何在缺失时自动补齐 Composer。
- 🧪 类型化返回值 —— 两套 SDK 共同的结构化返回设计。