Skill: sdk-team/alibabacloud-sysom-diagnosis (version 0.0.3)

--- name: alibabacloud-sysom-diagnosis version: 1.14.0 description: Perform deep Linux diagnostics for memory, network, IO, and load issues. Use when symptoms include high/insufficient memory, OOM/oom-killer, Java memory pressure, and memory panorama analysis (including socket queue and TCP memory views); packet loss or latency jitter (complements memgraph); disk statistics and slow IO; scheduling delay and system load. Outputs a structured diagnostic envelope for automated follow-up runs. layer: application category: os-ops lifecycle: operations tags: - os-ops - sysom - diagnosis - ecs - memory - oom - oom-killer - low-memory - kernel-logs - io - network - load status: beta --- # SysOM Diagnosis (sysom-diagnosis) Run diagnostics with **`./scripts/osops.sh`** under **`sysom-diagnosis/`** (skill root). stdout is a **JSON envelope**. By default it performs a **local quick check without cloud invocation**; remote deep diagnosis is triggered by **`--deep-diagnosis`** (memory domain) or **`io`/`net`/`load` subcommands**, with built-in environment checks. ## Installation > **Pre-check: Aliyun CLI >= 3.3.3 required** > Run `aliyun version` to verify >= 3.3.3. If not installed or version too low, > run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to update. > Then [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > Then [MUST] run `aliyun plugin update` to ensure local plugins are up-to-date. > > At the **start** of the Core Workflow (before any CLI invocation): > **[MUST] Enable AI-Mode** — AI-mode is required for Agent Skill execution. > ```bash > aliyun configure ai-mode enable > aliyun configure ai-mode set-user-agent --user-agent [REDACTED_SECRET] > ``` > > At the **end** of the workflow (after success or failure): > **[MUST] Disable AI-Mode** — AI-mode must be disabled after skill execution completes. > ```bash > aliyun configure ai-mode disable > ``` ## Core Agent Behaviors 1. **Local first**: run memory quick checks first; do not ask for region/instance by default. 2. **Intent routing**: - **Memory domain**: high usage/panorama → `memgraph`; OOM/oom-killer → `oom`; Java → `javamem`; unknown → `classify`. See [memory-routing.md](./references/memory-routing.md). - **Non-memory domain**: IO/network/load → use corresponding `io`/`net`/`load` subcommands and go directly to remote deep diagnosis. See [non-memory-routing.md](./references/non-memory-routing.md). - **Hard constraint for remote deep diagnosis**: for `--deep-diagnosis`, `io/*`, `net/*`, and `load/*`, SysOM `InvokeDiagnosis` must be triggered via `./scripts/osops.sh`; do not degrade to generic ECS diagnostics APIs or manual `Ecs.RunCommand`/Cloud Assistant collection (`top`/`ps`/`iostat`) as replacements. 3. **Follow envelope instructions**: always read `agent.summary` and execute `agent.next`. Quick output is signal detection only. If `agent.next` contains a command, execute it before summarizing to the user. 4. **Envelope is source of truth**: base conclusions on envelope `data`; no extra ad-hoc collection is needed. 5. **Latency + socket queue backlog**: if `net netjitter`/`net packetdrop` has been run and looks normal but `ss` shows high Send-Q/Recv-Q, cross-check with `memory memgraph --deep-diagnosis`. For full conventions (execution directory, credential safety, precheck noise reduction, etc.), see [agent-conventions.md](./references/agent-conventions.md). ## Envelope Output CLI stdout is a JSON envelope (`format: sysom_agent`, `version: 3.4`). The agent directly consumes `agent.summary` (summary), `agent.findings` (key metrics), and `agent.next` (next-step command, executed with Bash in the skill root). Business payload is in `data.routing`, `data.local`, and `data.remote`. See [output-format.md](./references/output-format.md). ### Precheck / Authentication Failure On authentication failure, the envelope includes `data.remediation` (standalone precheck) or `data.precheck_gate.remediation` (deep-diagnosis merged flow). Guide users according to envelope instructions. See [agent-conventions.md](./references/agent-conventions.md). ## Subcommand Quick Reference ### Memory Domain | Subcommand | Capability | Reference | |--------|------|------| | `memory memgraph` | Memory panorama/dashboard, including TCP memory and socket queues | [memgraph.md](./references/diagnoses/memgraph.md) | | `memory oom` | OOM / oom-killer diagnosis | [oomcheck.md](./references/diagnoses/oomcheck.md) | | `memory javamem` | Java memory diagnosis | [javamem.md](./references/diagnoses/javamem.md) | | `memory classify` | Comprehensive classification (fallback when uncertain) | Routing: [memory-routing.md](./references/memory-routing.md) | ### IO Domain | Subcommand | Capability | Reference | |--------|------|------| | `io iofsstat` | IO dashboard (disk statistics) | [iofsstat.md](./references/diagnoses/iofsstat.md) | | `io iodiagnose` | Deep IO analysis (slow IO, latency) | [iodiagnose.md](./references/diagnoses/iodiagnose.md) | ### Network Domain | Subcommand | Capability | Reference | |--------|------|------| | `net packetdrop` | Packet loss (rtrace) | [packetdrop.md](./references/diagnoses/packetdrop.md) | | `net netjitter` | Jitter (latency fluctuation) | [netjitter.md](./references/diagnoses/netjitter.md) | ### Load Domain | Subcommand | Capability | Reference | |--------|------|------| | `load delay` | Scheduling delay (nosched) | [delay.md](./references/diagnoses/delay.md) | | `load loadtask` | System load | [loadtask.md](./references/diagnoses/loadtask.md) | ## Quick Start ```bash cd <sysom-diagnosis> ./scripts/osops.sh memory classify # local classification ./scripts/osops.sh memory memgraph # local memory panorama ./scripts/osops.sh memory memgraph --deep-diagnosis --channel ecs --timeout 300 # remote memory deep diagnosis ./scripts/osops.sh io iofsstat --channel ecs --timeout 300 # IO dashboard ./scripts/osops.sh net packetdrop --channel ecs --region cn-hangzhou --instance i-xxx # packet loss diagnosis ./scripts/osops.sh load delay --channel ecs --params '{"duration":30}' # scheduling delay ``` For other instances, add `--region <id> --instance <i-xxx>`. For first-time setup, run `./scripts/init.sh`. ## Three Remote OpenAPI Requirements | Requirement | Description | |------|------| | Identity | AK/SK or instance RAM Role | | Policy | `AliyunSysomFullAccess` | | Activation & SLR | Activate SysOM in console; SLR details: [service-linked-role-subaccount.md](./references/service-linked-role-subaccount.md) | ## Key Path Index | Need | Document | |------|------| | Memory intent → subcommand mapping | [memory-routing.md](./references/memory-routing.md) | | IO/network/load routing | [non-memory-routing.md](./references/non-memory-routing.md) | | Remote invocation contract / CLI options / metadata | [invoke-diagnosis.md](./references/invoke-diagnosis.md) | | Permissions / credentials / precheck | [permission-guide.md](./references/permission-guide.md) → [openapi-permission-guide.md](./references/openapi-permission-guide.md) | | Envelope output format | [output-format.md](./references/output-format.md) | | Agent behavior conventions | [agent-conventions.md](./references/agent-conventions.md) | | Params fields per diagnosis | [diagnoses/README.md](./references/diagnoses/README.md) |

