alibabacloud-cms-manage：对云监控 2.0 的各个 APP 进行全生命周期管理，包括接入中心、应用监控、前端监控、Prometheus 服务、云拨测、告警中心、事件中心等。

CMS CLI — aliyun cms2

前置检查

每会话一次：仅在对话中首次调用本 Skill 时执行此前置检查。如果同一会话中早些时候所有检查已通过，直接跳到相关模块。

1. 检查 aliyun 是否存在 —— which aliyun（macOS/Linux）或 where aliyun（Windows）。

• 未找到 → 请用户先安装 aliyun CLI：<https://help.aliyun.com/document_detail/121541.html>。停止并等待。

1. 检查 CLI 版本 —— 运行 aliyun version。最低要求：3.3.15（见 frontmatter 中的 compatibility）。

> ⚠️ 按整数比较版本段（semver）：3.3.4 < 3.3.15，因为 4 < 15。
> Shell 验证：printf '%s\n' "3.3.15" "$(aliyun version)" | sort -V | head -1
> 如果输出等于当前版本，则要求未满足。

• 版本 OK → 进入步骤 3。
• 版本过旧或无法识别 →

1. 运行 aliyun upgrade --help 测试 upgrade 子命令是否存在。

• 可用 → 运行 aliyun upgrade -y 自动更新到最新版本，然后重新检查 aliyun version。

1. 如果 upgrade 不可用 → 请用户按官方指南手动升级：<https://help.aliyun.com/zh/cli/update-cli>。等待用户确认升级完成，然后重新检查 aliyun version。
2. 如果升级成功 → 进入步骤 3。
3. 如果升级失败 → 请用户手动升级：<https://help.aliyun.com/zh/cli/update-cli>。停止并退出。

1. 检查 cms2 插件 —— 运行 aliyun cms2 --help。

• 帮助输出 OK → 继续到凭证。
• unknown command / 缺失 → 立即停止，输出下方错误报告（附加 CLI 版本、操作系统和错误消息），并不再做任何 CLI 调用。

凭证

aliyun cms2 复用 aliyun CLI 凭证系统（aliyun configure）。

用 --profile <name> 切换 profile。

可观测性

加载本 Skill 时，每会话生成一次随机 session ID（32 字符小写十六进制字符串）……

对每条 aliyun cms2 命令，追加：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cms-manage/{session-id}"

本地工具命令（如 version、configure、plugin、--help）不支持该标志，已排除。

全局约定

硬性约束：严格禁止回退到 aliyun cms、其他 API 版本或任何变通方案。

会话中首次使用某子命令前，运行 aliyun cms2 <command> [subcommand] --help 获取完整标志列表和示例。一旦当前会话中已读取同一子命令的帮助且命令形态未变，复用该知识而非重复帮助调用。具名子命令的 --help / --show-schema / --show-example-body 是该命令标志、body 信封、响应字段和环境行为的权威——不要在其他 skill 文件中搜索这些字段的副本。

