gemdesign-skill

GemDesign プロトタイピング

gemdesign CLI を使用して、GemDesign プラットフォーム上で高精度なプロトタイプページを作成、保存、変更します。GemDesign Page Spec に従って HTML を生成し、検証してから CLI 経由で保存します。

実行するタイミング

• ユーザーが UI プロトタイプの作成やページのデザインを希望する場合
• ユーザーが要件ドキュメントを持っており、ページを一括生成したい場合
• ユーザーが既存の GemDesign ページを変更したい場合
• ユーザーが既存の GemDesign ページを表示したい場合

前提条件

重大：ワークフローを開始する前に、ステップ 1、ステップ 2、ステップ 2.5 を必ず順番どおりに実行してください。次のステップに進む前に、各ステップを完全に完了させる必要があります。現在のステップの成功が確認されるまで、スキップ、並列実行、先への移行を行わないでください。

重要 — ステップ 3 の実行タイミング：ステップ 3（ローカルサーバーの起動）は、ログイン直後には実行しません。必ずワークフロー内で、アプリを作成または再利用した後（つまり、gemdesign app create / gemdesign app use と gemdesign app info の実行後）、ページ生成の前に実行してください。アプリが存在する前にサーバーを起動するのは違反です。サーバーはアプリから派生したプロジェクトのサブディレクトリにあるページを配信するため、先にアプリが存在している必要があります。

ステップ 1：GemDesign CLI の確認とインストール（ステップ 2 の前に必ず完了すること）

ほかの作業を始める前に、必ず CLI のインストール状況とバージョンを確認してください。 このステップは必須条件です。このステップの完了が確認されるまで、ほかの操作（auth、app、page、style など）を実行してはいけません。

1. CLI がインストールされているか確認します：

   npm list -g @gemdesign-ai/cli
   

   • コマンドがバージョン情報（例：@gemdesign-ai/[email protected]）を返した場合、CLI はインストール済みです。ステップ 2 に進みます。
   • コマンドが空の結果またはエラー（例：(empty) や ERR!）を返した場合、CLI はインストールされていません。次を実行します：

     npm install -g @gemdesign-ai/cli
     

     インストールが完了するまで待ち、その後 npm list -g @gemdesign-ai/cli で再確認します。再確認でインストール済みのバージョンが確認できるまで、先に進まないでください。

2. CLI が最新バージョンか確認します（ステップ 1 で CLI のインストールが確認された後にのみ実行します）：

   npm outdated -g @gemdesign-ai/cli
   

   • コマンドが空の結果を返すか、Current=Latest と表示した場合、CLI は最新です。このステップは完了なので、ステップ 2 に進みます。
   • コマンドにバージョン情報が表示され、Current と Latest の値が異なる場合、CLI は古いバージョンです。最新バージョンに更新します：

     npm update -g @gemdesign-ai/cli
     

     更新が完了するまで待ち、その後 npm outdated -g @gemdesign-ai/cli で再確認します。再確認で CLI が最新であると確認できるまで、先に進まないでください。

このステップの完了が確認されると、最新バージョンの gemdesign-ai コマンドをグローバルに利用できるようになります。ステップ 2 に進めるのは、その後に限ります。

ステップ 2：ログインを確認する（ステップ 1 の完了後、ワークフローの前に必ず実行）

ステップ 1 が完了したら、必ずログイン状態を確認してください。次のコマンドを実行します：

gemdesign auth whoami

• 成功した場合（ユーザー情報が返される場合）、ユーザーはログイン済みです。ワークフロー（A/B/C）に進んでください。ステップ 3（ローカルサーバー）は、アプリの作成または再利用後、ワークフロー内で実行します。
• 失敗した場合（「GemDesign令牌 无效」や「未提供 GemDesign令牌」などのエラーが返される場合）、ユーザーは認証されていません。必ず次の操作を行ってください：
  1. ユーザーに、アカウントまたは GemDesign令牌 をまだ持っていない場合は、https://design.gemcoder.com にアクセスしてアカウントを登録し、GemDesign令牌 を取得するよう伝えます。GemDesign令牌 の取得手順は、プラットフォームにログイン -> 个人中心（パーソナルセンター）をクリック -> GemDesign令牌（GemDesign令牌）を取得、です。
  2. ユーザーに GemDesign令牌 を尋ねます（AskUserQuestion ツールを使って、GemDesign令牌 の入力を促します）。
  3. ユーザーから GemDesign令牌 が提供されたら、自動的にログインコマンドを実行します：

     gemdesign auth login --token <user_provided_token>
     

  4. gemdesign auth whoami で再確認し、ログインに成功したことを確認します。
  5. それでもログインに失敗する場合は、ステップ 2 から繰り返し、ユーザーにもう一度 GemDesign令牌 の入力を求めます。
  6. ログインが確認されてから、ワークフローに進んでください。

厳守事項：gemdesign auth whoami でログインが確認されるまで、ページ生成に関する作業を一切行ってはいけません。これには CLI コマンド（app、page、style、validate）とローカルファイル操作（.html の書き込み、ストリーミング書き込み、./output/ ディレクトリの作成）が含まれます。ローカルで HTML を生成してもログイン確認を回避する手段にはなりません。認証済みユーザーだけがページをプラットフォームに保存できるため、ログイン前に生成しても無駄になります。ログインに失敗した場合は、作業を中断してまず認証の問題を解決してください。HTML の書き込みを始めてはいけません。

ステップ 2.5：htmlWorkdir をクリーンアップして設定する（ステップ 2 の完了後、ワークフローの前に必ず実行）

ログインが確認されたら、まず前回の中断されたセッションで残った空のプロジェクトディレクトリをクリーンアップし、その後 HTML 作業ディレクトリ（htmlWorkdir）を設定します。順序は必須です。cleanup は workdir --path より先に実行しなければなりません。逆の順序で実行してはいけません。どちらの操作も、ワークフロー（特に app create）を始める前に完了させてください。

重要 — cleanup を workdir より先に実行しなければならない理由（順序は変更できません）： gemdesign server workdir --path ./output を実行すると、./output ディレクトリが作成されます。この時点では app create がまだ実行されていないため、空の作業ディレクトリであり、プロジェクトサブディレクトリ（{projectName}__{appuuid}）はまだありません。gemdesign server cleanup は pruneEmptyWorkdirs() を実行し、プロジェクトサブディレクトリを含まない作業ディレクトリを削除して、その設定も htmlWorkdir から削除します。先に workdir を実行してから cleanup を実行すると、新しく作成された空の ./output が古い空の作業ディレクトリとみなされ、cleanup によってディレクトリが削除され、設定からも消去されるため、htmlWorkdir が空になります。その結果、app create はローカルフォルダーの作成をスキップして warning を返し、server start は起動を拒否します（"未配置 htmlWorkdir..."）。これにより、「ページは生成されたがキャンバスに表示されない」という状態になります。先に cleanup を実行すれば、この問題を避けられます。前回のセッションの古い状態がクリアされた後、最後に workdir が ./output を作成するため、ディレクトリは残ります。（注：cleanup の実行前に htmlWorkdir を設定しておく必要はありません。未設定の場合は "未配置 htmlWorkdir，无需清理" を返して正常に終了します。）

1. 空のプロジェクトディレクトリをクリーンアップする（htmlWorkdir を設定する前に、必ず最初に実行してください）：

   gemdesign server cleanup
   

   • htmlWorkdir がまだ設定されていない場合、コマンドは {"success":true,"message":"未配置 htmlWorkdir，无需清理","removedDirs":[],"removedLocks":[],"removedWorkdirs":[],"removedWorkdirDirs":[]} を返します。これは正常な動作です。手順 2 に進んでください。
   • 前回のセッションですでに htmlWorkdir が設定されている場合、コマンドは設定済みの各作業ディレクトリをスキャンし、プロジェクトのサブディレクトリ（{projectName}__{appuuid} という名前）を調べて、次の処理を行います。
     • 空のプロジェクトディレクトリを削除します。.html ファイルが 1 つも含まれていないプロジェクトのサブディレクトリ（app create によって作成されたものの、ページが一度も保存されていないディレクトリ。例：セッションが中断された場合など）が対象です。
     • 残存するストリーミングファイルをクリーンアップします。開始したものの完了しなかったストリーミング書き込みで残された .stream.lock ファイルが対象です。
     • 空の作業ディレクトリを削除します。プロジェクトのサブディレクトリが 1 つも含まれていない作業ディレクトリは削除され、設定からも取り除かれます（これが、workdir --path を cleanup の後に実行しなければならない理由です）。
   • JSON を返します：{"success":true,"message":"清理完成：删除 N 个空项目目录，清理 M 个遗留文件，移除 K 个无项目的 htmlWorkdir","removedDirs":[...],"removedLocks":[...],"removedWorkdirs":[...],"removedWorkdirDirs":[...]}
   • この手順はブロッキングではありません。クリーンアップに失敗しても、ワークフローへの進行は妨げられません。予期しないエラーが発生しない限り、コマンドは常に success: true を返します。

2. htmlWorkdir を設定する（必ず手順 1 の後に実行してください。一度実行すれば、セッションをまたいで設定が保持されます）：

   重要 — app create は htmlWorkdir の下にローカルのプロジェクトフォルダーを同期的に作成し、server start は起動前に htmlWorkdir を検証します。 htmlWorkdir が設定されていない場合、app create はローカルフォルダーの作成をスキップして（warning を返します）、server start は {"success":false,"error":"未配置 htmlWorkdir，请先执行 gemdesign server workdir --path <path> 设置 HTML 工作目录"} を返し、起動を拒否します。これにより、バックグラウンドプロセスの作業ディレクトリ（cwd）が実際の HTML 生成ディレクトリと食い違い、fileWatcher が .html の変更を検出できず、キャンバスが空白のままになる事態（「ページは生成されたが、キャンバスに表示されない」）を防ぎます。

   gemdesign server workdir --path ./output
   

   • 相対パスは、現在の作業ディレクトリを基準に絶対パスへ解決されます。
   • gemdesign server workdir（フラグなし）を実行して確認します。{"success":true,"htmlWorkdir":["<absolute path>"]} が返されます。
   • ここで作成される ./output ディレクトリは、この同じステップ 2.5 の cleanup では削除されません。cleanup はすでに手順 1 で実行されているためです。この手順の後に cleanup を再実行しないでください。app create はまだ実行されておらず、プロジェクトのサブディレクトリがないため、再実行すると新しく作成された空の ./output が削除されます。

ステップ 3：ローカルサーバーを起動する（アプリの作成または再利用後、ページ生成の前に必ず完了してください）

重要 — 必須条件：このステップでブラウザーを開いてください。 これは交渉の余地がなく、スキップ、延期、任意扱いにしてはなりません。ブラウザーを開く前にページを生成することは重大な違反です。ユーザーが生成中のページを確認できるよう、リアルタイムプレビュー画面が必要です。プラットフォームに組み込まれたブラウザー／プレビューツールを使って、自分で必ずブラウザーを開いてください（フォールバックの方法については、以下のステップ 3 を参照してください）。チャットに URL を出力してユーザーがクリックするのを待つだけでは不十分です。プログラムからブラウザーを開く必要があります。

実行タイミング — ログイン直後ではなく、ワークフローの内部で実行してください。 ステップ 3 はワークフロー A/B/C の内部から呼び出します（各ワークフローの「ローカルサーバーを起動する」ステップを参照）。gemdesign app create／gemdesign app use でアプリを作成または再利用し、gemdesign app info で確認した後に実行してください。ステップ 2（ログイン）の直後にサーバーを起動しないでください。サーバーはアプリから導出されるプロジェクトのサブディレクトリ（<projectDir> = {projectName}__{appuuid}）からページを配信するため、先にアプリが存在している必要があります。アプリが存在する前にサーバーを起動することは違反です。 ステップ 1（CLI のインストール）、ステップ 2（ログインの確認）、およびアプリの作成／再利用（ワークフロー内）がすべて完了したことを確認したら、リアルタイムのストリーミングプレビューを利用するためにローカルサーバーを起動します。

ローカルサーバーは、HTML ページの生成中にリアルタイムのストリーミングプレビューを提供します。サーバーは CLI に組み込まれており、gemdesign server コマンドで管理します。サーバーはデフォルトでポート 4056 で実行されます。このポートが使用中の場合は、次に利用可能なポート（最大 4066）を自動的に再試行します。

0. htmlWorkdir が設定されていることを確認します（ワークフローで app create を実行する前、および server start を実行する前に必ず完了してください）。

   htmlWorkdir はステップ 2.5 で設定します（セッションをまたいで保持されます）。app create は htmlWorkdir の下にローカルプロジェクトフォルダーを同期的に作成し、server start は起動前に htmlWorkdir を検証します。設定されていない場合、app create はローカルフォルダーの作成をスキップして warning を返し、server start は起動を拒否します。その結果、fileWatcher が .html の変更を検出できず、キャンバスが空白のままになります（「ページは生成されたが、キャンバスに表示されない」）。

   ステップ 2.5 をスキップした場合（セッションを再開する場合など）は、続行する前に確認してください。gemdesign server workdir（フラグなし）を実行すると、{"success":true,"htmlWorkdir":"<absolute path>"} が返されます。htmlWorkdir が空の場合は、続行する前に gemdesign server workdir --path ./output を実行してください。

