Ponko2 - AI Overlay App

※ 現在開発中です。座標認識の精度向上に取り組んでいます。

🚀 Gemini AI搭載インタラクティブチュートリアル表示アプリ

Ponko2は、Google Vertex AI (Gemini 3)を活用してスクリーンショットを分析し、UI要素の位置を特定してチュートリアル表示するmacOSアプリケーションです。

アプリ上にオーバーレイを作成することでアプリを操作しながらAIにUIを教えてもらうことが可能です。

✨ 主要機能

🤖 AI駆動スクリーンショット分析

• Vertex AI (Gemini 3) 統合: Google最新のマルチモーダルAIによる画面解析
• UI要素自動検出: ボタン、アイコン、メニューなどの自動識別
• インテリジェント座標計算: 物理ピクセルから論理座標への精密変換

🎯 インタラクティブオーバーレイ

• アプリ内ウィンドウ方式: 安定したオーバーレイ表示
• リアルタイム赤枠表示: 対象UI要素のハイライト表示
• チュートリアルガイド: ステップバイステップの操作説明
• クリック透過: オーバーレイ下のアプリ操作が可能

🛡️ 安全性とパフォーマンス

• gcloud認証: セキュアなGoogle Cloud認証
• 自動圧縮: 4MB以内の画像最適化
• 権限管理: 画面収録権限の適切な処理

🏗️ アーキテクチャ

Ponko2/
├── Sources/
│   ├── main.swift                      # メインアプリケーション
│   ├── OverlayServiceProtocol.swift    # XPCプロトコル定義
│   └── XPCConnectionManager.swift      # XPC接続管理
├── OverlayHelper.swift                 # 外部プロセスオーバーレイ（予備）
├── Package.swift                       # Swift Package Manager
├── .env                                # 環境設定（要作成）
└── .env.example                        # 環境設定テンプレート

🔧 技術スタック

• フロントエンド: SwiftUI + AppKit
• AI分析: Vertex AI (Gemini 3 Flash)
• 認証: gcloud CLI (Application Default Credentials)
• 画像処理: Core Graphics
• オーバーレイ: NSWindow + Core Graphics描画

🚀 セットアップ

前提条件

• macOS 14.0+
• Xcode 15.0+
• Swift 5.9+
• Google Cloud SDK (gcloud CLI)
• Google Cloud プロジェクト（Vertex AI API有効化済み）

インストール

1. リポジトリのクローン

git clone https://github.com/Tonoyama/ponko2.git
cd ponko2

2. Google Cloud認証の設定

# gcloud CLIのインストール（まだの場合）
# https://cloud.google.com/sdk/docs/install からダウンロード

# ログイン認証
gcloud auth application-default login

# プロジェクトの設定
gcloud config set project YOUR_PROJECT_ID

3. 環境設定ファイルの作成

# .env.exampleから.envファイルを作成
cp .env.example .env

# .envファイルを編集
nano .env

.envファイル内で以下を設定：

# Google Cloud Project ID (必須)
GOOGLE_CLOUD_PROJECT=your-project-id-here

# Development settings
NODE_ENV=development

4. ビルドと実行

swift build
swift run MyOverlayApp

📱 初回セットアップ

1. 画面収録権限: システム設定 > プライバシーとセキュリティ > 画面収録で.build/debug/MyOverlayAppを許可
2. gcloud認証: gcloud auth application-default loginでログイン
3. プロジェクトID設定: .envファイルにGOOGLE_CLOUD_PROJECTを設定
4. 接続テスト: アプリ内の⚙️ボタンから「Vertex AI接続テスト」を実行

🔐 Google Cloud の設定

1. Google Cloud Console にアクセス
2. プロジェクトを作成または選択
3. Vertex AI API を有効化
4. gcloud CLIで認証: gcloud auth application-default login

⚙️ 設定方法

アプリ内設定

1. アプリを起動: swift run MyOverlayApp
2. 設定画面を開く: フローティングパネル右上の☁️（クラウド）ボタンをクリック
3. 接続テスト: 「Vertex AI接続テスト」ボタンで設定を確認

.envファイル設定

# Google Cloud Project ID (必須)
GOOGLE_CLOUD_PROJECT=your-project-id

# オプション設定
NODE_ENV=development

💡 使用方法

基本操作

1. アプリ起動: swift run MyOverlayApp でアプリを開始
2. チャットを開く: 💬ボタンでチャットパネルを表示
3. 質問入力: 「.envファイルを閉じるボタンはどこ？」のように質問
4. AI分析: 自動でスクリーンショット撮影・AI分析実行
5. 結果表示: 赤枠で対象UI要素をハイライト表示（10秒間）

クイックテスト

• ▶️ボタン（オレンジ）をクリックすると、テスト質問を自動送信

質問例

• 「ファイルメニューはどこをクリックすればいい？」
• 「保存ボタンの場所を教えて」
• 「設定画面はどこから開く？」
• 「.envファイルを閉じるボタンはどこ？」

UIボタン説明

ボタン	説明
▶️	テスト実行（クイックテスト）
☁️	Vertex AI設定
👁️‍🗨️	オーバーレイ非表示
💬	チャット表示切り替え
⬇️	パネル最小化

🔧 カスタマイズ

オーバーレイ設定

// Sources/main.swift内 - createSafeOverlay関数
// 自動非表示時間を変更
DispatchQueue.main.asyncAfter(deadline: .now() + 10.0) // 10秒 → 任意の秒数

APIモデル変更

// Sources/main.swift内
// gemini-3-flash-preview → gemini-3-pro-preview など
let urlString = "https://aiplatform.googleapis.com/.../gemini-3-flash-preview:generateContent"

🐛 トラブルシューティング

よくある問題

「プロジェクトIDが設定されていません」

• .envファイルにGOOGLE_CLOUD_PROJECT=your-project-idを設定してください

「gcloud認証に失敗しました」

gcloud auth application-default login

「画面収録権限エラー」

• システム設定 > プライバシーとセキュリティ > 画面収録でアプリを許可

オーバーレイが表示されない

• コンソールログで「🎨 MultiStepOverlayView描画」を確認
• 2秒の遅延後に表示されます

🤝 開発に参加

課題報告

バグ報告や機能要望はIssuesでお気軽にどうぞ。

プルリクエスト

1. フォークしてフィーチャーブランチを作成
2. 変更をコミット (git commit -am 'Add feature')
3. ブランチをプッシュ (git push origin feature)
4. プルリクエストを開く

開発ガイドライン

• Swift 5.9+ の最新機能を活用
• コードコメントは日本語OK
• セキュリティを最優先に考慮
• パフォーマンス影響を最小限に

📄 ライセンス

MIT License - 詳細はLICENSEファイルを参照してください。

👨‍💻 作者

Tonoyama - GitHub

---

"AI時代のインタラクティブなUI案内体験を" 🚀