huawei-cloud-smn-dms-message

Huawei Cloud SMN / DMS Messaging Skill

Step 0: Ensure skill-quality-cli (required; installed on first use)

Mandatory: before running any huawei_* action, ensure skill-quality-cli is installed and available — every execution reports quality telemetry through it. This step MUST be triggered on every execution of this skill (ensure_cli.sh is idempotent and exits silently when everything is ready).

# Ensure ~/.local/bin is on PATH (where skill-quality-cli is installed)
export PATH="$HOME/.local/bin:$PATH"

# Ensure skill-quality-cli is ready (idempotent: installs a pinned version with SHA256
# verification only if absent; no auto-upgrade — upgrade manually with `skill-quality-cli upgrade`)
bash scripts/ensure_cli.sh

# Verify it works
skill-quality-cli version

供应链披露: ensure_cli.sh 安装固定版本（默认 v1.1.8）并做 SHA256 白名单校验， 未命中校验和一律拒绝安装；下载前还会检查安装目录合法性（防目录穿越/通配符注入）。 安装位置 ~/.local/bin，不修改系统服务或全局配置。失败（离线/校验失败）时显式 警告后静默降级——绝不阻塞业务流。关闭遥测上报：export SKILL_QUALITY_REPORT=0。

Overview

This skill provides 15 huawei_* actions for Huawei Cloud SMN (Simple Message Notification) and DMS (Distributed Message Service). Only Huawei Cloud is supported; operations against other cloud providers are out of scope. SMN handles pub/sub notifications (topic → subscription → message). DMS is the product umbrella for three message-queue engines: Kafka, RabbitMQ, RocketMQ.

Critical architecture rule: KooCLI has no DMS service of its own. DMS is exposed as three independent services: Kafka, RabbitMQ, RocketMQ (callable as hcloud <service>). Every DMS operation must first determine the engine, then call the matching service. Never issue a DMS command.

┌────────────────┐     ┌────────────────┐     ┌─────────────────────────────┐
│ hcloud SMN     │     │ hcloud Kafka   │     │ hcloud RabbitMQ / RocketMQ  │
│ topics/subs/   │     │ instances &    │     │ instances & delete ops      │
│ templates/msgs │     │ topics         │     │                             │
└────────────────┘     └────────────────┘     └─────────────────────────────┘

Precedence of Action Families (Risk-Based Execution)

Family	Actions	Execution	Risk
R3 — Query / Diagnose (7)	huawei_list_smn_topics, huawei_list_smn_subscriptions, huawei_list_smn_message_templates, huawei_list_dms_instances, huawei_list_dms_topics, huawei_analyze_smn_subscription_confirmation, huawei_analyze_dms_instance_status	Auto-execute (read-only)	No
R2 — Manage (5)	huawei_create_smn_topic, huawei_add_smn_subscription, huawei_create_smn_message_template, huawei_publish_smn_message, huawei_create_dms_instance	Preview command + ask user to confirm before running	Yes (creates resources / spends money)
R1 — Destructive (3)	huawei_delete_smn_topic, huawei_confirm_smn_subscription, huawei_delete_dms_instance	End-to-end confirmation: present full command + describe irreversible impact, require explicit user approval	High (deletes/changes state, SMS/email side effects)

Action Dispatch (Script Executor)

Every huawei_* action is dispatched through the bundled script scripts/smn_dms_skill.py — the script selects the right KooCLI service/operation, injects --cli-region, and hard-binds the quality report (success / biz_fail U02 / sys_fail B01) on every run. Execution is identical to the wrapped skill-quality-cli run commands in "Core Commands" below; the script form is the unified script/agent (wrapper) executor entry point:

# R3 — Query / Diagnose (read-only, auto-execute)
python3 scripts/smn_dms_skill.py huawei_list_smn_topics --region={region}
python3 scripts/smn_dms_skill.py huawei_list_smn_subscriptions --region={region}
python3 scripts/smn_dms_skill.py huawei_list_smn_message_templates --region={region}
python3 scripts/smn_dms_skill.py huawei_list_dms_instances --engine=kafka --region={region}
python3 scripts/smn_dms_skill.py huawei_list_dms_topics --instance_id={instance_id} --preview
python3 scripts/smn_dms_skill.py huawei_analyze_smn_subscription_confirmation --region={region}
python3 scripts/smn_dms_skill.py huawei_analyze_dms_instance_status --engine=kafka --region={region}

