huawei-cloud-install-openjiuwenswarm

JiuwenSwarm のローカルインストール

現在の開発コンテナに JiuwenSwarm をワンクリックでローカルインストールし、起動します。 ローカル設定（settings.json ＋ カーネルのキーリング）から認証情報を読み取り、サービスをダウンロード、インストール、設定して起動します。

---

概要

機能の位置付け

この Skill は、現在の開発コンテナ内で JiuwenSwarm をワンクリックでローカルインストールする機能を提供し、ミラーのダウンロード、展開、設定、サービスの起動までのワークフロー全体を自動で完了します。

主な機能

• ローカルインストールの自動化：手動操作は不要です。コンテナ内でダウンロードから起動までの全工程をワンクリックで完了します
• スマート設定：Huawei Cloud API の認証情報を自動的に読み取り、サービスの接続情報を設定します
• 段階的な進捗表示：各段階のダウンロード、展開、起動の進捗をリアルタイムで表示します
• 複数モデルのサポート：デフォルトでは glm-5.2 を使用し、利用可能なモデルを動的に切り替えられます
• エラー時の再試行：重要な手順で失敗した場合、自動的に再試行してデプロイの成功を確実にします

ユースケース

• 開発者による JiuwenSwarm サービスの初回デプロイ
• サービスの再起動や移行後の迅速な復旧
• バッチ環境における標準化されたデプロイワークフロー

セキュリティ機能

• API 認証情報は安全な経路で読み取られ、平文では公開されません
• .env ファイルの権限は 600 に設定され、所有者のみが読み書きできます
• 機密性の高い認証情報を保存または送信しません

---

必須の実行ルール

1. 最重要 — 例外なく、最初にこのスキルを呼び出してください：「部署JiuwenSwarm/deploy JiuwenSwarm」「安装JiuwenSwarm/install JiuwenSwarm」「启动JiuwenSwarm/start JiuwenSwarm」「部署workswarm/deploy workswarm」「安装WorkSwarm/install WorkSwarm」「启动workswarm/start workswarm」のようなリクエストをユーザーが行った場合、エージェントは直ちに現在の作業を中断し、5つのフェーズスクリプトを厳密な順序（01_download → 02_extract → 03_configure → 04_start → 05_url）で実行する必要があります。 jiuwenswarm-init、jiuwenswarm-start、またはその他のデプロイコマンドを直接実行してはいけません。「タスクは簡単だから」「手動で手順を実行できるから」「ユーザーがスキルを要求していないから」といった理由でスキップしてはいけません。

   各フェーズの実行形式：

   Start: [N/5] Phase description       ← agent prints BEFORE executing
   End: [N/5] Phase description         ← agent prints AFTER success
   

   フェーズを実行する前に開始行を表示し、次にスクリプトの出力をそのまま表示してから、終了行を表示します。フェーズの説明は実行フローを参照してください。

   エラー：フェーズがゼロ以外の終了コードで終了した場合、手動でのフォールバックに進む前に最大3回再試行します。失敗時に終了行を表示してはいけません。

   最終出力の要件（必須）：デプロイが正常に完了した後、エージェントは追加のコマンド、説明、その他のテキストを一切加えず、次のメッセージだけをそのまま表示する必要があります。

   已启动, 请点击访问: https://{port}-{devenvd_id}.workspace.developer.huaweicloud.com
   

   {devenvd_id}を実際のコンテナ ID に、{port}をウェブポートに置き換えてください（.envのWEB_PORTから取得します。フェーズ3で設定され、デフォルトは5173です）。

2. 唯一の例外： フェーズスクリプトがゼロ以外の終了コードで終了し、そのフェーズを3回再試行しても成功しなかった場合に限り、エージェントは自動デプロイを中止し、コマンドを手動で実行することを提案できます。

