huawei-cloud-skill-tester

Huawei Cloud Skill Tester — 3 トラック・8 フェーズの E2E テストパイプライン

独立して繰り返し実行できる Huawei Cloud Skill テストフレームワークです。skill-creator に依存せず、既存の Huawei Cloud Skill をテストできます。 実環境での機能テストと複数 Skill のオーケストレーションシナリオに重点を置いています。

---

概要

この Skill は、3 トラック・8 フェーズの標準化されたテストパイプラインを提供します （3 階層構成 × 全 8 フェーズ：フェーズ 0～6 の実行 + フェーズ 7 の最終レポート）。

階層	フェーズ	目標
Tier 1：単一 Skill のユニットテスト	フェーズ 0～4	各 Skill 項目を順に検証します：インストール、機能抽出、技術調査、テストケース生成、実行
Tier 2：統合テスト	フェーズ 5～6	複数 Skill のオーケストレーションシナリオの導出と、実環境でのエンドツーエンドフロー検証
Tier 3：最終レポート	フェーズ 7	すべてのフェーズの出力を統合したレポート

中核となる設計原則

1. チェーン検証 — 各フェーズの開始前に、前のフェーズの JSON が存在することを確認します。存在しない場合は実行を拒否します
2. エージェントによる不正操作の防止 — 書き込み操作では、項目ごとにユーザーの確認が必要です。ゲートを自動的に回避することはできません
3. 3 トラック構成 — 階層間に明確なゲートを設けます。Tier 2 に進む前に Tier 1 を完了する必要があります
4. バッチで繰り返し実行可能 — --skills "skill-a,skill-b" または --all-installed をサポートします
5. フォールバック戦略 — Skill が 1 つだけの場合、フェーズ 5／6 は単一 Skill のライフサイクルテストに自動的に切り替わります。同階層 Skill の自動スキャンはデフォルトで有効です（フェーズ 5／6 では、テスト対象の Skill と同じディレクトリ内にある他の huawei-cloud-* Skill を自動的に探し、オーケストレーションの組み合わせを実行します）。無効にするには --no-siblings を使用します。
6. 標準化された JSON 出力 — すべてのフェーズが統一されたスキーマで出力し、フェーズ 7 で単一のレポートに統合します
7. 実環境を優先 — Tier 2 のフェーズでは、適用可能な場合は実際の Huawei Cloud に対して実行します（書き込み操作は ALLOW_WRITES によるゲートで制御）。複数 Skill を対象とするフェーズ 6 では、現在、実際に実行せずにシナリオプランを導出します。一方、単一 Skill のフェーズ 6 では、実際の作成→クエリ→更新→削除のループを実行します。モックやシミュレーションは使用しません。

データフロー図

User Input (--skills or --all-installed)
    │
    ├── Tier 1 ──── Iterate over each skill ────
    │   Phase 0 → 1 → 2 → 3 → 4
    │   (phase-N-summary.json chain validation)
    │
    ├── Tier 2 ──── Integration ────
    │   Phase 5 (orchestration scenario derivation + real-environment execution)
    │   Phase 6 (e2e full-flow: create→query→update→delete lifecycle)
    │   Only 1 skill → Downgrade single-skill closed loop
    │
    └── Tier 3 ──── Final ────
        Phase 7 (merge phase-0~6 JSON into consolidated report)

---

依存関係：品質テレメトリは skill-quality-cli によって自動的に収集されます（存在しない場合は scripts/ensure_cli.sh によってインストールされます）。

前提条件

1. hcloud CLI がインストールされ、認証済みであること（Tier 2 の CLI モードテスト用）— 参考：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. Python 3.8+ と huaweicloudsdk パッケージ（SDK モードテスト用）— SDK リファレンス：https://console.huaweicloud.com/apiexplorer/#/sdkcenter
3. Huawei Cloud AK/SK — HUAWEI／HW／HWC で始まるすべての環境変数を自動スキャンします（キーに AK／SK のマーカーが含まれるキーと値のペア）。存在しない場合、フレームワークは環境変数の設定テンプレートを stderr に出力して終了コード 77 で終了します。チャットでユーザーに AK/SK の入力を求めてはいけません。ユーザーはチャット外でシェルプロファイルに環境変数を設定してから、再実行する必要があります。（完全なプロトコルは references/agent-protocol.md を参照してください）。
4. 対象 Skill は $SKILL_INSTALL_DIR/（自動検出順：~/.agents/skills/ → ~/.hermes/skills/ → デフォルト）またはユーザー指定のパスにある必要があります
5. jq コマンド（すべての JSON 処理で必要です）
6. API リファレンス：https://console.huaweicloud.com/apiexplorer/#/openapi