1. 以前に起動したサーバーをすべて停止します（server start の前に毎回必ず実行してください。スキップできません）。

   重要 — server start を実行する前に、必ず server stop を実行して以前に起動したサービスを終了してください。アプリを新規作成する場合も再利用する場合も、省略できません。これにより、fileWatcher が正しいプロジェクトディレクトリにバインドされ、以前のプロセスが新しいセッションに干渉するのを防ぎます。

   厳守 — この手順を絶対に省略しないでください：現在サービスが実行中かどうかにかかわらず、必ず gemdesign server stop コマンドを実行してください。「サーバーは実行されていない」「前のセッションですでに起動した」「ブラウザーのプレビューがすでに開いている」「時間を節約するため」など、どのような理由でも stop を省略してはいけません。唯一の判定基準として、gemdesign server stop の実際の戻り値を確認してください。

   gemdesign server stop
   

   • {"success":true,"message":"本地服务已停止"} が返された場合は、停止済みです。次の手順に進んでください。
   • {"success":false,"error":"未发现运行中的本地服务"} が返された場合は、実行中のサービスがありません。このエラーは無視して次の手順に進んでください。
   • 上記のコマンドの戻り値を受け取ってからでなければ、第 2 手順に進んではいけません。stop コマンドの戻り値が返る前に、server start を実行してはいけません。

2. CLI コマンドを使用して、ローカルサーバーを起動します。

   gemdesign server start
   

   このコマンドを実行する前に、必ず前の手順で gemdesign server stop を実行してください。古いサービスを停止せずに直接 start してはいけません。

   厳守 — 順序の制約：server start は、server stop コマンドの戻り値（成功、または「実行中のローカルサービスが見つからない」というエラー）を受け取ってからでなければ実行できません。次の行為は絶対に行わないでください。

   • server stop と server start を並行して実行する（同じ並列ツール呼び出しのバッチ内で実行する場合など）。
   • server stop コマンドの戻り値が返る前に server start を実行する。
   • server start を実行してから server stop を実行する。
   • 「stop は不要だと思う」という理由で stop を省略し、直接 start する。

   正しい順序：gemdesign server stop を実行する -> コマンドの戻り値を待つ -> gemdesign server start を実行する。これは不可逆の直列依存関係です。

   • サーバーが正常に起動すると、コマンドは次の JSON を返します：{"success":true,"port":<port>,"url":"http://localhost:<port>"}
   • サーバーの起動に失敗すると、コマンドはエラーを含む JSON を返します：{"success":false,"error":"<error message>"}
   • エラーが発生した場合：エラーメッセージを注意深く確認してください。よくあるエラー：
     • "服务文件不存在"：CLI のインストールが不完全です。CLI を再インストールしてください。
     • "服务启动失败，进程已退出"：ポートの競合または設定ファイルのエラーが考えられます。~/.gemdesign/config.json を確認してください。
   • 後続の手順で使用するため、成功時の応答から <port> を記録してください。

3. サーバーの状態を確認します（デバッグ用。省略可能）。

   gemdesign server status
   

   次のいずれかが返されます：{"success":true,"status":"running","port":<port>,"url":"http://localhost:<port>"} または {"success":true,"status":"stopped"}

4. プレビューを開きます（必須 — 厳守。省略しないでください）：サーバーが実行中であることを確認した後（server start コマンドが成功を返した後）、必ずブラウザーを開き、GemDesign设计器 という名前のサービスページに移動してください（URL：http://localhost:<port>。server start の応答にあるポートを使用します）。

   この手順は必須です。 ブラウザーで http://localhost:<port> を開くまでは、ページ生成ワークフロー（Workflow A/B/C）に進まないでください。サーバーが起動していることと、プレビューがブラウザーで開いていることは同じではありません。ユーザーがブラウザーでプレビュー画面を確認できる必要があります。

   チャットに URL を出力するだけではいけません。 ツールを使って、実際にブラウザーを開く必要があります。「服务器启动成功！请在浏览器中打开 http://localhost:4056」のような出力は違反です。ユーザーにリンクをクリックするよう求めるのではなく、プログラムからブラウザーを開いてください。

   ブラウザーを開く方法 — 以下の優先順位に従ってください：

   以下の方法を優先順位の高いものから順に試してください。利用可能で、正常に動作した最初の方法を使用します。失敗した場合は、次の方法を試してください：

   優先順位	方法	使用方法
   1	プラットフォームに組み込まれたブラウザー／プレビュー用ツール	現在のエージェントプラットフォームで利用できるブラウザー／プレビュー用ツールを必ず確認し、最適なものを使用してください。 プラットフォームによって組み込みツールは異なります。利用可能なものを使用してください。プラットフォーム固有のツールの例：Trae では OpenPreview と integrated_browser MCP の browser_navigate が利用できます。Cursor では独自のプレビュー機能を利用できます。その他のプラットフォームにも同等のツールがある場合があります。重要なのは、チャットに URL を出力するだけでなく、ツールを使ってプログラムからブラウザーを開くことです。 ツールを使って http://localhost:<port>/ に移動してください。
   2	OS の既定ブラウザーを起動するコマンド	組み込みのブラウザー／プレビュー用ツールが利用できない場合、または失敗した場合は、OS のコマンドで既定のブラウザーを開いてください：Windows start http://localhost:<port>/、macOS open http://localhost:<port>/、Linux xdg-open http://localhost:<port>/。
   3	ユーザーに URL を開くよう依頼する	上記の方法がすべて失敗するか利用できない場合は、最終手段として、ユーザーに「请在浏览器中打开 http://localhost:/ 查看设计器预览」と明確に伝え、先に進む前にユーザーの確認を待ってください。

   プラットフォームに組み込まれたツールの確認方法： 利用可能なツール一覧を確認し、OpenPreview、browser_navigate、preview、browser などの名前のツールを探してください。ブラウザーパネルで URL を開けるツールであれば、どれでも使用できます。URL http://localhost:<port>/ を指定してください。

   成功を確認する：

   • 最優先の方法でエラーが返された場合、または成功したかどうか不明な場合は、ただちに表の次の方法を試してください。
   • ブラウザーを開いた後、デバッグエンドポイント（http://localhost:<port>/api/local/stream/debug が 200 を返す）を再確認し、サーバーに引き続きアクセスできることを確認してください。
   • 少なくとも1つの利用可能な方法でブラウザーを開くことを最大限試みてから、ページ生成に進んでください。

   プレビューを開いた後、ページ生成ワークフローに進むことができます。

   重要 — ブラウザーを開くのは Step 3 のここで1回だけです。 ブラウザーで http://localhost:<port>（デザイナー SPA のルート）を開いた後は、ページ生成（Workflow A/B/C）の実行中も、変更の適用中も、生成したページを「更新」または「表示」する場合も、ブラウザーを再度開いてはいけません。セッション全体を通じて、デザイナー SPA を開いた状態にしてください。生成された HTML は、ブラウザーを別の URL に移動して開くのではなく、SSE を介してデザイナー内の iframe に読み込みます（「Streaming Write Workflow」を参照）。

   ブラウザーを再度開くと、指定した URL に移動し、デザイナーから離れてしまいます。これにより、生成された HTML（または 404）がデザイナーに上書きされ、ユーザーに必要なプレビュー画面が失われます。ブラウザーを開く際の URL は、必ずデザイナーのルート URL http://localhost:<port>/ にしてください。生成された .html ファイルへのパス（例：http://localhost:<port>/output/<projectDir>/<pageuuid>.html）や、ページ固有の URL を指定してはいけません。生成されたページに直接アクセスできるブラウザー URL はありません。SSE を介してデザイナーの iframe でのみ表示できます。

CLI コマンドリファレンス

サーバー管理

gemdesign server start [--port <port>]   # 启动本地设计器服务（默认端口 4056）
gemdesign server stop                    # 停止本地设计器服务
gemdesign server status                  # 查看服务运行状态
gemdesign server workdir --path <path>   # 保存 HTML 工作目录（htmlWorkdir，相对路径基于当前目录解析为绝对路径）
gemdesign server workdir                 # 查看当前 htmlWorkdir
gemdesign server workdir --clear         # 清除 htmlWorkdir 配置
gemdesign server cleanup                 # 清理空项目目录和遗留的流式文件

server workdir HTML の作業ディレクトリを ~/.gemdesign/config.json の htmlWorkdir フィールドに保存します。ローカルサービスの起動後、fileWatcher がこのディレクトリ内の .html ファイルの変更を監視し、SSE 経由でブラウザーのキャンバスにプッシュします。app create はこのディレクトリ内にプロジェクトのサブディレクトリ {projectName}__{appuuid} も同期的に作成します。また、server start は起動前に htmlWorkdir が設定済みかどうかも検証します。未設定の場合、app create はローカルディレクトリの作成をスキップして（warning を返します）、server start は起動を拒否してエラーメッセージを返します。バックグラウンドプロセスの cwd と実際の HTML 生成ディレクトリが一致せず、「ページは生成されたのにキャンバスに表示されない」という事態を防ぐためです。ログイン後、app create の実行前に gemdesign server workdir --path ./output を一度実行することをおすすめします（通常、パスは ./output です。ページ HTML のルートディレクトリにあたります）。一度設定すると保存されるため、以降は再設定する必要はありません。 server start はローカルサービスをバックグラウンドプロセスとして起動します。server start を実行する前に、必ず server stop を実行して以前のサービスを終了してください。古いサービスを停止せずに直接 start することは禁止されています。server stop を省略することは厳禁です（実行中のサービスがないと思われる場合でも、必ずこのコマンドを実行してください）。また、server start は server stop コマンドの結果が返ってから実行する必要があります。両方を並行して実行したり、stop の結果が返る前に start を実行したりすることは禁止されています。起動に成功すると、port と url を含む JSON が返されます。失敗した場合は、error を含む JSON が返されます。エラーメッセージをよく読み、原因を診断して修正してから再試行してください（再試行の前にも、同様にまず stop を実行してください）。 server stop 実行中のサーバーを停止します。Windows では taskkill を使用してプロセスツリーを終了します。サーバーが実行中でない場合、またはプロセスを終了できない場合はエラーが返されます。この場合、そのエラーは無視してかまいません（実行中のサービスがなかったことを示します）。ただし、stop の手順は完了したものとみなされるため、start に進むことができます。 server status 現在のステータス（running または stopped）を返します。実行中の場合は、ポートと URL も返します。

認証

gemdesign auth login --token <token>   # 配置 GemDesign 令牌
gemdesign auth whoami                  # Verify identity

アプリ管理

gemdesign app create --name "MyApp" --workdir <path> [--type web|app] [--width <px>] [--height <px>]    # Create new app (sync-creates local project folder under --workdir), --type defaults to web
gemdesign app list                     # List all apps
gemdesign app info [--appuuid <id>]    # App details
gemdesign app use --appuuid <id> --workdir <path>       # Switch current default app (creates/locates local project folder under --workdir)