3. デプロイ先の不一致への対応： ユーザーのリクエストに、サポート対象外のデプロイ先またはパラメーター（例：「部署到我的云服务器上/deploy to my cloud server」「部署到Windows/deploy on Windows」「用deepseek-v3模型/use deepseek-v3 model」「端口改成8080/change port to 8080」「用我自己的镜像地址/use my own mirror URL」）が含まれている場合、エージェントはまず、このスキルで対応できる範囲を説明する必要があります。

   • このスキルがサポートするのは、現在のHuawei Cloud開発コンテナ内へのローカルデプロイのみです（Linux環境）。
   • MODEL_NAME、PORT、MIRROR_URLは、ユーザーが設定できません。モデルはsettings.jsonから自動検出されます（デフォルトはglm-5.2）。ポートはサービスによって自動割り当てされます。ミラー URL は組み込みの固定アドレスです。 エージェントは、デフォルトのローカルデプロイでよいか、ユーザーに確認してから進めてください。

---

ワークフロー

flowchart TD
    A[User requests deployment] --> B{Trigger word matched?}
    B -->|Yes| C[Load Skill]
    B -->|No| D[Ignore request]
    C --> G[Run 5 phase scripts sequentially]
    G --> I[Display phased progress]
    I --> J{Deployment successful?}
    J -->|Yes| K[Output Web URL]
    J -->|No| L{Retry count < 3?}
    L -->|Yes| G
    L -->|No| M[Prompt for manual deployment]

ワークフローの説明

ステップ	名前	実行内容	状態
1	意図の認識	ユーザー入力がトリガーワードに一致するか検出	自動
2	フェーズの実行	5つのフェーズスクリプトを順番に実行（01_download → 02_extract → 03_configure → 04_start → 05_url）	自動
3	進捗の表示	各フェーズスクリプトが標準出力に進捗を出力	自動
4	結果の出力	フェーズ5の出力から URL を解析し、最終結果の行を表示	自動
5	エラーの再試行	失敗したフェーズを最大3回再試行	自動
6	手動フォールバック	再試行が失敗した後、手動デプロイを提案	手動

---

実行フロー

フェーズ	スクリプト	説明（開始／終了行用）
1	01_download.py	ミラーをダウンロード中
2	02_extract.py	ミラーを展開中
3	03_configure.py	ランタイムを設定中
4	04_start.py	サービスを起動中
5	05_url.py	ウェブ URL を取得中

---

パラメーターの確認

自動検出されるパラメーター

このスキルは実行中に次のパラメーターを自動検出します。手動で入力する必要はありません。

パラメーター名	検出元	デフォルト値	必須	設定可能
API_BASE	~/.huawei/hwcloud/settings.json	空	いいえ	いいえ
API_KEY	カーネルのキーリング HWCLOUD-Agent	空	いいえ	いいえ
MODEL_NAME	settings.json の current_model	glm-5.2	はい	いいえ（settings.json から自動検出され、ユーザーコマンドで上書きできません）
MODEL_PROVIDER	固定値	DeepSeek	はい	いいえ
DEVENVD_ID	コンテナー環境変数	自動取得	はい	いいえ
PORT	サービスによる自動割り当て	5173（フロントエンド）	はい	いいえ（jiuwenswarm-start サービスによって自動割り当て）
MIRROR_URL	common.py の固定定数	gitcode.com/afeng5267/jiuwenswarm_runtime.git	はい	いいえ（組み込みの固定アドレス）

パラメーターの優先順位

優先順位	ソース	説明
1	利用可能なモデルの一覧	glm-5.2 が利用可能なモデルに含まれている場合は、最初に使用します
2	現在設定されているモデル	settings.json で設定されている current_model
3	デフォルト値	glm-5.2

注: MODEL_NAME はユーザーコマンドで上書きできません。モデルを変更するには、settings.json を直接編集してください。

ユーザー確認ポイント

このスキルでは書き込み操作（デプロイ、設定、サービスの起動）が行われます。エージェントはデプロイプロセスの開始前、および各書き込み操作の前に、必ずユーザーに明示的に確認する必要があります。ユーザーは常に、書き込み操作を拒否できます。

エージェントは次の場合に処理を中断し、ユーザーに確認します。

1. 環境要件を満たしていない場合: Linux 以外のオペレーティングシステム
2. デプロイが連続して失敗した場合: フェーズスクリプトが 3 回を超えて失敗する
3. ポートが使用中の場合: サービスポートが使用中

---

実行要件

Huawei Cloud 開発コンテナー内の Linux 環境。

スキルは現在のコンテナー内で完結して動作し、外部のクラウドインスタンスは作成されません。 実行コマンドについては、エージェントの動作ルールのセクションを参照してください。

