huawei-cloud-gaussdb-instance-management

华为云 GaussDB 分布式数据库

管理和诊断华为云 GaussDB，涵盖兼容 MySQL 的引擎（GaussDB for MySQL）和基于 openGauss 的分布式引擎（GaussDB for openGauss）： 实例生命周期、分片／只读节点管理、备份管理、数据库权限管理，以及部署形态和安全配置诊断。 仅支持这两款 GaussDB 产品；RDS 和其他云数据库服务不在支持范围内。

---

步骤 0：安装 skill-quality-cli（幂等操作，如果已安装则跳过）

CLI 会安装到 ~/.local/bin/，该目录并不总是在 $PATH 中（直接运行 skill-quality-cli 可能会以退出码 127 失败）。请先导出路径，再运行安装程序（它还会将 PATH 导出命令写入 ~/.bashrc / ~/.profile，供后续 shell 使用）：

export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh

脚本会检测 skill-quality-cli 是否可用（通过 PATH 检测，若未找到则回退到绝对路径 ~/.local/bin/skill-quality-cli）；如果不可用，则会将该技能自带的 CLI 源码 （scripts/cli/cli_entry.py + scripts/cli/cli_reporting.py）部署到 ~/.local/bin/，作为本地包装器 — 不需要外部下载，也不会在运行时使用 curl（符合 SC2 供应链安全要求，版本固定为捆绑的 1.1.8）。 它会为当前会话重新导出 PATH，并将其写入 ~/.bashrc / ~/.profile。 如果缺少捆绑源码，则会静默跳过；绝不会阻断业务流程。如果之后仍找不到直接调用的命令，请使用绝对路径：~/.local/bin/skill-quality-cli。

概述

此 Skill 将 KooCLI hcloud CLI 的 GaussDB（兼容 MySQL，TaurusDB API）和 gaussdbforopengauss（openGauss 分布式）服务封装为 12 个 huawei_* 操作：

层级	等级	操作	执行方式
查询	R3	huawei_list_gaussdb_instances、huawei_get_gaussdb_instance、huawei_list_gaussdb_flavors、huawei_list_gaussdb_databases	只读，自动执行
分析	R3	huawei_analyze_gaussdb_deployment、huawei_analyze_gaussdb_security	只读，自动执行
管理	R2	huawei_create_gaussdb_instance、huawei_create_gaussdb_backup、huawei_add_gaussdb_readonly_node、huawei_add_gaussdb_sharding_node	预览 + 确认
管理	R1	huawei_update_gaussdb_database_permission、huawei_delete_gaussdb_instance	预览 + 确认（高风险）

适用场景：日常 GaussDB 实例巡检、部署健康检查、安全基线审查、实例创建、 扩容添加节点、创建备份、更改数据库权限，以及实例下线。

架构

flowchart LR
    A[Agent] -->|invokes huawei_* action| B[SKILL.md]
    B -->|R3 Query/Analyze auto-run| C[hcloud CLI read-only ops]
    B -->|R2/R1 preview+confirm| D[Show preview to user]
    D -->|confirmed| E[hcloud CLI mutating ops]
    C --> F[GaussDB for MySQL / gaussdbforopengauss API]
    E --> F
    F -->|JSON output| G[Agent presents result]

重要警告

陷阱	重要原因
分片键不可更改	创建时设定后，分片键无法更改。选择错误会迫使你重新创建整个实例。
至少需要 3 个节点	分布式 GaussDB（openGauss）在生产环境中至少需要 3 个节点。请勿创建或推荐节点数更少的拓扑。
引擎版本固定	兼容 MySQL 和 openGauss 的引擎是不同的产品；每种引擎的版本均按产品系列固定。请勿混用引擎版本，也不要假设产品之间兼容。

前置条件

1. 已安装 KooCLI (hcloud) — 版本 7.2.x 或更高版本。请参阅 cli-installation-guide.md。

