alibabacloud-cms-manage

CMS CLI — aliyun cms2

前置检查

每个会话执行一次：仅在对话中首次调用此技能时执行此项前置检查。如果本会话中所有检查此前均已通过，请直接转到相关模块。

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

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

2. 检查 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 如果输出与当前版本相同，则表示未满足要求。

   • 版本符合要求 → 转到第 3 步。
   • 版本过旧或无法识别 →
     1. 执行 aliyun upgrade --help，检查是否存在 upgrade 子命令。
        • 存在 → 执行 aliyun upgrade -y 自动更新到最新版本，然后重新检查 aliyun version。
     2. 如果没有 upgrade → 请用户按照官方指南手动升级：https://help.aliyun.com/zh/cli/update-cli。等待用户确认升级完成，然后重新检查 aliyun version。
     3. 如果升级成功 → 转到第 3 步。
     4. 如果升级失败 → 请用户手动升级：https://help.aliyun.com/zh/cli/update-cli。停止并退出。

3. 检查 cms2 插件 — 执行 aliyun cms2 --help。

   • 帮助输出正常 → 继续检查凭证。
   • 出现 unknown command / 缺失 → 立即停止，输出下方的错误报告（附上 CLI 版本、操作系统和错误消息），并且不得再调用任何 CLI 命令。

---

凭证

aliyun cms2 复用 aliyun CLI 凭证系统（aliyun configure）。 使用 --profile <name> 切换配置文件。

可观测性

加载此技能时，每个会话生成一次随机会话 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 是该命令的标志、请求体封装、响应字段和环境行为的权威来源——不要从其他技能文件中查找这些字段的副本。

• 优先使用 -o text（默认值），以减少 list/get 操作的令牌消耗；仅当需要逐字段解析输出而非阅读时，才使用 -o json。
• Addon-release values：按照 Addon Values Defaults 中的说明，将每个字段的 fieldPath 展开为嵌套 JSON。不要将带点号的 fieldPath 写成一个字面键。如何选择 --env-type、创建与更新时子字段的位置，以及何时可以（或不可以）使用子集作为请求体，均见该章节。
• 变更和详情命令必须包含区域参数：除非模块特定规则另有说明，所有 create、update、delete 和单资源 get/详情命令都必须包含 --region 参数，以便将请求路由到正确的后端 OpenAPI 端点。在这些命令中省略 --region 可能导致路由失败或在非预期区域执行操作，而且报错内容可能与实际问题完全无关——即使工作区存在且请求体有效，integration policy create 也会返回 status 400: The workspace can not be created。这不适用于有意跨多个区域查询的 list/查询命令（例如 entity query --source CloudResource 的全区域查询）。要求提供该参数，不代表可以自行选择其值——必须按照 Region Confirmation Gate 确定。
• 一个选择，一个问题：每个列举选项（区域、工作区、策略、addon、作用域模式、标签匹配模式以及任何其他互斥参数）都必须在一个问题中列出所有选项。绝不可拆分到多个问题，也不可放在 （续）... 续问中，更不能删去放不下的选项——拆分会使一个选择变成两个可能冲突或不完整的答案；截断列表则会完全隐藏有效选项。当结构化输入表单无法呈现所有选项时，应改用纯文本提问，并在问题正文中写明每个选项及其说明。互斥选项必须为单选；只有真正可多选的选项（多个区域）才使用多选。一个提示词可以包含多个不同的选择，每个选择各自作为一个问题。任何推荐值都应直接写在选项标签中（例如 (Recommended)）；推荐仅供参考，除非其他规则允许使用默认值或用户已确认，否则不得据此写入云端。
• 写入操作和高影响创建操作必须取得人工确认：执行任何会创建或更改云端状态的命令（create、update、delete、patch、start、stop 等）之前，先简要说明确认摘要和准确命令，询问用户是否确认执行，并等待明确肯定答复。摘要必须包括操作、目标资源标识符、预期影响，以及适用时的重要风险或不可逆影响。无需用户使用特定短语或长篇确认；“yes”“confirm”“proceed”或“确认”等明确肯定答复即表示同意。仅当操作是 dry-run、仅预览，或创建操作等同于读取且不会影响云端时，才可跳过确认；不确定时必须要求确认。
• 不确定的参数必须由用户明确回答：对于任何未明确提供或无法可靠确定的参数值（例如 region/regionId、工作区、策略、resourceGroup、标签、资源作用域、addon/addonName、资源类型、云产品/服务名称、接入配置选项等），继续操作前必须请用户明确回答。绝不可编造、猜测、根据默认值或历史记录推断，或随意选择某个值。模块特定参考资料可能定义有限例外——集成模块的例外见 references/integration-common.md。更改现有 addon release 的设置属于无法预先演练的写入操作：遵循 Addon Release Config Update。
• 发现查询不等于用户答案：读取命令（workspace list、entity query、policy list、sts get-caller-identity 等）仅用于构建供用户选择的候选集合，其输出绝不能代替用户的答案——即使查询只返回一个候选值，即使可按命名约定推导出该值，也不例外；即使用户在本次会话的前一轮使用过该值，也不例外。“可靠确定”是指用户自己的表述或其指定的资源明确锁定了该值，而不是查询结果恰好没有歧义。
• 名称到 ID 的查询必须精确匹配：按名称查找区域 ID、工作区 ID、集成策略 ID、资源组 ID、资源类型值或云产品/服务名称/代码时，如果查询结果中没有精确匹配，不得默默用任意值替代。应向用户说明不匹配的情况，并请其确认或提供正确值。