---

• skill-quality-cli — bash scripts/ensure_cli.sh によって確保されます（冪等で、存在する場合はスキップします）
  • アップグレード：手動で skill-quality-cli upgrade を実行します（自動アップグレードはありません）
  • テレメトリレポートを無効にするには、SKILL_QUALITY_REPORT=0 を設定します

ワークフロー — 3 トラック・8 フェーズ

Tier 1: Single-Skill Unit Testing
   Phase 0: Installation Verification (install/uninstall/reinstall)
   Phase 1: Feature Extraction (metadata + commands + resource types + doc checks)
   Phase 2: Technical Research (CLI→SDK→API three-level availability)
   Phase 3: Test Case Generation (functional TC-F + boundary + negative + API TC-A)
   Phase 4: Real-Environment Execution (read-only automatic + write ops require confirmation)

Tier 2: Integration Testing — Real-Environment Orchestration
   Phase 5: Multi-Skill Orchestration (conflict scan / scenario derivation / self-check)
   Phase 6: End-to-End Flow (resource lifecycle: create→query→update→delete)

Tier 3: Final Report
   Phase 7: Consolidated Report (merge phase-0~6 JSON, verdict + issues + reasons)

各フェーズの詳細な実装仕様（手順、合格基準、JSON フィールド）は references/phase-details.md に記載されています。

---

フェーズの概要

フェーズ	名前	主なポイント	判定
0	インストールの検証	ディレクトリの完全性：必須の3点（SKILL.md、references フォルダー、iam-policies ドキュメント）と、任意必須の scripts フォルダー（純粋な CLI スキルには含まれない場合があります。報告はされますが、ブロック要因にはなりません）；インストール／アンインストール／再インストール（同一パス／シンボリックリンク保護）	3点のディレクトリ構成＋ライフサイクル（scripts フォルダーは任意必須）
1	機能の抽出	metadata/triggers/commands/capabilities/resource_types ＋ doc_checks（参照の整合性、禁止対象の .bak/.template ファイル）	コマンドとトリガーが空でないこと
2	技術調査	CLI→SDK→API の3段階で利用可否を確認；純粋なローカルツールは自動的に not_applicable としてマーク	利用可能数
3	テストケースの生成	正常系＋境界値（limit=1）＋異常系（不明なパラメーター）のケース；プレースホルダーの置換（/path/to、./xxx、{region}）；テンプレート／対話型コマンドのフィルタリング	ケース数 > 0
4	実行	自動実行＋出力品質の判定（rc=0 で出力が空の場合は警告）；異常系ケースのエラー品質；ドキュメントの不足分析（doc_gap_issues）；依存関係の不足をマーク	pass/fail/warn/skip
5	オーケストレーション	複数スキル：トリガーの競合スキャン＋データフロー候補；単一スキル：簡易化した自己チェック（内部の曖昧さ＋書き込み操作の順序）	競合スキャン
6	フルフロー	複数スキル：シナリオの導出；単一スキル：簡易化した機能全体のループ（作成→照会→更新→削除）	シナリオのステップ
7	レポート	フェーズ0～6を統合；判定＋pass_rate＋issues_found＋フェーズごとの理由；test-report.json/md	総合判定

詳細な手順、チェーン検証ルール、JSON スキーマについては、references/phase-details.md と references/output-schema-spec.md を参照してください。

---

KooCLI コマンド形式の標準

