alibabacloud-wxz-website-builder

Category: サービス

AI スタッフ Web サイトビルダー

検証

mkdir -p output/alibabacloud-wxz-website-builder
for f in skills/ai/service/alibabacloud-wxz-website-builder/scripts/*.py; do
  python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/alibabacloud-wxz-website-builder/validate.txt

合格条件：コマンドが 0 で終了し、output/alibabacloud-wxz-website-builder/validate.txt が生成されること。

出力とエビデンス

• list／summarize の出力は output/alibabacloud-wxz-website-builder/ の下に保存します。
• 各エビデンスファイルに会話 ID とイベントの概要を記録します。

前提条件

pip install -r requirements.txt

• すべての依存関係のバージョンは requirements.txt で厳密に固定されています。
• 認証情報はデフォルトの認証情報チェーンで解決されます（AK／SK を明示的に指定する必要はありません）。

認証

このスキルは Alibaba Cloud のデフォルト認証情報チェーンを使用します。AK／SK を明示的に設定しないでください。SDK は次の順序で認証情報を自動的に解決します。

1. 環境変数：ALIBABACLOUD_ACCESS_KEY_ID／ALIBABACLOUD_ACCESS_KEY_SECRET
2. 共有設定ファイル：~/.alibabacloud/credentials
3. RAM ロール／ECS メタデータサービス（Alibaba Cloud インスタンスで実行している場合）

リージョン：ALIBABACLOUD_REGION_ID のデフォルトは cn-hangzhou です。

AccessKey の取得方法（ユーザーが持っていない場合）

ユーザーがまだ AccessKey を持っていない場合は、次の手順を案内してください（詳細は references/ak-setup-guide.md を参照してください）。

1. ログイン：https://www.aliyun.com を開いてログインする（または登録する）
2. RAM ユーザーを作成：https://ram.console.aliyun.com/users に移動し、「Create User」を選択 → 「OpenAPI Access」にチェックを入れる → AK／SK をすぐに保存する（Secret が表示されるのは一度だけです！）
3. 権限を付与：最小権限となるよう、次の Actions を含むカスタムポリシーを追加します。
   • zero2staff:CreateAIStaffConversation
   • zero2staff:CreateAIStaffChat
   • zero2staff:ListAIStaffChatEvents
   • zero2staff:ListAIStaffChatMessages
   • zero2staff:GetAIStaffPreviewUrl
4. 設定：~/.alibabacloud/credentials に書き込むか、環境変数を設定します。

重要：ユーザーを案内する際は、次の点を必ず伝えてください。

• root アカウントの AccessKey は使用せず、必ず RAM サブユーザーを使用してください。
• AccessKey Secret は作成時に一度だけ表示されるため、すぐに保存してください。
• AccessKey を Git にコミットしないでください。

認証エラーが発生した場合は、references/ak-setup-guide.md のトラブルシューティング表を参照してください。

---

アプリケーションのライフサイクル

一連の処理は 3 つのフェーズで構成されています。順番に進めてください。

重要 — エージェント主導のポーリング：chat コマンドはリクエストを送信し、すぐに戻ります。その後、エージェントが poll コマンドを使ってポーリングループを進めます。各ポーリングの間に、状況がわかるよう、エージェントは必ずユーザーに進捗メッセージを表示してください（詳細なメッセージには progressDetail を使用します）。

Phase 1: Create Conversation
        ↓
Phase 2: Fire requirement chat → poll → HITL → Fire resume → poll → ... → PRD ready
        ↓
Phase 3: Fire code generation → Show link → poll loop with progress → Get preview URL → Done

フェーズ 0：認証の設定

上記の「認証」セクションを参照し、デフォルトの認証情報チェーンで Alibaba Cloud の認証情報が設定されていることを確認します。

フェーズ 1：会話の作成

チャット操作を行う前に、必ず会話を作成してください。

CONV=$(python scripts/aistaff_api.py create-conversation --text "build a popmart homepage")
CONV_ID=$(echo $CONV | jq -r '.ConversationId')
CHAT_ID=$(echo $CONV | jq -r '.ChatId')
SITE_ID=$(echo $CONV | jq -r '.SiteId')

フラットな JSON を返します：{ConversationId, SiteId, ChatId, SectionId, BotId, Title}。

フェーズ 2：要件の収集と PRD

このフェーズでは、要件を収集して PRD を生成します。プラットフォームから複数回の HITL ラウンド（基本情報 → 機能 → 言語など）を求められる場合があります。処理を速く進めるため、次のようにしてください。

• 最初の HITL ラウンドのみをユーザーに表示します（プロジェクトの基本情報）。
• それ以降のすべての HITL ラウンドでは、フォームのデフォルト値または事前選択値を自動入力し、すぐに再開してください。ユーザーに尋ねないでください。

ステップ 1：要件収集を開始する

python scripts/aistaff_api.py chat \
  --text "build a popmart homepage" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID

ユーザーに次のように伝えます：「要件を分析しています。しばらくお待ちください…」

ステップ 2：最初の HITL フォームが届くまでポーリングする

phase が waiting_for_input になるまで、5 秒ごとに poll を呼び出します。

python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --last-event-id 0

各ポーリングの間に、phase に応じた進捗メッセージをユーザーに表示します。

• processing → 「要件を分析しています…」
• fetching_reference → 「参照サイトの情報を取得しています…」
• waiting_for_input → 最初の HITL フォームが届きました。ステップ 3 に進みます。

ステップ 3：最初の HITL — ユーザーから回答を収集する

name: "AskUserQuestion" の message.tool イベントの metaData.arguments から questions を抽出します。AskUserQuestion ツールを使って、これらの質問をユーザーに提示します（通常は、アプリ名、ビジネスの説明、対象ユーザー、参考サイトです）。

ステップ 4：--phase generate_prd を指定して再開を実行する

重要：最初の HITL の再開時には、必ず --phase generate_prd --user-navigation generate_prd を渡してください。

python scripts/aistaff_api.py chat \
  --text '{"App Name": "POP MART Official", "Main Service": "Trendy Toys", "Target Users": "Gen Z trendsetters", "Reference Site": "None"}' \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --chat-id $CHAT_ID \
  --chat-status interrupt \
  --phase generate_prd \
  --user-navigation generate_prd \
  --hidden --without-refer

--text の JSON キーは、フォームの header の値と一致しなければなりません。

ユーザーに次のように伝えます：「要件を受け取りました。プロダクト計画を作成しています……」

ステップ 5：PRD の準備ができるまでポーリングを繰り返す — 以降の HITL には自動で回答する

5 秒ごとにポーリングします。phase / summary に基づいて対応します。

• phase == "waiting_for_input"（別の HITL 質問）→ AskUserQuestion イベントの answers フィールドを使ってすぐに自動入力し、再度再開を実行します。ユーザーに次のように伝えます：「要件の詳細を調整しています……」
• phase == "generating_prd" → ユーザーに次のように伝えます：「PRD を作成しています。しばらくお待ちください……」
• phase == "fetching_reference" → ユーザーに次のように伝えます：「参考資料を取得しています……」
• summary.chatStatus == "success" + summary.hasPrd == true → PRD の準備ができたため、フェーズ 3 に進みます。
• summary.chatStatus == "fail" → 再試行するかどうかをユーザーに尋ねます。

# Poll:
python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID --biz-id $SITE_ID --last-event-id $LAST_EVENT_ID

# Auto-fill (use the "answers" field from the AskUserQuestion event):
python scripts/aistaff_api.py chat \
  --text '{"Core Features": ["Product Showcase", "Brand Story", "News"]}' \
  --conversation-id $CONV_ID --biz-id $SITE_ID --chat-id $CHAT_ID \
  --chat-status interrupt --phase generate_prd \
  --user-navigation generate_prd --hidden --without-refer

重要なルール：プラットフォームの AskUserQuestion イベントには、常に妥当なデフォルト値を含む answers フィールドがあります。最初のラウンド以降は、必ずこれらのデフォルト値をそのまま使用し、ユーザーに質問しないでください。

フェーズ 3：コード生成

PRD の準備ができたら：

ステップ 1：コード生成を実行する

python scripts/aistaff_api.py chat \
  --text "Confirm app generation" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --phase generate_code \
  --without-refer

ステップ 2：サイトのリンクをすぐに表示する

コード生成の前後に必ず表示してください：

https://wanwang.aliyun.com/webdesign/home#/ai/manage/prd?conversationId=<CONV_ID>

ユーザーに次のように伝えます：「コード生成を開始しました。通常は 2～5 分かかります。進捗を確認している間、上のリンクからプロジェクトをご確認いただけます……」

ステップ 3：進捗状況を更新しながらポーリングを繰り返す

10 秒ごとにポーリングします。各ポーリングの間に、ユーザーに進捗状況を表示します。

python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID --biz-id $SITE_ID --last-event-id $LAST_EVENT_ID

進捗メッセージ（詳細なメッセージには progressDetail を使用してください）：

• phase == "processing" + latestFile が存在する → 「コードを生成しています……書き込み中：{latestFile.semantic}（{filesWrittenCount} 個のファイルを生成済み）」
• phase == "processing" + latestFile が存在しない → 「コードを生成しています……{N} 件のイベントを処理済み」
• phase == "processing" + lastMessage が存在する → コンテキストとして、アシスタントの最新メッセージも表示します。
• phase == "success" → サイトの準備ができました！ステップ 4 に進みます。
• phase == "fail" → 再試行するかどうかをユーザーに尋ねます。

ステップ 4：プレビュー URL を取得する

コード生成が完了した後（summary.chatStatus == "success"）、必ずこれを呼び出してください。プレビュー用サンドボックスを起動し、ライブプレビュー URL を返します。

PREVIEW=$(python scripts/aistaff_api.py get-preview-url --conversation-id $CONV_ID)
PREVIEW_URL=$(echo $PREVIEW | jq -r '.urlMap.https // .urlMap.http // empty')

ユーザーに次のように伝えます：「サイトが完成しました！プレビュー URL を取得しています……」

サンドボックスの起動に数秒かかる場合があるため、最初の呼び出しには時間がかかることがあります。プレビュー URL がまだ利用できない場合は、10 秒後に再試行します（最大 3 回）。プレビュー URL を次のように表示します：「プレビュー URL：{PREVIEW_URL}」

--restart：サンドボックス内でアプリを再起動する場合（変更後など）は、--restart を渡します。初回ビルドでは不要です。

ステップ 5：完了を処理する

• summary.chatStatus == "success" → サイトの準備ができました。サイトのリンクとプレビュー URL を表示します。
• summary.chatStatus == "fail" または summary.hasError == true → ユーザーに再試行するかどうかを尋ねます。自動で再試行してはいけません。

初回生成後

• サイトを変更するには、--conversation-id を指定して chat を使用します。
• 各変更では、同じ chat + poll のパターンを使用します。
• 各変更の完了後に get-preview-url --restart を呼び出して、プレビューを更新します。
• 各変更後に、サイトのリンクとプレビュー URL を再度表示します。

判断テーブル

summary.chatStatus	summary.hasPrd	フェーズ	アクション
interrupt	—	2（初回）	AskUserQuestion を解析し、ユーザーから回答を収集して、--phase generate_prd で再開します
interrupt	—	2（2回目以降）	AskUserQuestion イベントのデフォルト answers を使って自動入力し、すぐに再開します。ユーザーには質問しないでください
success	true	2	PRD の準備が完了 → フェーズ 3 に進みます
success	false	3	サイトの準備が完了 → get-preview-url を呼び出し → リンクとプレビュー URL を表示します
fail	—	任意	再試行するかどうかをユーザーに尋ねます
unknown	—	任意	ポーリングがタイムアウトしました → list-messages にフォールバックします

---

利用可能なコマンド

create-conversation

python scripts/aistaff_api.py create-conversation --text "user question"

戻り値：{ConversationId, SiteId, ChatId, SectionId, BotId, Title}。

chat

非同期のチャットメッセージを送信し、すぐに戻ります。送信前に古い SSE イベントを自動的にドレインします。進捗を追跡するには、その後 poll を使用します。

python scripts/aistaff_api.py chat --text "description" --conversation-id <ID> --biz-id <ID> [options]

主なパラメーター：

• --text TEXT：メッセージテキストまたはフォーム回答の JSON（必須）
• --conversation-id ID / --biz-id ID：必須の識別子
• --chat-id ID + --chat-status interrupt：HITL の再開用
• --phase {requirement_collect,generate_prd,generate_code}：開始するフェーズ
• --user-navigation TARGET：ナビゲーション先（--phase generate_prd とともに generate_prd を使用）
• --hidden / --without-refer：メッセージを非表示にする／参照コンテキストを省略する
• --verbose：デバッグ情報を表示する

戻り値：{conversationId, chatId, status: "fired", error}。

poll

単発のステータス確認 — 新しいイベントを一度取得し、メッセージのステータスを確認して、すぐに戻ります。エージェント主導のポーリングループ向けに設計されています。

python scripts/aistaff_api.py poll --conversation-id <ID> --biz-id <ID> [--last-event-id N]

主なパラメーター：

• --last-event-id N：前回のポーリングで使用したカーソル（デフォルト：0）。前回の poll 結果の lastEventId を渡します。
• --max-output-events N：出力イベント数の上限（デフォルト：10、0＝無制限）

戻り値： {conversationId, lastEventId, newEvents, phase, summary, progressDetail, events}

summary のフィールド： chatStatus、hasError、errorMsg、hasPrd、toolsCalled

progressDetail のフィールド — 情報量のある進捗メッセージを作成するために使用します：

• filesWrittenCount：これまでに生成されたファイルの合計数
• activeTools：現在進行中のツール（status=wait）。すべて完了すると空になります
• latestFile：{path, semantic, status} — 直近で書き込み中のファイル（ユーザーには semantic を表示します）
• allFiles：書き込まれたファイルの完全な一覧。それぞれに path と semantic が含まれます
• lastMessage：最新のアシスタントテキストメッセージ（200 文字に切り詰め）
• toolProgress：ツールごとのステータス一覧。name、status（wait／done）、semantic が含まれます

推奨される進捗メッセージ：

• latestFile.status == "wait"：「生成中：{latestFile.semantic}...」
• latestFile.status == "done" + activeTools が空：「{filesWrittenCount} 個のファイルが完了しました。次のステップを待っています...」
• filesWrittenCount > 0 + activeTools が空でない：「コードを生成中... {filesWrittenCount} 個のファイルが完了し、書き込み中：{latestFile.semantic}」
• lastMessage が空でない：追加のコンテキストとして表示します

phase の値：

フェーズ	意味	推奨されるユーザーメッセージ
processing	一般的な処理中	「処理中...」
fetching_reference	参照サイトを取得中	「参照サイトの情報を取得中...」
waiting_for_input	HITL フォームの準備完了	（フォームを解析して処理します）
generating_prd	PRD を生成中	「PRD を生成中...」
success	正常に完了	「完了しました！」
fail	失敗	（再試行するかどうかをユーザーに尋ねます）

list-messages

最新のチャットメッセージを照会します。直近の N 件のメッセージを返します（デフォルト：10）。

python scripts/aistaff_api.py list-messages --conversation-id <ID> [--tail 10]

主な用途：ポーリングで進捗が見られない場合に、最後のメッセージの ChatStatus を確認するために使用します。

get-preview-url

コード生成後に、ライブプレビューの URL を取得します。必要に応じてサンドボックスを起動します。

python scripts/aistaff_api.py get-preview-url --conversation-id <ID> [--restart]

パラメーター： --conversation-id ID（必須）、--restart（サンドボックス内のアプリを再起動します。変更後に便利です）

戻り値： {urlMap: {https: "...", http: "...", sessionId: "..."}}

フェーズ 3 で chatStatus == "success" になった後に、必ず呼び出してください。初回の呼び出しでは、サンドボックスの起動に数秒かかることがあります。URL が空の場合は、10 秒後に再試行してください（最大 3 回）。

---

SSE イベントの制約

• 新しいチャットラウンドごとに、前回の SSE イベントが消去されることがあります。chat コマンドは実行前に、古いイベントを自動的にドレインします。
• poll を使用する場合は、イベントの再処理を避けるため、前回のポーリング結果の lastEventId を渡してください。
• コード生成中、プラットフォームが「magic fix」ラウンドを複数回自動的にトリガーすることがあります。poll コマンドは、イベントの概要からこれを検出します。

---

エラー処理

エラー	対応
認証エラー	デフォルトの認証情報チェーン（環境変数、設定ファイル、または RAM ロール）で認証情報が設定されていることを確認してください
summary.chatStatus == "fail"	再試行するかどうかをユーザーに確認してください。自動で再試行してはいけません
5 分以上ポーリングしても進展がない	実際のステータスを確認するため、list-messages を使用してください