alibabacloud-sysom-diagnosis

alibabacloud-sysom-diagnosis

使用 SysOM CLI 和后端封套作为诊断事实来源。此 Skill 取代旧版 SysOM 诊断 Skill，是 SysOM ECS 性能与稳定性诊断的唯一入口。

立即路由

当用户报告症状但未提供最新的 SysOM 封套输出时，在进行临时 Linux 检查或手动探测之前，先运行下方领域路由中的相应 SysOM 命令。然后根据返回的 agent.summary、agent.findings[].detail/category 和 agent.next_steps[] 继续操作。只有在 SysOM 命令不可用、输出相互矛盾，或运行针对性 SysOM 命令后仍缺少必需实体时，才可将原始 Linux 命令作为有限的备用方案。

凭证安全

绝不要打印、回显或询问 AccessKey ID 或 AccessKey Secret 的值。远程命令会自行检查身份验证。如果命令返回身份验证或权限错误，请说明错误，并引导用户查看 references/ram-policies.md；必须在对话之外设置凭证。

CLI 设置

检查 CLI 是否可用：

command -v sysom-osops

如果缺少 CLI，请安装。安装程序可在 Linux 或 macOS 上运行，不能在 Windows 上运行。被诊断的目标 ECS 必须运行 Linux（参见 references/supported-environments.md），但控制主机可以运行任一操作系统。

系统范围安装（需要对 /usr/local/bin 有写入权限，通常通过 sudo 获取）：

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

用户本地安装——无需 sudo，也不使用归 root 所有的路径。适用于 Linux 和 macOS；如果没有管理员权限，推荐使用此方式：

mkdir -p ~/.local/bin
curl -fsSL --connect-timeout 1000 https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/skill_cli/install.sh \
  | bash -s -- -d "$HOME/.local/bin"

然后确保安装目录位于 PATH 中（例如 ~/.bashrc / ~/.zshrc）：

export PATH="$HOME/.local/bin:$PATH"

然后仅验证二进制文件：

command -v sysom-osops

在 macOS 上，安装程序会自动执行临时 codesign，并移除隔离属性。如果你使用 Apple Silicon，并在 Rosetta 下运行 x86_64 shell，安装程序会检测到不匹配；只有确认二进制文件能在转译模式下运行时，才可传入 -f 强制覆盖。

命令可见性取决于凭证

只有 memory classify 等本地命令始终可用。所有远程深度命令都会在运行时从 SysOM 技能目录中发现，这需要凭证。在未配置凭证的机器上，预期会出现以下情况：

• sysom-osops memory --help 仅列出 classify，不显示深度内存命令。
• 顶层 sysom-osops --help 完全不显示 io、net 和 load 组。

这是可见性限制，而非能力限制。请将 references/deep-actions.md 视为此 Skill 的权威命令清单，绝不要根据 --help 输出推断某个领域或命令不受支持。使用 sysom-osops precheck 报告身份验证状态。

核心工作流

1. 将用户的症状归类到一个 SysOM 领域：memory、IO、load/CPU、network 或 Java（GC/memory/CPU）。
2. 运行与该领域匹配的最小 SysOM 命令。对于不明确的内存症状，优先使用本地 memory classify；对于其他领域，使用对应的文档化远程操作。
3. 只读取默认信封字段：ok、error、command 和 agent。
4. 构建回答前，先加载领域参考资料。 此步骤为必需步骤，即使 agent.findings 和 agent.next_steps 看似完整，也不得跳过。要加载哪些参考资料取决于领域：
   • Java（任何类型：gc/memory/cpu）→ 首先阅读 references/java/README.md，了解症状路由和参数验证；然后按类型阅读：
     • gc：references/java/gc/gc-guide.md
     • memory：references/java/memory/memory-guide.md（然后阅读 references/java/memory/ 下的 glossary、envelope guide、profiling playbook、decision tree）
     • cpu：references/java/cpu/cpu-guide.md
   • 其他领域 → 加载下方 References 表格中对应的参考资料。 参考资料提供信封本身无法传达的解读规则、实体定义和回答组织指导。不得根据原始信封文本推断 Java 术语、原生内存类别或性能分析语义。
5. 将该轮过程作为可见进度反馈给用户：向用户呈现 agent.summary（以及关键发现），并结合第 4 步加载的参考资料进行解读。保留会影响解读的证据限定条件，包括时效性、直接信号不可用、回退证据以及修复措施的前置条件。
6. 根据 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；不得改写、添加或删除标志。如果命令失败，应原样反馈错误信封，不要调整参数后重试。
• 轮数上限：即使后端仍返回 in_progress，同一会话中达到 4 轮后也必须停止循环；呈现目前得出的结论，并说明证据限制（后端也会在相同上限强制结束，以提供双重保障）。
• 用户拒绝：如果用户拒绝建议执行的命令，应停止循环，根据已收集的证据进行总结，并明确说明由于未运行该轮采集，哪些结论仍未得到确认。

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

• 告知用户该命令的作用、运行时长，以及它可能对目标进程造成的性能影响（例如采样产生的 CPU 开销、注入 Agent 占用的额外内存、潜在的安全点暂停）。
• 询问用户是否继续。除非用户确认，或此前已明确要求自动运行后续命令，否则不得运行该命令。
• 命令开始运行后，告知用户预计等待时间；如果操作仍在进行，应持续向用户更新进度。