• 优先 -o text（默认）以减少 list/get 的 token 消耗；仅当输出是逐字段解析而非阅读时才用 -o json。
• Addon-release values：按 Addon Values Defaults 中规定，将每个字段的 fieldPath 展开为嵌套 JSON。不要把点分 fieldPath 写成一个字面键。如何选择 --env-type、子字段在 create 与 update 上的位置，以及何时子集是（或不是）有效 body，见该章节。
• 变更和详情命令需要 region 参数：除非模块特定规则另有规定，所有 create、update、delete 和单资源 get/detail 命令都必须包含 --region 参数，以便请求路由到正确的后端 OpenAPI 端点。在这些命令上省略 --region 可能导致路由失败或对意外地域操作，且错误可能完全指向别的东西——integration policy create 返回 status 400: The workspace can not be created，即使 workspace 存在且 body 有效。这不适用于有意跨多地域的 list/查询命令（例如 entity query --source CloudResource 全地域查询）。要求该标志不代表可以自行选择其值——按 Region Confirmation Gate 解析它。
• 一个选择，一个问题：每个枚举选择（地域、workspace、policy、addon、scope mode、tag match mode，及任何其他互斥参数）作为一个问题提出，携带其全部选项。绝不把它们拆到多个问题或 （续）... 延续中，也绝不丢掉放不下的——拆分会把一个选择变成两个可能冲突或未完成的答案，截断列表会完全隐藏有效选项。当结构化输入表单无法渲染每个选项时，以纯文本提问，并在问题正文中列出每个选项及其说明。互斥选择保持单选；只有真正多值的（多个地域）才多选。一个提示可携带多个不同选择，各为独立问题。将任何推荐值直接放在选项标签中（例如 (Recommended)）；推荐仅供参考，除非另一规则允许默认或用户确认，否则不允许云端写入。
• 写入和高影响创建需要人工确认：在任何创建或改变云端状态的命令（create、update、delete、patch、start、stop 等）之前，展示简洁的确认摘要和确切命令，询问用户是否确认执行，并等待明确肯定答复。摘要必须包含操作、目标资源标识符、预期影响，以及适用时的显著风险或不可逆影响。不要求确切短语或长确认文本；清晰肯定答复如"yes"、"confirm"、"proceed"或"确认"即足够批准。仅对 dry-run、仅预览或无云端影响的读等价创建跳过确认；不确定时，要求确认。
• 不确定的参数必须由用户明确回答：对于任何未显式提供或无法可靠确定的参数值（例如 region/regionId、workspace、policy、resourceGroup、tag、资源范围、addon/addonName、资源类型、云产品 / 服务名、接入配置选项等），在继续前请用户明确回答。绝不臆造、猜测、从默认 / 历史推断，或任意选一个值。模块特定参考可能定义窄例外——对 integration 模块，它们列在 references/integration-common.md。更改现有 addon release 的设置是不可排练的写入：遵循 Addon Release Config Update。
• 发现查询不是答案：读命令（workspace list、entity query、policy list、sts get-caller-identity 等）只构建你呈现的候选集，其输出绝不成为用户的答案——不是当它返回单个候选时，不是当命名约定使值可推导时，也不是当会话早些时候用过它时。"可靠确定"意味着用户自己的话或他们点名的资源钉住了该值，而非查询恰好无歧义。
• 名称到 ID 查找必须精确匹配：按名称查找地域 ID、workspace ID、接入策略 ID、资源组 ID、资源类型值或云产品 / 服务名 / 代码时，如果查询结果中未找到精确匹配，不要静默选一个任意值替代。而是向用户报告不匹配并请他们确认或提供正确值。

地域确认门禁（硬性要求）

适用于每个模块和每条接受 --region 或 region/regionId body 字段的命令。先确定地域，再确定 workspace，因为 workspace 验证是地域范围的。

list/query 命令仅在模块规则说该调用是全地域时省略 --region。省略标志不是全地域：CLI 会提供 profile 默认值。变更和详情命令必须按 Region parameter required 携带它。

该值只有三个合法来源：

1. 用户在当前请求中说明——不是同一会话早些时候不相关的一轮。
2. 用户从你呈现的候选列表中挑选，且你在运行下一条命令前等待了该答案。
3. 主机将其作为运行时上下文注入（控制台会话的当前地域）。使用前说明你在操作哪个地域。

其他任何情况都是违规，包括：CLI profile / aliyun configure / ALIYUN_REGION 默认值，或省略必需的 --region；文档和示例中的 cn-hangzhou，或仅在叙述中提到的地域；拆分 default-cms-{userId}-{regionId}（或任何 workspace 名）；传 controlRegionId。

模块可以将 --region 绑定到用户已确认的资源的 regionId（已命名集群、已通过此门禁的 workspace、实例）。那仍是来源 1 或 2。模块参考不放松这一点。

如果来源 1 和 2 都缺失，按 One choice, one question 将地域作为选择呈现并停止。用 aliyun cms2 meta regions 收集候选并提供每个 regionId（绝不用 showName 或 controlRegionId）；仅消费其输出是错误的。来源 3 存在时仅为推荐选项——它路由调用，不决定范围。接入地域范围由 Resource Scope Selection Gate 收集；不要在此再问第二个地域问题。

controlRegionId 是控制面地域，对专用 / 独占位置可能不同——绝不将其作为 --region 传入。

Workspace 确认门禁（硬性要求）

适用于每个模块和每条接受 --workspace 或 workspace body 字段的命令。该值只有三个合法来源：

