ZSeven-W/dsh-ios

DSH iOS シミュレータ – AIエージェント駆動の iOS デバイスビュー

何であるか – DeepSeek Harness (DSH) コンバージェンスプラットフォーム用のプラグイン（@zseven-w/dsh-ios）で、LLM駆動エージェント（またはユーザー）がチャットウィンドウ内から iOS シミュレータ または実機の iPhone を制御できるようにします。デバイスの画面は MJPEG ビデオとして永続的な右側パネルにストリーミングされ、22 の JSON ベースの エージェントツール（起動、ビルド、UIツリー、OCR、タップ、ログ、SwiftUI ホットリロードなど）により、モデルがデバイスを安全かつインタラクティブに視認・制御できます。

---

コアアイデア

アイデア	動作方法
リアルタイムの視覚フィードバック	シミュレータ（またはUSB接続されたiPhone）は、署名済みのループバック専用URL（/_dsh/dsh-ios/*）を通じてビデオをストリーミングします。ブラウザはシミュレータのポートに直接接続せず、すべてのバイトはDSHウェブサーバーによってプロキシされます。
エージェントフレンドリーなツール	各機能はシンプルなJSONツール（例：ios_sim_boot、ios_sim_interact、ios_sim_ui_tree）として公開されます。LLMはツールを呼び出し、構造化された出力を得て、次のステップを決定できるため、完全に自律的なUI自動化が可能になります。
実機サポート	物理的なiPhoneがUSBで接続された場合、プラグインは電話機上で WebDriverAgent をビルドして起動し、USB-muxループバック経由で制御およびMJPEGポートをトンネル化し、同じUIパネルとツールセットを再利用します。
セキュリティゲート	すべてのタップはアクセシビリティカウンター、OCRテキスト、または明示的な expect_* パラメータによって検証されます。ターゲットが一意に識別されない限り、実機のタップはブロックされます。
SwiftUI ホットリロード	ios_sim_preview は一時的なホストアプリを作成し、SwiftUIプレビューをdylibとしてビルドし、実行中のシミュレータに約2〜5秒でホットスワップします。これにより、エージェントはUIの変更を即座に確認できます。

---

主な機能グループ

グループ	代表的なツール	実行可能な操作
デバイスライフサイクル	ios_sim_devices、ios_sim_boot、ios_sim_shutdown	シミュレータの一覧表示、起動/停止、画面のストリーミング
アプリ管理	ios_sim_list_apps、ios_sim_launch_app、ios_sim_build_run	インストール済みアプリの検出、起動、またはXcodeプロジェクトをソースからビルドしてシミュレータまたは実機で実行
インタラクション	ios_sim_interact、ios_sim_tap_element、ios_sim_tap_text、ios_sim_find_text、ios_sim_tap_row	アクセシビリティ識別子、OCR検出テキスト、またはリスト行座標を使用してタップ、入力、ハードウェアボタンの押下、スクロール、ジェスチャー
UIインスペクション	ios_sim_ui_tree、ios_sim_ui_rows	アクセシビリティ階層のダンプ、または高レベルのリストビュー（リストスタイルアプリ用の解析済みカウンター付き）
診断	ios_sim_logs、ios_sim_processes、ios_sim_backtrace、ios_sim_leaks、ios_sim_app_info	統合ログの取得、プロセスの列挙、バックトレースのキャプチャ、Xcodeのリーク検出器の実行、アプリバンドル情報の照会
プレビュー	ios_sim_preview	アプリの再起動なしでSwiftUIプレビューをホットリロード
実機ブリッジ	ios_real_start_wda	接続されたiPhone上でWebDriverAgentをビルド・起動し、シミュレータと同じ制御およびビデオストリームを公開

---

使い始め方

1. npmパッケージのインストール

   npm i -g @zseven-w/dsh-ios   # またはプロジェクトの依存関係に追加
   

2. DSHセッションの実行 – DeepSeek Harness（会話UIを実行するホスト）を起動します。DSHバージョンが 0.1.5-rc.1 以上であれば、プラグインは自動的に検出されます。
3. シミュレータの起動（例：JSONツール呼び出し）

   { "tool": "ios_sim_boot", "args": { "udid": "iPhone-14-Simulator" } }
   

   右側パネルに起動したデバイスのライブMJPEGビューが表示されます。
4. インタラクション – ios_sim_interact を使ってタップ、入力、ホームボタンを押す、または ios_sim_ui_tree を呼び出してアクセシビリティマップを取得し、ios_sim_tap_element でラベルでボタンを押す。
5. 独自コードの実行 – ios_sim_build_run でXcodeプロジェクトまたはSwiftパッケージを指定、または ios_sim_preview でSwiftUIプレビューを開始。
6. 実機iPhone – デバイスを接続し、UDIDを指定して ios_real_start_wda を実行すると、同じインタラクションツールが物理デバイスで動作します。

---

制限事項と注意点

• macOS専用のシミュレータ制御 – simctl/serve-sim と通信するツールはMacが必要です。他のOSではツールは登録されますが、説明付きエラーを返します。
• USBデバイスにはロック解除されたiPhoneが必要 かつユーザーが「タップ前に識別」の許可を付与する必要があります。実機のすべてのタップは、誤操作を防ぐために検証されます。
• ループバック専用トランスポート – すべての通信は 127.0.0.1 上に留まります。追加のトンネリングなしではネットワーク越しに使用できません。
• パフォーマンス – 実機での深層アクセシビリティスナップショットは数秒（未制限のツリーで最大約30秒）かかります。リスト行抽出（ios_sim_ui_rows）も同様に重いです。軽量なツール（ios_sim_find_text、ios_sim_ui_tree で浅い深さ）を最初に使用してください。
• ホットリロードプレビュー – SwiftUIプレビュー専用。一時的なホストアプリを ~/Library/Caches/dsh-ios にビルドし、ソースファイルを監視します。同時に1つのプレビューセッションのみ可能。
• セキュリティ – 署名付きURLは10分後に有効期限切れになります。DSHサーバーはすべてのリクエストで Host、Fetch-Metadata、HMACを検証します。

---

こんな人に向いています

• iOS UIのテスト、自動UI回帰チェック、チャット内でのアプリ動作のデモが必要な LLM駆動AIエージェント。
• SwiftUIコードを会話インターフェースで反復する際、開発者が迅速な視覚フィードバック（シミュレータまたは実機）を得たい場合。
• XCUITestスクリプトを書かずに、プログラム可能なJSONベースの方法でiOS UIを操作したい QAエンジニア。

---

クイックリファレンス表（選択ツール）

ツール	主な目的	キー引数
ios_sim_devices	利用可能なシミュレータと接続されたiPhoneの一覧表示	–
ios_sim_boot	シミュレータを起動してストリーミングを開始	udid（またはデバイス名）
ios_sim_interact	一般的なタップ/ジェスチャー/キーボード操作	action、x、y、text、…
ios_sim_ui_tree	アクセシビリティ階層のダンプ	udid、max_depth、filter
ios_sim_tap_element	ラベル/識別子で要素をタップ	identifier / label、オプションの検証フラグ
ios_sim_find_text	現在の画面をOCRで検出	query、min_confidence
ios_sim_tap_row	カウンター検証付きでリスト/フィード行内をタップ	index、x、y、expect_count
ios_sim_preview	SwiftUIホットリロードプレビュー	packagePath、action（start/status/stop）
ios_real_start_wda	USB接続iPhone上でWebDriverAgentを起動	udid

---

まとめ

DSH iOS シミュレータ は、iOS シミュレータまたは実機iPhoneを、AIエージェントがシンプルなJSON呼び出しで視認・制御できるライブで画像フリーの視覚エンドポイントに変換します。すべてのメディアを署名済みループバックURLの背後に保ち、安全検証付きのインタラクションツールを提供することで、会話型AIワークフロー内で自律的なiOS UI自動化を現実のものにしています。