このテストフレームワークでは、主な実行方法として bash スクリプトを使用します。未加工の hcloud CLI コマンドを直接実行することはありません。以下に示す hcloud コマンド文字列は、形式のテンプレートであり、 プレースホルダーの例であって、実行可能なコマンドではありません。実際の値を含まないプレースホルダートークン（<Service>、{region}、 [--param1=value1 ...] など）が含まれているため、コマンド収集／テストケース生成／テスト実行ロジック（フェーズ1/3/4）で抽出または実行してはなりません。テンプレートの各行には #（コメントマーカー）が付いており、セクションにも実行不可であることが明記されています。

**実行可能なコマンド一覧：**このスキルで実行可能な実際のコマンドは、scripts ディレクトリ内のパイプラインスクリプトのみです。 bash scripts/... で実行します（例：bash scripts/run-test-pipeline.sh --skills <name>、 bash scripts/tier1/phase-0-install-check.sh --skill <name> など。以下のコアコマンドを参照してください）。 このセクションの hcloud ... 形式のテンプレートはすべて説明用のプレースホルダーであり、実行可能なコマンドではありません。コマンドの抽出／実行ロジックではスキップする必要があります。

形式テンプレートのプレースホルダー例 — 形式を読むためのものです。コマンドとして抽出または実行しないでください（# コメント行。/{region} のプレースホルダーを含みます）

hcloud --cli-region={region} [--param1=value1 ...]

**Format Rules:**

- **Service name** — Follows KooCLI Services (uppercase: ECS, VPC, OBS; title case: CloudPond, IAMAccessAnalyzer)
- **Operation name** — PascalCase (e.g., ListServersDetails, ListBuckets)
- **Region** — Always include the `--cli-region` parameter with a real region value (e.g. `cn-north-4`). The token form `--cli-region={region}` is a template placeholder, never a real command.
- **Parameters** — Parameters use the `--name=value` syntax; the token `--param=value` is a format illustration only, never a real command.
- **Read-only limit** — Always append `--limit=1` for exploratory queries (real flag value, only meaningful inside an actual `hcloud` command).

For OBS service, the framework uses `hcloud obs` (obsutil) subsystem:

