alibabacloud-aes-sysom-pai-diagnosis

alibabacloud-aes-sysom-pai-diagnosis

技能名称：alibabacloud-aes-sysom-pai-diagnosis 目标：对 Alibaba Cloud PAI 产品（EAS / DLC）执行 SysOM 深度诊断，以确定实例级性能和健康问题的根因。

---

凭证安全

[严重] 凭证安全规则：

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

aliyun configure list

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

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

1. 从 Alibaba Cloud Console 获取凭证
2. 在本次会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并在 aliyun configure list 显示有效配置后重新运行

---

RAM 策略

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

**[必须] 权限错误处理：**执行过程中，任何命令或 API 调用因权限错误而失败时，都必须遵循以下流程：

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

---

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例 ID、产品类型、 时间范围等）。未经用户明确批准，不得自行假设或使用默认值。

参数	必填/可选	说明	默认值
region	必填	PAI 资源所在的地域（例如 cn-hangzhou）	无，必须由用户提供
instance	必填	PAI 实例 ID（EAS 服务 ID eas-m-xxx 或 DLC 作业 ID dlcxxxxxxxx）	无，必须由用户提供
product	必填	PAI 子产品类型，只能是 EAS 或 DLC	根据 instance 前缀自动推断（eas- → EAS，dlc → DLC）；仅在无法推断时询问用户
start_time	可选	诊断开始时间戳（Unix 秒）	0（实时）
end_time	可选	诊断结束时间戳（Unix 秒）	0
enable_diagnosis	可选	强制执行实时诊断（优先级最高）	false
uid	可选	资源所属账号的 ID	None
ocd_description	可选	用户以英文描述的问题，单词之间用下划线（_）连接。不得包含中文字符或空格。例如：GPU_OOM_instance_restart	None

产品自动推断规则

product 字段必须出现在 params JSON 中。其值按以下规则确定：

1. 如果用户明确指定了 product（EAS 或 DLC），则使用用户指定的值
2. 否则，根据 instance 前缀推断：
   • eas- → EAS
   • dlc（无连字符，例如 dlcxxxxxxxx）→ DLC
3. 如果推断存在歧义或失败，必须明确询问用户选择 EAS 或 DLC

---

核心工作流

此工作流分为两个阶段，共 8 个步骤。所有 aliyun CLI 业务命令（SysOM、EAS、DLC API 调用）必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis。系统命令（version、configure、plugin）不使用 --user-agent。

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

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

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

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis"
aliyun plugin update

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

步骤 1 — 检查 CLI 版本

aliyun version

确认版本 >= 3.3.1。如果不符合要求，请参阅 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 — 澄清模糊问题（反转门）

必须确认 region、instance 以及异常发生的时间。如果用户未提供，请明确询问。根据 instance 前缀自动推断 product（eas- → EAS，dlc → DLC）；只有在推断失败时才询问用户。同时提取可选的时间范围。

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

步骤 5 — 初始化 SysOM 角色

aliyun sysom initial-sysom --check-only false --source aes-skills --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

步骤 6 — 资源验证

调用诊断前，必须根据推断出的 product 验证资源：

6A. EAS — 验证服务是否存在

aliyun eas list-services \
  --region <region> \
  --filter <eas_service_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

在返回的 Services 数组中，确认存在 ServiceId 匹配的条目。如果未找到匹配项，请告知用户服务 ID 无效，并停止流程。

6B. DLC — 验证资源类型是否为 Lingjun

aliyun pai-dlc get-job \
  --region <region> \
  --job-id <dlc_job_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

检查响应中的 ResourceType 字段：

• Lingjun → 继续执行步骤 7
• 其他任何值 → 停止并告知用户：“SysOM 诊断目前仅支持在 Lingjun 资源上运行的 DLC 作业。您的作业使用的是 <ResourceType>，暂不受支持。”

⚠️ params JSON 中的 instance 字段直接使用原始实例 ID（eas-m-xxx 或 dlcxxxxxxxx）——此步骤仅用于验证。

步骤 7 — 调用诊断并轮询结果

诊断模式判定规则

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
• 历史：start_time=<unix_ts>，end_time=<unix_ts>
• 强制实时：当 enable_diagnosis=true 时，即使提供了 start_time，也将其强制设为 0

构建 params JSON

使用 snake_case 键（与 SDK 保持一致）。必填基础字段（必须全部包含）：

{
  "instance": "<eas_service_id_or_dlc_job_id>",
  "region": "<region>",
  "product": "<EAS_or_DLC>",
  "start_time": 0,
  "end_time": 0,
  "type": "ocd",
  "ai_roadmap": true,
  "enable_sysom_link": false,
  "ocd_description": "<user_problem_description_in_english_with_underscores>"
}

⚠️ 防混淆提示：params JSON 中的 "type": "ocd" 和 "product": "<EAS|DLC>" 都是必填字段——两者都不可省略！

• --service-name ocd（CLI 参数）→ 告诉 CLI 要调用哪个诊断服务端点
• "type": "ocd"（params JSON 字段）→ 告诉诊断引擎要在内部执行哪种诊断类型
• "product": "EAS" 或 "product": "DLC"（params JSON 字段）→ 告诉诊断引擎要针对哪个 PAI 子产品

以上三项均为必填项；不可省略任何一项。

**⚠️ instance 字段直接使用原始实例 ID——EAS 使用 eas-m-xxx，DLC 使用 dlcxxxxxxxx。**请勿转换为 ServiceName 或任何其他标识符。

条件字段（仅在非空时添加）：

