SysOM 巡检（sysom-inspection）

巡检通过 sysom-osops CLI 命令（sysom-osops inspection ecs ...）启动。始终通过 CLI 调用，而非直接调用巡检 OpenAPI。

CLI 安装配置

检查 CLI 是否可用：

command -v sysom-osops

如果缺失则安装：

curl -fsSL --connect-timeout 1000 https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/skill_cli/install.sh | sudo bash

然后只验证二进制：

command -v sysom-osops

如果 CLI 已安装但还没有 inspection 子命令，先运行 sysom-osops update，然后重试。

如果命令因缺少 RAM 权限失败，按 references/ram-policies.md 附加最小权限策略。

快速开始

按意图聚焦巡检（--query）

仅运行 CPU / 负载相关项（关键词映射）

sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "cpu 相关巡检"

组合意图：内存和磁盘

sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "内存和磁盘"

自然语言句子：自动提取意图，匹配丢包项

sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "检查这台机器是否有网络丢包"

如果查询不匹配任何项，自动回退到全量巡检

批量巡检（--scope-type batch，支持自动诊断）

巡检所有指定实例 -> 对最严重的 Top-3 异常实例自动根因诊断 -> LLM 摘要（其余在报告中给出可直接复制的深度诊断命令）

sysom-osops inspection ecs --region cn-shenzhen --scope-type batch --instances i-aaa,i-bbb,i-ccc

地域级巡检（--scope-type all，支持自动诊断）

自动发现该地域所有 ECS 实例（上限 5000）-> Top-3 异常自动诊断

-> LLM 摘要；一条命令完成整个闭环

sysom-osops inspection ecs --region cn-shenzhen --scope-type all

复查现有报告（--report-id）

立即返回而不重新运行（在巡检 next_steps 中自动生成）。

重要：--region 和 --scope-type（或 --instance）必须与原始巡检命令一致，

否则重放会因 MissingParam 错误失败。

sysom-osops inspection ecs --region cn-shenzhen --scope-type all --report-id inspection-82a64d9d-11c5-45b2-a81c-27fc754891e8

调用模式

  • 聚焦巡检： --query "<intent>" 将关键词或提取的意图映射到具体项（CPU / 负载关键词映射、内存 + 磁盘等组合意图、网络丢包检查等自然语言句子）。查询不匹配任何项时自动回退到全量巡检。
  • 批量： --scope-type batch --instances i-aaa,i-bbb,... 巡检所有指定实例，自动诊断最严重的 Top-3 异常实例，并在报告中列出其余实例可直接复制的深度诊断命令。
  • 地域级： --scope-type all 自动发现该地域所有 ECS 实例（上限 5000），然后在一条命令中应用相同的 Top-3 自动诊断和 LLM 摘要。
  • 报告重放： --region <region> --scope-type <scope-type> --report-id <reportId>（或 --region <region> --instance <instanceId> --report-id <reportId>）立即返回现有报告而不重新运行巡检；巡检结果在 next_steps 中自动发出此重放命令——附带原始 --region 和 --scope-type/--instance。

可观测性

  • UA 模板（所有 SDK 请求必需）：
  • AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
  • 本 Skill 中运行时解析形式：AlibabaCloud-Agent-Skills/alibabacloud-alinux-sysom-inspection/<SKILL_SESSION_ID>
  • 统一 session-id 规则：
  • 每会话（一次 CLI 执行）生成一次单一 session-id，必须在所有 API 调用中一致复用，包括 CLI 和 SDK 请求。
  • 生成优先级：外部环境变量 SKILL_SESSION_ID（首选）-> 自动生成兜底 sid-<32 字符十六进制>（uuid4 hex）；无效的注入值回退到生成的 id。
  • 接受格式：[A-Za-z0-9][A-Za-z0-9._:-]{7,127}。
  • 解析后的值导出到进程环境 SKILL_SESSION_ID，使下游调用保持一致。
  • sysom-osops CLI 自动注入 UA 头，并遵循相同的统一 session-id 规则。

执行流程

  • 每次巡检前，CLI 验证 SysOM 激活和权限（InitialSysom、source=skill_hub）；激活和安装提示由 CLI 自身处理。
  • 每次新巡检调用 ROA API POST /api/v1/inspection/createInstanceInspection，带 source=skill_hub；选中项来自 --query 关键词 / 意图映射，查询不匹配任何项时回退到全量巡检。
  • 每种模式运行完整闭环：巡检（指标 + 日志）-> 对检测到的异常自动根因诊断 -> LLM 摘要的中文报告。
  • 自动根因诊断通过 InvokeDiagnosis 触发（向 params 注入 __sysom_diagnosis_source=skill_hub），并通过 GetDiagnosisResult 轮询直到 success / fail / 超时。
  • 批量（--scope-type batch --instances ...）巡检每个指定实例；地域级（--scope-type all）自动发现该地域所有 ECS 实例（上限 5000）。两者都自动诊断最严重的 Top-3 异常实例，并在报告中包含其余实例可直接复制的深度诊断命令。
  • 报告查找使用 ROA API GET /api/v1/inspection/getInspectionReport；CLI 轮询直到报告成功或超时。
  • --region <region> --scope-type <scope-type> --report-id <reportId>（或用 --instance 代替 --scope-type）跳过任务创建，直接获取现有报告；巡检结果在 next_steps 中自动发出此重放命令，包含原始 --region 和 --scope-type/--instance。
  • 不使用本地阈值 / 事件规则配置；异常判定来自服务端巡检报告。

错误处理

当 CLI 调用失败时，按错误文本（Error: <Code>: ...）分类并如下处理，而非盲目重试：

  • 权限（Forbidden.RAM）：说明缺少 sysom:InitialSysom / sysom:InvokeAgentCli，并指引用户到 references/ram-policies.md 获取最小策略；不要重试。
  • 参数（InvalidParameter、无效参数）：识别有问题的参数并引导用户验证实例 id 和地域；不要归因于服务。
  • 限流（Throttling）：告知用户请求被限流并建议稍后重试；不要循环自动重试。
  • 内部错误（InternalError）：诚实报告临时服务故障并建议稍后重试；不要归因于用户输入。
  • 空地域（no ECS instances found）：不是错误。报告该地域没有 ECS 实例并跳过巡检；绝不编造报告。

可扩展性说明

  • 巡检焦点由 --query 控制（关键词 / 意图映射到具体项）；不匹配的查询回退到全量巡检。
  • 用 --scope-type batch --instances ... 做批量巡检，用 --scope-type all 做全地域（上限 5000 实例）；两者都自动诊断最严重的 Top-3 异常。
  • 用 --region <region> --scope-type <scope-type> --report-id <reportId>（或用 --instance 代替 --scope-type）复查现有报告而不重新执行；重放命令自动在巡检 next_steps 中发出，附带原始 --region 和 --scope-type/--instance。
  • 本地 Python CLI（./scripts/osops.sh inspection）仅作为 sysom-osops 不可用环境的兜底保留。
  • 兜底路径的内存异常触发逻辑仍实现在 scripts/sysom_cli/inspection/command.py。
  • 要添加更多巡检后的专项诊断动作，复用 InvokeDiagnosis 集成模式。