huawei-cloud-gaussdb-instance-management

Huawei Cloud GaussDB 分散データベース

Huawei Cloud GaussDB を管理・診断します。対象は、MySQL 互換エンジン （GaussDB for MySQL）と openGauss ベースの分散エンジン（GaussDB for openGauss）です。 インスタンスのライフサイクル、シャード／読み取り専用ノードの管理、バックアップ管理、データベースの 権限管理に加え、デプロイ形態とセキュリティ設定の診断を行います。 サポート対象はこの 2 つの GaussDB 製品のみです。RDS やその他のクラウドデータベース サービスは対象外です。

---

ステップ 0：skill-quality-cli をインストールします（冪等です。インストール済みの場合はスキップしてください）

CLI は ~/.local/bin/ にインストールされます。このディレクトリは 常に $PATH に含まれているとは限りません（skill-quality-cli を直接実行すると、終了コード 127 で失敗することがあります）。まず PATH をエクスポートしてからインストーラーを実行してください（今後のシェルのために、PATH のエクスポートは ~/.bashrc ／ ~/.profile にも保存されます）。

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	いいえ	レポートに使用するエージェントセッション ID（3 つの情報源の優先順位：--session-id > SKILL_QUALITY_SESSION_ID > 自動収集）
SKILL_TRACE_ID	いいえ	コマンドが skill-quality-cli run でラップされると自動的に設定されます。二重計上を避けるため、ラッパー独自のレポートはスキップされます

上記の変数名は参照用の説明です（シェル プロファイルまたは 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 用の input.json（MySQL 互換）。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 用の input_opengauss.json（openGauss 分散型）：

{
  "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 を実行して AZ を選択してください。

アクションルーティングテーブル

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（プロファイルが設定されている場合は自動）	--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。

品質レポート

このスキルでは、Huawei Cloud の品質レポート規約に従い、統合 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 null ポインター、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 アクションの受け入れ基準

トラブルシューティング

エラー	対処方法
gaussdbforopengauss に対して Service not found が表示される	そのリージョンでは製品を利用できません。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（複数ステップ／手順形式のスキル）

ステップごとに 1 回報告します（複数回呼び出し可能です）：

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_\-.,:=/{}@]）のみで構成されるプレーンな文字列である必要があります。それ以外（シェルのメタ文字、$()、バッククォート、引数としての空白など）はエラーとして拒否され、サブプロセスの開始前に処理が中断されるため、不正な入力がツールに渡ることはありません。