cloud-api-recipe-authoring

1# Cloud API Recipe Authoring
2 
3目标：让**「AI 可以 100% 操作云开发」**可验证 —— 每个高频管控面场景都有一篇能照着跑通的 recipe，且每篇都建立在**公开 API** 之上。
4 
5## When to use
6 
7- 新增一篇 recipe，或修改现有一篇
8- 判断某个能力**该不该**进 recipe 集（准入）
9- 更新 `config/source/skills/cloud-api-operations/references/recipes/README.md` 的目录表与状态列
10- 复核已有 recipe 是否仍满足准入（Action 是否已公开、是否已被专用 MCP 工具覆盖）
11- 有人（或他的 Agent）要提交一篇 recipe —— 把 `./references/contributing.md` 给他
12 
13## 为什么不全部封装进 MCP / CLI（分工原则）
14 
15产品排期里「对外开放 API」通常不优先，于是有一个固定落差：**控制台上了功能，AI 却操作不了**。因果链是单向的 —— 没有公开 API，CLI / MCP 就无从封装，AI 只能用鼠标。
16 
17补齐落差有两条路，我们不走「全都封装」那条：
18 
19| 做法 | 代价 |
20| --- | --- |
21| 把能力都补成 API、再全部封装成工具 | 工具面持续膨胀：模型选错工具的概率上升，工具描述吃掉上下文预算，每个工具都要跟 API 变更一起维护 |
22| **只封装核心，长尾走 recipe** | 要多维护一份文档，但工具面稳定，长尾能力照样能被 AI 操作 |
23 
24**核心能力已经封装过了**（`query*` / `manage*` 工具家族 + CLI），剩下的大量接口**不需要**封装。一个能力该去哪：
25 
26| 能力形态 | 归属 |
27| --- | --- |
28| 有公开 API + 高频核心 | 已在 MCP / CLI 工具里 —— 直接用，不要另写 recipe |
29| 有公开 API + 长尾（串联多 Action、有非平凡前置、有踩坑或回查义务） | **写 recipe**（本 skill） |
30| 有公开 API + 单接口、读文档即可调 | 既不封装也不写 recipe —— agent 现场查索引 |
31| **没有公开 API**（只在控制台可见） | 谁也封装不了 —— **产品缺口**，推产品先开放 API；这里也没有 recipe 可写 |
32 
33最后一行是硬约束：**没有公开 API，能力对 AI 的可用性就是 0**，这不是「我们封装得不够」的问题。
34 
35## 准入：API first（硬门槛，先过这一关再动笔）
36 
37三条必须同时满足：
38 
391. **有公开云 API**：目标 Action 已列入公开 API 概览 / 接口文档（`https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/api-reference.md` 或产品官方文档）。
402. **语言无关可调用**：云 API 直调 / 官方 SDK / CLI / MCP 任一条通路都行 —— 但必须是**公开 API 的封装**，不能反过来「只有某个语言的 SDK 封装、没有公开 Action」。
413. **写操作能由使用者独立完成**：含签名、必要的前置查询与加解密。若关键步骤依赖客户端拿不到的内部配置，就不合格。
42 
43不满足时的处理：
44…