app create のキャンバスサイズ：--width／--height はキャンバスのピクセルサイズを指定します。指定しない場合は、--type に応じたデフォルト値が使われます：web -> 1920×1080、app -> 440×956。指定したサイズはアプリ情報とともにローカルデザイナーのキャンバスに同期され、デフォルト値を上書きします。例：gemdesign app create --name "PadApp" --type app --width 768 --height 1024。 重大 — app create と app use には --workdir が必要です：app create と app use の --workdir <path> は必須パラメーターで、ローカルプロジェクトのサブディレクトリ {projectName}__{appuuid} の親ディレクトリを指定します。パスはエージェントが明示的に指定し、CLI が設定から自動的に推測することはありません。--workdir は自動的に htmlWorkdir 設定配列に追加されます（重複は除外）。local-server はこれに基づいてすべてのプロジェクトディレクトリをスキャンします。./output を渡すことを推奨します（gemdesign server workdir --path ./output で設定したディレクトリと同じです）。page create の --file <path> も同様です。lock ファイルは --file から導出されるプロジェクトサブディレクトリに直接書き込まれ、lock と html が同じディレクトリに配置されます。 appuuid の優先順位：--appuuid フラグ > defaultAppUuid（app create／app use によって設定）> GEMDESIGN_APPUUID 環境変数 app create または app use を実行すると、その後の page コマンドでは --appuuid は不要です。 重要：新しいアプリを作成する前に、必ず gemdesign app list を確認してください。すべてのページを同じプロジェクトフォルダーにまとめるため、既存のアプリを再利用してください。ユーザーが明示的に新しいアプリを求めた場合にのみ作成してください。 重大 — アプリを重複して作成しないでください：1 回のセッション／タスク内で gemdesign app create を複数回実行しないでください。このセッションですでに app create を実行している場合は、その後、ワークフローの手順や再試行でアプリの設定が必要に見えても、再度実行してはいけません。代わりに gemdesign app list を実行して既存のアプリを見つけ、gemdesign app use --appuuid <id> --workdir ./output で再利用してください。2 つ目のアプリを作成すると、1 つ目のアプリが空のままプラットフォーム上に取り残されます。 重大 — セッションロックエラーの処理：CLI は appuuid を使ってセッションロックを自動的に検証するようになりました。app create が stage: "appCreateSession" を返した場合（セッションロックが存在し、リモートにアプリが残っている場合）は、--force で再試行しないでください。代わりに：（1）gemdesign app use --appuuid <existingApp.appuuid> --workdir ./output を実行してアプリを再利用します。（2）既存のアプリが別の完了済みタスクのものであれば、gemdesign app end-session を実行してから、--force を付けずに app create を実行します。（3）セッションロックされたアプリがリモートから削除されたことを app list で確認した場合に限り、--force を使用してください。なお、CLI は古いセッションロック（リモートで削除されたアプリ）を自動的にクリーンアップするため、--force が必要になることはほとんどありません。（4）app create が stage: "appCreateSessionVerify" を返した場合（ネットワークエラーによりアプリの存在を確認できない場合）は、待ってから再試行してください。--force は使用しないでください。 重大 — app create または app use の前後で必ずサーバーを再起動してください：正しい順序は、gemdesign server stop -> （stop コマンドの結果が返るまで待機）-> （htmlWorkdir が設定済みであることを確認）-> gemdesign app create／gemdesign app use -> gemdesign server start です。この順序はワークフローの手順で必須となっているため、独立した手順として繰り返し実行しないでください。アプリを新規作成する場合も再利用する場合も、server start の実行前に、必ず server stop を実行して以前のサービスを終了してください。そうしないと、以前のサービスの fileWatcher が前の app の <projectDir> にバインドされたままになり、新しいページがキャンバスに反映されません。この server stop の手順は絶対に省略しないでください（実行中のサービスがないと思われる場合も必ず実行してください）。また、server start は server stop コマンドの結果が返ってから実行する必要があります。並行して実行したり、stop より先に start したりすることは禁止されています。 重要 — アプリ情報をユーザーに伝えてください：アプリを選択／切り替え／作成した後（つまり、作業対象のアプリを確定する app create、app use、app info のいずれかを呼び出した後）は、ページ生成のアクティブな対象となるアプリを、テキストの回答で必ず明確にユーザーに伝えてください。最低限、アプリ名とappuuid（可能であれば算出された <projectDir> も）を出力してください。これにより、ユーザーはどのアプリにページが生成／変更されるかを常に把握でき、誤ったアプリが選ばれた場合に中断できます。正確な形式については、各ワークフローの「現在のアプリ情報をユーザーに伝える」手順を参照してください。 重大 — アプリの種類によってページの種類が決まります：アプリには web（デスクトップ）または app（モバイル）の種類があり、app info の pageScene フィールドに返されます。新しいページを生成する際は、ページの種類をアプリの種類に合わせる必要があります：web アプリには web ページ（デスクトップレイアウト、ワイド画面）のみ、app アプリには app ページ（モバイルレイアウト、狭い画面）のみを作成できます。HTML を生成する前に、app info からアプリの pageScene を確認し、それに応じてページを設計してください。app タイプのアプリにデスクトップ幅のページを生成したり、web タイプのアプリにモバイル幅のページを生成したりしないでください。

スタイル検索（任意のヘルパー）

gemdesign style search --keywords "科技,深蓝,企业" --limit 5   # Search styles
gemdesign style get --id <styleId> --format html                 # Get full style

スタイル検索は任意です。スタイルを独自にデザインしたり、ほかの UI デザインスキルを使ったりすることもできます。

ページ - 表示

gemdesign page list [--appuuid <id>]                                        # List pages
gemdesign page get --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html  # Get page HTML (auto-creates projectDir)
gemdesign page doc get --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.md  # Get requirement doc

重大 - リモートページを同期する際はフォルダー構造を必ず保持してください：page list が返す各ページには dirName フィールドが含まれます（リモート側のフォルダー。複数階層は / で区切られ、ルート階層のページは null／空です）。リモートページをローカルに同期する際（特に「同期後に編集」する場合）、page get --file の <subfolder> は、そのページの dirName と一致させる必要があります。つまり、./output/<projectDir>/<dirName>/<pageuuid>.html に保存します。すべてのページをプロジェクトのルートディレクトリにまとめて保存することは厳禁です。そうすると、後で編集内容を保存する際、ローカルで推定されるディレクトリがリモート側と一致せず、ページがリモートフォルダーから外れるおそれがあります。例：page list が返すページ report-sales の dirName が reports の場合、必ず gemdesign page get --pageuuid report-sales --file ./output/<projectDir>/reports/report-sales.html を実行してください。

ページ - 作成（ストリーミングモード）

gemdesign page create --pageuuid <readable-id> --name "<pageName>" --file ./output/<projectDir>/<subfolder>/<readable-id>.html   # Create page + enter streaming mode (.stream.lock written next to --file)

page create は、このページのストリーミングモードを開始するようローカルサーバーに指示し、.html ファイルへの書き込みと同時にリアルタイムで HTML プレビューを表示できるようにします。このコマンドは HTML ファイルを書き込む前に実行してください。ストリーミングモードは page save の完了時に自動的に終了します。

【重大 - HTML ファイル名は pageuuid と一致させる必要があります】 --file のファイル名部分は --pageuuid と完全に一致させる必要があります。たとえば、--pageuuid customers-list には --file .../customers-list.html を指定する必要があります。local-server の fileWatcher、streamPoller、pageCache はすべて、「ファイル名 = pageUuid」という前提で動作します。一致しない場合、ロックファイルと HTML ファイルが連動しなくなり、フロントエンドのストリーミング状態が異常になり、.meta.json とリモートの pageuuid が一致しなくなるおそれがあります。page create の応答では、不一致を検出すると WARNING が表示されます。必ず推奨されるパスに修正してください。

ページ - 保存（検証付き）

gemdesign page save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html                                         # Update existing
gemdesign page save --new --pageuuid <readable-id> --name "Login" --file ./output/<projectDir>/<subfolder>/<readable-id>.html  # Create new
gemdesign page doc save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/doc.md                                                           # Save requirement doc

page save はアップロード前に、GemDesign Page Spec に照らして HTML を自動検証します。保存が成功すると、ストリーミングモードを自動的に終了し、ブラウザーが最終レンダリングを取得するようにします。 page doc save は、エージェントが生成した要件ドキュメントをプラットフォームに保存します。 --new の --pageuuid：人が読みやすい ID（例：.html を除いたファイル名）を使用してください。アプリ内で一意になるようにしてください。この ID はナビゲーション要素の data-uuid として直接使用されるため、保存後に変更する必要はありません。 プロジェクトのサブディレクトリ：パスには必ず ./output/<projectDir>/ を使用してください。CLI は冪等であり、パスにすでに <projectDir> が含まれている場合は重複して追加しません。詳細は「ローカルファイル管理」を参照してください。 フォルダー構成：フォルダーパスを --file に直接含めてください（例：--file ./output/<projectDir>/crm/客户管理/page.html）。CLI はファイルパスからリモートの dirName を自動的に導き出します。

検証のみ

gemdesign validate --file ./output/<projectDir>/<subfolder>/page.html    # Validate without saving

ローカルファイル管理

すべてのページの HTML ファイルは、プロジェクトごとのサブディレクトリに整理して ./output/ 以下に保存してください。

ファイル	用途	生成方法
./output/<projectDir>/<subfolder>/<pageuuid>.html	ページ HTML（DSL を含み、編集と保存に使用）	エージェントが page create によって .stream.lock が作成された後にのみ 書き込みます（ロックなしで直接作成することは禁止です。<subfolder> には複数階層のフォルダーパスを含めることができます）
./output/<projectDir>/<subfolder>/<pageuuid>.meta.json	ページ位置のメタデータ（キャンバスレイアウト用に { position: { x, y } } を保存）	CLI のみが管理します。page get によって自動生成され、位置の読み取りに page save が使用します。エージェントがこのファイルを手動で作成または変更することは絶対に禁止です。HTML ファイルと同じディレクトリに配置されます。

.meta.json は HTML ファイルのディレクトリに従います：.meta.json ファイルは、フォルダーの階層の深さにかかわらず、対応する .html ファイルと常に同じディレクトリに生成されます。例：

• --file ./output/<projectDir>/page.html → meta.json は ./output/<projectDir>/page.meta.json
• --file ./output/<projectDir>/crm/page.html → meta.json は ./output/<projectDir>/crm/page.meta.json
• --file ./output/<projectDir>/crm/客户管理/page.html → meta.json は ./output/<projectDir>/crm/客户管理/page.meta.json

.meta.json ファイルを手動で作成または変更してはいけません。これらは CLI のみが管理します（page get が生成し、page save が読み取ります）。page save の実行時には、HTML ファイルと同じディレクトリにある .meta.json から位置を読み取ります（.meta.json が存在しない場合は --x／--y フラグにフォールバックします）。 ディレクトリ整合性チェック（自動）：page get または page save でファイルを書き込む前に、CLI はプロジェクトディレクトリを自動的にスキャンし、--file が指すディレクトリとは異なるディレクトリに同名の .html ファイルがすでに存在しないか確認します。不一致が検出された場合（例：HTML ファイルが customers/ に存在するのに、--file がルートを指している場合）、CLI は suggestedFilePath を含むエラーを返します。提案されたパスを必ず使ってコマンドを再実行してください。このチェックは、データの不整合を防ぐため、ファイルを書き込む前に実行されます。このエラーが返された場合は、無視せず、エラーレスポンスに含まれる suggestedFilePath をそのまま使ってコマンドを再実行してください。

プロジェクトのサブディレクトリ名：<projectDir> = {projectName}__{appuuid}

• projectName は app info から取得します（ファイルシステムで使用できない文字 \/:*?"<>| は削除され、空白は _ に置き換えられます）
• projectName が空の場合は 默认项目 に置き換えられ、appuuid が空の場合は local に置き換えられます
• 例：CRM系统__abc-123、电商App__9f3e、默认项目__local
• ディレクトリの作成：このサブディレクトリは、server workdir で事前に htmlWorkdir を設定しておくと、app create によってその配下に同期的に作成されます。ファイル書き込み時には、page get／page save もべき等に作成します。

ファイルの書き込み方法：

• ファイルを直接書き込む場合も CLI コマンドに渡す場合も、すべてのファイルパスで必ず ./output/<projectDir>/<subfolder>/<pageuuid>.html を使用してください。必要に応じて <subfolder> にフォルダーのパスを含めてください（例：./output/<projectDir>/crm/客户管理/page.html）。HTML ファイル名は必ず pageuuid と一致させてください（例：--pageuuid customers-list の場合、ファイル名は customers-list.html でなければならず、list.html は使えません）。
• CLI はべき等です。パスにすでに <projectDir> が含まれている場合、重複して追加することはありません。ネストを心配せずに ./output/CRM系统__abc-123/home.html を page get --file または page save --file に安全に渡せます。
• 最初に <projectDir> を算出してください：gemdesign app info を実行し、{appuuid} と {projectName} を取得してから、<projectDir> = {projectName}__{appuuid} を算出します（projectName はサニタイズしてください）。
• ファイルを作成する前に <projectDir> を検証してください：<projectDir> が空ではなく、{nonEmptyName}__{nonEmptyUuid} の形式に一致することを確認してください。projectName または appuuid が空／未定義の場合は、gemdesign app info を再実行してください。空または不完全な <projectDir>（例：__abc や MyApp__）でファイルを作成しないでください。名前のない孤立したディレクトリが作成されます。

ローカルサーバーは、プロジェクトのサブディレクトリパスからページを自動的に配信します。

ページフォルダーの構成

ページは、プロジェクトディレクトリ内のサブフォルダーに整理できます。--file にフォルダーのパスを含めるだけです。

• ルート階層のページ：--file ./output/<projectDir>/page.html → プロジェクトのルートに配置
• サブフォルダー内のページ：--file ./output/<projectDir>/crm/page.html → crm サブフォルダーに配置
• 複数階層のフォルダー：--file ./output/<projectDir>/crm/客户管理/page.html → ネストされたディレクトリ構造

# Single-level folder
gemdesign page create --pageuuid customer-list --name "客户列表" --file ./output/<projectDir>/crm/customer-list.html
gemdesign page save --new --pageuuid customer-list --name "客户列表" --file ./output/<projectDir>/crm/customer-list.html

# Multi-level folder
gemdesign page create --pageuuid customer-detail --name "客户详情" --file ./output/<projectDir>/crm/客户管理/customer-detail.html
gemdesign page save --new --pageuuid customer-detail --name "客户详情" --file ./output/<projectDir>/crm/客户管理/customer-detail.html

フォルダーを使う場合：ユーザーがページをモジュール／カテゴリ別に整理するよう指定した場合は、フォルダーを使用してください。たとえば、ユーザーが「顧客ページを crm/客户 の下に配置して」と言った場合は、--file ./output/<projectDir>/crm/客户/page.html を使用します。 フォルダー名：ファイルシステムで使用できない文字（\/:*?"<>|）は自動的に除去されます。フォルダー名には、内容が分かる読みやすい名前を付けてください。 ローカルサーバー：ローカルサーバーはすべてのサブフォルダーを自動的に再帰スキャンし、デザイナー内にツリー構造で表示します。 リモート同期：page save を呼び出すと、CLI は --file からフォルダーのパスを自動的に導出し、dirName としてリモートサーバーに送信します。追加のパラメーターを指定する必要はありません。CLI が透過的に処理します。

ストリーミング書き込みワークフロー（リアルタイム表示）