区域确认门（硬性要求）

适用于每个模块，以及每条接受 --region 或 region/regionId 正文参数的命令。先确定区域，再确定工作区，因为工作区验证受区域范围限制。

仅当模块规则规定调用适用于所有区域时，列表/查询命令才省略 --region。省略该标志并不代表适用于所有区域：CLI 会使用配置文件中的默认值。变更和详情命令必须按必需的区域参数携带该参数。

该值只有以下三个合法来源：

1. 用户在当前请求中明确说明——不包括同一会话中此前无关轮次的内容。
2. 用户从你提供的候选列表中选定，并且你等待用户答复后才运行下一条命令。
3. 主机将其作为运行时上下文注入（即控制台会话的当前区域）。使用前说明你将在哪个区域操作。

其他任何来源都属于违规，包括：CLI 配置文件 / aliyun configure / ALIYUN_REGION 默认值，或省略必需的 --region；文档和示例中的 cn-hangzhou，或仅在叙述中提到的区域；拆分 default-cms-{userId}-{regionId}（或任何工作区名称）；传入 controlRegionId。

模块可以将 --region 绑定到用户已确认资源的 regionId，例如已命名的集群、已通过此门确认的工作区或实例。这仍属于来源 1 或 2。模块说明不会放宽此要求。

如果来源 1 和 2 均不存在，请按一个选择，一个问题将区域作为选项提供，然后停止。使用 aliyun cms2 meta regions 获取候选项，并提供每个 regionId（绝不要提供 showName 或 controlRegionId）；只使用命令输出而不展示候选项是错误的。来源 3（如果存在）只是推荐选项——它用于路由调用，并不决定范围。入门流程的区域范围通过资源范围选择门收集；此处不要再询问一次区域。

controlRegionId 是控制平面区域，在专用/独占位置可能与实际区域不同——绝不要将其作为 --region 传入。

工作区确认门（硬性要求）

适用于每个模块，以及每条接受 --workspace 或 workspace 正文参数的命令。该值只有以下三个合法来源：

1. 用户在当前对话中明确说明。请通过完全匹配 workspaceName，在目标区域验证该工作区是否存在；如果没有完全匹配项，就报告情况并询问用户，绝不要替换为相近项。
2. 用户从你提供的候选列表中选定，并且你等待用户答复后才运行下一条命令。
3. 环境将其作为运行时上下文提供（例如技能运行所在的控制台会话），且其区域与目标区域一致。使用前说明你将在哪个工作区操作。