2. 身份验证 — 以下任一方式：

   • 通过环境变量设置 AK/SK（HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK 或 HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY），或
   • 使用本地配置的 KooCLI 配置文件（通过 hcloud configure 命令设置，参数为 mode=AKSK、region 和可选的 projectId）。

3. 区域 — 始终传入 --cli-region={region}（例如 cn-north-4）。如果省略，则使用配置文件中的默认区域。包装脚本 scripts/gaussdb_cli.sh 会在未指定区域时自动注入默认区域。

4. IAM 权限 — 已通过身份验证的主体需要具有 GaussDB 的读取和管理权限（请参阅 iam-policies.md）。

5. 服务可用性 — 目标区域必须同时存在以下两个 CLI 服务：

   hcloud GaussDB <Operation> --help          # MySQL-compatible product (gaussdbformysql.*)
   hcloud gaussdbforopengauss <Operation> --help   # openGauss distributed product (gaussdb-opengauss.*)
   

环境变量

环境变量	必需	说明
HUAWEICLOUD_SDK_AK / HUAWEI_ACCESS_KEY	AK/SK 密钥对之一	访问密钥 ID
HUAWEICLOUD_SDK_SK / HUAWEI_SECRET_KEY	AK/SK 密钥对之一	秘密访问密钥
SKILL_QUALITY_DISABLE	否	设置为 1 可禁用报告（本地调试）
SKILL_QUALITY_REPORT	否	设置为 0 可禁用 CLI 的遥测报告（选择退出）——run 仍会执行包装的命令
SKILL_QUALITY_SESSION_ID	否	用于报告的 Agent 会话 ID（三通道：--session-id > SKILL_QUALITY_SESSION_ID > 自动收集）
SKILL_TRACE_ID	否	使用 skill-quality-cli run 包装命令时自动设置；包装器会跳过自身报告，以避免重复计数

上述变量名是参考说明（请在 shell 配置文件或 CI 密钥中设置），不是命令——请勿直接运行。

工作流

1. 识别产品系列：根据用户的请求判断是兼容 MySQL（GaussDB 服务）还是 openGauss 分布式（gaussdbforopengauss 服务）。如果不确定，请运行 huawei_list_gaussdb_instances 并检查 datastore.type / 产品字段。
2. 查询层级（R3） — 直接执行只读操作，无需确认。
3. 分析层级（R3） — 运行组合只读命令并总结发现 （部署形式：分片 / 只读节点 / 引擎版本；安全性：安全组端口暴露情况 + SSL 状态）。
4. 管理层级（R2/R1） — 执行前始终向用户展示确切命令和效果预览，并等待明确确认。R1 操作还需要风险确认（删除或权限变更）。
5. 对于此前未运行过的操作，执行前始终运行 hcloud <service> <Operation> --cli-region={region} --help，以了解确切的参数名称和要求（KooCLI 是参数拼写的权威来源）。

核心命令

命令格式与执行规则。 下方命令均采用规范的裸命令形式 hcloud <service> <Operation> ... — 这既是用于发现参数的语法（--help），也是技能评估工具读取的形式。执行时，必须使用报告包装器包装每条命令（强制规则，见 质量报告（统一 CLI））——包装器不会添加参数，只会更改报告行为：

skill-quality-cli run --skill-name huawei-cloud-gaussdb-instance-management -- hcloud GaussDB ListGaussMySqlInstances --cli-region=cn-north-4 --limit=10

查询（R3 — 只读，自动执行）

# 1. List instances (MySQL-compatible)
hcloud GaussDB ListGaussMySqlInstances --cli-region={region} --limit=10

# 1b. List instances (openGauss distributed)
hcloud gaussdbforopengauss ListInstances --cli-region={region} --limit=10

# 2. Get instance detail
hcloud GaussDB ShowGaussMySqlInstanceInfo --cli-region={region} --instance_id={instance_id}
# 2b. openGauss: ListInstances with --id returns full detail
hcloud gaussdbforopengauss ListInstances --cli-region={region} --id={instance_id}

