alibabacloud-sysom-diagnosis

以 SysOM CLI 和后端封装作为诊断的事实来源。此 Skill 将替代旧版 SysOM 诊断 Skill，并成为 SysOM ECS 性能和稳定性诊断的唯一入口。

即时路由

当用户报告症状且尚未提供最新的 SysOM 封装输出时， 应先运行下方 领域路由 中匹配的 SysOM 命令，再进行临时 Linux 检查或手动探查。然后遵循返回的 agent.summary、 agent.findings[].detail/category 和 agent.next_steps[]。原始 Linux 命令 仅在以下情况下作为范围受限的后备手段：SysOM 命令不可用、输出 相互矛盾，或执行定向 SysOM 命令后仍缺少所需实体。

凭证安全

严禁打印、回显或索取 AccessKey ID 或 AccessKey Secret 的值。远程 命令会自行执行身份验证检查。如果命令返回 身份验证或权限错误，请说明该错误，并引导用户参阅 references/ram-policies.md；凭证必须在 对话之外配置。

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

核心工作流

1. 将用户症状归入一个 SysOM 领域：内存、IO、负载/CPU、

网络或 Java（GC/内存/CPU）。

2. 运行与该领域匹配且粒度最小的 SysOM 命令。对于不明确的内存症状，优先使用本地

内存分类；对于其他领域，使用 文档中与之匹配的远程操作。

3. 仅读取默认封装字段：ok、error、command 以及

agent.

4. 构建答案前加载领域参考资料。此步骤为强制要求，

即使 agent.findings 和 agent.next_steps 看起来完整也不得跳过。需要加载哪些参考资料取决于领域：

• Java（任意类型：gc/内存/cpu）→ 首先阅读 references/java/README.md

以进行症状路由和参数校验；然后按类型处理：

• gc: references/java/gc/gc-guide.md
• 内存：references/java/memory/memory-guide.md（然后阅读术语表、包装结构

指南、性能分析操作手册以及 references/java/memory/ 下的决策树）

• cpu: references/java/cpu/cpu-guide.md
• 其他领域 → 从下方参考资料表加载匹配的参考资料。

参考资料补充了仅凭包装结构无法了解的解释规则、实体定义和答案组织 指导。不得根据原始包装结构文本推断 Java 术语、 原生内存类别或性能分析语义。

1. 将每一跳作为可见进度传达：向用户展示 agent.summary（以及关键

发现），并通过 第 4 步加载的参考资料进行解释。保留会改变解释的证据限定条件，包括 当前性、不可用的直接信号、备用证据和修复 前置条件。

2. 根据 agent.status 分支处理：

• concluded（或缺失/无法识别）→ 根据

agent.summary、agent.findings[].detail/category 和 agent.next_steps[] 构建最终答案，然后停止循环。

• in_progress → 后端正在请求另一次采集：从

agent.next_steps[] 中取出 kind=command 条目，应用下方 确认规则，运行命令，并将新的包装结构反馈到 第 4 步。

引导式诊断循环硬性规则（Java 多跳会话）：

• 节奏控制权：绝不能跳过 agent.next_steps[] 自行决定采集，

也绝不能运行包装结构以外的诊断命令。

• 严格按展示内容运行命令——网关已经注入

--session-id；绝不能重写、添加或移除参数。如果命令失败， 应原样传达错误包装结构，不要通过调整参数重试。

• 跳数上限：同一会话达到 4 跳后停止循环，即使

后端仍返回 in_progress；展示目前为止的结论，并说明 证据限制（后端也会在同一上限强制给出结论—— 双重保护）。

• 用户拒绝：如果用户拒绝建议的命令，停止循环，

根据已经收集的证据进行总结，并明确说明由于未运行该跳，哪些 结论仍未得到确认。

执行性能分析或长时间运行的后续命令之前（例如 java analyze --type memory --duration N、任何向目标进程注入 agent 的命令，或预计运行数分钟的任何命令）：

• 告知用户命令的作用、所需时间以及可能对目标进程造成的性能

影响（例如采样带来的 CPU 开销、 注入 agent 带来的额外内存、可能的安全点暂停）。

• 询问用户是否继续。在用户确认之前不得运行命令，

除非用户此前已明确长期授权 自动运行后续操作。

• 命令启动后，告知用户预计等待时间；如果操作仍在进行，

继续向用户同步进度。

只读查询命令（例如 java analyze --type cpu）不适用此规则—— 具体要求请参见各领域指南的执行模型。

当分类操作在 agent.next_steps[] 中返回命令，且尚无根本原因 发现包含足以作答的证据时，接下来运行第一条命令。 不得用手动 shell 探查替换 Agent 可见的 SysOM 后续步骤。原始 Linux 检查只能在 SysOM 后续步骤成功、失败或 超时后，作为范围受限的后备手段。

默认情况下，应严格按文档所示使用命令。不得添加原始、 调试或后端证据扩展标志，除非用户明确要求 查看该视图。