其他任何情况都属于违规：直接采用 aliyun cms2 workspace list 返回的唯一一行；因为看起来像账户默认项就选择 default-cms-{userId}-{regionId}；使用 aliyun sts get-caller-identity 加上区域拼出该名称；或在同一会话中重用此前无关请求所用的工作区。

因此，aliyun cms2 workspace list 仍然是获取候选项的正确方式——错误之处在于只使用输出而不展示候选项。按照一个选择，一个问题，在选项中将最佳候选项标记为 (Recommended)，然后停止并等待。

模块说明不会放宽此要求。如果模块说明将 default-cms-{userId}-{regionId} 作为工作区的“默认格式”，或根据账户 ID 和区域拼出该名称，那只是在描述账户默认工作区的命名方式——它是建议推荐的候选项，并不意味着可以跳过提问。

分页与查询失败处理

• 分页直至完成：对于每个支持 --next-token 的 list 命令，持续查询，直到没有剩余的 nextToken，或累积数量 ≥ totalCount。当分页元数据表明还有更多数据时，不要认为第一页已经包含全部结果。
• 对分页 list 指定页面大小：当命令接受 --max-results 时，传入 100，然后分页直至完成。本文档优先于 --help：不要依赖省略该标志时的默认值。policy list --help 显示为 30（最大值 100），但省略该参数时可能返回 maxResults: 100；prometheus instance list 省略时的默认值是 30。20 页 × 30 条可能会截断大型列表。
• 累积数量 ≥ totalCount：即使 nextToken 非空或 truncated=true，也应停止；totalCount 是更可靠的信号。
• 总数已满足时遇到空页面：即使存在 nextToken，也应停止。
• 令牌循环保护：记录已见令牌；遇到重复令牌时停止，并报告结果不完整。
• 页面数限制：默认 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 数据。解决方法：仅保留一个输入源。在 Agent/CI 环境中，stdin 可能是管道；可在命令末尾追加 < /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

术语表

英文	中文
Cloud Monitor / CMS	云监控
Workspace	工作空间
Application Monitoring / APM	应用监控
RUM	用户体验监控
Synthetic Monitoring / Synthetic	云拨测
CloudResource	云资源
EntityStore	实体仓库
Entity	实体
Integration Policy / policy	接入策略
Addon / addon	组件
Addon Catalog	组件目录
AddonRelease / addon release / release	接入配置
Collector	采集器
Prometheus View	Prometheus 聚合视图
AggTaskGroup	聚合任务
Delivery Task	数据投递任务
Alert Rule	告警规则
Alert Template	告警模板
Alert History	告警历史
Notification Channel	通知渠道
Contact	联系人
Event Hub	事件中心
Metric Meta	指标元数据
ClusterCollector	集群采集器
NodeCollector	节点采集器
Cluster probe	集群探针
Metric drop	指标废弃
CMS resource tag	CMS 资源标签
Grafana workspace	Grafana 工作区

元数据查询映射

所需内容	获取方式
指标业务元数据（通过 meta namespaces 获取命名空间和产品代码；通过 meta metrics 获取指标名称、类型、单位和维度）	meta namespaces / meta metrics
Prometheus 标签、值和序列检查	metric promql labels / label-values / series

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

模块路由

