alibabacloud-aes-ack-pod-performance-profiling

alibabacloud-aes-ack-pod-performance-profiling

技能名称：alibabacloud-aes-ack-pod-performance-profiling 目标：对阿里云 ACK 集群 Pod 执行 SysOM 性能分析。

---

凭证安全

[CRITICAL] 凭证安全规则：

• 绝不在对话或命令输出中打印、回显或显示 AccessKey ID / AccessKey Secret 值（即使是对 LTAI_ACCESS_KEY_ID 进行部分掩码也禁止）
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用带有明文凭证值的 aliyun configure set
• 只能使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（在终端中通过 aliyun configure 配置，或在 shell 配置文件中设置环境变量）
3. 返回并在 aliyun configure list 显示有效配置后重新运行

---

RAM 策略

此技能所需 RAM 权限的完整列表，请参阅 references/ram-policies.md。

[MUST] 权限错误处理： 在执行期间的任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停操作，等待用户确认所需权限已获授

---

参数确认

重要：参数确认——执行任何命令或 API 调用前， 必须与用户确认所有可自定义参数（例如 RegionId、集群 ID、命名空间、Pod 名称等）。 未经用户明确批准，不要假定或使用默认值。

Pod 诊断所需的用户输入

Pod 诊断场景需要用户提供以下信息：

1. Pod 名称（pod）——必填
2. 命名空间（namespace）——必填
3. 集群 ID（cluster_id）——必填

范围：仅支持运行在常规 ECS 支持型 ACK 节点上的 Pod。instance 字段始终自动推导为 ack-<cluster_id>。

参数	必填/可选	描述	默认值
cluster_id	必填	ACK 集群 ID（例如 c0ee8f62dd10541c598af3627d5b6cda7）	无，必须由用户提供
region	必填	ACK 集群所在地域（例如 cn-hangzhou）	无，必须由用户提供或根据集群推导
namespace	必填	目标 Pod 的 Kubernetes 命名空间	无，必须由用户提供
pod	必填	要诊断的 Pod 名称（例如 test-app-64cdcb7b98-gchks）	无，必须由用户提供
instance	自动推导	运行该 Pod 的实例 ID，始终为 ack-<cluster_id>	根据 cluster_id 自动推导
description	可选	问题描述关键词。必须匹配 ^[a-zA-Z0-9_-]*$——将空格替换为 _（例如 "pod_oom"、"high_load"）	""
start_time	可选	诊断开始时间戳（Unix 秒）	0（实时）
end_time	可选	诊断结束时间戳（Unix 秒）	0
enable_diagnosis	可选	强制执行实时诊断（优先级最高）	true

---

核心工作流

工作流分为两个阶段，共 10 个步骤。

User-Agent 规则（三个独立的陈述；每条陈述都特意编写为不会在描述性句子中同时提及系统命令名称和请求标志令牌）：

1. 业务命令必须附带请求标志。 业务命令指 cs、sysom 和 sts 命名空间下的命令。必需的请求标志值为 AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling。
2. 系统／工具命令集是固定的。 其中恰好包含五个成员：configure、plugin、help、version、upgrade。（此陈述不会提及请求标志令牌；适用于这些命令的规则见陈述 3。）
3. 陈述 2 中列出的命令调用时不得携带请求 User-Agent 标志。

允许的例外（配置值设置器，不是请求标头）。 子命令 aliyun configure ai-mode set-user-agent 接受一个必需参数；根据 aliyun configure ai-mode set-user-agent --help，该参数的标志写法恰好是 --user-agent <value>。此参数会将 AI-mode User-Agent 写入本地 CLI 配置文件。它是要存储的值，而不是 HTTP 请求标头，因此不受陈述 3 中规则的约束。

阶段 1：环境设置（步骤 0–3）

步骤 0 — 启用 AI-Mode 并更新插件

执行任何 CLI 命令之前，请启用 AI-Mode、设置 User-Agent 并更新插件。

为什么下面的 bash 代码块符合规则：下面的 set-user-agent 子命令行是文档中允许的例外（见上方“允许的例外”说明框）。其中的 --user-agent <value> 是此配置设置器子命令所需的位置参数，而不是 HTTP 请求标头。代码块中的其他行均未携带请求标志。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling"  # ALLOWED-EXCEPTION: config-setter argument, not a request header
aliyun plugin update