# R2 — Manage (preview + confirm; --preview prints the command without executing)
python3 scripts/smn_dms_skill.py huawei_create_smn_topic --name=test-topic --display_name=test --preview
python3 scripts/smn_dms_skill.py huawei_add_smn_subscription --topic_urn=urn:smn:test --protocol=email [email protected] --preview
python3 scripts/smn_dms_skill.py huawei_create_smn_message_template --message_template_name=test --content=hello --preview
python3 scripts/smn_dms_skill.py huawei_publish_smn_message --topic_urn=urn:smn:test --message=hello --preview
python3 scripts/smn_dms_skill.py huawei_create_dms_instance --engine=kafka --name=test --engine_version=2.7 --product_id=test --available_zones=cn-north-4a --broker_num=3 --vpc_id=vpc-test --subnet_id=subnet-test --security_group_id=sg-test --storage_space=100 --storage_spec_code=dms.physical.storage.high.v2 --preview

# R1 — Destructive (end-to-end confirm; --preview prints the command without executing)
python3 scripts/smn_dms_skill.py huawei_delete_smn_topic --topic_urn=urn:smn:test --preview
python3 scripts/smn_dms_skill.py huawei_confirm_smn_subscription --token=test-token --preview
python3 scripts/smn_dms_skill.py huawei_delete_dms_instance --engine=kafka --instance_id=test-id --preview

• {region} is auto-resolved (default cn-north-4); R2/R1 commands run with --preview by default and only execute for real after the user confirms the shown command.
• huawei_list_dms_topics --instance_id={instance_id} uses --preview because it requires a real Kafka instance ID; substitute the ID (from huawei_list_dms_instances) to run it live.

Prerequisites

Prerequisite check 1/3: KooCLI (hcloud) 2.x+ installed and authenticated

Install and configure the Huawei Cloud KooCLI:

curl -O https://cn-north-4-hcli.obs.cn-north-4.myhuaweicloud.com/hcli_install.sh && bash hcli_install.sh
# verify: hcloud --help should print the KooCLI version banner

Prerequisite check 2/3: Authentication — AK/SK or hcloud profile (either is supported)

Auth mode	How to configure	When to use
Local hcloud profile	Run hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 interactively, then enter AK/SK	Recommended; commands run exactly as documented below
AK/SK environment variables	export HUAWEICLOUD_SDK_AK=<ak> and export HUAWEICLOUD_SDK_SK=<sk> (optional HUAWEICLOUD_SDK_SECURITY_TOKEN)	CI / ephemeral runtimes; KooCLI reads these automatically

Verify a profile exists (values are never printed):

# hcloud configure list | head -5   (only metadata is shown, keys are masked)

--project_id and --cli-region are auto-resolved by KooCLI from the profile / authentication info; you normally do not pass them.

Prerequisite check 3/3: IAM permissions

The account must hold the SMN and DMS permissions listed in references/iam-policies.md (e.g., SMN Administrator, DMS User, or least-privilege policies from the same file).

• See references/cli-installation-guide.md for full install/auth details.
• See references/verification-method.md to verify the skill works.

Authentication

Security rules (must be followed):

• Prohibited from reading, echoing, or printing AK/SK values.
• Prohibited from asking the user to input AK/SK directly in the conversation.
• Prohibited from using hcloud configure set with plaintext credential values pasted in chat.
• Prohibited from hardcoding AK/SK in scripts or command lines.
• Allowed: reference the configured hcloud profile, or use HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK environment variables set out-of-band.

If the user offers AK/SK inline, refuse politely and point them to the two auth modes above.

Workflow

1. Determine scope — SMN or DMS? For DMS, ask/confirm the engine (kafka, rabbitmq, rocketmq) and choose the matching KooCLI service.
2. Route the action to one of the 15 huawei_* actions below.
3. Risk gate:
   • R3 query/diagnose → run immediately, summarize results.
   • R2 manage → build the exact hcloud command, show it to the user, and wait for confirmation before executing.
   • R1 destructive → show the exact command with its impact (what will be deleted / which endpoint will receive a confirmation), require explicit end-to-end confirmation, then execute.