用户意图关键词	命令	模块
入门配置、监控插件、策略、集成、插件发布、集成资源、Kubernetes 资源列表、策略下的 Namespace 资源、由策略管理的资源、拆除、退出集成 — 通用规则，每次入门配置操作都要加载	integration integration resource	references/integration-common.md
容器入门配置、ACK/ACS/ASI 集群入门配置、集群集群审计、哪些集群尚未完成入门配置	integration entity query	references/cs-onboarding.md（+ integration-common.md）
ECS 主机入门配置、ECS 集群审计、NodeCollector	integration entity query	references/ecs-onboarding.md（+ integration-common.md）
云服务入门配置、RDS/SLB/ALB/Redis/MongoDB/PolarDB 入门配置、云资源集群审计	integration entity query	references/cloud-onboarding.md（+ integration-common.md）
批量云服务指标入门配置、批量入门配置、cloud-batch-metrics	integration meta entity query	references/batch-onboarding-workflow.md（+ integration-common.md）
集成策略诊断、健康检查、策略故障排查、抓取配置、ServiceMonitor/PodMonitor/自定义采集诊断、custom-discover-<id>（发布名称——将其视为自定义任务前先读取 discoverType）、任务目标	integration check-scrape-config integration job-target integration check-collector-target integration resource integration dashboard	references/integration-diagnosis.md
指标丢弃、丢弃指标、dropMetrics、指标废弃、丢弃指标、废弃指标、集群探针 metric-agent	integration collector integration addon-release	references/integration-management.md（+ integration-common.md）
添加／修改／移除 CMS 资源标签、打标签、修改标签、删除标签、CMS 资源标签、应用服务（APM/RUM）标签	tag	references/integration-management.md（+ integration-common.md）
Prometheus 视图、Prometheus 聚合视图、创建 Prometheus 聚合视图、创建 Prometheus 视图、Prometheus 聚合视图诊断、Prometheus 聚合视图健康检查、子实例状态	prometheus view	references/prometheus-management.md
工作空间、创建工作空间、获取工作空间、列出工作空间、更新工作空间、删除工作空间	workspace	aliyun cms2 workspace --help
实体、实体查询、CloudResource、EntityStore、云资源查询、实体存储查询、资源元数据、实例详情	entity query	aliyun cms2 entity --help
Prometheus 实例、recordingRule、recording rule、AggTaskGroup	prometheus instance prometheus recording-rule	aliyun cms2 prometheus --help
元数据、指标元数据、产品代码、meta-format	meta metrics meta namespaces	aliyun cms2 meta --help
指标、指标查询、基础指标、PromQL、promql 查询、标签值、时间序列	metric basic metric promql	aliyun cms2 metric --help
告警、规则、告警规则、告警模板、告警历史、补丁、创建规则、管理规则	alert rule alert template alert history	references/alerting.md
APM measureCode、group/filter/groupBy、baseUnit/displayUnit	alert rule（APM 类型）	references/apm-metrics.md
UModel metricSet、K8s pod 指标、基于实体的告警	alert rule（UModel 类型）	references/umodel-metrics.md
通知、联系人、机器人、webhook、通知接收人、dingTalk、机器人、lark、weChat work	notification-channel contact notification-channel robot notification-channel webhook	references/alerting.md
事件、event-hub、告警事件、SLS 事件、事件响应	event-hub	references/event-hub.md
Grafana、Grafana 工作空间、托管 Grafana 实例、创建／查询／更新／删除 Grafana 工作空间	grafana workspace	aliyun cms2 grafana workspace --help
Grafana 仪表盘编写、仪表盘 JSON、面板、PromQL 面板、仪表盘变量、数据源占位符	meta metrics metric promql integration storage	references/grafana-dashboard-rules.md
APM、应用监控、Agent 安装、Java Agent、Golang Agent、Python Agent、Node.js Agent、PHP Agent、.NET Agent、ack-onepilot、OpenTelemetry 入门配置、K8s/ACK/ACS 容器入门配置、ECS 主机应用入门配置、LicenseKey、专有 Agent、instgo、aliyun-bootstrap、探针设置、APM 入门配置	apm service apm configuration	references/apm.md
AI 可观测性、Dify、LangChain、LangGraph、DashScope、AgentScope、OpenAI、Coze、OpenClaw、CoPaw、Hermes、大模型监控、AI 追踪、AI Agent 监控、自定义埋点	apm service apm configuration integration addon	references/ai.md
RUM、真实用户监控、用户体验监控、前端监控、Web 监控、H5、移动应用监控、Android 崩溃、iOS 崩溃、JS 错误、页面性能、小程序监控、创建 RUM 应用、RUM SDK、pid、serviceId、endpoint	rum service rum configuration	references/rum.md
资源组查询	resource-group	aliyun cms2 resource-group --help
未在上述列出的命令——请参阅 aliyun cms2 --help。