d3k

d3k Agent Runtime

d3k は、このタスク用のローカル Web ランタイムです。安定した Portless URL の背後で開発サーバーを起動し、プロジェクトごとに固定された Chrome プロファイルを管理します。また、サーバーログ、ブラウザーのコンソール出力、ネットワークアクティビティ、操作、スクリーンショットを 1 つのタイムラインに記録します。

このスキルが起動したら、d3k を操作してください。実行方法をユーザーに伝えるだけでは不十分です。

リクエストの解釈

• 「d3k でプロジェクトをテスト／開発させてください」：ランタイムと画面表示ブラウザーを準備し、準備完了を確認したら、ユーザーに操作を引き継ぎます。証拠を調べるのは、ユーザーが問題を再現するまで待ってください。
• 「d3k でテスト／デバッグ／修正してください」：ランタイムを準備した後、管理対象ブラウザーを操作して、自律的に調査します。
• 意図が曖昧な場合は、まずランタイムとブラウザーを起動してください。どちらの場合にも安全で有用な対応です。

d3k の起動または再利用

プロジェクトのルートから実行してください。

1. アプリのプロセスを起動する前に、Portless の正規の準備状況を確認してください。

d3k portless status --json

"setupRequired": true の場合は、次を実行してください。

d3k portless setup

macOS では、システム管理者の認証ダイアログが開きます。ユーザーが承認するまで待ち、その後 d3k portless status --json を再実行してください。"canonical": true、"serviceInstalled": true、"setupRequired": false になるまで d3k を起動しないでください。承認されない場合、または承認できない場合は中止し、問題を説明してください。localhost への直接接続に黙って切り替えてはいけません。

2. 既存のプロジェクトランタイムを確認してください。

d3k status --json

"running": true、"ready": true、"routing": "portless"、"browserConnected": true を報告し、ポート番号を含まない https://...localhost の appUrl が実際に設定されている場合に限り、再利用してください。実行中のセッションが "routing": "direct" を報告する場合は、その d3k セッションを停止し、Portless の準備が整ってから再起動してください。2 つ目の開発サーバーやブラウザーを起動しないでください。

3. d3k がインストールされていない場合は、インストールしてください。

bun install -g dev3000

Bun が利用できない場合に限り、npm install -g dev3000 を使用してください。

4. エージェントのシェル／プロセスツールを使い、d3k をバックグラウンドまたはセッション保持モードで起動してください（デフォルトでは非 TUI）。

d3k -t

この長時間実行コマンドの終了を待たないでください。後で監視または停止できるよう、プロセス／セッションのハンドルを保持してください。& を付けてシェルから実行するより、実行ツールのバックグラウンド／セッション機能を優先してください。

対象 URL がすでにわかっている場合は、管理対象ブラウザーでその URL を開くように渡してください。

d3k -t --app-url "<url>"

パッケージマネージャー、開発コマンド、ポートは d3k に自動検出させてください。検出が誤っている場合、またはユーザーが指定した場合に限り、--command、--script、--port を追加してください。

5. ランタイムの準備が整うまでポーリングしてください。

d3k status --json

ステータス応答が "ready": true、"routing": "portless"、"browserConnected": true を報告し、ポート番号を含まない https://...localhost の appUrl が設定されている場合に限り、準備完了と判断してください。アプリ内部のポートは実行ごとに変わる場合があります。起動に失敗した場合は、保持しているプロセスの出力と d3k logs --type server を調べてください。別の開発サーバーを起動しないでください。

ユーザー主導のテスト

ユーザーが「テストさせて」と言った場合：

1. ステータス応答にアプリ URL と "browserConnected": true が含まれていることを確認してください。
2. 監視対象のブラウザーを利用できることをユーザーに伝えてください。
3. d3k のプロセスを実行したままにし、ユーザーが動作を再現するのを待ってください。
4. 再現できたと報告されたら、次を実行してください。

d3k errors --context
d3k logs -n 200

ユーザーがテスト中に、画面表示ブラウザーを自動化に置き換えないでください。

エージェント主導のテスト

d3k が監視しているブラウザーを操作してください。

d3k agent-browser snapshot -i
d3k agent-browser click @e2
d3k agent-browser fill @e3 "text"
d3k errors --context

URL を開く際は --require-d3k-browser を使用し、失敗時に別のブラウザーが黙って作成されないようにしてください。

d3k agent-browser --require-d3k-browser open "<url>"

問題の再現またはコードの変更を行うたびに、関連する操作を再実行し、d3k errors --context をもう一度確認してください。

証拠を確認するコマンド

場当たり的なログ抽出より、次を優先してください。

d3k status --json
d3k errors --context
d3k logs -n 200
d3k logs --type browser
d3k logs --type server

成果物は ~/.d3k/<project>/ 以下に保存されます。これには session.json、ログ、スクリーンショット、Chrome プロファイルが含まれます。

ブラウザーと認証の安全性

デフォルトでは、ブラウザーの起動は d3k に任せてください。プロジェクトごとの Chrome プロファイルには、ログイン状態、Cookie、ローカルストレージが保持されます。

Google OAuth、Supabase 認証など、認証が重要なフローでは、raw Chrome、Playwright、ブラウザー MCP セッション、手動の CDP 接続、agent-browser --profile に決して置き換えないでください。これらの方法では別のブラウザー／プロファイルが使われ、「このブラウザーまたはアプリは安全でない可能性があります」と表示されることがあります。

管理対象のブラウザーが利用できない場合は、保持されている d3k プロセスを停止または中断してから、d3k をクリーンに再起動してください。別のブラウザーを作成して回避しないでください。

--headless は CI で使用する場合、または明示的に要求された場合に限り使用してください。ブラウザーの監視が意図的に不要な場合に限り、--servers-only を使用してください。

運用ルール

• d3k と同時に npm run dev、bun run dev、または別の開発サーバーを実行しないでください。
• d3k status --json が稼働中の d3k を報告している場合、2つ目の d3k を起動しないでください。
• 編集や再テストの間も d3k を稼働させたままにしてください。
• ユーザーから新しいプロファイルを明示的に求められない限り、プロジェクト固有の Chrome プロファイルを維持してください。
• ヘッド付きブラウザーをユーザーに引き継ぐ場合はランタイムを稼働させたままにしてください。停止するのは、依頼された場合、またはタスクでクリーンな再起動が必要な場合に限ります。
• デフォルトでは、Canonical Portless HTTPS ルーティングが必須です。ユーザーから localhost への直接ルーティングを明示的に求められない限り、--no-portless を追加したり、PORTLESS=0 を設定したりしないでください。