• uid：拥有该资源的账户 ID（整数）
• ocd_description：用户的问题描述（字符串）。格式限制：必须为英文，不得包含中文字符或空格——使用下划线（_）连接单词。例如：high_latency_first_token、GPU_OOM_killed

调用诊断

aliyun sysom invoke-diagnosis \
  --service-name ocd \
  --channel ecs \
  --params '{"instance":"<eas_service_id_or_dlc_job_id>","region":"<region>","product":"<EAS|DLC>","start_time":<start_time>,"end_time":<end_time>,"type":"ocd","ai_roadmap":true,"enable_sysom_link":false}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

从响应中提取 task_id。

⚠️ [CRITICAL] Sysom.TaskInProgress 错误处理： 如果 invoke-diagnosis 返回 Sysom.TaskInProgress 错误，表示已有诊断任务正在运行。你必须：

1. 使用字符串匹配从错误消息中提取现有的 task_id（模式：ocd(<task_id>) 或消息正文中的类似标识符）
2. 立即使用提取出的 task_id 进入轮询流程
3. 绝不要将 TaskInProgress 视为致命故障或中止工作流

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

aliyun sysom get-diagnosis-result --task-id <task_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

检查响应中的 status 字段：

• Ready / Running → 必须以 10s 的间隔继续轮询
• Success → 诊断完成，进入步骤 8
• Fail → 诊断失败，告知用户

⛔ [CRITICAL] 强制轮询规则（必须遵守——违反将导致结果错误）：

1. Running 状态属于正常情况——这仅表示诊断引擎仍在工作。你必须每隔 10 秒继续轮询。Running 不是错误，绝不能因此提前终止。
2. 绝不能提前放弃轮询——在达到 Success、Fail 或 60 次尝试上限之前，不要停止轮询。不要在收到几次 Running 响应后就“放弃”。
3. 绝不能退回手动分析——如果轮询仍在进行或已超时，绝不能尝试通过分析 ListServices 输出、实例元数据或任何其他数据源来手动诊断问题。诊断报告是唯一有效的根因信息来源。
4. 绝不能捏造诊断结果——如果任务尚未达到 Success 状态，绝不能输出任何 summary.overall_status、summary.root_cause 或 summary.suggestions 值。这些字段只能来自已完成的诊断结果。
5. 超时处理——如果轮询 60 次后仍未完成，只输出以下模板并停止：

   ⏳ SysOM 诊断任务超时
   - 任务 ID：<task_id>
   - 当前状态：<status>
   - 建议：请继续等待诊断完成。
   

   超时输出中禁止添加其他建议、手动分析或捏造的结论。

步骤 8 — 解析并输出结果

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

---

成功验证

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

---

清理

此技能中的诊断操作为只读操作，不会修改 PAI 服务 / 作业状态——无需清理。

PAI EAS / DLC 是完全托管的服务——无需安装或卸载 Agent。

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

aliyun configure ai-mode disable

---

命令表

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

---

最佳实践

1. 自动推断产品且不提示用户：根据 instance 前缀确定 product（eas- → EAS，dlc → DLC）——只有当前缀无法识别时才询问用户
2. 必须验证资源：EAS 调用 ListServices 验证资源是否存在；DLC 调用 GetJob 验证资源是否存在，并检查 ResourceType 是否为 Lingjun
3. 在参数中直接使用实例 ID：EAS（eas-m-xxx）和 DLC（dlcxxxxxxxx）实例 ID 均按原样传入 instance 字段——不要转换为 ServiceName
4. 默认使用实时诊断模式：除非用户明确指定时间范围，否则默认使用实时诊断
5. 凭证安全：绝不在对话中打印或回显 AK/SK 值
6. 所有业务 CLI 命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis（version、configure、plugin 等系统命令不使用 --user-agent）
7. 修复建议可能涉及高风险操作：遵循 Human-in-the-loop 协议，并等待用户确认
8. 无需注册或安装 Agent：PAI EAS 和 DLC 是托管服务；SysOM 通过平台侧访问这些服务，而不是通过实例级 Agent 访问

---

不支持的场景

• 非 PAI 产品（ECS 实例请使用 alibabacloud-aes-sysom-os-diagnosis）
• 除 EAS 和 DLC 外的 PAI 产品（例如 DSW、MaxCompute）——当前技能仅支持 EAS / DLC
• 纯配置问题（例如模型版本不匹配、EAS 路由配置——无需进行操作系统级诊断）

---

错误处理

错误场景	CLI 响应	Agent 操作
EAS ServiceId 无效	ListServices 返回空结果	告知用户该区域中不存在此服务 ID，并停止流程
DLC JobId 无效	GetJob 返回未找到	告知用户不存在此 DLC 作业 ID，并停止流程
DLC ResourceType 不是 Lingjun	GetJob 返回非 Lingjun 类型	告知用户 SysOM 仅支持 Lingjun 资源，并停止流程
产品未知 / 前缀不明确	无法根据 instance 推断	明确询问用户选择 EAS 还是 DLC
角色授权失败	initial-sysom 返回错误	提示用户检查 SysOM 服务的开通状态
诊断调用失败	invoke-diagnosis 返回错误	检查凭证、权限和 product 字段是否正确
诊断超时	get-diagnosis-result 轮询超时	输出超时模板，并建议用户稍后重试
权限不足	API 返回 Forbidden	阅读 references/ram-policies.md，并指导用户申请权限

---

参考链接

参考资料	说明
references/cli-installation-guide.md	Aliyun 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	测试验收标准