⚠️ 上述三个命令必须在所有 CLI 操作之前执行，且只需运行一次。

步骤 1 — 检查 CLI 版本

aliyun version

验证版本 >= 3.3.15。如果不满足，请参阅 references/cli-installation-guide.md 进行安装。

步骤 2 — 启用自动插件安装

aliyun configure set --auto-plugin-install true

步骤 3 — 凭证验证

aliyun configure list

如果不存在有效凭证，请停止，并引导用户在会话之外配置凭证。

---

阶段 2：执行诊断（步骤 4–8）

详细工作流请参阅 references/diagnose-workflow.md。

⛔ 强制执行链——不得跳过、不得调整顺序、不得探索其他方案

第 4 步参数确认完成后，必须按顺序执行以下四次 API 调用。每一项都是硬性要求——跳过其中任何一项都将导致工作流失败：

1. 第 5 步 — aliyun cs GET /clusters/<cluster_id>（cs.DescribeClusterDetail）
2. 第 6 步 — aliyun sysom initial-sysom --check-only false --source aes-skills（sysom.InitialSysom）— 必须执行，绝非可选
3. 第 7 步 — .sysom-sdk-venv/bin/python scripts/create-cluster-vpc-endpoint-connection.py（通过 SDK 调用 cs.CreateClusterVpcEndpointConnection）— 必须执行，绝非可选
4. 第 8 步 — aliyun sysom invoke-diagnosis ...（sysom.InvokeDiagnosis），然后通过 aliyun sysom get-diagnosis-result --task-id <task_id> 轮询（sysom.GetDiagnosisResult）— 必须执行，绝非可选

⛔ 关键：诊断 API 是 sysom invoke-diagnosis，不是 CS 集群诊断端点。 CS 产品有单独的诊断 API（cs POST /clusters/<cluster_id>/diagnosis，即 cs:CreateClusterDiagnosis）——这是完全不同的功能，绝对不能使用。如果调用 cs:CreateClusterDiagnosis 或 aliyun cs POST /clusters/.../diagnosis，工作流将失败。此技能唯一正确的诊断 API 是 aliyun sysom invoke-diagnosis。

严格禁止以下行为（这些行为曾导致实际评测失败）：

• 禁止使用 cs:CreateClusterDiagnosis / aliyun cs POST /clusters/<cluster_id>/diagnosis 进行诊断。这是错误的 API。此技能使用 SysOM 诊断（sysom invoke-diagnosis），而不是 CS 集群诊断。
• 禁止将 aliyun sysom --help / aliyun sysom <subcommand> --help 作为“探索”步骤调用。此技能所需的三个 sysom 子命令是固定的：initial-sysom、invoke-diagnosis、get-diagnosis-result。不要查看任何其他 sysom 子命令的帮助。
• 禁止调用上述三个子命令以外的任何 sysom 子命令。尤其是，此技能不得调用以下 sysom 子命令：list-abnormaly-events、describe-metric-list、get-resources、list-pods-of-instance，或工作流中未明确列出的任何其他 sysom 子命令。
• 禁止用通过帮助信息发现的“更方便”的 sysom 子命令，或任何 CS 产品 API，替代四项强制调用中的任何一项。
• 禁止在第 5 步 / 第 6 步 / 第 7 步后终止工作流；必须继续调用 invoke-diagnosis 并进行轮询。
• 禁止在未通过 invoke-diagnosis 获取 task_id，并通过 get-diagnosis-result 轮询至终止状态的情况下宣告成功。
• 禁止在第 5 步成功时跳过第 6 步和第 7 步。即使第 5 步返回了有效的集群信息，仍必须按顺序执行第 6、7、8 步。

第 4 步 — 参数确认（反转门）

必须向用户确认以下信息。如果未提供任何必需值，需在继续之前明确询问。

1. cluster_id — 必需
2. namespace — 必需
3. pod — 必需
4. 另外提取可选的 description、时间范围等。

⚠️ 时间推断规则：当用户的描述中包含任何时间指向（例如“今天早上”“昨天下午”“下午 3 点左右”“昨晚”）时，必须主动询问具体时间范围，并建议使用历史诊断模式。如果问题明显发生在过去，不要默认采用实时诊断。