最终答案应说明证据、根本原因、责任方/范围以及运维 操作目标。除非 用户明确要求提供命令，否则不得添加用于验证或修复的 shell 片段。应优先使用“检查依赖关系， 并在变更窗口中禁用或升级发生泄漏的组件”之类的表述，而不是原始的模块、 cgroup、sysctl、缓存释放或进程终止命令。 默认最终答案的步骤中不得包含看似命令的行内片段，例如模块检查/移除、 内存汇总命令、cgroup 文件写入、缓存释放控件、sysctl 更改， 或进程终止命令。

agent 视图必须包含完整的诊断信息。结构化证据属于 后端/UI 视图，不得将其视为默认 Agent 来源，用于获取所需的 实体。

领域路由

| 用户症状 | 初始路由 | |--------------|-------------| | 不明确的内存问题、OOM、高 RSS、文件缓存、共享内存/临时文件系统、内存 cgroup、套接字内存、内核内存 | sysom-osops memory classify | | Java 问题（症状不明确） | 遵循 references/java/README.md 中的症状分诊规则——询问用户具体症状，然后路由到匹配的类型 | | Java GC 暂停/频繁 GC/GC 吞吐量低 | sysom-osops java analyze --type gc | | Java 堆/OOM/堆泄漏/原生内存泄漏 | sysom-osops java analyze --type memory——如果未提供 pid/pod，它会返回候选列表；停止并等待用户选择，然后才能重试 | | Java CPU 热点/线程 CPU 使用率高/火焰图 | sysom-osops java analyze --type cpu --pid <PID> | | 磁盘速度慢、IO 等待时间过高、磁盘延迟、IO 阻塞 | 先运行 sysom-osops io iofsstat；如果概览显示 IO 较慢，再运行 io iodiagnose | | 高负载、运行队列积压、任务因等待 CPU 而卡住 | 根据可见症状选择 sysom-osops load loadtask 或 load delay | | 丢包、重传、网络超时、抖动 | 丢包/丢弃症状使用 sysom-osops net packetdrop；延迟波动使用 net netjitter |

对于命令参数，请阅读 references/deep-actions.md 和 references/parameter-guide.md。对于 OS 和地域支持，请阅读 references/supported-environments.md。这些参考资料属于 Skill 材料； 不要使用远程目标文件工具打开被诊断 主机上的 .claude/skills 路径。 有关 Java 症状到类型的路由，请查阅 references/java/README.md。

内存路由

内存领域与其他所有领域一样，遵循相同的核心工作流和后续操作规则：首先 运行 sysom-osops memory classify，然后从可见输出 或 agent.next_steps[] 中选择下一项操作。如需选择内存深度操作或检查仍缺少哪个 实体，请加载 references/memory-triage.md（与其他领域的 references/non-memory-triage.md 对应）。

注意：与 Java 相关的内存症状（Java 进程中的 OOM、堆泄漏、原生内存泄漏） 通过 sysom-osops java analyze --type memory 路由到 Java 领域，而不是通过 内存分类处理。请参见上方的领域路由表。

根据可见的 SysOM 输出选择下一项内存操作。不得仅根据症状描述推断内存机制。

封装契约

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

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "concluded",
    "session_id": "a1b2c3d4e5f6",
    "summary": "Concise diagnosis summary.",
    "findings": [
      {
        "severity": "high",
        "title": "Short finding title",
        "detail": "Root cause, key entities, and evidence summary.",
        "category": "root_cause"
      }
    ],
    "next_steps": [
      {
        "kind": "command",
        "label": "Run focused deep diagnosis",
        "command": "sysom-osops memory oom",
        "reason": "The missing entity this command can fill."
      }
    ]
  }
}

agent.findings[] 只能包含 severity、title、detail 和 category。PID、cgroup、服务、文件路径、OOM 受害进程、限制值/当前值、残留项、持有者或清理目标等必需实体，必须写入 agent.summary 或 agent.findings[].detail。

引导式诊断会话的字段语义：

• agent.status：in_progress 表示后端诊断 agent 请求

再次采集；concluded 表示诊断已经收敛。将 缺失或无法识别的值视为 concluded。旧版采集器级状态 （success、warning 等）仍可能出现在非 Java 操作中； 继续按以前的方式解释。

• agent.session_id：后端生成的多跳会话标识符。绝不能

生成或修改它；网关已将其注入 command 字符串，因此应逐字运行。

• agent.next_steps[].kind：command = 后端请求的采集命令

（受上方确认规则约束）；info = 用户侧建议—— 应展示但绝不能自动运行；warning = 证据或数据质量注意事项。

后续规则

• 优先选择 category=root_cause，其次选择严重性最高的发现，最后选择

与用户所报告症状最匹配的发现。

• 将 root_cause 视为已满足停止条件，前提是可见的 detail 中包含相应实体，

这些实体应足以解释该症状并确定安全的后续操作。

• 将 agent.next_steps[] 视为有优先级的计划，而非检查清单。
• 仅当另一条 SysOM 命令能够补全已明确指出的缺失实体，或

