CRITICAL - Hard Gate: This is the first step before all operations, taking priority over installation checks, credential verification, and any workflow. The agent MUST complete this check before executing any other step.

User requests ECS backup/restore
|
+-> Check each item in "Not-Recommended Scenarios & Alternatives"
|   +-> Matches any not-recommended scenario -> Execute [HALT Flow]
|   +-> No match -> Pass, continue to "Installation Requirements"
|
+-> Not-recommended scenario keywords:
    - Database: MySQL/Oracle/SQL Server/PostgreSQL/MongoDB/Redis/database data directory
    - Full-machine: full-machine recovery/DR failover/clone instance
    - Cross-region/cross-account: remote backup/cross-account replication
    - Custom policy: hourly backup/custom retention period
    - Large data volume: data exceeds 2 TB

1. Stop immediately - Do NOT execute installation checks, credential verification, parameter confirmation, or any CLI command
2. Output warning to user - Explain why the current scenario is not suitable for ECS File Backup Essential Edition (cite the reason from "Not-Recommended Scenarios & Alternatives")
3. Recommend alternatives - Provide specific alternative products/features
4. End current task - After outputting the warning and alternatives, the agent MUST stop and NOT continue with any subsequent steps of this Skill

Sole recovery condition: Only when the user, after receiving the warning, proactively and explicitly states "I understand the risks and still want to use ECS File Backup Essential Edition" (or semantically equivalent explicit confirmation), may the agent continue with subsequent steps. The following are NOT considered valid confirmations; the agent must remain stopped:

• User does not reply
• User only replies with vague confirmations like "OK", "Continue", "Help me backup" without mentioning "ECS File Backup Essential Edition"
• User changes the topic
• User asks for details about alternatives (indicates user is considering alternatives; do not force continuation)

CRITICAL: The agent MUST complete the following pre-checks before executing any core workflow.

aliyun plugin list 2>/dev/null | grep aliyun-cli-hbr

aliyun plugin install --names aliyun-cli-hbr

After plugin installation, HBR commands and parameter names use kebab-case naming convention (e.g.,

describe-backup-plans

instead of

DescribeBackupPlans

).

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER print, echo, or output AK/SK values in any form (including partial fragments or masked forms)
• NEVER expose any credential content in command-line arguments, logs, conversation output, or code comments
• NEVER enter AK/SK directly in the command line
• ONLY USE

  aliyun configure list

  to check credential status; NEVER echo the output of this command to the user (output may contain credential-related information); the agent should only use the output internally to determine whether credentials are valid

bash

aliyun configure list

Confirm the output shows a valid profile (AK, STS, or OAuth identity).

If no valid credentials exist, configure first:

1. Obtain credentials from Alibaba Cloud Console
2. Run

   aliyun configure

   in the terminal to configure credentials
3. Re-run

   aliyun configure list

   to confirm successful configuration

IMPORTANT: Parameter Confirmation - Before executing any command, all customizable parameters must be confirmed with the user. Do not assume default values; explicit user confirmation is required. If the user refuses to confirm or does not respond to the confirmation request, the agent MUST abort the current operation and NOT continue with subsequent steps.

CRITICAL - Security Gate: Before embedding any parameter into a CLI command, the agent MUST validate all user-provided parameters against the validation regex in the table below. On validation failure, the agent MUST refuse to execute the command, inform the user which parameter is invalid and what format is expected, and wait for the user to provide a valid value before re-validating.

REGION_ID

^[a-zA-Z0-9-]+$

cn-hangzhou

INSTANCE_ID

^[a-zA-Z0-9-]+$

i-bp1abc123def456

PLAN_ID

^[a-zA-Z0-9-]+$

plan-abc123

VAULT_ID

search-historical-snapshots

^[a-zA-Z0-9-]+$

v-0001xjb123

SNAPSHOT_ID

search-historical-snapshots

^[a-zA-Z0-9-]+$

s-0001abc123

SNAPSHOT_HASH

search-historical-snapshots

^[a-zA-Z0-9-]+$

sh-abc123

performanceLevel

L0

L1

^(L0|L1)$

L0

ConflictPolicy

SKIP_THE_FILE

OVERWRITE_EXISTING

^(SKIP_THE_FILE|OVERWRITE_EXISTING)$

SKIP_THE_FILE

CLIENT_TOKEN

^[a-zA-Z0-9-]{1,64}$

550e8400-e29b-41d4-a716-446655440000

keep-latest-snapshots

1

0

^(0|1)$

1

SOURCE_PATH

^[a-zA-Z0-9/_.-]+$

/home/data/file.txt

TARGET_PATH

^[a-zA-Z0-9/_.-]+$

/tmp/restore

