huawei-cloud-smn-dms-message

Huawei Cloud SMN / DMS 消息传递技能

步骤 0：确保已安装 skill-quality-cli（必需；首次使用时安装）

强制要求：运行任何 huawei_* 操作前，确保已安装并可使用 skill-quality-cli——每次执行都会通过它报告质量遥测数据。每次执行此技能时都必须触发此步骤（ensure_cli.sh 具有幂等性，一切就绪时会静默退出）。

# 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。

概览

此技能提供 15 个 huawei_* 操作，适用于 Huawei Cloud 的 SMN（简单消息通知）和 DMS（分布式消息服务）。仅支持 Huawei Cloud；不涵盖针对其他云服务提供商的操作。SMN 处理发布/订阅通知（主题 → 订阅 → 消息）。DMS 是三种消息队列引擎的产品总称：Kafka、RabbitMQ、RocketMQ。

**关键架构规则：**KooCLI 没有自己的 DMS 服务。DMS 由三个独立服务提供：Kafka、RabbitMQ、RocketMQ（可通过 hcloud <service> 调用）。每项 DMS 操作都必须先确定引擎，再调用对应服务。切勿发出 DMS 命令。

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

操作系列优先级（基于风险执行）

系列	操作	执行方式	风险
R3 — 查询 / 诊断 (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	自动执行（只读）	无
R2 — 管理 (5)	huawei_create_smn_topic、huawei_add_smn_subscription、huawei_create_smn_message_template、huawei_publish_smn_message、huawei_create_dms_instance	预览命令 + 运行前请用户确认	是（创建资源 / 产生费用）
R1 — 破坏性操作 (3)	huawei_delete_smn_topic、huawei_confirm_smn_subscription、huawei_delete_dms_instance	端到端确认：展示完整命令 + 说明不可逆的影响，并要求用户明确批准	高（删除/更改状态，可能产生短信/电子邮件副作用）

操作分派（脚本执行器）

每项 huawei_* 操作都通过随附脚本 scripts/smn_dms_skill.py 分派——该脚本会选择正确的 KooCLI 服务/操作，注入 --cli-region，并在每次运行时强制绑定质量报告（成功 / biz_fail U02 / sys_fail B01）。其执行方式与下方“核心命令”中的 skill-quality-cli run 封装命令相同；脚本形式是统一的脚本/Agent（封装器）执行入口：

# 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} 会自动解析（默认值为 cn-north-4）；R2/R1 命令默认使用 --preview 运行，只有用户确认所展示的命令后才会实际执行。
• huawei_list_dms_topics --instance_id={instance_id} 使用 --preview，因为它需要真实的 Kafka 实例 ID；替换为 huawei_list_dms_instances 返回的 ID 后即可实际运行。

前置条件

前置条件检查 1/3：已安装并完成身份验证的 KooCLI (hcloud) 2.x+

安装并配置 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

前置条件检查 2/3：身份验证 — AK/SK 或 hcloud 配置文件（两种方式均支持）

身份验证模式	配置方法	适用场景
本地 hcloud 配置文件	交互式运行 hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4，然后输入 AK/SK	推荐方式；命令将严格按照下文所述运行
AK/SK 环境变量	export HUAWEICLOUD_SDK_AK=<ak> 和 export HUAWEICLOUD_SDK_SK=<sk>（可选 HUAWEICLOUD_SDK_SECURITY_TOKEN）	CI / 临时运行环境；KooCLI 会自动读取这些变量

验证配置文件是否存在（不会打印任何值）：

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

KooCLI 会根据配置文件 / 身份验证信息自动解析 --project_id 和 --cli-region；通常无需传入这些参数。

前置条件检查 3/3：IAM 权限

该账户必须拥有 references/iam-policies.md 中列出的 SMN 和 DMS 权限（例如 SMN Administrator、DMS User，或该文件中的最小权限策略）。

• 完整的安装 / 身份验证详情，请参阅 references/cli-installation-guide.md。
• 验证工具是否正常工作，请参阅 references/verification-method.md。

身份验证

安全规则（必须遵守）：

• 禁止读取、回显或打印 AK/SK 值。
• 禁止要求用户在对话中直接输入 AK/SK。
• 禁止使用 hcloud configure set 设置从聊天中粘贴的明文凭据值。
• 禁止在脚本或命令行中硬编码 AK/SK。
• 允许：引用已配置的 hcloud 配置文件，或使用通过其他渠道设置的 HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK 环境变量。

如果用户在消息中直接提供 AK/SK，请礼貌拒绝，并引导其使用上述两种身份验证方式。

工作流

1. 确定范围 — SMN 还是 DMS？对于 DMS，请询问 / 确认引擎（kafka、rabbitmq、rocketmq），并选择匹配的 KooCLI 服务。
2. 路由操作至下方 15 个 huawei_* 操作之一。
3. 风险关卡：
   • R3 查询 / 诊断 → 立即运行并总结结果。
   • R2 管理 → 构建准确的 hcloud 命令，展示给用户，并在执行前等待确认。
   • R1 破坏性操作 → 展示准确的命令及其影响（将删除的内容 / 将接收确认的终端），要求明确的端到端确认，然后执行。
4. 解读输出 — SMN 命令返回 JSON；订阅 status 字段：0=未确认，1=已确认，2=无需确认，3=已取消，4=已删除。DMS 的 status 值包括 RUNNING（正常）以及 CREATING/ERROR/DELETING/FROZEN/EXTENDING 等。
5. 报告 — 总结已创建 / 更新 / 移除的资源，并确认输出中不包含凭据。

核心命令

始终先运行 hcloud <Service> <Operation> --help，重新确认参数名称后再构建命令，尤其是创建操作。

R3 — 查询（自动执行）

huawei_list_smn_topics — 列出 SMN 主题

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

参数	必需	描述
--cli-region	是（自动）	区域，由 Agent 自动填写
--limit	否	1–100，默认值为 100
--offset	否	页偏移量，默认值为 0
--name	否	精确匹配主题名称
--fuzzy_name	否	模糊搜索主题名称

huawei_list_smn_subscriptions — 列出 SMN 订阅

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

参数	必填	描述
--cli-region	是（自动）	区域
--protocol	否	http | https | sms | email | functionstage
--status	否	0=未确认 1=已确认 2=无需确认 3=已取消 4=已删除
--limit / --offset	否	分页

huawei_list_smn_message_templates — 列出 SMN 消息模板

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

参数	必填	描述
--cli-region	是（自动）	区域
--message_template_name	否	模板名称，1–64 个字符
--protocol	否	default | email | sms | functionstage | http | https

huawei_list_dms_instances — 按引擎列出 DMS 实例

# 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

参数	必填	描述
--engine	是	kafka | rabbitmq | rocketmq（每个引擎固定）
--cli-region	是（自动）	区域
--status	否	RUNNING | CREATING | ERROR | DELETING | ...

huawei_list_dms_topics — 列出实例的 Kafka 主题

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

参数	必填	描述
--instance_id	是	Kafka 实例 ID（来自 huawei_list_dms_instances）
--cli-region	是（自动）	区域

R3 — 诊断（自动执行）

huawei_analyze_smn_subscription_confirmation — 订阅确认状态分析

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

分析结果：status=0 的订阅尚未确认——HTTP/HTTPS 端点必须实现 ping-back 确认；电子邮件端点需要用户点击确认链接。列出未确认的订阅，并说明各协议所需的操作。

参数	必填	描述
--cli-region	是（自动）	区域
--topic_urn	否	分析单个主题
--protocol	否	聚焦于一种协议

huawei_analyze_dms_instance_status — DMS 实例运行状况与容量分析

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}

