Cloud API Recipe Authoring

目标：让**「AI 可以 100% 操作云开发」可验证, , 每个高频管控面场景都有一篇能照着跑通的 recipe，且每篇都建立在公开 API** 之上。

When to use

• 新增一篇 recipe，或修改现有一篇
• 判断某个能力该不该进 recipe 集（准入）
• 更新 config/source/skills/cloud-api-operations/references/recipes/README.md 的目录表与状态列
• 复核已有 recipe 是否仍满足准入（Action 是否已公开、是否已被专用 MCP 工具覆盖）
• 有人（或他的 Agent）要提交一篇 recipe, , 把 ./references/contributing.md 给他

为什么不全部封装进 MCP / CLI（分工原则）

产品排期里「对外开放 API」通常不优先，于是有一个固定落差：控制台上了功能，AI 却操作不了。因果链是单向的, , 没有公开 API，CLI / MCP 就无从封装，AI 只能用鼠标。

补齐落差有两条路，我们不走「全都封装」那条：

做法	代价
把能力都补成 API、再全部封装成工具	工具面持续膨胀：模型选错工具的概率上升，工具描述吃掉上下文预算，每个工具都要跟 API 变更一起维护
只封装核心，长尾走 recipe	要多维护一份文档，但工具面稳定，长尾能力照样能被 AI 操作

核心能力已经封装过了（query* / manage* 工具家族 + CLI），剩下的大量接口不需要封装。一个能力该去哪：

能力形态	归属
有公开 API + 高频核心	已在 MCP / CLI 工具里, , 直接用，不要另写 recipe
有公开 API + 长尾（串联多 Action、有非平凡前置、有踩坑或回查义务）	写 recipe（本 skill）
有公开 API + 单接口、读文档即可调	既不封装也不写 recipe, , agent 现场查索引
没有公开 API（只在控制台可见）	谁也封装不了, , 产品缺口，推产品先开放 API；这里也没有 recipe 可写

最后一行是硬约束：没有公开 API，能力对 AI 的可用性就是 0，这不是「我们封装得不够」的问题。

准入：API first（硬门槛，先过这一关再动笔）

三条必须同时满足：

1. 有公开云 API：目标 Action 已列入公开 API 概览 / 接口文档（https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/api-reference.md 或产品官方文档）。
2. 语言无关可调用：云 API 直调 / 官方 SDK / CLI / MCP 任一条通路都行, , 但必须是公开 API 的封装，不能反过来「只有某个语言的 SDK 封装、没有公开 Action」。
3. 写操作能由使用者独立完成：含签名、必要的前置查询与加解密。若关键步骤依赖客户端拿不到的内部配置，就不合格。

不满足时的处理：

• 不要写进 config/source/skills/（那是对外发布面）
• 同时当产品缺口反馈：请官方把这些 Action 列入公开概览，或给出语言无关的调用路径
• 归档：维护者放 specs/cloud-api-skill/pending-recipes/（内部目录，不进版本控制），正文顶部写清「为什么未通过 + 解封条件」；外部贡献者不提 PR，按 ./references/contributing.md 开 Issue 说明

踩过的实例见下文「反面 case」, , 驳回后不进公开集，也不要把归档内容抄回来。

负向清单（不该写 recipe）

• 读公开 API 概览 + 单个接口文档就能直接调的（单个 Action、参数可查、无需串联）→ 让 agent 走 SKILL.md §1 的发现流程现场查
• 已有专用 MCP 工具覆盖的（query* / manage* 家族）→ 路由到工具，不写文档
• 纯参数含义 / 概念说明 → 属于官方文档，路由过去
• 只对某个 SDK 语言成立的用法（除该 SDK 外没有语言无关通路）

正向清单（必须写 recipe）