只读查询命令（例如 java analyze --type cpu）不适用此规定——具体说明请参见各领域指南中的 Execution Model。 当 agent.next_steps[] 中的 classify 返回命令，且没有任何根因发现已包含足够证据来回答时，下一步运行第一个命令。 不要用手动 shell 探查替代 Agent 可见的 SysOM 下一步操作。只有在 SysOM 下一步操作成功、失败或超时后，才可将原始 Linux 检查作为有限的后备方案。

默认严格按照文档所示运行命令。除非用户明确要求查看此类信息，否则不要添加原始、调试或后端证据扩展标志。

最终回答应说明证据、根因、负责人/范围以及运维操作目标。除非用户明确要求提供命令，否则不要添加用于验证或修复的 shell 代码片段。优先使用“在变更窗口内检查依赖项，并禁用或升级存在泄漏的组件”等表述，而不是原始模块、cgroup、sysctl、清理缓存或终止进程的命令。 默认情况下，不要在最终回答的步骤中加入看起来像命令的内联片段，例如检查/卸载模块、内存摘要命令、写入 cgroup 文件、清理缓存控制项、sysctl 更改或终止进程的命令。

agent 视图必须能够独立完成诊断。结构化证据属于后端/UI 视图，不得将其视为 Agent 获取必需实体的默认来源。

领域路由

用户症状	首选路由
内存问题不明确、OOM、RSS 偏高、文件缓存、shmem/tmpfs、内存 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>
磁盘缓慢、iowait 偏高、磁盘延迟、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 领域，而不是通过内存 classify 路由。请参阅上方的领域路由表。

根据可见的 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，然后选择严重程度最高的发现，最后选择与用户报告症状最匹配的发现。
• 当可见的 detail 包含解释症状和提出安全后续操作所需的实体时，将 root_cause 视为已足以停止排查。
• 将 agent.next_steps[] 视为优先级计划，而非检查清单。
• 只有当另一个 SysOM 命令能够补齐明确缺失的实体或改变修复方案时，才运行该命令。
• 对于长时间运行的 Java 收集命令——java analyze --type memory --duration N（分析；旧版命令为 memory javamem --duration N）以及处于 collect 模式的 java analyze --type gc（需要 5–10 分钟的 JFR/GC 收集）——等待时间以分钟计：告知用户，适当设置工具超时时间，并且客户端超时后绝不要重新执行相同命令。参见 references/java/memory/profiling-playbook.md（memory）和 references/java/gc/gc-guide.md（gc）。
• 保留会影响解释的可见限定条件，例如当前证据与历史证据的区别、直接信号不可用、用于确认当前状态的备用证据，以及修复的安全前提。
• 当发现因直接信号不可用而使用备用证据时，在最终答复中说明这两点。不要将结论简化为仅提及备用指标。
• 有针对性的 SysOM 命令确认根因后，依据该结果作答。不要为了让报告更全面而运行额外命令；除非先前的分类异常或观察与同一实体相关且揭示了明确的证据缺口，否则不要继续追查。
• 不要直接调用仅供后端使用的数据收集器或私有辅助命令。
• 不要重新检查 SysOM 已在 summary 或 detail 中指出的 PID、cgroup、文件、限制或事件。
• 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	当仍需要缺失的证据时，针对同一明确操作重试一次

空输出不是封套

命令可能以非零状态退出，且完全没有 stdout 和 stderr。这不是封套，因此不要解析它——将空输出解析为 JSON 会失败。最主要的原因是不支持的标志：CLI 会在生成任何封套之前拒绝未定义的标志，目前也不会显示错误消息。

当命令没有产生任何输出时：

1. 不要原样重试同一命令，也不要报告诊断结果。
2. 对照 references/parameter-guide.md 检查传入的标志，并使用 sysom-osops <group> <command> --help 确认。请注意，io、load 和 net 命令只接受 --region、--instance 和 --scope。
3. 移除不受支持的标志后重跑一次。
4. 如果输出仍为空，请告知用户命令失败且没有可诊断的错误，列出使用的命令和标志，并按 Sysom.InvalidParameter 处理，不要编造诊断结果。

帮助文本不是封套

域子命令可能是缺失，而非损坏。远程深度诊断命令会在运行时从 SysOM 技能目录中发现，这需要凭证。缺少凭证时，目录无法访问，子命令不会注册，CLI 会退回到打印域组的帮助文本——且退出代码为 0。

如果输出以 Commands under "<domain>" are discovered at runtime 开头，应将其视为命令缺失，绝不能视为诊断结果：

1. 不要将其解析为封套，也不要报告“未发现问题”。此处退出代码为 0 表示命令根本没有运行。
2. 不要据此认定该域不受支持，或此 Skill 仅提供 memory classify。
3. 告知用户深度诊断需要凭证。引导他们使用 sysom-osops precheck 检查认证状态，并使用 sysom-osops configure 进行配置；凭证需要在对话之外设置。
4. 只有在用户确认凭证已配置后，才重新运行命令。

参考资料

参考资料	使用场景
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	检查操作系统、架构和地域支持情况

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	案例库和反模式