alibabacloud-sysom-diagnosis

以 SysOM CLI 和后端信封（envelope）作为诊断事实来源。本 Skill 取代旧版 SysOM 诊断 Skill，是 SysOM ECS 性能与稳定性诊断的统一入口。

即时路由（Immediate Route）

当用户报告症状但尚未提供新鲜的 SysOM 信封输出时，在执行临时 Linux 检查或手动探测前，应先从下方领域路由（Domain Routing）中运行匹配的 SysOM 命令。随后依据返回的 agent.summary、agent.findings[].detail/category 和 agent.next_steps[] 继续操作。仅当 SysOM 命令不可用、输出相互矛盾，或在执行聚焦式 SysOM 命令后仍缺失关键实体时，才将原始 Linux 命令作为有边界的兜底方案。

凭证安全（Credential Security）

切勿打印、回显或索要 AccessKey ID 或 AccessKey Secret 的值。远程命令自行完成身份验证检查。若某命令返回身份验证或权限错误，请向用户解释该错误，并指引其查阅 references/ram-policies.md；凭证配置必须在当前会话之外完成。

CLI 安装配置（CLI Setup）

检查 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

核心工作流（Core Workflow）

1. 将用户报告的症状归类至一个 SysOM 领域：内存、IO、负载/CPU、网络或 Java 内存。
2. 运行匹配该领域的最小 SysOM 命令。对症状不明确的内存问题，优先使用本地 memory classify；其余领域则采用文档中明确对应的远程操作。
3. 仅读取默认信封字段：ok、error、command 和 agent。
4. 答案需基于 agent.summary、agent.findings[].detail、agent.findings[].category 和 agent.next_steps[] 构建。保留影响结论解读的证据限定条件，包括时效性、直接信号不可用、兜底证据、以及修复操作的前提条件。
5. 若根因、关键实体、证据强度及安全的下一步操作均已清晰可见，则立即作答并终止流程。仅当存在缺失实体，或命令明确建议时，才执行一次有针对性的后续操作。

当 classify 在 agent.next_steps[] 中返回一条命令，且尚无根因发现（root-cause finding）包含足够证据支持作答时，应立即执行该命令。不得以人工 Shell 探测替代 Agent 可见的 SysOM 下一步操作。原始 Linux 检查仅在 SysOM 下一步操作成功、失败或超时后，作为有边界的兜底方案使用。

默认情况下，须严格按文档所示方式使用已定义命令。除非用户明确要求查看调试视图，否则不得添加原始（raw）、调试（debug）或后端证据展开（backend evidence expansion）类参数标志。

最终回答应明确指出：所依据的证据、根因、责任方/作用范围（owner/scope）及运维操作目标。除非用户明确要求提供命令，否则不得附加用于验证或修复的 Shell 片段。应优先采用如下表述方式：“在变更窗口内审查依赖项，并禁用或升级泄漏组件”，而非直接给出模块、cgroup、sysctl、清缓存（cache-drop）或进程终止（process-kill）等原始命令。 默认最终答案步骤中，不得包含形如模块检查/卸载、内存摘要命令、cgroup 文件写入、缓存清除控制、sysctl 修改或进程终止等类命令的内联片段。

agent 视图必须自包含（self-contained），满足完整诊断需求。结构化证据属于后端/UI 展示视角，不得作为 Agent 默认所需实体的事实来源。

领域路由（Domain Routing）

关于命令参数，请参阅 references/deep-actions.md 和 references/parameter-guide.md。关于操作系统与地域支持情况，请参阅 references/supported-environments.md。上述参考文档属于本 Skill 的组成部分；请勿使用远程目标文件工具在被诊断主机上打开 .claude/skills 路径下的文件。

内存路由（Memory Routing）

内存诊断遵循与其他所有领域一致的核心工作流与后续操作规则：始终从 sysom-osops memory classify 启动，然后依据可见输出或 agent.next_steps[] 选择下一步操作。如需在多个内存深度操作间进行选择，或确认仍有哪个实体缺失，请加载 references/memory-triage.md（其他领域对应参考文档为 references/non-memory-triage.md）。

下一步内存操作应完全依据可见的 SysOM 输出决定，不得仅凭症状描述文字推断内存机制。

信封契约（Envelope Contract）

默认命令输出即为 Agent 契约：

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "warning",
    "summary": "简明诊断摘要。",
    "findings": [
      {
        "severity": "high",
        "title": "简短发现标题",
        "detail": "根因、关键实体及证据摘要。",
        "category": "root_cause"
      }
    ],
    "next_steps": [
      {
        "kind": "command",
        "label": "执行聚焦式深度诊断",
        "command": "sysom-osops memory oom",
        "reason": "此命令可补全的缺失实体。"
      }
    ]
  }
}

agent.findings[] 中仅允许包含 severity、title、detail 和 category 字段。PID、cgroup、服务名、文件路径、OOM 受害者、限制值/当前值、残留物、持有者或清理目标等必需实体，必须明确写入 agent.summary 或 agent.findings[].detail 中。

后续操作规则（Follow-up Rules）

• 优先选择 category=root_cause 的发现；其次按严重性由高到低排序；最后选择最贴合用户所报症状的发现。
• 当 root_cause 发现的 detail 中已包含解释症状所需的全部实体及安全的下一步操作时，即可视为可终止诊断。
• agent.next_steps[] 应视为优先级计划，而非待办清单。
• 仅当新 SysOM 命令能补全某个已命名的缺失实体，或改变修复策略时，才执行该命令。
• 保留所有影响解读的可见限定条件，例如：当前证据 vs 历史证据、直接信号不可用、用于弥补时效性缺口的兜底证据、以及修复操作的安全前提条件。
• 若某发现因直接信号不可用而采用兜底证据，则最终回答中必须同时陈述两部分，不得仅以兜底指标为唯一结论依据。
• 当某聚焦式 SysOM 命令已闭环根因时，应据此作答。无需额外运行命令以追求报告完备性；除非共享同一实体且暴露出明确的证据缺口，否则不应追溯早期 classify 阶段的异常或观察项。
• 禁止直接调用仅限后端使用的采集器或私有辅助命令。
• 不得重新检查 SysOM 已在 summary 或 detail 中明确指出的 PID、cgroup、文件、限制值或事件。
• 当 SysOM 深度命令返回 category=root_cause 且所需实体均已可见时，应直接依据该信封作答。原始 Linux 检查仅用于处理矛盾输出、命令报错或明显缺失实体的情形。
• 最终回答中，不得将已闭环的实体转化为额外的原始 Linux 验证命令。修复操作应以“依赖感知型动作目标 + 变更窗口计划”的形式表达，除非信封本身已提供可安全执行的下一步操作。
• 最终答案中应避免可执行的 Shell 片段。若某命令仅适用于变更后的验证环节，应指明需复用的 SysOM 检查项或指标，而非原始 Linux 命令。
• 该原则同样适用于模块检查/卸载、内存摘要命令、cgroup 文件写入、缓存清除控制、sysctl 修改、进程终止等内联命令名称；应在正文中以自然语言描述其依赖关卡与运维动作目标。
• 当当前信封无法解释用户报告的症状，而另一 SysOM 领域却指出了更强的根因时，应跨领域切换诊断方向。
• 诊断过程中，禁止执行任何会改变目标系统状态的修复命令，例如终止进程、删除文件、修改 sysctl 值或写入缓存清除控制接口。此类操作仅可作为建议提出，除非用户明确要求你执行修复。
• 对于非内存类发现，同样适用该规则：执行一次聚焦式深度命令，待所需实体可见后即作答。

错误处理（Error Handling）

参考文档（References）