huawei-cloud-flexus-l-deploy-jiuwenswarm

重要事項：

1. scripts ディレクトリ内のすべての Python ファイルには、すべての関数が実装されています。追加の py ファイルを作成しないでください。
2. scripts ディレクトリ内のスクリプトファイルを変更しないでください。
3. 提供されているコードとドキュメントに従って、そのまま操作してください。Huawei Cloud の公式 API ドキュメントを確認する必要はありません。

---

security 実行ルール（最優先）：

1. すべてのスクリプトは、skill action=exec を介して実行する必要があります。シェルから直接実行することは絶対に避けてください
2. スクリプトの内容や、会話内に AK/SK/Token を含むコマンドを絶対に出力しないでください
3. 一時スクリプトファイルを絶対に作成しないでください。インライン実行（python -c）を優先してください
4. 実行に失敗した場合は、エラー情報のみを返してください。スクリプトを書き換えたり、コマンドをすべて出力したりしないでください
5. AK/SK/Token は環境変数または hcloud の設定を介して渡す必要があります。会話内に絶対に記載しないでください
6. Huawei Cloud の認証情報をユーザーに対話形式で求めることは絶対にしないでください。認証情報は次の方法のみで取得してください。
   • hcloud CLI の設定ファイル（~/.hcloud/config.json）— 優先ソース。自動検出されます
   • 環境変数を介した一時セキュリティ認証情報（STS Token）— フォールバック
   • 環境変数を介した永続認証情報 — フォールバック

---

Huawei Cloud Flexus L インスタンスへの JiuwenSwarm デプロイスキル

概要

このスキルは、Huawei Cloud Flexus L インスタンス上で JiuwenSwarm（JiuwenClaw）マルチエージェントコラボレーションプラットフォームを完全に自動デプロイするソリューションを提供します。段階的なスクリプトにより、環境の準備からメッセージチャネルの設定まで、全プロセスを自動化します。

---

前提条件

1. Huawei Cloud アカウントの要件

• 有効なサブスクリプションがある Huawei Cloud アカウント
• 十分な残高があるか、請求方法が設定されていること
• 対象リージョン（cn-north-4/cn-east-3/cn-south-1/cn-southwest-2）で Flexus L インスタンスのクォータが利用可能であること

2. IAM 認証情報

• 適切な権限を持つ Huawei Cloud Access Key（AK）と Secret Key（SK）
• 一時セキュリティ認証情報（STS Token）：一時セキュリティ認証情報をサポートしています。AK/SK とともに環境変数 HUAWEICLOUD_SDK_SECURITY_TOKEN が設定されている場合、このスキルは一時認証情報を使用して認証します。
• 必要な IAM 権限については、references/iam-policies.md を参照してください

3. 環境要件

• pip がインストールされた Python 3.8 以降
• システムパッケージの競合を避けるため、Python 仮想環境の使用を推奨します。

  python3 -m venv .venv && source .venv/bin/activate
  

  仮想環境を使用できない場合、一部の新しい Linux ディストリビューションで pip を実行する際に --break-system-packages の追加が必要になることがあります。
• 必要な Python パッケージ：requests、huaweicloudsdkcore、huaweicloudsdkcoc
• KooCLI（hcloud）がインストールされ、PATH から利用できること（IAM/RMS クエリに使用します。references/api-specs.md を参照）

4. ネットワーク要件

• Huawei Cloud API へのインターネットアクセス
• アウトバウンド HTTP/HTTPS トラフィック（ポート 80、443）を許可するセキュリティグループルール
• Web アクセスの場合：デプロイ後にセキュリティグループでポート 5173 を開放する必要があります

5. リソース要件

• Flexus L インスタンスの最小仕様：
  • フレーバー：2c-4g-50g（2 vCPU、4GB RAM、50GB ディスク）以上
  • ネットワーク：パブリック IP が必要
• 対応フレーバー：
  • 2c-4g-50g（2 vCPU 4GB 50GB）- 約 60 CNY/月
  • 2c-4g-70g（2 vCPU 4GB 70GB）- 約 100 CNY/月
  • 4c-8g-180g（4 vCPU 8GB 180GB）- 約 170 CNY/月

6. 設定要件

• LLM 連携用のモデル API 認証情報（API_BASE、API_KEY）（フェーズ 6 で必要）
• メッセージチャネルを設定する場合は、チャネル認証情報（Xiaoyi/Feishu/DingTalk）（フェーズ 7 で必要）

---

アーキテクチャ図