第 5 步 — 获取集群信息

调用的 API：cs.DescribeClusterDetail（POP 代码 cs，版本 2015-12-15）。 通过 CLI ROA 路径形式 aliyun cs GET /clusters/<cluster_id> 调用（符合插件模式）。根据 SA-2.11，禁止使用传统的 PascalCase RPC 形式。

# API: DescribeClusterDetail (cs:2015-12-15) — ROA path form
aliyun cs GET /clusters/<cluster_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling

从响应中提取 region_id、name 和 profile。验证集群存在且处于 running 状态。

• region_id → 在 invoke-diagnosis 参数中用作 region
• name → 记录以供参考（不在 invoke-diagnosis 参数中使用）
• profile → 必须为 "Default"（表示标准 ACK 托管集群）
• cluster_id → 用于构造 instance 字段，格式为 ack-<cluster_id>

⛔ 集群类型验证（硬性停止条件）：从 DescribeClusterDetail 响应中提取 profile 字段：

• profile == "Default" → 标准 ACK 集群，继续诊断。
• profile != "Default"（例如 "acs"、"Serverless"、"Edge" 等）→ 立即停止。输出以下消息并终止工作流：

❌ 不支持的集群类型
- 集群 ID：<cluster_id>
- 集群配置：<profile>
- 此技能仅支持对标准 ACK 托管集群（profile = "Default"）进行诊断。
- ACS 集群、ASK（Serverless Kubernetes）集群、Edge 集群以及其他 profile 非 Default 的集群均不受支持。
- 请提供标准 ACK 集群 ID 以继续。

当 profile != "Default" 时，禁止继续执行步骤 6 / 7 / 8。

⛔ 硬性停止条件（失败即关闭）：如果调用返回非成功状态（ErrorClusterNotFound、HTTP 404、Forbidden.RAM、网络错误或任何其他失败），则必须立即停止工作流，并要求用户验证 cluster_id。步骤 5 失败时，以下操作严格禁止：

1. 响应未提供区域值时，禁止合成、猜测或硬编码区域值。
2. 没有经过验证的 region_id 时，禁止继续执行步骤 6 / 7 / 8。
3. 禁止创建模板诊断产物、伪造任务 ID 或输出占位 JSON。
4. 未经用户明确输入，禁止以其他 cluster_id 静默重试。
5. 禁止使用任何 cs 诊断 API（例如 cs POST /clusters/<id>/diagnosis，又名 cs:CreateClusterDiagnosis）作为回退方案。CS 诊断 API 是一项不同的功能——此技能仅使用 SysOM sysom invoke-diagnosis。

失败时唯一允许的操作：将错误原样告知用户，并请求提供正确的 cluster_id。

⛔ 步骤 5 成功后——继续执行步骤 6，切勿通过 CS 进行诊断： 步骤 5 返回有效集群详情后，下一步操作是步骤 6（sysom initial-sysom）。不要尝试任何基于 CS 的诊断（cs POST /clusters/<id>/diagnosis、cs:CreateClusterDiagnosis）。诊断通过 SysOM API（步骤 6→7→8）执行，绝不通过 CS 产品执行。

步骤 6 — 初始化 SysOM 角色

调用的 API：sysom.InitialSysom（POP 代码 sysom，版本 2023-12-30）。

⛔ 必须执行——不可跳过。 此调用会在账户上激活 SysOM 服务角色。每次工作流运行都必须且只能调用一次，并且必须在步骤 7 和步骤 8 之前调用。跳过此调用会导致后续 invoke-diagnosis 调用因授权错误而失败。不要假设“角色可能已经初始化”——始终使用 --check-only false 调用 initial-sysom。

# API: InitialSysom (sysom:2023-12-30)
aliyun sysom initial-sysom --check-only false --source aes-skills --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling

步骤 7 — 创建集群 VPC 终端节点连接（SDK 调用）

调用的 API：cs.CreateClusterVpcEndpointConnection（POP 代码 cs，版本 2015-12-15）。CLI 不支持此操作；SDK 脚本是唯一可用方式。