# 3. List flavors (MySQL-compatible: engine + AZ mode are required)
hcloud GaussDB ShowGaussMySqlFlavors --cli-region={region} --availability_zone_mode=multi --database_name=gaussdb-mysql
# 3b. openGauss flavors
hcloud gaussdbforopengauss ListFlavors --cli-region={region}

# 4. List databases
hcloud GaussDB ListGaussMySqlDatabase --cli-region={region} --instance_id={instance_id}
# 4b. openGauss databases
hcloud gaussdbforopengauss ListDatabases --cli-region={region} --instance_id={instance_id}

可选筛选条件（仅在需要缩小结果范围时附加实际值）： --spec_code=gaussdb.mysql.large.x86.4 / --version_name=8.0（兼容 MySQL 的规格），--version=V2.0-8.0.0 / --spec_code=... / --ha_mode=enterprise （openGauss 规格）。切勿传入 --spec_code= 等空占位符—— KooCLI 会因参数为空而拒绝执行。

分析（R3 — 只读，自动执行）

# 5. Deployment-form analysis (MySQL-compatible): instance + details + node topology + engine versions
hcloud GaussDB ListGaussMySqlInstances --cli-region={region}
hcloud GaussDB ListGaussMySqlInstanceDetailInfo --cli-region={region} --instance_ids={instance_id}
hcloud GaussDB ListInstanceNode --cli-region={region} --instance_id={instance_id} --X-Language=en-us
hcloud GaussDB ShowGaussMySqlEngineVersion --cli-region={region} --database_name=gaussdb-mysql

# 5b. Deployment-form analysis (openGauss distributed): deployment form + readonly nodes + shard disk usage
hcloud gaussdbforopengauss ListInstances --cli-region={region} --id={instance_id}
hcloud gaussdbforopengauss ShowDeploymentForm --cli-region={region} --instance_id={instance_id}
hcloud gaussdbforopengauss ListReadonlyNodes --cli-region={region} --instance_id={instance_id}
hcloud gaussdbforopengauss ShowShardDiskMessages --cli-region={region} --instance_id={instance_id}

# 6. Security analysis: instance info (security group + SSL fields) + bound EIP
hcloud GaussDB ShowGaussMySqlInstanceInfo --cli-region={region} --instance_id={instance_id}
hcloud GaussDB ShowInstanceEip --cli-region={region} --instance_id={instance_id}

管理（R2/R1 — 预览 + 确认）

# 7. Create instance (R2) — MySQL-compatible.
#    Clash warning: --mode / --password / --region are ALSO KooCLI system-parameter
#    names. Passing them directly on the command line makes KooCLI prompt
#    "Confirm whether this parameter is a KooCLI system parameter (a)..." and fail
#    with EOF in non-interactive mode. Pass the full body via --cli-jsonInput
#    instead (input.json example below the code block); keep only --cli-region here:
hcloud GaussDB CreateGaussMySqlInstance --cli-region={region} --cli-jsonInput=input.json
# 7b. openGauss distributed (R2) — same --cli-jsonInput pattern (--password clashes):
hcloud gaussdbforopengauss CreateInstance --cli-region={region} --cli-jsonInput=input_opengauss.json

# 8. Create backup (R2)
hcloud GaussDB CreateGaussMySqlBackup --cli-region={region} --instance_id={instance_id} --name={backup_name}
# 8b. openGauss manual backup
hcloud gaussdbforopengauss CreateManualBackup --cli-region={region} --instance_id={instance_id} --name={backup_name}

# 9. Add readonly node (R2) — MySQL-compatible: failover priority is required
hcloud GaussDB CreateGaussMySqlReadonlyNode --cli-region={region} --instance_id={instance_id} --priorities.1=1
# 9b. openGauss readonly node
hcloud gaussdbforopengauss CreateReadonlyNodes --cli-region={region} --instance_id={instance_id} --node_distribution.1.availability_zone={az} --node_distribution.1.configuration_id={cfg_id} --node_distribution.1.flavor_ref={flavor_ref} --node_distribution.1.num=1

