jdcloud-vm-ops

name: jdcloud-vm-ops description: >- Use when managing JD Cloud VMs — create, start, stop, restart, delete, resize; manage disks, key pairs, snapshots; configure EIPs, security groups; run scripts via cloud assistant; diagnose issues. Works with "实例", "服务器", "云服务器", or "CVM" without saying "VM". NOT for monitoring, VPC, load balancers, or billing. license: MIT compatibility: >- Official JD Cloud SDK (Python 3.10+), valid API credentials, network access to JD Cloud endpoints, and official JD Cloud CLI (jdc). metadata: author: buhaiqing version: "1.8.0" last_updated: "2026-06-18" runtime: Harness AI Agent api_profile: "VM API v1.0 - https://docs.jdcloud.com/cn/virtual-machines/api" cli_applicability: jdc-first-with-fallback cli_version_locked: "1.2.12" sdk_version_locked: ">=1.6.26" cli_support_evidence: >- Official jdc CLI supports VM operations. Verified via jdc vm --help and documentation at https://docs.jdcloud.com/cn/cli environment: - JDC_ACCESS_KEY - JDC_SECRET_KEY - JDC_REGION

This skill follows the Agent Skill OpenSpec.

JD Cloud VM Operations Skill

Overview

JD Cloud Virtual Machine (VM) is a core computing service that provides elastic, scalable, and secure cloud servers. This skill enables efficient operations, including automated deployment, real-time monitoring, and rapid troubleshooting of VM resources.

CLI applicability (repository policy)

• cli_applicability: jdc-first-with-fallback: Official jdc CLI supports VM operations. The Agent MUST attempt to use jdc as the primary execution path. If jdc installation or command execution fails, the Agent MUST retry up to 3 times (with exponential backoff). Only after 3 consecutive failures should the Agent fall back to SDK/API. Both paths MUST be documented.
• Path Preference: Follow jdc-first with SDK fallback strategy. See API & SDK Usage for detailed comparison.

Trigger & Scope (Agent-Readable)

SHOULD Use This Skill When

• User mentions "JD Cloud VM" OR "云主机" OR "Virtual Machine" OR "CVM" OR "VM"
• Task involves CRUD operations on VM instances: create, describe, start, stop, reboot, delete, resize
• Task involves image management, disk management, keypair management
• Task involves cloud assistant (云助手) operations: create commands, invoke commands on VMs, batch execute scripts
• Task keywords: create-instances, describe-instances, start-instance, stop-instance, delete-instance, createCommand, invokeCommand, describeCommands, describeInvocations, cloud-assistant, 云助手, 批量执行命令

SHOULD NOT Use This Skill When

• Task is about monitoring metrics / alarms for VMs → delegate to: jdcloud-cloudmonitor-ops
• Task is about VPC / subnet / security group creation → delegate to: jdcloud-vpc-ops
• Task is about load balancer configuration → delegate to: jdcloud-lb-ops
• Task is purely about billing / account management → delegate to: jdcloud-billing-ops

Delegation Rules

• If user asks "why is my VM slow / high CPU", use this Skill to describe the VM, then suggest jdcloud-cloudmonitor-ops for metrics data
• If user wants a VM in a new VPC, suggest creating VPC first via jdcloud-vpc-ops, then return here

Variable Convention (Agent-Readable)

This Skill uses structured placeholders to avoid prompt injection and parsing ambiguity:

Rule: Placeholders wrapped in {{env.*}} MUST NOT be exposed to or requested from the user. Placeholders wrapped in {{user.*}} MUST be collected interactively.

Security Warning: NEVER log, print, or expose JDC_SECRET_KEY (or any secret) in console output, debug messages, or logs. When verification is needed, check existence only (e.g., if os.environ.get('JDC_SECRET_KEY')) without printing the actual value. If logging credential status is required, use masked placeholders like JDC_SECRET_KEY=<masked> or JDC_SECRET_KEY=***. This applies to all execution flows (SDK, CLI, and debugging scripts).

Output Parsing Rules (Agent-Readable)

Mandatory CLI Conventions

ponytail: full details in references/cli-usage.md and AGENTS.md.