User/Agent      ──────▶│   Flexus L Instance   │──────▶│   JiuwenSwarm App    │──────▶│ Model Config     │ ──────▶│  Channel Config     │
(Skill caller)           (Target Host)                 (Multi-Agent Platform)           (API_BASE/KEY)            (Xiaoyi/Feishu/Dingtalk)

コンポーネントの説明：

• ユーザー／エージェント：自然言語または API を介して JiuwenSwarm のデプロイ操作を開始するスキル呼び出し元です
• Flexus L インスタンス：JiuwenSwarm のデプロイ先ホストとして機能する Huawei Cloud のエラスティッククラウドサーバーです
• JiuwenSwarm アプリ：Flexus L インスタンス上で実行されるマルチエージェントコラボレーションプラットフォームです
• モデル設定：外部 LLM サービスの設定です（API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER）
• チャネル設定：メッセージングチャネルの設定です（Huawei Xiaoyi、Feishu、Dingtalk）

---

スキルの役割

主な機能

1. Flexus L インスタンスの作成 - Flexus L API を呼び出してインスタンスを作成します。インスタンス名、フレーバー、リージョンなどのパラメーターを指定できます。
2. インスタンスステータスの照会 - KooCLI（hcloud RMS ListAllResources）を介して、インスタンスのステータス、パブリック IP、インスタンス ID を照会します
3. COC リモートデプロイ - Huawei Cloud COC（Cloud Operations Center）を使用して、インスタンス上でデプロイスクリプトをリモート実行します
4. COC タスクステータスの照会 - COC API を介して、デプロイタスクの実行ステータスと結果を照会します
5. システムサービスの設定 - 起動時に自動起動する systemd サービスを設定します
6. モデルの設定 - API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER を設定します
7. メッセージチャネルの設定 - 3 つのメッセージチャネル（Xiaoyi、Feishu、DingTalk）に対応します

代表的なユースケース

英語での例：

1. 「Huawei Cloud に JiuwenSwarm をデプロイしてください」
2. 「Flexus L インスタンスに JiuwenClaw をインストールしたい」
3. 「JiuwenSwarm に Feishu ボットを追加する方法を教えてください」
4. 「JiuwenSwarm がカスタムモデルを使用するように設定したい」
5. 「JiuwenSwarm をワンクリックでデプロイして、Xiaoyi チャネルを設定してください」

---

ワークフロー

このスキルは、7 つのフェーズでデプロイを実行します。次のフェーズに進む前に、各フェーズを完了する必要があります。

フェーズ 1：環境の準備

1. Huawei Cloud の認証情報（AK/SK）を確認します
2. 環境変数を設定します：PYTHONIOENCODING=utf-8
3. 依存モジュールを確認します：requests、huaweicloudsdkcore、huaweicloudsdkcoc、KooCLI（hcloud）
4. 認証情報の有効性を検証します（KooCLI hcloud IAM KeystoneListProjects を使用）

フェーズ 2：Flexus L インスタンスの作成

⚠️ 実行前にお客様の確認が必要です！

1. --region パラメーターが指定されていない場合は、対応しているオプションからリージョンを選択するよう、対話形式でユーザーに求めます
2. インスタンスの設定（名前、フレーバー、リージョン、推定コスト）をお客様に表示します
3. お客様の確認を待ちます（「confirm」または「agree」と返信します）
4. 確認後：プロジェクト ID を取得（KooCLI）→ Flexus L 作成 API を呼び出す → order_id を保存 → KooCLI で RMS をポーリングして完了を確認します（30 秒ごとにポーリングし、タイムアウトは既定で600 秒／10 分です。--timeout で変更できます）→ instance_id、public_ip、ecs_instance_id を取得します

フェーズ 3：COC によるリモート依存関係のインストール

1. COC を介して依存関係のインストールスクリプトを実行します
2. git、curl、vim、wget、net-tools などの基本ツールをインストールします
3. Python と Node.js の環境を確認します
4. 完了まで待機します（約 8 分）。スクリプトの実行エラーが発生した場合にのみ再試行します。

フェーズ 4：COC による JiuwenSwarm サービスのリモートデプロイ

1. デプロイスクリプトのテンプレート（assets/deploy_script_template.sh）を読み込みます
2. COC を介して、インスタンス上で完全なデプロイスクリプトを実行します
3. JiuwenSwarm をインストールし、systemd サービスを設定して、サービスを開始します
4. 完了まで待機します（約 15 分）。スクリプトの実行エラーが発生した場合にのみ再試行します。

