alibabacloud-aes-sysom-os-diagnosis：基于阿里云SysOM平台，对 ECS Linux 实例进行操作系统内核级深度诊断。可分析 CPU 飙高、内存泄漏、IO 延迟、网络丢包、宕机等性能问题根因分析，支持实例纳管（7×24 持续监控）和自动诊断和自动钉群机器人告警通知。

alibabacloud-aes-sysom-os-diagnosis

Skill 名称：alibabacloud-aes-sysom-os-diagnosis
目标：对阿里云 ECS 实例执行 SysOM 深度操作系统级诊断，可选实例纳管和钉钉告警配置。

凭证安全

[关键] 凭证安全规则：
- 绝不在对话或命令输出中打印、回显或显示 AccessKey ID / AccessKey Secret 值（即使部分掩码 LTAI_ACCESS_KEY_ID 也禁止）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list --user-agent AlibabaCloud-Agent-Skills
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list --user-agent AlibabaCloud-Agent-Skills 显示有效 profile 后返回并重新运行

RAM 策略

本 Skill 所需 RAM 权限完整列表见 references/ram-policies.md。

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

参数确认

重要：参数确认 —— 在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、实例名、CIDR 块、
密码、域名、资源规格等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

核心工作流

工作流有四个阶段共 14 个步骤。所有 aliyun CLI 命令必须包含 --user-agent AlibabaCloud-Agent-Skills。

阶段 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-os-diagnosis"
aliyun plugin update

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

步骤 1 —— CLI 版本检查

aliyun version --user-agent AlibabaCloud-Agent-Skills

验证版本 >= 3.3.1。如果不满足，参阅 references/cli-installation-guide.md 获取安装说明。

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

aliyun configure set --auto-plugin-install true --user-agent AlibabaCloud-Agent-Skills

步骤 3 —— 凭证验证

aliyun configure list --user-agent AlibabaCloud-Agent-Skills

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

阶段 2：诊断执行（步骤 4-9）

详细工作流见 references/diagnose-workflow.md。

步骤 4 —— 模糊问题澄清（倒置门禁）

必须确认 region 和 instance_id。如果用户未提供，明确询问。同时提取可选 ocd_description（必须翻译为英文）、时间范围等。

⚠️ 时间推断规则：当用户描述包含任何时间引用（例如“今天早上”、“昨天下午”、“大约下午 3 点”、“昨晚”）时，你必须主动询问具体时间范围并推荐历史诊断模式。当问题明显发生在过去时，不要静默默认实时诊断。

步骤 5 —— 云助手在线检查

aliyun ecs describe-cloud-assistant-status --biz-region-id <region> --instance-id <instance_id> --user-agent AlibabaCloud-Agent-Skills

检查响应中 CloudAssistantStatus 是否为 true。如果离线，终止流水线。

步骤 6 —— SysOM 角色初始化

aliyun sysom initial-sysom --check-only false --source aes-skills --user-agent AlibabaCloud-Agent-Skills

步骤 7 —— 实例支持检查

aliyun sysom check-instance-support --instances <instance_id> --biz-region <region> --user-agent AlibabaCloud-Agent-Skills

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

#### 诊断模式决策规则

if enable_diagnosis == true:
    mode = 实时诊断    # enable_diagnosis 最高优先级
elif start_time != 0:
    mode = 历史诊断    # 指定了时间范围，回溯分析
else:
    mode = 实时诊断    # 默认

• 实时：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": "<instance_id>",
  "region": "<region>",
  "start_time": 0,
  "end_time": 0,
  "type": "ocd",
  "ai_roadmap": true,
  "enable_sysom_link": false
}

⚠️ 防混淆警告："type": "ocd" 是 params JSON 中的必需字段——不要省略！
--service-name ocd（CLI 参数）和 "type": "ocd"（params JSON 字段）是两个不同层级的参数，两者都是强制的：
- --service-name ocd → 告诉 CLI 调用哪个诊断服务 endpoint
- "type": "ocd" → 告诉诊断引擎内部执行哪种诊断类型
不要因为 --service-name 已指定 ocd 就从 params 中省略 "type": "ocd"！

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

• ocd_description：英文问题描述（例如 high_cpu）
• uid：拥有实例的账号 ID（整数）

#### 调用诊断