改变修复方案时，才运行该命令。

• 对于长时间运行的 Java 采集命令——`java analyze --type memory

--duration N (profiling; legacy memory javamem --duration N) and java analyze --type gc in collect 模式（5–10 分钟的 JFR/GC 采集）——等待时间为 分钟级：告知用户，并相应设置工具超时；绝不能 在客户端超时后重新触发同一命令。请参见 references/java/memory/profiling-playbook.md（内存）和 references/java/gc/gc-guide.md`（gc）。

• 保留会影响解读的可见限定信息，例如当前证据与

历史证据、不可用的直接信号、用于 确认当前状态的回退证据，以及修复措施的安全前置条件。

• 当某项发现因直接信号不可用而采用回退证据时，

请在最终回答中同时说明这两方面。不得仅以 回退指标概括结论。

• 在一条有针对性的 SysOM 命令确认根因后，据此作答。不得运行

额外命令来追求报告面面俱到，也不得继续追查先前 分类阶段的异常或观察结果，除非它们涉及同一实体并 暴露出一个已明确指出的证据缺口。

• 不得直接调用仅供后端使用的采集器或私有辅助命令。
• 不得重新检查 PID、cgroup、文件、限制值或事件，如果 SysOM 已在

summary 或 detail 中明确指出这些信息。

• 当 SysOM 深度诊断命令返回 category=root_cause 且所需

实体均可见后，依据该封装结果作答。原始 Linux 检查仅限于 结果相互矛盾、命令错误或实体明显缺失的情况。

• 在最终回答中，不得针对已经确认的实体添加额外的原始 Linux

验证命令。应将修复措施表述为考虑依赖关系的操作目标 和变更窗口计划，除非该封装结果本身提供可执行的安全 后续步骤。

• 最终回答中避免使用可执行的 shell 片段。如果某条命令仅适用于

变更后验证，请指出要重新运行的 SysOM 检查或指标， 而不要使用原始 Linux 命令。

• 这包括用于模块检查/移除的行内命令名称、内存

摘要命令、cgroup 文件写入、缓存释放控制项、sysctl 更改以及 进程终止操作；请用文字描述依赖关系前置条件和运维操作 目标。

• 当当前封装结果无法解释所报告的

症状，且另一个 SysOM 领域指出更有力的根因时，应跨领域切换。

• 诊断期间，不得执行会改变目标

状态的修复命令，例如终止进程、删除文件、更改 sysctl 值或 写入缓存释放控制项。除非 用户明确要求你执行修复，否则应将这些操作作为建议提出。

• 对于非内存类发现，同样遵循以下规则：执行一条有针对性的深度诊断命令，然后

在所需实体可见后作答。

错误处理

| error.code | 处理措施 | |--------------|--------| | Sysom.TargetRequired | 请求用户提供实例 ID 和地域，或说明 ECS 元数据自动检测要求 | | Sysom.FallbackClassify | 展示本地分类结果，并且仅在有针对性的后续步骤可用时继续 | | Sysom.PermissionDenied | 使用 references/ram-policies.md 说明所需的 RAM 权限 | | Sysom.AuthenticationFailure | 请用户在当前会话之外配置凭证 | | Sysom.InvalidParameter | 请用户更正实例、地域或命令参数 | | Sysom.DiagnosisVersionNotSupported | 说明目标实例的诊断组件需要更新 | | Sysom.DiagnosisJsonParseFailed | 仅当用户仍需要同一证据时，重试一次 | | Sysom.PollError | 当仍需要该缺失证据时，对同一项有针对性的操作重试一次 |

参考资料

| 参考资料 | 适用场景 | |-----------|----------| | references/classify-output-guide.md | 读取本地内存分类输出 | | references/memory-triage.md | 选择内存深度诊断操作或检查内存实体是否完整 | | references/non-memory-triage.md | 路由 IO、负载/CPU、网络诊断 | | references/deep-actions.md | 按领域查找 SysOM 命令 | | references/parameter-guide.md | 验证命令参数 | | references/report-interpretation.md | 解读封装结果字段和回答结构 | | references/ram-policies.md | 说明 RAM 权限 | | references/supported-environments.md | 检查 OS、架构和地域支持情况 |

Java 分析参考资料

| 参考资料 | 适用场景 | |-----------|----------| | references/java/README.md | 主要 Java 入口：症状分诊、参数指南、子领域索引 | | references/java/gc/gc-guide.md | 运行或解释 --type gc 结果 | | references/java/cpu/cpu-guide.md | 运行或解释 --type cpu 结果 | | references/java/memory/memory-guide.md | --type memory 解释和发现优先流程入口 | | references/java/memory/glossary.md | Java 内存术语 | | references/java/memory/javamem-envelope-guide.md | 解释 --type memory 包装结构 | | references/java/memory/profiling-playbook.md | --duration 采集前的准备工作和预期行为 | | references/java/memory/decision-tree.md | 在 Java 多跳会话中执行后端 next_steps | | references/java/memory/case-library.md | 案例库和反模式 |