4. Interpret output — SMN commands return JSON; subscription status field: 0=unconfirmed, 1=confirmed, 2=no confirmation required, 3=cancelled, 4=deleted. DMS status values include RUNNING (healthy) and CREATING/ERROR/DELETING/FROZEN/EXTENDING etc.
5. Report — summarize created/updated/removed resources, and confirm no output contains credentials.

Core Commands

Always run hcloud <Service> <Operation> --help first to re-confirm parameter names before constructing a command, especially for create operations.

R3 — Query (auto-execute)

huawei_list_smn_topics — List SMN topics

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListTopics --cli-region={region} --limit=20 --offset=0

Parameter	Required	Description
--cli-region	Yes (auto)	Region, agent fills automatically
--limit	No	1–100, default 100
--offset	No	Page offset, default 0
--name	No	Exact topic name match
--fuzzy_name	No	Fuzzy topic name search

huawei_list_smn_subscriptions — List SMN subscriptions

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListSubscriptions --cli-region={region} --limit=20 --offset=0

Parameter	Required	Description
--cli-region	Yes (auto)	Region
--protocol	No	http | https | sms | email | functionstage
--status	No	0=unconfirmed 1=confirmed 2=no confirm 3=cancelled 4=deleted
--limit / --offset	No	Pagination

huawei_list_smn_message_templates — List SMN message templates

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListMessageTemplates --cli-region={region} --limit=20

Parameter	Required	Description
--cli-region	Yes (auto)	Region
--message_template_name	No	Template name, 1–64 chars
--protocol	No	default | email | sms | functionstage | http | https

huawei_list_dms_instances — List DMS instances by engine

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstances --engine=kafka --cli-region={region} --limit=20 --offset=0
# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ ListInstancesDetails --engine=rabbitmq --cli-region={region} --limit=20 --offset=0
# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ ListInstances --engine=rocketmq --cli-region={region} --limit=20 --offset=0

Parameter	Required	Description
--engine	Yes	kafka | rabbitmq | rocketmq (fixed per engine)
--cli-region	Yes (auto)	Region
--status	No	RUNNING | CREATING | ERROR | DELETING | ...

huawei_list_dms_topics — List Kafka topics of an instance

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstanceTopics --instance_id={instance_id} --cli-region={region} --limit=20 --offset=0

Parameter	Required	Description
--instance_id	Yes	Kafka instance ID (from huawei_list_dms_instances)
--cli-region	Yes (auto)	Region

R3 — Diagnose (auto-execute)

huawei_analyze_smn_subscription_confirmation — Subscription confirmation status analysis

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListSubscriptions --cli-region={region}

Analyze the result: status=0 subscriptions have not been confirmed — HTTP/HTTPS endpoints must implement the ping-back confirmation, email endpoints require the user to click the confirmation link. List the unconfirmed subscriptions and the action needed for each protocol.

Parameter	Required	Description
--cli-region	Yes (auto)	Region
--topic_urn	No	Analyze a single topic
--protocol	No	Focus on one protocol

huawei_analyze_dms_instance_status — DMS instance health & capacity analysis

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstances --engine=kafka --cli-region={region}     # then per instance:
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ShowInstance --instance_id={instance_id} --cli-region={region}

Analyze: instance status (RUNNING healthy; ERROR/FROZEN/CREATEFAILED unhealthy), storage usage, restart/maintain state, broker count. Follow the same pattern with RabbitMQ/RocketMQ for other engines.

Parameter	Required	Description
--engine	Yes	Engine
--instance_id	Yes (for ShowInstance)	Instance ID

R2 — Manage (preview + confirm)

huawei_create_smn_topic — Create a topic

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN CreateTopic --name={name} --display_name={display_name} --cli-region={region}

Parameter	Required	Description
--name	Yes	1–255 chars, letters/digits/-/_, must start with letter/digit
--display_name	Yes	Display name shown as sender in email (may be empty string)
--enterprise_project_id	No	Enterprise project

huawei_add_smn_subscription — Add a subscription to a topic

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN AddSubscription --topic_urn={topic_urn} --protocol={protocol} --endpoint={endpoint} --cli-region={region}