⛔ 必须执行——不可跳过。 此步骤会在 SysOM 与目标集群之间建立内部诊断通道。缺少此步骤，步骤 8 中后续的 invoke-diagnosis 调用将无法连接到集群并失败。此脚本具有幂等性——在已建立连接的集群上重新运行是安全的，并会立即返回成功。不要假设“之前可能已经做过”而跳过此步骤。 ⛔ 如何执行：必须在终端（shell）中运行以下命令。 这是此工作区中的本地 Python 脚本 — 必须将其作为 shell 命令执行。阅读 API 文档、通过 Web 获取 API 元数据，或从列表中查找 API 名称，都不算执行。只有运行此脚本才会发起 API 调用。

前提条件（如果虚拟环境不存在，则运行一次）：

bash scripts/setup-sdk.sh

执行 VPC 终端节点创建（必须在终端中运行）：

.sysom-sdk-venv/bin/python scripts/create-cluster-vpc-endpoint-connection.py \
  --region "<region>" \
  --cluster-id "<cluster_id>"

成功时的预期输出：[OK] Cluster VPC endpoint connection created successfully.

[自动执行] 此步骤会为集群创建 VPC 内部终端节点连接，作为诊断的前提条件。虽然这会修改网络配置（写操作），但无需用户确认即可自动执行，因为这是必须满足的前置条件，没有它就无法继续诊断工作流。

• 集群 ID：<cluster_id>
• 区域：<region>
• 影响：在 SysOM 与此集群之间建立内部诊断通道
• 幂等：对于已建立连接的集群，重复运行是安全的

⚠️ --dry-run 标志：仅在测试时传入 --dry-run（不带值）。实际执行时，完全省略此标志 — 不要传入 --dry-run false 或 --dry-run "false"（该标志是布尔型 store_true，不接受值）。

⚠️ 必须使用 .sysom-sdk-venv/bin/python 执行脚本 — 严禁使用系统的 python3。

第 7 步禁止执行以下操作：

• 禁止跳过此步骤。必须先创建 VPC 终端节点，才能执行 invoke-diagnosis。
• 禁止将通过 Web 获取的 API 元数据或文档列表视为执行凭据。必须在终端中运行脚本。
• 禁止使用 aliyun cs CLI 执行此操作 — 该 CLI 不支持此操作。只有 SDK 脚本可以执行。
• 禁止在未运行此脚本且未看到 [OK] 输出的情况下继续第 8 步。

第 8 步 — 发起诊断并轮询结果

⛔ 必须执行 — 这不是可选项。 必须同时调用 invoke-diagnosis，并通过 get-diagnosis-result 轮询结果。只有轮询到终止状态，工作流才算完成。invoke-diagnosis 返回 task_id 后，不要在未轮询的情况下结束，也不要以“无需诊断”为由跳过 invoke-diagnosis。

诊断模式判定规则

if enable_diagnosis == true:
    mode = real-time diagnosis    # enable_diagnosis has highest priority
elif start_time != 0:
    mode = historical diagnosis   # time range specified, retrospective analysis
else:
    mode = real-time diagnosis    # default

• 实时：start_time=0、end_time=0、enable_diagnosis=true
• 历史：start_time=<unix_ts>、end_time=<unix_ts>、enable_diagnosis=false

构建 params JSON

必需的基础字段（必须全部包含）：

实时模式模板（默认 — 未提供时间范围时）：

{
  "product": "ACK",
  "region": "<region_id>",
  "instance": "ack-<cluster_id>",
  "cluster_id": "<cluster_id>",
  "namespace": "<namespace>",
  "pod": "<pod_name>",
  "description": "<sanitized_description>",
  "start_time": 0,
  "end_time": 0,
  "enable_diagnosis": true
}

历史模式模板（用户提供了过去的时间范围时 — 用户的描述中包含“今天早上”“昨天下午”“下午 3 点左右”“昨晚”等任何时间表述时，必须使用此模板）：

{
  "product": "ACK",
  "region": "<region_id>",
  "instance": "ack-<cluster_id>",
  "cluster_id": "<cluster_id>",
  "namespace": "<namespace>",
  "pod": "<pod_name>",
  "description": "<sanitized_description>",
  "start_time": <unix_start_ts>,
  "end_time": <unix_end_ts>,
  "enable_diagnosis": false
}