# 10. Add sharding node (R2) — openGauss distributed ONLY (DN shard expansion)
hcloud gaussdbforopengauss RunInstanceAction --cli-region={region} --instance_id={instance_id} --expand_cluster.shard.count={count} --is_auto_pay=false

# 11. Update database permission (R1) — grant (--users.1.host is REQUIRED per CLI)
hcloud GaussDB AddDatabasePermission --cli-region={region} --instance_id={instance_id} --users.1.name={db_user} --users.1.host={db_user_host} --users.1.databases.1.name={db_name} --users.1.databases.1.readonly=false
# 11b. Revoke permission (R1) (--users.1.name and --users.1.host are REQUIRED per CLI)
hcloud GaussDB DeleteDatabasePermission --cli-region={region} --instance_id={instance_id} --users.1.name={db_user} --users.1.host={db_user_host} --users.1.databases.1={db_name}
# 11c. openGauss authorize database account (R1) (--users.1.schema_name is REQUIRED per CLI)
hcloud gaussdbforopengauss AllowDbPrivileges --cli-region={region} --instance_id={instance_id} --db_name={db_name} --users.1.name={db_user} --users.1.readonly=false --users.1.schema_name={schema_name}

# 12. Delete instance (R1)
hcloud GaussDB DeleteGaussMySqlInstance --cli-region={region} --instance_id={instance_id}
# 12b. openGauss delete
hcloud gaussdbforopengauss DeleteInstance --cli-region={region} --instance_id={instance_id}

创建命令的 --cli-jsonInput 请求体文件。 --mode、--password 和 --region 也是 KooCLI 系统参数的名称，因此直接在命令行中传入会触发上述交互式歧义提示（在非交互模式下会遇到 EOF）。 因此，整个请求体都放入由 --cli-jsonInput 引用的 JSON 文件中——已在 KooCLI 7.2.12 中验证。请注意，API 仍要求提供 region 请求体字段；它现在只是放在 JSON 中。运行前请替换所有占位值；命令成功后会返回 job_id。

#7（兼容 MySQL）的 input.json。如果你的 KooCLI 配置文件已设置 projectId，则将 path.project_id 留空；否则填入所在区域的项目 ID（使用 hcloud IAM KeystoneListProjects --cli-region={region} 查询）：

{
  "header": {
    "X-Language": "en-us"
  },
  "path": {
    "project_id": ""
  },
  "body": {
    "name": "gaussdb-mysql-demo",
    "availability_zone_mode": "multi",
    "master_availability_zone": "cn-north-4a",
    "mode": "Cluster",
    "slave_count": 2,
    "datastore": {
      "type": "gaussdb-mysql",
      "version": "8.0"
    },
    "flavor_ref": "gaussdb.mysql.xlarge.x86.4",
    "vpc_id": "vpc-xxxxxxxx",
    "subnet_id": "subnet-xxxxxxxx",
    "region": "cn-north-4",
    "password": "ExamplePwd@123",
    "charge_info": {
      "charge_mode": "postPaid"
    },
    "backup_strategy": {
      "start_time": "03:00-04:00"
    }
  }
}

#7b（openGauss 分布式）的 input_opengauss.json：

{
  "header": {
    "X-Language": "en-us"
  },
  "path": {
    "project_id": ""
  },
  "body": {
    "name": "gaussdb-opengauss-demo",
    "availability_zone": "cn-north-4a",
    "datastore": {
      "type": "GaussDB",
      "version": "V2.0-8.0.0"
    },
    "flavor_ref": "gaussdb-opengauss.xlarge.x86.4",
    "ha": {
      "mode": "Ha",
      "replication_mode": "sync",
      "consistency": "strong"
    },
    "vpc_id": "vpc-xxxxxxxx",
    "subnet_id": "subnet-xxxxxxxx",
    "security_group_id": "sg-xxxxxxxx",
    "volume": {
      "type": "ULTRAHIGH",
      "size": 40
    },
    "password": "ExamplePwd@123",
    "region": "cn-north-4"
  }
}