フェーズ 5：デプロイ結果の検証

1. COC のデプロイタスクのステータスを照会します
2. jiuwenswarm サービスが実行中であることを確認します（systemctl is-active）
3. .env に FRONTEND_HOST=0.0.0.0 が設定されていることを確認します
4. すべてのポートが 0.0.0.0 にバインドされていることを確認します：5173、18092、19000、19001
5. サービスの稼働状態を確認します（curl localhost:5173 が 200 を返すこと）
6. Web アクセス URL を出力します：http://{public_ip}:5173
7. 外部からアクセスできるように、セキュリティグループを設定するようユーザーに案内します

フェーズ 6：モデル設定

1. 対話形式で以下を収集します：API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER
2. COC リモート実行スクリプトを生成します：.env をバックアップし、4 つのコアパラメーターを更新して、権限を 600 に設定します
3. JiuwenSwarm サービスを再起動します

フェーズ 7：メッセージチャネル設定

1. チャネルタイプを選択します：xiaoyi / feishu / dingtalk
2. チャネルタイプに応じて設定を収集します：
   • xiaoyi：AK、SK、Agent ID
   • feishu：App ID、App Secret
   • dingtalk：Client ID、Client Secret、Allow From
3. COC リモート実行スクリプトを生成します：config.yaml をバックアップし、チャネルフィールドを更新して、権限を 644 に設定します
4. JiuwenSwarm サービスを再起動します

COC タスクステータスの照会

UUID を指定して COC の実行ステータスを照会します。単一の照会、詳細出力、完了待機、ファイル読み込みに対応しています。詳細は references/verification-method.md を参照してください。

ステータス	説明
READY	準備完了
PROCESSING	実行中。完了待ちが必要です
FINISHED	正常に完了しました
ABNORMAL	実行異常。失敗しました
CANCELED	キャンセルされました

---

コアコマンド

環境設定

# Install dependencies
pip install -r requirements.txt

認証情報の設定（いずれかを選択）：

オプション A — hcloud CLI の設定（推奨。環境変数は不要です）：

hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<your-ak> --cli-secret-key=<your-sk>
# For STS token: also add --cli-security-token=<your-token>

オプション B — 環境変数：

export HUAWEICLOUD_SDK_AK=<your-access-key>
export HUAWEICLOUD_SDK_SK=<your-secret-key>
export HUAWEICLOUD_SDK_SECURITY_TOKEN=<your-security-token>  # STS only
export HUAWEICLOUD_REGION="cn-north-4"

デプロイコマンド

# 1. Environment preparation
python scripts/prepare_env.py

# 2. Create instance (interactive confirmation)
python scripts/create_instance.py --name jiuwenSwarm-<timestamp> --flavor 2c-4g-50g --wait

# 3. Install dependencies
python scripts/install_deps.py --ip <public_ip>

# 4. Deploy service
python scripts/deploy_service.py --ip <public_ip>

# 5. Verify deployment
python scripts/verify_deployment.py --ip <public_ip>

# 6. Configure model
python scripts/config_model.py --ip <public_ip> --interactive

# 7. Configure message channel
python scripts/config_channel.py --channel xiaoyi --ip <public_ip> --interactive

# 8. Query COC task status
python scripts/query_coc_status.py --uuid <execute_uuid> --verbose

COC ステータス照会コマンド

# Query single task status
python scripts/query_coc_status.py --uuid <execute_uuid>

# Wait for task completion with custom timeout
python scripts/query_coc_status.py --uuid <execute_uuid> --wait --timeout 3600 --interval 30

# Load UUID from JSON file
python scripts/query_coc_status.py --from-file new_instance_info.json

---

パラメーターの確認

⚠️ お客様による確認が必要です

クラウドリソースの作成操作を実行する前に、お客様の明示的な同意を得る必要があります！

操作	確認の要否
新しい Flexus L インスタンスを作成する	必須
既存のインスタンスにアプリケーションをデプロイする	必須
クラウドリソースの設定を変更する	必須

確認テンプレート：

============================================================
⚠️ Cloud Resource Creation Confirmation
============================================================
Operation to be executed: Create new Flexus L instance

Instance Specifications:
  - Name: {instance_name}
  - Flavor: {flavor} (2c-4g-50g ~60 CNY/month / 2c-4g-70g ~100 CNY/month / 4c-8g-180g ~170 CNY/month)
  - Region: {region}
  - Estimated Cost: Calculated based on selected flavor