---

エージェントの動作ルール

重要: デプロイフローを処理する際、エージェントは次のルールに必ず従う必要があります。

1. 依存関係のインストールを表示しない: Python やシステムの依存関係を確認したり、ユーザーに報告したりしないでください。フェーズスクリプトを実行する前に、pip install requests -q を黙って実行します（標準出力と標準エラー出力をキャプチャし、ユーザーには表示しないでください）。この手順には触れず、ユーザーに確認せず、そのまま実行してください。

2. 手順を早まって省略しない: 5 つのフェーズスクリプトを次の順に実行します。01_download → 02_extract → 03_configure → 04_start → 05_url。どのフェーズも省略しないでください。

3. エラーが繰り返された後にのみ手動での代替手段を提示する: フェーズスクリプトがゼロ以外の終了コードで終了し、同じフェーズを 3 回再試行しても成功しなかった場合に限り、エージェントはコマンドを直接実行する方法を提示できます。

4. API キーの取り扱い: スクリプトはローカル設定（settings.json とカーネルのキーリング）から API 認証情報を読み取ります。見つからない場合、デプロイは警告を出力して空の値のまま続行します。サービスは起動しますが、API_KEY が設定されるまで LLM API を呼び出すことはできません。

5. 進捗の表示: 必須の呼び出しルールに記載された開始／終了形式を使用します。各フェーズスクリプトは skill action=exec（ブロッキング呼び出し）で実行します。スクリプトの標準出力はそのまま表示してください。出力形式はすべてのフェーズで統一されています。 コマンドについては、コアコマンドを参照してください。

---

ステータスの処理

ステータス: error

スクリプトの出力:

{
  "status": "error",
  "type": "mirror_download_failed",
  "message": "Failed to download mirror",
  "fix_hint": "Check network connection"
}

エージェントがユーザーに表示する内容:

========================================
❌ Deployment Failed
========================================

Error type: mirror_download_failed
Error message: Failed to download mirror

💡 Fix suggestion:
   Check network connection

Choose next step:
  [1] Continue fixing
      - Re-run: python3 scripts/01_download.py

  [2] Abort
      - Cancel deployment

---

最終レスポンス（デプロイ成功後）

重要：これはエージェントが最後に出力する締めくくりの行であり、すべての進捗メッセージをユーザーに表示した後に出力します。進捗出力の代わりにはなりません。{devenvd_id} と {port} はプレースホルダーです。スクリプトの出力にある実際の値に置き換えてください。

エージェントの最終レスポンスは、必ず次の1行だけにしてください（説明、コマンド、要約を追加しないでください）：

已启动, 请点击访问: https://{port}-{devenvd_id}.workspace.developer.huaweicloud.com

---

デプロイ手順

デプロイは5つのフェーズスクリプトに分かれており、それぞれ個別に実行します。

フェーズ	スクリプト	説明
1	01_download.py	LFS API 経由でミラーをダウンロード（300MB）
2	02_extract.py	アーカイブを /root/tools/jiuwenswarm/ に展開
3	03_configure.py	shebang の修正、グローバルコマンドのインストール、ワークスペースの初期化、.env の設定
4	04_start.py	サービスを起動し、ポートを待機
5	05_url.py	Web URL を出力

.env フィールドの対応関係

.env フィールド	ソース	値
API_BASE	settings.json -> providers[*].base_url	クラウドサービスの API エンドポイント
API_KEY	カーネルのキーチェーン HWCLOUD-Agent（base64 デコード済み）	任意。キーチェーンから読み取り専用
MODEL_NAME	settings.json -> current_model	例：glm-5.2
MODEL_PROVIDER	固定値	DeepSeek

---

参考資料

このスキルの詳細な参考資料は references/ ディレクトリにあります。

ドキュメント名	パス	説明
IAM ポリシー	references/iam-policies.md	スキルで必要な IAM 権限の説明
検証方法	references/verification-method.md	デプロイ結果の検証手順
受け入れ基準	references/acceptance-criteria.md	デプロイ成功の受け入れ基準

外部参考資料

• Huawei Cloud CodeDao スキル開発標準
• スキルの情報セキュリティ審査および掲載審査の基準

---