```bash
> **⚠️ Mandatory: every `hcloud` command in this skill MUST be wrapped with `skill-quality-cli run --skill-name huawei-cloud-skill-tester -- ` — bare `hcloud` calls are strictly forbidden.**

# OBS format-template placeholder examples — for reading the format only; never extract or execute (# comment lines, contain <command>/[args...] placeholders)
# hcloud obs <command> [args...] [options...]

---

コアコマンド

パイプラインの全実行

# Specify skills
bash scripts/run-test-pipeline.sh --skills "huawei-cloud-bss-voucher-manage"

# Specify multiple skills (comma-separated)
bash scripts/run-test-pipeline.sh --skills "huawei-cloud-bss-voucher-manage, huawei-cloud-ecs-manage"

# Scan all installed
bash scripts/run-test-pipeline.sh --all-installed

# Start from a specific phase (recovery scenarios only)
bash scripts/run-test-pipeline.sh --skills "bss-voucher" --phase 4

# Fresh mode
bash scripts/run-test-pipeline.sh --skills "bss-voucher" --fresh

単一フェーズの実行（デバッグ）

bash scripts/tier1/phase-0-install-check.sh --skill "huawei-cloud-bss-voucher-manage"
bash scripts/tier1/phase-1-skill-analysis.sh --skill "huawei-cloud-bss-voucher-manage"
bash scripts/tier2/phase-5-orchestration.sh --skills "skill-a, skill-b"
bash scripts/tier3/phase-7-final-report.sh --skills "skill-a, skill-b"

複数スキルのオーケストレーションを実行

# Derive and execute orchestration scenarios for 3 skills
bash scripts/tier2/phase-5-orchestration.sh --skills "ecs-manage, vpc-manage, eip-manage"

# Run E2E lifecycle test for a single skill
bash scripts/tier2/phase-6-full-flow.sh --skill "huawei-cloud-rds-intelligent-service"

---

パラメーターの確認

パラメーター	必須	説明	例
--skills	相互排他	カンマ区切りのスキル名またはディレクトリ名	"bss-voucher-manage, ecs-manage"
--all-installed	相互排他	$SKILL_INSTALL_DIR/huawei-cloud/ 配下のすべての huawei-cloud-* をスキャンします	—
--phase	いいえ	特定のフェーズから開始します（デフォルトでは、未実施のフェーズから再開します）	--phase 0
--fresh	いいえ	既存の phase-*.json を phases/archive/<timestamp>/ にアーカイブ（削除ではなく移動）して、最初から開始します。履歴は保持され、削除されるものはありません。	—
--output	いいえ	レポートの出力ディレクトリ（デフォルト：reports/）	--output ./test-reports
--skill-path	いいえ	スキルのディレクトリパス。設定すると、find_skill_path はここだけを検索し（インストールディレクトリへのフォールバックはありません）	--skill-path ./skills
--no-siblings	いいえ	フェーズ 5/6 で、同じディレクトリ内の兄弟 huawei-cloud-* スキルを自動スキャンしません（デフォルトではスキャンが有効です）	--no-siblings
--sibling-limit <N>	いいえ	兄弟スキルの最大数（デフォルトは 5、0 は --no-siblings と同じ）	--sibling-limit 3

環境変数（上級者向け）

変数	デフォルト	用途
SKILL_INSTALL_DIR	自動検出：~/.agents/skills → ~/.hermes/skills → ~/.agents/skills	エージェントランタイムがスキルをインストールする場所
SKILL_PATH_HERMES	SKILL_INSTALL_DIR のエイリアス	下位互換性のために保持されている旧名称
SKILL_INSTALL_CMD	hermes skills	リモートスキルをインストール／アンインストールするコマンド。実際のインストールをスキップするには "" に設定します。
ALLOW_WRITES	0	1 の場合、フェーズ 4/6 の書き込みケースをライブ API に対して実際に実行します（デフォルトではスキップします）
HUAWEI_REGION	cn-north-4	Huawei Cloud のリージョン
HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY	—	フェーズ 4/6 の SDK/CLI 実行に必要です。HUAWEI* / HW* / HWC* で始まる任意の AK/SK 環境変数も使用できます

---

参考資料

主要ドキュメント（必読）

• references/architecture.md — 3 トラック 8 フェーズのアーキテクチャ図（Mermaid）
• references/output-schema-spec.md — 各フェーズの JSON フィールド仕様の全容（フェーズ 7 の最終レポートスキーマを含む）
• references/phase-transition-rules.md — フェーズの遷移／フォールバック／スキップのルール
• references/acceptance-criteria.md — 品質ゲートと 17 項目のレポート受け入れチェックリスト
• references/verification-method.md — 各フェーズを手動で検証する方法（PowerShell + Git Bash）
• references/phase-details.md — フェーズごとの実装仕様の全容（手順、合格基準、JSON フィールド）
• references/agent-protocol.md — 認証情報のリクエストプロトコル（AK/SK が不足している場合の処理フロー全体）

補足資料

• references/iam-policies.md — テスターの実行に必要な最小限の IAM 権限

テンプレート（JSON Schema）

• templates/phase-report-schema.json — phase-N-summary.json（N=0..6）用の JSON Schema
• templates/test-case-schema.json — 個々のテストケース（TC-F-* / TC-A-* / OF-* / FF-*）用の JSON Schema
• templates/scenario-example.json — フェーズ 6 の複数スキルシナリオ導出の参照例

出力形式

すべてのテスト成果物は、テスト対象のスキルと同階層にある <skill-name>-test-files/ という名前のディレクトリに出力されます。これにより、スキルのソースディレクトリがクリーンに保たれ、差分やリグレッションの確認に備えて実行履歴も保持されます。

skills/
├── huawei-cloud-rds-query/                  ← skill source (untouched)
└── huawei-cloud-rds-query-test-files/       ← test artifacts (created on first run, kept across runs)
    ├── phases/
    │   ├── phase-0-summary.json
    │   ├── phase-1-summary.json
    │   ├── ...
    │   └── phase-7-summary.json
    └── reports/
        ├── report-20260724-152309/          ← one subdir per run (timestamped)
        │   ├── test-report.json
        │   └── test-report.md
        ├── report-20260725-090000/
        │   ├── test-report.json
        │   └── test-report.md
        └── ...

• フェーズ 0～6 では、<skill-name>-test-files/phases/ に phase-N-summary.json を出力します。
• フェーズ 7 では、それらを <skill-name>-test-files/reports/report-<timestamp>/test-report.{json,md} に統合します。
• テスト成果物は実行間で保持されます（自動クリーンアップは一切行われません）。--fresh は削除を行わず、古い phases/*.json を phases/archive/<timestamp>/ にアーカイブするため、履歴を保持したままチェーンチェックをリセットできます。reports/ は常に保持されます。
• $SKILL_INSTALL_DIR/ にあるテスト用にインストールされたコピーは終了時にアンインストールされるため、次回の実行時にはクリーンなインストール状態になります。

JSON スキーマについては references/output-schema-spec.md を参照してください。フェーズ 5 と 6 では、監査可能性を確保するため、実際の CLI/SDK レスポンスを含むシナリオ実行ログも出力されます。

ベストプラクティス

• オーケストレーションを行う前に、各スキルが個別に機能することを確認するため、Tier 1 を完了してください。
• 誤操作を避けるため、フェーズ 4 とフェーズ 5/6 では書き込み操作を一つずつ確認してください。一括確認は行わないでください。
• スキルが 1 つだけの場合、フェーズ 5/6 は自動的に単一スキルのクローズドループに切り替わるため、手動でスキップする必要はありません。
• --fresh を使用してリセットし再実行する際は、クリーンアップされていないテストリソースがないことを確認してください。
• 実行前にオーケストレーションのシナリオを確認し、リソースの依存関係の順序が正しいことを確かめてください。

注意事項

• 3 トラック 8 フェーズでは順次実行が厳守され、チェーン検証によってフェーズのスキップを防ぎます。
• API エンドポイントを推測することは固く禁止されています。情報は SDK の _http_info または API Explorer からのみ取得してください。
• 認証情報は環境変数から読み込みます。ハードコーディングは禁止されています。
• AK/SK が不足している場合、フレームワークは環境変数の設定テンプレートを stderr に出力し、終了コード 77 で終了します。Agent はそのテンプレートを一字一句変えずにユーザーへ出力し、シェルまたは PowerShell の $PROFILE で環境変数を設定するよう指示しなければなりません。Agent はチャットで AK/SK の入力や貼り付けをユーザーに求めてはなりません。認証情報が必要な手順を黙ってスキップすることは固く禁止されています。（プロトコルの全文は references/agent-protocol.md を参照してください）
• テスト中に作成したリソースは追跡する必要があります。残っているものがある場合は、手動でクリーンアップする手順を出力してください。
• オーケストレーションのシナリオは自動生成されます。ユーザーは実行前に確認し、承認する必要があります。
• オーケストレーションのシナリオにおける書き込み操作には、ステップごとのユーザー確認が必要です。

エッジケース

シナリオ	対応
スキルディレクトリが存在しない	エラーを報告して終了し、利用可能なスキル一覧を出力します
AK/SK 環境変数が設定されていない	フレームワークは環境変数の設定テンプレート（export HUAWEICLOUD_SDK_AK=<your-access-key-id> / $env:HUAWEICLOUD_SDK_AK=<...> のプレースホルダースニペットを含む）を stderr に出力し、終了コード 77 で終了します。エージェント（またはターミナルの呼び出し元）は、そのテンプレートをユーザーに出力し、環境変数をシェルプロファイルまたは PowerShell $PROFILE に別途設定してから再実行するよう伝える必要があります。チャットで AK/SK の入力や貼り付けを求めてはなりません。黙ってスキップすることは厳禁です。
ユーザーがスキル名を指定したが、Hermes にインストールされていない	--fresh でディレクトリ単位の検出を行い、見つからない場合は案内を添えてエラーを報告します
一部の Phase JSON ファイルが削除されている	チェーンを検出し、削除された Phase から再開します
Phase 4 の実行中にネットワークが中断された	すでに実行されたケースの結果は失われません。再実行時は、--phase フラグを使って合格済みのケースをスキップします
実行中にユーザーが Ctrl+C を押した	すでに出力された Phase JSON は有効です。次回は --resume で現在の Phase から復元できます
テスト対象のスキルが 1 つだけ	Phase 5 → downgraded_self_check（単一スキルのトリガー曖昧性スキャン）、Phase 6 → downgraded_single_skill_flow（実際の実行）
ユーザーが導出されたオーケストレーションシナリオに納得しない	導出されたシナリオを手動で編集するか、スキップします。Phase 5 の導出はメタデータのみで、実行されません
ALLOW_WRITES=1 を指定せずに Phase 4 で書き込み操作を行う	status=skip としてスキップされ、resource_changes は記録されません
Phase 4 で必要なビジネスパラメーター（例：coupon_id）が不足している	status=warn としてマークされ、レポート内の manual_test_items に表示されます。ユーザーは実際のデータを指定して再試行する必要があります
スキル間のデータフローが一致しない	Phase 5 で data_flow_tests の候補として記録されます。自動実行はされません
E2E フロー後に孤立したリソースが検出された	phase-6-summary.json の cleanup.manual_required に、具体的なクリーンアップコマンドとともに一覧表示されます

エージェントプロトコル — 認証情報の要求

Phase 4 または Phase 6 で Huawei Cloud の実 API を呼び出す必要があるものの、環境内に認証情報が見つからない場合、フレームワークは黙ってスキップしません。構造化された要求（sentinel 行 __HUAWEI_SKILL_TESTER_CRED_REQUEST_v1__ を stderr に出力）を出し、終了コード 77 で終了することで、呼び出し元のエージェントがユーザーに必要性を必ず伝えるようにします。

基本ルール（必ず従うこと）：

1. 終了コード 77 または sentinel を受け取ったら、パイプラインを一時停止します。Phase 5/7 をスキップしてはいけません
2. stderr に出力された環境変数の設定テンプレートをそのままユーザーに出力し、シェルプロファイルまたは PowerShell $PROFILE に別途設定するよう案内します（プレースホルダーは <your-access-key-id> / <your-secret-access-key>）
3. 会話内で AK/SK の平文を求めてはなりません（ask_user / read -p / クリップボード経由での受け渡し / ~/.hcloud/config.json などのパスの読み取りを含む）
4. 別途設定した後、失敗した Phase を再実行します。ユーザーが拒否した場合は、「ライブ Phase はスキップ — 認証情報なし」と明示し、合格とマークしてはいけません

プロトコル全体（6 ステップの応答フロー、直接ターミナルモード、動作例）：references/agent-protocol.md。

設計原則

• チェーン検証 — 各フェーズでは、前のフェーズの JSON をチェックして、フェーズのスキップを防ぎます
• エージェントによる不正を防止 — 書き込み操作はユーザーの確認が必要です。偽の確認は許可されません
• データ駆動 — すべてのフェーズで JSON 形式の出力を行い、フェーズ 7 で統合します
• バッチで繰り返し可能 — 同じスキルセットを繰り返しテストできます。--fresh でリセットします
• 実環境を優先 — すべてのオーケストレーションと E2E フローは実際の Huawei Cloud に対して実行し、モックは使用しません
• 価値を損なわずに縮退 — スキルが 1 つだけの場合、空のオーケストレーションフェーズは実行せず、単一スキルのライフサイクルテストへと縮退します
• リソースの安全性 — テスト中に作成したリソースを追跡する必要があります。残っているリソースがある場合は、手動でのクリーンアップ手順を明確に出力します
• 認証情報は必須 — AK/SK が不足している場合、フレームワークは環境変数の設定テンプレートを stderr に出力し、終了コード 77 で終了します。エージェントは必ずそのテンプレートをユーザーに提示し、環境変数をチャット外で設定するよう指示しなければなりません。エージェントはユーザーにチャットで AK/SK を入力または貼り付けるよう求めてはなりません。認証情報が必要な手順を黙ってスキップすることは厳禁です。