• --output json MUST be BEFORE the subcommand: jdc --output json vm <command>
• --no-interactive does NOT exist — omit it
• CLI reads from ~/.jdc/config INI only (NOT env vars). SDK uses env vars
• Resource IDs: i-[hash] (instance), img-[hash] (image), vol-[hash] (disk)

Key JSON Paths for Common Operations

Expected State Transitions

Changelog

Execution Flows (Agent-Readable)

Every operation follows the pattern: Pre-flight → Execute (jdc primary / SDK fallback) → Validate → Recover. The Agent MUST NOT skip any phase.

jdc-first strategy: The Agent MUST attempt jdc CLI first (primary path). If jdc fails after 3 retries with exponential backoff, fall back to SDK/API. Documentation below lists jdc before SDK to reflect execution priority.

Operation: Create VM Instance

Pre-flight Checks

Execution — CLI (jdc) [Primary Path]

jdc --output json vm create-instances \
  --region-id {{user.region}} \
  --az "{{user.az}}" \
  --instance-type "{{user.instance_type}}" \
  --image-id "{{user.image_id}}" \
  --name "{{user.instance_name}}" \
  --primary-network-interface "{\"subnetId\":\"{{user.subnet_id}}\",\"securityGroupIds\":[\"{{user.sg_id}}\"]}" \
  --system-disk "{\"diskCategory\":\"cloud_ssd\",\"diskSizeGB\":{{user.disk_size}}}" \
  --charge-mode "postpaid_by_duration"

Execution (SDK Fallback — after 3 jdc failures)

SDK fallback: use VmClient.create_instances() — see references/api-sdk-usage.md.

Post-execution Validation

1. Capture {{output.instance_id}} from $.result.instanceIds[0]
2. Poll until running:

   for i in $(seq 1 60); do
     STATUS=$(jdc --output json vm describe-instances \
       --region-id {{user.region}} \
       --instance-ids '["{{output.instance_id}}"]' | jq -r '.result.instances[0].status')
     [ "$STATUS" = "running" ] && break
     sleep 5
   done
   

3. If status is running → operation succeeded, report instance ID, public IP, private IP to user
4. If status is error → capture error from $.result.instances[0].errorMessage, go to Failure Recovery

Failure Recovery

Operation: Describe VM Instance

Execution — CLI (jdc) [Primary Path]

jdc --output json vm describe-instances \
  --region-id {{env.JDC_REGION}} \
  --instance-ids '["{{user.instance_id}}"]'

Execution (SDK Fallback — after 3 jdc failures)

SDK fallback: use VmClient.describe_instances() — see references/api-sdk-usage.md.

Output to Present to User

Operation: Stop VM Instance

Pre-flight (Safety Gate)

• MUST ask user: "Are you sure you want to stop {{user.instance_name}} ({{user.instance_id}})? Running services will be interrupted."
• MUST wait for explicit "yes" / "confirm" before proceeding

Execution — CLI (jdc) [Primary Path]

jdc --output json vm stop-instance \
  --region-id {{env.JDC_REGION}} \
  --instance-id {{user.instance_id}}

Execution (SDK Fallback — after 3 jdc failures)

SDK fallback: use VmClient.stop_instance() — see references/api-sdk-usage.md.

Post-execution Validation

1. Poll until status == stopped (max 120s)

Operation: Delete VM Instance

Pre-flight (Safety Gate)

• MUST ask user: "Are you sure you want to delete {{user.instance_name}} ({{user.instance_id}})? This is IRREVERSIBLE and will release all associated resources."
• MUST wait for explicit "yes" / "confirm" before proceeding

Execution — CLI (jdc) [Primary Path]

jdc --output json vm delete-instance \
  --region-id {{env.JDC_REGION}} \
  --instance-id {{user.instance_id}}

Execution (SDK Fallback — after 3 jdc failures)

SDK fallback: use VmClient.delete_instance() — see references/api-sdk-usage.md.

Post-execution Validation

1. Poll describe-instances until HTTP 404 (max 300s)

Quality Gate (GCL)

This skill participates in the repository-wide Generator-Critic-Loop (GCL) defined in AGENTS.md §Quality Gate. The quality gate is required for this skill (per AGENTS.md §8 — destructive ops).