HTML ページを生成するときは、ブラウザーでリアルタイム表示するために、ストリーミング書き込みワークフローを使用してください。GemDesign ローカルサーバーはファイルの変更を監視し、Server-Sent Events（SSE）を介して増分コンテンツをブラウザーに送信します。

重大 — ストリーミング書き込み中（または Step 3 の後はいかなる時点でも）、ブラウザーを再度開かないでください。 デザイナー SPA（Step 3 の時点ですでにブラウザーで開いています）は .html ファイルの変更を監視し、生成された HTML を SSE 経由で内部 iframe に自動的に読み込みます。「開く」操作も「更新」操作も必要ありません。ファイルを書き込むだけで、デザイナーがリアルタイムで更新されます。生成された .html の URL（例：プレビュー ツールや、ページ固有の URL を指定した OS のブラウザーコマンド）にブラウザーで移動すると、デザイナーが生成された HTML で上書きされ、プレビュー画面が壊れます。ブラウザーを開く際に有効な URL はデザイナーのルート http://localhost:<port>/ のみであり、これも Step 3 の後に再利用してはいけません。

HARD GATE — ローカルファイルの生成後は、必ず page save コマンドを呼び出してください：HTML ファイルを書き込んだ後、必ず gemdesign page save コマンドを呼び出して、ページをリモートサーバーに保存してください。page save を省略してローカルファイルだけを書き込むことは厳禁です。その場合、ページはローカルにしか存在せず、プラットフォームに表示されないため、ユーザーはページを見たり使用したりできません。完全な手順は、page create → HTML の書き込み → page save です。page save には仕様への準拠を検証する機能が組み込まれており、検証に失敗するとエラーが返されます。修正後、page save を再実行してください。ローカルファイルだけを書き込み、page save を呼び出さないことは重大な違反です。

注意：page create の JSON レスポンスには warning フィールドと requiredNextSteps フィールドが含まれており、後続で必ず実行する手順が明示されています。このレスポンスを受け取った後は、requiredNextSteps に記載された手順を順番に実行しなければなりません。HTML の書き込み後に処理を止めてはいけません。

HARD GATE — .html ファイルと .meta.json ファイルを直接作成することは厳禁です：エージェントがファイルツール（Write/Edit など）を使用して .html ファイルまたは .meta.json ファイルを直接作成することは禁止されています。これらのファイルの作成は必ず CLI コマンドを通じて行ってください：

• 新しいページを作成する場合：まず gemdesign page create を実行してください（--file と同じディレクトリに .stream.lock を作成し、ストリーミングモードを開始します）。HTML の書き込みが許可されるのは、その後です。ロックなしで HTML ファイルを書き込むことは重大な違反です。local-server がストリーミングモードに入れず、リアルタイムプレビューが無効になり、フォールバック保存でもページが未保存であることを認識できなくなります。
• 既存のページを変更する場合：まず gemdesign page get を実行して HTML を取得してください（CLI によって .html ファイルと .meta.json ファイルが生成されます）。変更が許可されるのは、その後です。
• .meta.json は CLI 専用ファイルです：page get によって自動生成され、page save によって読み取られます。いかなる場合も、エージェントが .meta.json ファイルを手動で作成または変更することは厳禁です。

自己確認基準：.html に書き込む前に、必ずそのページの .stream.lock（新規作成の場合。page create が作成）または page get の出力（既存ページの変更の場合）が存在していなければなりません。この順序に違反すること（先にファイルを書き込み、後からコマンドを実行すること、またはコマンドを完全に省略すること）は、いずれも重大な違反です。

仕組み

CLI がストリーミングのライフサイクルを自動的に管理します。gemdesign page create コマンドでストリーミングモードが開始され、gemdesign page save で自動的に終了します。.html ファイルに追記すると、ブラウザーは増分 HTML を受信します。

1. gemdesign page create → ブラウザーがそのページのストリーミングモードに入ります
2. .html に追記 → ブラウザーが増分 HTML を受信し、リアルタイムで再レンダリングします
3. gemdesign page save → ブラウザーが完全な HTML を取得し、最終レンダリングに切り替わります

手順

生成するページごとに、このワークフローに従ってください。このワークフローには、page create、HTML の書き込み、page save の必須手順が 3 つあります。各ページについて、3 つの手順をすべて完了しなければなりません。HTML の書き込み後に処理を止めることは重大な違反です。ページはプラットフォームに表示されません。

1. パスを計算する：

   • htmlPath = ./output/<projectDir>/<subfolder>/<pageuuid>.html（<subfolder> にはフォルダーのパスを含めます。ルート階層のページでは <subfolder> を省略します）

2. ページを作成する（ストリーミングモードに入る）：

   gemdesign page create --pageuuid <pageuuid> --name "<pageName>" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html
   

   これにより、ローカルサーバーにこのページのストリーミングモードを開始するよう通知されます。.stream.lock は --file の隣に書き込まれるため、ロックと HTML は同じディレクトリに配置されます。ブラウザーはストリーミングモードに入り、増分 HTML を受信する準備をします。

   レスポンスには requiredNextSteps が含まれています。必ずその手順に従ってください。 page create の呼び出し後、HTML ファイルを書き込み、続けて page save を呼び出さなければなりません。HTML の書き込み後に処理を止めてはいけません。

3. HTML ファイルを書き込みます（最初の書き込み以降は追記のみとし、短い内容で上書きすることは絶対に避けてください）：

   • 前提条件：手順 2 の page create が成功している必要があります（--file と同じ場所に .stream.lock が存在します）。ロックなしで HTML ファイルを作成／書き込みすることは絶対に避けてください。上記の「严禁直接创建 .html 和 .meta.json 文件」HARD GATE を参照してください。
   • HTML は一度に書き込むことも、複数回に分けて追記することもできます。ローカルサーバーがファイルの変更を検出し、追記するたびにリアルタイムでブラウザーに送信します。
   • HTML は完全なドキュメントである必要があります。<!DOCTYPE html> + <head>（すべての依存関係とスタイルを含む）+ <body>...</body> + </html> を含めてください。
   • 複数回に分けて追記する場合、最初の書き込みに <body> タグを含めてください。そうすればブラウザーはすぐにレンダリングを開始できます（ブラウザーは <body> が現れてからレンダリングします）。

   重要なルール：

   • 最初の書き込み後は、必ずファイルに追記してください。ストリーミング中に短い内容で上書きすることは絶対に避けてください。これにより pageReset イベントが発生し、ブラウザーは最初から再レンダリングすることになります。
   • 最初から書き直す必要がある場合は、先に .html ファイルを削除してから、最初から書き始めてください。
   • 最初の書き込みでファイルが作成されます（長さは 0 から N になります）。以降の書き込みは追記されます（長さは N から N+M になります）。
   • 遅延やチャンクサイズの制限はありません。好きな速度、サイズで書き込めます。ローカルサーバーは、ファイルの変更を約 10ms 以内にブラウザーへ送信します。
   • 失敗時のクリーンアップ：ストリーミング書き込みが失敗または中断された場合、そのページの不完全な .html ファイルを削除してください。gemdesign server cleanup を実行して、不要なファイルや空のプロジェクトディレクトリを削除することもできます。

4. （任意）HTML を検証します — 保存前に早期エラー検出を行いたい場合のみ実施してください。

   gemdesign validate --file ./output/<projectDir>/<subfolder>/<pageuuid>.html
   

   検証に失敗した場合は、HTML を修正して再検証してください。注：page save でも内部的に検証されます。保存時の検証に失敗した場合は、HTML を修正して page save を再実行してください。

5. プラットフォームに保存します（必須 — HTML の書き込み後に必ず実行してください）：

   gemdesign page save --new --pageuuid <pageuuid> --name "<pageName>" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html
   

   page save は保存前に HTML を自動的に検証します。検証に失敗するとエラーが返されるため、HTML を修正して page save を再実行してください。保存が完了すると、CLI はストリーミングモードを自動的に終了します。ブラウザーは完全な HTML を取得し、最終的なレンダリングに切り替わります。

   この手順は必須です。 HTML をローカルに書き込んだだけで page save を実行しない場合、そのページはローカルマシン上にしか存在せず、プラットフォームには表示されません。ユーザーはページを確認できません。これは最もよくある、かつ重大なミスです。絶対に避けてください。

   重要 — ページの HTML の書き込みが完了したら、直ちに実行してください。後回しやまとめての実行は絶対に避けてください：あるページの HTML をすべて書き終えたら、すぐにそのページの page save を実行する必要があります。他のページの生成が終わるまで遅らせてはいけません。.stream.lock を削除し、ストリーミングモードを終了して、ページをリモートサーバーに同期する操作は page save だけです。保存を後回しにするとロックが残り、ページはストリーミング状態のままプラットフォームに同期されず、ブラウザーのキャンバスも最終レンダリングに切り替わりません。複数のページを生成する場合は、以下の「批量生成：逐页立即保存」HARD GATE を参照してください。

HARD GATE — 複数ページを生成する場合、各ページの書き込み完了後に直ちに保存する必要があります（並列処理は可能ですが、保存をまとめることは絶対に避けてください）：複数のページを生成する場合、複数のページの生成を並行して進めることはできますが、各ページの HTML の書き込みが完了したら、対応する次のコマンドを直ちに実行する必要があります（page save、または先に validate を実行してから page save）。save が成功したことを確認してから、そのページを完了とします。正しい例：create(p1) → p1 を書き込む → 直ちに save(p1)；create(p2) → p2 を書き込む → 直ちに save(p2) — 各ページは互いの完了を待ちません。

すべてのページの page save を最後にまとめて実行することは絶対に避けてください（すべてのページの HTML を書き終えてから save(p1)…save(pN) を一括実行するのは重大な違反です）。保存をまとめると、各ページの .stream.lock がなかなか削除されず、ページはストリーミング状態のままリモートサーバーに同期されません。ブラウザーのキャンバスも最終レンダリングに切り替わらず、ユーザーには一括処理が終わるまで「すべてのページが読み込み中」のように見えます。

自己確認基準：いずれかのページの HTML の書き込みが完了した後、そのページで次に実行するコマンドは、必ずそのページ自身の page save（または先に validate を実行してから save）でなければなりません。他のページの HTML を先に書いたり、すべてのページの書き込みが終わるまで待ってから一括処理したりしてはいけません。並列処理では、create 済みのページが複数存在してもかまいませんが、「HTML の書き込みが完了したのに、save が遅れている」ページが存在してはいけません。

例（「home」ページのストリーミング書き込み）

# Step 1: Create the page (enter streaming mode)
gemdesign page create --pageuuid home --name "首页" --file ./output/MyApp__abc-123/home.html
# → Response includes requiredNextSteps — you MUST follow them

# Step 2: Write the HTML file (one shot or multiple appends)
#    Use Write tool to create ./output/MyApp__abc-123/home.html with the complete HTML

# Step 3 (OPTIONAL): Validate early to catch errors before saving
gemdesign validate --file ./output/MyApp__abc-123/home.html
# If validation fails, fix and re-validate

# Step 4 (MANDATORY): Save to platform — MUST call, otherwise page won't appear
gemdesign page save --new --pageuuid home --name "首页" --file ./output/MyApp__abc-123/home.html
# → page save also validates internally; if validation fails, fix HTML and re-run this command

ワークフロー

すべてのワークフローの前提条件：ワークフローを開始する前に、ステップ 1（CLI のインストールと最新状態の確認）、ステップ 2（gemdesign auth whoami によるログインの確認）、およびステップ 2.5（htmlWorkdir の設定とクリーンアップ）が完了していることを必ず確認してください。ログインが確認されていない場合は、HTML を生成したり、./output/ ファイルを作成したり、ストリーミング書き込みを開始したりしないでください。そこで停止し、まず認証の問題を解決してください。ステップ 3（ローカルサーバーの起動とブラウザーのプレビュー表示）は、ワークフローの開始前には実行しません。アプリの作成または再利用後に、app info で <projectDir> を確認してから、ページを生成する前に、各ワークフロー内で実行します。これはワークフロー A、B、C のすべてに適用されます。

ワークフロー A：要件からの一括生成