分析：实例状态（RUNNING 表示健康；ERROR/FROZEN/CREATEFAILED 表示不健康）、存储使用情况、重启/维护状态、Broker 数量。其他引擎可按照相同模式使用 RabbitMQ/RocketMQ。

参数	必填	描述
--engine	是	引擎
--instance_id	是（用于 ShowInstance）	实例 ID

R2 — 管理（预览 + 确认）

huawei_create_smn_topic — 创建主题

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

参数	必填	描述
--name	是	1–255 个字符，字母/数字/-/_，必须以字母或数字开头
--display_name	是	在电子邮件中显示为发件人的显示名称（可以是空字符串）
--enterprise_project_id	否	企业项目

huawei_add_smn_subscription — 向主题添加订阅

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}

参数	必填	描述
--topic_urn	是	主题资源标识符
--protocol	是	email | sms | http | https | functionstage | dingding | wechat | feishu | welink
--endpoint	是	按协议填写：电子邮件地址、电话号码、http(s):// URL、FunctionGraph ARN、聊天机器人 Webhook
--remark	否	备注，≤128 字节

⚠️ 添加后，HTTP/HTTPS 订阅需要端点进行 ping-back 确认；电子邮件订阅需要用户点击确认链接——在此之前，订阅会保持 status=0。

