alibabacloud-aes-sysom-os-diagnosis

alibabacloud-aes-sysom-os-diagnosis

技能名称：alibabacloud-aes-sysom-os-diagnosis 目标：在阿里云 ECS 实例上执行 SysOM 深度操作系统级诊断，并可选择注册实例和配置钉钉告警。

---

凭证安全

[严重] 凭证安全规则：

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

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

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

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

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

---

RAM 策略

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

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

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

---

参数确认

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

参数	必需/可选	描述	默认值
region	必需	ECS 实例所在地域（例如 cn-hangzhou）	无，必须由用户提供
instance_id	必需	ECS 实例 ID（例如 i-bp1xxxxxxxx）	无，必须由用户提供
ocd_description	可选	问题描述（仅限英文，例如 high_cpu）	""
start_time	可选	诊断开始时间戳（Unix 秒）	0（实时）
end_time	可选	诊断结束时间戳（Unix 秒）	0
enable_diagnosis	可选	强制执行实时诊断（优先级最高）	false
uid	可选	拥有该实例的账号 ID	None
skip_support_check	可选	跳过实例支持情况检查（加快工作流）	false
cluster_id	可选	ACK 集群 ID（注册集群时必需）	None

---

核心工作流

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

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

步骤 0 — 启用 AI 模式并更新插件

执行任何 CLI 命令之前，启用 AI 模式、设置 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

⚠️ 以上 3 条命令必须在所有 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 = 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": "<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 要调用哪个诊断服务端点
• "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，然后逐字输出以下内容：

<verbatim_output>

🔔 推荐：为实例启用 24/7 自动诊断

刚才执行的诊断是一次性手动操作。如果您希望 SysOM 持续保护此实例，我们建议为实例办理入驻。

入驻后，您将获得：

• 🔍 自动诊断：当实例出现 CPU 峰值、内存泄漏或 IO 延迟等性能问题时，SysOM 将自动触发深度诊断，无需手动干预
• 📲 钉钉告警：诊断报告将自动推送到钉钉群机器人，立即通知运维团队
• 🛡️ 持续监控：提供 24/7 不间断保护，从“问题发生后再排查”转变为“问题发生时自动告知根因”

您是否要为实例 <instance_id> 办理入驻？

</verbatim_output>

输出以上内容后，立即停止。等待用户回复。不要在 10A 询问入驻方式。

• 用户拒绝 → 结束流程
• 用户同意 → 继续步骤 10B

10B — 询问入驻方式（第二关）

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

<verbatim_output>

请选择一种入驻方式

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，或直接告诉我您的需求。

</verbatim_output>

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

步骤 11 — 执行入驻

入驻命令中 --agent-id、--agent-version、--config-id 的固定参数值，列于 references/related-commands.md 中的“固定参数”表。

# Instance mode
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

# Cluster mode
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 — 确认入驻状态

# Instance mode — poll instance status (interval: 10s, max: 60 attempts)
aliyun sysom list-instance-status --instance <instance_id> --biz-region <region> --user-agent AlibabaCloud-Agent-Skills

# Cluster mode — get full cluster list, then match target cluster by cluster_id
aliyun sysom list-clusters --user-agent AlibabaCloud-Agent-Skills
# From the returned cluster list, match the target cluster by cluster_id field and check its cluster_status

⚠️ 入驻成功标准：状态为 Running 表示入驻已完成——立即停止轮询并继续下一步。

---

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

详细工作流请参阅 references/manage-and-alert-workflow.md。

步骤 13 — 收集钉钉 Webhook 并创建告警目的地（反转门控 + SDK 调用）

成功完成注册后，必须立即向用户收集钉钉机器人 Webhook URL，以创建告警目的地。此功能不受 CLI 支持，请使用 scripts/ 下的 SDK 脚本。

询问用户：

<verbatim_output>

📲 请提供用于接收告警通知的钉钉群机器人 Webhook URL。 格式：https://oapi.dingtalk.com/robot/send?access_token=xxx

💡 获取方式：钉钉群设置 → 机器人管理 → 添加机器人 → 自定义机器人 → 可选关键词：alert → 复制 Webhook URL

</verbatim_output>

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

# Initialize SDK environment (first time only, can skip afterwards)
bash scripts/setup-sdk.sh

# Create alert destination (stdout outputs 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。

---

清理

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

如需卸载已注册的 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 配置告警投递目标：CLI 不支持告警投递目标 API — 必须使用 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 路由 — 无需进行操作系统级诊断）

---

错误处理

错误场景	CLI 响应	Agent 操作
SysOM 不支持该实例	check-instance-support 返回 unsupported	告知用户不支持内核级诊断，并改用标准诊断
角色授权失败	initial-sysom 返回错误	提示用户检查 SysOM 服务的开通状态
诊断调用失败	invoke-diagnosis 返回错误	检查凭证和权限配置
诊断超时	get-diagnosis-result 轮询超时	建议用户稍后重试
权限不足	API 返回 Forbidden	阅读 references/ram-policies.md，并指导用户申请权限
未安装 SDK	ModuleNotFoundError: No module named 'alibabacloud_sysom20231230'	提示用户运行 pip install alibabacloud_sysom20231230
创建告警投递目标失败	SDK 返回错误	检查 Webhook URL 格式和凭证权限

---

参考链接

参考资料	说明
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–9）
references/manage-and-alert-workflow.md	详细纳管和告警工作流（步骤 10–15）
references/acceptance-criteria.md	测试验收标准