1. 前提条件をすべて満たします：次に進む前に、ステップ 1（CLI のインストール／更新）、ステップ 2（ログイン）、およびステップ 2.5（htmlWorkdir の設定とクリーンアップ）が完了していることを確認します。ステップ 3（ローカルサーバーとブラウザーのプレビュー）はここでは実行しません。アプリを作成または再利用した後、以下のステップ 5 で実行します。
2. アプリが存在することを確認します（まず再利用します）：
   • htmlWorkdir が設定されていることを確認します：htmlWorkdir はステップ 2.5 で設定済みです（セッションをまたいで保持されます）。app create --workdir と app use --workdir は、パスを htmlWorkdir の設定に自動的に追加します（重複は除外されます）。gemdesign server workdir（フラグなし）で確認してください。空の htmlWorkdir が返された場合でも、app create／app use に --workdir ./output を直接渡すことができます。
   • gemdesign app list を実行して既存のアプリを確認します。
   • アプリがすでに存在する場合：gemdesign app use --appuuid <id> --workdir ./output を実行して、対象アプリをデフォルトに設定します。ユーザーから新規作成を明示的に求められない限り、新しいアプリを作成してはいけません。
   • アプリが存在しない場合：gemdesign app create --name "<AppName>" --workdir ./output [--type web|app] [--width <px>] [--height <px>] を実行して作成します（デフォルトの種類は web、デフォルトのキャンバスサイズは web が 1920×1080、app が 440×956 です）。app create は --workdir の下にローカルのプロジェクトフォルダーを同期作成します（htmlWorkdir の設定に自動追加されます）。作成後、直ちに gemdesign app info を実行してアプリの存在を確認し、appuuid を記録してください。このセッション中は、いかなる理由があっても app create を再実行してはいけません。 之前运行中的服务会在步骤 5 的 server stop 中统一终止。
   • 重要 — アプリの重複を禁止します：このセッション中にすでに app create を実行している場合（以前のワークフローの試行中であっても）、再実行してはいけません。app list と app use を使って既存のアプリを再利用してください。2 つ目のアプリを作成すると、最初のアプリが空のまま取り残されます。
   • 重要 — セッションロックエラーへの対処：app create が stage: "appCreateSession" を返した場合（セッションロックが存在し、リモートにアプリも存在する場合）、--force を付けて再試行してはいけません。代わりに、（1）app use --appuuid <existingApp.appuuid> --workdir ./output を実行して再利用します。（2）別の完了済みタスクのアプリであれば、gemdesign app end-session を実行してから、--force を付けずに app create を実行します。（3）stage: "appCreateSessionVerify"（ネットワークエラー）の場合は、待ってから再試行します。CLI は古いロックを自動的にクリーンアップするため（リモートでアプリが削除されている場合）、--force が必要になることはほとんどありません。
   • 重要：同じバッチ内のすべてのページは、必ず同じアプリに格納してください。既存のアプリを再利用すると、ページが別々のプロジェクトフォルダーに分散するのを防げます。
3. プロジェクトディレクトリ名を取得します：
   • gemdesign app info を実行して {appuuid} と {projectName} を取得します。
   • <projectDir> = {projectName}__{appuuid} を計算します（projectName から使用できない文字 \/:*?"<>| を削除し、連続する空白を _ に置き換えます）。
   • 例：プロジェクト名が "电商 App" で appuuid が "abc-123" の場合、<projectDir> = "电商_App__abc-123" です。
4. 現在のアプリ情報をユーザーに伝えます（重要 — どのアプリにページを生成するかユーザーが把握できるようにします）：
   • HTML を生成する前に、どのアプリにページを生成するのかを、応答テキストではっきりとユーザーに伝えます。最低限、次の情報を出力します：
     • アプリ名（app info の projectName）
     • アプリ UUID（app info の appuuid）
     • アプリの種類（app info の pageScene。デスクトップ向けは web、モバイル向けは app）
     • プロジェクトディレクトリ（ステップ 3 で計算した <projectDir>）
     • 生成するページ数（ステップ 7 の分析結果）
   • 出力形式の例：

     📦 当前应用信息
     - 应用名称：电商 App
     - 应用 ID：abc-123
     - 应用类型：app（移动端）
     - 项目目录：电商_App__abc-123
     - 本次将生成页面数：5
     

   • 種類の一致：pageScene の値によって、従うべきページレイアウトが決まります。web アプリには web（デスクトップ向け、ワイド画面）のページを、app アプリには app（モバイル向け、ナロー画面）のページを生成してください。種類を混在させてはいけません。web アプリに app ページを含めることも、その逆もできません。
   • ユーザーがアプリを明示的に指定せず、既存のアプリを再利用した場合は、どのアプリを選択したかもユーザーに伝えます（例：「既存のアプリを再利用しました：电商 App」）。誤ったアプリが選ばれた場合にユーザーが中断できるようにします。
   • 一時停止に関する補足：これは情報提供のみであり、アプリの切り替えをユーザーが希望しない限り、返信は必要ありません。出力後は直ちに次のステップに進みます。
5. ローカルサーバーを起動します（ステップ 3）：アプリが存在し、<projectDir> の計算が終わったら、ステップ 3（上記の「ステップ 3：ローカルサーバーを起動する」セクションを参照）を実行します。必ず gemdesign server stop を実行して、以前のサービスを終了してください（アプリを新規作成した場合も再利用した場合も、以前にサービスが稼働していたかどうかにかかわらず、この手順を省略してはいけません）。server stop コマンドの結果が返り（停止済み、または稼働中のサービスがないことを確認した）後に限り、gemdesign server start を実行してローカルサーバーを起動し、ブラウザーでデザイナー http://localhost:<port>/ を開くのは 1 回だけにします。server start が返す <port> を記録し、後続のステップで使用します。これは HARD GATE です。サーバーが稼働しておらず、ブラウザーのプレビューも開いていない状態では、ページ生成に進んではいけません。
   • 重要 — server stop を絶対に省略してはいけません：現在のセッションで稼働中のサービスがないと思われる場合でも、必ず gemdesign server stop コマンドを実行し、コマンドの戻り値を確認してください。「サーバーはすでに稼働中」「前回のワークフローで起動済み」「ブラウザーのプレビューはすでに開いている」などを理由に、stop を省略することは禁止です。stop が {"success":false,"error":"未发现运行中的本地服务"} を返した場合は、停止対象のサービスがないことを示します。その場合は次の start に進めます。
   • 重要 — server start は server stop の完了後に実行してください：stop と start を並行して実行したり、stop より先に start を実行したりしてはいけません。server start の前提条件は、server stop の結果が返っていることです。
   • 生成したページの URL（例：http://localhost:<port>/output/<projectDir>/<pageuuid>.html）でブラウザーを開いてはいけません。生成した HTML でデザイナーが上書きされ、プレビュー画面が破棄されます。
6. スタイルを検索します（任意）：gemdesign style search --keywords "电商,现代,简洁" → 1 つ選択 → gemdesign style get --id <id>
7. 要件を分析します：要件ドキュメントを読み、個別のページに分割します。各ページには、わかりやすい pageuuid（例：home、product-list、cart）を割り当てます。
8. デザインシステムページを生成します（新規作成したアプリのみ）：ステップ 2 で新しいアプリを作成した場合（再利用ではない場合）、ビジネスページを生成する前に、視覚的なスタイルの基準としてデザインシステムページを生成します。その後のすべてのビジネスページは、このスタイルに従う必要があります。app info の pageScene に基づいてデザインシステムの種類を決定し、以下の専用の 「デザインシステムページ仕様」 セクションにある種類の表とページ構造に従ってページを生成します。pageuuid は design-system 固定で、ビジネスページ数には含めません。デザインシステムページはローカルに書き込むだけでなく、必ずプラットフォームに保存してください。保存しないと、アプリに表示されず、スタイルの基準として使用できません。 ストリーミング書き込みワークフローを使い、次の手順を明示的に実行します（ビジネスページと同じ作成・検証・保存の流れです）：
   • ページを作成します（ストリーミングモードに入ります）：gemdesign page create --pageuuid design-system --name "设计系统" --file ./output/<projectDir>/design-system.html
   • ./output/<projectDir>/design-system.html に HTML ファイルを書き込みます（デザインシステムページの仕様に従います。pageuuid は design-system です）。
   • （任意） 検証します：gemdesign validate --file ./output/<projectDir>/design-system.html（エラーを修正して再検証します）。
   • プラットフォームに保存します（必須 — 省略禁止）：gemdesign page save --new --pageuuid design-system --name "设计系统" --file ./output/<projectDir>/design-system.html（デザインシステムページをアプリにアップロードしてプラットフォームに保存し、page list に表示されるようにします。ストリーミングモードは自動的に終了します）。
   • 保存されたことを確認します：gemdesign page list（一覧に design-system が表示されることを確認します）。 アプリを再利用した場合（ステップ 2 で app use により切り替えた場合）は、このステップとステップ 9 を省略します。
9. デザインシステムのレビューゲート（重要 — ステップ 8 でデザインシステムページを生成した場合のみ）：ビジネスページを生成する前に、**「デザインシステムのレビューゲート」**のルール（該当セクションを参照）を必ず適用します。続行条件を評価し、該当する条件がない場合は停止して、そのセクションで指定された形式でデザインシステムへの確認やフィードバックをユーザーに求めます。ユーザーがデザインシステムを確認するか、続行条件を満たすまで、ステップ 10 に進んではいけません。アプリを再利用した場合（ステップ 8 を省略した場合）は、このステップも省略します。
10. 各ページについて（リアルタイム表示には、上記のストリーミング書き込みワークフローを使用します）：
    • HARD GATE — 各ページを書き終えたら直ちに保存し、まとめて保存することは禁止です：生成方法（逐次でも並列でもかまいません）は問いませんが、各ページの HTML を書き終えたら、そのページの page save を直ちに実行しなければなりません（先に validate を実行してから save することは可能です）。これにより .stream.lock が削除され、ストリーミング状態が終了してリモートサーバーに同期されます。save の成功を確認して初めて、そのページは完了となります。すべてのページの HTML を書き終えてから、まとめて page save を実行することは禁止です（まとめて保存するとロックが残り、ページがストリーミング状態のままリモートにも同期されません）。詳しくは、ストリーミング書き込みワークフローの「一括生成：ページごとに直ちに保存」の HARD GATE を参照してください。
    • 以下のページ仕様に従って HTML を生成します（スタイルがある場合は適用します）。ナビゲーション要素の data-uuid には、割り当てられた pageuuid を使用します。すべてのビジネスページは、デザインシステムページで確立された（該当する場合は確認済みの）スタイル基準に従う必要があります。
    • ストリーミング書き込みを使用します（ページごとに、必須の 3 ステップを順に実行します：作成 → HTML の書き込み → 保存）：
      • gemdesign page create --pageuuid <pageuuid> --name "页面名" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html
      • --file のパスに HTML ファイルを書き込みます（必要に応じてパスにフォルダーを含め、フォルダーが存在しない場合は作成します）。
      • （任意） 早期のエラー検出のために gemdesign validate --file ... を実行します。
      • gemdesign page save --new --pageuuid <pageuuid> --name "页面名" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html — 必須です。この手順を実行しないとページはプラットフォームに表示されません。このページの HTML を書き終えたら、次のページに取りかかる前に直ちに実行してください。
    • 重要：page save は最も重要な手順です。HTML をローカルに書き込むだけで page save を実行しない場合、ページはプラットフォームに表示されません。page save は内部で検証します。検証に失敗した場合は修正して再実行してください。
