/cloud-api-recipe-authoring

name: cloud-api-recipe-authoring
description: "Author or revise a cloud-api-operations recipe (config/source/skills/cloud-api-operations/references/recipes/). Encodes why the long tail of control-plane capabilities is deliberately NOT wrapped as MCP/CLI tools, the API-first admission test for whether a capability deserves a recipe, the negative and positive lists, the fixed recipe structure, the writing rules distilled from writing-for-agents, the user-facing copy red lines, and the product regeneration/verification pipeline. Also routes contributors (and their agents) to the contribution flow and the pre-PR self-test protocol in references/contributing.md. Use when adding a recipe, judging whether a scenario belongs in the recipe set, updating the recipes index, re-checking existing recipes against the admission test, or onboarding someone who wants to submit one."
alwaysApply: false

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）

• 需要**串联多个 Action 或多个产品**（例：monitor 策略族 + postgres `DescribeDBInstances`）
• 有**非平凡前置**：CAM 授权升级、临时密钥、环境绑定、签名或加密
• 有**实测踩坑**：报错信息 → 正确做法，靠读文档推不出来
• 调用后有**回查 / 清理义务**：幂等查重、解绑、残留维度清理

反面 case（准入驳回长什么样）

**集成中心 UserKey 密钥对管理** —— 全文在内部归档 `specs/cloud-api-skill/pending-recipes/integration-userkey.md`（不进版本控制，外部读者看不到内容，按下文「驳回后归档页写三样」自行落笔）。

它当时**过了正向清单的两条**：有非平凡前置（password 字段加密）、有实测踩坑（脱离 SDK 会明文落库）。但三条硬门槛一条都不过：

| 硬门槛 | 实际 | | --- | --- | | 有公开云 API | 6 个 Action（`GetUserKeyList` / `CreateUserKey` / …）在公开概览 **0 命中** | | 语言无关可调用 | 唯一通路是 `@cloudbase/manager-node` 的封装；Python / Go / Java 用户没有对应入口 | | 写操作能独立完成 | password 的加密密钥由 SDK 内部从七彩石取（`QueryRainbowConfig`），公开面没有入口 → 裸调云 API 无法加密，写路径走不通 |

**要记住的是漏判机制，不是这条结论**：把「官方 SDK 文档里写全了、本地跑得通」当成了「能力在公开 API 契约内」。**SDK 文档公开 ≠ Action 公开**。

**写前自检**：动笔前拿目标 Action 名去公开概览 / 官方接口文档搜一次（入口见上文准入 §1）。0 命中就停手，不进公开集。

**驳回后归档页写三样**（照 `pending-recipes/` 那份抄）：① 为什么未通过，逐条对到上面三条门槛；② 解封条件——满足其一即可移回公开集；③ 显式禁止「复制回公开 skill」。

权限模型（维护者视角：这一步要不要预置掉）

使用者看到的是「点一下授权链接」；我们要判断的是**要不要让这一步消失**。三种处置：

| 处置 | 什么情况 | 怎么做 | | --- | --- | --- | | 预置进角色族 | 能力通用、高频、且在 TCB 产品语义内（TCR 拉镜像、CloudBase Run 访问 VPC/CVM 属这类） | 推产品给 `TCB_QcsRole` 挂预设策略，命名沿 `QcloudAccessForTCBRoleIn<X>` → 用户零操作 | | 让用户按需追加 | 长尾能力、跨产品，或预设策略粒度太粗（`QcloudMonitorFullAccess` 是全读写） | 给一键授权链接，写进 recipe 的 `前置权限`。**默认走这条** —— 把大权限挂在默认角色上，等于替所有用户扩大默认授权范围 | | 都不做 | 能力没有公开 API（准入驳回那一类） | 到此为止，不写 recipe 也不预置；当产品缺口反馈 |

判断顺序：先过准入（没有公开 API 就停），再看值不值得进角色族；两条都不过就只留一键授权链接。

**动笔预置前先做一次身份校验**：确认这条通路的凭据真的以该角色发起。`auth get_temp_credentials` 导出的是 Web / device 登录的**同一份**临时密钥（不是另起一次角色假定），所以只有用「权限收窄到刚好没这个 Action」的身份实测报出 `UnauthorizedOperation`，才能判定角色策略在这条通路上生效。判不出来就给一键授权链接、不预置。

一个已观察到的线索：账号级 device 登录的凭据能过 `cam:CreateRole`、`cdn:DescribeDomains`，而同一账号 `TCB_QcsRole` 的挂载策略里都没有这两条 —— 倾向说明它取的**不是**该角色。但这个结果用主账号登录也会得到，必须换窄权子账号复测才算数；没复测前，对外只写「按凭据身份判断」，不要对外断言 CLI / MCP 走角色。

**已落定的归属**（按能力族，不按产品）：

| 能力 | 处置 | 依据 | | --- | --- | --- | | 云开发自己的域名（静态托管、网关自定义域名的绑定 / 解绑 / 查任务） | 预置——已在角色族 | 走 `tcb:*` 与 `cdn:Tcb*`，属 TCB 产品语义内 | | 证书只读（列证书 / 详情 / 校验链） | 预置——已在角色族 | 绑自定义域名要在证书列表里挑一张，是必要读权限 | | 云监控告警族 | 预置——已在角色族 | 随基座策略下发 `monitor:*`，不单独挂 `QcloudMonitorFullAccess` | | 通用 CDN 加速域名（`AddCdnDomain` 等） | 让用户按需追加 | 跨产品长尾；`QcloudCDNFullAccess` 粒度太粗 | | DNS 解析（DNSPod） | 让用户按需追加 | 跨产品长尾：解析记录操作与云开发无产品语义绑定 | | 证书写（申请 / 续期 / 删除 / 部署） | 让用户按需追加 | 同上；`QcloudSSLFullAccess` 是全读写，粒度偏粗 |

角色挂载策略会随产品迭代变动，上面这张表可能过期 —— **以 `ListAttachedRolePolicies` + `GetPolicy` 读到的实际策略内容为准**，不要拿历史结论当事实。

用到的 service 必须在 MCP 白名单里

recipe 里出现的 service 要能在 `callCloudApi` 直接调通。白名单是 `mcp/src/tools/capi.ts` 的 `SERVICE_VERSIONS`（枚举 + 官方版本映射）。写 recipe 时若发现目标产品不在表里，**先补表再写 recipe**：单版本产品写 `service: ["YYYY-MM-DD"]`，多版本产品把官方在用版本都列进数组（缺省时调用方必须显式传 version）。版本号取自官方 SDK 目录 `tencentcloud/<service>/v<YYYYMMDD>`，不要凭记忆填。

改完 `SERVICE_VERSIONS` 要同步**两处**再跑产物链：使用者侧的完整索引 `config/source/skills/cloud-api-operations/references/service-versions.md`（按产品线分组的分组表），以及 `references/calling-methods.md` §1 的「最常用的几个」小表（只在核心产品变动时动这张）。

链接拼法、角色载体读法、策略覆盖范围见对外 skill 的 `config/source/skills/cloud-api-operations/references/calling-methods.md` §3 —— 维护者视角的内容**只写在本 skill**（对外 skill 只写