path: references/agent-conventions.md
content: # Agent Conventions (sysom-diagnosis)

This document was split out from `SKILL.md` and provides detailed agent behavior conventions. The main skill file keeps only core rules and index links.

## Execution Directory

- `./scripts/osops.sh` is a relative path and is only valid in the **skill root** (same level as `SKILL.md`).
- Recommended form: `cd <absolute skill root path> && ./scripts/osops.sh ...`.
- Commands in `agent.next.command` must also be executed with Bash in the skill root; do not switch to asking users to copy and run manually.

## Local First

- If users only describe generic symptoms like "high memory" or "OOM" and do not explicitly request remote diagnosis, run a local quick check first (choose subcommands via [memory-routing.md](./memory-routing.md)); do not request region/instance.
- If users explicitly request remote diagnosis, or `agent.next` already includes `--deep-diagnosis`, follow [invoke-diagnosis.md](./invoke-diagnosis.md) for local vs remote flow.

## Credentials and Security

- **Do not** collect AccessKey/Secret in chat.
- Guide users to run `./scripts/osops.sh configure` in their local terminal under the skill root, which writes to `~/.aliyun/config.json`.
- Without PTY: in COSH, enable "Interactive Shell (PTY)" via `/settings`, or enter an interactive Bash with `/bash`.

## Precheck Envelope Consumption

- Guide users to remediate in **order** based on `data.remediation` (standalone precheck) or `data.precheck_gate.remediation` (deep-diagnosis merged). If `primary_path` is locked, show only that path. For `configure_identity`, let users choose per `guidance.auth_path_choice`.
- If `data.precheck_gate` exists, treat it as authoritative and avoid repeating quick findings and precheck findings in full.

## Check and Usage Order

### A. Memory Domain

1. **Quick check**: choose local subcommands via [memory-routing.md](./memory-routing.md). Then read `agent.next`; key findings are in `agent.findings`.
2. **(Optional) `precheck`**: validate credentials and SysOM activation separately.
3. **Confirm target**: for current instance, do not pass `--region`/`--instance`; for other instances, users must provide region + instance-id.
4. **Deep diagnosis**: execute `agent.next.command`, or append `--deep-diagnosis`.
5. **Failure handling**: inspect `error`, `data` (including `remediation`, `precheck_gate`, etc.), and `agent.summary`.

### B. Non-Memory Domains (IO / Network / Load)

1. **Confirm current/other instance** (same as A) → run `./scripts/osops.sh <io|net|load> <subcommand> ...` (built-in environment check before invocation) → read `data.routing`/`data.remote` and `agent.findings`.
2. **Latency + socket queue backlog**: if `net netjitter`/`net packetdrop` has been run and results look normal, but `ss` shows high Send-Q/Recv-Q, cross-check with `memory memgraph --deep-diagnosis`. See [non-memory-routing.md](./non-memory-routing.md).
3. **Failure handling**: same as A.

## Boundary with Other Memory Skills

- This skill uses `./scripts/osops.sh` under `sysom-diagnosis/` (with `memory`/`io`/`net`/`load` support).
- Other skills or parent-repo entries may differ; for SysOM remote deep diagnosis, use the `osops` in this directory.


path: scripts/requirements.txt
content: # Core dependencies
httpx>=0.24.0
requests>=2.28.0

# Alibaba Cloud OpenAPI SDK
alibabacloud-tea-openapi>=0.3.0
alibabacloud-credentials>=0.3.0
alibabacloud-tea-util>=0.3.0
alibabacloud-sysom20231230>=1.14.0

# Data validation
pydantic>=2.0.0


path: scripts/sysom_cli/__init__.py
content: # -*- coding: utf-8 -*-
# sysom_cli: 顶层入口；diagnosis / am / precheck 等，子命令由各模块注册。


path: scripts/sysom_cli/diagnosis/__init__.py
content: # sysom_cli.diagnosis: InvokeDiagnosis 子命令


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)