11. 確認します：gemdesign page list
12. デザイナーのリンクを出力します（必須 — 全ページの生成完了後に 1 回だけ出力します）：バッチ内のすべてのページの生成、検証、保存が完了した後（つまり、ステップ 10 のループが完全に終了し、ステップ 11 の確認に成功した後）、ユーザーが最終結果を簡単に表示できるよう、応答テキストにクリック可能なリンクを必ず出力します。リンクは次のとおりです：
    • 名前：gemdesign 设计器（完全一致のテキストを使用し、変更または翻訳しないでください）
    • URL：http://localhost:<port>（ステップ 3 の server start の結果から記録したポートを使用します）
    • 形式（Markdown リンク）：[gemdesign 设计器](http://localhost:<port>)
    • 出力例：gemdesign 设计器

    重要 — ステップ 10 でページごとにこのリンクを出力してはいけません。 バッチ全体の最後に、すべてのページの生成と保存が完了した後で、ちょうど 1 回だけ出力してください。各ページの後にリンクを出力すると会話が煩雑になり、「すべてのページが完了している」という要件にも違反します。

    注：これは、ステップ 3 の「チャットテキストに URL を出力しない」というルールに対する唯一の例外です。ステップ 3 のルールで禁止されているのは、セットアップ時にプログラムからブラウザーを開く代わりに、URL を出力することです。このステップは異なります。すべてのページ生成が完了した後に実行し、ユーザーが希望する場合（ブラウザーを閉じた場合や、デザイナーを再度開きたい場合など）にクリックできるテキストリンクを出力します。これはブラウザーを自動的に開く操作ではなく、最終的な要約に含める Markdown リンクです。

ワークフロー B：会話型生成

会話中にユーザーがページを依頼した場合：

1. 前提条件を完了する：次に進む前に、ステップ 1（CLI のインストール／更新）、ステップ 2（ログイン）、およびステップ 2.5（htmlWorkdir の設定とクリーンアップ）が完了していることを確認します。ステップ 3（ローカルサーバーとブラウザープレビュー）はここでは実行しません。アプリを作成／再利用した後、以下のステップ 5 で実行します。
2. アプリが存在することを確認する（まず再利用！）：
   • htmlWorkdir が設定されていることを確認する：htmlWorkdir はステップ 2.5 で設定済みです（セッション間で保持されます）。app create --workdir と app use --workdir は、パスを htmlWorkdir の設定に自動的に追記します（重複は除去されます）。gemdesign server workdir（フラグなし）で確認します。空の htmlWorkdir が返された場合でも、app create／app use に --workdir ./output を直接渡せます。
   • gemdesign app list を実行して既存のアプリを確認します
   • アプリがすでに存在する場合：gemdesign app use --appuuid <id> --workdir ./output を実行して、対象アプリをデフォルトに設定します。ユーザーが新しいアプリを明示的に依頼しない限り、新しいアプリを作成しないでください。
   • アプリが存在しない場合：gemdesign app create --name "<AppName>" --workdir ./output [--type web|app] [--width <px>] [--height <px>] を実行して作成します（デフォルトの種類は web、デフォルトのキャンバスサイズは web が 1920×1080、app が 440×956 です）。app create は --workdir の下にローカルのプロジェクトフォルダーを同期作成します（htmlWorkdir の設定に自動追記されます）。作成後、直ちに gemdesign app info を実行してアプリの存在を確認し、その appuuid を記録します。このセッションでは、いかなる理由があっても app create を再実行しないでください。 以前に実行中だったサービスは、ステップ 5 の server stop でまとめて停止します。
   • 重要 — アプリの重複を禁止：このセッション中にすでに app create を実行した場合（以前のワークフローの試行中も含む）、再実行しないでください。app list と app use を使って既存のアプリを再利用してください。2 つ目のアプリを作成すると、最初のアプリが空のまま孤立します。
   • 重要 — セッションロックエラーへの対処：app create が stage: "appCreateSession" を返した場合（セッションロックが存在し、リモートにアプリがある場合）、--force を付けて再試行しないでください。代わりに、（1）app use --appuuid <existingApp.appuuid> --workdir ./output を実行して再利用します。（2）別の完了済みタスクによるものであれば、gemdesign app end-session を実行してから、--force を付けずに app create を実行します。（3）stage: "appCreateSessionVerify"（ネットワークエラー）の場合は、待ってから再試行します。CLI は古いロックを自動的にクリーンアップするため（アプリがリモートから削除されている場合）、--force が必要になることはほとんどありません。
   • 重要：すべてのページを必ず同じアプリに追加してください。既存のアプリを再利用すれば、ページが別々のプロジェクトフォルダーに分散するのを防げます。
3. プロジェクトディレクトリ名を取得する：
   • gemdesign app info を実行して {appuuid} と {projectName} を取得します
   • <projectDir> = {projectName}__{appuuid} を計算します（projectName から使用不可文字 \/:*?"<>| を削除し、空白の連続を _ に置き換えます）
4. 現在のアプリ情報をユーザーに伝える（重要 — ページの生成先となるアプリをユーザーが把握できるようにします）：
   • HTML を生成する前に、テキスト応答でページの生成先となるアプリを明確に伝えます。最低限、次の情報を出力します。
     • アプリ名（app info の projectName）
     • アプリ UUID（app info の appuuid）
     • アプリの種類（app info の pageScene — デスクトップ向けは web、モバイル向けは app）
     • プロジェクトディレクトリ（ステップ 3 で計算した <projectDir>）
   • 出力例：

     📦 現在のアプリ情報
     - アプリ名：電商 App
     - アプリ ID：abc-123
     - アプリの種類：app（モバイル向け）
     - プロジェクトディレクトリ：電商_App__abc-123
     

   • 種類の一致：pageScene の値によって、必ず従うページレイアウトが決まります。web アプリには web（デスクトップ向け、ワイド画面）のページを、app アプリには app（モバイル向け、縦長画面）のページを生成します。種類を混在させないでください。web アプリに app ページを含めることはできず、その逆も同様です。
   • ユーザーがアプリを明示的に指定せず、既存のアプリを再利用した場合は、どのアプリを選択したかも伝えます（例：「既存のアプリを再利用しました：電商 App」）。選択したアプリが正しくない場合、ユーザーが中断できるようにしてください。
   • 中断不要：これは情報提供のみであり、アプリを切り替えたい場合を除いて、ユーザーの返答は不要です。情報を出力したら、直ちに次のステップに進みます。
5. ローカルサーバーを起動する（ステップ 3）：アプリが存在し、<projectDir> を計算できたら、ステップ 3（上記の「ステップ 3：ローカルサーバーの起動」セクションを参照）を実行します。まず必ず gemdesign server stop を実行し、以前のサービスを停止します（アプリを新規作成したか再利用したか、また以前にサービスが実行されていたかどうかにかかわらず、このステップを省略することはできません）。server stop コマンドが返り、停止したこと、または実行中のサービスがないことを確認してから、gemdesign server start を実行してローカルサービスを起動し、デザイナー http://localhost:<port>/ をブラウザーで一度だけ開きます。server start が返す <port> を記録し、後続のステップで使用します。これは厳格なゲートです。サービスが実行され、ブラウザープレビューが開くまでは、ページ生成に進んではいけません。
   • 重要 — server stop を絶対に省略しない：現在のセッションで実行中のサービスがないと思われる場合でも、必ず gemdesign server stop コマンドを実行し、コマンドの返却結果に従ってください。「サーバーはすでに実行中」「前回のワークフローで起動済み」「ブラウザープレビューをすでに開いている」などの理由で、stop を省略することは禁止されています。stop が {"success":false,"error":"未发现运行中的本地服务"} を返した場合、停止するサービスがないことを意味するため、次の start に進めます。
   • 重要 — server stop の完了後に server start を実行すること：stop と start を並行して実行したり、start の後に stop を実行したりすることは禁止されています。server start の前提条件は、server stop が結果を返していることです。
   • 生成ページの URL（例：http://localhost:<port>/output/<projectDir>/<pageuuid>.html）でブラウザーを開かないでください。生成 HTML でデザイナーが上書きされ、プレビュー画面が失われます。
6. デザインシステムページを生成する（新規作成したアプリのみ）：ステップ 2 で新しいアプリを作成した場合（再利用ではない場合）、ビジネスページを生成する前に、ビジュアルスタイルの基準としてデザインシステムページを生成します。以降のビジネスページはすべて、このスタイルに従います。app info の pageScene に基づいてデザインシステムの種類を決め、専用の 「デザインシステムページ仕様」 セクションにある種類表とページ構成に従ってページを生成します。pageuuid は design-system に固定され、ビジネスページの数には含まれません。デザインシステムページはローカルに書くだけでなく、必ずプラットフォームに保存してください。保存しないとアプリに表示されず、スタイルの基準としても機能しません。 次の明示的な手順に従い、ストリーミング書き込みワークフローを使用します（ビジネスページと同じ作成・検証・保存の手順です）。
   • ページを作成します（ストリーミングモードに入ります）：gemdesign page create --pageuuid design-system --name "设计系统" --file ./output/<projectDir>/design-system.html
   • ./output/<projectDir>/design-system.html に HTML ファイルを書き込みます（デザインシステムページ仕様に従います。pageuuid は design-system です）
   • （任意） 検証します：gemdesign validate --file ./output/<projectDir>/design-system.html（エラーを修正して再検証します）
   • プラットフォームに保存します（必須 — 省略禁止）：gemdesign page save --new --pageuuid design-system --name "设计系统" --file ./output/<projectDir>/design-system.html（デザインシステムページをアプリにアップロードしてプラットフォーム上に保存し、page list に表示します。ストリーミングモードは自動的に終了します）
   • 保存されたことを確認します：gemdesign page list（一覧に design-system が表示されることを確認します） アプリを再利用した場合（ステップ 2 で app use により切り替えた場合）は、このステップとステップ 7 を省略します。
7. デザインシステムのレビューゲート（重要 — ステップ 6 でデザインシステムページを生成した場合のみ）：「デザインシステムのレビューゲート」のルール（下記のセクションを参照）を適用します。続行条件に該当しない場合は、停止してからユーザーに確認またはフィードバックを求めます。デザインシステムが確認されるか、続行条件を満たすまではステップ 8 に進まないでください。アプリを再利用した場合（ステップ 6 を省略した場合）は、このステップも省略します。
8. 読みやすい pageuuid（例：.html を除いたファイル名。アプリ内で一意）を決めます
9. Page Spec に従って HTML を生成し、ナビゲーション要素の data-uuid に pageuuid を使用します。デザインシステムページで定めた（該当する場合は確認済みの）スタイル基準に従います。
10. ストリーミング書き込みを使用する（必須の 3 ステップ：作成 → HTML の書き込み → 保存）：
    • gemdesign page create --pageuuid <pageuuid> --name "<pageName>" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html
    • --file のパスに HTML ファイルを書き込みます（必要に応じてパスにフォルダーを含め、存在しない場合はディレクトリを作成します）
    • （任意） 早期にエラーを検出するため、gemdesign validate --file ... を実行します
    • gemdesign page save --new --pageuuid <pageuuid> --name "<pageName>" --file ./output/<projectDir>/<subfolder>/<pageuuid>.html — 必須。このステップを実行しないと、ページはプラットフォームに表示されません
    • 重要：HTML をローカルに書き込むだけで page save を呼び出さない場合、ページはプラットフォームに表示されません。
11. 結果をユーザーに説明します
12. デザイナーへのリンクを出力する（必須 — すべてのページ作業が完了した後、一度だけ出力）：ページの生成、検証、保存が完了したら、ユーザーがデザイナーを簡単に開けるよう、テキスト応答にクリック可能なリンクを必ず出力します。リンクの要件は次のとおりです。
    • 名前：gemdesign 设计器（正確なテキスト。変更や翻訳をしないでください）
    • URL：http://localhost:<port>（ステップ 3 の server start の返却結果から記録したポートを使用します）
    • 形式（Markdown リンク）：[gemdesign 设计器](http://localhost:<port>)
    • 例：[gemdesign 设计器](http://localhost:4056)

    重要 — このリンクはワークフローの最後に一度だけ、正確に出力してください。 中間ステップごとに出力しないでください。これはユーザーが任意にクリックするためのテキストリンクであり、ブラウザーを自動的に開く操作ではありません。これがステップ 3 の「チャットに URL を出力しない」ルールと矛盾しない理由については、ワークフロー A のステップ 12 を参照してください。 ユーザーが変更を依頼した場合：

13. gemdesign page get --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html を実行して、編集用の HTML と DSL を取得します
14. HTML を変更します（DOM の調整、インタラクション DSL の追加・削除、jsHandle の更新）
    • 大幅な変更には、ストリーミング書き込みワークフローを使用します：HTML を書き換えます（最初から作成する場合は古いファイルを先に削除し、追加のみの場合は追記します）
15. （任意） gemdesign validate --file ./output/<projectDir>/<subfolder>/<id>.html — エラーがあれば修正します
16. gemdesign page save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html — 必須
17. 要件ドキュメントを更新する必要がある場合：gemdesign page doc save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/updated-doc.md

ワークフロー C：既存ページの変更

1. 前提条件をすべて完了する：次に進む前に、ステップ 1（CLI のインストール／更新）、ステップ 2（ログイン）、およびステップ 2.5（htmlWorkdir の設定＋クリーンアップ）が完了していることを確認します。ステップ 3（ローカルサーバー＋ブラウザープレビュー）はここでは実行しません。以下のステップ 4 で、app info により <projectDir> を確認した後に実行します。
2. プロジェクトディレクトリ名を取得する：gemdesign app info を実行し、<projectDir> = {projectName}__{appuuid} を計算します（projectName から使用できない文字 \/:*?"<>| を削除し、連続する空白を _ に置き換えます）。
3. 現在のアプリ情報をユーザーに出力する（重要 — ユーザーが、変更対象のページがどのアプリに属するかを把握できるようにします）：
   • HTML を変更する前に、対象ページがどのアプリに属するかを、必ずテキスト応答でユーザーにはっきり伝えます。最低限、以下を出力します。
     • アプリ名（app info の projectName）
     • アプリ UUID（app info の appuuid）
     • アプリの種類（app info の pageScene。デスクトップ向けは web、モバイル向けは app）
     • プロジェクトディレクトリ（ステップ 2 で計算した <projectDir>）
   • 出力形式の例：

     📦 現在のアプリ情報
     - アプリ名：電商 App
     - アプリ ID：abc-123
     - アプリの種類：app（モバイル）
     - プロジェクトディレクトリ：電商_App__abc-123
     

   • 種類の一致：pageScene の値によって、従わなければならないページレイアウトが決まります。web アプリには web（デスクトップ、ワイド画面）ページを、app アプリには app（モバイル、ナロースクリーン）ページを生成します。種類を混在させてはいけません。web アプリに app ページを含めることはできず、その逆も同様です。
   • これにより、特に複数のアプリがある場合に、変更が正しいアプリに反映されることをユーザーが確認できます。別のアプリを希望する場合は、ここで中断して gemdesign app use から切り替えられます。
   • 一時停止可能：これは情報提供のみを目的としています。ユーザーがアプリの切り替えを希望しない限り、返信は不要です。出力後、直ちに次のステップに進みます。
4. ローカルサーバーを起動する（ステップ 3）：アプリが存在し、<projectDir> の計算が完了したら、ステップ 3（上記の「ステップ 3：ローカルサーバーを起動する」セクションを参照）を実行します。以前のサービスを終了するため、必ず先に gemdesign server stop を実行します（アプリを新規作成したか再利用したか、また以前にサービスが起動していたかどうかにかかわらず、この手順は省略できません）。server stop コマンドの結果が返る（停止済み、または実行中のサービスがないことを確認する）まで、gemdesign server start を実行してローカルサーバーを起動してはいけません。その後、ブラウザーでデザイナー http://localhost:<port>/ を一度だけ開きます。後続のステップで使うため、server start の戻り値に含まれる <port> を記録します。これは厳格なゲートです。サービスが稼働していない場合、またはブラウザープレビューが開いていない場合は、ページの変更に進んではいけません。
   • 重要 — server stop を絶対に省略しないでください：現在のセッションで実行中のサービスがないと思われる場合でも、必ず gemdesign server stop コマンドを実行し、コマンドの戻り値に従ってください。「サーバーはすでに起動している」「前回のワークフローで起動した」「ブラウザープレビューはすでに開いている」などの理由で stop を省略してはいけません。stop が {"success":false,"error":"未发现运行中的本地服务"} を返した場合、停止対象のサービスがないことを意味します。この場合は、次の start に進めます。
   • 重要 — server start は server stop の完了後に実行してください：stop と start を並行して実行したり、start を stop より先に実行したりしてはいけません。server start を実行するには、事前に server stop の結果が返っている必要があります。
   • 生成ページの URL（例：http://localhost:<port>/output/<projectDir>/<pageuuid>.html）でブラウザーを開いてはいけません。デザイナーが生成 HTML で上書きされ、プレビュー画面が破壊されます。
5. gemdesign page list を実行し、対象ページを探します。
6. gemdesign page get --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html を実行し、編集用の HTML と DSL を取得します。
7. HTML の構造とインタラクションを分析します。
8. 必要に応じて HTML を変更します。
   • 大幅な変更の場合は、ストリーミング書き込みワークフロー（上記を参照）を使用して HTML を書き換えます。
9. （任意）検証する：gemdesign validate --file ./output/<projectDir>/<subfolder>/<id>.html を実行し、エラーがあれば修正します。
10. プラットフォームに保存する（必須）：gemdesign page save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/<id>.html
    • 重要：ローカルファイルだけを変更して page save を実行しない場合、変更はプラットフォームに同期されません。page save は内部で検証を行います。
11. 要件ドキュメントを更新する必要がある場合：gemdesign page doc save --pageuuid <id> --file ./output/<projectDir>/<subfolder>/updated-doc.md
12. デザイナーへのリンクを出力する（必須 — ページの作業がすべて完了した後に一度だけ出力）：ページの変更、検証、保存が完了したら、ユーザーが更新後の結果を簡単に確認できるよう、テキスト応答にクリック可能なリンクを必ず出力します。リンクは以下のとおりです。
    • 名前：gemdesign 设计器（正確にこのテキストを使用し、変更も翻訳もしないでください）
    • URL：http://localhost:<port>（ステップ 3 の server start の戻り値から記録したポートを使用します）
    • 形式（Markdown リンク）：[gemdesign 设计器](http://localhost:<port>)
    • 例：gemdesign 设计器

    重要 — このリンクはワークフローの最後に一度だけ出力してください。 中間ステップのたびに出力してはいけません。これはユーザーが必要に応じてクリックするテキストリンクであり、自動的にブラウザーを開く操作ではありません。このリンクがステップ 3 の「チャットに URL を出力しない」というルールと矛盾しない理由の詳細については、ワークフロー A のステップ 12 を参照してください。

---

デザインシステムページの仕様

アプリを新規作成する際は、ビジネスページを生成する前に、ページ UUID を design-system に固定したデザインシステムページを生成し、アプリのビジュアルスタイルの基準とします。その後に生成するすべてのビジネスページは、このデザインシステムで定めた色、角丸、シャドウ、コンポーネントスタイルに従う必要があります。デザインシステムページには、GemDesign ページ仕様（以下を参照）も適用されます。技術スタックのルール、CSS のルール、Lite-Interaction DSL などが含まれます。

タイプの判定

app info が返す pageScene フィールドに基づいて、デザインシステムのタイプを判定します。

pageScene	デザインシステムのタイプ	主な目的
app	モバイル向け C 端末の体験重視型	消費者向けで、体験と感情を重視したモバイルアプリ UI のデザインシステム紹介ページを作成します。C 端末アプリでよく使われるインタラクションパターンとビジュアルコンポーネントを紹介し、コンテンツの閲覧、ソーシャルインタラクション、パーソナライズされた体験を重視します。ページはモバイル幅のレイアウトを直接使用し（スマートフォンのフレームや外枠のラッパーは使用しません）、モバイルアプリのインターフェースをそのまま表示します。
web	エンタープライズ向け管理機能重視型	機能を重視した、企業や管理者向けの Web UI デザインシステム紹介ページを作成します。管理システムでよく使われるフレームワークの構造、データ操作、フォーム入力コンポーネントを紹介し、情報密度、操作効率、ステータスのフィードバックを重視します。ページは全幅の管理画面レイアウトを使用し、実際の管理システムのインターフェースを再現します。
その他	柔軟な分析	要件に基づいて最適なデザインシステムのタイプを分析し、Header + Design Tokens + Components の基本構造を使用して柔軟に設計します。

ページ構成 — app タイプ（モバイル向け C 端末）

ヘッダー

• システムのロゴ／アイコン、システム名（中国語）、簡単な説明を含めます
• 暗色またはブランドカラーの背景に白いテキストを使用します
• 上部固定、またはページ上部のバナーとして配置します

セクション 1：デザイントークン

• セクションタイトルのスタイル：左側に色付きの境界線バー（border-l-4、スタイルのプライマリカラーを使用）を配置し、大きなタイトルとタグバッジを組み合わせます
• カラーシステム：カラースウォッチカードを使用して、プライマリカラー、セカンダリカラー、機能色、中立色を表示し、Hex 値と用途の説明を添えます
• 角丸とシャドウ：立体的なブロックを使用して、段階ごとのシャドウ効果、大きな角丸の仕様（例：16px／24px）、ソフトシャドウ、拡散する光彩を表示します

セクション 2：コンポーネント

• メディアカード：画像とテキストのカード（大きな画像モード）、石積み／ウォーターフォール型カード、動画／ライブ配信のカバーコンテナ
• ソーシャル要素：ユーザーアバター、いいね／お気に入り／コメントのアイコン（マイクロインタラクションのスタイル付き）、フォローボタン
• インタラクティブコンテナ：ボトムシートパネル（Bottom Sheet／Drawer）、Toast 通知（コンテナ内のスタイル表示としてのみ表示し、ページレイアウト内で固定された実際のポップアップ効果をシミュレートしないでください）
• ナビゲーション：没入感のあるトップバー（透明なグラデーション）、ボトムナビゲーションバー（アイコン＋テキスト、選択状態のアニメーションのヒント付き）
• 空状態／読み込み：読み込みプレースホルダー（Skeleton）、空状態のイラストプレースホルダー

ページ構成 — web タイプ（エンタープライズ管理）

ヘッダー

• システムロゴ／アイコン、システム名（中国語）、簡潔な説明を含めます
• ダークカラーまたはブランドカラーの背景に白いテキストを使用します
• ページ上部に固定するか、ページ上部のバナーとして配置します

セクション 1：デザイントークン

• セクションタイトルのスタイル：左側に色付きのボーダーバー（border-l-4、スタイルのプライマリカラーを使用）を配置し、大きなタイトルとタグバッジを組み合わせます
• カラーシステム：カラースウォッチカードを使ってプライマリカラー、セカンダリカラー、機能カラー、ニュートラルカラーを表示し、Hex 値と使用上の注意を記載します
• タイポグラフィの階層：カード内に H1〜H4、Body、Caption の各レベルを表示し、フォント／サイズ／ウェイトの注釈を付けます
• ボーダーの角丸とシャドウ：立体的なブロックを使って、異なるレベルのシャドウ効果を表示します

セクション 2：コンポーネント

• グリッドレイアウト（grid-cols-1 lg:grid-cols-2/3）を使って、コンポーネントの表示を整理します
• 構造／シェル：サイドバーのナビゲーション項目（選択時／ホバー時）、上部のパンくずリスト、ページヘッダー
• データ表示：データテーブル（ヘッダー、ゼブラストライプ、行のホバー状態、ページネーション）、タブページ、タグ（Tag／Badge）、キーと値のペアのリスト
• フォーム要素：入力欄（Input）、ドロップダウン選択（Select）、チェックボックス／ラジオボタン（Checkbox／Radio）、スイッチ（Switch）。デフォルト、ホバー、フォーカス、エラーの各状態を必ず含めます
• アクション：アクションボタン（Primary、Secondary、Ghost、Icon Button）
• フィードバック／オーバーレイ：グローバルメッセージ（Message）、通知（Notification）、ダイアログ（Modal／Dialog、表示例として示します。全画面モーダルは使用しないでください）、読み込み状態（Skeleton／Spinner）

ページ構成 — その他のタイプ

ヘッダー + デザイントークン + コンポーネントの基本構成に従い、要件分析に基づいて適切なコンポーネントとビジュアルスタイルを決定します。

---

デザインシステムのレビューゲート（重要）

デザインシステムのページを生成する場合（新規作成アプリのみ）は、ビジネスページを生成する前に、必ずこのレビューゲートを適用してください。 このゲートは、再利用するアプリ（デザインシステムの生成をスキップする場合）およびワークフロー C（既存ページの変更）には適用されません。

このゲートが必要な理由（第一原理）

デザインシステムのページは、大きな影響を及ぼす意思決定のポイントです。ここで決定したカラー、タイポグラフィ、シャドウ、角丸、コンポーネントのスタイルは、その後に生成されるすべてのビジネスページに引き継がれます。生成直後のタイミングが自然なチェックポイントとなる理由は、次の 2 つの特性にあります。

1. エラーコストの非対称性。 ここで誤ったスタイルを決定すると、その後に生成されるすべてのビジネスページに波及します。N ページができた後で修正するには N ページを作り直す必要がありますが、直ちに修正すればユーザーとのやり取りは 1 回で済みます。ゲートを省略した場合の予想コストはページ数に比例して増加しますが、一時停止するコストは一定で、ごくわずかです。

2. 情報状態の切り替わり。 生成前のエージェントは、要件ドキュメントからユーザーのビジュアル上の好みを推測することしかできず、状態は不確かです。生成後は、ユーザーがブラウザーにレンダリングされた具体的な案を確認できるため、状態は確かなものになります。この時点で初めて、ユーザーは確認または方向転換に役立つ情報を得られます。ここで反応を把握することが最も大きな価値をもたらします。これは、ワークフロー全体の中で最も低コストで方向修正できるポイントです。

判断ルール — 停止するか、続行するか？

デザインシステムのページを生成、検証、保存した後、以下の続行条件を評価してください。デフォルトは停止して確認することです。続行条件を少なくとも1つ明確に満たす場合に限り、確認せずに続行できます。

続行条件（いずれか1つを満たせば、一時停止を省略して業務ページへ直接進めます）：

#	条件	続行しても安全な理由
C1	ユーザーが最初のリクエストでビジュアルスタイルを明示している（例：具体的なブランドカラー、「深蓝科技风」、「某Appのスタイルを参考にする」、ムードボード、16進数コード）	スタイルの方向性はすでにユーザーによって確定されており、この確認で埋めるべき情報の不足がありません。
C2	ユーザーがこのセッション中に style search + style get を実行しており、デザインシステムのページが選択されたスタイルを忠実に反映している	ユーザーは明示的な選択操作を通じて事前に好みを示しています。デザインシステムは新たな提案ではなく、その選択を実現するものです。
C3	ユーザーがレビューを明示的に省略している（例：「不用确认，直接全部生成」、「全自动跑完」、「不要中途停」）	ユーザーが自ら確認の機会を放棄しています。明示された希望を尊重してください。

続行条件を満たさない場合 → 必ず停止してください。 これがデフォルトであり、要件文書だけをもとに新規アプリを作成する場合に最もよく当てはまります。

停止するとき — 提示する内容

単に「デザインシステムが生成されました」と伝えるだけでは不十分です。ユーザーが最小限の手間で確認または方向転換できるよう、判断に必要な情報をまとめた要約を提示してください。

1. 決定したスタイル — メインカラー／サブカラー（16進数コード付き）、全体の方向性（例：テクノロジー感／温かみ／ミニマル）、主要コンポーネントのデザイン（カードの角丸、シャドウのスタイル、ボタンのスタイル）。曖昧にせず具体的に説明してください。
2. 要件との関連性 — 決定したスタイルと要件を結び付けてください（例：「『若者向けのソーシャルプラットフォーム』という要件文書の位置付けを踏まえ、メインカラーには彩度の高い紫を選びました…」）。
3. 明確な確認依頼 — AskUserQuestion ツールを使って選択肢を提示してください。推奨する選択肢：
   • 「確認して、業務ページの生成を続ける」
   • 「配色を調整する」
   • 「全体のスタイルの方向性を調整する」
   • （「その他」から、ユーザーが自由に回答することもできます）

ユーザーの回答後

• ユーザーが確認した場合 → 業務ページの生成に進み、確認済みのデザインシステムをすべてのページに適用する確定済みのスタイル基準として扱います。
• ユーザーが調整を依頼した場合 → まずデザインシステムのページを変更（編集 → 検証 → 保存）します。その後、大きな変更や主観に関わる変更（例：「テクノロジー感のある青」から「温かみのあるオレンジ」への変更）であれば再提示し、小さな変更で明確に解決している場合（例：16進数コードを1つ変更する）であればそのまま進めます。状況に応じて判断してください。ここでいう「保存」とは、gemdesign page save --pageuuid design-system --file ./output/<projectDir>/design-system.html を再実行することを意味します（--new フラグは付けないでください。ページは手順7/5ですでにプラットフォーム上に存在しており、--new を付けると pageuuid が重複してエラーになります）。gemdesign page list を実行して更新を確認してください。
• デザインシステムが (a) ユーザーに確認されるか、(b) 上記の続行条件を満たすまでは、業務ページの生成を開始しないでください。

---

GemDesign ページ仕様

HTML を生成する際は、この仕様に必ず従ってください。gemdesign validate コマンドでこれらのルールがすべて検証されます。

概要

GemDesign ページは HTML（DOM） + TailwindCSS（スタイル） + Lite-Interaction DSL（インタラクション） で構成されます。

技術スタックのルール

使用可能：HTML のネイティブタグ、TailwindCSS（<script> タグ経由）、CSS（<style>）、Font Awesome、ECharts
使用禁止：あらゆる JavaScript フレームワーク（Vue／React／jQuery）、手書きの DOM JavaScript（jsHandle を除く）、CSS Hack、vh 単位

使用可能なスクリプトは次の2種類のみ

1. <script id="interaction-data"> — Lite-Interaction JSON 文字列（インタラクションロジック）
2. <script id="funcName">function funcName(event){...}</script> — jsHandle カスタム関数

依存関係

<script src="https://cdn.tailwindcss.com"></script>
<link rel="stylesheet" href="https://cdn.bootcdn.net/ajax/libs/font-awesome/6.4.0/css/all.min.css">

<script src="https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js"></script>

<script src="https://cdn.jsdmirror.com/npm/echarts/map/js/china.js"></script>

レイアウトルール

1. レイアウト用のコンポーネントクラスには TailwindCSS を使用してください。
2. flexbox レイアウトを優先してください。Flexbox、パディング、gap はインターフェースのレイアウトにおける基本的なツールです。
3. ブロック要素は単純な要素（テキスト、装飾画像）には使用できますが、レイアウトには使用しないでください。すべての要素はデフォルトで border-box ボックスモデルになります。
4. 固定要素（サイドバー、ナビゲーションバー）には明示的な高さ／幅を設定し、コンテンツ領域には対応するパディングを設定する必要があります。
5. マスクとモーダル／ドロワーは入れ子にする必要があります。マスク／オーバーレイレイヤーには半透明の背景色（例：bg-black/50）を設定し、内側のモーダル／ドロワーのコンテンツコンテナには不透明な背景色（例：bg-white）を設定する必要があります。コンテンツコンテナが透明だと、マスクの色が透けて見えるため、重大な違反となります。
6. 要素を中央揃えにするときは、絶対に mx-auto や m-auto を使用しないでください。親要素で flex レイアウトの justify-center と items-center を必ず使用してください。

CSS ルール

ルール 1：vh 単位の禁止

禁止事項：vh 単位、vh を含む Tailwind CSS クラス、および vh を含むクラス（例：h-[80vh]）。

ルール 2：最優先のレッドライン — マージンは絶対に禁止

ページ全体で、いかなるマージンも絶対に使用してはいけません。これには、ネイティブ CSS と、マージンの意味を持つすべての Tailwind クラス名が含まれます。モデルは「アイコンの間隔」や「要素の上下の間隔」にマージンを使いがちです。この習慣を必ず克服してください。

出力コードに以下のいずれかのプレフィックス（正負を問わず）が含まれている場合、重大な違反となります。

• m-（例：m-2、m-auto）
• mt-（例：mt-4）
• mb-（例：mb-3、mb-4、mb-6）
• ml-（例：ml-2）
• mr-（例：mr-1、mr-2）
• mx-（例：mx-auto）
• my-（例：my-4）
• space-x-／space-y-（内部実装でもマージンが使われるため、絶対に禁止）

必須の代替方法 — 違反しやすい以下のケースで使用してください：

• ❌ 違反例 1（アイコンとテキストの間隔）：<i class="fas fa-edit mr-1"></i>編集

• ✅ 正しい例 1（flex と gap を使用）：<div class="flex items-center gap-1"><i class="fas fa-edit"></i><span>編集</span></div>

• ❌ 違反例 2（タイトル／段落の下の間隔）：<h3 class="mb-4">タイトル</h3><form>...</form>

• ✅ 正しい例 2（親要素で flex と gap を使用）：<div class="flex flex-col gap-4"><h3>タイトル</h3><form>...</form></div>

• ❌ 違反例 3（中央揃え）：class="mx-auto" または class="m-auto"

• ✅ 正しい例 3（親要素で中央揃え）：親要素で flex justify-center items-center を使用

Lite-Interaction DSL（コア）

すべてのインタラクションは、バッククォートで囲んだ JSON 配列として <script id="interaction-data"> 内に宣言します。

interface TriggerEvent {
  original: string;        // Selector: #id or .class only
  trigger: 'click' | 'mouseover' | 'mouseenter' | 'mouseleave' | 'mousedown' | 'mouseup';
  actions: Action[];
}

interface Action {
  operation: 'show' | 'hide' | 'openModal' | 'closeModal' | 'addClass' | 'removeClass' | 'openPage' | 'back' | 'openLink' | 'jsHandle';
  target?: string;         // Required for show/hide/addClass/removeClass. #id only, multiple: "#id1,#id2"
  params?: string;         // addClass/removeClass: class names (comma-separated); openPage: pageUuid; openLink: URL. Forbidden for jsHandle. Must be a plain string, no code/variables.
  funcName?: string;       // Only for jsHandle
  operationTitle?: string; // Required for jsHandle/addClass/removeClass (2-8 Chinese chars)
  animation?: string;      // Animation effect name
  animationTime?: number;  // Animation duration in seconds
  delayTime?: number;      // Delay before execution in seconds
}

セレクタールール（重要）

ルール	詳細
original と target	#id または .class のみ — 属性セレクター（[data-xxx]）は禁止
original	単一の要素のみ — 複数のセレクターは禁止
target	複数の ID を指定できます："#id1,#id2" — .class は禁止
要素にデータ属性しかない場合	必ず要素に id を追加し、DSL では #id を使用してください

操作の優先順位

1. show／hide — モーダルの開閉に優先して使用
2. addClass／removeClass — CSS の変更
3. openPage — ページ遷移（パラメーターには pageUuid 文字列のみを指定）
4. back — 戻る
5. jsHandle — 上記では要件を満たせない場合のみ使用

jsHandle のルール

1. 各関数はそれぞれ独自の <script> タグに記述する
2. スクリプトの id は関数名と完全に一致させる必要があります
3. パラメーターは event のみ
4. API 呼び出しは禁止

<script id="tabSwitchXxx">
function tabSwitchXxx(event) {
  // full implementation
}
</script>

ページ遷移

ナビゲーション要素では、HTML タグに id と data-uuid を追加してください。data-uuid の値は、page save --new に渡す --pageuuid と一致する必要があります。

<a id="nav-home" data-uuid="home" href="javascript:void(0);">首页</a>

これらの要素に対する openPage イベントを interaction-data に追加しないでください。自動生成されます。

画像プレースホルダー

プレースホルダー URL を使用してください。プラットフォームが実際の画像に置き換えます。

<img src="./api/searchImage?query=premium laptop on white background&width=400&height=400" class="w-full h-full object-cover" />

ボタンのルール

• すべてのボタンに type="button" を指定してください
• type="submit" は使用しないでください
• リンクには href="#" ではなく、href="javascript:void(0);" を使用してください

設計上の制約

• シャドウ：短く濃いシャドウではなく、拡散シャドウを使用してください：shadow-[0_8px_30px_rgba(0,0,0,0.04)]
• ネイティブコントロール：オプションの切り替えに<select>やラジオボタンを使わず、カプセル型のセグメントコントロールを使用してください
• 横スクロール：scrollbar-hideでスクロールバーを非表示にしてください
• モーダル／マスク／ドロワー：デフォルトでhiddenクラスを追加し、ネストした構造を使用してください。マスク／オーバーレイ層には半透明の背景色（例：bg-black/50）を設定し、内側のモーダル／ドロワーのコンテンツコンテナには不透明な背景色（例：bg-white）を設定する必要があります。コンテンツコンテナが透明であることは重大な違反です。マスクの色が透けて、ポップアップのコンテンツ領域がマスクと同じ色に見えてしまいます。例：

  <div id="modalMask" class="modal-mask hidden fixed inset-0 bg-black/50 flex justify-center items-center z-50">
    <div class="bg-white rounded-lg p-6">
      
    </div>
  </div>
  

• CSSオーバーライド：ステータスクラス（hiddenなど）がコンポーネントクラスをオーバーライドする場合は、スタイルシートで組み合わせてください：.modal-mask.hidden { display: none; } — @apply hiddenは使用しないでください

スクリプトの順序

1. TailwindCSS（<head>内）
2. EChartsの依存関係（<head>内、任意）
3. tailwind.configの設定
4. ECharts設定スクリプト（<script id="echarts_*" type="echarts">、任意）
5. jsHandle関数スクリプト（<script id="funcName">、任意）
6. interaction-dataは最後の<script>タグでなければなりません

ページテンプレート全体

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdn.tailwindcss.com"></script>
  <link rel="stylesheet" href="https://cdn.bootcdn.net/ajax/libs/font-awesome/6.4.0/css/all.min.css">
  <script>
    tailwind.config = {
      theme: {
        extend: {
          colors: { primary: '#1890ff' }
        }
      }
    };
  </script>
  <style>
    .modal-mask.hidden { display: none; }
  </style>
</head>
<body>
  <div id="app">
    
  </div>

  
  

  
  <script id="interaction-data">
`
[
  {
    "original": "#elementId",
    "trigger": "click",
    "actions": [
      { "operation": "show", "target": "#targetId" }
    ]
  }
]
`
  </script>
</body>
</html>

検証ルールの概要

gemdesign validateコマンドは、次の項目をチェックします。

#	ルール	チェック内容
1	interaction_data_exists	<script id="interaction-data">が存在する
2	dsl_json_valid	コンテンツが有効なJSON配列である
3	selector_exists	元／ターゲットのセレクターがすべてDOMに存在する
4	selector_format	#idと.classのみを使用し、属性セレクターを使用していない
5	original_single	originalのセレクターが1つのみである
6	target_no_class	targetが#idのみを使用し、.classを使用していない
7	jshandle_func_match	各funcNameに対応する<script id="funcName">がある
8	script_id_funcname_match	script idが関数名と一致する
9	button_type	すべてのボタンがtype="button"であり、type="submit"を使用していない
10	no_vh	クラスまたはスタイルにvh単位を使用していない
11	no_hash_href	href="#"を使用していない
12	image_url_format	プレースホルダー画像のURLが./api/searchImage?query=...&width=...&height=...の形式であり、width/heightが数値で、&の前後にスペースがない
13	data_uuid_complete	data-uuidを持つタグにidもある
14	interaction_data_last	interaction-dataが最後のscriptタグである

ヒント

• HARD GATE — .html / .meta.jsonファイルを直接作成することは厳禁です：ページを新規作成する場合は、HTMLを書き込む前に必ずpage createを実行して（.stream.lockを作成して）ください。lockなしでHTMLを直接作成することは重大な違反です。既存のページを変更する場合は、事前に必ずpage getを実行してください。.meta.jsonはCLI専用で管理します（page getで生成され、page saveで読み取られます）。エージェントが作成または変更することは厳禁です。
• HARD GATE — page saveを省略することはできません：HTMLファイルを書き込んだ後、必ずgemdesign page saveを呼び出してプラットフォームに保存してください。ローカルファイルを生成するだけでpage saveを呼び出さないことは重大な違反です。そのページはプラットフォームに表示されず、ユーザーは閲覧も使用もできません。完全な手順：page create → HTMLを書き込む → page save。page saveには仕様の検証機能が組み込まれており、検証に失敗するとエラーが返されます。修正後、page saveを再実行してください。
• HARD GATE — 複数ページを生成する場合は、各ページを完成後すぐに保存してください：複数のページを並行して進めることはできますが、各ページのHTMLを書き終えたら、対応するページのpage saveを直ちに実行してください（.stream.lockを削除し、ストリーミングを終了して、リモートと同期します）。成功を確認してから、そのページを完了としてください。すべてのページを生成し終えるまで待って一括でsaveすることは厳禁です。そうするとlockが残り、ページがストリーミング状態のままになり、リモートサーバーと同期されません。
• page createの応答にはrequiredNextStepsフィールドが含まれ、以降に必ず実行する手順が記載されています。この応答を受け取ったら、手順に従って実行してください。HTMLを書き込んだ後に停止してはいけません。
• gemdesign validateは任意の早期エラー検出ツールです。page saveには検証機能が組み込まれていますが、validateを使えば保存前にエラーを検出できます。
• すべてのページのHTMLをローカルに保存してください：編集してプラットフォームに保存するためのパスは./output/<projectDir>/<pageuuid>.htmlです。まずgemdesign app infoを使って、必ず<projectDir> = {projectName}__{appuuid}を計算してください。CLIは冪等であり、<projectDir>をすでに含むパスを渡しても重複して追加されません。
• 新しいページを作成する場合は、読みやすい値（例：home、login）を--pageuuidに指定してください。ナビゲーション要素のdata-uuidにも同じ値を使えば、保存後に更新する必要がありません。
• 変更前に、gemdesign page get --file <path>を使って編集可能なHTMLとDSLを取得してください。
• ページ仕様の全文は、CLIプロジェクトディレクトリ内のpage-spec.mdにあります。