edgeone-makers-env-adaption

ランタイム環境の適応ガイド

このドキュメントでは、さまざまな AI コーディング環境における EdgeOne Makers Skills の特別な制約と適応ルールについて説明します。 現在の対象：WorkBuddy（Tencent のサンドボックス化 IDE）

---

🚦 クイックリファレンス：プレビューの判断ツリー

「表示／プレビュー」の手順に進んだら、present_files の呼び出し方を決める前に、まずこれを読んでください。

            ┌─ Delivering finished work? ── Yes ──→ present_files(deployed EdgeOne URL) ✅
            │
Enter       ┤
preview     │                      ┌─ dev server running? ─ Yes ──→ present_files(http://127.0.0.1:8088/) ✅
            └─ Still iterating? ───┤
                                    └─ No ──→ start edgeone makers dev → present_files(...)

実行したいこと	正しい方法	誤った方法（動作しません）
ローカル開発サーバーをプレビューする	present_files("http://127.0.0.1:8088/")	❌ /path/to/index.html を渡す（IDE が file:// 経由で開きます）
デプロイ済みプロジェクトをプレビューする	?eo_token=... を付けて present_files(deploy_url) を呼び出す	❌ ローカルの dist/index.html パスを渡す
開発サーバーを起動する	edgeone makers dev --name <p> --skip-env-sync	❌ python -m http.server / npx serve
開発サーバーが起動しているか確認する（エージェント側の API チェック）	curl --noproxy '*' http://127.0.0.1:8088/api/... ✅ 動作します（同じサンドボックス内）	❌ curl localhost:8088 / 通常の curl（プロキシと IPv6 が原因で 404/000 になります）
開発サーバーが起動しているか確認する（ユーザー向け）	present_files(http://127.0.0.1:8088/)（プラットフォームのトンネル）	❌ ユーザーに 127.0.0.1:8088 を開くよう伝える — ユーザーのブラウザーからサンドボックスにはアクセスできません

絶対に守るべきルール：Makers プロジェクト内での HTML／URL のプレビューは、必ず HTTP プロトコル経由で行ってください。file:// は便利に見えますが、その場合 fetch／SSE／Blob／KV はすべて動作しません。

違反時の症状のセルフチェック（次の症状が見られたら、すぐに前の手順に戻ってください）

• ブラウザーのコンソールに TypeError: Failed to fetch／CORS policy エラーが表示される
• ページの HTML は正常に読み込まれるのに、すべての JS リクエストが 404 になる
• SSE／EventSource が接続直後に切断される
• ローカルでは動作するのにデプロイ後は動作しない（またはその逆）

---

WorkBuddy サンドボックス環境

WorkBuddy はサンドボックス化されたリモート IDE 環境です。AI コーディングタスクの実行時には、ローカル開発環境とは異なる次の制約があります。

⚠️ よくある誤解：WorkBuddy はヘッドレス環境ではなく、デスクトップ IDE のサンドボックスです。

• CLI の対話型プロンプト（サイト選択画面や確認画面）はサンドボックス内で停止するため、このセクションに記載されている非対話型フラグを使用してください。
• ただし、ブラウザーログイン（edgeone login --site <x>）は完全に動作します — WorkBuddy はホスト OS のブラウザーを起動し、OAuth コールバックをサンドボックスに戻します。

デプロイ／リンク時のログインでは、ブラウザーログインを既定で使用し、ブラウザーログインが失敗すると確認された場合に限り -t <token> に切り替えてください。呼び出し元が「Agent」だからという理由だけで、トークンログインに切り替えてはいけません。

---

1. 非対話型モード（すべての CLI コマンドで対話型プロンプトを回避する必要があります）

WorkBuddy サンドボックス内では、CLI の対話型プロンプトによってプロセスが停止したままになります。すべての edgeone CLI コマンドに非対話型フラグを指定する必要があります。

シナリオ	必須フラグ	理由
ローカル開発	--skip-env-sync	「環境変数を同期しますか？」という確認をスキップします
プロジェクトのリンク	--name <project>	対話型のプロジェクト選択画面をスキップします
未ログイン時の認証	-t <token>	トークンを直接渡し、ログインポップアップを表示しません
デプロイ出力	--json	機械可読な JSON を出力し、ANSI の解析を回避します

# Correct: local development
edgeone makers dev --name my-project --skip-env-sync

# Correct: deploy
edgeone makers deploy -n my-project --json

# Wrong: will hang
edgeone makers dev

2. ログイン認証

トークンの解決優先順位（CLI は自動的に次の順序で確認します）：

1. -t <token> コマンドライン引数
2. EDGEONE_PAGES_API_TOKEN 環境変数
3. <cwd>/.edgeone/auth.json（edgeone login --local によって書き込まれます）
4. ~/.edgeone/ のグローバル認証情報

推奨される方法：ブラウザーログインと --local フラグの併用：

edgeone login --site china --local

--local は認証情報をプロジェクトディレクトリの <cwd>/.edgeone/auth.json に書き込み、ホームディレクトリへの書き込み制限を回避します。

ログイン状態の検出：

edgeone whoami  # exit 0 = logged in, exit 1 = not logged in (does not hang)

実際にログインが必要になるのはいつですか？ ログインが必要なのは、プロジェクトで Blob やその他の認証情報が必要なバックエンドを使う場合に限られます。これは依存関係の連鎖によるものです。Blob にはプロジェクトのリンクが必要で、リンクには先にログイン済みのアカウントが必要です。 そのため、静的のみのサイトで edgeone makers dev を実行する場合は、ログインしなくても問題なく動作します。静的のみのプレビューでログインを強制しないでください。 開発やデプロイで Blob ストレージにアクセスする時点で、ログイン（または -t <token>）が必須になります。（トリガー条件とリンクの連鎖については makers-storage を参照してください。）

CLI バージョン要件：>= 1.6.7（古いバージョンには非対話型の修正がなく、whoami がハングします）

---

3. ネットワーク分離（Bash からの開発サーバーへの到達性）

Bash ツールと edgeone makers dev は同じサンドボックス（同じマシン）内で実行されるため、Bash からループバックの開発サーバーに到達できます。「Bash の curl は分離されていて 404 を返す」という以前の主張は誤りです。失敗の原因はネットワーク分離ではなく、プロキシ（§5）とIPv6 の localhost（§4）です。

検証方法	利用可否	備考
組み込みブラウザープレビュー（present_files）	✅ 利用可能	プラットフォームトンネルを使用します。サンドボックスの開発サーバーをユーザーのブラウザーから見られる唯一の方法です
ユーザーのシステムターミナル	✅ 利用可能	curl http://127.0.0.1:8088/
Bash ツールの curl（エージェント側の API チェック）	✅ --noproxy '*' と 127.0.0.1 の併用時のみ利用可能	通常の curl localhost:8088 は失敗します：（a）localhost が ::1 に解決される（§4）、（b）プロキシがリクエストを横取りする（§5）

実用上のルール：

• テスト中に API エンドポイントをエージェント側で検証する場合は、Bash から curl --noproxy '*' http://127.0.0.1:8088/... を使用してください。これは動作します（作成→アップロード→いいねの一連のフローの検証に使用しました）。
• Bash の curl でユーザーにページを表示しようとしないでください。ユーザーのブラウザーはサンドボックス内の 127.0.0.1:8088 にアクセスできません。ユーザー向けにプレビューするには、開発 URL を present_files（プラットフォームトンネル）に渡すか、デプロイして公開 URL を共有してください。

---

4. IPv4 を強制する（localhost ではなく 127.0.0.1）

開発サーバーは IPv6 デュアルスタック（::）でリッスンしますが、サンドボックスでは localhost が ::1 に解決されるため、誤った 404 が発生します。

# Correct
curl http://127.0.0.1:8088/

# Wrong (404 in the sandbox)
curl http://localhost:8088/

プレビュー URL でも 127.0.0.1 を使用する必要があります：

present_files: http://127.0.0.1:8088/

---

5. プロキシによる横取り（curl には --noproxy が必要）

サンドボックスでは http_proxy 環境変数が設定されており、curl はデフォルトでプロキシを経由します。そのため、SSE のストリーミング応答がプロキシに遮断されます。

# Correct
curl --noproxy '*' http://127.0.0.1:8088/api/chat

# Wrong (returns "Empty reply" / status 000)
curl http://127.0.0.1:8088/api/chat

組み込みブラウザープレビューはプロキシの影響を受けません。

---

6. ホームディレクトリへの書き込み制限

サンドボックスでは ~/.edgeone/ への書き込みがブロックされますが、プロジェクトディレクトリへの書き込みは許可されています。

パス	書き込み可能	備考
<cwd>/.edgeone/	✅	--local の書き込み先
~/.edgeone/	❌	EPERM エラー

setLocalData EPERM は実行中のサービスには影響しません。影響するのは CLI のローカル状態の永続化のみです。

---

7. コマンド実行モード（同期と非同期）

コマンド	実行モード	理由
npm install	フォアグラウンド同期	通常は10～30秒かかります。バックグラウンドで実行すると、後続のコマンドで依存関係が不足する可能性があります
edgeone makers dev	バックグラウンド非同期（run_in_background）	長時間実行されるプロセスなので、会話をブロックしてはいけません
edgeone makers deploy	バックグラウンド非同期（run_in_background）	コールドデプロイ（ビルド → アップロード → Process → 公開）には、通常2～10分以上かかります。フォアグラウンドの実時間予算（約100秒）を超えると、進捗が表示され続けていてもCLIがデプロイ途中でSIGKILLされ（終了コード137）、最後のURLの行が失われます。バックグラウンドで実行し、完了通知を待ってください。

7.2 バックグラウンドでのデプロイ — その理由と、強制終了の実際の意味

• フォアグラウンドでの強制終了は実時間予算によるもので、ハングではありません。 このサンドボックスのフォアグラウンドBashコマンドには、固定の実時間予算（約100秒）があります。上限に達すると、プロセスが進捗を表示し続けているかどうかにかかわらず、プロセスツリー全体がSIGKILLされます（exit 137 = 128 + 9）。デプロイ中、CLIは約10秒ごとに Deployment in progress... elapsed: ~XXs と表示しますが、これらのハートビート行によって予算がリセットまたは延長されることはありません。そのため、「出力が続いているのに約100秒で強制終了される」のは想定どおりであり、停止しているわけではありません。
• CLIを強制終了しても、通常デプロイは失敗しません。 デプロイそのものはサーバー側で実行されます。Created deployment / Process の段階でフォアグラウンドのCLIが強制終了されても、サーバー上では処理が続行され、公開まで完了している可能性が非常に高いです（実際の確認例では、約100秒で強制終了されたデプロイが後に公開済みであることが確認され、開始から完了まで約674秒かかりました）。deploy を再実行すると（同じ -n <project> を指定）、既存のプロジェクトが再利用され、URLが返されます。
• デプロイには必ず run_in_background: true を使用してください。 これにより、CLIはフォアグラウンドの予算を超えても動作し、公開済みURLを含む最後の --json 行を出力できます。ターンをまたいでタスクをポーリングせず、<task-notification> の完了イベントを待ってください。（ターンをまたいだ TaskOutput では、ハンドルが「not found」と報告されることがありますが、プロセスは完了しています。）
• --json を指定しても、標準出力／標準エラー出力には進捗ハートビートが表示され、整ったJSON行が1行だけ出力されるわけではありません。 結果オブジェクトは最後の行から解析し、進捗行は無視してください。（これはCLIの出力形式の問題であり、強制終了の挙動とは無関係です。「出力がない＝プロセスが終了した」と判断しないでください。サンドボックスは標準出力のバイト数ではなく、OSのプロセス状態で稼働状況を判定します。）
• バックグラウンドプロセスは使用後にクリーンアップしてください。 edgeone makers dev を実行したままにするとポート8088を占有し続け、次の開発／デプロイと競合する可能性があります。セッションを次に進めるときに、TaskStop を使うか、プロセスを終了してください。

7.1 プレビューと開発サーバーの全手順（HTTP必須、file://は禁止）

開発が完了したら、開発サーバーを起動して、プレビューを直接表示してください。「プレビューしますか？」と尋ねてはいけません。手順全体は次のとおりです。

⚠️ WorkBuddyのデフォルトの動作：HTMLファイルを作成すると、プラットフォームがfile://経由でプレビューを自動的に開くことがありますが、無視してください。これは有効なプレビューではありません。edgeone makers dev の起動を待ってから、HTTP URL経由で開き直して上書きする必要があります。

1. edgeone makers dev --name <project> --skip-env-sync を起動します（バックグラウンド非同期。§7を参照）。
2. 開発サーバーの準備が整うまで2～3秒待ちます。
3. http://127.0.0.1:8088/ を present_files に渡します（localhost ではなく 127.0.0.1 であることに注意してください。§4を参照）。
4. ユーザーに次のように伝えます。「プロジェクトのローカルプレビューが起動しました。ご確認ください。問題がなければ、こちらで直接公開デプロイできます。」

ユーザーの確認後に限り、edgeone makers deploy -n <project> --json を実行します（バックグラウンド非同期。フォアグラウンドの実時間予算を超えるため、§7および§7.2を参照してください）。

⛔ file:// プレビューは厳禁です

絶対にローカルの HTML パスを present_files に渡さないでください。IDE は file:// プロトコル経由で開くため、fetch／SSE／Blob／KV がすべて動作しなくなります。例外はありません。「ちょっと確認するだけ」という状況も認められません。

# ✅ Correct
present_files("http://127.0.0.1:8088/")                                       # dev server
present_files("https://my-app-w9t0lxe8.edgeone.cool?eo_token=...")            # after deploy (full URL with query params)

# ❌ Wrong (IDE opens via file://, all APIs fail)
present_files("/Users/foo/dist/index.html")
present_files("./dist/index.html")
present_files("file:///Users/foo/dist/index.html")

# ❌ Wrong (truncated query params — the user gets a 401 when they open it)
present_files("https://my-app-w9t0lxe8.edgeone.cool")                         # missing ?eo_token=...

⚠️ URL の切り詰め＝401：デプロイ URL の ?eo_token=...&eo_time=... は認証パラメーターです。切り詰められると、ユーザーが URL を開いたときに 401 UNAUTHORIZED が返されます。返信内のすべての URL には、表、リスト、脚注内の参照先も含め、クエリー文字列全体を含めてください。

違反時の症状（次の症状が見られた場合は、すぐに「クイックリファレンス」を再確認してください）：

• コンソール：TypeError: Failed to fetch ／ Cross-Origin Request Blocked
• ページの DOM は正常に見えるのに、すべての fetch ／ XMLHttpRequest 呼び出しが失敗する
• SSE／EventSource 接続が直ちに切断される
• @edgeone/pages-blob の呼び出しで Missing: deployCredential が報告される（プロジェクトがリンク済みでも、file:// の下には HTTP コンテキストがないため）

⛔ セルフホストの HTTP サーバーは厳禁です

edgeone makers dev を次のいずれかに置き換えてはいけません。

• python -m http.server
• npx serve ／ npx http-server
• Node.js の http.createServer ／ express で起動するローカルサービス

理由：edgeone makers dev は Blob の認証情報を注入し、Cloud Functions のルーティングをエミュレートし、Edge Functions を処理して、ミドルウェアチェーンを実行します。セルフホストのサーバーが配信できるのは静的ファイルのみです。その動作は本番環境と異なるため、「ローカルでは動くのにデプロイすると動かない」（またはその逆）という不可解な問題が発生します。

---

10. Next.js の HMR クロスオリジン設定

Next.js 15 以降の開発サーバーは、デフォルトで localhost のみを信頼します。サンドボックス内で 127.0.0.1 経由でアクセスするとクロスオリジンとして扱われるため、HMR WebSocket がブロックされ、ページが応答しなくなります。

next.config.js に必ず追加してください：

allowedDevOrigins: ["127.0.0.1"]

注：値はポートを含まない、http:// プレフィックスのないホスト名のみです。

---

11. プロジェクトのリンク（Blob／KV に必須）

Blob Storage または KV を使用するプロジェクトでは、開発を開始する前にプロジェクトがリンク済みである（.edgeone/project.json が存在する）ことを確認してください。リンクされていない場合、Blob／KV の呼び出しで Missing: deployCredential が報告されます。

前提条件 — 先にログインしてください：リンク（および Blob／KV の利用）には、ログイン済みアカウントが必要です。必要な手順は、Blob → リンク必須 → リンクにはログインが必要です。edgeone whoami が終了コード 1 を返した場合は、リンクを試みる前に edgeone login（ブラウザー）を実行するか、トークンを使って edgeone makers link -t <token> を実行してください。未認証のままリンクを試みないでください。

リンク済みかどうかを確認する：

cat .edgeone/project.json 2>/dev/null && echo "LINKED" || echo "NOT LINKED"

リンクする方法：

# Explicit link (auto-creates the project if it does not exist)
edgeone makers link --name <project-name> -t <token>

# Or implicitly link via the dev command
edgeone makers dev --name <project-name> --skip-env-sync

--name で指定したプロジェクトがリモートに存在しない場合、link コマンドが自動的に作成します。

注：静的なプロジェクトだけの場合でも、コードが @edgeone/pages-blob をインポートしていると、リンクしなければ必ずエラーになります。

---

12. フレームワークのバージョン要件

フレームワーク／パッケージ	最小バージョン	理由
EdgeOne CLI	>= 1.6.7	非対話型の修正、whoami の即時失敗、--json のサポート
EdgeOne CLI（匿名デプロイ／claim のみ）	>= 1.6.29	これより前のバージョンには --anonymous と claim がありません
Next.js	16.x	フレームワークアダプターが新しいバージョンに追従しています
@edgeone/pages-blob	>= 0.0.14	旧バージョンには既知の不具合があります

古いバージョンを手動で固定するのではなく、create-next-app@latest を使用してください。

---

13. WorkBuddy の組み込みブラウザーでは、ブラウザー標準のダイアログ（alert／confirm／prompt）が動作しません

WorkBuddy の右側のプレビューパネルでは、window.alert()／window.confirm()／window.prompt() は表示されません。ユーザーの操作を待たずに呼び出しがすぐに戻るため、if (confirm("Delete?")) のような条件で実行されるハンドラーは何もせずに終了します（削除ボタンを押しても何も起きないように見えます）。同じページでも、ユーザーが実際に使用している Chrome／Safari では問題なく動作します。

ルール：ページ内で確認、入力、通知を行う場合は、ページ内のカスタムモーダル（ボタンに JS を割り当てた <div> オーバーレイ）を使用してください。ブラウザー標準の alert／confirm／prompt に依存してはいけません。コードレビューでは問題がないように見え、ユーザーが公開 URL を自分のブラウザーで開けば動作しますが、開発時や検証時に WorkBuddy のプレビューでは何も表示されず、正常に機能しません。

14. ユーザーに実行用コマンドを渡さないでください

ユーザーは WorkBuddy のサンドボックスでターミナルを使えません。指示として表示するコマンドはすべて意味のないテキストです。ユーザーは実行できず、技術に詳しくないユーザーには内容も理解できません。

状況	こちらを行う	こちらは行わない
匿名プロジェクトの所有権を取得する必要がある	バックグラウンドで edgeone login --claim --local --json を実行し、claimLoginUrl をクリック可能なリンクとして提示します。ユーザーが所有権の取得を完了すると、リスナーがプロジェクトを自動的にリンクします	❌ edgeone makers claim --sid <token> を表示すること。または、デプロイ JSON に含まれる claimUrl をそのまま提示すること（CLI はログイン状態を把握できません）
ユーザーがログインする必要がある	説明したうえで、自分で edgeone login --site <china|global> --local を実行します	❌「ターミナルで edgeone login を実行してください」
インストールが必要なものがある	Bash で自分で実行します	❌「npm install -g edgeone を実行してください」

シェルにアクセスできるのはあなたです。活用してください。本当に自動化できない場合（たとえば、開いたブラウザーウィンドウでログインを完了してもらう場合）に限ってユーザーに入力を頼み、必要なことを明確に伝えてください。

14.1 重要な結果をプロセスメッセージに折りたたまれないようにしてください

WorkBuddy では、実行中または実行直後の Bash コマンドと同じメッセージで出力された内容が、折りたたみ可能なプロセスエントリーにまとめられる場合があります。ユーザーがデプロイを依頼した場合、デプロイ URL と所有権取得リンクをそこに含めてはいけません。含めると、ユーザーには何も表示されません。

状況	こちらを行う	こちらは行わない
デプロイが完了した直後	Bash の呼び出しが完全に終了するまで待ってから、結果（URL と所有権取得リンク）を独立したメッセージとして送信します	❌ デプロイを実行したメッセージと同じメッセージで結果を送ること。またはコマンドの標準出力に添えること
長時間かかるコマンドを実行している	ツールの呼び出しが終了した後、後続のメッセージでのみ進捗を報告します	❌ コマンドの出力と同じターン内に「こちらが URL です」と書くこと