huawei_create_smn_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}

参数	必填	描述
--message_template_name	是	1–64 个字符，以字母或数字开头
--content	是	纯文本模板内容，≤256 KB；支持 ${variable} 占位符
--protocol	否	default | email | sms | functionstage | http | https

⚠️ SMS 按成功送达的消息计费——通过偏向 SMS 的模板发布消息会产生按条计费的费用。

huawei_publish_smn_message — 向主题发布消息

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

参数	必填	描述
--topic_urn	是	主题资源标识符
--message	是（或使用 --message_structure/--message_template_name）	≤256 KB；SMS ≤490 个字符，不能包含 []
--subject	否	电子邮件主题，≤512 字节
--message_template_name	否	使用模板发布
--tags.*	否	替换模板变量，例如 --tags.name=value
--time_to_live	否	保留时间 ≤86400 s，默认值为 3600

huawei_create_dms_instance — 创建 DMS 实例（按引擎）

# 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}

参数	必填	描述
--engine	是	kafka | rabbitmq | rocketmq
--name	是	实例名称
--engine_version	是	例如，Kafka 2.7/3.3、RabbitMQ 3.8.35、RocketMQ 4.8.0
--product_id	是	与引擎/版本对应的已发布实例规格（参见 ListEngineProducts）
--available_zones.1	是	AZ ID
--vpc_id / --subnet_id / --security_group_id	是	网络配置
--storage_space	是	存储空间，单位为 GB
--storage_spec_code	是	dms.physical.storage.high.v2 | dms.physical.storage.ultra.v2 | dms.physical.storage.general | dms.physical.storage.extreme
--broker_num	是（Kafka/RocketMQ）	Broker 数量
--access_user / --password	是（RabbitMQ）	RabbitMQ 控制台凭据

创建前运行 hcloud Kafka ListEngineProducts --engine=kafka --cli-region={region}，获取有效的 --product_id / --engine_version 组合。运行前预览完整命令，并与用户确认预估费用。

R1 — 破坏性操作（端到端确认）

huawei_delete_smn_topic — 删除主题（及其订阅）

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

参数	必填	描述
--topic_urn	是	主题资源标识符

⚠️ 删除主题会删除该主题的所有订阅和消息历史记录——必须要求用户明确确认，并告知主题名称。

huawei_confirm_smn_subscription — 确认待处理的订阅

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

参数	必填	描述
--token	是	确认令牌（来自 HTTP ping-back 请求正文或电子邮件确认链接）
--topic_urn	否	主题资源标识符
--endpoint	否	订阅端点 IP

令牌通常会发送到订阅端点（HTTP/HTTPS ping-back 正文，或电子邮件确认链接中的 URL）。Agent 必须向用户/端点获取令牌，并在运行前展示确切的确认操作。

huawei_delete_dms_instance — 删除 DMS 实例

# 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}

参数	必填	描述
--instance_id	是	DMS 实例 ID
--cli-region	是（自动）	区域

⚠️ 删除消息队列实例是不可逆的，并会删除所有已存储的消息（主题、队列、偏移量）。运行前，必须向用户明确确认实例 ID、引擎和数据丢失影响。

参数确认

