alibabacloud-sysom-diagnosis：阿里云操作系统控制台官方 Skill，面向 Linux，对内存、网络、IO、负载等问题做深度分析与诊断。

alibabacloud-sysom-diagnosis

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

即时路由

当用户报告症状且尚未提供最新的 SysOM 信封输出时，先运行下方领域路由中匹配的 SysOM 命令，再考虑临时性的 Linux 排查或手工探测。然后遵循返回的 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

如果缺失则安装。安装器运行于 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 上，安装器会自动执行 ad-hoc 签名并去除隔离属性。如果你在 Apple Silicon 上通过 Rosetta 运行 x86_64 shell，安装器会检测到不匹配；仅当你确知该二进制将在转译下运行时才传 -f 覆盖。

命令可见性取决于凭证

只有本地命令（如 memory classify）始终存在。每条远程深度命令都是在运行时从 SysOM skills 目录中动态发现的，而这需要凭证。在未配置凭证的机器上，预期现象为：

• sysom-osops memory --help 仅列出 classify，深度内存命令缺失。
• 顶层 sysom-osops --help 完全省略 io、net 和 load 分组。

这是可见性限制，而非能力限制。将 references/deep-actions.md 视为本 Skill 的权威命令清单，绝不从 --help 输出推断某领域或命令不受支持。用 sysom-osops precheck 报告鉴权状态。

核心工作流

1. 将用户的症状归类到一个 SysOM 领域：内存、IO、负载 / CPU、网络，或 Java（GC / 内存 / 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/ 下的术语表、信封指南、profiling 手册、决策树）
• cpu：references/java/cpu/cpu-guide.md
• 其他领域 → 从下方「参考资料」表中加载匹配的参考。

参考文档补充了信封本身无法传达的解释规则、实体定义和答案组织指引。不要从原始信封文本推断 Java 术语、本地内存类别或 profiling 语义。

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；绝不重写、添加或删除标志。如果命令失败，按原样传递错误信封，而不是调整参数重试。
• 跳数上限：即使后端仍说 in_progress，同一会话中 4 跳后停止循环；呈现目前所得结论并说明证据局限（后端在同一上限处强制收敛——双重保险）。
• 用户拒绝：如果用户拒绝提议的命令，停止循环，基于已收集证据总结，并明确说明哪些结论因该跳未运行而仍未确认。

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

• 告知用户该命令的作用、耗时，以及对目标进程可能造成的性能影响（例如采样带来的 CPU 开销、注入 agent 带来的额外内存、可能的 safepoint 停顿）。
• 询问用户是否继续。在用户确认之前，或用户此前已给出自动运行后继命令的长期指示之前，不要运行该命令。
• 命令开始后，告知用户预期等待时间，并在操作仍在进行时保持告知。

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

当 classify 在 agent.next_steps[] 中返回一条命令，且尚无根因发现已包含足够证据作答时，接下来运行第一条命令。不要用人工 shell 探测替代 Agent 可见的 SysOM 后继步骤。原始 Linux 检查是在 SysOM 后继步骤成功、失败或超时之后的有边界兜底。

默认严格按所示使用已记录的命令。除非用户明确要求该视图，不要添加原始、调试或后端证据扩展标志。

最终答案应点明证据、根因、归属 / 范围，以及运维操作目标。除非用户明确要求命令，不要添加用于验证或修复的 shell 片段。优先使用「在变更窗口内审查依赖并禁用或升级泄漏组件」这类措辞，而非原始的模块、cgroup、sysctl、cache-drop 或进程 kill 命令。

不要将形似命令的内联片段（如模块检查 / 移除、内存摘要命令、cgroup 文件写入、cache-drop 控制、sysctl 变更或进程 kill 命令）作为默认的最终答案步骤。

agent 视图必须对诊断自包含。结构化证据是后端 / UI 视图，不得被视为 Agent 获取所需实体的默认来源。

领域路由

命令参数请阅读 references/deep-actions.md 和 references/parameter-guide.md。操作系统与地域支持请阅读 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 领域，而非经由 memory classify。见上方领域路由表。

从可见的 SysOM 输出中选择下一步内存动作。不要仅凭症状措辞推断内存机制。

信封契约

