DSH iOS シミュレータ

DeepSeek Harness の会話の中に、ライブで操作可能な iOS シミュレータを組み込む——USB 接続の実機 iPhone にも対応。
_{22 個のエージェントツール • ライブ MJPEG サイドバーパネル • シミュレータと USB 実機 • リスト/フィードの行操作 • SwiftUI プレビューのホットリロード}

_{npm: @zseven-w/dsh-ios · 現在のプラグインリリース: 0.1.0-rc.3 · DSH 0.1.1-rc.1 で動作確認済み}

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

_{npm: @zseven-w/dsh-ios · 現在のプラグインリリース: 0.1.0-rc.3 · DSH 0.1.1-rc.1 で検証済み}

_{DSH の会話からそのまま実機を操作 — 左はエージェントのツール呼び出し、右はライブデバイスパネル}

`、デフォルト 2m）または `follow`（`duration_seconds` の有界ライブキャプチャ。デフォルト 10、最大 60——ハングし続けることはありません）。出力は約 300 行 / 30 KB が上限で、絞り込みのヒントが付きます。 | `udid`（省略可）、`mode`（`snapshot`/`follow`）、`duration`、`duration_seconds`、`bundle_id`、`predicate`（生の NSPredicate。`bundle_id` より優先）、`level`（`default`/`info`/`debug`）、`grep` | ### プレビューツール | ツール | 機能 | 主なパラメータ | | --- | --- | --- | | `ios_sim_preview` | シミュレータ内でライブに動く SwiftUI プレビューのホットリロード。`start`（デフォルト）はパッケージを検証し、プラグインキャッシュに使い捨てのホストアプリを生成し（あなたのパッケージ内には決して書き込みません）、パッケージをシミュレータ向け dylib としてビルドし、ホストをインストール・起動して、ソースを監視します——編集のたびに再ビルドして再起動なしでホットスワップします（約 2–5 秒）。コンパイルエラーでも最後に成功したプレビューは維持され、エラー末尾は `status` から確認できます。同時に動くプレビューセッションは 1 つだけです。 | `packagePath`（`start` では必須）、`udid`、`action`（`start`/`status`/`stop`）、`previewFilter`（プレビュー名への大文字小文字を区別しない部分一致） | ### デバッグツール | ツール | 機能 | 主なパラメータ | | --- | --- | --- | | `ios_sim_processes` | 1 台のシミュレータの実行中アプリプロセスを、そのシミュレータ自身の launchd から一覧表示します（ホストから見える pid、名前、バンドル ID）——バックトレース/リークの pid の取得元です。実機の udid を渡すと、代わりに devicectl 経由で電話機のプロセスを一覧表示します。 | `udid`（省略可）、`filter`（名前/バンドル ID への大文字小文字を区別しない部分一致） | | `ios_sim_backtrace` | ワンショットのバッチ LLDB（attach → thread backtrace → detach。対話的にはなりません）。出力は約 200 行が上限でメインスレッドが先頭、対象プロセスは必ず再開されたことが検証されます。macOS が attach を拒否した場合（開発者モードがオフ）は、Xcode の `sample` エンジン（サスペンドしない）にフォールバックし、有効化のヒントを報告します。シミュレータ専用——実機は理由付きで拒否されます。 | `udid`（省略可）、`pid` / `bundle_id`、`all_threads`（デフォルト true） | | `ios_sim_leaks` | Xcode の `leaks` ツールでリークを解析します。`summary`（リーク数、リーク総バイト数、上位約 30 タイプ）または `memgraph`（Xcode Instruments で開く `.memgraph` アーティファクト。ここで解析されることはありません）。スキャン中アプリはサスペンドされますが、必ず再開されます。シミュレータ専用。 | `udid`（省略可）、`pid` / `bundle_id`、`mode`（`summary`/`memgraph`） | | `ios_sim_app_info` | インストール済みアプリの情報: アプリバンドルパス、書き込み可能なデータコンテナ、Info.plist の値——シミュレータでは `simctl appinfo`（`get_app_container` フォールバック付き）、USB 実機では `devicectl` 経由。未インストールの場合は `installed: false` と、`ios_sim_list_apps` を案内する `note` を返します。 | `udid`（省略可）、`bundle_id`（必須） | ## 表示面 - **サイドバーパネル——「iOS 模拟器」。** ライブ映像は常駐の右側パネルに表示されます（会話を押しのける固定ドック。狭いビューポートでは中央のオーバーレイ）。パネルはライブ MJPEG ストリームを描画し、動画の上でのクリックでタップ、ドラッグでジェスチャを直接受け付けます。アイコンツールバー（Home、スクリーンショット、回転、更新）のボタンにはホバーツールチップが付きます。サイズコントロールは**适应**（パネル幅にフィット）、**50–125%**（デバイスの論理幅に対するズーム）、**S / M / L** プリセット（デバイスの短辺を基準にサイズ決定。横向きではデバイスの物理サイズが保たれるよう拡大縮小します）。フレームスタイルは**无框 / 边框 / 真机框**（フレームなし / ベゼル / 実機風の筐体）で、角丸は比例して計算されます。デバイスが横向きに回転するとパネルは快適なサイズまで自動的に広がり、縦に戻ると元の幅を復元します——その間に行った手動ドラッグは常に優先されます。左端のハンドルでパネルを広げたり狭めたりできます（最大 960 px。ダブルクリックでデフォルト幅にリセット）。USB 接続の iPhone がストリーム対象の場合、同じパネルが電話機の WebDriverAgent MJPEG ストリームを同じコントロールで表示します。 - **コンパクトな会話カード。** ツール結果はインライン画像なしの 1 行カードとして描画されます。統一された**「iOS 模拟器」**タイトル、アクションサブラベル（起動 / スクリーンショット / 操作 / ビルド＆実行 / WebDriverAgent 起動）、デバイス名、ステータスバッジ、「サイドバーで開く」キュー。行をクリックするとパネルが開きます。ボタン、リンク、ライブフレーム自体のクリックでは開きません。 - **入力欄の上のステータスカプセル。** パネルが閉じていてストリームがオンラインの間、入力欄の上に緑ドットの小さなピル（`` · 实时）が表示され、クリックでパネルが開きます。セッションゲート付きで、現在の会話にシミュレータ結果がマウントされている間だけ描画・ポーリングされ、それがないセッションに切り替えると停止します。 - **標準モードと Code モード。** 標準セッションはホストが投影する `presentationMeta` を使います。ネストした Code モード（PTC）のディスパッチは meta を運ばないため、クライアントは永続化された結果 JSON から同一の meta を再構築します——パネル、カード、カプセルは両方のモードで機能します。 ## セキュリティ - ブラウザが serve-sim のポートと直接通信することはありません。すべてのバイトは DSH ウェブサーバーのオリジンにあるプラグイン所有の `/_dsh/dsh-ios/*` ルートを通ります。`/stream/`（MJPEG プロキシ）、`/screenshot/`（キャッシュ済み PNG）、`/ws?token=…`（HID 制御リレー）、さらに `/grant`、`/capture`、`/status` エンドポイントです。 - トークンは HMAC-SHA256 ケーパビリティ（`base64url(payload).base64url(mac)`）で 10 分以内に失効し、DSH ホームごとの鍵（`/cache/dsh-ios/stream-access.key`、0600、原子的に作成）で署名されます。 - すべてのルートはケーパビリティを確認する前にループバック/信頼済み転送ガードを適用します。ループバックのピアアドレス、ループバック `Host`（DNS リバインディングは拒否）、Fetch-Metadata/Origin チェックです。スクリーンショットルートはプラグインキャッシュディレクトリ内のファイルのみを配信します（シンボリックリンクは拒否、`realpath` による包含チェック）。 - serve-sim はループバックのみで専用ポート範囲（3181–3244）のフォアグラウンド子プロセスとして動くため、ユーザー自身のポート 3100 の serve-sim には決して触れません。`--host` は使いません。。同じ署名付きルートのガードの内側にあり、ブラウザが通信するのは依然として DSH ウェブサーバーのオリジンだけです。 - **孤児プロセスの引き取り/回収**——以前の DSH ホストが正常終了せずに殺され、その serve-sim ヘルパーが生き残った場合、同じデバイスは引き取られます（孤児のハンドシェイクが正とみなされます）。別のデバイスのスロットに居座る古いヘルパーは `serve-sim -k` で回収され、一度だけ再起動されます。 - **キープアライブ + アイドル停止**——クラッシュしたストリームはバックグラウンドで再起動します（約 5 秒後）。コンシューマがゼロになると、ストリームは 5 分後に自動停止します。意図的な停止が妨げられることはありません。（実機ランナーは意図的にアイドル回収の対象外です。再起動には数分の `xcodebuild` 再ビルドがかかるためです。） ## 要件 - **フル Xcode が入った macOS**——Command Line Tools だけでは不十分です。`xcodebuild`、`xcrun simctl`、シミュレータランタイムはすべて Xcode に同梱されています。 - **Xcode に iOS シミュレータランタイムが少なくとも 1 つ**インストールされていること。 - **パネルには DSH ≥ 0.1.0-rc.6 と Web バンドル**が必要です。ヘッドレスプロファイルでも動作します。22 個のツールはすべて通常どおり機能し、ライブ映像だけがありません。 - **非 macOS ホスト**: プラグインはロードされ 22 個のツールも登録されますが、呼び出しはすべて説明付きのエラーを返します（`iOS Simulator requires macOS with Xcode …`）。 - **serve-sim** はこのプラグインの npm 依存関係として同梱されるため、実際のインストールではローカルで解決されます。開発ツリーでは `npx -y serve-sim` フォールバックがカバーします（初回使用はネットワークが必要）。 - **AXe**（省略可——AXe ベースのツールだけが必要とします: `ios_sim_ui_tree` / `ios_sim_tap_element`、およびシミュレータ上の `ios_sim_ui_rows` / `ios_sim_tap_row`）: `brew install cameroncooke/axe/axe`、またはプラグインに固定リリース（v1.8.0、SHA-256 検証済み）を `~/Library/Caches/dsh-ios/bin` へ自動ダウンロードさせます。`DSH_IOS_AXE_BIN` で解決結果を上書きできます。`DSH_IOS_AXE_OFFLINE=1` でダウンロードを無効化できます。 - **Vision OCR**（省略可——`ios_sim_find_text` / `ios_sim_tap_text` だけが必要とします）: プラグインは初回使用時に同梱の `assets/ocr.swift` を `swiftc` で `~/Library/Caches/dsh-ios/bin/ocr` にコンパイルします（zh-Hans + en-US 認識）。 - **lldb attach には macOS の開発者モードが必要**です。`sudo DevToolsSecurity -enable` を一度実行してください。それまでは `ios_sim_backtrace` が Xcode の `sample` エンジン（サスペンドしない）を使い、`ios_sim_leaks` は有効化のヒント付きで縮退動作します。 - **実機 iPhone**——画面がロック解除された USB 接続の iPhone（ロック画面では WebDriverAgent を起動できません。。最初の WDA ビルドでは署名済みの WebDriverAgentRunner がインストールされます。プロンプトに従ってデバイスで証明書を信頼し、無料チームの署名プロファイルが失効したら（7 日間の有効期間）`ios_real_start_wda` を再実行してください。 ## DSH にインストール ```sh dsh plugin --profile web add @zseven-w/dsh-ios@latest dsh web ``` ## クイックスタート 典型的な最初の会話: 1. **デバイスを探す**——「利用できるシミュレータを一覧表示して。」 → `ios_sim_devices`。 2. **起動**——「iPhone 17 Pro を起動して。」 → `ios_sim_boot`。ストリームが始まり、**「iOS 模拟器」パネル**が開きます。デバイスがサイドバーにライブ表示されます。（任意のシミュレータカードの行、または入力欄の上のステータスピルをクリックすると再び開きます。） 3. **動画の上でタップ**——パネル上で直接タップまたはドラッグします。エージェントに UI を操作させることもできます。「設定を開いて、General をタップして。」 → `ios_sim_interact`（識別子ベースのタップは `ios_sim_ui_tree` + `ios_sim_tap_element`、テキストベースのタップは `ios_sim_find_text` + `ios_sim_tap_text`、リスト/フィード系アプリは `ios_sim_ui_rows` + `ios_sim_tap_row`）。 4. **アプリをビルド＆実行**——「/path/to/MyApp.xcodeproj をビルドして実行して。」 → `ios_sim_build_run`。フルビルドには数分かかります。完了するとアプリがシミュレータで起動し、パネルでライブに確認できます。 5. **プレビューのホットリロード**——「/path/to/MyPackage の SwiftUI プレビューを表示して。」 → `ios_sim_preview start`。ソースファイルを編集すると、実行中のシミュレータに約 2–5 秒でホットスワップされます——再起動は不要です。 6. **実機 iPhone を操作する**——USB（データケーブル）で電話機を接続してロック解除し、「電話機で WebDriverAgent を起動して。」 → `ios_real_start_wda`。パネルは電話機のライブストリームに切り替わり、すべてのツールがその `realDevices` の udid を受け付けます。呼び出しが失敗したら、パネルのステータスからコード化された理由を読んでください（`device-locked`、`cert-untrusted`、`profile-expired`、`tunnel-failed`、`device-unplugged`）。 ## トラブルシューティング - **バックトレースが lldb ではなく `sample` を使う、または leaks が制限付き検査を警告する**——macOS の開発者モードがオフです。`sudo DevToolsSecurity -enable` を一度実行して再試行してください。それまではツールはきれいに縮退動作します。`ios_sim_backtrace` は Xcode の `sample`（シンボル化済み、サスペンドしない）にフォールバックし、`ios_sim_leaks` は有効化のヒントを報告します。 - **`ios_sim_ui_tree` / `ios_sim_tap_element` には AXe が必要**——`brew install cameroncooke/axe/axe` でインストールするか、初回使用時にプラグインに固定リリースをダウンロードさせます（github.com へのネットワークが必要）。エラーメッセージには常に完全なインストールのヒントが含まれます。`DSH_IOS_AXE_BIN=/path/to/axe` で解決結果を上書きできます。行ツール（`ios_sim_ui_rows` / `ios_sim_tap_row`）もシミュレータ上では AXe が必要です。 - **`ios_sim_find_text` / `ios_sim_tap_text` が OCR ヘルパー欠落を報告する**——初回使用時に `swiftc`（Xcode が必要）が同梱の `assets/ocr.swift` を `~/Library/Caches/dsh-ios/bin/ocr` にコンパイルします。エラーには正確なパスとヒントが含まれます。 - **`ios_sim_ui_rows` が行を見つけない**——結果が理由を示します。深さが足りない（`max_depth` を上げてください。実機では深いスナップショットごとに約 15–25 秒かかります）、リスト画面ではない、または深く読んでも本当にアクセシビリティ情報がない。浅い読み取りが「アクセシビリティ欠落」と誤報告されることはありません。 - **iOS 26.2 シミュレータでの `ios_sim_leaks`**——iOS 26.2 ランタイムでは、開発者モードが有効でも Xcode の `leaks` がシミュレータプロセスを検査できず、`Failed to get DYLD info` や minimal-corpse のような致命的な診断を出すことがあります。ツールはきれいに縮退します。生の診断が返り、対象プロセスは必ず再開が検証され、ハングしません。プラグイン側での修正方法はありません——発生したら `mode: "memgraph"` または別のランタイムを試してください。 - **実機の呼び出しがコード化されたステータスで失敗する**——パネルのステータスは推測ではなく原因を示します。`device-locked`（電話機のロックを解除。。 - **ストリームが勝手に止まる**——それはクラッシュではなくアイドルポリシーです。コンシューマがゼロ（パネルが閉じている、カードがマウントされていない、アクティブなルートがない）になると、ストリームは 5 分後に停止し、次のツール呼び出しやパネルを開く操作で再開します。クラッシュしたストリームは約 5 秒以内にバックグラウンドで再起動します。 ## 開発 ```sh pnpm install pnpm run build # ホスト tsc + クライアントバンドル → lib/ pnpm run typecheck ``` `scripts/` のスモークテストはビルド済みの `lib/` を検証します（シミュレータを起動したり USB 接続の電話機と通信したりする部分は macOS のみ。`DSH_IOS_SMOKE_SKIP_SIM=1` を設定するとそれらの部分をスキップします）: | スクリプト | カバー内容 | | --- | --- | | `node scripts/dev-smoke.mjs` | Sim ホスト: バイナリ解決、ストリーム起動、制御、キープアライブ、破棄。 | | `node scripts/dev-tools-smoke.mjs [--full-build]` | 実シミュレータに対するコアツール（`--full-build` 付きなら実ビルドも実行）。 | | `node scripts/dev-routes-smoke.mjs` | 署名付き Web ルート: grant、ストリームプロキシ、スクリーンショット、ws リレー、ガード、失効。 | | `node scripts/dev-card-smoke.mjs` | クライアントカード: 静的 SSR（`` なしの検証）、status/capture 契約、ほぼライブのネットワーク部分。 | | `node scripts/dev-panel-smoke.mjs` | パネルコンポーネント、サイズモード、フレームスタイル、ドック/トリガー/カプセルのロジック（静的のみ）。 | | `node scripts/dev-logs-smoke.mjs` | `ios_sim_logs` の snapshot/follow、フィルタ、上限、プロセス回収。 | | `node scripts/dev-uitree-smoke.mjs` | UI ツリーツール: AXe の解決/ダウンロードパイプライン、セレクタ、実シミュレータでのツリーとタップ。 | | `node scripts/dev-debug-smoke.mjs` | デバッグツール: プロセス、バックトレース（lldb + sample）、リーク、アプリ情報。 | | `node scripts/dev-preview-smoke.mjs` | プレビューのホットリロード: 開始、編集 → 再起動なしのホットスワップ、エラー回復、停止。 | | `node scripts/dev-orphan-smoke.mjs` | ホストが異常終了した後の孤児 serve-sim の引き取り/回収。 | | `node scripts/dev-ocr-smoke.mjs` | Vision-OCR ツール: ヘルパー解決、swiftc コンパイルキャッシュ、認識パイプライン、tap-text ルーティング。 | | `node scripts/dev-wda-smoke.mjs` | WebDriverAgent ホスト: `ServerURLHere` パース、失敗分類、トンネル、キープアライブ（モック。任意のライブ実行）。 | | `node scripts/dev-realdevice-smoke.mjs` | USB 接続の iPhone に対する `xcrun devicectl`——ツールが使うそのままのコードパス。 | | `node scripts/dev-realstart-smoke.mjs` | `/real-start` ルート: ガード、コード化された拒否、ビルド/起動ゲーティング（静的）。 | | `node scripts/dev-realtools-smoke.mjs` | `ios_sim_screenshot` / `ios_sim_interact` / `ios_sim_ui_tree` / `ios_sim_tap_element` の実機バックエンド、および `ios_real_start_wda`。 | ## エコシステム - [DSH Android](https://github.com/ZSeven-W/dsh-android) — 会話の中で動く Android エミュレータや USB 接続の実機を、すべて adb 経由で操作 - [DSH Crew](https://github.com/ZSeven-W/dsh-crew) — Claude Code / Codex から DSH エージェントに作業を委譲 - [DSH Noema](https://github.com/ZSeven-W/dsh-noema) — DSH の長期記憶 - [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — 会話の中で `.op` デザイン文書を閲覧・編集 ## クレジットとライセンス - [serve-sim](https://github.com/EvanBacon/serve-sim) —— Evan Bacon —— シミュレータストリーミングエンジン（Apache-2.0。同梱のランタイム依存関係）。 - [AXe](https://github.com/cameroncooke/AXe) —— Cameron Cooke —— UI ツリーツールを支えるアクセシビリティ CLI（MIT）。 - [WebDriverAgent](https://github.com/appium/WebDriverAgent) —— プラグインが実機上でビルド・起動する WebDriver サーバー（BSD ライセンス）。 - アーキテクチャは Codex の「Build iOS Apps」プラグインに触発されたものです。SwiftUI プレビューエンジンは、公開文書化されたアプローチのクリーンルーム再実装であり、Codex のコードは一切コピーされていません。 - 完全な通知は [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) を参照してください。 **ライセンス**: MIT