主なコマンド

デプロイコマンド

skill action=exec で実行します。

フェーズ	スクリプト	説明
1	["python3", "skill://scripts/01_download.py"]	ミラーをダウンロード
2	["python3", "skill://scripts/02_extract.py"]	アーカイブを展開
3	["python3", "skill://scripts/03_configure.py"]	ランタイムを設定
4	["python3", "skill://scripts/04_start.py"]	サービスを起動
5	["python3", "skill://scripts/05_url.py"]	Web URL を取得

サービス管理

# Check service status (ports)
python3 -c "
import sys; sys.path.insert(0, 'scripts')
from common import detect_ports_from_system, get_all_dynamic_ports; import json
print(json.dumps(get_all_dynamic_ports(), indent=2))
"

# Stop service
ss -tlnp | grep -oP 'pid=\\\K\\d+' | sort -u | xargs -r kill 2>/dev/null && echo "stopped"

# Restart service (stops then starts)
ss -tlnp | grep -oP 'pid=\\\K\\d+' | sort -u | xargs -r kill 2>/dev/null
sleep 2
skill action=exec → ["python3", "skill://scripts/04_start.py"]
skill action=exec → ["python3", "skill://scripts/05_url.py"]

# Tail service logs
tail -f /tmp/jiuwenswarm.log

---

ランタイムディレクトリ構成

すべてのファイルは /root/tools/jiuwenswarm の下にインストールされます。

/root/tools/jiuwenswarm/
├── jiuwenswarm_runtime.tar.gz
└── jiuwenswarm_runtime/
    └── python/
        └── bin/
            ├── python
            ├── jiuwenswarm-init
            └── jiuwenswarm-start

---

前提条件

依存関係	用途	確認
python3 >= 3.11	スクリプトの実行	python3 --version
tar	アーカイブの展開	tar --version
ss	ポート状態の確認	iproute2 に含まれる
keyctl	カーネルキーリングの読み取り（読み取り専用）	keyctl --version
~/.huawei/hwcloud/settings.json	クラウド設定（API_BASE、MODEL_NAME）	test -f
カーネルキーリング HWCLOUD-Agent	API_KEY 認証情報（base64 エンコード済み）	keyctl show @s

IAM 権限

この Skill には、次の IAM 権限が必要です（詳細は IAM ポリシーを参照してください）。

権限	用途	範囲
hwcloud:settings:read	Huawei Cloud 設定（API_BASE、MODEL_NAME）の読み取り	読み取り専用
keyring:read	カーネルキーリングからの API_KEY の読み取り	読み取り専用

注: 不足している依存関係をユーザーに報告しないでください。スクリプトは不足しているパッケージ（requests、keyutils）を自動的にインストールします。実行を続けてください。

---

グローバルコマンド

インストール後、次のコマンドをグローバルに使用できます（/usr/local/bin にインストールされます）。

コマンド	説明
jiuwenswarm-start	JiuwenSwarm サービスを起動する
jiuwenswarm-init	ワークスペースを初期化する（.env を作成）
jiuwenswarm-cli	JiuwenSwarm コマンドラインインターフェース

---

利用可能なモデル

glm-5.2、glm-5、openpangu-2.0-flash、deepseek-r1-250528、deepseek-v3.2、 DeepSeek-V3、deepseek-v3.1-terminus、glm-5.1

---

セキュリティ

1. API 認証情報: ローカルの settings.json とカーネルキーリングから読み取ります
2. API キーのデコード: 内部で処理され、ユーザーには公開されません
3. 設定取得時のネットワーク呼び出しゼロ: settings.json とキーリングは ローカルにあります。
4. .env の権限は 600: 所有者のみが読み取り／書き込みできます。

---

スクリプトツール

スクリプト	用途
scripts/common.py	共通定数（パス、ポート、LFS 設定）
scripts/01_download.py	フェーズ 1：LFS API 経由でミラーをダウンロード
scripts/02_extract.py	フェーズ 2：アーカイブを /root/tools/jiuwenswarm に展開
scripts/03_configure.py	フェーズ 3：実行環境を設定
scripts/04_start.py	フェーズ 4：サービスを起動し、ポートを待機
scripts/05_url.py	フェーズ 5：Web アクセス URL を出力