Resources will be created immediately after confirmation.
Please reply "confirm" or "agree" to continue.
============================================================

ユーザーが設定可能なパラメーター

create_instance.py

パラメーター	説明	デフォルト値
--name	インスタンス名	jiuwenSwarm-{timestamp}
--flavor	インスタンスのフレーバー（2c-4g-50g / 2c-4g-70g / 4c-8g-180g）	2c-4g-50g
--region	リージョン（cn-north-4/cn-east-3/cn-south-1/cn-southwest-2）。指定しない場合は、対話形式で選択できます。	（対話形式）
--wait	作成完了を待機します（RMS を 30s 間隔でポーリングし、インスタンスのステータスを確認します）	False
--timeout	--wait を使用する場合の最大待機時間（秒）	600（10 分）
--confirm	確認プロンプトを省略します	False

deploy_service.py

パラメーター	説明	デフォルト値
--ip	インスタンスのパブリック IP	必須
--wait	デプロイ完了を待機します	True
--timeout	タイムアウト時間（秒）	1800

config_model.py

パラメーター	説明
--api-base	モデル API の URL
--api-key	モデル API キー
--model-name	モデル名
--model-provider	モデルプロバイダー
--ip	インスタンスのパブリック IP
--interactive	対話形式で設定します

config_channel.py

パラメーター	説明
--channel	チャネルタイプ（xiaoyi/feishu/dingtalk）
--ip	インスタンスのパブリック IP
--interactive	対話形式で設定します

query_coc_status.py

パラメーター	説明	デフォルト値
--uuid, -u	COC 実行 UUID	必須
--from-file, -f	JSON ファイルから UUID を読み込みます	-
--key, -k	JSON ファイル内の UUID キー名	execute_uuid
--verbose, -v	詳細な出力を表示します	False
--wait, -w	タスクの完了を待機します	False
--timeout, -t	待機タイムアウト（秒）	1800
--interval, -i	ポーリング間隔（秒）	60

---

ディレクトリ構成

huawei-cloud-flexus-l-deploy-jiuwenswarm/
├── SKILL.md                    # Skill documentation
├── requirements.txt            # Python dependency list
├── scripts/                    # Phased deployment scripts
│   ├── utils.py                # Utility functions
│   ├── prepare_env.py          # Environment preparation
│   ├── create_instance.py      # Create Flexus L instance
│   ├── install_deps.py         # COC remote dependency installation
│   ├── deploy_service.py       # COC remote service deployment
│   ├── verify_deployment.py    # Verify deployment result
│   ├── config_model.py         # Model configuration
│   ├── config_channel.py       # Message channel configuration
│   └── query_coc_status.py     # COC task status query
├── assets/                     # Template files
│   ├── deploy_script_template.sh # Deployment script template
│   ├── jiuwenswarm.service.template # systemd service template
│   ├── config_template.yaml    # Configuration template
│   └── env_template.env        # Environment variable template
└── references/                 # Reference documents
    ├── api-specs.md            # API specifications
    ├── deployment-checklist.md # Deployment checklist
    ├── iam-policies.md         # IAM policies
    ├── verification-method.md  # Verification methods
    ├── acceptance-criteria.md  # Acceptance criteria
    └── troubleshooting.md      # Troubleshooting guide

---

Web UI へのアクセス

Web UI にアクセスするには、次の 2 つの条件を満たす必要があります。

1. サービスが 0.0.0.0 にバインドされていること（.env の FRONTEND_HOST=0.0.0.0 で設定）
2. セキュリティグループでポート 5173 が許可されていること（Huawei Cloud Console で設定）

.env の設定（サービス側）

/root/.jiuwenswarm/config/.env ファイルでは、正しい変数名を使用する必要があります。

.env 変数	用途	必須値
FRONTEND_HOST	フロントエンドの HTTP バインド先	0.0.0.0
FRONTEND_PORT	フロントエンドの HTTP ポート	5173
WEB_HOST	WebChannel のバインド先	0.0.0.0
AGENT_SERVER_HOST	AgentServer のバインド先	0.0.0.0
GATEWAY_HOST	Gateway のバインド先	0.0.0.0

セキュリティグループの設定（クラウド側）

1. Flexus L コンソールにログインします。
2. JiuwenSwarm インスタンスを探し、インスタンスの詳細 → セキュリティ／ネットワークを開きます。
3. セキュリティグループのルールを設定し、ポート 5173（TCP のインバウンド）を開放します。