aliyun sysom invoke-diagnosis \
  --service-name ocd \
  --channel ecs \
  --params '{"instance":"<instance_id>","region":"<region>","start_time":<start_time>,"end_time":<end_time>,"type":"ocd","ai_roadmap":true,"enable_sysom_link":false,"ocd_description":"<ocd_description>"}' \
  --user-agent AlibabaCloud-Agent-Skills

从响应中提取 task_id。如果返回 Sysom.TaskInProgress 错误，从错误消息中提取现有 task_id 并进入轮询。

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

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

步骤 9 —— 结果解析与输出

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

阶段 3：纳管推荐（步骤 10-12）

详细工作流见 references/manage-and-alert-workflow.md。

步骤 10 —— 纳管推荐与意图收集（倒置双门禁）

此步骤包含两个严格分离的门禁，必须按顺序执行——禁止合并、跳过或简化。

10A —— 突出纳管推荐（第一门禁）

⚠️ 强制规则：展示诊断结果后，你必须立即逐字输出以下推荐内容。不要缩写、省略或用你自己的话改写。

将 <instance_id> 替换为实际实例 ID，然后逐字输出以下内容：

<逐字输出>

## 🔔 推荐：纳管实例以启用 7×24 自动化诊断
刚才执行的诊断是一次性手动操作。如果你希望 SysOM 持续保护此实例，我们推荐实例纳管。
### 纳管后，你将获得：
- 🔍 自动化诊断：当实例出现 CPU 飙高、内存泄漏或 IO 延迟等性能问题时，SysOM 将自动触发深度诊断，无需人工干预
- 📲 钉钉告警：诊断报告将自动推送到钉钉群机器人，立即通知运维团队
- 🛡️ 持续监控：7×24 不间断保护，从“问题发生后排查”转变为“问题发生时自动告知根因”
是否纳管实例 <instance_id>？

</逐字输出>

输出上述内容后，停止。等待用户回复。10A 中不要询问纳管方式。

• 用户拒绝 → 结束流水线
• 用户同意 → 进入步骤 10B

10B —— 询问纳管方式（第二门禁）

只有在用户在 10A 中明确同意后，才输出以下内容（将 <instance_id> 和 <region> 替换为实际值）：

<逐字输出>

### 请选择纳管方式
A. 仅纳管当前实例
仅纳管刚诊断的实例：<instance_id>（<region>）
B. 纳管 ACK 集群
如果此实例属于 ACK 集群，你可以一键纳管集群中的所有节点。
新添加的节点将自动纳管——无需手动操作。
👉 请提供 ACK 集群 ID（例如 c9d7f3fc3d42********c1100ffb19d）
C. 纳管多个指定实例
批量纳管多个实例。
👉 请以 InstanceID:Region 格式提供实例列表，用空格分隔
示例：i-xxx:cn-beijing i-yyy:cn-hangzhou
请选择 A / B / C，或直接告诉我你的需求。

</逐字输出>

输出上述内容后，停止。等待用户回复。

步骤 11 —— 执行纳管

纳管命令中 --agent-id、--agent-version、--config-id 的固定参数值列在 references/related-commands.md 的“Fixed Parameters”表中。

实例模式

aliyun sysom install-agent \

--instances instance=<instance_id> region=<region> \

--install-type InstallAndUpgrade \

--agent-id <agent-id> \

--agent-version <agent-version> \

--user-agent AlibabaCloud-Agent-Skills

集群模式

aliyun sysom install-agent-for-cluster \

--cluster-id <cluster_id> \

--agent-id <agent-id> \

--agent-version <agent-version> \

--config-id <config-id> \

--user-agent AlibabaCloud-Agent-Skills

**步骤 12 —— 纳管状态确认**

实例模式——轮询实例状态（间隔：10 秒，最多：60 次尝试）

aliyun sysom list-instance-status --instance <instance_id> --biz-region <region> --user-agent AlibabaCloud-Agent-Skills

集群模式——获取完整集群列表，然后按 cluster_id 匹配目标集群

aliyun sysom list-clusters --user-agent AlibabaCloud-Agent-Skills

从返回的集群列表中，按 cluster_id 字段匹配目标集群并检查其 cluster_status

> **⚠️ 纳管成功标准：状态 `Running` 表示纳管完成——立即停止轮询并进入下一步。**

---

### 阶段 4：告警配置（步骤 13-15）

详细工作流见 [references/manage-and-alert-workflow.md](references/manage-and-alert-workflow.md)。

**步骤 13 —— 收集钉钉 Webhook 并创建告警目的地（倒置门禁 + SDK 调用）**