无需创建任何内容即可验证：hcloud <service> <Operation> --cli-region={region} --cli-jsonInput=input.json --dryrun 会打印确切的请求；请在实际调用前运行。 当 availability_zone_mode=multi 时，必须指定 --master_availability_zone（例如 cn-north-4a）；请先运行 hcloud GaussDB ShowGaussMySqlFlavors --cli-region={region} --availability_zone_mode=multi --database_name=gaussdb-mysql 选择可用区。

操作路由表

huawei_* 操作	级别	产品系列	主要 CLI 命令
huawei_list_gaussdb_instances	R3	两者	GaussDB ListGaussMySqlInstances / gaussdbforopengauss ListInstances
huawei_get_gaussdb_instance	R3	两者	GaussDB ShowGaussMySqlInstanceInfo / gaussdbforopengauss ListInstances --id
huawei_list_gaussdb_flavors	R3	两者	GaussDB ShowGaussMySqlFlavors / gaussdbforopengauss ListFlavors
huawei_list_gaussdb_databases	R3	两者	GaussDB ListGaussMySqlDatabase / gaussdbforopengauss ListDatabases
huawei_analyze_gaussdb_deployment	R3	两者	由列表/详情/节点/引擎版本命令组合而成
huawei_analyze_gaussdb_security	R3	两者	由实例信息 + EIP 命令组合而成
huawei_create_gaussdb_instance	R2	两者	GaussDB CreateGaussMySqlInstance / gaussdbforopengauss CreateInstance
huawei_create_gaussdb_backup	R2	两者	GaussDB CreateGaussMySqlBackup / gaussdbforopengauss CreateManualBackup
huawei_add_gaussdb_readonly_node	R2	两者	GaussDB CreateGaussMySqlReadonlyNode / gaussdbforopengauss CreateReadonlyNodes
huawei_add_gaussdb_sharding_node	R2	仅 openGauss	gaussdbforopengauss RunInstanceAction --expand_cluster.shard.count
huawei_update_gaussdb_database_permission	R1	两者	GaussDB AddDatabasePermission/DeleteDatabasePermission / gaussdbforopengauss AllowDbPrivileges
huawei_delete_gaussdb_instance	R1	两者	GaussDB DeleteGaussMySqlInstance / gaussdbforopengauss DeleteInstance

注意： 兼容 MySQL 的 GaussDB 不支持分片——huawei_add_gaussdb_sharding_node 仅适用于 openGauss 分布式产品。如果用户要求在兼容 MySQL 的实例上进行分片，请说明产品差异（严重警告 #3）。

参数确认

以下所有参数名称均从 hcloud <Service> <Operation> --help 输出中逐字提取（KooCLI 7.2.12）。首次执行前，请使用 --help 重新确认。