1. 用户在当前对话中说明。通过精确 workspaceName 匹配验证它存在于目标地域；无精确匹配 → 报告并询问，绝不替代近似匹配。
2. 用户从你呈现的候选列表中挑选，且你在运行下一条命令前等待了该答案。
3. 环境将其作为运行时上下文提供（例如本 Skill 运行所在的控制台会话）且其地域与目标地域匹配。使用前说明你在操作哪个 workspace。

其他任何情况都是违规：采用 aliyun cms2 workspace list 返回的唯一行、因看起来像账号默认而选 default-cms-{userId}-{regionId} 条目、用 aliyun sts get-caller-identity 加地域组装该名称，或复用同一会话早些时候不相关请求中的 workspace。

因此 aliyun cms2 workspace list 仍是收集候选的正确方式——只是消费其输出而不呈现它是错的。按 One choice, one question 在选项中标记最佳候选 (Recommended)，然后停止并等待。

模块参考不放松这一点。当某参考给出 default-cms-{userId}-{regionId} 作为 workspace 的"默认格式"或从账号 ID 和地域构建它时，那描述的是账号默认 workspace 如何命名——它是推荐候选，绝不是跳过问题的许可。

分页与查询失败处理

• 分页到底：对每条支持 --next-token 的 list 命令，持续查询直到无 nextToken 剩余或累计计数 ≥ totalCount。当分页元数据表明还有更多数据时，不要相信第一页是完整的。
• 分页 list 的页大小：当命令接受 --max-results 时，传 100 然后分页到底。20 页上限乘以 CLI 默认页大小可能截断大型策略列表。
• 累计计数 ≥ totalCount：即使 nextToken 非空或 truncated=true 也停止；totalCount 是更强的信号。
• totalCount 满足的空页：即使 nextToken 存在也停止。
• Token 循环保护：跟踪已见 token；重复时停止并报告为部分。
• 页数上限：默认 20 页；达到时报告为部分。
• 截断结果：不要从部分结果下结论说不存在。用过滤器（--search、--query、--policy-name 等）或完整分页。
• 瞬时查询失败：对瞬时服务端错误（DEADLINE_EXCEEDED、超时）重试一次；仍失败则标记为 Unknown/QueryFailed——不要视为健康或不健康。

错误处理

错误码和动作列在 aliyun cms2 --help。额外提示：

• InvalidJSON 通常意味着 --body 格式错误；传给 CLI 前用 jq . <<<'<value>' 校验。
• --body and stdin are mutually exclusive; specify only one —— 意味着同时提供了 --body（或 --file）和 stdin 数据。修复：只保留一个输入源。在 stdin 可能是管道的 agent/CI 环境中，给命令追加 < /dev/null 以确保 stdin 为空。

输出语言与术语

• 用用户的语言写面向用户的解释、分析、建议、摘要和结论；当语言不明确或混杂时默认简体中文。遵循对话中途的切换，并让关于输出语言的明确指令覆盖两者。
• 问题提示、选项标签、表头和报告也是面向用户的文本——即使参考文件用一种语言写出，也要用答案语言表述它们。
• CLI 命令名、标志、API 路径、JSON 字段名、枚举值、资源 ID、指标名和日志 / 错误消息必须保持逐字英文 / 代码，无论答案语言。
• 用英文回答时：使用术语表的英文列作为规范词汇，而非发明同义词。
• 用中文回答时：在所有行文中使用术语表的中文术语，绝不留下映射术语的英文。仅在能消歧时首次提及时写 中文（English），之后仅用中文术语。发送前，扫描已映射的英文术语并替换它们，代码、命令、JSON 字段、ID 或引用的 CLI 输出内部除外。

示例（中文答案）：

• 好：接入配置（AddonRelease，CLI 命令为 addon-release）
• 好：查询接入配置状态：aliyun cms2 integration addon-release list ...
• 差：all releases are Ready
• 较好：所有接入配置均 Ready

术语表

元数据查询映射

Integration 模块查找（资源元数据、接入状态、策略范围的 Kubernetes 资源、按策略的 Prometheus 实例）见 references/integration-common.md。

模块路由

未列出的命令——见 aliyun cms2 --help。