Parameters (override AGENTS.md §8 defaults)

Loop overview

User request
   │
   ▼
[0] Orchestrator pre-flight  ──► load rubric, classify operation
   │                              optionally load failure-patterns.md
   ▼
[1] Generator (G)            ──► jdc (primary) → SDK (after 3 fails)
   │                              generate command (DO NOT execute yet)
   ▼
[1.5] Hallucination Detection (H) ──► pre-execution structural validity check
   │   (mandatory for vm-ops)        - CLI parameter existence
   │                                   - JSON structure compliance
   │
   ├── PASS → [1a] Execute (run the jdc/SDK call)
   ├── FAIL → [1b] Regenerate (H retriggers G with hallucination report; max 1 retry)
   │         still FAIL → HALT with "HALLUCINATION_ABORT"
   ▼
[2] Critic (C)               ──► isolated context, blind to user request
   │                              score every rubric dimension (5+3)
   │                              assess test accuracy + regression gate
   ▼
[3] Orchestrator decider
   ├─ HALLUCINATION_ABORT     → ABORT (no partial)
   ├─ Safety=0 / blocking     → ABORT
   ├─ all pass                → RETURN
   ├─ iter<2 & not all pass   → RETRY (inject suggestions)
   └─ iter=2 & not all pass   → RETURN_BEST

Hallucination Detection Layer (H) — Mandatory

Purpose: Catch LLM-generated CLI/SDK calls that contain structurally invalid elements before they reach the JD Cloud VM API. This is a pre-execution gate placed between G's generation and actual API execution.

Two-Category Check (for vm-ops):

Key Parameters to Validate:

Termination:

Trace Integration:

The H result is embedded in the GCL trace JSON under iterations[].hallucination_detector:

{
  "iter": 1,
  "hallucination_detector": {
    "status": "PASS|FAIL",
    "checks": {
      "cli_parameters": { "status": "PASS|FAIL", "unrecognized_params": [] },
      "json_structure": { "status": "PASS|FAIL", "issues": [] }
    },
    "report": "..."
  },
  "regenerated": false,
  "generator": { ... },
  "critic": { ... }
}

Reflexion Integration (Lightweight Reflexion)

Purpose: Enable cross-session learning from failure patterns, complementing the within-session GCL loop with persistent failure memory.

Architecture:

┌─────────────────────────────────────────────────────────────────┐
│                    GCL Execution (per-session)                   │
│   [0] Pre-flight → [1] Generate → [1.5] H → [2] C → [3] Decide │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                    failure_pattern (in trace)
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│              Reflexion Memory (cross-session)                    │
│   docs/failure-patterns.md (structured text, ≤200 lines)        │
│   §1 CLI Parameter Errors | §2 Skill Generation | §3 Cross-Skill│
└──────────────────────────┬──────────────────────────────────────┘
                           │
                    Pre-flight retrieval (optional)
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│              Prevention (next session)                           │
│   Inject known patterns into Generator context                  │
│   Agent avoids repeating known mistakes                          │
└─────────────────────────────────────────────────────────────────┘

Pre-flight Retrieval (Optional):

During GCL Pre-flight (step [0]), the Orchestrator MAY:

# 1. Load docs/failure-patterns.md (lazy-load, ~150 lines)
# 2. Filter patterns by current skill name (jdcloud-vm-ops)
# 3. Inject top-3 relevant patterns into Generator context as prevention hints

# Example injection:
"Known failure patterns for this skill:
- InvalidInstanceType: Use exact instance type code from describe-instance-types
- MissingSubnetId: Subnet ID is required for instance creation
- InvalidAz: Availability zone must match region (e.g., cn-north-1a)"

This is a HINT, not a CONSTRAINT — the Generator should use these patterns to avoid known mistakes, but is not required to follow them if the context differs.

Failure Pattern Extraction:

When a GCL iteration fails (SAFETY_FAIL, HALLUCINATION_ABORT, or rubric dimension < threshold), the Orchestrator SHOULD extract a structured failure pattern and append it to the trace:

{
  "failure_pattern": {
    "category": "cli_parameter" | "skill_generation" | "cross_skill" | "runtime" | "token_efficiency",
    "skill": "jdcloud-vm-ops",
    "command": "jdc vm create-instance ...",
    "error": "InvalidParameter: InvalidInstanceType",
    "fix": "Use exact instance type code from describe-instance-types",
    "reusable": true
  }
}

Reusable patterns (reusable=true) are candidates for docs/failure-patterns.md — the centralized Reflexion memory.

Artifacts

• Rubric (concrete scoring rules): references/rubric.md
• Prompt templates (G / C / O / H): references/prompt-templates.md
• Failure patterns (cross-session memory): docs/failure-patterns.md

Integration with existing flows

The GCL wraps the jdc-first / SDK-fallback flow defined under ## Execution Flows above. The Generator (G) IS the existing jdc-or-SDK executor. The Critic (C) is a new, read-only role with no jdc / SDK access. The Orchestrator (O) owns the loop and persists the GCL trace. The Hallucination Detector (H) is a mandatory pre-execution structural check.

Operation-specific behavior

• delete-instance — Critic checks the trace contains both a pre-delete describe-instances snapshot and a post-delete describe-instances 404. Missing either → Correctness = 0. H layer validates --instanceId format before execution.
• create-instance — Critic verifies --client-token was set (Idempotency = 1 required). Missing → Idempotency = 0. H layer validates --instanceType, --az, --subnetId before execution.
• stop-instance / reboot-instance — Safety = 0 if the pre-state was not running and the user did not explicitly opt in. H layer validates --instanceId before execution.
• Cloud assistant run-command — All command output MUST appear in the trace; Traceability = 0 otherwise. H layer validates --commandContent (base64) before execution.

Cloud Assistant Operations

Important: Cloud assistant uses the separate endpoint assistant.jdcloud-api.com. jdc CLI does NOT currently support cloud assistant commands. Use SDK/API only for all cloud assistant operations. See Cloud Assistant Guide for complete reference.

Operation: Create Cloud Assistant Command

Pre-flight Checks

Execution — SDK

SDK-only (CLI not supported). Use AssistantClient.create_command() — see references/cloud-assistant.md.

Post-execution Validation

1. Capture {{output.command_id}} from response.result.commandId
2. Verify via describeCommands

Failure Recovery

Operation: Invoke Cloud Assistant Command

Pre-flight (Safety Gate)

• MUST confirm with user: "Execute command {{user.command_name}} on {{user.instance_count}} VM(s)? This will run the command immediately."
• MUST wait for explicit "yes" / "confirm" before proceeding

Pre-flight Checks

Execution — SDK

SDK-only (CLI not supported). Use AssistantClient.invoke_command() — see references/cloud-assistant.md.

Post-execution Validation

1. Capture {{output.invoke_id}} from response.result.invokeId
2. Poll via DescribeInvocationsRequest until status in (finished, failed, partial_failed) — max 300s, 5s interval
3. Report table:

Prerequisites

Python 3.10 is REQUIRED — jdcloud_cli==1.2.12 uses SafeConfigParser removed in Python 3.12. Full setup is in AGENTS.md MANDATORY Pre-flight Checks.

Quick Setup

uv venv --python 3.10
source .venv/bin/activate
uv pip install jdcloud_cli==1.2.12 jdcloud_sdk>=1.6.26

Credentials (CLI)

export HOME=/tmp/jdc-home
mkdir -p /tmp/jdc-home/.jdc
cat > /tmp/jdc-home/.jdc/config << 'CONFIGEOF'
[default]
access_key = {{env.JDC_ACCESS_KEY}}
secret_key = {{env.JDC_SECRET_KEY}}
region_id = {{env.JDC_REGION}}
endpoint = vm.jdcloud-api.com
scheme = https
timeout = 20
CONFIGEOF
printf "%s" "default" > /tmp/jdc-home/.jdc/current

CRITICAL: CLI reads credentials only from ~/.jdc/config INI, NOT env vars. SDK reads from env vars. Both paths require configuration.

Reference Directory

• Core Concepts
• API & SDK Usage
• CLI Usage
• Cloud Assistant
• Troubleshooting Guide
• Monitoring & Alerts
• Integration (MCP/SDK)