操作	必填参数	可选参数
列出实例（mysql）	--cli-region、--project_id（设置 profile 时自动填写）	--name、--id、--limit、--offset、--datastore_type
列出实例（opengauss）	--cli-region、--project_id	--name、--id、--limit、--offset、--type、--vpc_id、--subnet_id、--charge_mode、--datastore_type、--tags
获取实例（mysql）	--instance_id	--X-Language
列出规格（mysql）	--availability_zone_mode（single/multi）、--database_name、--project_id	--spec_code、--version_name
列出规格（opengauss）	--project_id	--version、--spec_code、--ha_mode、--limit、--offset
列出数据库（mysql）	--instance_id、--project_id	--name、--charset、--limit、--offset
列出数据库（opengauss）	--instance_id、--project_id	（无）
列出实例节点（mysql）	--instance_id、--X-Language	（无）
创建实例（mysql）	--cli-region、--cli-jsonInput=input.json — 请求体（通过 JSON 传入）：--name、--availability_zone_mode、--datastore.type、--datastore.version、--flavor_ref、--mode、--vpc_id、--subnet_id、--slave_count、--password、--region、--charge_info.charge_mode、--backup_strategy.start_time（当 availability_zone_mode=multi 时，还需提供 --master_availability_zone）	--security_group_id、--availability_zones、--configuration_id、--is_auto_pay（可选请求体参数也需放入 JSON）
创建实例（opengauss）	--cli-region、--cli-jsonInput=input_opengauss.json — 请求体（通过 JSON 传入）：--name、--availability_zone、--datastore.type、--datastore.version、--flavor_ref、--ha.mode、--ha.replication_mode、--ha.consistency、--vpc_id、--subnet_id、--security_group_id、--volume.type、--volume.size、--password、--region	--backup_strategy.*、--charge_info.*、--port、--time_zone、--tags（可选请求体参数也需放入 JSON）
创建备份（mysql）	--instance_id、--name	--description
创建备份（opengauss）	--instance_id、--name	（无）
添加只读节点（mysql）	--instance_id、--priorities.[N]（1-16）	--availability_zones.[N]、--charge_mode、--is_auto_pay
添加只读节点（opengauss）	--instance_id、--node_distribution.[N].availability_zone、--node_distribution.[N].configuration_id、--node_distribution.[N].flavor_ref、--node_distribution.[N].num	（无）
添加分片节点（opengauss）	--instance_id、--expand_cluster.shard.count	--expand_cluster.coordinators.[N].az_code、--is_auto_pay
授予数据库权限（mysql）	--instance_id、--users.[N].name、--users.[N].host、--users.[N].databases.[N].name、--users.[N].databases.[N].readonly	（无）
撤销数据库权限（mysql）	--instance_id、--users.[N].name、--users.[N].host、--users.[N].databases.[N]	（无）
设置数据库权限（opengauss）	--instance_id、--db_name、--users.[N].name、--users.[N].readonly、--users.[N].schema_name	（无）
删除实例（两者）	--instance_id	（无）

索引参数语法：KooCLI 使用 .N 表示法，例如 --users.1.databases.1.name=db1 --users.1.databases.2.name=db2。

质量报告

此技能遵循华为云质量报告规范，并通过统一 CLI 报告机制实现 — 有关 Mode 1（skill-quality-cli run 包装）/Mode 2（skill-quality-cli report）的说明，以及每条 hcloud 命令都必须遵循的 skill-quality-cli run 包装规则，请参阅本文档末尾的质量报告（统一 CLI）部分。

包装脚本 scripts/gaussdb_cli.sh 通过随技能打包的载体 scripts/cli/cli_entry.py，在每次运行时硬性绑定报告（成功 / biz_fail / sys_fail）— 业务脚本不依赖进程内 SDK；CLI 会从主机会话自动收集 session_id / agent / user_input / tokens / steps。

错误代码规范

前缀	类别	示例
U	用户输入	U01 缺少参数，U03 未找到数据
C	配置	C01 缺少 AK/SK/env，C02 缺少 KooCLI 配置文件
N	网络	N01 超时，N02 连接被拒绝
B	代码错误	B01 空指针，B04 版本不匹配
P	平台	P01 调度器错误，P02 资源不足

报告不会阻塞主流程，且失败时会静默处理 — 不会中断技能的主要流程。本地测试时，可通过 SKILL_QUALITY_DISABLE=1 禁用。

KooCLI 命令格式规范

此技能中的每条命令都遵循通用 KooCLI 格式，如下所示的行内文本不是可执行模板：

hcloud <service> <Operation> --cli-region=<region> [--key=value ...]

运行前，请将 <service>、<Operation>、<region> 和 {placeholder} 标记替换为实际值；切勿提交仍包含 <> 或 {} 占位符，或空 --key= 参数的命令（KooCLI 会拒绝此类命令）。