Parameter	Required	Description
--topic_urn	Yes	Topic resource identifier
--protocol	Yes	email | sms | http | https | functionstage | dingding | wechat | feishu | welink
--endpoint	Yes	Per protocol: email address, phone, http(s):// URL, FunctionGraph ARN, chatbot webhook
--remark	No	Remarks, ≤128 bytes

⚠️ After adding, HTTP/HTTPS subscriptions need endpoint ping-back confirmation; email subscriptions need the user to click the confirmation link — the subscription stays status=0 until then.

huawei_create_smn_message_template — Create a message template

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN CreateMessageTemplate --message_template_name={message_template_name} --content={content} --cli-region={region}

Parameter	Required	Description
--message_template_name	Yes	1–64 chars, start with letter/digit
--content	Yes	Plain-text template content, ≤256 KB; supports ${variable} placeholders
--protocol	No	default | email | sms | functionstage | http | https

⚠️ SMS is billed per delivered message — publishing via SMS-inclined templates incurs per-message charges.

huawei_publish_smn_message — Publish a message to a topic

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN PublishMessage --topic_urn={topic_urn} --message={message} --cli-region={region}

Parameter	Required	Description
--topic_urn	Yes	Topic resource identifier
--message	Yes (or --message_structure/--message_template_name)	≤256 KB; SMS ≤490 chars, no []
--subject	No	Email subject, ≤512 bytes
--message_template_name	No	Publish using a template
--tags.*	No	Template variable substitution, e.g. --tags.name=value
--time_to_live	No	Retention ≤86400 s, default 3600

huawei_create_dms_instance — Create a DMS instance (by engine)

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka CreatePostPaidKafkaInstance --name={name} --engine=kafka --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --broker_num={broker_num} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ CreatePostPaidInstanceByEngine --name={name} --engine=rabbitmq --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --access_user={access_user} --password={password} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ CreateInstanceByEngine --name={name} --engine=rocketmq --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --broker_num={broker_num} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

Parameter	Required	Description
--engine	Yes	kafka | rabbitmq | rocketmq
--name	Yes	Instance name
--engine_version	Yes	e.g. Kafka 2.7/3.3, RabbitMQ 3.8.35, RocketMQ 4.8.0
--product_id	Yes	Instance flavor published with engine/version (see ListEngineProducts)
--available_zones.1	Yes	AZ ID
--vpc_id / --subnet_id / --security_group_id	Yes	Networking
--storage_space	Yes	Storage in GB
--storage_spec_code	Yes	dms.physical.storage.high.v2 | dms.physical.storage.ultra.v2 | dms.physical.storage.general | dms.physical.storage.extreme
--broker_num	Yes (Kafka/RocketMQ)	Number of brokers
--access_user / --password	Yes (RabbitMQ)	RabbitMQ console credentials

Run hcloud Kafka ListEngineProducts --engine=kafka --cli-region={region} to get valid --product_id / --engine_version pairs before creating. Preview the full command and confirm the estimated cost with the user before running.

R1 — Destructive (end-to-end confirm)

huawei_delete_smn_topic — Delete a topic (and its subscriptions)

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN DeleteTopic --topic_urn={topic_urn} --cli-region={region}

Parameter	Required	Description
--topic_urn	Yes	Topic resource identifier

⚠️ Deleting a topic deletes all subscriptions and message history for it — require explicit user confirmation including the topic name.

huawei_confirm_smn_subscription — Confirm a pending subscription

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ConfirmSubscription --token={token} --cli-region={region}

Parameter	Required	Description
--token	Yes	Confirmation token (from the HTTP ping-back request body or the email confirmation link)
--topic_urn	No	Topic resource identifier
--endpoint	No	Subscription endpoint IP

The token normally arrives at the subscribing endpoint (HTTP/HTTPS ping-back body, or the URL in the email confirmation link). The agent must obtain it from the user/endpoint and show the exact confirmation action before running.

huawei_delete_dms_instance — Delete a DMS instance

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka DeleteInstance --instance_id={instance_id} --cli-region={region}
# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ DeleteInstance --instance_id={instance_id} --cli-region={region}
# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ DeleteInstance --instance_id={instance_id} --cli-region={region}