• 所有命令使用经 hcloud <Service> <Operation> --help 验证的准确参数拼写。请勿臆造参数名称。
• --cli-region 和 --project_id 会根据 hcloud 配置文件／身份验证信息自动解析；无需用户输入。
• 每个表格中以“Yes”标记必需参数；表格会说明可选参数，且只有在需要值时才会将其添加到命令中。
• --help 是权威依据：执行任何非简单命令前，先运行 hcloud <Service> <Operation> --cli-region={region} --help。

KooCLI 命令格式标准

通用调用格式为 hcloud <Service> <Operation> --cli-region={region} [--key=value ...] — 这仅为格式说明：<...> 和 [...] 是占位符，不可原样执行。

特性	约定	示例
服务名称	实际的 KooCLI 服务（区分大小写）：SMN、Kafka、RabbitMQ、RocketMQ。不存在 DMS 服务	hcloud <Service> <Operation>
操作名称	PascalCase	ListInstanceTopics
区域	始终包含 --cli-region={region}	--cli-region=cn-north-4
标量参数	--param=value	--instance_id=xxx
索引参数	--param.N=value	--available_zones.1=cn-north-4a

RAM／容量说明

• SMN 主题的 display_name 是 API 必需参数，但可以是空字符串；参数验证通常会拒绝未知默认值，因此在 CreateTopic 上始终显式传入 --display_name。
• 列出 Kafka 主题需要实例 ID；请保留 huawei_list_dms_instances 输出中的实例 ID 以供后续复用。
• Email／SMS／FunctionGraph 通知终端各自有特定于协议的验证要求；执行 AddSubscription 前，请确认终端格式。

参考文档

• references/iam-policies.md — 最小权限 IAM 策略（必需）
• references/cli-installation-guide.md — KooCLI 安装与身份验证设置（必需）
• references/verification-method.md — 如何验证此技能（推荐）
• references/dataflow-diagram.md — 端到端数据流（推荐）
• references/acceptance-criteria.md — 验收检查（推荐）
• references/engine-operation-reference.md — 完整的 SMN + DMS 引擎操作目录（推荐）
• references/security-audit-guide.md — 安全审计方法（推荐）

质量报告（统一 CLI）

CLI 安装：请参阅本文档顶部的“Step 0: Ensure skill-quality-cli”（幂等；仅在缺少时安装经过 SHA256 验证的固定版本）。

每次运行此技能时都要报告执行质量，可使用以下任一模式。CLI 会通过 --session-id、SKILL_QUALITY_SESSION_ID 或每次运行生成的 .quality_report.json 显式收集 session_id／agent，不会抓取主机的会话信息。

⚠️ PATH 注意：CLI 安装在 ~/.local/bin/，某些环境中的 $PATH 不一定包含该路径。如果出现 skill-quality-cli: command not found（退出码 127），请先运行 export PATH="$HOME/.local/bin:$PATH"（ensure_cli.sh 会自动执行此操作），然后重试；或者直接调用绝对路径 ~/.local/bin/skill-quality-cli。

模式 1（推荐，自动）— 包装整个执行过程

对于脚本／命令式技能，请使用 run 包装整个命令：

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

模式 2（多步骤／指令式技能）

每个步骤报告一次（可多次调用）：

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

⚠️ 强制规则：此技能执行的任何 hcloud 命令都必须使用 skill-quality-cli run 包装 — 严禁直接调用 hcloud。

CLI 安装（固定版本，经过 SHA256 验证）

• 自动安装：执行前运行 bash scripts/ensure_cli.sh（幂等；若已安装则跳过；安装固定版本，并通过 SHA256 白名单验证）。
• 不自动升级：CLI 在运行时绝不会自行升级——请使用 skill-quality-cli upgrade 手动升级（或重新运行 bash scripts/install_cli.sh 手动安装）。
• 离线 / 失败：安装失败时不会显示错误，也绝不会阻塞业务流程；该技能会优雅降级并跳过报告。
• 禁用报告：设置 SKILL_QUALITY_REPORT=0（选择退出）。
• 当前版本记录在 ~/.skill-quality/version.json 中；ensure_cli.sh 和 install_cli.sh 均会验证 SHA256（验证失败时停止操作）。