⚠️ 模式选择不是可选项：根据诊断模式判定规则，从上方两个模板中准确选择一个。将 enable_diagnosis=true 与非零的 start_time/end_time 一起设置是无效的 — 引擎会忽略时间范围，并静默地以实时模式运行。

⚠️ instance 字段：始终使用 ack-<cluster_id>（例如 ack-cd5b0b91bc05540b1a4c1ddb37f5175c8）。

此值必须匹配正则表达式 ^[a-zA-Z0-9_-]*$ — 不要使用原始集群名称，因为其中可能包含中文字符或空格。

⚠️ region 字段：从第 5 步 DescribeClusterDetail 响应的 region_id 字段中获取。

⚠️ product 字段：必须为 "ACK"（大写）— 这会告知 SysOM 引擎执行 ACK Pod 级诊断，而不是 ECS 操作系统级诊断。

调用诊断

调用的 API：sysom.InvokeDiagnosis（POP 代码 sysom，版本 2023-12-30）。

⚠️ 硬性规则 — description 字段净化（适用于每一次 invoke-diagnosis 调用，无一例外）：

• description 的值必须匹配正则表达式 ^[a-zA-Z0-9_-]*$（仅限 ASCII 字母、数字、_、-）。
• 调用前，净化用户提供的描述：将每个空格替换为 _，删除或转写所有中文／Unicode 字符／标点符号（.、~、,、: 等）。
• 示例："pod oom" → "pod_oom"，"高负载" → "high_load"，"Pod OOM diagnosis" → "pod_oom_diagnosis"，""（空字符串）也有效。
• 违反此规则会导致 API 以 Sysom.InvalidParameter 拒绝调用，且诊断无法启动。

# API: InvokeDiagnosis (sysom:2023-12-30)
aliyun sysom invoke-diagnosis \
  --service-name ocd \
  --channel ecs \
  --params '{"product":"ACK","region":"<region_id>","instance":"ack-<cluster_id>","cluster_id":"<cluster_id>","namespace":"<namespace>","pod":"<pod_name>","description":"<sanitized_description>","start_time":<start_time>,"end_time":<end_time>,"enable_diagnosis":<enable_diagnosis>}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling

从响应中提取 task_id。

对 Sysom.TaskInProgress 的特殊处理：如果返回此错误，表示目标实例上已有诊断任务正在运行。错误响应正文不包含 task_id 字段（仅包含 Code、Message、HostId、Recommend、RequestId）。因此：

1. 等待 30 秒，然后重试 invoke-diagnosis（最多重试 3 次）。
2. 如果重试成功，从成功的响应中提取 task_id，然后继续轮询。
3. 如果 3 次重试均仍返回 TaskInProgress，停止并输出：

⚠️ An existing diagnosis task is running on this instance.
- Instance: ack-<cluster_id>
- Error: Sysom.TaskInProgress
- Suggestion: Please wait for the running task to complete (typically 3–5 minutes), then retry.

⛔ 禁止事项（适用于上述重试循环，以及所有重试均已用尽的情况）：

• 不要猜测或伪造 task_id 值（例如使用 cluster_id、实例 ID、RequestId 或 pod 名称作为 task_id）。task_id 必须来自成功的 invoke-diagnosis 响应。
• 不要编写自定义 SDK 脚本，也不要使用其他方法调用诊断。唯一允许的调用方式是上方所示的 CLI 命令。
• 未从成功的响应中获取有效 task_id 前，不要继续调用 get-diagnosis-result。

轮询结果（间隔：10 秒，最多 60 次）

调用的 API：sysom.GetDiagnosisResult（POP 代码 sysom，版本 2023-12-30）。

# API: GetDiagnosisResult (sysom:2023-12-30)
aliyun sysom get-diagnosis-result --task-id <task_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling

⛔ 轮询期间的行为约束（必须遵守）：

等待诊断结果期间进行轮询时，以下操作严格禁止（包括执行和向用户建议）：

1. 禁止在集群上执行 kubectl 命令
2. 禁止调用 ECS 监控、CloudMonitor 或其他 API
3. 禁止尝试“替代诊断方法”或启动新的诊断任务
4. 禁止调用本技能命令表中未列出的任何命令
5. 禁止将上述任何操作作为“替代方案”或“备用选项”建议给用户