纳管成功后，你**必须立即从用户处收集钉钉机器人 Webhook URL** 以创建告警目的地。此功能 CLI **不支持**——使用 `scripts/` 下的 SDK 脚本。

询问用户：

<逐字输出>

> 📲 请提供用于接收告警通知的钉钉群机器人 **Webhook URL**。
> 格式：`https://oapi.dingtalk.com/robot/send?access_token=xxx`
>
> 💡 如何获取：钉钉群设置 → 机器人管理 → 添加机器人 → 自定义机器人 → 可选关键词：alert → 复制 Webhook URL

</逐字输出>

用户提供 Webhook 后，初始化 SDK 环境并创建告警目的地：

初始化 SDK 环境（仅首次，之后可跳过）

bash scripts/setup-sdk.sh

创建告警目的地（stdout 输出 destination_id）

.sysom-sdk-venv/bin/python scripts/create-alert-destination.py '<user-provided-webhook-url>'

> **⚠️ 你必须使用 `.sysom-sdk-venv/bin/python` 执行脚本**——禁止使用系统 `python3`（签名算法依赖特定 SDK 版本）。

成功时，stdout 输出 `destination_id`（纯数字）。记录此值供步骤 15 使用。

**步骤 14 —— 告警项选择（倒置门禁）**

aliyun sysom list-alert-items --user-agent AlibabaCloud-Agent-Skills

展示告警项列表（按 NODE/POD 分类），支持快速选择（`all`、`node-all`、`pod-all`）和编号选择。

**步骤 15 —— 创建告警策略（SDK 调用）**

用户选择告警项后，**直接创建告警策略**，`destinations` 设置为步骤 13 的目的地 ID。

> **⚠️ CLI 不支持 `destinations` 参数——你必须使用 SDK 脚本创建告警策略。**

.sysom-sdk-venv/bin/python scripts/create-alert-strategy.py \

--name "aliyun-aes-skills-create-<YYYYMMDDHHmm>" \

--items "<alert_item_1>,<alert_item_2>" \

--clusters "<clusters_value>" \

--destinations "<destination_id>"

- 实例模式 → `--clusters` 值为 `default`
- 集群模式 → `--clusters` 值为 `<cluster_name>`（注意：名称，**不是** ID）
- `--destinations` → 步骤 13 的目的地 ID（多个 ID 逗号分隔，例如 `1,2`）
- `--items` → 告警项名称逗号分隔

> **⚠️ 你必须使用 `.sysom-sdk-venv/bin/python` 执行脚本**——禁止使用系统 `python3`。

---

成功验证

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

清理

本 Skill 中的诊断操作是只读的，不修改实例状态——无需清理。

要卸载已纳管的 Agent，使用 aliyun sysom uninstall-agent（参数见 references/related-commands.md）。

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

aliyun configure ai-mode disable

命令表

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

最佳实践

1. 诊断前检查云助手状态：SysOM 诊断依赖云助手在线——始终在步骤 5 中确认
2. 使用实时诊断模式：除非用户明确指定时间范围，否则默认实时诊断
3. ocd_description 使用英文关键词：API 仅支持 [a-zA-Z0-9_.~-] 字符
4. 纳管推荐使用双门禁：先推荐，再询问方式——避免信息过载
5. 集群纳管批量限制：超过 50 个实例时，首批仅安装 50 个；其余自动安装
6. 告警策略的 clusters 参数：实例模式用 default，集群模式用集群名称（不是 ID）
7. 告警目的地通过 SDK：告警目的地 API 不支持 CLI——必须使用 Python SDK（alibabacloud_sysom20231230）
8. 告警策略的 destinations 参数：创建告警目的地后，在 create-alert-strategy 中包含 destinations（目的地 ID 列表）——告警将通过 SysOM 推送到钉钉
9. 凭证安全：绝不在对话中打印或回显 AK/SK 值
10. 所有 CLI 命令必须包含 --user-agent AlibabaCloud-Agent-Skills
11. 修复建议可能涉及高风险操作：遵循 Human-in-the-loop 协议并等待用户确认

不支持的场景

• 非 Linux 实例（不支持 Windows 实例）
• 内核版本不兼容的实例（通过 check-instance-support 检查）
• 纯配置问题（例如安全组规则、VPC 路由——不需要操作系统级诊断）

错误处理

参考链接

文档 2 / 7：alibabacloud-esa-pages-deploy