---
purpose: 跨云厂商证书 / CDN / LB API 命名风格差异说明
loaded_by: SKILL.md §4 授权与写 API 闸门按需引用
blocking: false
---

# 跨云厂商 API 命名风格差异说明

> ⚠️ **仅为命名风格示意**，不保证当前有效、不保证完整覆盖能力、不保证字段可套用。
> 本 Skill **不绑定任何特定云厂商**；Agent 在任何云上使用 API 都必须先跟用户确认并查阅该厂商当前官方文档。

---

## 1. 典型风格样本

不同云厂商的证书 / CDN / LB API 命名风格**差异巨大**，无法从一家推断另一家。
以下是几种典型风格样本：

- **AWS 风格**：服务前缀 + 动词 + 名词（如 `acm:ImportCertificate` / `elbv2:ModifyListener`）
- **阿里云风格**：服务前缀 + Describe/Upload/Set + 名词（如 `cas:UploadUserCertificate` / `slb:SetLoadBalancerHTTPSListenerAttribute`）
- **腾讯云风格**：服务前缀 + 动词 + 名词（如 `ssl:DescribeCertificates` / `clb:ModifyListener`）
- **Cloudflare 风格**：RESTful 路径 + HTTP 动词（如 `POST /zones/{id}/custom_certificates`）
- **华为云风格**：RESTful 路径，常带显式版本号（如 `POST /v3/scm/certificates`）
- **火山引擎风格**：混合命名（既有 `ImportCertificate` 也有 `CertificateGetInstanceList`，同一服务内风格不统一）

---

## 2. Agent 调用云 API 前的必做 3 步

1. **问用户用哪家云** —— 不预设、不推断、不按"常见场景"猜测
2. **查该厂商当前官方文档** —— 核对 API 名、入参结构、返回字段、权限要求、版本号
3. **把官方文档链接和关键字段回读给用户确认** —— 减少版本漂移 / 产品线差异带来的误调用

> 📌 厂商同一能力常存在多个 API（老接口 + 新接口 + 私有化版本），Agent 应优先选择官方**推荐版本**并显式告知用户。
> 📌 国密证书、私有 CA、HSM、专属云/政务云等特殊产品线各厂商接口差异更大，**必须向用户单独确认**，禁止套用主流公有云的 API。

---

## 3. 适合用只读 API 自动化的典型场景（减轻用户负担）

- **信息收集**：从云厂商拉取已签发证书清单、到期时间、绑定资源
- **资产盘点**：枚举 CDN 域名、LB 监听器、API Gateway 自定义域名的证书绑定关系
- **选型支撑**：读取用户所在公有云支持的 CA 品牌 / 证书类型清单与价格
- **探测**：对已知域名做 TLS 握手 + CT 日志反查，发现清单外的子域名
- **监控**：读取证书到期告警配置、最近一次 SSL Labs 评分
- **DNS 基础设施反推**：由 DNS 只读记录反推客户使用的 CDN / 源站云厂 / CA 偏好 / ACME 现状 / 邮件服务（详见 `dns-probing.md`）

---

## 4. 授权获取协议

- Agent 首次需要调用只读 API 时，必须**先说明**以下 4 项，获得用户确认后才调用：
  1. 要调用的具体 API 名称与云厂商
  2. 调用的目的（解决什么信息缺口）
  3. 需要用户提供的凭证类型（强调：只需只读 AK/SK 或子账号权限）
  4. 预计调用次数与可能产生的费用（如有）
- 凭证由用户通过环境变量或临时 token 提供，Agent **不得持久化凭证**到任何文件
- 如果用户拒绝授权，Agent 回退到 Phase 1 的"只读命令清单"模式，让用户本地执行
- 🔴 写 API 的授权**不能继承** 🟢 只读 API 的授权，必须单独征询（具体授权流程见 SKILL.md §4 闸门机制）

---

## 5. 硬边界

- 未经授权调用任何 API → 违反本协议，立即停止并道歉
- 在用户只授权了只读 API 时调用写 API → 严重违规
- 探测域名清单之外的目标 → 越权行为
- 在任一闸门未满足时代为执行写 API → 严重违规
- 对 Delete 类写操作代为执行 → 一律违规（无论授权与否）