アクセス URL：http://<instance_public_ip>:5173 セキュリティに関する警告：ポートを開放すると、JiuwenSwarm の Web インターフェースにアクセスできるようになります。有効にする前に、セキュリティリスクを評価してください。必要な場合にのみ一時的に開放し、使用後は閉じることをお勧めします。

---

Huawei Cloud の認証情報の設定

認証情報の優先順位：hcloud 設定ファイル → 環境変数。

オプション 1：hcloud CLI 設定ファイル（推奨）

認証情報は ~/.hcloud/config.json から読み取られます。暗号化が有効になっている場合（authEncrypt=true）、スクリプトはプレーンテキストの値を読み取れるように、自動的に暗号化を無効にします。

# Permanent credentials
hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<AK> --cli-secret-key=<SK>

# Temporary credentials (STS Token)
hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<AK> --cli-secret-key=<SK> --cli-security-token=<TOKEN>

環境変数は不要です。スクリプトは設定ファイルから直接読み取ります。

オプション 2：環境変数（代替）

環境変数	説明	必須
HUAWEICLOUD_SDK_AK	アクセスキー（永続または一時）	はい
HUAWEICLOUD_SDK_SK	シークレットキー（永続または一時）	はい
HUAWEICLOUD_SDK_SECURITY_TOKEN	セキュリティトークン（STS のみ）	いいえ
HUAWEICLOUD_REGION	Huawei Cloud のリージョン（デフォルト：cn-north-4）	いいえ

参考：https://support.huaweicloud.com/iam_faq/iam_01_0620.html

---

主な API エンドポイント

サービス	エンドポイント	用途
Flexus L	https://hcss.{region}.myhuaweicloud.com/v1/light-instances	インスタンスの作成／照会
IAM	KooCLI：hcloud IAM KeystoneListProjects --cli-region=<region> [--name=<region>]	プロジェクト ID／ドメイン ID の取得（グローバルサービス。有効な認証情報があれば、hcloud がドメイン ID を自動解決します）
RMS	KooCLI：hcloud RMS ListAllResources --cli-region=cn-north-4 --cli-domain-id=<domain_id> [--region_id=<region>] [--type=hcss.l-instance]	リソースの照会（グローバルサービス：常に統一された cn-north-4 エンドポイントを使用し、region_id パラメーターで対象リージョンを絞り込みます）
COC	https://coc.myhuaweicloud.com/v1/job/scripts/{script_uuid}	リモートスクリプトの実行（グローバルサービス：SDK クライアントは常に cn-north-4 エンドポイントを使用し、各対象インスタンスのリージョンはリクエスト本文に含めます）

対応リージョン：cn-north-4（北部・北京 4）、cn-east-3（東部・上海 1）、cn-south-1（南部・広州）、cn-southwest-2（南西部・貴陽 1）

システムイメージ：Ubuntu 24.04 LTS

---

出力規約

成功時の出力テンプレート

============================================================
  JiuwenSwarm COC Deployment - Complete
============================================================

Target Instance:
  Name: {instance_name}
  ID: {instance_id}
  IP: {public_ip}

COC Execution:
  Execute UUID: {execute_uuid}
  Status: FINISHED

Deployment Result:
  Web Access: http://{public_ip}:5173
  Port Binding: 0.0.0.0:5173 (verified)
  Submit Time: {submit_time}

NOTE: Huawei Cloud security group must allow inbound TCP 5173
      for external web access. Configure at:
      https://console.huaweicloud.com/smb/?/resource/list

============================================================
[SUCCESS] Deployment task completed!
============================================================

エラー時の出力テンプレート

============================================================
[ERROR] Deployment Failed
============================================================

Error: {error_message}

Suggestions:
  1. Check Huawei Cloud credentials
  2. Verify instance status
  3. Check deployment logs

============================================================

---

参考ドキュメント

以下の参考ドキュメントでは、このスキルについて詳しく説明しています。

ドキュメント	説明
references/api-specs.md	Huawei Cloud サービス（Flexus L、IAM、RMS、COC）の API 仕様
references/iam-policies.md	デプロイ用の IAM 権限ポリシーとポリシー JSON
references/deployment-checklist.md	すべてのフェーズを対象としたデプロイ前後のチェックリスト
references/verification-method.md	検証方法と受け入れテストの手順
references/acceptance-criteria.md	受け入れ基準と承認要件
references/troubleshooting.md	一般的なデプロイの問題に関するトラブルシューティングガイド