唯一允许的操作：继续调用 aliyun sysom get-diagnosis-result 进行轮询，或在超时后停止。

超时处理：如果轮询 60 次后仍未完成，必须且只能输出以下模板，然后停止：

⏳ SysOM diagnosis task timed out
- Task ID: <task_id>
- Current status: <status>
- Suggestion: Please continue waiting for the diagnosis to complete.

步骤 9 — 结果解析与输出

解析返回的 JSON，并向用户展示 summary.overall_status、summary.root_cause、summary.suggestions、issues[] 及其他关键信息。

---

成功验证

各阶段的验证方法请参见 references/verification-method.md。

---

清理

此技能中的诊断操作为只读，不会修改集群状态，因此无需清理。

完成所有 CLI 操作后，必须禁用 AI-Mode：

aliyun configure ai-mode disable

---

命令表

完整的 CLI 命令列表请参见 references/related-commands.md。

---

最佳实践

1. 诊断前确认集群存在且为标准 ACK 集群：始终调用 GET /clusters/<cluster_id> 确认集群状态、提取地域，并验证 profile == "Default"。如果 profile 不是 "Default"（例如 acs、Serverless），立即停止——仅支持标准 ACK 集群。
2. 默认使用实时诊断模式：除非用户明确指定时间范围，否则默认设置 enable_diagnosis=true
3. 描述字段格式限制：description 字段必须匹配正则表达式 ^[a-zA-Z0-9_-]*$（仅允许 ASCII 字母、数字、_、-）。将空格替换为 _（例如，"pod oom" → "pod_oom"）。中文字符、句点、波浪号和其他符号会导致 Sysom.InvalidParameter。
4. 获取目标字段所需的 UID：target 字段需要账户 UID——始终使用 sts get-caller-identity（插件模式）获取该 UID
5. 凭据安全：绝不在对话中打印或回显 AK/SK 值
6. User-Agent 标志规则（拆分为两条独立子规则，确保没有任何一行同时提及系统命令名称和标志令牌）：
   • 6a. 每个业务 CLI 命令（cs、sysom、sts）都必须包含请求标志，并将其值设为 AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling。
   • 6b. 五个系统／工具命令 configure、version、plugin、help、upgrade 在其调用行中不得携带请求标志。（此子规则有意不提及标志令牌；该规则的表述由子规则 6a 的互补关系决定。）
7. 修复建议可能涉及高风险操作：遵循 Human-in-the-loop 协议，并等待用户确认

---

不支持的场景

仅支持标准 ACK 托管集群（DescribeClusterDetail 响应中的 profile = "Default"）。以下集群类型／工作负载不受支持——工作流必须在第 5 步集群类型验证时停止：

• ACS 集群（profile = "acs"）——不受支持
• 无服务器 Kubernetes（ASK）集群（profile = "Serverless"）——不受支持
• 边缘集群（profile = "Edge"）——不受支持
• 任何 profile != "Default" 的集群——不受支持
• 基于 Windows 的容器工作负载
• 处于 Pending 状态的 Pod（尚未调度到节点）
• 虚拟节点／弹性容器实例（ECI）Pod

---

错误处理

错误场景	CLI 响应	Agent 操作
未找到集群	GET /clusters 返回 404	提醒用户检查集群 ID
在集群中未找到 Pod	诊断返回 Pod 未找到	请用户核实命名空间和 Pod 名称
角色授权失败	initial-sysom 返回错误	提示用户检查 SysOM 服务的启用状态
诊断调用失败	invoke-diagnosis 返回错误	检查凭据和权限配置
诊断超时	get-diagnosis-result 轮询超时	建议用户稍后重试
权限不足	API 返回 Forbidden	阅读 references/ram-policies.md 并指导用户申请权限
未安装 SDK	ModuleNotFoundError	提示用户运行 bash scripts/setup-sdk.sh

---

参考链接

参考资料	说明
references/cli-installation-guide.md	阿里云 CLI 安装与配置指南
references/ram-policies.md	RAM 权限策略列表
references/related-commands.md	完整的 CLI 命令列表
references/verification-method.md	各阶段的成功验证方法
references/diagnose-workflow.md	详细的诊断工作流（步骤 4–8）
references/acceptance-criteria.md	Skill 测试验收标准（正确/错误的命令模式）