默认命令输出即 Agent 契约：

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "concluded",
    "session_id": "a1b2c3d4e5f6",
    "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 中。

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

• agent.status：in_progress 表示后端诊断 agent 请求另一次采集跳；concluded 表示诊断已收敛。缺失或未识别的值按 concluded 处理。旧版采集器级状态（success、warning 等）在非 Java 动作上仍可能出现；照旧解读。
• agent.session_id：后端生成的多跳会话标识符。绝不生成或修改它；网关已将其注入 command 字符串，因此按原样运行。
• agent.next_steps[].kind：command = 后端请求的采集命令（受上方确认规则约束）；info = 用户侧建议——呈现但绝不自动运行；warning = 证据或数据质量警示。

后继规则

• 优先 category=root_cause，其次最高 severity，再次是最匹配用户报告症状的发现。
• 当可见 detail 包含解释症状所需的实体和一个安全的下一步动作时，将 root_cause 视为可停止。
• 将 agent.next_steps[] 视为优先计划，而非检查清单。
• 只有当另一条 SysOM 命令能填补具名缺失实体或改变修复方案时才运行它。
• 对于长时间运行的 Java 采集命令——java analyze --type memory --duration N（profiling；旧版 memory javamem --duration N）和 collect 模式下的 java analyze --type gc（5–10 分钟 JFR/GC 采集）——等待是分钟级的：告知用户，相应设置工具超时，绝不在客户端超时时重复触发同一命令。见 references/java/memory/profiling-playbook.md（内存）和 references/java/gc/gc-guide.md（gc）。
• 保留影响解读的可见限定词，例如当前证据与历史证据、不可用的直接信号、用于闭合时效性的兜底证据，以及修复的安全前置条件。
• 当某项发现因直接信号不可用而使用兜底证据时，在最终答案中同时说明两部分。不要将结论简化为仅剩兜底指标。
• 在一条聚焦 SysOM 命令闭合根因后，据此作答。不要为让报告更全面而运行额外命令，也不要追逐早先 classify 的异常或观察，除非它们共享同一实体并暴露出具名证据缺口。
• 不要直接调用仅后端可用的采集器或私有辅助命令。
• 不要重新检查 SysOM 已在 summary 或 detail 中点名的 PID、cgroup、文件、限制或事件。
• 在 SysOM 深度命令返回 category=root_cause 且所需实体可见后，据此信封作答。原始 Linux 检查仅用于矛盾、命令错误或明显缺失实体的情况。
• 在最终答案中，不要将已闭合的实体变成额外的原始 Linux 验证命令。除非信封本身提供了可执行的安全下一步动作，否则将修复表达为依赖感知的操作目标和变更窗口计划。
• 避免在最终答案中出现可执行的 shell 片段。如果某命令仅对变更后验证有用，请点名要重跑的 SysOM 检查或指标，而非原始 Linux 命令。
• 这包括模块检查 / 移除、内存摘要命令、cgroup 文件写入、cache-drop 控制、sysctl 变更和进程 kill 动作的内联命令名；请用文字描述依赖门禁和运维操作目标。
• 当当前信封无法解释所报症状，而另一 SysOM 领域点名了更强的根因时，跨领域转向。
• 诊断期间，不要执行会改变目标状态的修复命令，例如杀进程、删文件、改 sysctl 值或写入 cache-drop 控制。除非用户明确要求你执行修复，否则将这些作为建议呈现。
• 对非内存发现保持同一规则：一条聚焦深度命令，然后在所需实体可见时作答。

错误处理

空输出不是信封

命令可能以非零退出码结束，且完全没有 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 skills 目录中动态发现的，而这需要凭证。凭证缺失时目录不可达，子命令从未注册，CLI 回退打印领域分组的帮助文本——且退出码为 0。

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

1. 不要将其解析为信封，也不要报告「未发现问题」。此处的退出码 0 意味着命令从未运行。
2. 不要断定该领域不受支持，或本 Skill 仅提供 memory classify。
3. 告知用户深度诊断需要凭证。指引其用 sysom-osops precheck 查看鉴权状态，用 sysom-osops configure 设置；凭证配置在对话之外完成。
4. 仅在用户确认凭证已配置后重跑该命令。

参考资料

Java 分析参考