CRITICAL: Before executing any of the following workflows, the agent MUST complete all steps in "Scenario Eligibility Check" and "Installation Requirements (Mandatory Pre-check)". If Aliyun CLI or the aliyun-cli-hbr plugin is not installed or does not meet version requirements, it MUST be installed/updated first before proceeding.

aliyun hbr open-hbr-service \
  --endpoint hbr.aliyuncs.com \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Idempotent operation; safe to run repeatedly.

aliyun hbr create-backup-plan \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --instance-id <INSTANCE_ID> \
  --keep-latest-snapshots 1 \
  --options '{"performanceLevel":"<LEVEL>"}' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Idempotent operation; repeated calls for the same instance will not create duplicate backup plans. Safe to retry on timeout.

Activation and client installation are asynchronous operations; they typically take a few minutes to become ready.

Preparing

Ready

Backing Up

aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Extract

PlanId

from the response.

aliyun hbr disable-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Idempotent operation; safe to call repeatedly.

aliyun hbr enable-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Idempotent operation; safe to call repeatedly.

WARNING: This operation will permanently delete all backup data and is irreversible! User intent must be confirmed before execution. If the user has not explicitly confirmed deletion, the agent MUST abort the operation and NOT continue.

aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --source-type ECS_FILE \
  --edition BASIC \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr delete-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

After cancellation, the instance stops incurring charges; deleted backup data cannot be recovered. Idempotent operation; safe to call repeatedly on an already-deleted plan.

aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr describe-backup-jobs-2 \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

describe-backup-jobs-2

returns backup jobs sorted by creation time in descending order; the first record is the latest execution result.

describe-backup-plans finds no plan -> Not Activated (未激活)
describe-backup-plans finds a plan
+-> Disabled = true -> Paused (已暂停)
+-> Query describe-backup-jobs-2 for latest backup job
    +-> No backup jobs -> Preparing (准备中)
    +-> Has backup jobs (first record = latest result)
        +-> COMPLETE/PARTIAL_COMPLETE -> Backup Normal (备份正常)
        +-> RUNNING/QUEUED/CREATED -> Backing Up (备份中)
        +-> CANCELED -> Canceled (已取消)
        +-> FAILED/EXPIRED -> Backup Abnormal (备份异常); troubleshoot via describe-backup-clients

aliyun hbr describe-backup-clients \
  --region <REGION_ID> \
  --client-type ECS_CLIENT \
  --instance-ids '["<INSTANCE_ID>"]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr search-historical-snapshots \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --query '[{"field":"instanceId","value":"<INSTANCE_ID>","operation":"MATCH_TERM"}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr create-restore-job \
  --region <REGION_ID> \
  --restore-type ECS_FILE \
  --edition BASIC \
  --source-type ECS_FILE \
  --vault-id <VAULT_ID> \
  --snapshot-id <SNAPSHOT_ID> \
  --snapshot-hash <SNAPSHOT_HASH> \
  --include '["<SOURCE_PATH>"]' \
  --target-instance-id <INSTANCE_ID> \
  --target-path <TARGET_PATH> \
  --options '{"ConflictPolicy":"<CONFLICT_POLICY>"}' \
  --client-token <UUID> \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

VaultId

,

SnapshotId

, and

SnapshotHash

can be obtained via

search-historical-snapshots

. Omitting

--include

restores all files in the snapshot.

TargetPath

must be an existing directory on the target ECS instance; otherwise the restore job will report a

TARGET_NOT_EXIST

error. Using the

OVERWRITE_EXISTING

policy will overwrite files with the same name at the target path; explicit user confirmation is required before execution. If the user has not confirmed, the agent MUST abort the restore operation. Use

--client-token

to ensure idempotency; the agent should generate a UUID as the ClientToken and reuse the same token on timeout retries to prevent duplicate restore jobs.

aliyun hbr describe-restore-jobs-2 \
  --region <REGION_ID> \
  --edition BASIC \
  --restore-type ECS_FILE \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

aliyun hbr update-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --schedule 'I|<TIMESTAMP>|P1D' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

Schedule format:

I|<start_timestamp>|P1D

, where start_timestamp is a Unix timestamp in seconds, and

P1D

means once per day (fixed for Essential Edition). Idempotent operation; safe to call repeatedly.

aliyun hbr update-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --keep-latest-snapshots <0_OR_1> \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

1

= keep the last backup version (recommended);

0

= do not keep; all backup points older than 30 days will be automatically deleted. Idempotent operation; safe to call repeatedly.

aliyun hbr update-backup-plan \
  --region <REGION_ID> \
  --plan-id <PLAN_ID> \
  --edition BASIC \
  --options '{"performanceLevel":"<LEVEL>"}' \
  --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

See

performanceLevel

in the Parameter Confirmation table for valid values; detailed use cases are described in references/related-apis.md. Idempotent operation; safe to call repeatedly.