Parameter	Required	Description
--instance_id	Yes	DMS instance ID
--cli-region	Yes (auto)	Region

⚠️ Deleting a message-queue instance is irreversible and deletes all stored messages (topics, queues, offsets). Confirm instance ID, engine, and data-loss impact with the user explicitly before running.

Parameter Confirmation

• All commands use the exact parameter spelling verified against hcloud <Service> <Operation> --help. Do not invent parameter names.
• --cli-region and --project_id are resolved automatically from the hcloud profile / authentication; no user input needed.
• Required parameters are marked "Yes" in each table; optional parameters are described in each table and only added to a command when a value is needed.
• --help is the source of truth: run hcloud <Service> <Operation> --cli-region={region} --help before executing any non-trivial command.

KooCLI Command Format Standard

The generic invocation shape is hcloud <Service> <Operation> --cli-region={region} [--key=value ...] — this is a format description only: <...> and [...] are placeholders, never executed verbatim.

Feature	Convention	Example
Service name	Actual KooCLI service (case matters): SMN, Kafka, RabbitMQ, RocketMQ. No DMS service exists	hcloud <Service> <Operation>
Operation name	PascalCase	ListInstanceTopics
Region	--cli-region={region} always included	--cli-region=cn-north-4
Scalar param	--param=value	--instance_id=xxx
Indexed param	--param.N=value	--available_zones.1=cn-north-4a

RAM / Capacity Notes

• SMN topic display_name is required by the API but can be an empty string; unknown defaults tend to be rejected by parameter validation — always pass --display_name explicitly on CreateTopic.
• Kafka topic listing requires an instance ID; keep instance IDs from huawei_list_dms_instances output for reuse.
• Email/SMS/FunctionGraph notification endpoints each have protocol-specific validation; confirm the endpoint format before AddSubscription.

Reference Documents

• references/iam-policies.md — least-privilege IAM policies (required)
• references/cli-installation-guide.md — KooCLI install + auth setup (required)
• references/verification-method.md — how to verify this skill (recommended)
• references/dataflow-diagram.md — end-to-end data flow (recommended)
• references/acceptance-criteria.md — acceptance checks (recommended)
• references/engine-operation-reference.md — full SMN + DMS engine operation catalog (recommended)
• references/security-audit-guide.md — security audit how-to (recommended)

Quality Reporting (Unified CLI)

CLI installation: see "Step 0: Ensure skill-quality-cli" at the top of this document (idempotent, installs a pinned version with SHA256 verification only if absent).

Report execution quality on every run of this skill, using either mode below. The CLI collects session_id / agent explicitly (via --session-id, SKILL_QUALITY_SESSION_ID, or the per-run .quality_report.json) — no host session scraping.

⚠️ PATH note: the CLI is installed to ~/.local/bin/, which is NOT always in $PATH in some environments. If skill-quality-cli: command not found (exit 127) appears, run export PATH="$HOME/.local/bin:$PATH" first (ensure_cli.sh does this automatically), then retry; or call the absolute path ~/.local/bin/skill-quality-cli directly.

Mode 1 (recommended, automatic) — wrap the whole execution

For script/command-style skills, wrap the entire command with run:

skill-quality-cli run --skill-name <skill-name> -- <your command>

Mode 2 (multi-step / instruction-style skills)

Report once per step (callable multiple times):

skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>

⚠️ Mandatory rule: any hcloud command executed by this skill MUST be wrapped with skill-quality-cli run — bare hcloud calls are strictly forbidden.

CLI installation (pinned version, SHA256-verified)

• Auto install: run bash scripts/ensure_cli.sh before execution (idempotent, skips if installed; installs the pinned version with SHA256 whitelist verification).
• No auto-upgrade: the CLI never upgrades itself at runtime — upgrade manually with skill-quality-cli upgrade (or re-run bash scripts/install_cli.sh for a manual install).
• Offline / failure: installation failures are silent and never block the business flow; the skill degrades gracefully and reporting is skipped.
• Disable reporting: set SKILL_QUALITY_REPORT=0 (opt-out).
• Current version is recorded in ~/.skill-quality/version.json; both ensure_cli.sh and install_cli.sh verify SHA256 (fail-closed).