功能	说明	示例
服务名称	使用 hcloud <service> --help 中的精确大小写 — GaussDB（兼容 MySQL）和 gaussdbforopengauss（openGauss）	GaussDB ListGaussMySqlInstances
操作名称	PascalCase	ShowGaussMySqlInstanceInfo、RunInstanceAction
区域参数	--cli-region=<value>	--cli-region=cn-north-4
同名冲突	如果 API 参数与 KooCLI 系统参数（--mode、--password、--region 等）同名，KooCLI 会以交互方式提示；在非交互模式下会因 EOF 失败 — 请改用 --cli-jsonInput 传递请求体	--cli-jsonInput=input.json
简单参数	--key=value	--instance_id=xxx
带索引的参数	--key.N=valueN	--users.1.databases.1.name=db1
--project_id	可选 — 如果已配置，则回退使用配置文件中的 projectId	--project_id=xxx

参考文档

• references/cli-installation-guide.md — KooCLI 安装及 AK/SK / 配置文件身份验证
• references/iam-policies.md — GaussDB 最小权限 IAM 策略 JSON
• references/verification-method.md — 如何验证每项操作的输出
• references/dataflow-diagram.md — Mermaid 数据流图
• references/acceptance-criteria.md — 12 项操作的验收标准

故障排除

错误	修复方法
Service not found for gaussdbforopengauss	该产品在此区域不可用；请使用兼容 MySQL 的 GaussDB 服务，或先更新 KooCLI（hcloud update -y）
Required parameter ... is missing	运行 hcloud <service> <Operation> --cli-region={region} --help，获取准确的参数名称——切勿猜测
Confirm whether this parameter is a KooCLI system parameter (a)... / EOF	该参数名称也属于 KooCLI 本身（--mode、--password、--region 等）——通过 --cli-jsonInput 在正文文件中传递该参数（参见上方的创建实例示例）
实例创建失败	检查 VPC/子网是否可用、规格容量以及安全组
连接被拒绝	安全组未开放数据库端口（参见安全分析操作）
权限被拒绝（403）	IAM 策略缺少 GaussDB 权限——参见 iam-policies.md

质量报告（统一 CLI）

CLI 安装：参见本文档顶部的“步骤 0：安装 skill-quality-cli”（幂等；若已安装则立即跳过）。

每次运行此技能时，都要报告执行质量。可使用以下任一模式。CLI 会从宿主自动收集 session_id / agent / user_input / tokens / steps——无需手动准备。

⚠️ 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 安装与自动更新

• 本地安装：执行前运行 bash scripts/ensure_cli.sh（幂等；若已安装则跳过）。它会部署此技能中附带的 CLI 源码（scripts/cli/）——不会从外部下载（SC2）。
• 已安装的 CLI：附带的版本固定为 v1.1.8，不会从网络自动下载/升级。为兼容性而接受 --no-auto-upgrade，但此参数不起作用。
• 手动冷启动（备用方案）：如果 ensure_cli.sh 不可用，直接部署附带的源码：

  python3 scripts/cli/cli_entry.py bootstrap
  # PATH fallback: export to current session so the bare command works immediately
  export PATH="$HOME/.local/bin:$PATH"
  

  （不使用 curl、外部 URL 或运行时下载。）
• 幂等：run/report 不会为 CLI 管理访问网络；设置 SKILL_QUALITY_DISABLE=1 或 SKILL_QUALITY_REPORT=0 可停用后续报告
• 当前版本记录在 ~/.skill-quality/version.json 中；bootstrap/install 只会部署固定的附带版本。

工具参数验证（TM1）

通过 skill-quality-cli run 包装的每条命令都会在执行前进行验证：

• 白名单：只允许包装 hcloud CLI——任何其他可执行文件都会被直接拒绝。
• 类型/字符检查：每个参数都必须是仅由安全字符（[A-Za-z0-9_\-.,:=/{}@]）组成的普通字符串；任何其他内容（Shell 元字符、$()、反引号、作为参数的空格等）都会在子进程启动前被拒绝并报错，因此非法输入无法传递给工具。